rc_visard_driver

Nodelet/node providing a ROS interface to configure a Roboception rc_visard and receive images/poses.

Please also consult the manual for more details: https://doc.rc-visard.com

Installation

On Debian/Ubuntu add the ROS sources and

sudo apt-get install ros-${ROS_DISTRO}-rc-visard-driver

From Source

This rc_visard_driver depends on

• rc_genicam_api
• rc_dynamics_api

The dependencies can also be installed via rosdep.

rosdep install --from-paths rc_visard_driver --ignore-src rc_visard_driver -r -y

Building and installing the package follows the typical ROS catkin workflow.

As an alternative, the cmake build-flow would be something like

mkdir build && cd build
cmake -DCATKIN_BUILD_BINARY_PACKAGE="1" -DCMAKE_INSTALL_PREFIX="/opt/ros/$ROS_DISTRO" -DCMAKE_PREFIX_PATH="/opt/ros/$ROS_DISTRO" -DCMAKE_BUILD_TYPE=Release ../rc_visard_driver
make
make install

Alternatively, instead of the final make install, you can also use make package and sudo dpkg -i install ros-melodic-rc-visard-driver_*.deb.

GenICam GenTL Transport Layer

The rc_visard_driver uses rc_genicam_api for interfacing with the rc_visard sensor via GenICam/GigE Vision and requires a transport layer called a GenTL producer (shared library with the suffix .cti). For convenience rc_genicam_api comes with producers from Baumer for common architectures.

The path to the producer can be set with the GENICAM_GENTL64_PATH environment variable (or GENICAM_GENTL32_PATH for 32 bit systems). If not set, rc_visard_driver will fall back to searching for the Baumer producer where rc_genicam_api is installed.

If the producer .cti can’t be found and you will get an error message like

[ERROR] [1512568083.512790905]: rc_visard_driver: No transport layers found in path /opt/ros/melodic/lib/rc_genicam_api

In this case you need either need to actually install rc_genicam_api properly or set the environment variable when running it. E.g. export:

GENICAM_GENTL64_PATH=/path/to/rc_genicam_api/baumer/Ubuntu-14.04/x86_64

Configuration

Parameters

Parameters to be set to the ROS param server before run-time.

• device: The ID of the device, i.e. Roboception rc_visard sensor. This can be either the

  • serial number, e.g. 02912345

    IMPORTANT: preceed with a colon (:02912345) when passing this on the commandline or setting it via rosparam (see https://github.com/ros/ros_comm/issues/1339). This is not neccessary when specifying it as a string in a launch file.

  • user defined name (factory default is the name of the rc_visard’s model), must be unique among all reachable sensors

  • internal ID, which is generated by the used GenTL producer. Often, this ID contains the MAC address in some way. This ID can change with the implementation of the transport layer.

  See https://github.com/roboception/rc_genicam_api#device-id for more details. By default this parameter is set to rc_visard, which works with one rc_visard with factory settings connected.

• gev_access: The gev_access mode, i.e.:
  • ‘control’ Configuration and streaming with the possibility of other clients to read GenICam parameters. This is the default.
  • ‘exclusive’ Exclusive access to the sensor. This prevents other clients to read GenICam parameters.
  • ‘off’ Switches gev access completely off. The node only streams pose information if switched on.

• max_reconnects: Maximum number of consecutive recovery trials in case the driver lost connection to the device or another error happened, e.g. during streaming data. If 0, no recovery is tried at all. If negative, the driver keeps trying to re-connect forever until a connection is re-established. Default: 5.

• enable_tf: If true then the node subscribes to the rc_visard’s dynamics-pose stream and publishes them on tf. Default: false

• enable_visualization_markers: If true, additional visualization markers are published that visualize the rc_visard’s dynamics state (velocities and accelerations), see /dynamics_visualization_markers topic. Default: false

• autostart_dynamics: If true, the rc_visard’s dynamics module is turned on with this ROS node’s start up. Default: false

• autostart_dynamics_with_slam: If true, the rc_visard’s dynamics module tries to turn on SLAM with this ROS node’s start up. If SLAM is not available (no license) only a warning is printed. Default: false

• autostop_dynamics: If true, the rc_visard’s dynamics module is turned off when this ROS node shuts down. Default: false

• autopublish_trajectory: If true, results of the get_trajectory service calls are automatically published to /trajectory topic. Default: false

Dynamic-reconfigure Parameters

These parameters can be changed during runtime via dynamic reconfigure:

• ptp_enabled: Enable PTP slave (PrecisionTimeProtocol, IEEE1588)

• camera_fps: Frames per second that are published by this nodelet. Publishing frames will be slowed down depending on this setting. Setting it higher than the real framerate of the specific device has no effect.

• camera_exp_auto: If true, then the exposure time is chosen automatically, up to exp_max as maximum. If false, then exp_value is used as exposure time in seconds.

• camera_exp_auto_mode: Auto-exposure mode, i.e. Normal, Out1High or AdaptiveOut1.

• camera_exp_max: Maximum exposure time in seconds if exp_auto is true.

• camera_exp_value: Exposure time in seconds if exp_auto is false.

• camera_gain_value: Gain factor in decibel if exp_auto is false.

• Auto exposure region: Definition of a region in the left image, if the region has zero size or is outside the image, then the full left and right image is used to determine the auto exposure.
  • camera_exp_width: Width of auto exposure region. 0 for whole image.
  • camera_exp_height: Height of auto exposure region. 0 for whole image.
  • camera_exp_offset_x: First column of auto exposure region
  • camera_exp_offset_y: First row of auto exposure region

• depth_acquisition_mode: Can be either SingleFrame or Continuous. Only the first letter will be checked, thus giving S or C is sufficient.

• depth_quality: Quality can be “Low”, “Medium”, “High” and “Full”. Only the first letter will be checked, thus specification of “L”, “M”, “H” or “F” is sufficient. The quality setting effectively downscales the image after the downscale factor as given above:

  • Full does not downscale the image, i.e. factor is 1 (e.g. 1280x960). NOTE: This mode requires the ‘stereo_plus’ license on the rc_visard.
  • High downscales by factor 2 (e.g. 640x480).
  • Medium downscales by factor 4 (e.g. 320x240).
  • Low downscales by factor 6 (e.g. 214x160).

• depth_static_scene: This parameter can be set to true if the scene and camera is static. It only has an effect if quality is either High or Full. If active, input images are accumulated and averaged for 300 ms to reduce noise. This limits the frame rate to a maximum of 3 Hz. The timestamp of the disparity image is taken from the first image that was used for accumulation.

• depth_double_shot: This parameter can be set to true to combine disparity images from two subsequent stereo image pairs. This is meant to be used in conjunction with a projector and ExposureAlternateActive mode.

• depth_fill: Higher numbers fill gaps with measurments with potentielly higher errors.

• depth_seg: Maximum size of isolated disparity regions that will be invalidated, related to full resolution.

• depth_smooth: Switching smoothing of disparities on or off. NOTE: Smoothing requires the ‘stereo_plus’ license on the rc_visard.

• depth_minconf: Minimal confidence. All disparities with lower confidence will be set to invalid.

• depth_mindepth: Minimum depth in meter. All disparities with lower depth will be set to invalid.

• depth_maxdepth: Maximum depth in meter. All disparities with higher depth will be set to invalid.

• depth_maxdeptherr: Maximum depth error in meter. All disparities with a higher depth error will be set to invalid.

• depth_exposure_adapt_timeout: Maximum time in seconds to wait after triggering in SingleFrame modes until auto exposure has finished adjustments.

• out1_mode: Mode for the digital GPIO out1. Possible values are:

  • Low for switching out1 permanently off.
  • High for switching out1 permanently on.
  • ExposureActive for switching out1 on for the exposure time of every image.
  • ExposureAlternateActive for switching out1 on for the exposure time of every second image.

  The value can only be changed if the rc_visard has an IO Control license. The default is ExposureActive.

• out2_mode: Mode for the digital GPIO out2. The functionality is the same as for out1_mode. The default is Low.

For color sensors, the following dynamic-reconfigure parameters are additionally available:

• camera_wb_auto: If true, then white balancing is done automatically. If false, then the red and blue to green ratios can be chosen manually.

• camera_wb_ratio_red: Red to green ratio for color balancing if camera_wb_auto is false.

• camera_wb_ratio_blue: Blue to green ratio for color balancing if camera_wb_auto is false.

Provided Topics

The following topics are provided. The nodelet tries to request only data (e.g., images, poses) from the sensor if there is subscriber to the corresponding topic.

Images, Stereo Data, Point Clouds

• /stereo/left/camera_info (sensor_msgs::CameraInfo)
• /stereo/right/camera_info (sensor_msgs::CameraInfo)
• /stereo/left/camera_param (rc_common_msgs::CameraParam)
• /stereo/right/camera_param (rc_common_msgs::CameraParam)
• /stereo/left/image_rect (sensor_msgs::Image, MONO8)
• /stereo/right/image_rect (sensor_msgs::Image, MONO8)
• /stereo/disparity (stereo_msgs::DisparityImage)
• /stereo/disparity_color (sensor_msgs::Image, RGB8, visually pleasing)
• /stereo/depth (sensor_msgs::Image, TYPE_32FC1)
• /stereo/confidence (sensor_msgs::Image, TYPE_32FC1, values between 0 and 1)
• /stereo/error_disparity (sensor_msgs::Image, TYPE_32FC1)
• /stereo/error_depth (sensor_msgs::Image, TYPE_32FC1)
• /stereo/points2 (sensor_msgs::PointCloud2)

The proprietary CameraParam messages are sent for every image and contain information like the exposure time, gain and values of digital inputs and outputs at the time of image capture.

For color sensors, the following topics are additionally available:

• /stereo/left/image_rect_color (sensor_msgs::Image, format: RGB8)
• /stereo/right/image_rect_color (sensor_msgs::Image, format: RGB8)

There are also topics provided for images where the GPIO out1 is either low or high. These topics are especially useful if out1_mode is set to the special mode ExposureAlternateActive.

• /stereo/left/image_rect_out1_low (sensor_msgs::Image, MONO8)
• /stereo/left/image_rect_out1_high (sensor_msgs::Image, MONO8)
• /stereo/right/image_rect_out1_low (sensor_msgs::Image, MONO8)
• /stereo/right/image_rect_out1_high (sensor_msgs::Image, MONO8)

For color sensors with an IO Control license, the following topics are additionally available:

• /stereo/left/image_rect_color_out1_low (sensor_msgs::Image, format: RGB8)
• /stereo/left/image_rect_color_out1_high (sensor_msgs::Image, format: RGB8)
• /stereo/right/image_rect_color_out1_low (sensor_msgs::Image, format: RGB8)
• /stereo/right/image_rect_color_out1_high (sensor_msgs::Image, format: RGB8)

Dynamic State (i.e. poses, IMU data, etc.)

These topics deliver the rc_visard’s estimated dynamic state such as its position, orientation, and velocity. For these topics to work properly, the rc_visard’s dynamics module must be turned on (see respective service calls or startup-parameters).

• /pose (geometry_msgs/PoseStamped; same data as provided via tf if enable_tf is set to true)
• /pose_ins (geometry_msgs/PoseStamped)
• /pose_rt (geometry_msgs/PoseStamped)
• /pose_rt_ins (geometry_msgs/PoseStamped)
• /dynamics (nav_msgs/Odometry)
• /dynamics_ins (nav_msgs/Odometry)

This topic delivers raw measurements from the on-board IMU sensor:

• /imu (sensor_msgs/Imu)

TF

If the parameter enable_tf is set to true, the node subscribes to the rc_visard’s pose stream (same data published on /pose topic) and publishes them on tf.

Relevant Coordinate Frames

The following coordinate frames are relevant for interpreting the data provided by the rc_visard:

• camera: The pupil’s center of the rc_visard’s left camera. All stereo-camera data such as images and point clouds are given in this frame.
• world: Relevant for navigation applications. The world frame’s origin is located at the origin of the rc_visard’s IMU coordinate frame at the instant when state estimation is switched on. Estimated poses of the rc_visard are given in this frame, i.e. as the rc_visard moves in the world and state estimation is running, the camera frame will change w.r.t. this frame.
• imu: The IMU coordinate frame is inside the rc_visard’s housing. The raw IMU measurements are given in this frame.

Running multiple rc_visard’s in one ros environment

For operating multiple rc_visard’s in one ros environment, each ros node must be started in separate namespaces, e.g., my_visard. As a result, all frame_ids in all ros messages will be prefixed, e.g., to my_visard_world or my_visard_camera.

Services

The following service is offered to trigger stereo matching in SingleFrame mode. It returns an error if the depth_acquisition_mode is Continuous.

• depth_acquisition_trigger

The following services are offered to start, stop, and restart the rc_visard’s dynamic module (which needs to be started for working dynamic-state estimates).

• dynamics_start
• dynamics_restart
• dynamics_stop
• dynamics_start_slam
• dynamics_restart_slam
• dynamics_stop_slam

The trajectory constructed and stored by the rc_slam node can be retrieved by

• slam_get_trajectory

The onboard map of the rc_slam node can be saved on the rc_visard for loading it after a SLAM restart or power cycle:

• slam_save_map
• slam_load_map
• slam_remove_map

The onboard rc_slam node can be “reset” (clears the internal state of the SLAM component, including the trajectory) to free the memory with

• slam_reset

Diagnostics

The rc_visard_driver uses the diagnostics_updater class from the ROS diagnostics stack to regularly publish a DiagnosticStatus Message.

The regular publishing rate can be set via the ~diagnostic_period parameter and defaults to 1 second.

Currently two status are published:

• Device: Information about the device that the driver is connected to. It covers the rc_visard’s serial number, mac address, user-defined GeV ID, and the firmware image version.

• Connection: Status of the current connection between rc_visard_driver and rc_visard. It publishes 4 different messages:

  • Disconnected (Error): The driver is currently not (yet) connected to the sensor and might try to reconnect several times according to the max_reconnects parameter.
  • Idle (Ok): The driver is connected but not publishing any data because no one is subscribed to any.
  • No data (Warning): The driver is connected and required to publish data but itself does not receive any data from the sensor.
  • Streaming (Ok): The driver is connected and properly streaming data.

  The published status values are connection_loss_total, incomplete_buffers_total, image_receive_timeouts_total, and current_reconnect_trial. If not Disconnected, additionally the current ip_address and gev_packet_size are published.

Launching

• Using command line parameters:

  rosrun rc_visard_driver rc_visard_driver _device:=:02912345 _enable_tf:=True _autostart_dynamics:=True _autostop_dynamics:=True
  

• As a nodelet, and in a separate namespace:

  ROS_NAMESPACE=my_visard rosrun nodelet nodelet standalone rc_visard_driver _device:=:02912345
  

Note that in this setup all frame_ids in all ros messages (including tf-messages) will be prefixed with my_visard, e.g., the frame_id of the published camera images will be my_visard_camera, the frame_id of the poses will be my_visard_world, and the frame_id of the Imu messages will be my_visard_imu.

Changelog for package rc_visard_driver

3.3.3 (2022-03-03)

• rc_visard_driver: warn if images can't be published fast enough

3.3.2 (2022-02-18)

• require at least rc_visard firmware version 22.04

3.3.1 (2022-02-18)

• Protected translation from GenICam to CamParam message with mutex to avoid race condition when changing out1_mode

3.3.0 (2022-02-08)

3.2.4 (2021-11-15)

• Add exposure_adapt_timeout parameter
• update parameter description with enum values in square brackets
• fix line_source and add more extra_data to CameraParam

3.2.3 (2021-08-03)

• Fixed building on internal gitlab CI

3.2.2 (2021-08-02)

Changes supporting rc_sgm_producer:

• Extend color format to RGB8
• Using parameter PtpEnable instead of deprecated parameter GevIEEE1588 for controlling PTP

3.2.1 (2021-02-11)

• Only checking for rc_visard as model and not for vendor when detecting devices

3.2.0 (2021-01-28)

• update cmake files for better version handling
• set out1_mode immediately in reconfigure callback to avoid race condition
• default out1_mode is Low

3.1.0 (2020-11-17)

• Change: publish all images on */image_rect topics, meaning don't filter out1 low in alternate mode
• Change: always publish _out1_low and_out1_high topics even if no iocontrol license is available
• debug messages when GenICam params are changed
• rename adaptive_out1_reduction to out1_reduction
• add Out1High camera_exp_auto_mode (requires rc_visard firmware >= 20.11.0)
• add depth_double_shot parameter (requires rc_visard firmware >= 20.11.0)

3.0.5 (2020-10-20)

• add noise, test, adaptive_out1_reduction and brightness to CameraParam extra_data if available

3.0.4 (2020-09-23)

• Removed forgotten debug log output

3.0.3 (2020-09-22)

• Removed parameter disparity range as it will be removed on rc_visard >= 20.10.0 (Use dynamic parameters depth_mindepth and depth_maxdepth for controlling the depth range and coloring of disparity_color images.)

3.0.2 (2020-07-28)

• Fixed filtering out images with projection if stereo matching is used single shot and controls a random dot projector
• Removed parameter depth_median as it will be removed on rc_visard >= 20.10.0
• rc_pick_client: fix grasp markers
• Fixed dockerfiles
• Update readme

3.0.1 (2020-05-14)

3.0.0 (2020-05-13)

• rc_visard_driver depends on rc_common_msgs >= 0.5
• Added estimated noise level of image as extra_data in CameraParam message
• Added dynamic parameter camera_exp_auto_mode with backward compatibility to old rc_visards
• Only update dynamic out1_mode parameter from buffers with intensity images or by polling global nodemap
• Ensure that the alternate active mode is set before publishing images
• Used updating of out1_mode to check for valid connection, even if no buffers are expected.
• dynamic reconfigure parameter out1_mode is automatically updated if changed on sensor
• Disparity range that is used for disparity images and visualization now correctly considers quality setting
• warn if DepthAcquisitionMode is not supported by rc_visard firmware version
• add complete_buffers_total to diagnostics
• Publish rc_common_msgs/CameraParams with every image. This provides information that is missing in CameraInfo, like current exposure time and gain.
• add imu2cam as static tf which is published once the driver is ready - driver checks if cam2imu transform can be retrieved from sensor or if sensor image is too old
  • in first case static tf is published

  - in latter case old behaviour is implemented, i.e. tf is published when subscribed to dynamics stream

• fix empty error message
• change to warning for those logs that inform about missing left images for disp images
• Implemented depth acquisition mode SingleFrameOut1
• Contributors: Christian Emmerich, Felix Ruess, Heiko Hirschmueller

2.7.0 (2019-07-19)

• replaced std_srvs/Trigger with rc_common_msgs/Trigger
• add support for setting exposure region via dynamic_reconfigure

2.6.4 (2019-06-19)

• fix race condition when changing exposure mode from auto to manual
• require ROS version with SteadyTime
• use enums in dynamic reconfigure for easier usage

2.6.3 (2019-06-12)

2.6.2 (2019-06-11)

2.6.1 (2019-05-20)

2.6.0 (2019-05-20)

• auto-start dynamics only on the very first startup
• improve handling and error messages for dynamics streams
• update exposure and gain after switching from auto to manual
• add check if rc_visard ready (genicam feature: RcSystemReady)
• if multipart is available, still send single components per buffer
• refactoring/cleanup

2.5.0 (2019-02-05)

• add parameter for max number of reconnections
• fix: enable driver to try to recover even if the very first time no connection worked out
• add diagnostics
• fix reporting of package size
• Fixed hanging image streams after restart of sensor
• Support for rc_visard firmware v1.5.0 additions (require [StereoPlus]{.title-ref} license)
  • quality full
  • advanced smoothing
• improved driver's auto-connect behavior
• also reapply dynamic_reconfigure params after recovery
• fix projection matrix in published right CameraInfo

2.4.2 (2018-10-29)

2.4.1 (2018-10-29)

• Fixed link error if rc_genicam_api is not installed in a standard directory
• docker images: upgrade packages first

2.4.0 (2018-10-16)

• added [depth_acquisition_mode]{.title-ref} parameter
• added [depth_acquisition_trigger]{.title-ref} service call
• Reduced latency for passing changes of dynamic parameters and topic discriptions to GenICam
• Fixed using wrong disparity range in disparity color publisher
• now depends on rc_genicam_api >= 2.0.0

2.3.0 (2018-08-21)

• read params from parameter server before falling back to current device params
• New image topics ...out1_low and ...out1_high are offered if iocontrol module is available

2.2.1 (2018-07-05)

• Changed to component intensity before changing pixel format for supporting color rc_visards with version >= 1.3.0

2.2.0 (2018-07-03)

• fix out1_mode/out2_mode description and default
• change/add service calls for onboard SLAM module:
  • rename [dynamics_reset_slam]{.title-ref} to [slam_reset]{.title-ref}
  • rename [get_trajectory]{.title-ref} to [slam_get_trajectory]{.title-ref}
  • add [slam_save_map]{.title-ref}, [slam_load_map]{.title-ref} and [slam_remove_map]{.title-ref}
• install Rviz example config file

2.1.1 (2018-06-15)

• Adjusting disparity range to content of disparity image for colored disparity visualization
• Added debug message if left and disparity images cannot be synchronized for creating point clouds
• Implemented parameters for IO control and relaxed time synchronization in case of exposure alternate mode

2.1.0 (2018-04-23)

• add ptp_enabled dynamic_reconfigure parameter (to enable PrecisionTimeProtocol Slave on rc_visard)
• add reset service for SLAM
• README updates
• use 'rc_visard' as default device name (works with one rc_visard with factory settings connected)

2.0.0 (2018-02-27)

• rc_genicam_api and rc_dynamics_api as dependency instead of submodule
• don't reset if datastreams time out
• added get_trajectory service
• Use new statemachine interface Return codes are now strings.
• Add services start_slam, restart_slam and stop_slam
• Publishing dynamics as odometry message
• visualizing dynamics message - angular velocity, linear accelerarion published as marker for visualization
  • cam2imu-transform is published with re-created timestamp
• Contributors: Christian Emmerich, Felix Endres, Felix Ruess, Heiko Hirschmueller

1.2.1 (2018-02-26)

• use rc_genicam_api as dependency instead of including as submodule also remove launchfile, as the device is a required parameter anyway...
• Contributors: Felix Ruess

1.2.0 (2018-02-11)

• Setting default of median to 1 instead of 0, which also means off
• install rc_visard_driver node in package lib dir, so start it with [rosrun rc_visard_driver rc_visard_driver]{.title-ref}

1.1.3 (2017-04-13)

• Added possibility to start as ROS node alternatively to nodelet
• Printing shutdown information to stdout, since ROS log messages just before exit disappear

1.1.2 (2017-04-11)

• The module reconnects to the GigE Vision server in case of errors
• Added reporting enabled componets and missing images

1.1.0 (2017-04-10)

• Implemented setting camera framerate via dynamic reconfigure
• Implementation of dynamic reconfigure parameters for controlling the depth image

1.0.1 (2017-03-16)

• Focal length of disparity image now relates to the size of the disparity image
• Use color for point cloud if color images are available

1.0.0 (2017-03-05)

• Initial release