CommonLibraries/README.md

# YoloRuntime

Shared C++17 Runtime, C ABI 5, for Windows x64 CPU and Linux AArch64 RK3588.
This is the sole production source for Studio, its SDK packages and MatchVerify.
Detect, CLS, Seg, OBB and Pose are retained. Seg supports four geometry modes:
minimum-area rotated rectangle (1), minimum enclosing circle (2), rectangle mean-diameter
circle (3), and robust contour-fit circle (4). Existing ABI 5 mode values and structure sizes remain unchanged.

## Build and consume

Windows: `powershell -ExecutionPolicy Bypass -File scripts/verify.ps1`.
Set `ONNXRUNTIME_ROOT` as a CMake cache path when using a non-default SDK.
Linux AArch64: configure with explicit `RKNN_MODEL_ZOO_ROOT` and the cross compiler;
Studio's build-runtime scripts supply these external dependencies. Native Linux
geometry/ABI tests can build with RKNN backends disabled.

Consumers may use `add_subdirectory` or installed `find_package(YoloRuntime CONFIG REQUIRED)`
and `YoloRuntime::Runtime`. Public headers and API names remain unchanged.
Use `yolo_runtime_infer_image` and `yolo_result_set_get_seg_geometry` with an explicit
geometry mode. Views are borrowed until `yolo_result_set_release`; copy masks first.
Angles are radians and all returned image coordinates are original-image pixels.
Entry-point paths and configuration model paths are UTF-8 on both platforms.

Every install includes `source-identity.json` and `runtime-manifest.json`.
The source revision hashes production sources/build scripts, not a moving branch name.
The manifest hashes all installed files. Consumers must deploy the full matching
dependency set and verify it before loading/packaging; they must never silently use
an older decoder. Rebuild/redeploy to update installed applications; no hot updater.

`python scripts/artifacts.py verify --root <install>` verifies the manifest.
The Windows and RK3588 source revisions must match before a dual-platform delivery.
Binary hashes differ between platforms and build toolchains by design.

Historical origin: RK3588_AI_Platform Runtime ABI 5 at repository HEAD
868a5f22f00ff2c81c3d0a6d2037400f037ac924, with its working source preserved during migration.

## Seg geometry modes

- `YOLO_SEG_GEOMETRY_MIN_AREA_RECT`: all mask boundary points, minimum-area rotated rectangle.
- `YOLO_SEG_GEOMETRY_MIN_ENCLOSING_CIRCLE`: all mask boundary points, minimum enclosing circle.
- `YOLO_SEG_GEOMETRY_MEAN_DIAMETER_CIRCLE`: same rectangle center, radius `(width + height) / 4`.
- `YOLO_SEG_GEOMETRY_ROBUST_FIT_CIRCLE`: largest external contour, arc-length sampling and
  Tukey IRLS fit with quality checks, migrated from MatchVerify's tested `SegCircleGeometry::Fit`.
  Failure returns that contour's minimum enclosing circle. `type` remains the requested fit mode;
  inspect `fit_status` (`YOLO_SEG_FIT_SUCCEEDED` or `YOLO_SEG_FIT_ENCLOSING_FALLBACK`).
  Other modes return `YOLO_SEG_FIT_NOT_REQUESTED`. Empty masks fail geometry calculation.

`fit_status` uses the first formerly reserved geometry word; existing fields, structure size
and ABI number remain unchanged. Query capability/mode bits before requesting a new mode
from an older Runtime. Linux runner: `--seg-geometry rect|circle|mean|fit`; JSON includes fit status.

OpenCV core/imgproc is now required to build the robust fit. Windows uses `OpenCV_DIR`;
installation includes its matching DLL(s) in the dependency manifest. Linux builds require
a target-compatible OpenCV package (`OpenCV_DIR`); deploy its shared dependencies as for
the existing Seg backend. This change does not update already deployed consumer applications.


## RGB instance-ID masks (2026-10-21)

`yolo_masks_compose_rgb_ids` is an additive public C API (ABI 5 structures
unchanged). Obtain each binary mask with `yolo_result_set_get_seg_mask`, keep
its result set alive, and pass the mask views in the intended instance order.
The function assigns ID = array index + 1 (not class ID), supports 0..255 masks,
and places each mask using its original-image origin. Pass the original image
width/height and a caller-owned RGB888 destination with its byte stride/capacity.
No dilation, fitting, resizing, or contour filling is performed.

| Membership | RGB bytes |
|---|---|
| Background | (0,0,0) |
| One instance | (ID,ID,ID) |
| Two instances | (ID1,ID2,ID1) |
| Three instances | (ID1,ID2,ID3) |

IDs in a shared pixel are ascending. Remove zero and duplicate channel values
to decode the instance set. Holes and disconnected regions are retained.
More than 255 instances or more than three at a pixel returns
`YOLO_STATUS_UNSUPPORTED` with a diagnostic when an error object is supplied.
Invalid bounds/stride/nonbinary pixels are rejected. Failure leaves the complete
destination unchanged; successful writes leave row padding unchanged. Zero masks
produce a black canvas. Source memory must remain readable during the call and
must not overlap output memory. Save as a lossless RGB image; when using a BGR
writer, convert RGB to BGR first. Existing per-instance binary-mask access and
runner PGM exports are unchanged. Apps must explicitly adopt the new API; this
batch does not redeploy any app or device runtime.