mbari/tethystales repository overview

⁠Tethys Tales

Tethys Tales replays LRAUV (Long Range Autonomous Underwater Vehicle) mission logs (.nc4) in RViz2. It shows the vehicle in a 3D underwater scene, with telemetry panels. The image contains ROS 2 Humble on Ubuntu 22.04.

The image runs on Linux with an X11 display only.

⁠Features

• Playback: Play, pause, reset and seek. The speed is 0.5 to 50 times real time.
• Underwater scene: Fog, sky, a sea surface with moving ripples, and less light at depth.
• Seafloor: A 25 m grid of Monterey Bay is in the image. If the grid does not cover the whole track, the viewer shows a labelled dummy floor for the track area instead. The dummy floor is not the real seafloor.
• Vehicle model: Moving rudder, elevator and propeller.
• Panels: Vehicle State, Attitude Indicator, Tail Assembly, Mass Position, Playback Control and Track Plot (click the plot to go to that time).
• Track: The full track, a trail behind the vehicle, and an overview line that you can see from far away.
• Saved views: Follow, Overview 3D and Top Down.

⁠Requirements

• Linux with an X11 display, and Docker.
• For an NVIDIA GPU: the NVIDIA driver and the NVIDIA Container Toolkit⁠.

⁠Quick start

1. Pull the image:

   docker pull mbari/tethystales:latest
   

   Copy
2. Let containers use your X11 display:

   xhost +local:docker
   

   Copy
3. Set your log directory. Use an absolute path to a directory that exists:

   LOGS="$HOME/lrauv-logs"
   

   Copy
4. Start the container with the command for your graphics hardware (see below).
5. In the Playback Control panel, click Load. The dialog opens in /mbari/LRAUV, which is your log directory. Select a .nc4 file.
6. To stop, press Ctrl+C in the terminal.
7. Remove the X11 access:

   xhost -local:docker
   

   Copy

⁠NVIDIA GPU

Use this command also on a laptop where an Intel GPU drives the display.

docker run -it --rm \
  --gpus all \
  -e NVIDIA_DRIVER_CAPABILITIES=graphics,utility,compute,display \
  -e __NV_PRIME_RENDER_OFFLOAD=1 \
  -e __GLX_VENDOR_LIBRARY_NAME=nvidia \
  --network host \
  -e DISPLAY -e QT_X11_NO_MITSHM=1 \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -v "${XAUTHORITY:-$HOME/.Xauthority}:/root/.Xauthority:ro" \
  -e ROS_LOCALHOST_ONLY=1 \
  -e TETHYSTALES_LOG_ROOT=/mbari/LRAUV \
  -v "$LOGS:/mbari/LRAUV:ro" \
  mbari/tethystales:latest

If RViz2 does not start on a desktop whose display runs on the NVIDIA GPU, remove the line -e __NV_PRIME_RENDER_OFFLOAD=1.

⁠Intel or AMD GPU (Mesa)

docker run -it --rm \
  --device /dev/dri:/dev/dri \
  --network host \
  -e DISPLAY -e QT_X11_NO_MITSHM=1 \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -v "${XAUTHORITY:-$HOME/.Xauthority}:/root/.Xauthority:ro" \
  -e ROS_LOCALHOST_ONLY=1 \
  -e TETHYSTALES_LOG_ROOT=/mbari/LRAUV \
  -v "$LOGS:/mbari/LRAUV:ro" \
  mbari/tethystales:latest

The image contains the Mesa of Ubuntu 22.04 (23.2 when this image was built). This Mesa can be too old for the newest Intel GPUs, for example Meteor Lake Arc (GLX BadValue errors). Use software rendering on these computers.

⁠Any computer (software rendering)

Software rendering works on all computers, but it is slower.

docker run -it --rm \
  -e LIBGL_ALWAYS_SOFTWARE=1 \
  -e __GLX_VENDOR_LIBRARY_NAME=mesa \
  --network host \
  -e DISPLAY -e QT_X11_NO_MITSHM=1 \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -v "${XAUTHORITY:-$HOME/.Xauthority}:/root/.Xauthority:ro" \
  -e ROS_LOCALHOST_ONLY=1 \
  -e TETHYSTALES_LOG_ROOT=/mbari/LRAUV \
  -v "$LOGS:/mbari/LRAUV:ro" \
  mbari/tethystales:latest

ROS_LOCALHOST_ONLY=1 keeps the ROS 2 traffic on this computer. Without it, a Tethys Tales on another computer in the same ROS domain can send data into your RViz2 (the container uses the host network).

⁠For MBARI users with access to the repository

The source repository is github.com/mbari-org/tethystales⁠. Access is limited to MBARI users. Its script docker/run.sh finds the GPU, tests OpenGL and falls back to software rendering automatically. The repository also has the full documentation and the files to build the image. Without access, use the commands on this page.

⁠Load a log at start

The image starts ros2 launch tethystales tethystales.launch.py. To give launch arguments (name:=value), write this full command after the image name. Keep all the flags of your Quick start command. Replace only its last line.

Load one file. Give the path as the container sees it:

  mbari/tethystales:latest \
  ros2 launch tethystales tethystales.launch.py \
  log_file:=/mbari/LRAUV/path/to/log.nc4

Load by vehicle name and logset name:

  mbari/tethystales:latest \
  ros2 launch tethystales tethystales.launch.py \
  vehicle:=tethys logset:=20250304T211257

The vehicle/logset search needs the MBARI layout in your log directory: <vehicle>/missionlogs/<year>/<date range>/<logset>/*.nc4 or <vehicle>/missionlogs/tmp/Logs/<logset>/*.nc4. If the logset does not exist, the search uses the nearest logset of the same year, if it is at most 24 hours away. The Playback Control panel also has Vehicle and Logset fields.

⁠Launch arguments

To list all launch arguments with their defaults, run this command. It opens no window.

docker run --rm mbari/tethystales:latest ros2 launch tethystales tethystales.launch.py --show-args

The table shows the arguments that people use most. The command above lists all of them.

With a scale other than 1.0, the scene is not to scale.

⁠Environment variables

Add each variable with -e NAME=value before the image name.

⁠In the RViz2 window

• Saved views: Click the Views tab. Expand Saved. Select Follow, Overview 3D or Top Down. Click Load.
• Track Plot: Click the map or the depth plot to go to that time. Turn the mouse wheel to zoom. Double-click to show the full track.
• Text size: Right-click an empty area of a panel. Select 75 % to 200 %, or Apply this size to all Tethys Tales panels.
• Track style: In the Displays panel, use Trajectory Style (track and trail) and Trajectory Overview (overview line).

⁠Troubleshooting

cannot open display or Authorization required: Run xhost +local:docker. Make sure that echo $DISPLAY shows a value, for example :0.

Failed to create an OpenGL context or BadValue:

• NVIDIA: make sure that the NVIDIA Container Toolkit is installed. Use the NVIDIA command with -e __NV_PRIME_RENDER_OFFLOAD=1. On a desktop whose display runs on the NVIDIA GPU, remove that line.
• Other GPUs: use software rendering.
• To see the renderer without a window, replace the last line of your command with mbari/tethystales:latest glxinfo -B. Find OpenGL renderer string. llvmpipe is software rendering.

The interface flickers, is too large, or the 3D view flashes black: Add -e QT_SCALE_FACTOR=1. Use a smaller window.

The Load dialog is empty, or the log is not found:

• Make sure that $LOGS is an absolute path to a directory that exists.
• Give log_file as a container path (/mbari/LRAUV/...).
• To see what the container sees, run docker run --rm -v "$LOGS:/mbari/LRAUV:ro" --entrypoint ls mbari/tethystales:latest /mbari/LRAUV.

The vehicle jumps between two tracks: Another computer sends Tethys Tales data into your RViz2. Keep -e ROS_LOCALHOST_ONLY=1, or set a different -e ROS_DOMAIN_ID=<number>.

Playback is slow: Use the command for your GPU. Set a larger downsample_factor.

⁠Tags

⁠License and contact

• License: MIT.
• Maintainer: Akshay Hinduja, MBARI (Monterey Bay Aquarium Research Institute).
• Source: github.com/mbari-org/tethystales⁠, for MBARI users with access to the repository.
• Monterey Bay bathymetry: MBARI Seafloor Mapping Lab.