OCR

OCR reads text from one or more regions of the captured frame. It uses an inference session, but it can run with or without an object-detection model.

Python Example

from helios import inference


class CVWorker:
    def __init__(self, width, height):
        self.engine = inference.create_inference_engine()
        self.engine.set_ocr_region_pixels(
            region_id=100,
            x=80,
            y=40,
            width=360,
            height=80,
        )
        self.engine.set_draw_ocr_region(True)
        self.engine.set_ocr_enabled(True)
        self.engine.start()

    def process(self, frame):
        result = self.engine.get_ocr_result(100)
        if result and result["status"] == inference.OCR_STATUS_READY:
            text = result["text"]
            confidence = result["confidence"]

get_ocr_result(region_id) returns None until a result exists.

Region Controls

Use stable numeric region ids so configuration and reads always refer to the same area. One session supports up to 16 OCR regions and processes at most one enabled region per scheduled frame, rotating through the enabled regions. More regions therefore increase the time between updates for any one region.

Drawing

set_draw_ocr_region(True) displays region markers. Colors use BGR order:

# All OCR regions
engine.set_color_ocr_region(223, 89, 192)

# One region
engine.set_color_ocr_region(0, 220, 255, region_id=100)

Disable region drawing after positioning the regions if the markers should not be visible in normal use.

Result Dictionary

Most scripts only need text and confidence. The returned dictionary also contains:

• region_id and status
• x, y, width, and height
• frame_width and frame_height
• frame_sequence
• text_bytes and flags

Status constants are OCR_STATUS_EMPTY, OCR_STATUS_READY, OCR_STATUS_NO_TEXT, OCR_STATUS_ERROR, and OCR_STATUS_DISABLED. OCR_FLAG_TRUNCATED indicates that the returned text was shortened.

With Object Detection

Pass a model UUID when the same session also needs detection, pose, or segmentation results:

engine = inference.create_inference_engine(model_uuid)
engine.set_confidence_threshold(0.45)
engine.set_ocr_region_normalized(100, 0.05, 0.04, 0.35, 0.12)
engine.set_ocr_skip_when_detections(False)
engine.set_ocr_enabled(True)
engine.start()

Set set_ocr_skip_when_detections(True) when OCR is only useful on frames without detections.

C++

Helios::Inference::Session provides matching camel-case methods:

using Helios::Inference::Session;

constexpr uint32_t kRegion = 100;

Session engine = Session::create();
engine.setOcrRegionPixels(kRegion, 80, 40, 360, 80);
engine.setDrawOcrRegion(true);
engine.setOcrEnabled(true);
engine.start();

HeliosInferenceOcrResult result{};
if (engine.getOcrResult(kRegion, result) && result.text_bytes > 0) {
    const std::string text(result.text, result.text_bytes);
    const float confidence = result.confidence;
}

The C++ session also provides setOcrSkipWhenDetections, normalized regions, per-region enable/remove controls, clearOcrRegions, and global or per-region setColorOcrRegion.

Tips

• Use the smallest region that reliably contains the text.
• Keep regions fixed when possible.
• Read status before using the text.
• Check the selected Compute GPU and the Output Panel if OCR does not start.