Entity - TechDocs

Overview

The Entity interface represents a generic trackable entity within the Zebra AI Data Capture SDK. It defines the methods required for any trackable entity, including retrieving bounding box data, and performing equality checks.Implementations of this interface represent specific types of entities that can be detected and tracked by the vision system.

Use Case:

Object Detection - Implementing Entity for objects detected in images to track their position and maintain metadata.

Methods

getBoundingBox()

    Rect Entity.Rect()

Retrieves the rectangular bounding box of the entity in pixel coordinates, providing a complete enclosure of the detected entity within an image. The bounding box is defined by its left, top, right, and bottom boundaries in absolute pixel coordinates relative to the original image dimensions. This information is valuable for quick collision detection, cropping operations, UI overlay positioning, and spatial analysis.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

NOTE: The Rect class is essential for graphical operations in Android, allowing developers to define and manipulate rectangular areas within an application’s UI or during drawing operations. The android.graphics.Rect is a class that represents a rectangle in a 2D coordinate system, defined by the coordinates of its top-left and bottom-right corners. It is extensively used for defining drawing boundaries, hit areas, and layout regions in Android applications. Rect holds four integer coordinates that define its edges (left, top, right bottom), which can be accessed directly. Use the width() and height() methods to retrieve the rectangle's width and height.

getCorners()

    List<Point>    getCorners();

Retrieves the corner points of the entity’s bounding box in pixel coordinates. This method returns a list of corner points that define the boundary of the detected entity within the image. The corners are typically returned in clockwise order starting from the top-left corner, with coordinates in absolute pixel values relative to the original image dimensions.

NOTE: android.graphics.Point is a fundamental Android class representing a 2D point with integer coordinates (x, y). The class provides direct access to x and y attributes, along with utility methods like set(int x, int y) for updating coordinates and equals(Object obj) for comparison.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

equals(Object obj)

    boolean    Entity.equals(Object obj)

Compares this entity with another entity for equality. This method compares the current entity with another entity of the same type, based on criteria specific to the implementation.

Parameters:

obj - The entity to compare with the current entity.

Return Value:

true - The entities are considered equal based on implementation-specific criteria
false - The entities are not considered equal based on implementation-specific criteria.

hashCode()

    int Entity.hashCode()

Returns the hash code of the trackable object. This method returns the hash code of the trackable object, which is used in hash-based collections. It must be consistent with the equals(Object) method to ensure proper behavior when entities are stored in hash-based collections.

Return Value: Returns the hash code of the entity as an integer.

getAccuracy()

    float Entity.getAccuracy()

Retrieves the detection probability (accuracy) for this entity. This value typically represents the confidence or probability score associated with the detection of this entity.

Return Value: Returns the probability or confidence value for this entity as a float.

BarcodeEntity Class

The BarcodeEntity interface represents a barcode detected within an image. It defines the structure for barcode entities, providing methods to access key barcode properties such as the raw barcode data, symbology type, label type, and detection accuracy. This interface is designed to be used within the context of barcode recognition systems, enabling developers to interact with barcode information in a structured and standardized manner.

Use Cases:

Inventory Management: Automate inventory tracking by scanning barcodes from product images to retrieve product details.
Retail Checkout Systems: Efficiently process product barcodes in point-of-sale systems, managing transactions and inventory updates.
Logistics and Supply Chain: Use barcode scanning to track shipments, verify contents, and ensure accurate delivery.
Security and Access Control: Enhance security systems by managing and verifying access credentials encoded in barcodes.
Marketing and Promotions: Process QR codes or barcodes for promotional materials, providing links to content or special offers.

Methods

getBoundingBox()

    Rect getBoundingBox()

Retrieves the rectangular bounding box of the barcode entity in pixel coordinates.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

getCorners()

    List<Point> getCorners()

Retrieves the corner points of the barcode’s bounding box in pixel coordinates.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

equals(Object obj)

    boolean    BarcodeEntity.equals(Object obj)

Compares this barcode entity with another for equality based on value, symbology, and corners.

Parameters:

obj - The object to compare with this BarcodeEntity.

Return Value:

true - The specified object is equal to this entity.
false - The specified object is not equal to this entity.

hashCode()

    int    BarcodeEntity.hashCode()

Generates a hash code for this barcode entity based on its value, symbology, and corners.

Return Value: Returns an integer hash code for this barcode entity.

getValue()

    String BarcodeEntity.getValue()

Retrieves the raw value of the barcode.

Return Value: Returns the barcode’s value as a String.

getSymbology()

    int    BarcodeEntity.getSymbology()

Retrieves the symbology type of the barcode.

Return Value: Returns an integer representing the barcode’s symbology type.

getLabel()

    String BarcodeEntity.getLabel()

Retrieves the label type or symbology of the barcode.

Return Value: Returns a string representing the barcode’s label type.

getAccuracy()

    float BarcodeEntity.getAccuracy()

Calculates and retrieves the accuracy of the barcode detection.

Return Value: Returns a float representing the accuracy of the barcode detection.

Sample Code

Explanation of Code Sample:

Process Image Data: The code initiates barcode detection process by calling barcodeDecoder.process, which accepts ImageData as input and returns a list of List<BarcodeEntity> objects representing detected barcodes.
Iterate Over Results: The resulting list is iterated, performing operations on each entity to extract and utilize barcode data.
Access Detection Confidence: The getAccuracy() method is called to retrieve the confidence level of the barcode detection, providing insights into detection reliability.
Check Equality and Hash Code: The code demonstrates how to check equality between entities and retrieve their hash codes using equals() and hashCode(), respectively. Note that equals() requires a parameter of the same type for comparison.
Access Bounding Box: The getBoundingBox() method obtains the dimensions of the barcode within the image.
Type Cast to BarcodeEntity: The entity is type-casted to BarcodeEntity to access barcode-specific methods like getValue() and getSymbology(), which are essential for barcode data extraction.
Access Barcode Data: Barcode-specific information such as the decoded value and symbology type is accessed for further processing or storage.

Sample Code:

    List<BarcodeEntity> resultList = barcodeDecoder.process(ImageData.fromImageProxy(image));

    for (BarcodeEntity entity:resultList) {
        // Access detection confidence
        float confidence = entity.getAccuracy();

        // Check equality (method requires a parameter, here it's assumed another entity for comparison)
        boolean isEqual = entity.equals(); // Note: Correct usage requires passing another entity

        // Retrieve hash code
        int hashcode = entity.hashCode();

        // Access bounding box
        BoundingBox boundingBox = entity.getBoundingBox();

        // Type cast Entity to BarcodeEntity for specific operations
        BarcodeEntity barcodeentity = (BarcodeEntity)entity;

        // Access barcode-specific data
        String value = barcodeentity.getvalue();
        Int symbology = barcodeentity.getSymbology();
        String label_type = barcodeentity.getLabel(); 
    }

LocalizerEntity Class

The LocalizerEntity class represents an entity detected by a Localizer, encapsulating details such as the object’s bounding box and its location within the image. This class offers methods for accessing and updating bounding box information, managing custom user data, and performing equality checks. It implements both the LocalizerEntity and MutableEntity interfaces.

Use Cases:

Object Detection and Classification: Detect and classify objects within images, providing precise location and category information for each detected entity.
Augmented Reality Applications: Anchor digital content to real-world objects based on their location and classification in AR systems.
Robotics and Navigation: Enable robots to navigate and interact with their environment by recognizing and classifying objects.
Security and Surveillance: Monitor and track objects of interest in security systems to enhance threat detection and response capabilities.
Retail and Inventory Management: Automate the identification and location of products within a store or warehouse for inventory tracking and management.

Methods

getBoundingBox()

    Rect LocalizerEntity.getBoundingBox()

Retrieves the rectangular bounding box of the entity in pixel coordinates. This method returns a rectangle that completely encloses the detected entity within the image.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

getCorners()

    List<Point>    LocalizerEntity.getCorners()

Retrieves the corner points of the entity’s bounding box in pixel coordinates. The corners are returned in a list, typically in clockwise order starting from the top-left corner.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

equals(Object obj)

    boolean    LocalizerEntity.equals(Object obj)

Compares this entity with another object for equality. This method considers two entities equal if their bounding box data, probability, and class ID match.

Parameters: obj - The object to compare with this LocalizerEntity.

Return Value:

true - The specified object is equal to this entity.
false - The specified object is not equal to this entity.

hashCode()

    int    LocalizerEntity.hashCode()

Returns a hash code value for this entity. The hash code is based on the bounding box, probability, and class ID.

Return Value: Returns an integer hash code for this entity.

getAccuracy()

    float LocalizerEntity.getAccuracy()

Retrieves the detection probability (accuracy) for this entity.

Return Value: Returns the probability value as a float.

getClassId()

    int LocalizerEntity.getClassId()

Retrieves the class ID for this entity.

Return Value: Returns the class ID as an integer.

Sample Code

Explanation of Code Sample:

Process Image Data: The code processes an image with the localizer.process() method, which accepts ImageData as input and returns a list of Entity<LocalizerEntity> objects.
Iterate Over Results: The resulting list is iterated over, and various operations are performed on each entity to extract and utilize localization data.
Access Detection Confidence: The getAccuracy() method is called to obtain the confidence level of the detection, offering insights into the reliability of the localization.
Check Equality and Hash Code: The code demonstrates how to check equality between entities and retrieve their hash codes using equals() and hashCode(), respectively. Note that equals() requires a parameter of the same type for comparison.
Access Bounding Box: The getBoundingBox() method is used to obtain the spatial location and dimensions of the localized entity within the image.
Type Cast to LocalizerEntity: The entity is type-cast to LocalizerEntity to access specific methods like getAccuracy() and getClassId(), which are essential for extracting localization data.
Access Localizer Data: Localizer-specific information such as detection confidence and class ID is accessed for further processing or classification.

Sample Code:

    List<LocalizerEntity> resultList = localizer.process(ImageData.fromImageProxy(image));

    for (LocalizerEntity entity: resultList) {
        // Access detection confidence
        float confidence = entity.getAccuracy();

        // Check equality (method requires a parameter, here it's assumed another entity for comparison)
        boolean isEqual = entity.equals(); // Note: Correct usage requires passing another entity

        // Retrieve hash code
        int hashcode = entity.hashCode();

        // Access bounding box
        BoundingBox boundingBox = entity.getBoundingBox();

        //Access probability of barcode 
        float value = entity.getAccuracy(); 

        // Typecast Entity to LocalizerEntity for specific operations 
        LocalizerEntity localizerentity = (LocalizerEntity)entity;

        // Access barcode-specific data
        Int getClassId = localizerentity.getClassId();
    }

ParagraphEntity Class

The ParagraphEntity class represents a paragraph of text detected in an image. It encapsulates information about a detected text paragraph, including its bounding box and component lines. The class provides access to the individual line entities that make up the paragraph.

Use Cases:

Document Digitization: Digitize and analyze printed or handwritten documents, extracting structured text information for digital storage or processing.
Content Management Systems: Automate the organization and indexing of text from scanned documents in content management applications.
Text Analysis and Summarization: Analyze and summarize text content, facilitating tasks such as data extraction, summarization, and sentiment analysis.
Optical Character Recognition (OCR): Enhance text recognition accuracy in OCR systems by leveraging structured paragraph data.
Educational Tools: Assist in reading comprehension and analysis in educational software, providing tools for students to interact with text in images.

Methods

getBoundingBox()

    Rect ParagraphEntity.getBoundingBox()

Retrieves the rectangular bounding box of the paragraph entity in pixel coordinates. This method returns a rectangle that completely encloses the detected entity within the image.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

getCorners()

    List<Point> getCorners()

Retrieves the corner points of the paragraph’s bounding box in pixel coordinates. The corners are returned in a list, typically in clockwise order starting from the top-left corner.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

equals(Object obj)

    boolean    ParagraphEntity.equals(Object obj)

Compares this paragraph entity with another object for equality. This method considers two entities equal if their text content, bounding box, line entities, and probability match.

Parameters:

obj - The object to compare with this ParagraphEntity.

Return Value:

true - The specified object is equal to this entity.
false - The specified object is not equal to this entity.

hashCode()

    int    ParagraphEntity.hashCode()

Returns a hash code value for this text paragraph entity. The hash code is based on the text content, bounding box, line entities, and probability.

Return Value: Returns an integer hash code for this entity.

getText()

    String ParagraphEntity.getText()

Concatenates the text from all lines in the paragraph, separating each line with a line break (\n). The result is a single string representing the entire paragraph as detected in the image.

Return Value: Returns a string containing the complete text of the paragraph, with lines separated by line breaks.

getLines()

    List<LineEntity> ParagraphEntity.getLines()

Returns an unmodifiable list of LineEntity objects representing the individual lines of text within this paragraph, ordered from top to bottom as they appear in the image. The returned list cannot be modified, ensuring the paragraph’s structure remains unchanged.

Return Value: An unmodifiable list of line entities (List<LineEntity>) within the text paragraph.

getAccuracy()

    float ParagraphEntity.getAccuracy()

Retrieves the detection probability (accuracy) for this paragraph entity.

Return Value: Returns a float value representing the detection probability.

Sample Code

Explanation of Code Sample:

Process Image Data: Use the textocr.process() method to extract a List<ParagraphEntity> from ImageData, resulting in a list of detected text paragraphs.
Iterate Over Results: The resulting list is iterated through, performing operations on each ParagraphEntity to extract and utilize paragraph data.
Access Detection Confidence: The getAccuracy() method is called to retrieve the confidence level of the paragraph detection, providing insights into the reliability of the recognition.
Check Equality and Hash Code: The code demonstrates how to check equality between entities and retrieve their hash codes using equals(Object) and hashCode(). Note that equals() requires a parameter of the same type for comparison.
Access Bounding Box: The getBoundingBox() method retrieves the rectangular bounding box of the paragraph within the image.
Access Paragraph Data: Paragraph-specific information, such as the full paragraph text (getText()) and the list of line entities (getLines()), is accessed for further processing or analysis.

Sample Code:

    List<ParagraphEntity> resultList = textocr.process(ImageData.fromImageProxy(image)).get(); 
    for (ParagraphEntity entity : resultList) { 

        // Access detection confidence 
        float confidence = entity.getAccuracy(); 

        // Check equality (example: compare with another entity) 
        // boolean isEqual = entity.equals(otherEntity); // Pass another ParagraphEntity or Object 

        // Retrieve hash code 
        int hashcode = entity.hashCode(); 

        // Access bounding box 
        android.graphics.Rect boundingBox = entity.getBoundingBox(); 

        // Access paragraph-specific data 
        String paragraphText = entity.getText(); 

        List<LineEntity> lineEntities = entity.getLines(); 
    }

LineEntity Class

The LineEntity class represents a line of text detected within an image. It encapsulates information such as the line’s bounding box and its component words. This class provides methods to access the individual word entities that compose the line and allows for the storage of custom user data associated with it.

Use Cases:

Document Processing: Extract and analyze lines of text from documents to support tasks such as indexing, searching, and archiving text data.
Optical Character Recognition (OCR): Improve text recognition accuracy and deliver structured output for further processing.
Text Layout Analysis: Analyze and understand text layout within documents to aid in reconstructing document structure.
Transcription Services: Convert scanned text lines into editable and searchable digital text for transcription applications.
Language Learning Tools: Assist learners in analyzing and understanding text lines with educational software, offering tools for language learning and comprehension.

Methods

getBoundingBox()

    Rect LineEntity.getBoundingBox()

Retrieves the rectangular bounding box of the line entity in pixel coordinates. This method returns a rectangle that completely encloses the detected entity within the image.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

getCorners()

    List<Point> getCorners()

Retrieves the corner points of the line’s bounding box in pixel coordinates. The corners are returned in a list, typically in clockwise order starting from the top-left corner.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

equals(Object obj)

    boolean LineEntity.equals(Object obj)

Compares this line entity with another line entity for equality. Two line entities are considered equal if their text content, bounding box, word entities, and bounding box probability are all equal.

Parameters:

obj - The object to compare with this LineEntity.

Return Value:

true - The specified object is equal to this entity.
false - The specified object is not equal to this entity.

hashCode()

    int    LineEntity.hashCode()

Returns a hash code value for this text line entity. The hash code is based on the text content, bounding box, word entities, and probability.

Return Value: Returns an integer hash code for this entity.

getText()

    String LineEntity.getText()

Returns the complete text content of the line as a single string, combining all words in the line with spaces between them. The resulting string represents the full line of text as detected in the image.

Return Value: String: The text content of the line, with words separated by spaces.

getWords()

    List<WordEntity> LineEntity.getWords()

Returns an unmodifiable list of WordEntity objects representing the individual words within this line, ordered from left to right as they appear in the image. The returned list cannot be modified, ensuring the structure of the line remains unchanged.

Return Value: An unmodifiable list of word entities (List<WordEntity>) within the line.

getAccuracy()

    float LineEntity.getAccuracy()

Retrieves the detection probability (accuracy) for this line entity.

Return Value: Returns the probability value as a float.

Sample Code

Explanation of Code Sample:

Iterate Over Results: The code iterates over a list of List<LineEntity>, where each object represents a detected line of text in the image.
Access Detection Confidence: The getAccuracy() method is called to retrieve the confidence level of line detection, providing insights into the reliability of the recognition.
Check Equality and Hash Code: The code demonstrates how to check equality between entities and retrieve their hash codes using equals(Object) and hashCode(). Note that equals() requires a parameter of the same type for comparison.
Access Bounding Box: The getBoundingBox() method retrieves the rectangular bounding box of the line within the image.
Access Line Data: Line-specific information, such as the text content (getText()) and the list of word entities (getWords()), is accessed for further processing or analysis.

Sample Code:

    for (LineEntity entity : resultList) { 

        // Access detection confidence 
        float confidence = entity.getAccuracy(); 

        // Check equality (example: compare with another entity) 
        // boolean isEqual = entity.equals(otherEntity); // Pass another LineEntity or Object 

        // Retrieve hash code 
        int hashcode = entity.hashCode(); 

        // Access bounding box (returns android.graphics.Rect) 
        android.graphics.Rect boundingBox = entity.getBoundingBox(); 

        // Access line-specific data 
        String lineText = entity.getText(); 
        List<WordEntity> wordEntities = entity.getWords(); 
    }

WordEntity Class

The WordEntity class represents a word detected within an image. It encapsulates information about a detected word, such as its bounding box and decoded text alternatives. This class allows access to the individual decoded text entities that form the word and supports the storage of custom user data linked to the word.

Use Cases:

Text Recognition and Processing: Extract and analyze words from images, facilitating tasks such as text recognition, indexing, and searching.
Document Digitization: Convert scanned documents into editable and searchable text formats within digitization workflows.
Optical Character Recognition (OCR): Enhance text recognition accuracy and deliver structured word-level output in OCR systems for further processing.
Language Learning Applications: Assist learners in analyzing and understanding words with educational software, providing tools for language learning and comprehension.
Data Extraction from Forms: Extract text data from structured forms to enable automated data entry and processing.

Methods

getCorners()

    List<Point>    getCorners()

Retrieves the corner points of the word’s bounding box in pixel coordinates. The corners are returned in a list, typically in clockwise order starting from the top-left corner.

Return Value: Returns a list of Point objects representing the corner coordinates in pixels, or an empty list if no corners are available.

getBoundingBox()

    Rect WordEntity.getBoundingBox()

Retrieves the rectangular bounding box of the word entity in pixel coordinates. This method returns a rectangle that completely encloses the detected entity within the image.

Return Value: Returns a Rect object representing the bounding box in pixel coordinates, or null if no bounding box is available.

equals(Object obj)

    boolean    WordEntity.equals(Object obj)

Compares this word entity with another object for equality. Two word entities are considered equal if their text content, bounding box, decoded text entities, and bounding box probability are all equal.

Parameters:

obj - The object to compare with this WordEntity.

Return Value:

true - The specified object is equal to this entity.
false - The specified object is equal to this entity.

hashCode()

    int    WordEntity.hashCode()

Returns a hash code value for this word entity. The hash code is generated based on the decoded text content if available, otherwise based on the bounding box.

Return Value: Returns an integer hash code for this entity.

getText()

    String WordEntity.getText()

Retrieves the most confident decoded text for this word. Returns the text content of the word as recognized by the OCR engine. This is typically the most likely interpretation of the word detected in the image.

Return Value: The most confident decoded text for this word in String format, or an empty string if no text is available.

getAllPredictedText()

    DecodedText[] WordEntity.getPredictedText()

Retrieves all possible decoded text interpretations for this word, ordered by confidence. Returns an array of DecodedText objects, each representing a possible interpretation of the word along with its confidence score. The first element in the array is the most confident prediction.

Return Value: An array (DecodedText[]) of possible decoded text interpretations for this word, ordered by confidence. Returns an empty array if no predictions are available.

getAccuracy()

    float WordEntity.getAccuracy()

Retrieves the detection probability (accuracy) for this word entity.

Return Value: Returns the probability value as a float.

Sample Code

Explanation of Code Sample:

Iterate Over Results: The code iterates over List<WordEntity>, where each object represents a detected word in the imagae.
Access Detection Confidence: The getAccuracy() method is invoked to retrieve the confidence level of word detection, providing insights into the reliability of the recognition.
Check Equality and Hash Code: The code demonstrates how to check equality between entities and retrieve their hash codes using equals(Object) and hashCode(). Note that equals() requires another object as a parameter for comparison.
Access Bounding Box: The getBoundingBox() method retrieves the spatial location and dimensions of the word within the image.
Access Word Data: Word-specific information, such as the recognized text (getText()) and all possible decoded text predictions (getAllPredictedText()), is accessed for further processing or analysis.

Sample Code:

    for (WordEntity entity : resultList) { 

        // Access detection confidence 
        float confidence = entity.getAccuracy(); 

        // Check equality (example: compare with another entity) 
        // boolean isEqual = entity.equals(otherEntity); // Pass another WordEntity or Object 

        // Retrieve hash code 
        int hashcode = entity.hashCode(); 

        // Access bounding box (returns android.graphics.Rect) 
        android.graphics.Rect boundingBox = entity.getBoundingBox(); 

        // Access word-specific data 
        String wordText = entity.getText(); 
        DecodedText[] decodedTexts = entity.getAllPredictedText(); 
    }

Related Guides

About
Setup
Localizer
- Models: Barcode, Product & Shelf
Product Recognition - Model: Model
Barcode Decoder
Text OCR
- Model
CameraX
Data Types