# bennjordan/plateshapez architecture

> Architecture diagram of the GitHub repository bennjordan/plateshapez, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bennjordan/plateshapez
- Repository: https://github.com/bennjordan/plateshapez

## Overview

PlateShapez is a research dataset generator for adversarial license-plate overlays on vehicle images. In the main workflow, a user invokes the CLI, configuration is merged from defaults, a file, and CLI overrides, and the generator loads background/overlay images, composites them, applies configured perturbations, then writes images and optional JSON metadata. The Python API can invoke the generator directly. The README also documents listing perturbations, configuration inspection, and an interactive demo. The graph covers documented perturbation types; source excerpts do not show every CLI command implementation or the demo script internals.

Main entry points: [`src/plateshapez/pipeline.py`](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/pipeline.py) (Dataset generator), [`src/plateshapez/perturbations/base.py`](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/base.py) (Perturbation registry), [`src/plateshapez/__main__.py`](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/__main__.py) (CLI commands), [`src/plateshapez/perturbations/noise.py`](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/noise.py) (Noise perturbation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI commands<br/>[__main__.py]"]
  node_demo["Workflow demo"]
end

subgraph group_generation["Dataset generation"]
  node_config["Config merging<br/>[config.py]"]
  node_generator["Dataset generator<br/>[pipeline.py]"]
end

subgraph group_perturbations["Perturbation system"]
  node_registry["Perturbation registry<br/>[base.py]"]
  node_noise["Noise perturbation<br/>[noise.py]"]
  node_shapes["Shape perturbation<br/>[shapes.py]"]
  node_texture["Texture perturbation<br/>[texture.py]"]
  node_warp["Warp perturbation<br/>[warp.py]"]
end

subgraph group_artifacts["Input and output"]
  node_input_io["Image discovery<br/>[io.py]"]
  node_image_utils["Image preparation<br/>[overlay.py]"]
  node_image_output["Generated images<br/>[io.py]"]
  node_metadata_output["Metadata labels<br/>[io.py]"]
end

node_user(("Research user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"starts generation"| node_generator
node_user -->|"uses Python API"| node_generator
node_cli -->|"runs demo"| node_demo
node_generator -->|"discovers files"| node_input_io
node_generator -->|"prepares images"| node_image_utils
node_generator -->|"dispatches perturbations"| node_registry
node_noise -->|"registers"| node_registry
node_shapes -->|"registers"| node_registry
node_texture -->|"registers"| node_registry
node_warp -->|"registers"| node_registry
node_generator -->|"saves images"| node_image_output
node_generator -->|"saves metadata"| node_metadata_output

click node_cli "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/__main__.py"
click node_demo "https://github.com/bennjordan/plateshapez/blob/main/examples/demo_full_workflow.py"
click node_config "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/config.py"
click node_generator "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/pipeline.py"
click node_registry "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/base.py"
click node_noise "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/noise.py"
click node_shapes "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/shapes.py"
click node_texture "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/texture.py"
click node_warp "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/warp.py"
click node_input_io "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py"
click node_image_utils "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/overlay.py"
click node_image_output "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py"
click node_metadata_output "https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_demo,node_user toneBlue
class node_config,node_generator toneAmber
class node_registry,node_noise,node_shapes,node_texture,node_warp toneMint
class node_input_io,node_image_utils,node_image_output,node_metadata_output toneRose
```

## Components

### User entry points

- [CLI commands](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/__main__.py): `src/plateshapez/__main__.py`
- [Workflow demo](https://github.com/bennjordan/plateshapez/blob/main/examples/demo_full_workflow.py): `examples/demo_full_workflow.py`

### Dataset generation

- [Config merging](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/config.py): `src/plateshapez/config.py`
- [Dataset generator](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/pipeline.py): `src/plateshapez/pipeline.py`

### Perturbation system

- [Perturbation registry](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/base.py): `src/plateshapez/perturbations/base.py`
- [Noise perturbation](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/noise.py): `src/plateshapez/perturbations/noise.py`
- [Shape perturbation](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/shapes.py): `src/plateshapez/perturbations/shapes.py`
- [Texture perturbation](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/texture.py): `src/plateshapez/perturbations/texture.py`
- [Warp perturbation](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/perturbations/warp.py): `src/plateshapez/perturbations/warp.py`

### Input and output

- [Image discovery](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py): `src/plateshapez/utils/io.py`
- [Image preparation](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/overlay.py): `src/plateshapez/utils/overlay.py`
- [Generated images](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py): `src/plateshapez/utils/io.py`
- [Metadata labels](https://github.com/bennjordan/plateshapez/blob/main/src/plateshapez/utils/io.py): `src/plateshapez/utils/io.py`

### Other components

- **Research user**

## Connections

- Research user → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Config merging: loads config (evidence: `src/plateshapez/__main__.py`)
- CLI commands → Dataset generator: starts generation (evidence: `src/plateshapez/__main__.py`)
- Research user → Dataset generator: uses Python API (evidence: `README.md`)
- CLI commands → Workflow demo: runs demo (evidence: `src/plateshapez/__main__.py`)
- Dataset generator → Image discovery: discovers files (evidence: `src/plateshapez/pipeline.py`)
- Dataset generator → Image preparation: prepares images (evidence: `src/plateshapez/pipeline.py`)
- Dataset generator → Perturbation registry: dispatches perturbations (evidence: `src/plateshapez/pipeline.py`)
- Noise perturbation → Perturbation registry: registers (evidence: `src/plateshapez/perturbations/noise.py`)
- Shape perturbation → Perturbation registry: registers (evidence: `src/plateshapez/perturbations/shapes.py`)
- Texture perturbation → Perturbation registry: registers (evidence: `src/plateshapez/perturbations/texture.py`)
- Warp perturbation → Perturbation registry: registers (evidence: `src/plateshapez/perturbations/warp.py`)
- Dataset generator → Generated images: saves images (evidence: `src/plateshapez/pipeline.py`)
- Dataset generator → Metadata labels: saves metadata (evidence: `src/plateshapez/pipeline.py`)
