Configuration Guide

This page explains how to configure the ATLAS GUI application through the main configuration file.

Configuration Parameters

Dataset Settings

dataset_type

The type of dataset to load. Supported formats are:

  • REASSEMBLE - For datasets using the REASSEMBLE format

  • RLDS - For RLDS (Reinforcement Learning Datasets) format

  • rosbag - For ROS bag files (.bag) with synchronized image and proprioceptive topics

  • video - For a folder of generic video files (.mp4, .avi, etc.)

  • frames - For a folder of image sequences (.png, .jpg)

dataset_name

Name of your dataset, will be used during logging of annotations. This helps identify which dataset was used when reviewing annotation logs.

fps

Frequency at which the data was recorded and/or at which the data will be synced to. This ensures proper temporal alignment of data streams.

annotation_dir

Directory where the JSON annotation files will be saved.

Note

This applies only when annotations are saved externally as JSON files. REASSEMBLE datasets configured with annotation_storage: h5 write annotations directly back into the source HDF5 file and do not use this directory.

Data Configuration

The data-related keys behave slightly differently depending on the chosen dataset_type. Select the relevant tab below. For complete, ready-to-use configuration files for each format, see Complete Configuration Example.

low_level_keys

List of proprioceptive robot data keys. You should list all available sensor keys here that you want to access during annotation.

Important

You should include the full dictionary path to your desired keys.

Example:

low_level_keys:
  - steps/observation/gripper_position
  - steps/observation/cartesian_position
  - steps/observation/joint_position
camera_keys

List the camera keys that you wish to display in the GUI interface.

Important

You should include the full dictionary path to your desired keys.

Example:

camera_keys:
  - steps/observation/wrist_image_left
  - steps/observation/exterior_image_1_left
  - steps/observation/exterior_image_2_left
color_format

Image color format, either "RGB" or "BGR". Specifies the format of the camera data to ensure proper color display.

annotation_storage

How annotations are persisted. Either "h5" (default) or "json".

  • h5 — annotations are written directly back into the source HDF5 file under the group specified by annotation_group.

  • json — annotations are written to an external JSON file inside annotation_dir, leaving the source data untouched.

annotation_storage: json
annotation_group

Name of the HDF5 group under which annotations are stored when annotation_storage: h5. Defaults to low_level.

annotation_group: low_level
low_level_keys

List of proprioceptive robot data keys. You should list all available sensor keys here that you want to access during annotation.

Important

You should include the full dictionary path to your desired keys.

Example:

low_level_keys:
  - steps/observation/gripper_position
  - steps/observation/cartesian_position
  - steps/observation/joint_position
camera_keys

List the camera keys that you wish to display in the GUI interface.

Important

You should include the full dictionary path to your desired keys.

Example:

camera_keys:
  - steps/observation/wrist_image_left
  - steps/observation/exterior_image_1_left
  - steps/observation/exterior_image_2_left
color_format

Image color format, either "RGB" or "BGR". Specifies the format of the camera data to ensure proper color display.

text_keys

Which text descriptions to load for a given segment.

Example:

text_keys:
  - language_instruction
low_level_keys

List of proprioceptive ROS topics whose messages will be made available during annotation.

Example:

low_level_keys:
  - franka_state_controller/O_T_EE
  - joint_states
  - ft_sensor/ft_compensated_base
camera_keys

List of ROS image topics that you wish to display in the GUI interface.

Example:

camera_keys:
  - cam1
  - cam2
color_format

Image color format, either "RGB" or "BGR". Specifies the format of the camera data to ensure proper color display.

annotation_group

Name of the dictionary entry under which annotations will be saved within the bag’s metadata. Defaults to annotations.

Example:

annotation_group: high_level
stream_mode

If True (default), camera frames are loaded on-demand from the bag to keep memory usage low. Set to False to load all frames into memory at startup — playback will be faster but RAM usage will be much higher.

stream_mode: true
frame_cache_size

Number of recently accessed frames to keep in memory while in streaming mode. Larger values smooth out playback at the cost of more RAM. Defaults to 30.

frame_cache_size: 60
low_level_keys

Leave empty — generic video files do not contain proprioceptive data.

low_level_keys:
camera_keys

Leave empty to auto-detect camera streams from the folder structure, or provide a list of explicit camera names if you have a known multi-camera layout.

camera_keys:
  # - camera           # uncomment for a single named camera
color_format

Image color format, either "RGB" or "BGR". Specifies the format of the camera data to ensure proper color display.

low_level_keys

Leave empty — image folders do not contain proprioceptive data.

low_level_keys:
camera_keys

Leave empty to auto-detect camera streams from the folder structure, or provide a list of explicit camera names if you have a known multi-camera layout.

camera_keys:
  # - camera           # uncomment for a single named camera
  # - left_cam         # uncomment and add entries for a known multi-camera setup
  # - right_cam
color_format

Image color format, either "RGB" or "BGR". Specifies the format of the camera data to ensure proper color display.

Display Settings

default_graphs

Proprioceptive data that you want to have displayed by default each time you load a segment. This allows you to automatically show the most relevant sensor data without manual selection.

Note

This setting has no effect for the video and frames dataset types, since those formats do not carry proprioceptive data. Leave it empty in that case.

Example:

default_graphs:
  - steps/observation/cartesian_position
  - steps/observation/gripper_position

Keyboard Configuration

keys

Keyboard shortcuts for annotation actions. Define custom key bindings for common annotation operations.

Example:

keys:
   play: Space
   previous_segment: Q
   next_segment: E
   toggle_annotation: S
   delete_last_annotation: Backspace
   save_segment_annotation: P
   fast_forward: D
   rewind: A
   fast_forward_small: C
   rewind_small: Z
   jump_to_end: F
ff_value_big

Step size in seconds for the fast_forward / rewind keys (large jumps).

Example:

ff_value_big: 0.1   # 100 ms per press
ff_value_small

Step size in seconds for the fast_forward_small / rewind_small keys (fine-grained jumps).

Example:

ff_value_small: 0.01   # 10 ms per press
action_map

Keyboard number shortcuts for inputting the name of the segmented part during annotation. This allows quick selection of annotation categories using number keys.

Example:

action_map:
   1: Approach
   2: Grasp
   3: Lift
   4: Release
   5: Align
   6: Push
   7: Pull
   8: Nudge
   9: Twist

Complete Configuration Example

Below is a complete example configuration file for each supported dataset format. Select the relevant tab to see the full template you can drop into your own setup.

Tip

Each of the example files shown here is also shipped in the config/ folder of the repository, so you can copy one and edit it directly instead of starting from scratch.

View on GitHub

config/reassemble.yaml
dataset_type: reassemble                  # has to match one of the implemented classes
dataset_name: reassemble
fps: 15

annotation_storage: json                  # 'h5' or 'json'. h5 overwrites the original data with new annots, json saves annots to external json file
annotation_dir: annotations/reassemble/   # used when annotation_storage is 'json'
annotation_group: low_level               # group name in h5 (used when annotation_storage is h5)

low_level_keys:
  - robot_state/compensated_base_force
  - robot_state/compensated_base_torque
  - robot_state/measured_force
  - robot_state/measured_torque
  - robot_state/joint_efforts
  - robot_state/joint_positions
  - robot_state/joint_velocities
  - robot_state/gripper_positions
  - robot_state/pose
  - robot_state/velocity
  
camera_keys:
  - hama1
  - hama2
  # - hand
  # - capture_node-camera-image             # event camera
color_format: "BGR"

default_graphs:
  - robot_state/compensated_base_force
  - robot_state/gripper_positions

keys:
  play: Space
  previous_segment: Q
  next_segment: E
  toggle_annotation: S
  delete_last_annotation: Backspace
  save_segment_annotation: P
  fast_forward: D
  rewind: A
  fast_forward_small: C
  rewind_small: Z
  jump_to_end: F

ff_value_big: 0.1                         # big skip in seconds (100ms)
ff_value_small: 0.01                      # small skip in seconds (10ms)

action_map:
  1: Approach
  2: Grasp
  3: Lift
  4: Release
  5: Align
  6: Push
  7: Pull
  8: Nudge
  9: Twist

View on GitHub

config/rlds.yaml
dataset_type: rlds                      # has to match one of the implemented classes
dataset_name: droid_100
fps: 15                                 # data recorded at 15hz
annotation_dir: annotations/rlds/       # where to save/write annotations

low_level_keys:
  - steps/observation/gripper_position
  - steps/observation/cartesian_position
  - steps/observation/joint_position

camera_keys:
  - steps/observation/wrist_image_left
  - steps/observation/exterior_image_1_left
  - steps/observation/exterior_image_2_left
color_format: "RGB"

text_keys:
  - language_instruction
  # - language_instruction_2
  # - language_instruction_3

# which low level keys will be displayed by default in the gui
default_graphs:
  - steps/observation/cartesian_position
  - steps/observation/gripper_position 

keys:
  play: Space
  previous_segment: Q
  next_segment: E
  toggle_annotation: S
  delete_last_annotation: Backspace
  save_segment_annotation: P
  fast_forward: D
  rewind: A
  fast_forward_small: C
  rewind_small: Z
  jump_to_end: F

ff_value_big: 0.1                       # big skip in seconds (100ms)
ff_value_small: 0.01                    # small skip in seconds (10ms)

action_map:
  1: Approach
  2: Grasp
  3: Lift
  4: Release
  5: Align
  6: Push
  7: Pull
  8: Nudge
  9: Twist

View on GitHub

config/rosbag.yaml
dataset_type: rosbag                      # has to match one of the implemented classes
dataset_name: my_rosbag_dataset
fps: 30
annotation_dir: annotations/rosbag/       # if saving the annotations in json files
annotation_group: high_level               # the name of the dict entry where annots will be saved within the original data

low_level_keys:
  - franka_state_controller/O_T_EE
  - joint_states
  - ft_sensor/ft_compensated_base
  
camera_keys:
  - cam1
  - cam2
  # - /hand
  # - /capture_node-camera-image             # event camera
color_format: "BGR"

default_graphs:
  - franka_state_controller/O_T_EE
  - ft_sensor/ft_compensated_base

keys:
  play: Space
  previous_segment: Q
  next_segment: E
  toggle_annotation: S
  delete_last_annotation: Backspace
  save_segment_annotation: P
  fast_forward: D
  rewind: A
  fast_forward_small: C
  rewind_small: Z
  jump_to_end: F

ff_value_big: 0.1                         # big skip in seconds (100ms)
ff_value_small: 0.01                      # small skip in seconds (10ms)

# Streaming mode (default: True) - loads camera frames on-demand to save RAM
# Set to False to load everything into memory (faster playback, more RAM)
stream_mode: false
frame_cache_size: 60                      # number of frames to cache in streaming mode

action_map:
  1: Approach
  2: Grasp
  3: Lift
  4: Release
  5: Align
  6: Push
  7: Pull
  8: Nudge
  9: Twist

View on GitHub

config/video.yaml
dataset_type: video
dataset_name: video_test
fps: 30                          # typical video fps
annotation_dir: annotations/video/

low_level_keys:                  # empty -- no numerical/sensor data

camera_keys:                     # empty -- auto-detected from folder structure
  # - camera                     # uncomment for single camera with known name
color_format: "BGR"              # OpenCV decodes as BGR

default_graphs:                  # empty -- no plots

keys:
  play: Space
  previous_segment: Q
  next_segment: E
  toggle_annotation: S
  delete_last_annotation: Backspace
  save_segment_annotation: P
  fast_forward: D
  rewind: A
  fast_forward_small: C
  rewind_small: Z
  jump_to_end: F

ff_value_big: 0.5                # bigger skip for video (500ms)
ff_value_small: 0.033            # ~1 frame at 30fps

action_map:
  1: Approach
  2: Grasp
  3: Lift
  4: Release
  5: Align
  6: Push
  7: Pull
  8: Nudge
  9: Twist

View on GitHub

config/frames.yaml
dataset_type: frames
dataset_name: frames_test
fps: 30
annotation_dir: annotations/frames/

low_level_keys:                  # empty -- no numerical/sensor data

camera_keys:                     # empty -- auto-detected from folder structure
  # - camera                     # uncomment for single camera with known name
  # - left_cam                   # uncomment and add entries for known multi-camera setups
  # - right_cam
color_format: "BGR"              # cv2.imread loads as BGR by default

default_graphs:                  # empty -- no plots

keys:
  play: Space
  previous_segment: Q
  next_segment: E
  toggle_annotation: S
  delete_last_annotation: Backspace
  save_segment_annotation: P
  fast_forward: D
  rewind: A
  fast_forward_small: C
  rewind_small: Z
  jump_to_end: F

ff_value_big: 0.1
ff_value_small: 0.01

action_map:
  1: Approach
  2: Grasp
  3: Lift
  4: Release
  5: Align
  6: Push
  7: Pull
  8: Nudge
  9: Twist

See Also