# Extracting and Using Objects
## Extracting the Objects
Use the [`E3DObjectExtractor::Extract`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a24f28f27d189595d9c072d74bfd91418) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#ace913c64931506a1bc76ca57475bfc9e) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a7948bf8c345e776096d8bc001c8e4478) method to perform the objects extraction.
You can limit the extraction to an [`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) [.NET](../../../doxygen_cs/classeVision_1_1ERegion.html) [Python](../../../doxygen_python/classeVision_1_1ERegion.html), for example to ignore parts of the ZMap that are not interesting and/or to speed up the extraction process.
The processing speed of the extraction depends directly on:
* The number of pixels in the ZMap or in the ERegion.
* The number of segmented objects.
* The computer features for each segmented object.
#### HINT
To speed up the extraction process:
- Adjust the extraction ranges to reduce the number of objects.
- Disable the features you do not need.
## Overlapped Objects
By default, the extraction does not produce objects that overlap on the ZMap. You must enable the [`E3DObjectExtractor::SetOverlappedObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a439bac2c07057c603366c30c7e27c973) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#ad3ef34960be5c007ec2c74fbd7d0881d) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#aa0fd4356f67defe20c27f61ab725d395) option to extract “stacked” objects.
The *area ratio* and the *height difference* parameters control how overlapped objects are extracted:
* The *area ratio* is configured by [`E3DObjectExtractor::SetOverlappedAreaRatio`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a1dc790707692fd272e6027e8704f2dbc) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a3643601271051878f205775bb02bf1c6) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a8eb585992710922107c6db851ae62147). The area of the bottom object divided by the area of the top object must be larger or equal than that ratio.
* The *height difference* is configured by [`E3DObjectExtractor::SetOverlappedHeightDifference`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#ab24767bc72e4e292a858c7283a236e0d) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a7428c74ce4e1c9eb51e4292b355ee1b8) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a8828ac95725473e8416861bbe48b66da). This represent the minimum height difference between the top and the bottom object
## Controlling the Object Detection
Two optional parameters affect the detection of the object:
* [`E3DObjectExtractor::SetExtractionSensitivity`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#ad3ecf564aedfcbdf7533e9d9ca67994b) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a9c4f1fbf6389bc9ef71761b1c7d574d8) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a9f7c0301d861bd0a9e2b61a357a8d3f5) controls the sensitivity of the extraction.
* A higher value increases the ability to detect objects that are mixed with their surrounding, because their grey values are close to the background or because the transition (the gradient) between the object and the background is smooth.
* This parameter value ranges from 0 to 1 (the default value is 0.6).
* [`E3DObjectExtractor::SetContourReinforce`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#aea7e6f03df1db363a4995b1775edc81b) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#aeef1af7ea50b68a9d91e276eac3b5229) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#abdfb0638c5a4631b564c259e8892578c) affects the extraction of the objects.
* As the extraction can fail when objects are close or touch each other, this parameter enables a filter to enhance the frontiers between objects and enable the extraction of such objects.
* The filter can affect the measurements.
## Using the Objects
The [`E3DObjectExtractor::Extract`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a24f28f27d189595d9c072d74bfd91418) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#ace913c64931506a1bc76ca57475bfc9e) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a7948bf8c345e776096d8bc001c8e4478) method populates a list of [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html) fulfilling your set criteria.
* Each [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html) is a collection of descriptive features of the associated 3D points in the [`EZMap`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EZMap.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EZMap.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EZMap.html), such as its oriented bounding box, its local height and its volume.
* Call the associated [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html) method to access a feature.
* The [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html) list is sorted from the smallest area to the largest area.
* Use [`E3DObjectExtractor::GetObjectsMask`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a30b1d4c7d0fcffa2f0b5495bd3683e09) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#a05377511423c94a9892b6bdcecc3ac8b) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObjectExtractor.html#af1fe7529f455aee76813de91272c4137) to get the mask of all the extracted [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html).
## Visualizing the Objects
To visualize some of these features in 2D or 3D:
* Use the [`E3DObject::Draw`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html#aef4c54a3837f1478c672e1585ddd24cc) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html#a11f1a1fc4dae0cfab23354f376404c7b) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html#a338a94b2303171911b02a8a512faa957) method.
* Or submit a list of [`E3DObject`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DObject.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DObject.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DObject.html) to an [`E3DViewer`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DViewer.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DViewer.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DViewer.html).
#### HINT
In an [`E3DViewer`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DViewer.html) [.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DViewer.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DViewer.html), use the [`ERenderStyle`](../../../doxygen_cpp/structeVision_1_1Easy3D_1_1ERenderStyle.html) [.NET](../../../doxygen_cs/structeVision_1_1Easy3D_1_1ERenderStyle.html) [Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1ERenderStyle.html) structure to choose your rendering style.
See below some examples to draw features from a list of `E3DObjects`:
* Drawing 2D features:
### C++
```cpp
#include
#include
```
```cpp
using namespace eVision;
using namespace eVision::Easy3D;
E3DObjectExtractor extractor;
// Get the list of E3DObjects
std::vector objects = extractor.GetObjects();
// Get the dimensions of the 2D feature
ERegion region = extractor.GetObjectsMask();
// Get an image on which to draw the 3D objects
EImageC24A image(region.GetBoundingBoxWidth(), region.GetBoundingBoxHeight());
EGenericDrawAdapter drawContext(&image);
// Draw the ERegion of each object
int nObjects = (int)objects.size();
for (int i = 0; i < nObjects; i++)
objects[i].Draw(&drawContext, E3DObjectFeature_ERegion, ERGBColor(0, 255, 0));
```
### C#
```cs
using eVision;
using eVision.Easy3D;
```
```cs
E3DObjectExtractor extractor = new E3DObjectExtractor();
// Get the list of E3DObjects
E3DObject[] objects = extractor.Objects;
// Get the dimensions of the 2D feature
ERegion region = extractor.ObjectsMask;
// Get an image on which to draw the 3D objects
EImageC24A image = new EImageC24A(region.BoundingBoxWidth, region.BoundingBoxHeight);
EGenericDrawAdapter drawContext = new EGenericDrawAdapter(image);
// Draw the ERegion of each object
int nObjects = objects.Length;
for (int i = 0; i < nObjects; i++)
objects[i].Draw(drawContext, E3DObjectFeature.ERegion, new ERGBColor(0, 255, 0));
```
### Python
```py
import eVision
from eVision import Easy3D
extractor = Easy3D.E3DObjectExtractor()
# Get the list of E3DObjects
objects = extractor.Objects
# Get the dimensions of the 2D feature
region = extractor.ObjectsMask
# The drawing surface
display_img = eVision.EImageC24A(width=region.BoundingBoxWidth, height=region.BoundingBoxHeight)
draw_adapter = eVision.EGenericDrawAdapter(display_img)
# Draw the ERegion of each object
for object_i in objects:
object_i.Draw(draw_adapter, Easy3D.E3DObjectFeature.ERegion, eVision.ERGBColor(0, 255, 0))
```
* Drawing 3D features:
### C++
```cpp
#include
#include
```
```cpp
using namespace eVision;
using namespace eVision::Easy3D;
E3DObjectExtractor extractor;
// Get the list of E3DObjects
std::vector objects = extractor.GetObjects();
// Register the list of E3DObjects to the 3D viewer
E3DViewer viewer3D(0, 0, 640, 480);
viewer3D.Register3DObjects(objects);
// Define and use a render style for the ReferenceTopPosition feature
ERenderStyle renderStyle;
renderStyle.pointRGB = EC24A(100, 0, 0);
viewer3D.SetFeatureStyleForAll3DObjects(renderStyle, E3DObjectFeature_ReferenceTopPosition);
// Set a different rendering color for the first object
ERenderStyle selectedRenderStyle;
selectedRenderStyle.pointRGB = EC24A(255, 255, 0);
viewer3D.SetFeatureStyleFor3DObject(0, selectedRenderStyle, E3DObjectFeature_ReferenceTopPosition);
// Enable the display of the TopZPosition feature
viewer3D.ShowFeatureForAll3DObjects(E3DObjectFeature_ReferenceTopPosition);
```
### C#
```cs
using eVision;
using eVision.Easy3D;
```
```cs
E3DObjectExtractor extractor = new E3DObjectExtractor();
// Get the list of E3DObjects
E3DObject[] objects = extractor.Objects;
// Register the list of E3DObject to the 3D viewer
E3DViewer viewer3D = new E3DViewer(0, 0, 100, 100);
viewer3D.Register3DObjects(objects);
// Define and use a render style for the ReferenceTopPosition feature
ERenderStyle renderStyle = new ERenderStyle();
renderStyle.pointRGB = new EC24A(100, 0, 0);
viewer3D.SetFeatureStyleForAll3DObjects(renderStyle, E3DObjectFeature.ReferenceTopPosition);
// Set a different rendering color for the first object
ERenderStyle selectedRenderStyle = new ERenderStyle();
selectedRenderStyle.pointRGB = new EC24A(255, 255, 0);
viewer3D.SetFeatureStyleFor3DObject(0, selectedRenderStyle, E3DObjectFeature.ReferenceTopPosition);
// Enable the display of the ReferenceTopPosition feature
viewer3D.ShowFeatureForAll3DObjects(E3DObjectFeature.ReferenceTopPosition);
```
### Python
```py
import eVision
from eVision import Easy3D
extractor = Easy3D.E3DObjectExtractor()
# Get the list of E3DObjects
objects = extractor.Objects
# Register the list of E3DObject to the 3D viewer
viewer3D = Easy3D.E3DViewer(0, 0, 100, 100)
viewer3D.Register3DObjects(objects)
# Define and use a render style for the ReferenceTopPosition feature
render_style = Easy3D.ERenderStyle()
render_style.pointRGB = eVision.EC24A(100, 0, 0)
viewer3D.SetFeatureStyleForAll3DObjects(render_style, Easy3D.E3DObjectFeature.ReferenceTopPosition)
# Set a different rendering color for the first object
selected_render_style = Easy3D.ERenderStyle()
selected_render_style.pointRGB = eVision.EC24A(255, 255, 0)
viewer3D.SetFeatureStyleFor3DObject(0, selected_render_style, Easy3D.E3DObjectFeature.ReferenceTopPosition)
# Enable the display of the ReferenceTopPosition feature
viewer3D.ShowFeatureForAll3DObjects(Easy3D.E3DObjectFeature.ReferenceTopPosition)
```
