# Arbitrarily Shaped ROI (ERegion)

#### SEE ALSO
Example: [Inspecting Pads Using Regions](../../../resources/application_examples/inspecting_pads_using_regions.html.md) / code snippets: [ERegion](../../../resources/code_snippets/basic_operations/eregion/index.html.md)

## Regions or arbitrarily shaped ROI

In some cases, most often to decrease the processing time or to single-out the object you want to analyze, you do not want to process the whole image but only a part of it.

You can define and use regions of interest (ROI) to restrict the area processed with your vision tool.

In **eVision**:

* An **ROI** (EROIxxx class) designates a rectangular region of interest.
* A **region** ([`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html) class) designates an arbitrarily shaped ROI. With regions, you can determine precisely which part of the image, down to a single pixel, is used for your processing.

## Creating regions

**eVision** offers multiple ways to create regions, depending on the shape you need:

The [`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html) is the base class for all regions and the most versatile. It encodes a region using a Run-Length Encoded (RLE) representation.

* The RLE representation of a region is made of runs (horizontal, 1-pixel high slices).
* The runs are stored in the form of their ordinate, starting abscissa and length.
  ![image](assets/images/manipulating/regions_rle.webp)

To create a region, either:

* Use one of the geometry-based region classes.
* Use the result of another tool, such as **EasyFind**, **EasyMatch** or **EasyObject**.
* Combine or modify other regions.
* Use a mask image.
* Directly provide the list of runs.

### Geometry-based regions

Geometry based regions are specialized classes of regions that are encompassed in simple geometries. **eVision** currently provides classes based on a rectangle, a circle, an ellipse or a polygon.

Use these classes to setup geometric regions and modify them with translation, rotation and scaling. The transformation operators return new regions, leaving the source object unchanged.

* [`ERectangleRegion`](../../../doxygen_cpp/classeVision_1_1ERectangleRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERectangleRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERectangleRegion.html)
  * The contour of an [`ERectangleRegion`](../../../doxygen_cpp/classeVision_1_1ERectangleRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERectangleRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERectangleRegion.html) class is a rectangle.
  * Define it using its center, width, height and angle.
  * Alternatively, use an [`ERectangle`](../../../doxygen_cpp/classeVision_1_1ERectangle.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERectangle.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERectangle.html) instance, such as one returned by an [`ERectangleGauge`](../../../doxygen_cpp/classeVision_1_1ERectangleGauge.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERectangleGauge.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERectangleGauge.html) instance.
    ![image](assets/images/manipulating/regions_erectangleregion_example.webp)
* [`ECircleRegion`](../../../doxygen_cpp/classeVision_1_1ECircleRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircleRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircleRegion.html)
  * The contour of an [`ECircleRegion`](../../../doxygen_cpp/classeVision_1_1ECircleRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircleRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircleRegion.html) class is a circle.
  * Define it using its center and radius or 3 non-aligned points.
  * Alternatively, use an [`ECircle`](../../../doxygen_cpp/classeVision_1_1ECircle.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircle.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircle.html) instance, such as one returned by an [`ECircleGauge`](../../../doxygen_cpp/classeVision_1_1ECircleGauge.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircleGauge.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircleGauge.html) instance.
    ![image](assets/images/manipulating/regions_ecircleregion_example.webp)
* [`EEllipseRegion`](../../../doxygen_cpp/classeVision_1_1EEllipseRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EEllipseRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EEllipseRegion.html)
  * The contour of an [`EEllipseRegion`](../../../doxygen_cpp/classeVision_1_1EEllipseRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EEllipseRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EEllipseRegion.html) class is an ellipse.
  * Define it using its center, long and short radius and angle.
    ![image](assets/images/manipulating/regions_eellipseregion_example.webp)
* [`EPolygonRegion`](../../../doxygen_cpp/classeVision_1_1EPolygonRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EPolygonRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EPolygonRegion.html)
  * The contour of an [`EPolygonRegion`](../../../doxygen_cpp/classeVision_1_1EPolygonRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EPolygonRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EPolygonRegion.html) class is a polygon.
  * It is constructed using the list of its vertices.
    ![image](assets/images/manipulating/regions_epolygonregion_example.webp)

### Using the result of other tools

The [`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html) class provides a set of specialized constructors to create regions from the results of another tool.

In a tool chain, these constructors restrict the processing of a tool to the area issued from the previous tool.

![image](assets/images/manipulating/regions_combining_tools.webp)

**eVision** provides constructors for the following tools:

* EasyFind: [`EFoundPattern`](../../../doxygen_cpp/classeVision_1_1EFoundPattern.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EFoundPattern.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EFoundPattern.html)
* EasyMatch: [`EMatchPosition`](../../../doxygen_cpp/structeVision_1_1EMatchPosition.html) [<sub>.NET</sub>](../../../doxygen_cs/structeVision_1_1EMatchPosition.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EMatchPosition.html)
* EasyGauge: [`ECircle`](../../../doxygen_cpp/classeVision_1_1ECircle.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircle.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircle.html) and [`ERectangle`](../../../doxygen_cpp/classeVision_1_1ERectangle.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERectangle.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERectangle.html)
* EasyObject: [`ECodedElement`](../../../doxygen_cpp/classeVision_1_1ECodedElement.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECodedElement.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECodedElement.html)

#### TIP
When compatible, **eVision** also provides specialized constructors for the geometry-based regions. For instance, [`ECircleRegion`](../../../doxygen_cpp/classeVision_1_1ECircleRegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircleRegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircleRegion.html) provides a constructor using an [`ECircle`](../../../doxygen_cpp/classeVision_1_1ECircle.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ECircle.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ECircle.html).

### Combining regions

Use the following operations to create a new region by combining existing regions:

* Union
  * The [`ERegion::Union`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a6c54ff8f521287fdd8fa0f5db4a254b6) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#aca5802ffc895c67fa27aa97ac5e52758) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#abb9f0f944cddb671ae79a082565853c0) method returns the region that is the addition of the two regions passed as arguments.
    ![image](assets/images/manipulating/regions_combining_union.webp)
* Intersection
  * The [`ERegion::Intersection`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a94458fb884f181d61519c494dbd95723) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#ad2b49aa148f4f553cc133acefb2df195) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#a1af0497544913d860c351decab7ed864) method returns the region that is the intersection of the two regions passed as argument.
    ![image](assets/images/manipulating/regions_combining_intersection.webp)
* Subtraction
  * The [`ERegion::Subtraction`](../../../doxygen_cpp/classeVision_1_1ERegion.html#aa2c92686c907c73ab480b3e0e4356839) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a2de753488ecd1495876d703a21ae6872) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#ae1e49e03ba287a566587abb75bb5143b) method returns the first region passed as argument after removing the second one.
    ![image](assets/images/manipulating/regions_combining_subtraction.webp)

### Morphological operations on regions

![image](assets/images/manipulating/regions_morph_arbitrary.webp)
* Grow
  * The [`ERegion::Grow`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a4de82cb1d1a0b3541b58df6a82cfd553) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#acee9a2587f8367b5d5f2548d93a3c19d) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#aed5e840f8a7e43a6ffa81b7dd6f9b409) method returns a region that is the dilation of the region by a disk with a radius equals to the argument.
    ![image](assets/images/manipulating/regions_morph_grow.webp)
* Shrink
  * The [`ERegion::Shrink`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a0aa53f38eda4992e1c7afc6980435f90) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a3769dbbe9ccd54d6647f28d7d8039595) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#a426a604e03f3f5b0b66736a34d67de31) method returns a region that is the erosion of the region by a disk with a radius equals to the argument.
    ![image](assets/images/manipulating/regions_morph_shrink.webp)
* Contour
  * The [`ERegion::Contour`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a37f10beb6bf83e444608f1c49a686847) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a7f02e55a380ca8ad30ca9bf75effd5bb) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#a5de7420d3256c6a2186ce64438078c20) method returns a region that is the contour of the region.
    ![image](assets/images/manipulating/regions_morph_contour.webp)

### Free-hand drawing a region

* The [`ERegionFreeHandPainter`](../../../doxygen_cpp/classeVision_1_1ERegionFreeHandPainter.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegionFreeHandPainter.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegionFreeHandPainter.html) class provides the methods that allow you to create a region by hand, using the mouse or any other user input method.
* The `RegionFreeHand` sample, available both in C++ and C#, shows how to use this class to draw a region on an image.

## Using regions

The tools supporting regions provide methods that follow one of these conventions:

* `Method(const EImage& source, const ERegion& region)`
* `Method(const EImage& source, const ERegion& region, EImage& destination)`

#### NOTE
The source, the region and the destination must be compatible. It means that the region must at least partly fit in the source, and that source and destination must have the same size.

#### NOTE
The process is applied only to the pixels inside the `ERegion`.

### Preparing the region

* **eVision** automatically prepares the regions when it applies them to an image, but this preparation can take some time.
* If you do not want your first call to a method to take longer than the next ones, you can prepare the region in advance by using the appropriate [`ERegion::Prepare`](../../../doxygen_cpp/classeVision_1_1ERegion.html#aab37b646200fd650eb0d6f969b2bc4e5) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a1ea24aad9740c18df88155e5163f3d92) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#a0232d66f12bbebd5d1cfafd854fc98ea) method.
* To manually prepare the regions, adapt the internal RLE description to your images.

## Drawing regions

The [`ERegion`](../../../doxygen_cpp/classeVision_1_1ERegion.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html) classes provide several methods to display the regions:

* [`ERegion::Draw`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a812de0cb1046394a0a56588d508e40db) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a80676f46d284ca0ff863b115a5888247) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#a8bc94d327e80c1cd7deb3bf498e8992d) draws the region area, in a semi-transparent way, in the provided device context.
* [`ERegion::DrawContour`](../../../doxygen_cpp/classeVision_1_1ERegion.html#ae98bceb9f604d53b1f72d4ae4019108b) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a7fed088f10ec68e94e987105a83f9c0d) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#acd66f8dd577f52f8a7258426bad932a8) draws the region contour in the provided device context.
* [`ERegion::ToImage`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a30598f67165f91786c9b97ae959760ef) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a8de73c4b5a99cb02879b773de3c958ba) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#aeb823477222fbf411cff395ff07ed07d) renders the region as a mask into the provided destination image.
  * You can configure the foreground and the background colors.
  * If you initialized your image with a width and a height, **eVision** renders the region inside those bounds.
  * If not, **eVision** resizes the image to contain the whole region.
  * Use [`ERegion::ToImage`](../../../doxygen_cpp/classeVision_1_1ERegion.html#a30598f67165f91786c9b97ae959760ef) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1ERegion.html#a8de73c4b5a99cb02879b773de3c958ba) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1ERegion.html#aeb823477222fbf411cff395ff07ed07d) to create masks for the **eVision** functions that support them.

## ERegions and EROIs

* The older `EROI` classes of **eVision** are compatible with the new regions.
* Some tools allow the usage of regions with source and/or destinations that are `ERoi` instead of `EImage` follow one of these conventions:
  * `Method(const ERoi& source, const ERegion& region)`
  * `Method(const ERoi& source, const ERegion& region, ERoi& destination)`

#### TIP
In that case, the coordinates used for the region are relative to the reduced ROI space instead of the whole image space .

## ERegion and 3D

* The new regions are compatible with the 2.5D representations of Easy3D ([`EDepthMap`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap.html) and [`EZMap`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EZMap.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EZMap.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1Easy3D_1_1EZMap.html)).
* You can also reduce the domain of processing when using these classes.