[Documentation] [TitleIndex] [WordIndex

pr2_robot: imu_monitor | pr2_bringup | pr2_camera_synchronizer | pr2_computer_monitor | pr2_controller_configuration | pr2_etherCAT | pr2_run_stop_auto_restart

Package Summary

The PR2 is equipped with a texture projector that can be used to project a texture onto featureless surfaces, allowing their three-dimensional structure to be determined using stereoscopy. The projector operates in a pulsed mode, producing brief (2ms) pulses of light. Cameras that want to see the texture must expose during the projector pulse; other cameras should be expose while the projector is off.

This package contains the pr2_projector_synchronizer node. Based on its dynamically reconfigurable parameters, this node controls the projector pulsing, and sets up triggering of the WGE100 cameras.

System Overview

This section gives an overview of the PR2's camera systems. Some readers may want to skip directly to the following section for a more practical discussion of how to use the robot's cameras, or to the ROS API for a detailed description of the pr2_camera_synchronizer parameters.

Hardware Components

The robot's cameras

The following hardware components are involved in producing vision data on the PR2:

Synchronization Constraints

Synchronization between these pieces of hardware is needed because of system constraints:

Overview of the Camera Systems

Software Components

The variety of hardware components involved implies that a variety of software components are involved in producing camera images:

Working With the WGE100 Cameras on the PR2

The various components involved in PR2 camera synchronization expose a large number of options to the user. This section is designed to highlight the options that the user should be using to configure the cameras on the PR2. All the necessary nodes and controllers to work with the WGE100 cameras are brought up automatically when the pr2 robot is started.

It is not recommended that the user adjust parameters that are not listed below as they are likely to leave the system in a non functioning state.

This section shows how to use the reconfigure_gui to set these parameters, they can be set just as easily using any other dynamic_reconfigure mechanism as demonstrated in these tutorials.

Setting Frame Rates and Projector Modes via the Synchronizer

Frame rates and projector modes should be set using dynamic_reconfigure on the pr2_camera_synchronizer_node. For example:

$ rosrun dynamic_reconfigure reconfigure_gui /camera_synchronizer_node

The synchronizer will make a best-effort attempt at using the rates and modes you requested, but may have to round to the nearest possible rate or use a different mode. In that case, the GUI and parameter will reflect the rates and modes that were actually set.

Other Camera Settings

Many WGE100 settings not managed by the synchronizer can be set directly with the cameras by using dynamic_reconfigure. A detailed list of which parameters can be set in this way without conflicting with the synchronizer can be found below.

For the forearm cameras, the camera node (forearm_camera_l or forearm_camera_r) should be configured directly. For the stereo pairs, the wge100_multi_configurator node (wide_stereo_both or narrow_stereo_both) should be configured; this node controls both cameras of a stereo pair, and will dispatch configuration changes to both underlying camera nodes.

For the wide stereo camera:

$ rosrun dynamic_reconfigure reconfigure_gui /wide_stereo_both

For the narrow stereo camera:

$ rosrun dynamic_reconfigure reconfigure_gui /narrow_stereo_both

For the right forearm camera:

$ rosrun dynamic_reconfigure reconfigure_gui /forearm_camera_r

For the left forearm camera:

$ rosrun dynamic_reconfigure reconfigure_gui /forearm_camera_l

Setting Image Levels

Many image level parameters can be safely set:

Please refer to the wge100_camera documentation for details on what these parameters mean.

Setting Region of Interest

(Region of Interest is currently broken)

The following parameters can be set: width, height, horizontal_binning, vertical_binning, horizontal_offset, vertical_offset, mirror_x, mirror_y, rotate_180.

Please refer to the wge100_camera documentation for details on what these parameters mean.

Note 1: the camera_info stored in the camera is only valid for the region of interest parameters that were used when it was created. The wge100_camera_node will refuse to use camera_info with the wrong width and height, but will not detect changes in the other parameters.

Note 2: if the data rate needed by region of interest settings is too high, the WGE100 camera will fail to stream the images, and you will have to select lower-bandwidth settings.

Image Topics

Images from the wide stereo camera and forearm cameras are published in the wide_stereo, forearm_r and forearm_l namespaces, whether they are textured or not.

To facilitate using the narrow stereo camera in AlternatingProjector mode, textured images from the narrow stereo camera are always published in the narrow_stereo_textured namespace, and untextured images are always published in the narrow_stereo namespace.

Resetting the WGE100 Cameras

Due to unresolved firmware bugs, it may happen that a WGE100 camera will become unresponsive. The unresponsiveness of the camera can be verified by running:

$ rosrun wge100_camera discover lan0
Found camera serial://1800023 name://forearm_l MAC: 00:24:cd:00:00:f0 iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202
Found camera serial://3001038 name://wide_stereo_r MAC: 00:24:cd:00:01:01 iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202
Found camera serial://3001039 name://wide_stereo_l MAC: 00:24:cd:00:00:fc iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202
Found camera serial://2701021 name://narrow_stereo_r MAC: 00:24:cd:00:01:02 iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202
Found camera serial://1800031 name://forearm_r MAC: 00:24:cd:00:00:ea iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202
Found camera serial://2701031 name://narrow_stereo_l MAC: 00:24:cd:00:01:03 iface: lan0 current IP:, PCB rev: C HDL rev: 504 FW rev: 202

If one of the cameras does not show up after a couple of attempts, it may have crashed.

The easiest way to reset all the WGE100 cameras while ROS is running on the PR2 is to use the camera_reset option to true in the camera_synchronizer_node options. This will raise the camera's trigger signal for a few seconds, telling the camera to reset itself. The reset will take about 5-10 seconds.

$ rosrun dynamic_reconfigure dynparam /camera_synchronizer_node camera_reset true

Note: This will only work if the trigger controllers are running.

Alternatively, a single camera can be reset when ROS is not running by using the reconfigure_cam utility in wge100_camera. For example:

$ rosrun wge100_camera reconfigure_cam name://wide_stereo_l

Synchronization Strategy

Projector Modes

In a running PR2, many cameras may be simultaneously in use by different users. Whether the projector should be on at any given time is a combination of the operating modes requested by the user of each camera. The settings of a user's camera depend on whether the projector is on or off. To avoid spurious changes in the settings of one user's camera when another user's camera is reconfigured, the pr2_camera_synchronizer is organized so that there is a master projector_mode setting, and a _trig_mode setting for each camera.

Users request the _trig_mode that their camera should be in, and the synchronizer decides on the projector state based on the current projector_mode. For a given projector_mode, the pr2_camera_synchronizer ensures that the settings of one camera do not depend on the trig_mode of the other cameras. In a typical use of the synchronizer, the projector_mode is set once and for all by a high-level decision, and users can adjust _trig_mode at will.

The synchronizer can be in one of three modes, depending on which strategy it should use:

The recommended operating mode is ProjectorAuto. ProjectorOff can be used if longer exposures are needed or if the projector is deemed too unpleasant. ProjectorOn will most likely not be used in practice.

Trigger Modes

A variety of triggering modes are available for the WGE100 cameras. Because different cameras have different constraints, all triggering modes are not available for all cameras.

Camera Frame Rates

In many cases, the camera frame rate must be some suitable divisor of the projector_rate. When a user sets the frame rate for a camera, the synchronizer will round that rate to the nearest suitable rate, and report the rounded value back to the user via the dynamic_reconfigure mechanism.

The projector_rate is not affected by the camera settings. When it is set, it is simply rounded to the nearest divisor of 1 kHz. Again the rounded value is reported back via the dynamic_reconfigure mechanism.

Projector Waveform

The pr2_camera_synchronizer operates with a standard waveform that repeats after four pulses. The pulses in one period are numbered 1 to 4. The waveform is entirely determined by three parameters:


The timing of the pulses is as follows, where 'T=1/projector_rate' is the average pulse period:

Interaction with the Prosilica Camera

(Not implemented yet.)

To avoid having texture in images taken by the Prosilica camera, the prosilica_projector_inhibit option can be turned on. In this case, an exposure signal from the Prosilica camera directly inhibits firing of the projector. When the projector is inhibited the WGE100 cameras will continue to be triggered as if the projector was active, so some frames that should be textured may be partially textured or not textured at all.

Implementation Limitations

The current implementation has certain timing limitations that may be removed in future versions.

Multiple PR2 Robots

The phase of the camera triggering is set absolutely relative to a ROS time of 0. Hence, if multiple robots have their clocks synchronized with sub-millisecond resolution, and their projector rates match, their projectors will fire synchronously. As a result images that are supposed to be textured will see the texture from both robots, and images that are supposed to be untextured should not see texture from either robot.

On the other hand, the Prosilica camera projector inhibition will not work between robots. Therefore, Prosilica images from one robot may see texture projected by the other, even if prosilica_projector_inhibit is true.



Node to set up triggering of the PR2 forearm cameras, stereo cameras and texture projector. It is configured via dynamic_reconfigure.


Dynamically Reconfigurable Parameters
See the dynamic_reconfigure package for details on dynamically reconfigurable parameters. ~projector_rate (double, default: 60.0) ~projector_pulse_length (double, default: 0.002) ~projector_pulse_shift (double, default: 0.0) ~projector_mode (int, default: 2) ~prosilica_projector_inhibit (bool, default: False) ~stereo_rate (double, default: 30.0) ~wide_stereo_trig_mode (int, default: 4) ~narrow_stereo_trig_mode (int, default: 4) ~forearm_r_rate (double, default: 30.0) ~forearm_r_trig_mode (int, default: 1) ~forearm_l_rate (double, default: 30.0) ~forearm_l_trig_mode (int, default: 1) ~projector_tweak (double, default: 0.0) ~camera_reset (bool, default: False)

2011-11-19 12:30