Anomalib 数据工具模块详解：anomalib.data.utils 中图像与视频实用工具全解析

Anomalib 数据工具模块详解anomalib.data.utils 中图像与视频实用工具全解析【免费下载链接】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 的异常检测工作流中数据集的路径组织、下载校验、图像/掩码/深度图读取、视频片段索引、标签体系、目标框互转以及数据集划分都由 anomalib.data.utils 包统一承担。本篇以官方 API 参考页 image_video.md 覆盖的七个子模块为主线逐模块解析其公开接口、参数约束与底层实现细节帮助你在自定义 DataModule、构建推理管线或处理私有数据集时能够正确且安全地复用这些底层工具。模块总览七类数据工具的组织方式anomalib.data.utils 包的模块级文档将工具分为六类图像处理读取、写入与转换、目标框处理掩码与框互转、路径处理校验与解析、数据集划分train/val/test、数据生成如 Perlin 噪声合成以及下载工具。包级__all__直接导出了最常用的函数from anomalib.data.utils import ( read_image, read_mask, read_depth_image, generate_perlin_noise, get_image_filenames, masks_to_boxes, boxes_to_masks, boxes_to_anomaly_maps, random_split, split_by_label, concatenate_datasets, DownloadInfo, download_and_extract, validate_path, resolve_path, validate_and_resolve_path, DirType, LabelName, Split, ValSplitMode, TestSplitMode, )从包结构看每个类别对应src/anomalib/data/utils/下的一个独立文件参考文档小节源码文件核心内容Path Utilspath.pyDirType枚举、validate_path、resolve_pathDownload Utilsdownload.pyDownloadInfo、download_and_extract、安全解压Image Utilsimage.pyread_image、read_mask、save_image等Video Utilsvideo.pyClipsIndexer、convert_videoLabel Utilslabel.pyLabelName整数枚举Bounding Box Utilsboxes.py掩码/框/异常图三者互转Dataset Split Utilssplit.pyrandom_split、split_by_label、划分模式枚举Path Utils异常检测目录规范与路径安全校验DirType数据集目录的七种角色异常检测数据集的目录约定由 DirType 枚举固化各取值的字符串形式直接对应磁盘上的目录名枚举成员字符串值语义DirType.NORMALnormal训练用正常样本DirType.ABNORMALabnormal异常/缺陷样本DirType.NORMAL_TESTnormal_test正常测试样本DirType.NORMAL_DEPTHnormal_depth正常样本的深度图DirType.ABNORMAL_DEPTHabnormal_depth异常样本的深度图DirType.NORMAL_TEST_DEPTHnormal_test_depth正常测试样本的深度图DirType.MASKmask_dir真实分割掩码值得注意的是正常与异常样本的深度目录被显式区分开——这是 MVTEC 3D、ADAM 3D 等深度数据集见 mvtec_3d.py、adam_3d.py的目录解析基础。validate_path长度、字符、存在性与权限四重校验validate_path 是路径校验的入口其检查顺序为类型检查仅接受str或Path否则抛出TypeError长度检查调用 is_path_too_long超过max_length默认512字符抛出ValueError可打印字符检查contains_non_printable_characters 使用正则^[\x20-\x7E]$判断存在\x00等不可打印字符即报错存在性与权限当should_existTrue默认时路径必须存在且具备读或执行权限os.R_OK or os.X_OK否则分别抛出FileNotFoundError/PermissionError扩展名白名单若传入extensionspath.suffix必须命中其一。from anomalib.data.utils import validate_path, resolve_path, validate_and_resolve_path # 校验带扩展名约束的路径 p validate_path(./datasets/image.png, extensions(.png, .jpg)) # 相对目录 数据集根目录 → 绝对路径 abs_p resolve_path(bottle/train/good, /data/MVTecAD) # 等价于 validate_path(resolve_path(folder, root), base_dir) safe_p validate_and_resolve_path(subdir, root/root)resolve_path 的解析规则从源码可以直接读出folder本身是绝对路径时原样使用root为None时对相对路径做resolve()否则拼接root / folder再resolve()。私有数据集的 DataModule 通常用它把 YAML 配置里的相对路径落到磁盘绝对路径上。内部的 _prepare_files_labels 还承担目录扫描生成文件-标签列表的职责它按扩展名默认torchvision的IMG_EXTENSIONS递归收集文件发现隐藏文件或位于隐藏目录中的文件时会记录 warning且当目录中找不到任何匹配图像时抛出RuntimeError提示Found 0 {path_type} images in ...。Download Utils带哈希校验与解压安全防护的数据集下载DownloadInfo 与下载主流程DownloadInfo 是一个四字段 dataclass描述从哪里下、下到什么文件、期望什么哈希from anomalib.data.utils import DownloadInfo, download_and_extract info DownloadInfo( namekolektor, urlhttps://go.vicos.si/kolektorsdd, hashsum65dc621693418585de9c4467d1340ea7958a6181816f0dc2883a1e8b61f9d4dc, filenameKolektorSDD.zip, # 缺省时取 URL 最后一段 ) download_and_extract(rootdatasets/kolektor, infoinfo)这是各内置 DataModule 的真实用法例如 Kolektor 的 DOWNLOAD_INFO 定义同样的模式也出现在 BMAD、BTECH、AutoVI 等数据模块中。download_and_extract 的执行逻辑值得逐条对照自动创建root目录幂等性若压缩包已存在于root跳过下载阶段直接进入解压URL 审计仅允许http://或https://前缀其他 scheme 抛出RuntimeError下载使用urlretrieve并挂接 DownloadProgressBar对tqdm的子类化封装其 update_to 方法作为reporthook回调把chunk_number * max_chunk_size换算成进度增量下载完成后立即调用check_hash校验再执行extract。哈希校验与安全解压generate_hash 按 4096 字节分块读取文件以避免整体载入内存算法名直接映射到hashlib属性默认sha256非法算法名抛ValueErrorcheck_hash 则在实际哈希与期望值不一致时抛出带完整比对的ValueError。解压环节 extract 支持.zip / .tar / .gz / .xz / .tgz并对两类归档恶意利用做了防御is_file_potentially_dangerous 拒绝路径中出现/etc/、/root/等敏感目录模式的成员is_within_directory 结合Path.resolve()与is_relative_to阻止路径穿越..逃逸safe_extract 还会跳过绝对路径与非常规文件成员符号链接、硬链接、设备、FIFO 等在 Python ≥ 3.11.4 上进一步启用tarfile的filterdata保护。解压成功后源压缩包会被unlink清理。Image Utils图像、掩码与深度图的读取/写入anomalib.data.utils.image 覆盖了从文件发现到磁盘落盘的全链路全部函数均带 docstring 示例。文件发现与输出命名is_image_file判断后缀是否属于IMG_EXTENSIONS大小写不敏感get_image_filenames接受单文件或目录先经validate_path校验再递归收集图像目录为空时抛ValueErrorduplicate_filename目标文件已存在时追加_1、_2数字后缀避免结果被静默覆盖generate_output_image_filename推理结果落盘时的命名策略——输出是目录或无扩展名时保留相对目录结构绝对路径输入则仅取文件名输出文件已存在时自动改名并告警。读取函数归一化与张量化约定函数打开模式返回as_tensorFalse返回as_tensorTrueread_imagePILconvert(RGB)np.ndarray已除以 255 归一化到 [0,1]torch.float32张量to_dtype(..., scaleTrue)read_maskPILconvert(L)np.ndarraytorchvision.tv_tensors.Mask二值化0uint8read_depth_imagetifffile.imread深度图np.ndarrayTIFF 格式不做归一化—from anomalib.data.utils import read_image, read_mask, read_depth_image image read_image(bottle/000.png) # ndarray, [0,1] 归一化 tensor read_image(bottle/000.png, as_tensorTrue) # float32 Tensor mask read_mask(ground_truth.png, as_tensorTrue) # Mask 张量, 二值 uint8 depth read_depth_image(depth.tiff) # 原始深度值尺寸与批处理辅助get_image_height_and_widthint输入展开为正方形(s, s)Sequence输入取前两项(H, W)其余类型抛TypeError——数据配置中image_size参数的解析都依赖它pad_nextpow2把图像批次填充到下一个 2 的幂的正方形尺寸采用上下/左右不对称的F.pad奇数填充量向上取整放在前侧常用于网络输入预处理save_image写入前经 duplicate_filename 防覆盖自动mkdir父目录并在保存前做RGB → BGR颜色空间转换以适配cv2.imwriteshow_image 与 figure_to_array基于 matplotlib 的展示与 Figure 转数组源码注释说明show_image对 matplotlib 采用延迟导入避免过早锁定后端。Video Utils视频片段索引与转码anomalib.data.utils.video 服务视频异常检测如 VAD 数据集ClipsIndexer帧-掩码对齐的视频数据访问器ClipsIndexer 继承自torchvision.datasets.video_utils.VideoClips构造参数与默认值为参数默认值说明video_paths必填视频文件路径列表mask_paths必填与视频一一对应的掩码文件路径clip_length_in_frames2每个 clip 的帧数frames_between_clips1相邻 clip 的帧步长关键实现细节强制output_formatTCHW即每个 clip 为[T, C, H, W]张量get_mask是抽象方法子类必须实现按 clip 索引取对应掩码从而保证帧与掩码严格对齐get_item 组装VideoItem附带video_path、本 clip 的帧号frames以及该视频的last_frame供下游做时序边界判断若未安装av模块导入时会构造一个占位 VideoClips实例化时抛出带安装指引的ImportErroruv pip install av或uv pip install anomalib[video]。convert_videoOpenCV 逐帧转码convert_video 用cv2.VideoCapture/cv2.VideoWriter逐帧读入写出保留原始分辨率与帧率codec参数为 FourCC 码默认MP4V输出目录不存在时自动创建。典型用途是把数据集中的掩码视频转成 OpenCV 可稳定解码的编码。Label Utils三元整数标签体系LabelName 是int与Enum的混合枚举全库样本标签约定为成员值语义LabelName.UNKNOWN-1未知/未定义标签LabelName.NORMAL0正常样本LabelName.ABNORMAL1异常样本由于继承了int可直接与数据框中的整型label_index比较——例如 split_by_label 正是按label_index 0/1切分正常与异常子集。Bounding Box Utils掩码、框与异常图三方互转anomalib.data.utils.boxes 提供三个互转函数坐标统一采用xyxy左上-右下格式masks_to_boxes掩码 → 框 分数masks_to_boxes 输入(B,1,H,W)、(B,H,W)或(H,W)的掩码批次流程为统一 reshape 为(B,1,H,W)并转 float按设备选择 connected_components_cpu /connected_components_gpu做连通域标记对每个连通域取其像素坐标的 min/max 得到框若传入anomaly_maps每个框的分数取框内异常图的最大值。返回两个长度B的列表框列表(N,4)张量与分数列表。boxes_to_masks 与 boxes_to_anomaly_mapsboxes_to_masks按xyxy填充1输出(B,H,W)二值掩码boxes_to_anomaly_maps把每个框区域填成该框分数重叠区域取最高分内部逐框max(dim0)归并——这是仅有框级标注数据集构造像素级评估输入的关键工具。scale_boxes分辨率对齐scale_boxes 按new_size / image_size的比例向量逐坐标缩放用于数据增广resize后把标注框同步映射到新尺寸。Dataset Split Utils面向异常检测的划分模式anomalib.data.utils.split 的模块文档指出其适用场景测试集缺正常图像、需要验证集、以及保持类别分布的划分。三个枚举划分类型与获取策略Splittrain/val/testTestSplitModeNONE无测试划分、FROM_DIR从目录读取、SYNTHETIC合成测试集ValSplitModeNONE、SAME_AS_TEST、FROM_TRAIN从训练集切出、FROM_TEST、SYNTHETIC、FROM_DIR数据集自带验证目录。这些枚举由各图像/深度 DataModule 在setup阶段消费决定验证集与测试集的来源策略。random_split带标签感知与可复现性random_split 的签名与约束splits random_split(dataset, split_ratio, label_awareFalse, seedNone)split_ratio为单个float时自动展开为[1-x, x]所有比例之和必须为 1 且每项严格位于 (0,1) 区间否则抛ValueErrorlabel_awareTrue且样本含label_index列时先按groupby(label_index)分组在每个标签内部独立随机划分后再合并——从而保持各子集类别分布一致seed通过torch.Generator().manual_seed(seed)控制randperm保证可复现子集长度按floor计算后余数循环补齐出现零长度子集时会打 warning提示某子集可能缺失正常或异常图像。配套的 concatenate_datasets 用数据集运算串联多个子集split_by_label 则直接把数据集二分为正常label 0与异常label 1两部分二者长度之和等于原数据集。小结anomalib.data.utils是 Anomalib 数据层的公共地基DirType/validate_path定义了私有数据集的目录契约与安全边界download_and_extract让内置数据集具备哈希可信、解压安全的自动获取能力read_image/read_mask/read_depth_image统一了输入数据的归一化与张量化口径ClipsIndexer解决了视频场景帧-掩码对齐问题boxes三件套打通了掩码-框-异常图三种标注形态而random_split与三个划分枚举则支撑 DataModule 的可配置数据划分策略。当你在 datamodules 中扩展自定义数据集时建议优先复用这些既有工具而非重复实现以保证与内置管线在标签编码LabelName、目录命名DirType和输出命名generate_output_image_filename上的行为一致。【免费下载链接】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），仅供参考