# Regions Of Interest (ROI)

ROIs are defined by a **width** ([`EBaseROI::GetWidth`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a59510c9bd296116be24733a7ac9442fc) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a7dc7043bd5a463d7176c40ca2dea1953) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a0ea6d101c697843cf6d50226b330aa08)), a **height** ([`EBaseROI::GetHeight`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a9780cb061a87ca0c001c936589047d34) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a0bfcc0aede828f3bf65c4135fce44d20) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a9e5ded3cddea01887fe6323532183133)), and **origin coordinates** ([`EBaseROI::GetOrgX`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a90079b3e2bcd8b07dc1ab6f52d21a64f) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a8c7853ee2c4863a0e311113108e379a2) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a996806ce482a103aa1e2d956954fd477) and [`EBaseROI::GetOrgY`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a95159058329bb78432fc54f5c6128a7d) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a454a5ad561e9ca9ff5818888468f0ad1) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a6ea24bd7b4de63bfcd57c2a1d189335e)).

* The origins are specified with respect to the top left corner in the parent image or ROI.
* The ROI must be wholly contained in its parent image.
* The processing / analysis time of a BW1 ROI is faster if `OrgX` ([`EBaseROI::GetOrgX`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a90079b3e2bcd8b07dc1ab6f52d21a64f) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a8c7853ee2c4863a0e311113108e379a2) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a996806ce482a103aa1e2d956954fd477)) and `Width` ([`EBaseROI::GetWidth`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a59510c9bd296116be24733a7ac9442fc) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a7dc7043bd5a463d7176c40ca2dea1953) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a0ea6d101c697843cf6d50226b330aa08)) are multiples of 8.

## Save and load

You can [`EBaseROI::Save`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#afda2dc66ee1dd71c3d164b4986003cb5) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a3d3a7b24cb090eebc6e662551b23a069) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a78024e4eac82a8bc01631be654073b25) or [`EBaseROI::Load`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a993f2416a63b523d6b1a89b1b4f9310d) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#ab468012a82769c1902eaefde4a1a74b1) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a6203404de61357bdbae378e32144fe91) an ROI as a separate image, to be used as if it was a full image. The ROIs perform **no memory allocation** at all and never duplicate parts of their parent image, the parent image provides them with access to its image data.

The image size of the new file must match the size of the ROI being loaded into it. The image around the ROI remains unchanged.

## ROI Classes

An **eVision** ROI inherits parameters from the abstract class [`EBaseROI`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html).

There are several ROI types, according to their pixel type. They have the same characteristics as the corresponding [image types](../images/pixel_containers_and_files.html.md).

* [`EROIBW8`](../../../doxygen_cpp/classeVision_1_1EROIBW8.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EROIBW8.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EROIBW8.html)
* [`EROIBW16`](../../../doxygen_cpp/classeVision_1_1EROIBW16.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EROIBW16.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EROIBW16.html)
* [`EROIBW32`](../../../doxygen_cpp/classeVision_1_1EROIBW32.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EROIBW32.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EROIBW32.html)
* [`EROIC24`](../../../doxygen_cpp/classeVision_1_1EROIC24.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EROIC24.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EROIC24.html)
* [`EROIC24A`](../../../doxygen_cpp/classeVision_1_1EROIC24A.html) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EROIC24A.html) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EROIC24A.html)

## Attachment

An ROI must be `attached` ([`EBaseROI::Attach`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#aded76b91243459a106cc9c7d5ce0649c) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#abd1f985ac7e4a49d9048dc54bfbe279c) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a667f3738c92f093b7c4378ddf6901f50)) to a parent (image / ROI) with parameters that set the parent, position and size, and these links are updated transparently, avoiding dangling pointers.

A normal image cannot be attached to another image or ROI.

## Nesting

Set and Get functions change or query the width, height and position of the origin of an ROI, with respect to its immediate or topmost parent image.

An image may accommodate an arbitrary number of ROIs, which can be nested in a hierarchical way. Moving the ROI also moves the embedded ROIs accordingly. The image / ROI classes provide several methods to traverse the hierarchy of ROIs associated with an image.

![image](assets/images/regions_frames/nestedrois.webp)

## Cropping

[`EBaseROI::CropToImage`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#ad62a199eb62bec69e8c7deb9e73cb3fc) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a688bcf150743fd0ed812d711401c55fe) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a0d53c27f72c5c32781334c5ff9b8e6e9) crops an ROI which is partially out of its image. The resized ROI never grows.

An exception is thrown if a function attempts to use an ROI that has limits that extend outside of the parents.

#### NOTE
In **Open eVision** 1.0.1 and earlier, an ROI was silently resized or repositioned when placed out of its image and sometimes grew. If ROI limits extended outside parents, they were silently resized to remain within parent limits.

## Resizing and moving

ROIs can easily be resized and positioned by two functions and dragging handles:

* [`EBaseROI::Drag`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#a70314b7dca064befc9cd18fbca7a16fc) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#a96487dd796aa1ee42226d0b3089dea70) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#a5f18a4599a4e410181ae2751cb52bee7) adjusts the ROI coordinates while the cursor moves.
* [`EBaseROI::HitTest`](../../../doxygen_cpp/classeVision_1_1EBaseROI.html#ac0e010f9782e13f0c5528e5c0493bc14) [<sub>.NET</sub>](../../../doxygen_cs/classeVision_1_1EBaseROI.html#ac8bdb624373e7047e1bf7e675830ffad) [<sub>Python</sub>](../../../doxygen_python/classeVision_1_1EBaseROI.html#ad01ab8b17a51ac1d2bde4e76ca25ca5d) informs if the cursor is placed over a dragging handle.
  * Once the handle is known, the cursor shape can be changed by an `OnSetCursor` MFC event handler. HitTest is unpredictable if called while dragging is in progress.
  * `HitTest` can be used in an `OnSetCursor` MFC event handler to change the cursor shape, or before a dragging operation like `OnLButtonDown`.