[Documentation] [TitleIndex] [WordIndex] 

Contents

  1. Troubleshooting
  2. Install or build rviz
    1. Install from debian repository
  3. Startup
  4. Displays
    1. Adding a new display
    2. Display Properties
    3. Display Status
    4. Moving Displays
    5. Built-in Display Types
  5. Configurations
    1. 0.4 and above
    2. 0.3 and below
  6. Views Panel
    1. The different camera types
      1. Orbital Camera (default)
      2. FPS (first-person) Camera
      3. Top-down Orthographic
      4. XY Orbit
      5. Third Person Follower
    2. Views
  7. Coordinate Frames
    1. The Fixed Frame
    2. The Target Frame
  8. Tools
    1. Move Camera (Keyboard shortcut: m)
    2. Select (Keyboard shortcut: s)
    3. 2D Nav Goal (Keyboard shortcut: g)
    4. 2D Pose Estimate (Keyboard shortcut: p)
  9. Time
  10. Stereo
  11. Plugins

Troubleshooting

If you're running into problems and have not seen the answer below, try the Troubleshooting Page

Install or build rviz

Obviously you don't need both and should prefer the install:

Install from debian repository

Until fuerte: 

sudo apt-get install ros-fuerte-visualization

From groovy on: 

sudo apt-get install ros-groovy-rviz
# or
sudo apt-get install ros-hydro-rviz
# or
sudo apt-get install ros-indigo-rviz
# or
sudo apt-get install ros-kinetic-rviz
# or
sudo apt-get install ros-melodic-rviz
# or
sudo apt-get install ros-noetic-rviz

Startup

You might have to run a line such as 

source /opt/ros/indigo/setup.bash
roscore &

Then start the visualizer: 

rosrun rviz rviz

When rviz starts for the first time, you will see an empty window: initial_startup.png

The big black thing is the 3D view (empty because there is nothing to see). On the left is the Displays list, which will show any displays you have loaded. Right now it just contains the global options and the time view, which I'll get to later. On the right are some of the other panels, described below.

Displays

A display is something that draws something in the 3D world, and likely has some options available in the displays list. An example is a point cloud, the robot state, etc.

Adding a new display

To add a display, click the Add button at the bottom:

add_display_button.png

This will pop up the new display dialog:

new_display_dialog.png

The list at the top contains the display type. The type details what kind of data this display will visualize. The text box in the middle gives a description of the selected display type. Finally, you must give the display a unique name. If you have, for example, two laser scanners on your robot, you might create two "Laser Scan" displays named "Laser Base" and "Laser Head".

Display Properties

Each display gets its own list of properties. For example:

display_properties_example.png

Display Status

New in 0.4

Each display gets its own status to help let you know if everything is OK or not. The status can be one of 4: OK, Warning, Error and Disabled. The status is indicated in the display's title by the background color, as well as in the Status category that you can see if the display is expanded:

displays_with_all_statuses.png

The Status category also expands to show specific status information. This information is different for different displays, and the messages should be self explanatory.

Moving Displays

You can move a display up or down in the list with the arrow buttons to the right of the Add/Remove buttons: move_display.png

Built-in Display Types

Name

Description

Messages Used

Axes

Displays a set of Axes

Effort

Shows the effort being put into each revolute joint of a robot.

sensor_msgs/JointStates

Camera

Creates a new rendering window from the perspective of a camera, and overlays the image on top of it.

sensor_msgs/Image, sensor_msgs/CameraInfo

Grid

Displays a 2D or 3D grid along a plane

Grid Cells

Draws cells from a grid, usually obstacles from a costmap from the navigation stack.

nav_msgs/GridCells

Image

Creates a new rendering window with an Image. Unlike the Camera display, this display does not use a CameraInfo. Version: Diamondback+

sensor_msgs/Image

InteractiveMarker

Displays 3D objects from one or multiple Interactive Marker servers and allows mouse interaction with them. Version: Electric+

visualization_msgs/InteractiveMarker

Laser Scan

Shows data from a laser scan, with different options for rendering modes, accumulation, etc.

sensor_msgs/LaserScan

Map

Displays a map on the ground plane.

nav_msgs/OccupancyGrid

Markers

Allows programmers to display arbitrary primitive shapes through a topic

visualization_msgs/Marker, visualization_msgs/MarkerArray

Path

Shows a path from the navigation stack.

nav_msgs/Path

Point

Draws a point as a small sphere.

geometry_msgs/PointStamped

Pose

Draws a pose as either an arrow or axes.

geometry_msgs/PoseStamped

Pose Array

Draws a "cloud" of arrows, one for each pose in a pose array

geometry_msgs/PoseArray

Point Cloud(2)

Shows data from a point cloud, with different options for rendering modes, accumulation, etc.

sensor_msgs/PointCloud, sensor_msgs/PointCloud2

Polygon

Draws the outline of a polygon as lines.

geometry_msgs/Polygon

Odometry

Accumulates odometry poses from over time.

nav_msgs/Odometry

Range

Displays cones representing range measurements from sonar or IR range sensors. Version: Electric+

sensor_msgs/Range

RobotModel

Shows a visual representation of a robot in the correct pose (as defined by the current TF transforms).

TF

Displays the tf transform hierarchy.

Wrench

Draws a wrench as arrow (force) and arrow + circle (torque)

geometry_msgs/WrenchStamped

Oculus

Renders the RViz scene to an Oculus headset

Configurations

Different configurations of displays are often useful for different uses of the visualizer. A configuration useful for a full PR2 is not necessarily useful for a test cart, for example. To this end, the visualizer lets you load and save different configurations.

A configuration contains:

Note: With RViz for Groovy the configuration file format has changed, from .vcg/INI to .rviz/YAML, probably also the internal config mechanism. Unfortunately "the RViz in Groovy is not backwards compatible" (related question). So there is no way of opening or converting old .rviz config files in Groovy's RViz.

0.4 and above

The global/local configs (referenced below) have been removed, in favor of a "Recent Configs" menu:

recent_configs.png

0.3 and below

There are also some built-in configurations available:

global_configs.png

If you save a config in the default folder, it will also show up in the "Local Configs" list:

local_configs.png

Views Panel

There are a number of different camera types available in the visualizer, and the list will grow as time goes on:

camera_types.png

Camera types consist both of different ways of controlling the camera and different types of projection (Orthographic vs. Perspective).

The different camera types

Orbital Camera (default)

The orbital camera simply rotates around a focal point, while always looking at that point. The focal point is visualized as a small disc while you're moving the camera:

focal_point.png

Controls

FPS (first-person) Camera

The FPS camera is a first-person camera, so it rotates as if you're looking with your head.

Controls

Top-down Orthographic

The top-down orthographic camera always looks down along the Z axis (in the robot frame), and is an orthographic view which means things do not get smaller as they get farther away.

Controls

XY Orbit

Same as the orbital camera, with the focus point restricted to the XY plane.

Controls

See orbital camera.

Third Person Follower

The camera maintains a constant viewing angle towards the target frame. In contrast to XY Orbit the camera turns if the target frame yaws. This could be handy if you are doing 3D mapping of a hallway with corners for example.

Controls

See orbital camera.

Views

The views panel also lets you create different named views, which are saved and can be switched between. A view consists of a target frame, camera type and camera pose. You can save a view by clicking the Save Current button.

views.png

A view consists of:

Views are saved per user, not in the config files.

Coordinate Frames

rviz uses the tf transform system for transforming data from the coordinate frame it arrives in into a global reference frame. There are two coordinate frames that are important to know about in the visualizer. Here is a video that explains them both:

The Fixed Frame

The more-important of the two frames is the fixed frame. The fixed frame is the reference frame used to denote the "world" frame. This is usually the "map", or "world", or something similar, but can also be, for example, your odometry frame.

If the fixed frame is erroneously set to, say, the base of the robot, then all the objects the robot has ever seen will appear in front of the robot, at the position relative to the robot at which they were detected. For correct results, the fixed frame should not be moving relative to the world.

If you change the fixed frame, all data currently being shown is cleared rather than re-transformed.

The Target Frame

The target frame is the reference frame for the camera view. For example, if your target frame is the map, you'll see the robot driving around the map. If your target frame is the base of the robot, the robot will stay in the same place while everything else moves relative to it.

Tools

The visualizer has a number of tools you can use on the toolbar:

Move Camera (Keyboard shortcut: m)

The Move Camera tool is the default tool. When this is selected, the current View gets to do its thing when you click inside the 3d view.

Select (Keyboard shortcut: s)

The Select tool allows you to select items being displayed in the 3D view. It supports single-point selection as well as click/drag box selection.

selection_highlight.png selection_selected.png

You can add to a selection with the Shift key, and remove from the selection with the Ctrl key. If you want to move the camera around while selecting without switching back to the Move Camera tool you can hold down the Alt key.

The f key will focus the camera on the current selection.

2D Nav Goal (Keyboard shortcut: g)

This tool lets you set a goal sent on the "goal" ROS topic. Click on a location on the ground plane and drag to select the orientation:

set_goal.png

This tool works with the navigation stack.

2D Pose Estimate (Keyboard shortcut: p)

This tool lets you set an initial pose to seed the localization system (sent on the "initialpose" ROS topic). Click on a location on the ground plane and drag to select the orientation:

set_pose.png

This tool works with the navigation stack.

Time

The Time panel is mostly useful when running in a simulator: it allows you to see how much ROS Time time has passed, vs. how much "Wall Clock" (aka real) time has passed.

The time panel also lets you reset the visualizer's internal time state -- this causes a reset of all the displays, as well as a reset of tf's internal cache of data.

time.png

If you are not running in simulation, the time panel is mostly useless. In most cases it can be closed and you will probably not even notice (other than having a bit more screen real estate for the rest of rviz).

Stereo

Rviz can render in 3D stereo if you have a graphics card, monitor, and glasses that support that. You can read how to set this up here.

Plugins

rviz is setup so that new displays can be added through plugins. In fact, even the built-in displays are loaded through the "default" plugin. The end result for you, the user, is that there is a way to load/unload plugins from the UI. (Note that as of this commit, all plugins are loaded automatically - there is no more UI.) If you select the Plugins->Manage... menu item, it will pop up a dialog letting you manage loading/unloading plugins:

manage_plugins.png

If you unload a plugin which has displays active, they will no longer display anything, but will keep their settings:

unloaded_plugin.png

If you're a programmer and are looking to write a plugin, take a look at the plugin tutorials: Plugins: New Display Type , Plugins: New Dockable Panel and Plugins: New Tool Type

2022-05-28 13:01