企业官网建设流程全解析

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模块展开，系统讲解 MPDD（Metal Part Defect Dataset）数据集的目录结构约定、MPDDDataModule 的全部构造参数、prepare_data的可用性校验与下载指引，以及底层MPDDDataset的样本解析、掩膜匹配与任务类型推断机制。读完后，你将能够针对工业金属件缺陷检测场景正确搭建训练/推理数据流水线，并通过 YAML 配置文件驱动整个数据模块。

一、MPDD 数据集是什么

MPDD 是面向工业金属件制造场景的视觉缺陷检测基准数据集，目标是评估各类异常检测方法在复杂工业条件下的表现。根据模块 docstring（src/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 conditions（ICUMT 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 DataModule

MPDD是AnomalibDataModule的子类，继承自 PyTorch Lightning 的 DataModule 抽象。最小可用示例（源自类 docstring）：

from 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", category="bracket_brown", )

自定义验证集来源（两个变体均来自类 docstring 的 Example 部分，src/anomalib/data/datamodules/image/mpdd.py）：

from anomalib.data.utils import ValSplitMode # 从 test 数据中切出验证集 datamodule = MPDD( val_split_mode=ValSplitMode.FROM_TEST, val_split_ratio=0.1, ) # 使用合成（synthetic）方式生成验证集 datamodule = MPDD( val_split_mode=ValSplitMode.SYNTHETIC, val_split_ratio=0.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 一一对应：

所有参数均原样透传给基类AnomalibDataModule（super().__init__调用，src/anomalib/data/datamodules/image/mpdd.py），MPDD 特有逻辑只有root解析与category保存两项。

四、root 路径解析与 prepare_data 可用性校验

构造函数中对root的处理只有一行（src/anomalib/data/datamodules/image/mpdd.py）：

root = resolve_dataset_root(root, "MPDD")

resolve_dataset_root的语义（src/anomalib/utils/path.py）：

• root非None：原样转为Path；
• root为None：回退到平台缓存目录下的MPDD子目录，由get_datasets_dir()给出（Linux/macOS 下即~/.cache/anomalib/datasets/MPDD一类位置，见 src/anomalib/utils/path.py 的 docstring 示例）。

真正“检查数据是否就位”的逻辑在prepare_data（src/anomalib/data/datamodules/image/mpdd.py）：若root目录不存在，则抛出RuntimeError，错误信息由get_download_instructions生成。该信息包含三步指引（src/anomalib/data/datamodules/image/mpdd.py）：

1. 访问作者（VUT Brno）提供的 OneDrive 共享目录——完整链接直接打印在错误信息中；
2. 手动下载全部文件；
3. 解压到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_EXTENSIONS，src/anomalib/data/datasets/image/mpdd.py）。

5.1 期望的目录布局

make_mpdd_dataset的 docstring 给出约定（src/anomalib/data/datasets/image/mpdd.py）：

path/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_dataset（src/anomalib/data/datasets/image/mpdd.py），可以归纳为五步：

1. 递归扫描：对类别目录做root.glob("**/*")，仅收集.png/.PNG文件；取路径最后三段组成(path, split, label, image_path)四元组。找不到任何图像时抛出RuntimeError("Found 0 images in ...")；
2. 标签编码：label（目录名）为good的样本label_index = 0（LabelName.NORMAL），其余（各类缺陷目录名）一律label_index = 1（LabelName.ABNORMAL）；
3. 掩膜关联：把ground_truth下的文件按image_path排序后，与测试集中异常样本（split == "test"且label_index == 1）按排序后顺序一一配对，写入mask_path列；
4. 一致性断言：逐一校验“异常图像文件名（stem）必须包含在对应掩膜文件名（stem）中”，不满足即抛出MisMatchError，并提示命名约定——掩膜文件名需与异常图像同名，例如000.png对000.png或000_mask.png（src/anomalib/data/datasets/image/mpdd.py）；
5. 任务类型推断：若所有样本都没有mask_path，samples.attrs["task"] = "classification"；否则为"segmentation"（src/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.py）：

from pathlib import Path from anomalib.data.datasets import MPDDDataset dataset = MPDDDataset( root=Path("./datasets/MPDD"), category="bracket_black", split="train", ) # 分类视角下每个样本包含： 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 配置文件使用 MPDD

anomalib 支持用 Hydrax 风格的 YAML 配置文件声明数据模块，仓库中为 MPDD 提供的样例是 examples/configs/data/mpdd.yaml：

class_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: null

class_path指向可导入的 DataModule 类，init_args与构造函数参数一一对应。将该文件路径传给 CLI 的数据模块参数（--datamodule_config）即可在训练/测试流程中复现同一套数据配置，便于实验管理。

七、单元测试如何验证 MPDD 的行为

仓库对 MPDD DataModule 提供了单元测试 tests/unit/data/datamodule/image/test_mpdd.py：

• 测试类TestMPDD继承通用图像 DataModule 测试基类_TestAnomalibImageDatamodule（tests/unit/data/datamodule/base/image），复用一组通用的数据流断言；
• fixture 使用假数据目录dataset_path / "mpdd"与category="dummy"构造 DataModule，说明解析逻辑不依赖真实 6 类命名，只依赖“split/label 目录 + PNG 文件”这一结构约定；
• 通过augmentations=Resize((256, 256))验证通用增强参数的透传；
• fxt_data_config_path指向 examples/configs/data/mpdd.yaml，意味着测试同时校验该 YAML 配置可被正确解析并实例化出等价参数。

八、实操要点与常见陷阱

结合源码行为，使用 MPDD 数据模块时建议注意：

1. 先准备数据再运行：prepare_data只校验根目录存在性。目录存在但结构不符合“类别/标签子目录/PNG”约定时，错误会推迟到setup阶段以RuntimeError("Found 0 images in ...")形式暴露，此时应核对解压层级是否多包了一层目录；
2. 掩膜命名必须对齐：测试集中的异常图像与ground_truth下掩膜按排序顺序配对，且要求图像 stem 是掩膜 stem 的子串。若文件名不一致，会得到明确的MisMatchError提示，按其建议统一命名（如000.png↔000_mask.png）即可；
3. 图像扩展名限制：扫描只匹配.png与.PNG，JPG 格式样本会被静默忽略，必要时需转换为 PNG；
4. 任务类型由数据决定：无需显式声明分类还是分割——只要存在ground_truth掩膜即推断为segmentation，反之退化为classification；
5. 验证集策略按场景选择：MPDD 默认ValSplitMode.SAME_AS_TEST（验证与测试同集，适合无标签验证集的场景）；若希望从测试集中切分独立验证集或合成验证样本，可分别改用ValSplitMode.FROM_TEST与ValSplitMode.SYNTHETIC，并配合val_split_ratio调节比例；
6. 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