Data Collection

High-quality training data is essential for creating effective deep learning autopilots. Donkeycar stores driving data in tubs - directories containing sensor readings, images, and control inputs.

What is a Tub?

A tub is Donkeycar’s data storage format that records:

Camera images (as JPG files)
Steering and throttle inputs
Sensor data (IMU, GPS, odometry)
Timestamps
Metadata

Tub Structure

data/
  tub_1_23-03-15/
    meta.json           # Tub metadata (inputs, types)
    manifest.json       # Record manifest
    images/             # Camera images
      0_cam-image_array_.jpg
      1_cam-image_array_.jpg
      ...

Collecting Training Data

Basic Data Collection

Start your car in user mode to collect data:

python manage.py drive

Navigate to the web interface at http://<your-car-ip>:8887:

Start Recording - Click the recording button or toggle via joystick
Drive Manually - Use keyboard, gamepad, or web interface
Stop Recording - Click recording button again when done

Recording Controls

Keyboard (Web UI):

i/k - Throttle forward/backward
j/l - Steer left/right
r - Toggle recording

Gamepad:

Configure buttons in myconfig.py
Default: Right bumper toggles recording

Auto-Recording

Enable automatic recording when throttle is applied:

# myconfig.py
AUTO_RECORD_ON_THROTTLE = True

Data Collection Best Practices

Quality Over Quantity

Good driving data:

Smooth, consistent steering
Varied track positions (center, left, right)
Recovery examples (moving from edge back to center)
Multiple laps with different lighting

Avoid:

Jerky, erratic steering
Stopped or very slow sections
Crashes or off-track driving
Excessive overfitting to one line

How Much Data?

Track Complexity	Recommended Frames	Drive Time (20 FPS)
Simple oval	5,000-10,000	4-8 minutes
Medium circuit	10,000-20,000	8-17 minutes
Complex track	20,000-40,000	17-33 minutes

Diverse Examples

Collect data showing:

Centerline driving - Smooth laps staying centered
Recovery maneuvers - Moving from edges back to center
Different positions - Left side, right side of track
Various speeds - Fast straightaways, slow corners

TubWriter Class

Donkeycar’s TubWriter part handles data recording:

from donkeycar.parts.tub_v2 import TubWriter

# Create tub writer
tub_writer = TubWriter(
    base_path='~/mycar/data/tub_1',
    inputs=['cam/image_array', 'user/steering', 'user/throttle'],
    types=['image_array', 'float', 'float']
)

# In vehicle loop
V.add(tub_writer, 
      inputs=['cam/image_array', 'steering', 'throttle'],
      outputs=['tub/num_records'],
      run_condition='recording')

Key parameters:

base_path - Directory to store tub data
inputs - List of data keys to record
types - Data types for each input
run_condition - Only runs when condition is True

Supported types:

image_array - Numpy arrays saved as JPG
float - Floating point numbers
int - Integers
str - Strings
boolean - Boolean values
list, vector - Lists of values

Writing Records

The TubWriter automatically saves records each frame:

# Vehicle loop calls this automatically
def run(self, *args):
    """Save data to tub"""
    record = dict(zip(self.tub.inputs, args))
    self.tub.write_record(record)
    return self.tub.manifest.current_index

Each record contains:

{
  "cam/image_array": "42_cam-image_array_.jpg",
  "user/steering": 0.15,
  "user/throttle": 0.35,
  "_timestamp_ms": 1234567890,
  "_index": 42
}

Managing Tubs

View Tub Data

Inspect tub contents:

# Show tub summary
donkey tubhist data/tub_1

# Show detailed statistics  
donkey tubhist data/tub_1 --detail

Clean Bad Data

Remove problematic frames:

donkey tubclean data/tub_1

This opens an interface to:

View images and telemetry
Delete individual frames
Remove ranges of frames
Filter by criteria

Combine Multiple Tubs

Merge tubs for training:

# Train on multiple tubs
donkey train --tubs data/tub_1,data/tub_2,data/tub_3 \
  --model models/pilot.h5

Tub Commands

# Check tub integrity
donkey tubcheck data/tub_1

# Plot steering/throttle distribution
donkey tubplot data/tub_1

# Export to CSV
donkey tubcsv data/tub_1

Tub Format (V2)

Donkeycar uses an efficient tub format: meta.json:

{
  "inputs": ["cam/image_array", "user/steering", "user/throttle"],
  "types": ["image_array", "float", "float"],
  "start": 1678901234.5
}

manifest.json:

{
  "current_index": 1523,
  "deleted_indexes": [45, 67, 89],
  "session_id": "abc123"
}

Images stored separately:

Reduces JSON file size
Enables efficient image loading
Supports lazy loading during training

Data Quality Tips

Lighting Conditions

Collect data in similar lighting to race conditions
If lighting varies, collect examples in multiple conditions
Avoid extreme shadows or glare

Track Coverage

Drive both directions if track is reversible
Include all turns and track sections
Don’t over-represent easy sections

Recovery Examples

20% of data should show recovery:

Position car near track edge
Start recording
Steer back toward center
Stop recording
Repeat at different locations

Throttle Consistency

For best results:

Maintain consistent speed throughout laps
Match training speed to desired race speed
Consider using constant throttle mode

Advanced: Custom Data Recording

Recording Additional Sensors

# myconfig.py
inputs = [
    'cam/image_array',
    'user/steering', 
    'user/throttle',
    'imu/acl_x', 'imu/acl_y', 'imu/acl_z',  # IMU data
    'gps/latitude', 'gps/longitude'          # GPS data
]

types = [
    'image_array',
    'float', 'float',
    'float', 'float', 'float',
    'float', 'float'
]

# In manage.py
tub_writer = TubWriter(tub_path, inputs=inputs, types=types)

Filtering During Recording

Only record when conditions are met:

class ConditionalRecording:
    def __init__(self, min_throttle=0.1):
        self.min_throttle = min_throttle
        
    def run(self, recording, throttle):
        # Only record if moving
        if abs(throttle) < self.min_throttle:
            return False
        return recording

V.add(ConditionalRecording(), 
      inputs=['recording', 'user/throttle'],
      outputs=['recording'])

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

What is a Tub?

Tub Structure

Collecting Training Data

Basic Data Collection

Recording Controls

Auto-Recording

Data Collection Best Practices

Quality Over Quantity

How Much Data?

Diverse Examples

TubWriter Class

Writing Records

Managing Tubs

View Tub Data

Clean Bad Data

Combine Multiple Tubs

Tub Commands

Tub Format (V2)

Data Quality Tips

Lighting Conditions

Track Coverage

Recovery Examples

Throttle Consistency

Advanced: Custom Data Recording

Recording Additional Sensors

Filtering During Recording

Next Steps

Train Deep Learning Model

Data Augmentation

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

​What is a Tub?

​Tub Structure

​Collecting Training Data

​Basic Data Collection

​Recording Controls

​Auto-Recording

​Data Collection Best Practices

​Quality Over Quantity

​How Much Data?

​Diverse Examples

​TubWriter Class

​Writing Records

​Managing Tubs

​View Tub Data

​Clean Bad Data

​Combine Multiple Tubs

​Tub Commands

​Tub Format (V2)

​Data Quality Tips

​Lighting Conditions

​Track Coverage

​Recovery Examples

​Throttle Consistency

​Advanced: Custom Data Recording

​Recording Additional Sensors

​Filtering During Recording

​Next Steps

Train Deep Learning Model

Data Augmentation

Build docs developers (and LLMs) love

What is a Tub?

Tub Structure

Collecting Training Data

Basic Data Collection

Recording Controls

Auto-Recording

Data Collection Best Practices

Quality Over Quantity

How Much Data?

Diverse Examples

TubWriter Class

Writing Records

Managing Tubs

View Tub Data

Clean Bad Data

Combine Multiple Tubs

Tub Commands

Tub Format (V2)

Data Quality Tips

Lighting Conditions

Track Coverage

Recovery Examples

Throttle Consistency

Advanced: Custom Data Recording

Recording Additional Sensors

Filtering During Recording

Next Steps