Perception Messages

Output types for machine learning and computer vision pipelines — detections, segmentation masks, tracked objects, and landmarks.

from horus import Detection, Detection3D, BoundingBox2D, BoundingBox3D, SegmentationMask

Detection

2D object detection — flat constructor with class, confidence, and bounding box fields.

import horus

det = horus.Detection(
    class_name="person",
    confidence=0.95,
    x=100.0, y=50.0,
    width=100.0, height=250.0,
    class_id=0,
    instance_id=0,
)

Field	Type	Default	Description
`class_name`	`str`	`""`	Detected class name
`confidence`	`float`	`0.0`	Detection confidence
`x`, `y`	`float`	`0.0`	Bounding box top-left (px)
`width`, `height`	`float`	`0.0`	Bounding box size (px)
`class_id`	`int`	`0`	Numeric class identifier
`instance_id`	`int`	`0`	Instance identifier

Detection3D

3D object detection — flat constructor with center, dimensions, and yaw.

det3d = horus.Detection3D(
    class_name="car",
    confidence=0.87,
    cx=5.0, cy=2.0, cz=0.8,
    length=4.5, width=1.8, height=1.5,
    yaw=0.0,
)

Field	Type	Default	Description
`class_name`	`str`	`""`	Detected class name
`confidence`	`float`	`0.0`	Detection confidence
`cx`, `cy`, `cz`	`float`	`0.0`	Bounding box center (m)
`length`, `width`, `height`	`float`	`0.0`	Bounding box dimensions (m)
`yaw`	`float`	`0.0`	Heading angle (rad)

BoundingBox2D

Axis-aligned 2D bounding box in pixel coordinates.

bbox = horus.BoundingBox2D(x=100.0, y=50.0, width=100.0, height=250.0)

Field	Type	Default	Description
`x`, `y`	`float`	`0.0`	Top-left corner (px)
`width`, `height`	`float`	`0.0`	Box dimensions (px)

BoundingBox3D

3D bounding box in world coordinates.

bbox3d = horus.BoundingBox3D(
    cx=5.0, cy=2.0, cz=0.8,
    length=4.5, width=1.8, height=1.5,
    yaw=0.0,
)

Field	Type	Default	Description
`cx`, `cy`, `cz`	`float`	`0.0`	Box center (m)
`length`, `width`, `height`	`float`	`0.0`	Box dimensions (m)
`yaw`	`float`	`0.0`	Heading angle (rad)

SegmentationMask

Per-pixel class labels.

mask = horus.SegmentationMask(width=640, height=480, mask_type=0, num_classes=21)

Field	Type	Default	Description
`width`, `height`	`int`	`0`	Image dimensions (px)
`mask_type`	`int`	`0`	Segmentation mask type
`num_classes`	`int`	`0`	Number of semantic classes

TrackedObject

Object with persistent tracking ID across frames.

tracked = horus.TrackedObject(
    track_id=42,
    x=100.0, y=50.0,
    width=100.0, height=250.0,
    class_id=0,
    confidence=0.9,
)

Field	Type	Default	Description
`track_id`	`int`	`0`	Persistent tracking ID
`x`, `y`	`float`	`0.0`	Bounding box top-left (px)
`width`, `height`	`float`	`0.0`	Bounding box size (px)
`class_id`	`int`	`0`	Numeric class identifier
`confidence`	`float`	`0.0`	Detection confidence

Landmark / Landmark3D

Visual landmarks for SLAM and localization.

lm = horus.Landmark(x=1.5, y=2.3, visibility=0.95, index=7)
lm3d = horus.Landmark3D(x=1.5, y=2.3, z=0.8, visibility=0.95, index=7)

Landmark

Field	Type	Default	Description
`x`, `y`	`float`	`0.0`	Position (px or m)
`visibility`	`float`	`1.0`	Visibility score (0.0-1.0)
`index`	`int`	`0`	Landmark index

Landmark3D

Field	Type	Default	Description
`x`, `y`, `z`	`float`	`0.0`	3D position (m)
`visibility`	`float`	`1.0`	Visibility score (0.0-1.0)
`index`	`int`	`0`	Landmark index

Example: YOLO Detection Pipeline

import horus

def detect_tick(node):
    img = node.recv("camera.rgb")
    if img is None:
        return

    frame = img.to_numpy()  # Zero-copy
    results = model.predict(frame)

    for r in results:
        det = horus.Detection(
            class_name=r.class_name,
            confidence=float(r.confidence),
            x=r.x, y=r.y,
            width=r.w, height=r.h,
            class_id=r.class_id,
        )
        node.send("detections", det)

detector = horus.Node(
    name="yolo",
    subs=[horus.Image],
    pubs=[horus.Detection],
    tick=detect_tick,
    rate=30,
    compute=True,
    on_miss="skip",
)
horus.run(detector)