Software IntegrationROS 2

ZED ROS 2 Wrapper Custom Messages

Open in ClaudeOpen in ChatGPT

All the custom messages used by the ZED ROS 2 Wrapper are defined in the zed-ros2-interfaces repository and are installed along with the zed-msgs package:

sudo apt install ros-<ros2-distro>-zed-msgs

Node Heartbeat

The zed_msgs/Heartbeat message, published on the ~/status/heartbeat topic, is defined as:

# Message to notify that the node is alive to other nodes
# idx of the message
uint64 beat_count
# namespace of the node
string node_ns
# name of the node
string node_name
# full node name
string full_name
# serial number of the input camera
uint32 camera_sn
# data from an svo?
bool svo_mode
# data from simulation?
bool simul_mode

Node Health Status

The zed_msgs/HealthStatusStamped message, published on the ~/status/health topic, is defined as:

# Message to provide information concerning the status of health of the ZED Camera
# Standard Header
std_msgs/Header header
# ZED Camera serial number
uint32 serial_number
# ZED Camera name
string camera_name
# Image quality is degraded
bool low_image_quality
# Environmental light conditions are not optimal
bool low_lighting
# Depth reliability is low
bool low_depth_reliability
# Motion sensors reliability is low
bool low_motion_sensors_reliability
# Scene Illuminance (units 0.1 lux)
int32 scene_illuminance
# Current image is a duplicate of the previous one, even though its timestamp advanced
bool duplicated_image

scene_illuminance requires zed_msgs v5.3 or newer; the value -1 means that the metric is not supported by the connected camera.

duplicated_image requires ZED SDK >= 5.5 and zed_msgs v5.5. It is raised by the ZED SDK when a frame repeats the content of an earlier one under a new timestamp, i.e. a repeating or stalled stream. With an older zed_msgs the node runs as before, without the field.

SVO Status

The zed_msgs/SvoStatus message, published on the ~/status/svo topic, is defined as:

# Message to provide information concerning the status of the SVO playback
# SVO File name
string file_name
# SVO playback status
uint8 status
# SVO playback status constants
uint8 STATUS_PLAYING=0
uint8 STATUS_PAUSED=1
uint8 STATUS_END=2
# SVO frame timestamp
uint64 frame_ts
# SVO playback position
uint32 frame_id
# SVO total number of frames
uint32 total_frames
# SVO loop status
bool loop_active
# SVO loop count
uint32 loop_count
# SVO real-time mode status
bool real_time_mode

Plane Detection result

The zed_msgs/PlaneStamped message, published by the Plane Detection module, is defined as:

# Standard Header
std_msgs/Header header
# Mesh of the plane
shape_msgs/Mesh mesh
# Representation of a plane, using the plane equation ax + by + cz + d = 0
shape_msgs/Plane coefficients
# Normal vector
geometry_msgs/Point32 normal
# Center point 
geometry_msgs/Point32 center
# Plane pose relative to the global reference frame
geometry_msgs/Transform pose
# Width and height of the bounding rectangle around the plane contours
float32[2] extents
# The polygon bounds of the plane
geometry_msgs/Polygon bounds

Depth information

The zed_msgs/DepthInfoStamped message is defined as:

# Standard Header
std_msgs/Header header
# Minimum measured depth
float32 min_depth
# Maximum measured depth
float32 max_depth

Positional Tracking status

The zed_msgs/PosTrackStatus message is defined as:

# CONSTANTS
uint8 OK = 0
uint8 UNAVAILABLE = 1
uint8 INSUFFICIENT_FEATURES = 2
uint8 LOOP_CLOSED = 1
uint8 SEARCHING = 2
uint8 OFF = 3
uint8 INITIALIZING = 4
uint8 KNOWN_MAP = 5
uint8 MAP_UPDATE = 6
uint8 LOST = 7
uint8 NOT_ENOUGH_MEMORY_FOR_TRACKING = 8
# ODOMETRY_STATUS
# Represents the current state of Visual-Inertial Odometry (VIO) tracking between the previous frame and the current frame.
# OK - The positional tracking module successfully tracked from the previous frame to the current frame.
# UNAVAILABLE - The positional tracking module cannot track the current frame.
# INSUFFICIENT_FEATURES - The positional tracking failed to track the current frame because it could not find enough features.
uint8 odometry_status
# SPATIAL_MEMORY_STATUS
# Represents the current state of camera tracking in the global map.
# OK - Deprecated: This state is no longer in use for GEN_3.
# LOOP_CLOSED - Displayed whenever the system has found a loop closure, relocalized within the area map or corrected after a sudden localization loss.
# SEARCHING - Deprecated: This state is no longer in use for GEN_3.
# OFF - Displayed when the spatial memory is turned off.
# INITIALIZING - Displayed until the camera has acquired enough memory (Initial Area Mapping) or has found its first loop closure and is localized in the loaded area map (Lifelong Mapping/Localization). Users need to keep moving the camera for it to get updated.
# KNOWN_MAP - Displayed when the camera is localized within the loaded area map.
# MAP_UPDATE - Displayed when the robot is mapping (Initial Area Mapping) or when the robot is getting out of the area map bounds (Lifelong Mapping). Displayed as "Tracking" when in exploratory mode with SLAM engaged.
# LOST - Displayed when localization cannot operate anymore (camera completely obstructed, sudden localization jumps after being localized) in Mapping/Localization modes. It can also include the case where the camera jumps or is located out of map bounds in Localization mode. This should be an indicator for users to stop the robot.
# NOT_ENOUGH_MEMORY_FOR_TRACKING - Displayed when there is not enough memory to continue tracking.
uint8 spatial_memory_status
# Pose confidence in the range [0,100], where 0 means that tracking is lost.
# It is filled only by `POSITIONAL_TRACKING_MODE::GEN_3` and stays at -1 until the first pose is retrieved.
int32 pose_confidence
# Deprecated
uint8 status

The pose_confidence field is published on ~/pose/status and requires ZED SDK >= 5.4 and zed_msgs v5.5. It is also reported as Pose confidence in the node diagnostic.

GNSS Fusion status

The zed_msgs/GnssFusionStatus message, published on the ~/pose/filtered/status topic, is defined as:

# GNSS_FUSION_STATUS
# Represents the current state of GNSS fusion for global localization.
# OK - The GNSS fusion module is calibrated and working successfully.
# OFF - The GNSS fusion module is not enabled.
# CALIBRATION_IN_PROGRESS - Calibration of the GNSS/VIO fusion module is in progress.
# RECALIBRATION_IN_PROGRESS- Re-alignment of GNSS/VIO data is in progress, leading to potentially inaccurate global position.
uint8 OK = 0
uint8 OFF = 1
uint8 CALIBRATION_IN_PROGRESS = 2
uint8 RECALIBRATION_IN_PROGRESS = 3
uint8 gnss_fusion_status

Object Detection and Body Tracking results

The Object Detection and the Body Tracking modules publish data on the detected objects and body topics by using the same custom message.

The zed_msgs/ObjectsStamped message is defined as:

# Standard Header
std_msgs/Header header
# Array of `object_stamped` topics
zed_msgs/Object[] objects

where zed_msgs/Object is defined as:

# Object label
string label
# Object label ID
int16 label_id
# Object sub-class label (Only for the `MULTI_CLASS_BOX` model)
string sublabel
# Object confidence level (1-99)
float32 confidence
# Object 3D centroid position
float32[3] position
# Position covariance
float32[6] position_covariance
# Object 3D velocity
float32[3] velocity
# Is Object tracking available?
bool tracking_available
# Tracking state
# 0 -> OFF (object not valid)
# 1 -> OK
# 2 -> SEARCHING (occlusion occurred, trajectory is estimated)
# 3 -> TERMINATE (This is the last searching state of the track. The track will be deleted in the next frame).
int8 tracking_state
# Action state
# 0 -> IDLE
# 2 -> MOVING
int8 action_state
# 2D Bounding box projected to the Camera image
zed_msgs/BoundingBox2Di bounding_box_2d
# 3D Bounding box in world frame
zed_msgs/BoundingBox3D bounding_box_3d
# 3D dimensions (width, height, length)
float32[3] dimensions_3d
# =======================================
#  Person Head Detection specific fields
# =======================================
# 2D Bounding box projected to Camera image of the person head
zed_msgs/BoundingBox2Df head_bounding_box_2d
# 3D Bounding box in world frame of the person head
zed_msgs/BoundingBox3D head_bounding_box_3d
# 3D position of the centroid of the person head
float32[3] head_position
# ===============================
#  Body Tracking specific fields
# ===============================
# Is skeleton available?
bool skeleton_available
# Skeleton format
# 0 -> POSE_18
# 1 -> POSE_34
# 2 -> POSE_38
# 3 -> POSE_70
int8 body_format
# 2D Person skeleton projected to Camera image
zed_msgs/Skeleton2D skeleton_2d
# 3D Person skeleton in world frame
zed_msgs/Skeleton3D skeleton_3d

And all the submessages are defined as following:

zed_msgs/BoundingBox2Df:

#      0 ------- 1
#      |         |
#      |         |
#      |         |
#      3 ------- 2
zed_msgs/Keypoint2Df[4] corners

zed_msgs/BoundingBox2Di:

#      0 ------- 1
#      |         |
#      |         |
#      |         |
#      3 ------- 2
zed_msgs/Keypoint2Di[4] corners

zed_msgs/BoundingBox3D:

#      1 ------- 2
#     /.        /|
#    0 ------- 3 |
#    | .       | |
#    | 5.......| 6
#    |.        |/
#    4 ------- 7
zed_msgs/Keypoint3D[8] corners

zed_msgs/Keypoint2Df:

float32[2] kp

zed_msgs/Keypoint2Di:

uint32[2] kp

zed_msgs/Keypoint3D:

float32[3] kp

zed_msgs/Skeleton2D:

# Skeleton joints
zed_msgs/Keypoint2Df[70] keypoints

zed_msgs/Skeleton3D:

# Skeleton joints
zed_msgs/Keypoint3D[70] keypoints