Skip to content

Creating a Calibration Dataset

Goals

  • Learn what data formats are accepted by TVCal.
  • Modify the input Plex according to your data format.

Introduction

TVCal currently accepts two different dataset formats: rosbags and image directories. The data format that you choose directly affects the way in which your Plex is constructed.

Object Space Considerations

First, verify that the target described in the object space JSON is identifiable by any component that needs calibration (e.g. a camera). Calibration data consists of component observations that contain any information helpful to modeling the system; this usually means a specific calibration target or fiducial that is identifiable in the scene.

Info

Data collection is an art unto itself. Check out the Data Collection documentation to learn how to create a great calibration dataset.

rosbag

rosbags are a highly-flexible format. The various tools used to generate rosbags may store sensor metadata in a variety of ways as there is no defined, uniform way to do so. For this reason, rosbags are treated solely as an observation source; we cannot derive any Plex information due to potential inconsistencies. This means that a Plex must be created from scratch for any system using rosbags.

Accepted rosbag Message Formats

Here are the compatible ROS message formats for each component type:

Component Type Compatible ROS message format
Camera sensor_msgs/Image

Constructing Components

TVCal uses each topic name in the rosbag as a component identifier. When constructing a component, the name field should exactly match the rosbag topic it references.

// rosbag Image topic named "/camera/ir_one"
let name = String::from("/camera/ir_one");

let camera = Component::Camera(Camera::new(
    ...,
    name,
    ...
));
// rosbag Image topic named "/camera/ir_one"
"camera": {
    ...
    "name": "/camera/ir_one",
    ...
}

Image Directories

TVCal can accept flat folder hierarchies of images. It treats each individual folder as a different component stream. This means that there is a 1:1 relationship between every folder and component.

Calibration Data Folder Structure

Accepted Image File Formats

TVCal uses the image Rust library to parse images. We can accept any file format that image can.

Constructing Components

TVCal uses each folder as a potential component identifier. When constructing a component, the name field should exactly match the folder name it references.

// Image folder named "camera_ir_one"
let name = String::from("/camera/ir_one");

let camera = Component::Camera(Camera::new(
    ...,
    name,
    ...
));
// Image folder named "camera_ir_one"
"camera": {
    ...
    "name": "/camera/ir_one",
    ...
}

Deriving Timestamps

Timestamps are taken directly from the filename in units of nanoseconds. If the filename is not a number, the observation is considered to have no time information. Here are examples of correct and incorrect timestamp filenames:

Filename TVCal Timestamp
1.png 1 ns since last epoch
200394872.png 200394872 ns since last epoch
one.png No timestamp (not a number)
A200394872.png No timestamp (not a number)
pic_of_target.png No timestamp (not a number)