Geometry Messages

Spatial data types for positions, orientations, velocities, and coordinate transforms.

# simplified
from horus import Pose2D, Pose3D, Twist, Vector3, Quaternion, TransformStamped

Pose2D

2D position and orientation — the most common pose type for ground robots.

# simplified
pose = Pose2D(x=1.0, y=2.0, theta=0.5)  # meters, radians

Field	Type	Unit	Description
`x`	`float`	m	X position
`y`	`float`	m	Y position
`theta`	`float`	rad	Heading angle
`timestamp_ns`	`int`	ns	Timestamp

Static Method	Returns	Description
`Pose2D.origin()`	`Pose2D`	Create a pose at the origin (0, 0, 0)

Method	Returns	Description
`distance_to(other)`	`float`	Euclidean distance to another Pose2D
`normalize_angle()`	`None`	Normalize theta to [-pi, pi] in-place
`is_valid()`	`bool`	Check for NaN/inf values

Pose3D

6-DOF pose — position + quaternion orientation.

# simplified
pose = Pose3D(
    x=1.0, y=2.0, z=0.5,
    qx=0.0, qy=0.0, qz=0.0, qw=1.0,  # identity rotation
)

Field	Type	Unit	Description
`x`, `y`, `z`	`float`	m	Position
`qx`, `qy`, `qz`, `qw`	`float`	—	Quaternion orientation
`timestamp_ns`	`int`	ns	Timestamp

Static Method	Returns	Description
`Pose3D.identity()`	`Pose3D`	Identity pose (origin, no rotation)
`Pose3D.from_pose_2d(pose)`	`Pose3D`	Create from a Pose2D (z=0, rotation around z-axis)

Method	Returns	Description
`distance_to(other)`	`float`	Euclidean distance to another Pose3D
`is_valid()`	`bool`	Check for NaN/inf values

Twist

6-DOF velocity — linear + angular.

# simplified
twist = Twist(
    linear_x=0.5, linear_y=0.0, linear_z=0.0,
    angular_x=0.0, angular_y=0.0, angular_z=0.3,
)

Field	Type	Unit	Description
`linear_x`, `linear_y`, `linear_z`	`float`	m/s	Linear velocity
`angular_x`, `angular_y`, `angular_z`	`float`	rad/s	Angular velocity
`timestamp_ns`	`int`	ns	Timestamp

Static Method	Returns	Description
`Twist.stop()`	`Twist`	Zero velocity (all components 0)
`Twist.new_2d(linear_x=0.0, angular_z=0.0)`	`Twist`	2D twist (only forward + yaw)

Method	Returns	Description
`is_valid()`	`bool`	Check for NaN/inf values

ROS2 equivalent: geometry_msgs/msg/Twist

Vector3

3D vector for general-purpose spatial math.

# simplified
v = Vector3(x=1.0, y=0.0, z=0.0)

Field	Type	Description
`x`, `y`, `z`	`float`	Vector components

Static Method	Returns	Description
`Vector3.zero()`	`Vector3`	Zero vector (0, 0, 0)

Method	Returns	Description
`magnitude()`	`float`	Vector length (L2 norm)
`normalize()`	`None`	Normalize to unit length in-place
`normalized()`	`Vector3`	Return a new unit-length vector (does not mutate self)
`dot(other)`	`float`	Dot product with another Vector3
`cross(other)`	`Vector3`	Cross product with another Vector3

Point3

3D point (semantically distinct from Vector3 — a position, not a direction).

# simplified
p = Point3(x=1.0, y=2.0, z=3.0)

Field	Type	Description
`x`, `y`, `z`	`float`	Point coordinates

Static Method	Returns	Description
`Point3.origin()`	`Point3`	Origin point (0, 0, 0)

Method	Returns	Description
`distance_to(other)`	`float`	Euclidean distance to another Point3

Quaternion

Rotation quaternion (x, y, z, w format).

# simplified
q = Quaternion(x=0.0, y=0.0, z=0.0, w=1.0)  # identity

Field	Type	Description
`x`, `y`, `z`, `w`	`float`	Quaternion components

Static Method	Returns	Description
`Quaternion.identity()`	`Quaternion`	Identity rotation (0, 0, 0, 1)
`Quaternion.from_euler(roll=0.0, pitch=0.0, yaw=0.0)`	`Quaternion`	Create from Euler angles (radians)

Method	Returns	Description
`normalize()`	`None`	Normalize to unit quaternion in-place
`is_valid()`	`bool`	Check if quaternion is approximately unit length

Accel

6-DOF acceleration.

# simplified
accel = Accel(
    linear_x=0.0, linear_y=0.0, linear_z=9.81,
    angular_x=0.0, angular_y=0.0, angular_z=0.0,
)

Field	Type	Unit	Description
`linear_x`, `linear_y`, `linear_z`	`float`	m/s²	Linear acceleration
`angular_x`, `angular_y`, `angular_z`	`float`	rad/s²	Angular acceleration
`timestamp_ns`	`int`	ns	Timestamp

Method	Returns	Description
`is_valid()`	`bool`	Check for NaN/inf values

TransformStamped

Timestamped rigid-body transform (translation + rotation).

Constructor

# simplified
tf = horus.TransformStamped(
    tx=0.1, ty=0.0, tz=0.3,
    rx=0.0, ry=0.0, rz=0.0, rw=1.0,
    timestamp_ns=horus.timestamp_ns(),
)

Field	Type	Description
`tx`, `ty`, `tz`	`float`	Translation (meters)
`rx`, `ry`, `rz`, `rw`	`float`	Rotation quaternion
`timestamp_ns`	`int`	Timestamp in nanoseconds

Static Methods

Method	Returns	Description
`TransformStamped.identity()`	`TransformStamped`	Identity transform (no translation or rotation)
`TransformStamped.from_pose_2d(pose)`	`TransformStamped`	Create from a `Pose2D` (z=0, rotation around z-axis)

Methods

Method	Returns	Description
`is_valid()`	`bool`	Check if the rotation quaternion is normalized
`normalize_rotation()`	`None`	Normalize the rotation quaternion in-place

PoseStamped

Timestamped pose.

# simplified
ps = horus.PoseStamped(
    x=1.0, y=2.0, z=0.0,
    qx=0.0, qy=0.0, qz=0.0, qw=1.0,
    frame_id="map",
    timestamp_ns=horus.timestamp_ns(),
)

PoseWithCovariance

Pose with uncertainty estimate (6x6 covariance matrix, row-major).

# simplified
pwc = PoseWithCovariance(
    x=1.0, y=2.0, z=0.0,
    qx=0.0, qy=0.0, qz=0.0, qw=1.0,
    frame_id="map",
)
pwc.covariance = [0.01] * 36  # 6x6 row-major

Field	Type	Description
`x`, `y`, `z`	`float`	Position
`qx`, `qy`, `qz`, `qw`	`float`	Quaternion orientation
`covariance`	`list[float]`	6x6 covariance matrix (36 elements, row-major)
`frame_id`	`str`	Coordinate frame
`timestamp_ns`	`int`	Timestamp

Method	Returns	Description
`position_variance()`	`list[float]`	Diagonal elements [0,0], [1,1], [2,2] — position uncertainty (x, y, z)
`orientation_variance()`	`list[float]`	Diagonal elements [3,3], [4,4], [5,5] — orientation uncertainty (roll, pitch, yaw)

TwistWithCovariance

Twist with uncertainty estimate (6x6 covariance matrix, row-major).

# simplified
twc = TwistWithCovariance(
    linear_x=0.5, linear_y=0.0, linear_z=0.0,
    angular_x=0.0, angular_y=0.0, angular_z=0.1,
    frame_id="base_link",
)
twc.covariance = [0.01] * 36

Field	Type	Description
`linear_x`, `linear_y`, `linear_z`	`float`	Linear velocity
`angular_x`, `angular_y`, `angular_z`	`float`	Angular velocity
`covariance`	`list[float]`	6x6 covariance matrix (36 elements, row-major)
`frame_id`	`str`	Coordinate frame
`timestamp_ns`	`int`	Timestamp

Method	Returns	Description
`linear_variance()`	`list[float]`	Diagonal elements [0,0], [1,1], [2,2] — linear velocity uncertainty
`angular_variance()`	`list[float]`	Diagonal elements [3,3], [4,4], [5,5] — angular velocity uncertainty