Docs / Tasks / Object detection

Object detection

Find every object in a frame, label it, return the bounding box in pixel coordinates.

Object detection takes one image, runs a YOLO-family model, and returns a list of detections. Each detection has a class label, a confidence score, and a Rect in the original image's pixel space. The yolo family auto-detects which task to run from the ONNX output shape: detect, segment, pose, OBB, or 1000-class classify.

The default detect path uses YOLO26x trained on COCO 80. Swap in YOLOv8 or YOLOv11 by pointing yolo.model at a different ONNX file. The same calls work on every binding; the only difference is how you load the source image.

Code

Use YoloFamily directly for type-safe std::variant results, or ai.getFamily("yolo") to match the C/Python registry pattern.

cpp

#include "imaged/sdk.hpp"
#include "imaged/families/yolo/yolo_family.hpp"

int main() {
    imaged::SDK::AI ai;
    auto& config = ai.getOptions();
    config.set("license.token", "your-license-token");
    config.set("license.audience", "cameras.acme.com");
    config.checkLicense();

    config.set("yolo.model", "yolo26x.onnx");
    config.set("yolo.confidenceThreshold", 0.35);

    imaged::SDK::YoloFamily family;
    family.load(config);

    imaged::SDK::Image image;
    image.load("bus.jpg");

    auto result = family.run({&image});
    for (const auto& d : std::get<imaged::SDK::DetectionResult>(result).detections) {
        std::cout << d.label << " " << d.score << "\n";
    }
}

#include "imaged/sdk_c.h"
#include <stdio.h>

int main(void) {
    AIHandle ai = ai_create();
    ConfigurationOptionsHandle cfg = ai_get_options(ai);

    configuration_options_set_string(cfg, "license.token", "your-license-token");
    configuration_options_set_string(cfg, "license.audience", "cameras.acme.com");
    configuration_options_check_license(cfg);

    configuration_options_set_string(cfg, "yolo.model", "yolo26x.onnx");

    ImageHandle img = image_create();
    image_load(img, "bus.jpg");

    ResponseObject r = ai_family_detect(ai, "yolo", img);
    for (int i = 0; i < r.objectCount; i++) {
        printf("%s %.2f\n", r.objects[i].label, r.objects[i].score);
    }

    image_destroy(img);
    ai_destroy(ai);
    return 0;
}

python

from imaged import AI, Image

ai = AI()
ai.config.set("license.token", "your-license-token")
ai.config.set("license.audience", "cameras.acme.com")
ai.config.check_license()

ai.config.set("yolo.model", "yolo26x.onnx")
ai.config.set("yolo.confidenceThreshold", "0.35")

img = Image()
img.load("bus.jpg")

for det in ai.detect("yolo", img):
    box = det["box"]
    print(f"{det['label']} {det['score']:.2f} "
          f"[{box['x']},{box['y']} {box['width']}x{box['height']}]")

Bundle yolo26x.onnx in your target so Bundle.main.path resolves. The full pattern with AVFoundation lives in CameraDetector.swift.

swift

import imaged

let ai = AISDK()
let cfg = ai.options
cfg.setOption(forKey: "license.token", stringValue: "your-license-token")
cfg.setOption(forKey: "license.audience", stringValue: "cameras.acme.com")
_ = cfg.checkLicense()

cfg.setOption(forKey: "yolo.model",
              stringValue: Bundle.main.path(forResource: "yolo26x", ofType: "onnx")!)
cfg.setOption(forKey: "yolo.confidenceThreshold", doubleValue: 0.35)

let img = AIImage()
img.load(from: "bus.jpg")

let response = ai.detect("yolo", in: img)
for obj in response.objects ?? [] {
    print(obj.label ?? "?", obj.score)
}

objc

#import <imaged/imaged.h>

AISDK *ai = [[AISDK alloc] init];
AIConfigurationOptions *cfg = [ai getOptions];
[cfg setOptionForKey:@"license.token" stringValue:@"your-license-token"];
[cfg setOptionForKey:@"license.audience" stringValue:@"cameras.acme.com"];
[cfg checkLicense];

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"yolo26x"
                                                      ofType:@"onnx"];
[cfg setOptionForKey:@"yolo.model" stringValue:modelPath];
[cfg setOptionForKey:@"yolo.confidenceThreshold" doubleValue:0.35];

AIImage *img = [[AIImage alloc] init];
[img loadFrom:@"bus.jpg"];

AIResponseObject *response = [ai familyDetect:@"yolo" image:img];
for (AIDetectedObject *obj in response.objects) {
    NSLog(@"%@ %.2f", obj.label, obj.score);
}

Stage yolo26x.onnx out of assets into filesDir before passing the absolute path; ORT cannot mmap files inside the APK.

java

import dev.imaged.sdk.*;

ImagedLoader.load(context);

ImagedSDK ai = new ImagedSDK();
ConfigurationOptions cfg = ai.getOptions();
cfg.setString("license.token", "your-license-token");
cfg.setString("license.audience", "cameras.acme.com");
cfg.checkLicense();

cfg.setString("yolo.model", modelPath);
cfg.setDouble("yolo.confidenceThreshold", 0.35);
cfg.setString("yolo.inference.provider", "cpu");

try (Image img = new Image()) {
    img.setData(rgbaBytes, width, height, ColorCode.RGBA);
    ResponseObject response = ai.detect("yolo", img);
    if (response.objects != null) {
        for (DetectedObject obj : response.objects) {
            android.util.Log.i("imaged", obj.label + " " + obj.score);
        }
    }
}

qnn engages the Snapdragon HTP on arm64; falls back to CPU on emulators or non-Snapdragon devices.

kotlin

import dev.imaged.sdk.*

ImagedLoader.load(context)

val ai = ImagedSDK()
val cfg = ai.options
cfg.setString("license.token", "your-license-token")
cfg.setString("license.audience", "cameras.acme.com")
cfg.checkLicense()

cfg.setString("yolo.model", modelPath)
cfg.setDouble("yolo.confidenceThreshold", 0.35)
cfg.setString("yolo.inference.provider", "qnn")

Image().use { img ->
    img.setData(rgbaBytes, width, height, ColorCode.RGBA)
    val response = ai.detect("yolo", img)
    response.objects.orEmpty().forEach { obj ->
        android.util.Log.i("imaged", "${obj.label} ${obj.score}")
    }
}

Models that fit

yolo26x yolov8 yolov11