CSV Format

Master Annotator accepts CSV (Comma-Separated Values) files as the primary data format. Each file represents a single robot trajectory where every row is one frame (timestep).

Overview

Your CSV file should contain one row per frame of robot motion data. The columns represent measurements at each timestep — joint angles, end-effector positions, timestamps, and any additional sensor readings.

The first row must be a header row containing column names. All subsequent rows are data frames that will be available for annotation.

File Constraints

Column Structure

Joint Angle Columns

These columns contain the rotation values for each joint in your robot arm. Requirements:

• Units: Values must be in radians
• Count: One column per joint (must match your robot configuration's joint count)
• Naming: Any descriptive name works (e.g., joint_1, joint_2, shoulder_pan, elbow_flex)
• Data type: Floating-point numbers

End-Effector Columns

Optional columns for the end-effector (tool tip) position in 3D space:

• Three columns for X, Y, Z coordinates (e.g., ee_x, ee_y, ee_z)
• Units should match your robot's coordinate system (typically meters)
• Used for end-effector visualization in the 3D viewer

Timestamp Columns

If your CSV includes a column with one of the recognized timestamp names, Master Annotator will automatically detect it and calculate the recording FPS. This is used to set the default playback speed in the labeling interface.

Recognized column names (case-insensitive):

• timestamp
• time
• t
• elapsed_time

Values are expected to be in seconds (floating-point). The system computes FPS from the interval between the first two rows.

Additional Columns

Any extra columns in your CSV are preserved and accessible in the labeling interface. Common additional columns include:

• Gripper state (open/closed or continuous value)
• Force/torque sensor readings
• Velocity measurements
• Task state flags
• Camera indices or frame IDs

Example CSV

timestamp,joint_1,joint_2,joint_3,joint_4,joint_5,joint_6,ee_x,ee_y,ee_z,gripper
0.000,0.00,0.52,-1.05,0.00,1.57,0.00,0.45,0.00,0.32,1.0
0.033,0.01,0.53,-1.04,0.01,1.56,0.00,0.45,0.01,0.32,1.0
0.066,0.03,0.55,-1.02,0.02,1.55,0.01,0.44,0.02,0.33,1.0
0.100,0.05,0.58,-0.99,0.03,1.53,0.01,0.44,0.03,0.33,0.8
0.133,0.08,0.62,-0.95,0.05,1.50,0.02,0.43,0.05,0.34,0.5

Validation Rules

During upload, Master Annotator validates your CSV against these rules:

1. Header row required — The first row must contain column names, not numeric data
2. Column count limit — Maximum 100 columns (files with more will be rejected)
3. Column name length — Each header must be 50 characters or fewer
4. File size — Maximum 100 MB (Free), 300 MB (Standard), or 500 MB (Pro & Enterprise)
5. Consistent row length — All rows should have the same number of columns as the header
6. Robot config match — If a robot configuration exists, the CSV must contain the mapped joint angle and end-effector columns

Best Practices

• Sort chronologically — Ensure rows are in time order for correct playback and visualization
• Use descriptive column names — Names like shoulder_pan are clearer than q1 when mapping columns later
• Include timestamps — This enables automatic FPS detection and more accurate playback
• Keep values in radians — The 3D viewer expects radians; convert from degrees before upload if needed
• Remove empty rows — Trailing blank rows may cause unexpected frame counts