melodic noetic   Show EOL distros: 

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.

• ros-pkg

  • image_transport ("raw") - The default transport, sending sensor_msgs/Image through ROS.

  • compressed_image_transport ("compressed") - JPEG or PNG image compression.

  • theora_image_transport ("theora") - Streaming video using the Theora codec.

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:

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.

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:

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.

Nodes

Usage

$ rosrun image_transport 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:

  $ rosrun image_transport 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.

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

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