# Encoding an Image The ***image encoder*** ([`EImageEncoder`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html)) clasifies the pixels of an image into several ***layers*** with a ***segmenter*** and build ***blobs*** for the selected ***layers***. The result is stored in a ***coded image*** ([`ECodedImage2`](../../../doxygen_cpp/classeVision_1_1ECodedImage2.html) [.NET](../../../doxygen_cs/classeVision_1_1ECodedImage2.html) [Python](../../../doxygen_python/classeVision_1_1ECodedImage2.html)) which contains the lists of blobs for each ***layer***, stored as ***coded elements*** ([`ECodedElement`](../../../doxygen_cpp/classeVision_1_1ECodedElement.html) [.NET](../../../doxygen_cs/classeVision_1_1ECodedElement.html) [Python](../../../doxygen_python/classeVision_1_1ECodedElement.html)). The pixels that are part of the ***blobs*** are stored using list of runs. A run is a sequence of adjacent pixels from the same row. To encode an image: 1. Create a new [`EImageEncoder`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html) object. 2. Set the [segmentation method and configure the segmenter](#easyobject-segmenters). 3. Set the [layers to encode](#easyobject-layers-to-encode). 4. Set the [connexity](#easyobject-connexity) of the encoder. 5. Create a new [`ECodedImage2`](../../../doxygen_cpp/classeVision_1_1ECodedImage2.html) [.NET](../../../doxygen_cs/classeVision_1_1ECodedImage2.html) [Python](../../../doxygen_python/classeVision_1_1ECodedImage2.html) object. 6. Call [`Encode(sourceImage, codedImage)`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a0212a8144f93eba43fbed584140a83cd) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a0956dbfef4ebce656f72e3471997e518) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a1292c1003f94e89af9600e99198aed4c). ## Image Segmenters The ***image segmenters*** are responsible for classifying the pixels of the image into several ***layers***. The segmenters are part of the [`image encoder`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html) object: * Use [`SetSegmentationMethod`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#abb35ac59ae3fca68b28595af6e07c988) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a7aa2f5ad29291fd8dea1dce347b2288b) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a606312e026ce9a8dec84407b7eea3d49) to set the segmenter. * Use the appropriate getter to access a segmenter and modify its parameters ### Grayscale Single Threshold (default) The grayscale single threshold segmenter is applicable to [`BW8`](../../../doxygen_cpp/classeVision_1_1EImageBW8.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageBW8.html) [Python](../../../doxygen_python/classeVision_1_1EImageBW8.html) and [`BW16`](../../../doxygen_cpp/classeVision_1_1EImageBW16.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageBW16.html) [Python](../../../doxygen_python/classeVision_1_1EImageBW16.html) grayscale images and produces coded images with two layers: - The **black layer** (usually Layer 0) contains unmasked pixels with a gray value below the Threshold value. - The **white layer** (usually Layer 1) contains the remaining unmasked pixels, i.e. unmasked pixels having a gray value greater or equal to the Threshold value. To use this segmenter: - Set the segmentation method to [`ESegmentationMethod_GrayscaleSingleThreshold`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da524efbd635fd154bc2e203b896c8c55b) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#af9a16abf86f6cee0a9196185d923d768) - Access and modify the parameters of the segmenter with [`GetGrayscaleSingleThresholdSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a8e55a5663c14ff487f5eeb0daf26d3e2) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#acde6796bb21e6ae0e6c1703d20eb0bf5) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a5db32d33674a7a39926fff79d63cc214). **EasyObject** provides 5 [`thresholding methods`](../../../doxygen_cpp/namespaceeVision.html#a71bd8dc388ff3bba317aac30727554e0) [.NET](../../../doxygen_cs/namespaceeVision.html#aab8828d3538e5723c87a93e3cdc7d4d7) [Python](../../../doxygen_python/classeVision_1_1EGrayscaleSingleThreshold.html): - **Absolute** (integer value): represents the first gray value of the white layer. Use the method [`EGrayscaleSingleThresholdSegmenter::SetAbsoluteThreshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a3c7a9d882334cf4c0b9e89139b162f02) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#aa89ef45f24add9821585d34e765a832b) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a1e449d050be65c767ad09197df5bdf7f). - **Relative** (%): represents the fraction of image pixels that belong to the Black layer, it is a user-defined float value in range 0 to 1. Use the method [`EGrayscaleSingleThresholdSegmenter::SetRelativeThreshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a6f228d2a6c5d21abe96e2f36b4fd8e61) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a22525de07826af906e371cb528445cb2) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a5403cc4bbef546275b80eb62841972a2). - **Minimum Residue** (default): The threshold is an automatically computed value such that the quadratic difference between the source and thresholded image is minimized. - **Maximum Entropy**: automatically computed value such that the entropy (i.e. the amount of information) of the resulting thresholded image is maximized. - **IsoData**: automatically computed value that lies halfway between the average dark gray value (gray levels below the threshold) and average light gray values (gray levels above the threshold). Use [`EGrayscaleSingleThresholdSegmenter::SetMode`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a65cc042621a41a112d2d6310cd27726e) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a737b36c58ab2569dda640f72880f05df) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EGrayscaleSingleThresholdSegmenter.html#a1bb14375bd35625f8331fe548c4c8f59) to select the thresholding method. Grayscale Single Threshold with a minimum residue thresholding method is the default. Only objects whose pixels have a value that is above this threshold are encoded. ### Grayscale Double Threshold The grayscale double threshold segmenter is applicable to [`BW8`](../../../doxygen_cpp/classeVision_1_1EImageBW8.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageBW8.html) [Python](../../../doxygen_python/classeVision_1_1EImageBW8.html) and [`BW16`](../../../doxygen_cpp/classeVision_1_1EImageBW16.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageBW16.html) [Python](../../../doxygen_python/classeVision_1_1EImageBW16.html) grayscale images and produces coded images with three layers: - The **black layer** (usually Layer 0) contains unmasked pixels having a gray value below the Low Threshold value. - The **white layer** (usually Layer 2) contains unmasked pixels having a gray value above or equal the High Threshold value. - The **neutral layer** (usually Layer 1) contains the remaining unmasked pixels. To use this segmenter: - Set the segmentation method to [`ESegmentationMethod_GrayscaleDoubleThreshold`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da05c3b7a956f202c5ac97ea4a1ef1d165) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#a1433503d47965408bd3d8729d3d756d8) - Access and modify the parameters of the segmenter with [`GetGrayscaleDoubleThresholdSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#aec503fc0bd6a249bc55bbd86ead7aa9f) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#ac2dcdbf098a715e7e2cb6fa0652b2299) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a64426a1ac516d48be688e215b6576c2a). This segmenter has two user-defined integer parameters: - The [`low threshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#a5f5184f228ca3cde7244913595413940) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#adcbb6b09a5f7d919166611dd20fcab4d) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#af5ca86f1876f3839639109153e35819f) - The [`high threshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#ac5955b364596cd9456c324134616dea3) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#a579b810d6c72d2fbc2f905a931439e1a) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EGrayscaleDoubleThresholdSegmenter.html#adbe8759e2dcc8a4bcde837bcc4f0ba2e) ### Color Single Threshold The color single threshold segmenter is applicable to [`C24`](../../../doxygen_cpp/classeVision_1_1EImageC24.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageC24.html) [Python](../../../doxygen_python/classeVision_1_1EImageC24.html) color images and produces coded images with two layers: * The **white layer** (usually Layer 1) contains unmasked pixels that belong to the cube of the color space defined by the threshold point and the white point (255,255,255). * The **black layer**(usually Layer 0) contains the remaining unmasked pixels. To use this segmenter: * Set the segmentation method to [`ESegmentationMethod_ColorSingleThreshold`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da4653e4739a75c11dadd655ed5c3ef9b1) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#a86363ebedc64edba90b94825fbc50bb9) * Access and modify the parameters of the segmenter with [`GetColorSingleThresholdSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a3664717417bb0a88f25f041360679091) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#aee8fa5362e726e5796ae74bd19f3f115) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a62f370675f3fc4b4d1a58a54241c6dd3). This segmenter has one user-defined parameter: * The [`color threshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EColorSingleThresholdSegmenter.html#af4677b3b0247e49b76b6146c5a6d7eff) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EColorSingleThresholdSegmenter.html#ab2c13b979b407f5e119de15c07ccea2b) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EColorSingleThresholdSegmenter.html#a95057979931a2c4d5b3ae39d9a641b57) is a set of three **user-defined** integer values designating a color in the color space. ### Color Range Threshold The color range threshold segmenter is applicable to [`C24`](../../../doxygen_cpp/classeVision_1_1EImageC24.html) [.NET](../../../doxygen_cs/classeVision_1_1EImageC24.html) [Python](../../../doxygen_python/classeVision_1_1EImageC24.html) color images and produces coded images with two layers: - The **white layer** (usually Layer 1) contains unmasked pixels that belong to the cube of the color space defined by the `Low Threshold` point and the `High Threshold` point. - The **black layer** (usually Layer 0) contains the remaining unmasked pixels. To use this segmenter: * Set the segmentation method to [`ESegmentationMethod_ColorRangeThreshold`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da236fa896b0dbd6210296d22799e497af) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#a05d53aaa1f4ac971bd9ea268c997959e) * Access and modify the parameters of the segmenter with [`GetColorRangeThresholdSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a252182524ac3fe7e5f0914f95d22be02) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a5f0f6b09094b9b61819f9d9192c09c3e) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#aedf889c20d4e5f06a3ee2d60c416763c). This segmenter has two user-defined parameters: * The [`low threshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#a101d2f23c92119201df12f6e31dd1cb3) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#a3e5cc7260492995b5a4865bff6afe1f3) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#a142f7bb8d9b9ddf7f7d3eba0e0b03a84) * The [`high threshold`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#ad48efe1ea10c4d1ef44c6cb99d183a3c) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#a0a6be128a6a50e432917968a9c0b9f0b) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EColorRangeThresholdSegmenter.html#a333316ac74b4f5c012cf9ae394122977). ### Reference Image The reference image segmenter does **pixel-by-pixel thresholding** based on the corresponding value in a **reference image**. The reference image segmenter is applicable to `BW8` and `BW16` grayscale images and `C24` color images. It produces coded images with two layers: * The **white layer** (usually Layer 1) contains unmasked pixels that * have a gray value greater or equal to the gray value of the respective pixel in the reference image for grayscale images; * belong to the cube of the color space defined by the threshold point and the white point (255,255,255) for color images. * The **black layer** (usually Layer 0) contains the remaining unmasked pixels. To use this segmenter: * Set the segmentation method to [`ESegmentationMethod_ReferenceImage`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da98dcd08de5148a96d27e0c9e5dd9da42) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#a47d7f4b33d1af2d3c7c90a2e42009099) * Access and modify the parameters of the segmenter with [`GetReferenceImageSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#af381e32c612ef467447ef21bcb786542) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a124bcec5271210645697ecb1ab9bbd58) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#aafb43b95491921f0e3650059a341fa4c). This segmenter has a user-defined parameter: * The **reference image**. The reference image must be in the respective **eVision** image type. For example, use [`SetReferenceImageBW8`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EReferenceImageSegmenter.html#aa7e9ee74325085316f0390e6da38c004) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EReferenceImageSegmenter.html#ad7548dc90b9140b9a6c46bf345f2f139) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EReferenceImageSegmenter.html#a4e599a93cb3299c021612af278b2e547) for a `BW8` image. ### Image Range The image range segmenter does **pixel-by-pixel double thresholding** based on the corresponding values in a **low image** and **high image**. The reference image segmenter is applicable to `BW8` and `BW16` grayscale images and `C24` color images. It produces coded images with two layers: * The **white layer** (usually Layer 1) contains unmasked pixels whose values are inside the corresponding unmasked pixels in the `low image` and `high image`. * The **black layer** (usually Layer 0) contains the remaining unmasked pixels. To use this segmenter: * Set the segmentation method to [`ESegmentationMethod_ImageRange`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92daaee011d5f8fb3d670abec467eb3cfba9) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#a084336580bac6427f0087ca88adc21ee) * Access and modify the parameters of the segmenter with [`GetImageRangeSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a5e59d97648d8ef677c745eda03c5a7cc) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#af8c794625b7df40eac34c058890d4650) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#aff935d5ed3c0508509daa958ce1ebbff). This segmenter has two user-defined parameters: * The **low image**. The low image must be in the respective **eVision** image type. For example, use [`SetLowImageBW8`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a553e7f241be2a3e20e1ee716b3597f8e) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a207e9d6d3c4d50c15b68096cbafe9ad3) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a8f8490efa9adb0b84bc85b162c01af98) for a `BW8` image. * The **high image**. The high image must be in the respective **eVision** image type. For example, use [`SetLowImageBW8`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a553e7f241be2a3e20e1ee716b3597f8e) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a207e9d6d3c4d50c15b68096cbafe9ad3) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EImageRangeSegmenter.html#a8f8490efa9adb0b84bc85b162c01af98) for a `BW8` image. #### Preparing High and Low Reference Images The following cases need a segmentation using **pixel-by-pixel thresholding** which gives an allowed range of values for each pixel: * When the background is not uniform enough. * When the illumination is not uniform across the image. * When only differences between the image and a reference image (ideal) are to be enhanced. To prepare high and low reference images for these cases, you can start from an image of the scene without defects and add security margins before comparison. ![image](assets/images/easyobject/imagesegmenterssourceimage.webp) Gray-level tolerance must be provided for noise and illumination variations. ![image](assets/images/easyobject/grayleveltolerancemargins.webp) The image may have a slight shift in some direction which can be corrected by enlarging the light and dark areas using dilate and erode morphological operations. This geometric tolerance margin is roughly as large as the morphological filter size. ![image](assets/images/easyobject/geometrictolerancemargins.webp) Combining both kinds of tolerance margins gives the best results. ![image](assets/images/easyobject/combinedmargins.webp) ### Labeled Image The labeled image segmenter is applicable to `BW8` and `BW16` grayscale images and produces coded images with a number of layers equal to the maximum number of gray values: 256 for `BW8` images or 65536 for `BW16` images. The layer $n$ contains all the unmasked pixels having a gray value equal to $n$. To use this segmenter: * Set the segmentation method to [`ESegmentationMethod_LabeledImage`](../../../doxygen_cpp/namespaceeVision.html#afb169b9d4c31b07ee43e33bb3998d92da0b9b8ab18aa26cd8c226bac89ff83469) [.NET](../../../doxygen_cs/namespaceeVision.html#a1ef0f09dfbe684b23ff1840c32e864a0) [Python](../../../doxygen_python/classeVision_1_1ESegmentationMethod.html#acf1f86c111fe63d1e49ddb5ce8c70802) * Access and modify the parameters of the segmenter with [`GetLabeledImageSegmenter`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a97bfbe243975473c09e792553c762330) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a5953480c32e63be03e5dff311ca1cd4e) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a2e302f978282198db4e5b58f1b2f983b). This segmenter has two parameters to retrict the range of encoded layers: - The [`minimum layer`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a4f63c04945ee7ead4cccc0a5f066c12b) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a9ce679d94e30303e530ef9fccbd22c8b) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a72ff960381b8a237fd8a295144f50e1f). - The [`maximum layer`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#af92eb4b9747ef0bd27d9f29b502f3426) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#ad7157c4af02901e8f92f7a2039c67134) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#acd49e8c31de151c517c16e714404a990). By default, all layers are encoded. ## Selecting the Layers to Encode The segmentation methods determine which layer(s) to encode by default, and do not encode pixels from the other layers. ### Enabling and Disabling Layer Encoding for each Layer Individually The following tables list, for each layer, the Set/Get function and the default enable/disable value. - Two-layer segmenters | Layer | Set LayerEncoded function | Get LayerEncoded function | Default value | |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | Black layer | [`SetBlackLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a59d909f3a42e533421fb9b97f5c9910c) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#ab60fa7259d417f49b9a8a0c5537d41c1) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a25612a1ed58055018b2dec49811df1ff) | [`GetBlackLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#aabe96f5f15bdb5809fb2e615364d8bb6) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#ab60fa7259d417f49b9a8a0c5537d41c1) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a25612a1ed58055018b2dec49811df1ff) | `false` | | White layer | [`SetWhiteLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a7c9ce71be239a674c2e2cdfb6f135f0b) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a8e5175cb861a4a22417fd3406aa639f9) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#abc16a6791593de2f5565c30a0da16132) | [`GetWhiteLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a14d839c1d3b3f05c2a56d978dff1e297) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a8e5175cb861a4a22417fd3406aa639f9) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#abc16a6791593de2f5565c30a0da16132) | `true` | - Three-layer segmenters | Layer | Set LayerEncoded function name | Get LayerEncoded function name | Default value | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | Black layer | [`SetBlackLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a73294f5e1afad3f5f8d9c74fd1be7d2f) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a7989fde28bae7064d4b41e6a60b6c3be) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a52907bf18847776ae969e5486ab1b609) | [`GetBlackLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a3b94bbbf7e2ae39de0388ce39a607071) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a7989fde28bae7064d4b41e6a60b6c3be) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a52907bf18847776ae969e5486ab1b609) | `false` | | White layer | [`SetWhiteLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a45660eb7643cb9fa250743a98b6c5459) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aaa0b811787949509a2581cc51c2ce279) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a51dd18adfe6a019a978322fc82b5b4e6) | [`GetWhiteLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#ae973ec6aa708b18b770cbbfa14fbf9c6) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aaa0b811787949509a2581cc51c2ce279) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a51dd18adfe6a019a978322fc82b5b4e6) | `false` | | Neutral layer | [`SetNeutralLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a438ee82b2453ee5dc0cd360419e34d41) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a8e14e8ccffaf1a2e3aa81d9e6b6f17b8) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aa0a538c086737afef6f66322860a4ac1) | [`GetNeutralLayerEncoded`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a1027c72897325d992952b5bf964febf8) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a8e14e8ccffaf1a2e3aa81d9e6b6f17b8) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aa0a538c086737afef6f66322860a4ac1) | `true` | - Labeled image segmenter: use the [`minimum layer`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a4f63c04945ee7ead4cccc0a5f066c12b) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a9ce679d94e30303e530ef9fccbd22c8b) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#a72ff960381b8a237fd8a295144f50e1f) and [`maximum layer`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#af92eb4b9747ef0bd27d9f29b502f3426) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#ad7157c4af02901e8f92f7a2039c67134) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ELabeledImageSegmenter.html#acd49e8c31de151c517c16e714404a990) properties. ### Manually Assigning a Layer Index to each Layer Individually The layer index can be used to select or sort the ***blobs***. The following tables list, for each layer, the Set/Get function and the default value. - Two-layer segmenters | Layer | Set LayerEncoded function name | Get LayerEncoded function name | Default value | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | Black layer | [`SetBlackLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a84449496ec143bdb7cb54dc402f3ff81) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#aef5c14ec6f3b84a9d31b043f25812479) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#af3338ca108efcf2f79f8b1b9c0bef804) | [`GetBlackLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#acb5d9fee145a002731cae52285a5300d) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#aef5c14ec6f3b84a9d31b043f25812479) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#af3338ca108efcf2f79f8b1b9c0bef804) | 0 | | White layer | [`SetWhiteLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a38ec111a8a5b7e09fd4bdc8c2c479354) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#acb6ce4036166dc8a5409a5b7b847d68d) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a1d01f2875643fe51d3aad1940d392072) | [`GetWhiteLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#affda8502f8b7d6061f29045c019949ef) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#acb6ce4036166dc8a5409a5b7b847d68d) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1ETwoLayersImageSegmenter.html#a1d01f2875643fe51d3aad1940d392072) | 1 | - Three-layer segmenters | Layer | Set LayerEncoded function name | Get LayerEncoded function name | Default value | |---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| | Black layer | [`SetBlackLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a672d1044a1b622c635a4f808b87d6b0e) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aabf35c7c256b17d728c1ac18c18b9859) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#adc9fb5d8b9112ea65a4df6fc195477b0) | [`GetBlackLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a6ebd4f66b1f3146870cad419ba58cdea) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#aabf35c7c256b17d728c1ac18c18b9859) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#adc9fb5d8b9112ea65a4df6fc195477b0) | 0 | | Neutral layer | [`SetNeutralLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#acc174eece489ebfd1d641e3ad4e286d1) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a3d75e8942c1a32c857ec738f9426951c) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a0be427312a2d1abbc66ffbab7d820ab1) | [`GetNeutralLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#ac47658fcc2a8bacb53c4ac089c5a7c63) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a3d75e8942c1a32c857ec738f9426951c) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a0be427312a2d1abbc66ffbab7d820ab1) | 1 | | White layer | [`SetWhiteLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a081f67b83ad24c073dd113879e0bbc0f) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#ad09bb7733ba0fbe33afb26e95fb3cc17) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a47e5dce723e31ddba4a0a74876fb5263) | [`GetWhiteLayerIndex`](../../../doxygen_cpp/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a000ed861a96732fbcefbcf0130774fbf) [.NET](../../../doxygen_cs/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#ad09bb7733ba0fbe33afb26e95fb3cc17) [Python](../../../doxygen_python/classeVision_1_1Segmenters_1_1EThreeLayersImageSegmenter.html#a47e5dce723e31ddba4a0a74876fb5263) | 2 | - Labeled image segmenter: it is not possible to change the layer indexes. ## Connexity Since ***blobs*** are contiguous group of neighboring pixels, the way we define how two pixels are considered neighbors is important. Pixels can touch each other along an edge or by a corner: * In [`four connexity`](../../../doxygen_cpp/namespaceeVision.html#ae0e95085cb220a1266eafb8af44c9aa6a72d708f28675de2103ff21e9f6e2c69e) [.NET](../../../doxygen_cs/namespaceeVision.html#ab1d901c6cc19ab3c51cff93d1f025278) [Python](../../../doxygen_python/classeVision_1_1EEncodingConnexity.html#ab2e662621dde0f3fd3a249bc8340f70d) only pixels touching by an edge are considered neighbors. * In [`eight connexity`](../../../doxygen_cpp/namespaceeVision.html#ae0e95085cb220a1266eafb8af44c9aa6af77d31a68b329dc4bc6ad87854811641) [.NET](../../../doxygen_cs/namespaceeVision.html#ab1d901c6cc19ab3c51cff93d1f025278) [Python](../../../doxygen_python/classeVision_1_1EEncodingConnexity.html#acc8dfe141f1cf07321d17dc29acaec8a) (the default) pixels touching by a corner are also considered neighbors. Use [`SetEncodingConnexity`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#ad2b071ad3e6ddd2d39d5235fe80b3c16) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a258dd2634fe5013e86435ce77fc1ba7e) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a6bdf0dee6e05632415b928832451e6b9) to set the encoding connexity. ![image](assets/images/easyobject/easyobjectconnexity.webp) ## Normal vs. Continuous Mode In ***normal mode*** (default behavior), the image encoder does not track blobs across several successive images. EasyObject works with one image, without keeping blobs in memory. All the blobs are returned as objects. In ***continuous mode*** - **EasyObject** can process an image whose height is unknown or infinite (e.g. coming from a line-scan camera). The image is split into several chunks that are fed into an image encoder. Objects that straddle several successive image chunks can be detected. - The image encoder encodes only the objects that contain no run touching the last row of the source image. Objects that touch the inferior border of the image are not written in the coded image because they are expected to continue in subsequent image chunks, but they are kept in memory and are processed when subsequent images are analyzed. ![An image whose height was initially unknown.](assets/images/easyobject/easyobjectcontinuousmodesource.webp)![The three chunks of the image that will be encoded with the continuous mode (right).](assets/images/easyobject/easyobjectcontinuousmodechunks.webp) To use ***continuous mode*** 1. Enable the ***continuous mode*** with [`EImageEncoder::SetContinuousModeEnabled`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a783c4febdddc085a48db2b7e08e1276c) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a3510d398894451bad5010e1768d2c137) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a2c46d1bfd5972b3504a0df1212cf35f1) 2. Encode successive image chunks with [`EImageEncoder::Encode`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#a0212a8144f93eba43fbed584140a83cd) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#a0956dbfef4ebce656f72e3471997e518) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a1292c1003f94e89af9600e99198aed4c) using the same coded image with each chunk. ![](assets/images/easyobject/easyobjectcontinuousmoderesult1.webp)![](assets/images/easyobject/easyobjectcontinuousmoderesult2.webp)![](assets/images/easyobject/easyobjectcontinuousmoderesult3.webp) 3. After processing all chunks, use [`EImageEncoder::FlushContinuousMode`](../../../doxygen_cpp/classeVision_1_1EImageEncoder.html#adedb693dd808ab67ef30c2f35cd82c94) [.NET](../../../doxygen_cs/classeVision_1_1EImageEncoder.html#aee101c36751deb5117d7632b7f4e484a) [Python](../../../doxygen_python/classeVision_1_1EImageEncoder.html#a2205f8b271e10172c6833724d408a991) to encode the remaining objects. ![](assets/images/easyobject/easyobjectcontinuousmoderesult4.webp) #### SEE ALSO See the [code snippets](../../../resources/code_snippets/matching_and_measurement/easyobject/continuousmode.html.md) showing how to use the continuous mode.