Configuration & Usage
ROS 2 Nodes and Utilities
vizionsdk_ros2 includes these main executables:
| Executable | Description |
|---|---|
vizionsdk_camera_node | Opens a VizionSDK camera and publishes IMU data, optional image data, camera calibration, camera status, and ISP controls. |
list_devices | Lists connected VizionSDK cameras and available device indexes. |
yuv422_to_bgr_node | Converts uyvy or yuv422_yuy2 image topics to bgr8 for ROS tools that cannot display packed YUV422 directly. |
Topics
| Topic | Message Type | Description |
|---|---|---|
imu/data | sensor_msgs/msg/Imu | IMU acceleration, gyro, and optional ISPU orientation data. |
image_raw | sensor_msgs/msg/Image | Uncompressed image data for raw formats. |
image_raw/compressed | sensor_msgs/msg/CompressedImage | Compressed image data for MJPG. |
camera_info | sensor_msgs/msg/CameraInfo | Camera intrinsics when VxGetIntrinsics succeeds. |
camera/status | diagnostic_msgs/msg/DiagnosticArray | Current exposure, gain, and selected ISP control status. |
Integrate With Customer ROS 2 Nodes
vizionsdk_camera_node acts as the bridge between VizionSDK cameras and the ROS 2 graph. Customer nodes do not need to call VizionSDK directly if they only need ROS 2 image, IMU, camera info, or status data.
Typical integration patterns are:
| Customer Need | Subscribe To |
|---|---|
| IMU acceleration, gyro, and orientation | imu/data |
| Raw uncompressed frames | image_raw |
| MJPG compressed frames | image_raw/compressed |
| Camera calibration | camera_info |
| Current exposure, gain, and ISP status | camera/status |
Customer nodes can also adjust supported ISP controls by setting parameters on the running camera node:
ros2 param set /vizionsdk_camera isp.exposure_time 8000
Show Launch Arguments
Show all launch arguments and descriptions:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py --show-args
Key Parameters
| Parameter | Default | Description |
|---|---|---|
device_index | 0 | VizionSDK camera index from list_devices. |
publish_imu | true | Enable IMU publishing. |
publish_status | true | Enable camera status publishing. |
status_rate_hz | 1.0 | Camera status publishing rate. |
imu_rate_hz | 100.0 | IMU polling and publishing rate. |
imu_mode | ispu | SDK IMU mode: ispu, self_test, or disable. |
imu_self_test_mode | normal | SDK IMU self-test mode: normal, positive, negative, or not_allowed. |
publish_ispu_orientation | true | Include ISPU orientation in IMU messages when available. |
acceleration_unit | mg | SDK acceleration unit before ROS conversion: mg, g, m/s^2, or raw. |
gyro_unit | deg/s | SDK gyro unit before ROS conversion: deg/s, rad/s, or raw. |
imu_frame_id | vizion_imu_link | IMU message frame ID. |
publish_image | false | Enable image publishing. |
image_format | auto | Select the camera image format: auto, YUY2, UYVY, NV12, MJPG, BGRA, BGRX, BGR, RGB16, or RGB. |
image_width | 0 | Select the camera image width. 0 accepts any width. |
image_height | 0 | Select the camera image height. 0 accepts any height. |
image_framerate | 0 | Select the camera format frame rate. 0 accepts any frame rate. |
image_timeout_ms | 1000 | SDK image capture timeout in milliseconds. |
image_frame_id | vizionsdk_camera_optical_frame | Image and camera_info frame ID. |
Image Mode Selection
Use list_devices --formats to check the image modes supported by each connected camera:
ros2 run vizionsdk_ros2 list_devices --formats
Then use image_format, image_width, image_height, and image_framerate to select the camera mode. These parameters are matched against the formats reported by VizionSDK. If a parameter is set to 0, it is treated as a wildcard.
Select an MJPG mode:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
publish_image:=true \
image_format:=MJPG \
image_width:=1920 \
image_height:=1080 \
image_framerate:=30
Select a raw BGR mode:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
publish_image:=true \
image_format:=BGR \
image_width:=1280 \
image_height:=720 \
image_framerate:=30
Use wildcard width, height, or frame rate when any matching value is acceptable:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
publish_image:=true \
image_format:=MJPG \
image_width:=0 \
image_height:=0 \
image_framerate:=0
image_rate_hz is separate from camera mode selection. It controls how often the ROS 2 node publishes image messages. The default value 0.0 uses the selected camera format frame rate.
Multiple Cameras
Each vizionsdk_camera_node instance opens one VizionSDK camera selected by device_index. Multiple cameras can be used in the same ROS 2 system when each node opens a different device_index.
Run list_devices first and assign one camera index to each node:
ros2 run vizionsdk_ros2 list_devices
Use a unique node_name for each camera instance:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
node_name:=vizionsdk_camera_0 \
device_index:=0
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
node_name:=vizionsdk_camera_1 \
device_index:=1
Do not run two camera nodes against the same device_index. Only one node should own a camera device at a time.
The default launch file publishes fixed topic names such as imu/data, image_raw, image_raw/compressed, camera_info, and camera/status. If multiple camera nodes run in the same ROS namespace, their topic data will share the same topic names.
For multi-camera applications, launch each camera in a separate namespace or add remappings in a custom launch file so downstream nodes can subscribe to each camera independently.
For example, a custom ROS 2 launch file can start the same executable in separate namespaces such as /camera0 and /camera1. Downstream nodes can then subscribe to /camera0/image_raw, /camera1/image_raw, /camera0/imu/data, and /camera1/imu/data separately.
ISP Controls
All SDK ISP controls exposed by vizionsdk_ros2 can be set at launch. Replace the ROS parameter dot with an underscore for the launch argument name. For example, isp.exposure_time becomes isp_exposure_time.
The default value for every ISP launch argument is -1, which leaves the current SDK value unchanged.
Set ISP exposure controls at launch:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
isp_exposure_mode:=0 \
isp_exposure_time:=8000 \
isp_exposure_gain:=4
Set other ISP controls the same way:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
isp_brightness:=8 \
isp_whitebalance_temperature:=4500 \
isp_jpeg_quality:=90
Set an ISP control while the node is running:
ros2 param set /vizionsdk_camera isp.exposure_time 8000
Read current exposure and gain status:
ros2 topic echo /camera/status
Supported ISP Parameters
| Parameter | Launch Argument |
|---|---|
isp.brightness | isp_brightness |
isp.contrast | isp_contrast |
isp.saturation | isp_saturation |
isp.whitebalance_mode | isp_whitebalance_mode |
isp.whitebalance_temperature | isp_whitebalance_temperature |
isp.exposure_mode | isp_exposure_mode |
isp.exposure_time | isp_exposure_time |
isp.exposure_min_time | isp_exposure_min_time |
isp.exposure_max_time | isp_exposure_max_time |
isp.exposure_gain | isp_exposure_gain |
isp.gamma | isp_gamma |
isp.sharpness | isp_sharpness |
isp.backlight_compensation | isp_backlight_compensation |
isp.special_effect_mode | isp_special_effect_mode |
isp.denoise | isp_denoise |
isp.flip_mode | isp_flip_mode |
isp.pan | isp_pan |
isp.tilt | isp_tilt |
isp.zoom | isp_zoom |
isp.flick_mode | isp_flick_mode |
isp.jpeg_quality | isp_jpeg_quality |
isp.trigger_mode | isp_trigger_mode |
isp.ehdr_mode | isp_ehdr_mode |
isp.ehdr_exposure_min_number | isp_ehdr_exposure_min_number |
isp.ehdr_exposure_max_number | isp_ehdr_exposure_max_number |
isp.ehdr_ratio_min | isp_ehdr_ratio_min |
isp.ehdr_ratio_max | isp_ehdr_ratio_max |
isp.ehdr_atm_weight | isp_ehdr_atm_weight |
isp.ehdr_atm_max | isp_ehdr_atm_max |
YUV422 Viewing
RViz may report unsupported image encoding uyvy when the selected camera format is packed YUV422. Use MJPG, select an RViz-friendly raw format such as BGR, BGRA, or RGB, or convert the YUV422 topic to bgr8.
Start the camera with UYVY:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
publish_imu:=false \
publish_image:=true \
image_format:=UYVY
Start the converter in another terminal:
ros2 run vizionsdk_ros2 yuv422_to_bgr_node --ros-args \
-p input_topic:=/image_raw \
-p output_topic:=/image_raw/bgr
Subscribe RViz or rqt_image_view to image_raw/bgr. The original image_raw topic remains uyvy for applications that need the camera raw format.
IMU Self-Test
Use SDK self-test mode by setting imu_mode:=self_test and selecting a self-test direction:
ros2 launch vizionsdk_ros2 vizionsdk_camera.launch.py \
imu_mode:=self_test \
imu_self_test_mode:=positive
imu_self_test_mode accepts normal, positive, negative, or not_allowed.