# EasyMailBarCode - Reading Mail Bar Codes ![image](assets/images/easymailbarcode/mail_bar_code_-_example.webp) ## Principles A mail bar code is a 4-state bar code. This is a special kind of bar code where data is encoded on the height and position of the bars rather than their width. Each bar can have one of 4 possible states: * Short and centered * Medium and elevated * Medium and lowered * Full height ![image](assets/images/easymailbarcode/mail_bar_code_-_4-state.webp) ## Specifications The Mail Bar code Reader: * Detects and decodes postal 4-state bar codes. * Supports multiple mail bar codes in an image. * Supports various symbologies. * Supports the 4 main bar code orientations, with a tolerance of 3°. * Detects bars that are at least 3 pixels wide. ## Workflow ![image](assets/images/easymailbarcode/mail_bar_code_-_workflow.webp) ## Mail Bar Code Symbologies The symbology of a mail bar code specifies how to decode the bar code and how to interpret its contents. Every country uses its own flavor of mail bar code, or symbology. Some countries, like the US, even use multiple symbologies. As of now, the [`EMailBarcodeReader`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html) supports the following symbologies: * US * PLANET * POSTNET * Intelligent Mail * Japan * Japan Post #### SEE ALSO A description of the properties and look of each symbology can be found [here](../list_of_supported_codes.html.md#list-supported-mailbarcodes) ## Mail Bar Code Orientation The [`EMailBarcodeReader`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html) is designed to be used in mail-handling machines. As such it is optimized to handle the 4 main orientations you encounter in such machines: * No Rotation: The mail bar code is horizontal and read from left to right * Rotated `90°` to the right: The mail bar code is vertical and read from top to bottom * Rotated `90°` to the left: The mail bar code is vertical and read from bottom to top * Rotated `180°`: The mail bar code is upside down, horizontal, and read from right to left. For each of these orientations, an additional rotation of `-3` to `3` degrees is allowed. ## Checksum Some symbologies specify the presence of a checksum in the bar code data. This checksum is an additional character computed from all others encoded characters. It enables the reader to check the decoded character string coherence. * The `EMailBarcodeReader` allows the user to verify or not the checksum for all enabled symbologies. * By default, checksum is not controlled. * To enable or disable checksum verification for all enabled symbologies, use [`EMailBarcodeReader::SetValidateChecksum`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a2199914835d254086767632b229c063f) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#add711a69bfee18a8f60b38256b50ed72) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a92f1130f6bf2f748c27bf5cb3e7ea95c). ## Reading the Mail Bar Codes in an Image To read all the mail barcodes in a given image: 1. Create an [`EMailBarcodeReader`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html) object. 2. Optionally, select the relevant symbologies using [`EMailBarcodeReader::SetExpectedSymbologies`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a2ce41c7fc1cafd07ec3c872d057fabc1) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#aea40b9f67387f1801403a68335703b77) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a5698a1d54f60c8b7ddde75734f71849e). By default, Mail Bar code Reader will consider all supported symbologies. 3. Optionally, select the relevant orientations using [`EMailBarcodeReader::SetExpectedOrientations`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a0042f066dc81b7babdcffa37f8376e89) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#a7d2fc00c394d0b0b4a8391c7e95a24d5) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#abc3204d58a63eb171744a4d0235385ff). By default, Mail Bar code Reader will test all supported orientations. 4. Call [`EMailBarcodeReader::Read`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a8463565e19f80dad6696bb333cafab0f) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#a13f20b2cb1c260874f7420161ea9251b) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a25dc0f81bbd24bbe17c606bca66cb695) on the source image or ROI. Each mail bar code detected is returned as an [`EMailBarcode`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html) object. 5. Each [`EMailBarcode`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html) objects contains the following information: * The decoded string, using [`EMailBarcode::GetText`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html#a40b5300f262e83adc7b644aa0652082e) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html#a8559023facdec0fdc0beea2dbcdb91a3) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html#aca19cda5c83866d297516ffdafa52cf3). * The decoded string, split up in semantic parts, using [`EMailBarcode::GetComponentStrings`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html#a556fcaccf021c53a0699569dafd4edef) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html#a568aca22bbab7c73c652a3dc6de5a666) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html#a26b3adf0297edfd065e1efc6c5da79fa). * The bar code orientation, using [`EMailBarcode::GetOrientation`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html#ade1f3a9a6e1856ef1cd98ccb6672b088) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html#abfeccc1b96e8827e04bb15f5c4dba8fc) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html#a2576f23cc372d2b6140e8c3393e98327). * The bar code position, using [`EMailBarcode::GetPosition`](../../../doxygen_cpp/classeVision_1_1EMailBarcode.html#a1b319ba798db4abf7a4e19ac9a117295) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcode.html#a598067ecb6a41597375a3e7f5255d109) [Python](../../../doxygen_python/classeVision_1_1EMailBarcode.html#a9c955c6c86da67c188e704ddd5964259). ![image](assets/images/easymailbarcode/mail_bar_code_-_us_example.webp) ## Advanced Parameters The advanced parameters of the [`EMailBarcodeReader`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html) object are: * [`EMailBarcodeReader::SetEnableDottedBarcodes`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a0fd698172b210a37e8a051616bb04741) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#a5116f328940bbac184c6272e83f267c9) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a42b5ebe1531c810c28d2013b38f81509) activates the support for dotted barcodes (barcodes whose bars are printed with dots). By default, this property is set to false. ![image](assets/images/easymailbarcode/mail_bar_code_-_dotted_bar_code.webp) * [`EMailBarcodeReader::SetEnableClutteredBarcodes`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a7e42ee7d1db786324880075101a56d6f) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#a3c743168ff6f542017a1543afde22499) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a777870723b54cf466606b340c6d313bc) activates the support for cluttered barcodes (barcodes in which some bars are connected). By default, this property is set to true. ![image](assets/images/easymailbarcode/mail_bar_code_-_cluttered_bar_code.webp) * [`EMailBarcodeReader::SetValidateChecksum`](../../../doxygen_cpp/classeVision_1_1EMailBarcodeReader.html#a2199914835d254086767632b229c063f) [.NET](../../../doxygen_cs/classeVision_1_1EMailBarcodeReader.html#add711a69bfee18a8f60b38256b50ed72) [Python](../../../doxygen_python/classeVision_1_1EMailBarcodeReader.html#a92f1130f6bf2f748c27bf5cb3e7ea95c) activates the validation of the bar codes checksums, if present. By default, this property is set to false. ## Quick Links List of all Classes, Structs and Enumerations of the **EasyBarCode** library. Code snippets for the **EasyBarCode** library. All the code symbologies read by the text and code reading libraries.