How To

Use C FFI

C / C++ and Foreign Function Interface (FFI) integration guide for RustO!.

RustO! exports a stable C ABI through dynamic libraries (librusto.so, librusto.dylib, rusto.dll) and static archives (librusto.a, rusto.lib).

C Header (`rusto.h`)

#ifndef RUSTO_H
#define RUSTO_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

// Opaque engine instance handle
typedef struct ROCRHandle ROCRHandle;

// C-compatible OCR text detection block
typedef struct {
    char *text;
    float score;
    float box_x1, box_y1;
    float box_x2, box_y2;
    float box_x3, box_y3;
    float box_x4, box_y4;
    float frame_width, frame_height;
    float frame_top, frame_left;
} CTextResult;

// 1. Engine Lifecycle
ROCRHandle *rocr_initialize(const char *config_json);
void rocr_free(ROCRHandle *handle);
const char *rocr_version(void);

// 2. Structured Text Detection (Lines / Words)
int rocr_detect_text_file(
    ROCRHandle *handle,
    const char *image_path,
    const char *options_json,
    CTextResult **results_out,
    size_t *count_out
);

int rocr_detect_text_data(
    ROCRHandle *handle,
    const uint8_t *image_data,
    size_t image_len,
    const char *options_json,
    CTextResult **results_out,
    size_t *count_out
);

// 3. Spatial Layout Text Detection
char *rocr_detect_text_file_spatial(
    ROCRHandle *handle,
    const char *image_path,
    const char *options_json
);

char *rocr_detect_text_data_spatial(
    ROCRHandle *handle,
    const uint8_t *image_data,
    size_t image_len,
    const char *options_json
);

// 4. Memory Deallocation
void rocr_free_results(CTextResult *results, size_t count);
void rocr_free_string(char *s);

#ifdef __cplusplus
}
#endif

#endif // RUSTO_H

Return Codes Reference

Functions returning int status use the following return codes:

Code	Constant	Meaning
`0`	`ROCR_OK`	Operation succeeded.
`-1`	`ROCR_ERR_NULL_PTR`	Null pointer passed for required handle or parameter.
`-2`	`ROCR_ERR_INVALID_PATH`	File path could not be converted or does not exist.
`-3`	`ROCR_ERR_ENGINE`	Internal OCR detection or model inference error.
`-4`	`ROCR_ERR_INVALID_OPTIONS`	Options JSON syntax error or validation failure.
`-5`	`ROCR_ERR_MODE_MISMATCH`	Option `output` mode does not match called C function.

Example C Application

#include <stdio.h>
#include <stdlib.h>
#include "rusto.h"

int main() {
    printf("RustO! Version: %s\n", rocr_version());

    // 1. Initialize engine with JSON configuration
    const char *init_json =
        "{"
        "  \"template\": \"ppv6\","
        "  \"detection\": { \"modelPath\": \"models/det.rten\" },"
        "  \"recognition\": { \"modelPath\": \"models/rec.rten\", \"dictPath\": \"models/dict.txt\" }"
        "}";

    ROCRHandle *engine = rocr_initialize(init_json);
    if (!engine) {
        fprintf(stderr, "Failed to initialize RustO! engine.\n");
        return 1;
    }

    // 2. Run structured OCR detection
    const char *options_json = "{\"output\":\"lines\",\"textScore\":0.5}";
    CTextResult *results = NULL;
    size_t count = 0;

    int status = rocr_detect_text_file(engine, "receipt.jpg", options_json, &results, &count);
    if (status == 0) {
        printf("Detected %zu text blocks:\n", count);
        for (size_t i = 0; i < count; i++) {
            printf("[%zu] %s (Score: %.2f) at (%.1f, %.1f) [%.1fx%.1f]\n",
                i, results[i].text, results[i].score,
                results[i].frame_left, results[i].frame_top,
                results[i].frame_width, results[i].frame_height
            );
        }
        // Always free structured results
        rocr_free_results(results, count);
    } else {
        fprintf(stderr, "OCR Error code: %d\n", status);
    }

    // 3. Run spatial layout reconstruction
    const char *spatial_opts = "{\"output\":\"spatial\",\"lineYThreshold\":0.5,\"wordXThreshold\":0.4}";
    char *spatial_text = rocr_detect_text_file_spatial(engine, "receipt.jpg", spatial_opts);
    if (spatial_text) {
        printf("\n--- Spatial Layout ---\n%s\n", spatial_text);
        // Always free allocated spatial string
        rocr_free_string(spatial_text);
    }

    // 4. Free engine instance
    rocr_free(engine);
    return 0;
}

Building and Linking

Using GCC / Clang

gcc main.c -I. -L. -lrusto -Wl,-rpath,. -o ocr_demo
./ocr_demo

Using CMake (`CMakeLists.txt`)

cmake_minimum_required(VERSION 3.15)
project(OcrApp C)

add_executable(ocr_app main.c)

# Include header path
target_include_directories(ocr_app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# Link librusto shared library
target_link_libraries(ocr_app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/librusto.so)

Edit this pageorReport an issue

Use Android (Kotlin)

Using RustO! in native Android Kotlin and Jetpack Compose applications via JitPack.

Use CLI

Command line interface usage, batch processing, and output formatting options for RustO!.