Documentation Status

image_common: camera_calibration_parsers | camera_info_manager | image_transport | polled_camera

Package Summary

Documented

image_transport should always be used to subscribe to and publish images. It provides transparent support for transporting images in low-bandwidth compressed formats. Examples (provided by separate plugin packages) include JPEG/PNG compression and Theora streaming video.

image_common: camera_calibration_parsers | camera_info_manager | image_transport | polled_camera

Package Summary

Released Continuous integration Documented

image_transport should always be used to subscribe to and publish images. It provides transparent support for transporting images in low-bandwidth compressed formats. Examples (provided by separate plugin packages) include JPEG/PNG compression and Theora streaming video.

image_common: camera_calibration_parsers | camera_info_manager | image_transport | polled_camera

Package Summary

Released Continuous integration Documented

image_transport should always be used to subscribe to and publish images. It provides transparent support for transporting images in low-bandwidth compressed formats. Examples (provided by separate plugin packages) include JPEG/PNG compression and Theora streaming video.

image_common: camera_calibration_parsers | camera_info_manager | image_transport | polled_camera

Package Summary

Released Continuous integration Documented

image_transport should always be used to subscribe to and publish images. It provides transparent support for transporting images in low-bandwidth compressed formats. Examples (provided by separate plugin packages) include JPEG/PNG compression and Theora streaming video.

Overview

When working with images we often want specialized transport strategies, such as using image compression or streaming video codecs. image_transport provides classes and nodes for transporting images in arbitrary over-the-wire representations, while abstracting this complexity so that the developer only sees sensor_msgs/Image messages.

Specialized transports are provided by plugins. image_transport itself provides only "raw" transport so as not to impose unnecessary dependencies on client packages. Other transports will only be available if they are built on your system. On Ubuntu, the ros-<distro>-base debians include the "compressed" and "theora" transports provided by the image_transport_plugins stack.

Quickstart Guide

image_transport should always be used to publish and subscribe to images. At this basic level of usage, it is very similar to using ROS Publishers and Subscribers. Using image_transport instead of the ROS primitives, however, gives you great flexibility in how images are communicated between nodes.

For complete examples of publishing and subscribing to images using image_transport, see the Tutorials.

C++ Usage

Instead of:

   1 // Do not communicate images this way!
   2 #include <ros/ros.h>
   3 
   4 void imageCallback(const sensor_msgs::ImageConstPtr& msg)
   5 {
   6   // ...
   7 }
   8 
   9 ros::NodeHandle nh;
  10 ros::Subscriber sub = nh.subscribe("in_image_topic", 1, imageCallback);
  11 ros::Publisher pub = nh.advertise<sensor_msgs::Image>("out_image_topic", 1);

Do:

   1 // Use the image_transport classes instead.
   2 #include <ros/ros.h>
   3 #include <image_transport/image_transport.h>
   4 
   5 void imageCallback(const sensor_msgs::ImageConstPtr& msg)
   6 {
   7   // ...
   8 }
   9 
  10 ros::NodeHandle nh;
  11 image_transport::ImageTransport it(nh);
  12 image_transport::Subscriber sub = it.subscribe("in_image_base_topic", 1, imageCallback);
  13 image_transport::Publisher pub = it.advertise("out_image_base_topic", 1);

image_transport publishers advertise individual ROS Topics for each available transport - unlike ROS Publishers, which advertise a single topic. The topic names follow a standard naming convention, outlined below. Note, however, that all code interfaces take only a "base topic" name (to which the transport type is automatically appended); typically you should not directly reference the transport-specific topic used by a particular plugin.

Python Usage

image_transport does not yet support Python, though it is on the Roadmap. If you need to interface a Python node with some compressed image transport, try interposing a republish node.

Known Transport Packages

If you have implemented a new transport option in a public repository and would like to see it added to this list, please email our mailing list.

Library ROS API

ROS Publishers and Subscribers are used to transport messages of any type. image_transport offers publishers and subscribers specialized for images. Because they encapsulate complicated communication behavior, image_transport publishers and subscribers have a public ROS API as well as a C++ code API. Please see the separate code API documentation for C++ usage. The ROS API is documented below.

image_transport Publishers

image_transport publishers are used much like ROS Publishers, but may offer a variety of specialized transport options (JPEG compression, streaming video, etc.). Different subscribers may request images from the same publisher using different transports.

C++: image_transport::Publisher (API), image_transport::CameraPublisher (API)

Published topics

image_transport publishers advertise individual ROS Topics for each available transport - unlike ROS Publishers, which advertise a single topic. The topic names follow a standard naming convention, outlined below. Note, however, that all code interfaces take only a "base topic" name; typically you should not directly reference the transport-specific topic used by a particular plugin.

The raw sensor_msgs/Image is published on the base topic, just as with using a normal roscpp ros::Publisher. If additional plugins are available, they advertise subtopics of the base topic, conventionally of the form <base topic>/<transport name>. For example, using plugins for "compressed" and "theora" transports, with a base topic of /stereo/left/image, the topics would be:

stereo/left/image (sensor_msgs/Image)

  • Base topic, used for "raw" transport. Advertised just as if we used ros::Publisher.
stereo/left/image/compressed (<transport-specific type>)
  • Topic for "compressed" transport.
stereo/left/image/theora (<transport-specific type>)
  • Topic for "theora" transport.
stereo/left/camera_info (sensor_msgs/CameraInfo)
  • (image_transport::CameraPublisher-only) Camera info topic.

Parameters

image_transport publishers have no independent parameters, but plugins are permitted to make use of the Parameter Server for configuration options, e.g. bit rate, compression level, etc. See the plugin package documentation.

Publisher plugin parameters give subscribers hooks to configure the publisher-side encoding to suit the needs on the client side. Lookup therefore occurs in the public namespace defined by <base_topic>, rather than the private namespace of the publishing node. Note that these parameters are a shared resource, controlling the behavior observed by all subscribers to the image topic.

Conventionally, publisher plugin parameters take the following form: <base topic>/<transport name>_image_transport_<parameter name> (type, default: ?)

  • Transport-specific publisher parameter. If the parameter is not found in namespace <base_topic>, the plugin searches up the parameter tree for it before resorting to the default value. This allows you to set defaults on a global, per-camera or per-topic scope.
stereo/compressed_image_transport_jpeg_quality (int, default: 80)
  • An example transport-specific parameter which sets the JPEG quality for "compressed" transport. This setting applies to all images published in the stereo namespace, if not overridden in lower (monocular camera or image base topic) namespaces.

NOTE: This convention was changed in Diamondback, to support using dynamic_reconfigure for plugin parameters.

Publisher plugin parameters should be exposed through dynamic_reconfigure for best visibility and ease of use. Conventionally, they take the following form:

Reconfigurable parameters
<base topic>/<transport name>/<parameter name> (type, default: ?)
  • Transport-specific publisher parameter.
/camera/image/compressed/jpeg_quality (int, default: 80)
  • An example transport-specific parameter which sets the JPEG quality for "compressed" transport for image topic /camera/image.

image_transport Subscribers

image_transport subscribers are used much like roscpp's ros::Subscriber, but may use a specialized transport to receive images.

C++: image_transport::Subscriber (API), image_transport::CameraSubscriber (API)

Subscribed topics

A Subscriber instance is created with a "base topic" name and the name of the transport to use. It subscribes to the transport-specific ROS topic associated with the base topic. For example, if the base topic is /stereo/left/image, the subscribed topics for transports "raw" and "compressed" are respectively:

stereo/left/image (sensor_msgs/Image)

  • Base topic, used for the default "raw" transport. Subscribed just as if we used ros::Subscriber.
stereo/left/image/compressed (<transport-specific type>)
  • Topic for "compressed" transport.
stereo/left/camera_info (sensor_msgs/CameraInfo)
  • (image_transport::CameraSubscriber-only) Camera info topic.

Parameters

~image_transport (string, default: "raw")
  • Name of the transport to use.

If this parameter is not set, the transport from the image_transport::TransportHints argument of image_transport::ImageTransport::subscribe() is used.

image_transport::TransportHints may be used to specify a different namespace for parameter lookup. This is useful to remap ~image_transport into a separate namespace to allow different transports for different image subscriptions. The node writer may even specify a parameter name other than ~image_transport, although this is discouraged for the sake of consistency. Nodes that subscribe to image topics should document what parameter(s) control transport, especially if different from ~image_transport.

Subscriber plugins are permitted to make use of the Parameter Server for configuration options, e.g. video post-processing level. See the plugin package documentation.

Subscriber plugin parameters configure the behavior of one particular subscriber. They affect how the data received is interpreted (decoded). This differs from publisher plugin parameters, which are a shared resource affecting the data sent to all subscribers. The namespace used for parameter lookup is again specified through image_transport::TransportHints, defaulting to the private namespace of the subscribing node.

Conventionally, subscriber plugin parameters take the following form: ~<transport name>_image_transport_<parameter name> (type, default: ?)

  • Transport-specific subscriber parameter.
~foo_image_transport_post_processing_level (int, default: 1)
  • An example (fictitious) transport-specific parameter which sets the post-processing level when using "foo" transport.

NOTE: This convention was changed in Diamondback, to support using dynamic_reconfigure for plugin parameters.

Subscriber plugin parameters should be exposed through dynamic_reconfigure for best visibility and ease of use. Conventionally, they take the following form:

Reconfigurable parameters
~<transport name>/<parameter name> (type, default: ?)
  • Transport-specific subscriber parameter.
~theora/post_processing_level (int, default: 0)
  • An example transport-specific parameter which sets the post-processing level when subscribed using "theora" transport.

Nodes

republish

republish listens on one base image topic (using any transport type, "raw" by default) and republishes the images to another base topic. By default it uses all available publishing plugins; you may optionally specify a single out transport type. "raw" is the name of the default transport, publishing sensor_msgs/Image messages. What other transports are available depends on which plugins are built.

Usage

$ republish in_transport in:=<in_base_topic> [out_transport] out:=<out_base_topic>

Examples

  • Suppose we are publishing images from a robot using the streaming video transport "theora". On an offboard computer we have several nodes listening to the image topic. This setup wastes bandwidth and computation, as each node processes the compressed video into still images independently. Instead we can start a republish node on the offboard computer, streaming the video only to that node for processing into sensor_msgs/Image messages republished to the other nodes:

    $ republish theora in:=camera/image raw out:=camera/image_decompressed
  • The above command is also useful simply to pipe a compressed image topic into a node that can only listen to sensor_msgs/Image (because it uses ros::Subscriber or is written in a language other than C++).

  • If a node publishes images only as sensor_msgs/Image, we can republish it using the full range of transports. Note however that the base topic must be different from the original topic, and this approach entails a slight overhead over using image_transport::Publisher in the original node.

    $ republish raw in:=camera/image out:=camera/image_repub

Subscribed Topics

in (<transport-specific type>)
  • The image base topic to listen on (may actually subscribe to a subtopic).

Published Topics

out (<transport-specific type>)
  • The image base topic to publish to (may also publish subtopics).

Parameters

republish itself does not make use of the Parameter Server. Plugins may read or set plugin-specific parameters, however.

Command-line tools

list_transports

list_transports lists the declared image transport options across all ROS packages and attempts to determine whether they are currently available for use (packages built, plugins able to be loaded properly, etc.).

Usage

$ rosrun image_transport list_transports

Wiki: image_transport (last edited 2012-11-08 21:52:38 by TullyFoote)