Arbitrarily Shaped ROI (ERegion)
See also: example: Inspecting Pads Using Regions / code snippets: ERegion
Regions or arbitrarily shaped ROI
You define and use regions of interest (ROI) to restrict the area processed with your vision tool and to reduce and optimize the processing time.
In Open eVision:
| □ | An ROI (EROIxxx class) designates a rectangular region of interest. |
| □ | A region (ERegion 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. |
Currently, only the following Open eVision methods support ERegions:
|
Library |
Method |
|---|---|
|
EasyImage |
|
|
Easy3D |
|
|
EasyObject |
|
|
EasyFind |
In the future Open eVision releases, the support of ERegions will be gradually extended to all operators.
Creating regions
Open eVision offers multiple ways to create regions, depending on the shape you need:
The ERegion 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. |
Run-Length Encoding of a circle-shaped region
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. Open 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 |
| □ | The contour of an ERectangleRegion class is a rectangle. |
| □ | Define it using its center, width, height and angle. |
| □ | Alternatively, use an ERectangle instance, such as one returned by an ERectangleGauge instance. |
Rectangle region separating a bar code from the background
| ● | ECircleRegion |
| □ | The contour of an ECircleRegion class is a circle. |
| □ | Define it using its center and radius or 3 non-aligned points. |
| □ | Alternatively, use an ECircle instance, such as one returned by an ECircleGauge instance. |
Circle region encompassing the useful part of an X-Ray image
| ● | EEllipseRegion |
| □ | The contour of an EEllipseRegion class is an ellipse. |
| □ | Define it using its center, long and short radius and angle. |
Ellipse region encompassing a waffle
| ● | EPolygonRegion |
| □ | The contour of an EPolygonRegion class is a polygon. |
| □ | It is constructed using the list of its vertices. |
Polygon region encompassing a key
Using the result of other tools
The ERegion 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.
Open eVision provides constructors for the following tools:
| □ | EasyFind: EFoundPattern |
| □ | EasyMatch: EMatchPosition |
| □ | EasyGauge: ECircle and ERectangle |
| □ | EasyObject: ECodedElement |
When compatible, Open eVision also provides specialized constructors for the geometry-based regions. For instance, ECircleRegion provides a constructor using an ECircle.
Combining regions
Use the following operations to create a new region by combining existing regions:
| ● | Union |
| □ | The ERegion::Union(const ERegion&, const ERegion&) method returns the region that is the addition of the two regions passed as arguments. |
Union of 2 circles
| ● | Intersection |
| □ | The ERegion::Intersection(const ERegion&, const ERegion&) method returns the region that is the intersection of the two regions passed as argument. |
Intersection of 2 circles
| ● | Subtraction |
| □ | The ERegion::Substraction(const ERegion&, const ERegion&) method returns the first region passed as argument after removing the second one. |
Subtraction of 2 circles
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) |
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.
Preparing the region
| ● | Open eVision automatically prepares the regions when it applies them to an image, but this preparation can take some time. |
| ● | If you do not want that your first call to a method takes longer than the next ones, you can prepare the region in advance by using the appropriate Prepare() method. |
| ● | To manually prepare the regions, adapt the internal RLE description to your images. |
Drawing regions
The ERegion classes provide several ways to display the regions:
| ● | ERegion::Draw() draws the region area, in a semi-transparent way, in the provided device context. |
| ● | ERegion::DrawContour() draws the region contour in the provided device context. |
| ● | ERegion::ToImage() 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, Open eVision renders the region inside those bounds. |
| □ | If not, Open eVision resizes the image to contain the whole region. |
| □ | Use ToImage() to create masks for the Open eVision functions that support them. |
ERegions and EROIs
| ● | The older EROI classes of Open 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) |
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