PlateShapez 快速上手指南:5 分钟从零生成你的第一个对抗车牌数据集
PlateShapez 快速上手指南:5 分钟从零生成你的第一个对抗车牌数据集
PlateShapez 是一个用于生成对抗性车牌叠加数据集的开源 Python 研究工具:它把车辆背景图与车牌 PNG 叠加层组合,并施加微小、几乎不可察觉的随机高斯形状、噪声与纹理扰动,用于干扰 AI 车牌识别(OCR/ALPR)系统,从而为对抗鲁棒性研究提供可复现的训练数据。本文带你 5 分钟从零跑通完整流程。
为什么选择 PlateShapez?
在 ALPR(自动车牌识别)鲁棒性研究中,手工构造扰动样本费时费力。PlateShapez 的价值在于:
- 可复现:随机种子决定一切,同样的输入与参数永远得到相同输出
- 结构清晰:自动生成图像 + JSON 元数据,天然适配训练流水线
- 易于扩展:4 种内置扰动(shapes / noise / warp / texture),全部支持
region(仅车牌区域)与global(全图)两种作用范围 - 安全默认:面向研究场景设计,附带完整的伦理使用指南
⚠️ 重要提示:本工具的定位是研究对抗鲁棒性,不是用于逃避执法或非法活动的工具。使用前请务必阅读 DATASET_CARD.md 中的伦理规范。
环境准备:一键安装步骤
前置条件:Python 3.10 ~ 3.13,以及 Python 包管理器 uv。
# 安装 uv(已有可跳过)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/pl/PlateShapez
cd PlateShapez
# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate
uv sync
uv pip install -e .
依赖非常轻量,核心只有 numpy、opencv-python、pillow 三个图像库,完整清单见 pyproject.toml。
最快验证方式:运行内置 Demo
不确定能否跑通?先执行内置演示,它会自动创建合成车辆背景和车牌叠加层,完整走一遍 CLI 与 Python API 流程:
# 运行交互演示(推荐)
uv run advplate demo
# 运行后自动清理演示文件
uv run advplate demo --cleanup
演示内容包括:创建测试图像、CLI 自定义配置用法、不同扰动的 Python API 调用、数据集生成与元数据分析。看到输出中的 ✅ Demo completed successfully! 就说明环境一切正常。
准备数据:5 分钟生成数据集的标准目录
真实生成时,项目目录结构如下:
project/
├── backgrounds/ # 车辆背景图(JPG)
│ ├── car1.jpg
│ └── car2.jpg
├── overlays/ # 车牌叠加图(带透明通道的 PNG)
│ ├── plate1.png
│ └── plate2.png
├── config.yaml # 可选配置文件
└── dataset/ # 生成后自动创建的输出目录
├── images/ # 合成图像
└── labels/ # JSON 元数据
只需两个目录:backgrounds/ 放车辆照片,overlays/ 放裁剪好的车牌 PNG(需带 alpha 通道)。扫描逻辑位于 src/plateshapez/utils/io.py,合成与扰动编排核心在 src/plateshapez/pipeline.py。
一条命令生成数据集
# 使用默认配置生成
uv run advplate generate
# 指定配置文件 + 随机种子(可复现)
uv run advplate generate --config my_config.yaml --seed 42
# 先预览生成计划,不写任何文件
uv run advplate generate --dry-run
默认配置(shapes 扰动 20 个 + 噪声强度 25,每对图像生成 10 个变体)定义在 src/plateshapez/config.py 中。建议先用 --dry-run 预览,确认背景图/叠加图/输出路径无误后再正式生成。
配置优先级
PlateShapez 按 默认值 < 配置文件 < 命令行参数 的顺序合并配置,例如:
# 配置文件写 n_variants: 10,命令行临时改成 50
uv run advplate generate --config base.yaml --n_variants 50
自定义 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
scope: region
- name: noise
params:
intensity: 25
- name: texture
params:
type: grain
intensity: 0.3
logging:
save_metadata: true
不确定配置怎么写?执行 uv run advplate examples 直接打印一份示例 YAML。
了解 4 种内置扰动
执行 uv run advplate list 可以查看完整列表:
| 扰动名 | 作用 | 关键参数 |
|---|---|---|
| shapes | 随机矩形/椭圆/三角形,模拟遮挡 | num_shapes、min_size、max_size |
| noise | 高斯噪声,模拟传感器噪点 | intensity |
| warp | 轻微几何变形,模拟透视畸变 | intensity、frequency |
| texture | 覆盖纹理(颗粒/划痕/污渍) | type: grain / scratches / dirt |
所有扰动都支持 scope 参数:region(仅车牌区域,默认,对抗研究推荐)或 global(全图)。4 种扰动的实现分别位于 src/plateshapez/perturbations/ 目录下的 shapes.py、noise.py、warp.py、texture.py。
查看输出:图像与元数据双输出
生成完成后,dataset/ 目录自动包含两部分:
dataset/
├── images/
│ ├── car1_plate1_000.png
│ └── car1_plate1_001.png
└── labels/
├── car1_plate1_000.json
└── car1_plate1_001.json
每个 JSON 记录了:背景图与叠加图文件名、叠加位置与尺寸、应用的扰动及参数、随机种子、变体索引。这意味着你可以精确复现任意一张图的生成过程——这是研究可复现性的关键。
Python API:编程方式生成
需要把流程嵌入自己的研究脚本?几行代码即可:
from plateshapez import DatasetGenerator
gen = DatasetGenerator(
bg_dir="backgrounds",
overlay_dir="overlays",
out_dir="dataset",
perturbations=[
{"name": "shapes", "params": {"num_shapes": 20}},
{"name": "noise", "params": {"intensity": 25}},
],
random_seed=1337,
verbose=True,
)
gen.run(n_variants=10)
完整 API 用法可参考 examples/generate_defaults.py 和 docs/usage_examples.md。
常用命令速查与最佳实践
uv run advplate list # 列出可用扰动
uv run advplate info --as yaml # 查看合并后的当前配置
uv run advplate version # 显示版本
最佳实践清单:
- 固定随机种子(
--seed 42)保证实验可复现 - 测试配置时先用小
n_variants(如 5)快速验证 - 正式生成前用
--dry-run预览 - 排查问题时加
--verbose或--debug - 定期用
uv run dev cleanup清理演示与生成文件,保持项目干净
小结
从克隆仓库到生成带元数据的对抗车牌数据集,PlateShapez 只需几步:uv sync 安装 → advplate demo 验证环境 → 准备 backgrounds/ 与 overlays/ → advplate generate。核心功能实现集中在 src/plateshapez/ 目录,技术细节可进一步阅读 docs/project_spec.md。请始终在研究语境中使用本工具,并遵守 DATASET_CARD 中的伦理指引。