lerobot-imgtransform-viz

Visualize image transformation effects for dataset augmentation

The lerobot-imgtransform-viz command generates visual examples of image transformations applied during dataset loading, helping you configure and debug image augmentation settings.

Command

lerobot-imgtransform-viz [OPTIONS]

Location: src/lerobot/scripts/lerobot_imgtransform_viz.py

Overview

This utility:

• Visualizes effects of image transformations
• Shows individual transforms separately
• Generates examples of combined transforms
• Saves output images for inspection
• Helps tune augmentation parameters
• Supports all LeRobot transform types

Key Options

Dataset Options

--repo_id · str · required

Dataset repository ID (e.g., lerobot/pusht).

--episodes · list[int]

Episode indices to use. Defaults to [0].

--revision · str

Git revision of the dataset.

--video_backend · str

Video backend: torchcodec, pyav, or video_reader.

Transform Options

--image_transforms.enable · bool · default: "false"

Enable image transformations. Must be True to generate transform examples.

--image_transforms.tfs · dict

Dictionary of transform configurations. See examples below.

Output Options

--output_dir · str · default: "outputs/image_transforms"

Directory to save visualization images.

--n_examples · int · default: "5"

Number of random examples to generate per transform.

Usage Examples

Basic Visualization

lerobot-imgtransform-viz \
  --repo_id=lerobot/pusht \
  --episodes='[0]' \
  --image_transforms.enable=true

Generates:

• Original frame from first episode
• Examples of combined transforms
• Individual transform examples (if configured)

Visualize Specific Transforms

lerobot-imgtransform-viz \
  --repo_id=lerobot/pusht \
  --episodes='[0]' \
  --image_transforms.enable=true \
  --image_transforms.tfs='{
    RandomCrop: {
      type: RandomCrop,
      kwargs: {size: [0.9, 1.0]}
    },
    ColorJitter: {
      type: ColorJitter,
      kwargs: {brightness: [0.8, 1.2], contrast: [0.8, 1.2]}
    }
  }'

Multiple Augmentation Examples

lerobot-imgtransform-viz \
  --repo_id=lerobot/aloha_mobile_cabinet \
  --episodes='[0]' \
  --image_transforms.enable=true \
  --n_examples=10 \
  --output_dir=./transform_examples

Generates 10 random augmentation examples.

Custom Transform Parameters

lerobot-imgtransform-viz \
  --repo_id=lerobot/pusht \
  --image_transforms.enable=true \
  --image_transforms.tfs='{
    SharpnessJitter: {
      type: SharpnessJitter,
      kwargs: {sharpness: [0.5, 1.5]}
    },
    RandomRotation: {
      type: RandomRotation,
      kwargs: {degrees: [-15, 15]}
    },
    GaussianBlur: {
      type: GaussianBlur,
      kwargs: {kernel_size: [3, 7], sigma: [0.1, 2.0]}
    }
  }'

Output Structure

Generated files are organized as:

outputs/image_transforms/pusht/
├── original_frame.png           # Original image from dataset
├── all/                        # Combined transforms
│   ├── 1.png
│   ├── 2.png
│   ├── 3.png
│   ├── 4.png
│   └── 5.png
├── RandomCrop/                 # Individual transform examples
│   ├── 1.png                    # Random examples
│   ├── 2.png
│   ├── 3.png
│   ├── min.png                  # Min parameter value
│   ├── mean.png                 # Average parameter value
│   └── max.png                  # Max parameter value
├── ColorJitter/
│   ├── 1.png
│   ├── ...
│   ├── min.png
│   ├── mean.png
│   └── max.png
└── SharpnessJitter/
    ├── 1.png
    ├── ...
    ├── min.png
    ├── mean.png
    └── max.png

Transform Types

RandomCrop

Randomly crops images to a fraction of original size:

--image_transforms.tfs='{
  RandomCrop: {
    type: RandomCrop,
    kwargs: {size: [0.9, 1.0]}  # 90-100% of original size
  }
}'

ColorJitter

Randomly adjusts brightness, contrast, saturation:

--image_transforms.tfs='{
  ColorJitter: {
    type: ColorJitter,
    kwargs: {
      brightness: [0.8, 1.2],
      contrast: [0.8, 1.2],
      saturation: [0.8, 1.2],
      hue: [-0.05, 0.05]
    }
  }
}'

SharpnessJitter

Randomly adjusts image sharpness:

--image_transforms.tfs='{
  SharpnessJitter: {
    type: SharpnessJitter,
    kwargs: {sharpness: [0.5, 1.5]}  # 0.5x to 1.5x sharpness
  }
}'

RandomRotation

Randomly rotates images:

--image_transforms.tfs='{
  RandomRotation: {
    type: RandomRotation,
    kwargs: {degrees: [-10, 10]}  # -10 to +10 degrees
  }
}'

GaussianBlur

Applies Gaussian blur:

--image_transforms.tfs='{
  GaussianBlur: {
    type: GaussianBlur,
    kwargs: {
      kernel_size: [3, 7],  # Odd numbers only
      sigma: [0.1, 2.0]
    }
  }
}'

RandomGrayscale

Randomly converts to grayscale:

--image_transforms.tfs='{
  RandomGrayscale: {
    type: RandomGrayscale,
    kwargs: {p: [0.0, 0.2]}  # 0-20% probability
  }
}'

Combining Transforms

Apply multiple transforms in sequence:

lerobot-imgtransform-viz \
  --repo_id=lerobot/pusht \
  --image_transforms.enable=true \
  --image_transforms.tfs='{
    RandomCrop: {
      type: RandomCrop,
      kwargs: {size: [0.95, 1.0]}
    },
    ColorJitter: {
      type: ColorJitter,
      kwargs: {brightness: [0.9, 1.1], contrast: [0.9, 1.1]}
    },
    SharpnessJitter: {
      type: SharpnessJitter,
      kwargs: {sharpness: [0.8, 1.2]}
    }
  }'

The all/ directory shows results of all transforms applied together.

Interpreting Results

Check Augmentation Strength

Compare transformed images to original:

• Too subtle: Increase parameter ranges
• Too aggressive: Reduce parameter ranges
• Good balance: Natural variation without distortion

Evaluate Individual Transforms

Check min.png, mean.png, max.png for each transform:

• min.png: Minimum parameter value
• mean.png: Average parameter value
• max.png: Maximum parameter value

Ensure all three are reasonable for your task.

Verify Combined Effects

Check all/ directory:

• Multiple transforms should create diverse but realistic variations
• No extreme distortions or artifacts
• Key visual features still recognizable

Tuning Guidelines

Conservative Augmentation

For sim-to-real or precise tasks:

--image_transforms.tfs='{
  RandomCrop: {type: RandomCrop, kwargs: {size: [0.98, 1.0]}},
  ColorJitter: {
    type: ColorJitter,
    kwargs: {brightness: [0.95, 1.05], contrast: [0.95, 1.05]}
  }
}'

Aggressive Augmentation

For diverse real-world environments:

--image_transforms.tfs='{
  RandomCrop: {type: RandomCrop, kwargs: {size: [0.8, 1.0]}},
  ColorJitter: {
    type: ColorJitter,
    kwargs: {brightness: [0.7, 1.3], contrast: [0.7, 1.3], saturation: [0.7, 1.3]}
  },
  RandomRotation: {type: RandomRotation, kwargs: {degrees: [-20, 20]}},
  GaussianBlur: {type: GaussianBlur, kwargs: {kernel_size: [3, 7], sigma: [0.1, 2.0]}}
}'

Balanced Augmentation (Recommended)

--image_transforms.tfs='{
  RandomCrop: {type: RandomCrop, kwargs: {size: [0.9, 1.0]}},
  ColorJitter: {
    type: ColorJitter,
    kwargs: {brightness: [0.8, 1.2], contrast: [0.8, 1.2]}
  },
  SharpnessJitter: {type: SharpnessJitter, kwargs: {sharpness: [0.8, 1.2]}}
}'

Using in Training

Once you’ve tuned transforms, use in training:

lerobot-train \
  --policy.type=act \
  --dataset.repo_id=lerobot/pusht \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.tfs='{
    RandomCrop: {type: RandomCrop, kwargs: {size: [0.9, 1.0]}},
    ColorJitter: {
      type: ColorJitter,
      kwargs: {brightness: [0.8, 1.2], contrast: [0.8, 1.2]}
    }
  }'

Programmatic Usage

from lerobot.scripts.lerobot_imgtransform_viz import visualize_image_transforms
from lerobot.configs.default import DatasetConfig
from lerobot.datasets.transforms import ImageTransformsConfig, TransformConfig
from pathlib import Path

config = DatasetConfig(
    repo_id="lerobot/pusht",
    episodes=[0],
    image_transforms=ImageTransformsConfig(
        enable=True,
        tfs={
            "RandomCrop": TransformConfig(
                type="RandomCrop",
                kwargs={"size": [0.9, 1.0]}
            ),
            "ColorJitter": TransformConfig(
                type="ColorJitter",
                kwargs={"brightness": [0.8, 1.2], "contrast": [0.8, 1.2]}
            ),
        }
    )
)

visualize_image_transforms(
    cfg=config,
    output_dir=Path("./transform_viz"),
    n_examples=10
)

Tips

1. Start Simple: Test one transform at a time
2. Check Extremes: Look at min/max examples to avoid over-augmentation
3. Use Real Data: Test on actual dataset images, not synthetic
4. Iterate: Adjust parameters based on visual inspection
5. Consider Task: Match augmentation to deployment environment

See Also

• lerobot-train - Train policies with augmentation
• Image Transforms - Transform configuration
• LeRobotDataset - Dataset format and loading