📜 PlateShapez

A research tool for generating adversarially perturbed license plate overlays on vehicle images, producing structured datasets with reproducibility, transparency, and ethical guardrails.

Design Principle: user-first, safe by default, hackable by experts.

🚀 Quick Start

🎬 Try the Demo First!

For a complete walkthrough that creates test images and demonstrates both CLI and Python API:

# Run the integrated CLI demo (recommended)
uv run advplate demo

# With automatic cleanup
uv run advplate demo --cleanup

# Or run the demo script directly
uv run python examples/demo_full_workflow.py

This demo will:

• Create synthetic car backgrounds and license plate overlays
• Show CLI usage with custom configurations
• Demonstrate Python API with different perturbations
• Generate datasets and show output structure
• Display metadata and results analysis

Prerequisites

• uv (Python package manager) installed:

  # Install uv
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

Installation

# Clone the repository
git clone https://github.com/benjordan/plateshapez.git
cd plateshapez

# Create virtual environment and activate
uv venv
source .venv/bin/activate

# Install dependencies
uv sync
# or uv sync --group dev for development dependencies

# Install the CLI tool
uv pip install -e .

Basic Usage

1. Prepare your data:

   project/
   ├── backgrounds/     # Vehicle images (JPG)
   ├── overlays/        # License plate images (PNG with alpha)
   └── config.yaml      # Optional configuration
   

2. Generate dataset:

   # Generate dataset with defaults
   uv run advplate generate
   
   # Generate with custom config and seed for reproducibility
   uv run advplate generate --config my_config.yaml --seed 42
   
   # Preview generation plan
   uv run advplate generate --dry-run
   

3. Explore available options:

   # Run interactive demo
   uv run advplate demo
   
   # List available perturbations
   uv run advplate list
   
   # Show current configuration
   uv run advplate info --as yaml
   
   # Print example configuration
   uv run advplate examples
   
   # Show version
   uv run advplate version
   

Python API

from plateshapez import DatasetGenerator

# Generate dataset programmatically
gen = DatasetGenerator(
    bg_dir="backgrounds",
    overlay_dir="overlays",
    out_dir="dataset",
    perturbations=[
        {"name": "shapes", "params": {"num_shapes": 20}},
        {"name": "noise", "params": {"intensity": 25}},
        {"name": "texture", "params": {"type": "grain", "intensity": 0.3}}
    ],
    random_seed=1337,
    verbose=True  # Enable verbose output
)
gen.run(n_variants=10)

🎛️ Configuration

Configuration File (config.yaml)

dataset:
  backgrounds: "./backgrounds"
  overlays: "./overlays"
  output: "./dataset"
  n_variants: 10
  random_seed: 1337

perturbations:
  - name: shapes
    params:
      num_shapes: 20
      min_size: 2
      max_size: 15
  - name: noise
    params:
      intensity: 25
  - name: texture
    params:
      type: grain
      intensity: 0.3
  - name: warp
    params:
      intensity: 5.0
      frequency: 20.0

logging:
  level: INFO
  save_metadata: true

Available Perturbations

• shapes: Random rectangles, ellipses, triangles (supports scope: region|global)
• noise: Add Gaussian noise (supports scope: region|global)
• warp: Mild geometric warping (supports scope: region|global)
• texture: Overlay texture maps (grain, scratches, dirt)

Scope Parameter: All perturbations support a scope parameter:

• scope: region (default): Apply only to the license plate area
• scope: global: Apply to the entire image

CLI Reference

Generation Commands:

• uv run advplate generate - Generate dataset with defaults
• uv run advplate generate --config file.yaml --seed 42 - Generate with config and seed
• uv run advplate generate --dry-run - Preview without creating files

Demo & Information Commands:

• uv run advplate demo - Run interactive demo with synthetic images
• uv run advplate demo --cleanup - Run demo with automatic cleanup
• uv run advplate list - List available perturbations
• uv run advplate info - Show current configuration (JSON)
• uv run advplate info --as yaml - Show configuration in YAML format
• uv run advplate examples - Print example configuration
• uv run advplate version - Show version

CLI Options:

• --config PATH - Path to YAML/JSON configuration file
• --n_variants INT - Override number of variants per image pair
• --seed INT - Random seed for reproducible results
• --verbose - Enable verbose logging
• --debug - Enable debug logging with full stack traces
• --dry-run - Preview generation plan without creating files

📁 Output Structure

Generated datasets follow this structure:

dataset/
├── images/              # Generated composite images
│   ├── car1_plate1_000.png
│   ├── car1_plate1_001.png
│   └── ...
└── labels/              # Metadata JSON files
    ├── car1_plate1_000.json
    ├── car1_plate1_001.json
    └── ...

Each JSON file contains:

• Background and overlay filenames
• Overlay position and size
• Applied perturbations with parameters
• Random seed for reproducibility
• Variant index for tracking multiple versions

🔧 Development (npm-like commands)

You can use either the console script (after uv sync) or the Bash wrapper.

• Console script (requires one-time uv sync):

  # Format / Lint / Type-check / All checks
  uv run dev format
  uv run dev lint
  uv run dev type
  uv run dev check
  
  # Pre-commit hooks
  uv run dev hooks install   # installs pre-commit & pre-push hooks
  uv run dev pre-commit      # run hooks on all files
  
  # Cleanup commands
  uv run dev cleanup         # standard cleanup (demo files and datasets)
  uv run dev cleanup all     # full cleanup (includes .venv and build artifacts)
  

• Bash wrapper (works without installing the package):

  ./scripts/dev format
  ./scripts/dev lint
  ./scripts/dev type
  ./scripts/dev check
  ./scripts/dev hooks install
  ./scripts/dev pre-commit
  

These map to the same underlying tools and are aligned with CI and scripts/check.sh.

What the commands do

• format: ruff format .
• lint: ruff check . --fix
• type: mypy .
• check: runs format, lint, and type in sequence (same as scripts/check.sh)
• hooks install: pre-commit install --hook-type pre-commit --hook-type pre-push
• pre-commit: pre-commit run --all-files
• cleanup: reset project to fresh state (removes demo files and datasets)
• cleanup all: full cleanup including .venv and build artifacts

📚 Additional Documentation

• Project Specification - Detailed technical requirements and implementation notes
• Usage Examples - Comprehensive examples for CLI and Python API
• Dataset Card - Ethical guidelines and responsible use information
• Code Examples - Working Python scripts demonstrating API usage
  • demo_full_workflow.py - Complete end-to-end demo with synthetic images
  • generate_defaults.py - Basic API usage examples

🔬 Research & Ethics

This tool is designed for research into adversarial robustness of OCR and ALPR systems. Please review the Dataset Card for ethical guidelines and responsible use practices.

🧪 Testing

Run the test suite:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=plateshapez

# Run specific test file
uv run pytest tests/test_pipeline.py

Reset to Fresh State

To clean up all generated files and reset for fresh testing:

# Using dev command (recommended)
uv run dev cleanup         # standard cleanup
uv run dev cleanup all     # full cleanup

# Direct script usage
python scripts/cleanup.py
python scripts/cleanup.py --all
python scripts/cleanup.py --dry-run  # preview mode

CI

GitHub Actions runs the same checks via ./scripts/check.sh. Local pre-commit hooks use the same tools via uv to avoid version drift.