PlateShapez 快速上手指南:5 分钟从零生成你的第一个对抗车牌数据集

原创2026-11-02 14:04:251,848 阅读

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   # 显示版本

最佳实践清单:

  1. 固定随机种子(--seed 42)保证实验可复现
  2. 测试配置时先用小 n_variants(如 5)快速验证
  3. 正式生成前用 --dry-run 预览
  4. 排查问题时加 --verbose 或 --debug
  5. 定期用 uv run dev cleanup 清理演示与生成文件,保持项目干净

小结

从克隆仓库到生成带元数据的对抗车牌数据集,PlateShapez 只需几步:uv sync 安装 → advplate demo 验证环境 → 准备 backgrounds/ 与 overlays/ → advplate generate。核心功能实现集中在 src/plateshapez/ 目录,技术细节可进一步阅读 docs/project_spec.md。请始终在研究语境中使用本工具,并遵守 DATASET_CARD 中的伦理指引。

登录后查看全文
PlateShapez