Anomalib MPDD DataModule工业金属件缺陷数据集的加载、划分与配置实战【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib本篇围绕 anomalib 文档参考页 MPDD 所对应的anomalib.data.datamodules.image.mpdd模块展开系统讲解 MPDDMetal Part Defect Dataset数据集的目录结构约定、MPDDDataModule 的全部构造参数、prepare_data的可用性校验与下载指引以及底层MPDDDataset的样本解析、掩膜匹配与任务类型推断机制。读完后你将能够针对工业金属件缺陷检测场景正确搭建训练/推理数据流水线并通过 YAML 配置文件驱动整个数据模块。一、MPDD 数据集是什么MPDD 是面向工业金属件制造场景的视觉缺陷检测基准数据集目标是评估各类异常检测方法在复杂工业条件下的表现。根据模块 docstringsrc/anomalib/data/datamodules/image/mpdd.py数据集包含6 个类别的工业物体每个类别同时包含正常normal与异常anomalous样本每个类别提供 RGB 图像与像素级 ground truth 掩膜因此既支持分类图像级正常/异常判别也支持分割像素级缺陷定位任务数据集采用 CC BY-NC-SA 4.0 许可发布学术出处为 Jezek 等人的论文Deep learning-based defect detection of metal parts: evaluating current methods in complex conditionsICUMT 2021。从源码常量看受支持的 6 个类别枚举在 src/anomalib/data/datasets/image/mpdd.py 中CATEGORIES ( bracket_black, bracket_brown, bracket_white, connector, metal_plate, tubes, )需要特别注意的是MPDD不能通过 anomalib 自动下载。模块 docstring 明确说明数据集需要手动从 OneDrive 下载src/anomalib/data/datamodules/image/mpdd.py下载入口链接会在prepare_data校验失败时随错误信息一并打印见下文第四节。二、快速开始创建 MPDD DataModuleMPDD是AnomalibDataModule的子类继承自 PyTorch Lightning 的 DataModule 抽象。最小可用示例源自类 docstringfrom anomalib.data import MPDD # 默认根目录与默认类别 datamodule MPDD() datamodule.setup() # 取出一个 batch i, data next(enumerate(datamodule.train_dataloader())) print(data.keys()) # dict_keys([image_path, label, image, mask_path, mask]) # 默认 batch 形状 print(data[image].shape) # torch.Size([32, 3, 256, 256])指定类别与根目录datamodule MPDD( root./datasets/MPDD, categorybracket_brown, )自定义验证集来源两个变体均来自类 docstring 的 Example 部分src/anomalib/data/datamodules/image/mpdd.pyfrom anomalib.data.utils import ValSplitMode # 从 test 数据中切出验证集 datamodule MPDD( val_split_modeValSplitMode.FROM_TEST, val_split_ratio0.1, ) # 使用合成synthetic方式生成验证集 datamodule MPDD( val_split_modeValSplitMode.SYNTHETIC, val_split_ratio0.2, )setup()阶段的行为由_setup方法实现src/anomalib/data/datamodules/image/mpdd.py它固定构造Split.TRAIN与Split.TEST两个MPDDDataset实例分别赋值给self.train_data与self.test_data训练与测试集直接按磁盘上的目录划分不做训练集内部再切分。三、构造参数全表以下参数、默认值与含义以构造函数签名为准src/anomalib/data/datamodules/image/mpdd.py与 docstring 的 Args 一一对应参数类型默认值说明rootPath \| str \| None./datasets/MPDD数据集根目录。传None时回退到 anomalib 缓存目录下的MPDD子目录categorystrbracket_blackMPDD 类别名应为CATEGORIES中的六个取值之一train_batch_sizeint32训练 batch 大小eval_batch_sizeint32验证/测试 batch 大小num_workersint8DataLoader worker 数train_augmentationsTransform \| NoneNone仅训练阶段生效的数据增强val_augmentationsTransform \| NoneNone仅验证阶段生效的数据增强test_augmentationsTransform \| NoneNone仅测试阶段生效的数据增强augmentationsTransform \| NoneNone通用增强当阶段专属增强未提供时回退使用test_split_modeTestSplitModeTestSplitMode.FROM_DIR测试集构建方式MPDD 场景下按目录直接取用test_split_ratiofloat0.2测试集占比val_split_modeValSplitModeValSplitMode.SAME_AS_TEST验证集构建方式可切换为FROM_TEST或SYNTHETICval_split_ratiofloat0.5验证集占比seedint \| NoneNone随机种子用于可复现所有参数均原样透传给基类AnomalibDataModulesuper().__init__调用src/anomalib/data/datamodules/image/mpdd.pyMPDD 特有逻辑只有root解析与category保存两项。四、root 路径解析与 prepare_data 可用性校验构造函数中对root的处理只有一行src/anomalib/data/datamodules/image/mpdd.pyroot resolve_dataset_root(root, MPDD)resolve_dataset_root的语义src/anomalib/utils/path.pyroot非None原样转为Pathroot为None回退到平台缓存目录下的MPDD子目录由get_datasets_dir()给出Linux/macOS 下即~/.cache/anomalib/datasets/MPDD一类位置见 src/anomalib/utils/path.py 的 docstring 示例。真正“检查数据是否就位”的逻辑在prepare_datasrc/anomalib/data/datamodules/image/mpdd.py若root目录不存在则抛出RuntimeError错误信息由get_download_instructions生成。该信息包含三步指引src/anomalib/data/datamodules/image/mpdd.py访问作者VUT Brno提供的 OneDrive 共享目录——完整链接直接打印在错误信息中手动下载全部文件解压到root指定的路径。同时会打印预期的目录结构示意{root}/ ├── bracket_black/ ├── bracket_brown/ └── ...这一设计意味着只要目录缺失Lightning 在调用prepare_data时就会明确告诉你“去哪里下、放到哪里”而不是在后续setup阶段以晦涩的 IO 错误失败。五、底层数据解析MPDDDataset 与 make_mpdd_dataset_setup创建的每个 split 都由 MPDDDataset继承自AnomalibDataset承载。其构造函数src/anomalib/data/datasets/image/mpdd.py要点root缺省时同样回退到缓存目录get_datasets_dir() / MPDD真正参与扫描的路径是root/category即“类别目录”立即调用make_mpdd_dataset把目录树解析为一个DataFrame样本表只识别.png/.PNG扩展名IMG_EXTENSIONSsrc/anomalib/data/datasets/image/mpdd.py。5.1 期望的目录布局make_mpdd_dataset的 docstring 给出约定src/anomalib/data/datasets/image/mpdd.pypath/to/dataset/split/category/image_filename.png path/to/dataset/ground_truth/category/mask_filename.png由于函数入参root实际接收的是“类别目录”展开到磁盘上即datasets/MPDD/ └── bracket_black/ ├── good/ # 训练用正常样本label_index 0 │ ├── 001.png │ └── 002.png ├── scratches/ # 异常类别目录label_index 1 ├── test/ │ ├── defects_screws/ # 测试用异常样本多个缺陷子目录 │ └── defects_scratches/ └── ground_truth/ ├── defects_screws/ # 与测试异常图一一对应的掩膜 └── defects_scratches/5.2 样本表的构建逻辑核心实现在make_mpdd_datasetsrc/anomalib/data/datasets/image/mpdd.py可以归纳为五步递归扫描对类别目录做root.glob(**/*)仅收集.png/.PNG文件取路径最后三段组成(path, split, label, image_path)四元组。找不到任何图像时抛出RuntimeError(Found 0 images in ...)标签编码label目录名为good的样本label_index 0LabelName.NORMAL其余各类缺陷目录名一律label_index 1LabelName.ABNORMAL掩膜关联把ground_truth下的文件按image_path排序后与测试集中异常样本split test且label_index 1按排序后顺序一一配对写入mask_path列一致性断言逐一校验“异常图像文件名stem必须包含在对应掩膜文件名stem中”不满足即抛出MisMatchError并提示命名约定——掩膜文件名需与异常图像同名例如000.png对000.png或000_mask.pngsrc/anomalib/data/datasets/image/mpdd.py任务类型推断若所有样本都没有mask_pathsamples.attrs[task] classification否则为segmentationsrc/anomalib/data/datasets/image/mpdd.py。因此同一个 DataModule 在只有图像而无掩膜的数据布局下会自然退化为纯分类数据源。最后若传入split则按split列过滤train/test并重置索引后返回。样本表最终包含列path、split、label、image_path、mask_path、label_index。5.3 样本键与张量形状MPDDDataset的 docstring 给出了单样本结构src/anomalib/data/datasets/image/mpdd.pyfrom pathlib import Path from anomalib.data.datasets import MPDDDataset dataset MPDDDataset( rootPath(./datasets/MPDD), categorybracket_black, splittrain, ) # 分类视角下每个样本包含 sample dataset[0] print(list(sample.keys())) # [image_path, label, image] # 分割任务下额外包含掩膜信息 print(list(sample.keys())) # [image_path, label, image, mask_path, mask] # 图像为 (C, H, W) 张量掩膜为 (H, W) print(sample[image].shape, sample[mask].shape) # (torch.Size([3, 256, 256]), torch.Size([256, 256]))六、通过 YAML 配置文件使用 MPDDanomalib 支持用 Hydrax 风格的 YAML 配置文件声明数据模块仓库中为 MPDD 提供的样例是 examples/configs/data/mpdd.yamlclass_path: anomalib.data.MPDD init_args: root: ./datasets/MPDD category: bracket_black train_batch_size: 32 eval_batch_size: 32 num_workers: 8 train_augmentations: null val_augmentations: null test_augmentations: null augmentations: null seed: nullclass_path指向可导入的 DataModule 类init_args与构造函数参数一一对应。将该文件路径传给 CLI 的数据模块参数--datamodule_config即可在训练/测试流程中复现同一套数据配置便于实验管理。七、单元测试如何验证 MPDD 的行为仓库对 MPDD DataModule 提供了单元测试 tests/unit/data/datamodule/image/test_mpdd.py测试类TestMPDD继承通用图像 DataModule 测试基类_TestAnomalibImageDatamoduletests/unit/data/datamodule/base/image复用一组通用的数据流断言fixture 使用假数据目录dataset_path / mpdd与categorydummy构造 DataModule说明解析逻辑不依赖真实 6 类命名只依赖“split/label 目录 PNG 文件”这一结构约定通过augmentationsResize((256, 256))验证通用增强参数的透传fxt_data_config_path指向 examples/configs/data/mpdd.yaml意味着测试同时校验该 YAML 配置可被正确解析并实例化出等价参数。八、实操要点与常见陷阱结合源码行为使用 MPDD 数据模块时建议注意先准备数据再运行prepare_data只校验根目录存在性。目录存在但结构不符合“类别/标签子目录/PNG”约定时错误会推迟到setup阶段以RuntimeError(Found 0 images in ...)形式暴露此时应核对解压层级是否多包了一层目录掩膜命名必须对齐测试集中的异常图像与ground_truth下掩膜按排序顺序配对且要求图像 stem 是掩膜 stem 的子串。若文件名不一致会得到明确的MisMatchError提示按其建议统一命名如000.png↔000_mask.png即可图像扩展名限制扫描只匹配.png与.PNGJPG 格式样本会被静默忽略必要时需转换为 PNG任务类型由数据决定无需显式声明分类还是分割——只要存在ground_truth掩膜即推断为segmentation反之退化为classification验证集策略按场景选择MPDD 默认ValSplitMode.SAME_AS_TEST验证与测试同集适合无标签验证集的场景若希望从测试集中切分独立验证集或合成验证样本可分别改用ValSplitMode.FROM_TEST与ValSplitMode.SYNTHETIC并配合val_split_ratio调节比例root 为 None 时看缓存目录未显式传root时数据预期位于 anomalib 缓存目录Linux 下形如~/.cache/anomalib/datasets/MPDD下载数据时请放到对应位置或显式传入root。以上机制均可在 src/anomalib/data/datamodules/image/mpdd.py 与 src/anomalib/data/datasets/image/mpdd.py 中直接查证配套测试位于 tests/unit/data/datamodule/image/test_mpdd.py。【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考