Navigation Messages

Data types for autonomous navigation — goals, paths, maps, and obstacle avoidance.

# simplified
from horus import NavGoal, GoalResult, PathPlan, Waypoint, NavPath, OccupancyGrid, CostMap

NavGoal

Navigation goal — target pose with tolerance.

# simplified
import horus

goal = horus.NavGoal(
    x=5.0, y=3.0, theta=1.57,
    position_tolerance=0.1,
    angle_tolerance=0.05,
    timeout=30.0,
    timestamp_ns=horus.timestamp_ns(),
)

Field	Type	Default	Description
`x`, `y`, `theta`	`float`	`0.0`	Target pose (m, rad)
`position_tolerance`	`float`	`0.1`	Position tolerance (m)
`angle_tolerance`	`float`	`0.1`	Heading tolerance (rad)
`timeout`	`float`	`30.0`	Goal timeout (seconds)
`tolerance_position`	`float`	—	Position tolerance getter (same as position_tolerance)
`tolerance_angle`	`float`	—	Angle tolerance getter (same as angle_tolerance)
`timeout_seconds`	`float`	—	Timeout getter (same as timeout)
`goal_id`	`int`	`0`	Goal identifier
`priority`	`int`	`0`	Goal priority (higher = more important)
`timestamp_ns`	`int`	`0`	Timestamp in nanoseconds

Methods:

Method	Returns	Description
`with_timeout(seconds)`	`NavGoal`	Return a copy with timeout set
`with_priority(priority)`	`NavGoal`	Return a copy with priority set
`is_position_reached(current)`	`bool`	True if current `Pose2D` is within position tolerance
`is_orientation_reached(current)`	`bool`	True if current `Pose2D` is within angle tolerance
`is_reached(current)`	`bool`	True if both position and orientation are reached

GoalResult

Navigation goal outcome.

# simplified
result = horus.GoalResult(goal_id=1, status=0, progress=1.0, timestamp_ns=horus.timestamp_ns())

Field	Type	Default	Description
`goal_id`	`int`	`0`	Associated goal identifier
`status`	`int`	`0`	Result status code
`progress`	`float`	`0.0`	Completion progress (0.0-1.0)
`distance_to_goal`	`float`	`0.0`	Remaining distance to goal (m)
`eta_seconds`	`float`	`0.0`	Estimated time of arrival (seconds)
`timestamp_ns`	`int`	`0`	Timestamp in nanoseconds

Method	Returns	Description
`with_error(message)`	`GoalResult`	Return a copy with error message set

Waypoint

Single waypoint in a path.

# simplified
wp = horus.Waypoint(x=2.0, y=3.0, theta=0.0)

Field	Type	Default	Description
`x`, `y`, `theta`	`float`	`0.0`	Waypoint pose (m, rad)
`pose`	`Pose2D`	—	Waypoint pose as Pose2D object
`velocity`	`Twist`	—	Desired velocity at this waypoint
`curvature`	`float`	`0.0`	Path curvature at this point
`stop_required`	`bool`	`False`	Whether the robot must stop here

Method	Returns	Description
`with_velocity(twist)`	`Waypoint`	Return a copy with velocity set
`with_stop()`	`Waypoint`	Return a copy with stop_required=True

NavPath

Ordered list of waypoints. Created with no parameters.

# simplified
path = horus.NavPath()

Getter	Type	Description
`waypoint_count`	`int`	Number of waypoints
`total_length`	`float`	Total path length (m)
`duration_seconds`	`float`	Estimated path duration (s)
`timestamp_ns`	`int`	Timestamp

Method	Returns	Description
`add_waypoint(waypoint)`	`None`	Append a `Waypoint` to the path
`get_waypoints()`	`list`	Get all waypoints
`closest_waypoint_index(pose)`	`int` or `None`	Index of closest waypoint to a `Pose2D`
`calculate_progress(pose)`	`float`	Progress along path (0.0-1.0) for a `Pose2D`

PathPlan

Planned path to a goal.

# simplified
plan = horus.PathPlan(goal_x=5.0, goal_y=3.0, goal_theta=1.57, timestamp_ns=horus.timestamp_ns())

Field	Type	Default	Description
`goal_x`, `goal_y`, `goal_theta`	`float`	`0.0`	Goal pose (m, rad)
`waypoint_count`	`int`	—	Number of waypoints (getter only)
`goal_pose`	`tuple`	—	Goal as (x, y, theta) tuple (getter only)
`timestamp_ns`	`int`	`0`	Timestamp in nanoseconds

Static Methods:

Method	Returns	Description
`PathPlan.from_waypoints(waypoints, goal_x, goal_y, goal_theta)`	`PathPlan`	Create from a list of [x, y, theta] waypoints

Methods:

Method	Returns	Description
`add_waypoint(x, y, theta)`	`bool`	Add a waypoint, returns False if full
`waypoint(index)`	`tuple` or `None`	Get waypoint at index as (x, y, theta)
`is_empty()`	`bool`	True if no waypoints

OccupancyGrid

2D grid map — each cell is free (0), occupied (100), or unknown (-1).

# simplified
grid = horus.OccupancyGrid(width=100, height=100, resolution=0.05)

Field	Type	Default	Description
`width`, `height`	`int`	`0`	Grid dimensions (cells)
`resolution`	`float`	`0.05`	Meters per cell
`origin`	`Pose2D`	—	Map origin (bottom-left corner)
`data`	`list[int]`	—	Occupancy values (-1 to 100)
`timestamp_ns`	`int`	`0`	Timestamp

Methods:

Method	Returns	Description
`occupancy(gx, gy)`	`int` or `None`	Get occupancy value at grid coordinates
`set_occupancy(gx, gy, value)`	`bool`	Set occupancy value, returns False if out of bounds
`is_free(x, y)`	`bool`	True if world point is free (occupancy 0-49)
`is_occupied(x, y)`	`bool`	True if world point is occupied (occupancy >= 50)
`world_to_grid(x, y)`	`tuple` or `None`	Convert world coords to grid indices
`grid_to_world(gx, gy)`	`tuple` or `None`	Convert grid indices to world coords

CostMap

Weighted grid for path planning — higher cost = harder to traverse.

# simplified
costmap = horus.CostMap(grid=OccupancyGrid(), inflation_radius=0.55)

Field	Type	Default	Description
`occupancy_grid`	`OccupancyGrid`	—	Underlying occupancy grid (getter)
`costs`	`list[int]`	—	Cost values (0-255)
`inflation_radius`	`float`	`0.55`	Obstacle inflation radius (m)
`cost_scaling_factor`	`float`	—	Cost decay factor
`lethal_cost`	`int`	—	Cost threshold for lethal obstacles

Methods:

Method	Returns	Description
`cost(x, y)`	`int` or `None`	Get cost at world coordinates
`compute_costs()`	`None`	Recompute costs from occupancy data

VelocityObstacle / VelocityObstacles

Dynamic obstacle representation for reactive avoidance.

# simplified
vo = horus.VelocityObstacle(
    px=2.0, py_=1.0,
    vx=0.5, vy=0.0,
    radius=0.3,
    time_horizon=1.0,
    obstacle_id=0,
)
vos = horus.VelocityObstacles()  # No parameters

Field	Type	Default	Description
`px`	`float`	`0.0`	Position X (m)
`py_`	`float`	`0.0`	Position Y (m) — note trailing underscore
`vx`, `vy`	`float`	`0.0`	Velocity (m/s)
`radius`	`float`	`0.0`	Obstacle radius (m)
`time_horizon`	`float`	`1.0`	Planning time horizon (s)
`obstacle_id`	`int`	`0`	Obstacle identifier

VelocityObstacles methods:

Method	Returns	Description
`add_obstacle(obs)`	`None`	Add a `VelocityObstacle`
`get_obstacles()`	`list`	Get all obstacles

Navigation Messages

NavGoal

GoalResult

Waypoint

NavPath

PathPlan

OccupancyGrid

CostMap

VelocityObstacle / VelocityObstacles

See Also