Python API

Complete Python API documentation for HORUS. The Python bindings are built with PyO3, exposing the core Rust framework to Python with zero-copy shared memory IPC.

Python Bindings

Full reference for the HORUS Python bindings:

Node — Create nodes with tick, init, and shutdown callbacks
Topic — Unified pub/sub with typed messages (CmdVel, Pose2D, Imu, etc.)
Scheduler — Node execution with priority ordering, rate control, and composable builder methods
TransformFrame / Transform — Coordinate frame management
Image / PointCloud / DepthImage — Zero-copy shared memory data with DLPack

Custom Messages

Create your own typed messages in Python:

Runtime messages - No build step, ~20-40μs latency
Compiled messages - Requires maturin, ~3-5μs latency
NumPy-based messages for better performance
YAML schema support for team projects

Async Nodes

Asynchronous Python nodes for non-blocking I/O operations.

Memory Types

Zero-copy Image, PointCloud, and DepthImage with NumPy/PyTorch/JAX interop.

Perception Types

Object detection, tracking, pose estimation — DetectionList, TrackedObject, COCOPose, PointCloudBuffer.

TransformFrame

Coordinate frame management — register frames, look up transforms, interpolate, export.

Quick Reference

Core Classes

Class	Description
`Node`	Computation unit — all config via kwargs (`tick`, `rate`, `order`, `budget`, etc.)
`Topic`	Standalone pub/sub channel for inter-process IPC
`Scheduler`	Node execution orchestrator (composable kwargs, no presets)
`Params`	Dict-like runtime parameter store from `horus.toml`
`Rate`	Drift-compensated rate limiter for background threads
`NodeState`	Node lifecycle states

Message Types

Class	Fields	Default Topic
`CmdVel`	`linear`, `angular`	`"cmd_vel"`
`Pose2D`	`x`, `y`, `theta`	`"pose"`
`Imu`	`accel_x/y/z`, `gyro_x/y/z`	`"imu"`
`Odometry`	`x`, `y`, `theta`, `linear_velocity`, `angular_velocity`	`"odom"`
`LaserScan`	`ranges`, `angle_min/max`, `range_min/max`	`"scan"`

Transform System

Class	Description
`TransformFrame`	Coordinate frame tree with transform lookups
`Transform`	3D transformation (translation + quaternion rotation)
`TransformFrameConfig`	TransformFrame configuration with size presets

Perception Types

Available in horus.perception:

Class	Description
`Detection`	Object detection result (bbox, class, confidence)
`DetectionList`	Collection of detections with filtering
`BoundingBox2D`	2D bounding box with IoU calculation
`PointCloudBuffer`	Point cloud with NumPy integration
`TrackedObject`	Object tracking with velocity estimation

Large Data Types

Class	Description
`Image`	Pool-backed camera image with zero-copy framework conversions
`PointCloud`	Pool-backed 3D point cloud with zero-copy ML interop
`DepthImage`	Pool-backed depth image (F32 meters or U16 millimeters)

Networking

Class	Description
`RouterClient`	Connect to HORUS network router
`RouterServer`	Host a HORUS network router

Installation

pip install horus-robotics

Minimal Example

import horus

def my_tick(node):
    node.send("greeting", "Hello from Python!")
    msg = node.recv("greeting")
    if msg:
        print(msg)

node = horus.Node(
    name="MyNode",
    pubs=["greeting"],
    subs=["greeting"],
    tick=my_tick,
    rate=10
)

horus.run(node)