简介：这份资源面向医学图像处理初学者与骨骼分割方向的算法实践者，提供X光手掌影像下的掌骨二分类分割数据集，前景采用0/1阈值标注，边界清晰，适合练手语义分割模型或验证医学影像预处理流程。包内共2000个文件，以1486个png掩膜、512个jpg图像为主，另含1个txt类别说明与1个py可视化脚本，压缩包约15.47MB，图像统一为256×512分辨率。数据已划分训练集与测试集，训练集含1486张原图及对应mask，测试集含92张原图及对应mask，部分样本做过缩放与翻转增广，具体规则可参考classes文件。附带的Python脚本无需修改即可直接运行，随机抽取一张图片，同时展示原始图像、GT图像以及GT叠加在原图上的蒙板效果，并自动保存到当前目录，便于快速核对标注质量。目前已有193人学习，适合希望低成本上手骨分割任务、搭建训练与评估基线的读者。
1. 掌骨 X 光分割数据集：从拿到手到跑通第一个可视化
医学影像里有一类分割任务，数据量不大、类别不多，但标注成本极高，X 光下的掌骨分割就是典型。它要做的只有两件事：把每根掌骨从背景里抠出来，再把不同掌骨区分开——也就是标题里说的「2 分割」，通常指前景（骨骼）与背景的二分类，或者左右手/不同骨段的二分类。这类数据集的价值不在于规模，而在于它把「放射影像 + 像素级标注 + 类别映射文件」打包好了，省掉最耗时的标注环节。
拿到一个掌骨分割数据集，你真正要关心的不是它有多少张图，而是三件事：标注是掩膜还是多边形、classes 文件里的类别顺序对不对、X 光灰度分布会不会让模型把软组织误判成骨。这篇笔记就按「数据集结构 → classes 文件解析 → 可视化验证 → 训练前处理 → 踩坑排查 → 进阶技巧」的顺序，把一套能直接复现的流程讲清楚。适合刚接触医学图像分割的工程师，也适合想快速验证一个分割 pipeline 的熟手。
2. 拆开数据集：目录结构、标注格式与 classes 文件
2.1 先看目录，别急着写 DataLoader
掌骨 X 光数据集常见的组织方式有两种：一种是images/和masks/平行存放，文件名一一对应；另一种是train/val/test下各自带images和masks。不管哪种，第一步都是把目录树打印出来，确认图像和掩膜的数量、扩展名、命名规则是否一致。
# 打印数据集目录结构，只看两层，避免输出爆炸 find ./hand_bone_dataset -maxdepth 2 -type d | sort # 统计图像和掩膜数量，确认是否配对 echo "images: $(find ./hand_bone_dataset -path '*images*' -name '*.png' | wc -l)" echo "masks: $(find ./hand_bone_dataset -path '*masks*' -name '*.png' | wc -l)"逻辑说明：find -maxdepth 2只展开两层，防止深层目录刷屏；两条wc -l分别统计图像和掩膜数量，数量不一致说明有缺失或命名不匹配。参数上，如果你的数据是.jpg或.bmp，把-name改掉即可。这一步看起来简单，但我见过太多人直接开训，跑到一半才发现掩膜少了几十张，loss 曲线诡异波动，回头查半天。
2.2 classes 文件到底存了什么
classes.txt或classes.json是这类数据集的灵魂。它通常记录类别名和类别索引的映射，比如：
background bone或者带索引：
0 background 1 bone这里有个关键点：索引从 0 还是从 1 开始，直接决定你的掩膜像素值怎么映射。如果 classes 文件写的是0 background / 1 bone，那掩膜里像素值 0 是背景、1 是骨；如果写的是1 background / 2 bone，而你的代码按 0/1 处理，就会把背景当骨、骨当背景，训练出来的模型完全反向。常见做法是写一个解析函数，把 classes 文件读成字典，再和掩膜的唯一像素值做交叉验证。
import numpy as np from PIL import Image def parse_classes(classes_path): """解析 classes 文件，返回 {索引: 类别名} 和 {类别名: 索引}""" idx2name, name2idx = {}, {} with open(classes_path, 'r', encoding='utf-8') as f: for line in f: line = line.strip() if not line: continue parts = line.split() # 兼容 "0 background" 和 "background" 两种写法 if parts[0].isdigit(): idx, name = int(parts[0]), parts[1] else: idx, name = len(idx2name), parts[0] idx2name[idx] = name name2idx[name] = idx return idx2name, name2idx def check_mask_values(mask_path, idx2name): """检查掩膜里出现的像素值是否都在 classes 索引范围内""" mask = np.array(Image.open(mask_path)) unique_vals = np.unique(mask) print(f"掩膜唯一像素值: {unique_vals}") for v in unique_vals: if v not in idx2name: print(f"警告: 像素值 {v} 不在 classes 索引中") return unique_vals idx2name, name2idx = parse_classes('./hand_bone_dataset/classes.txt') print("类别映射:", idx2name) check_mask_values('./hand_bone_dataset/masks/0001.png', idx2name)逻辑说明：parse_classes同时兼容带索引和不带索引的写法，不带索引时按出现顺序自动编号。check_mask_values把掩膜的唯一像素值和 classes 索引比对，任何不在映射里的值都要警惕——可能是标注工具留下的边缘值，也可能是类别定义和实际标注不一致。参数上，如果你的掩膜是彩色图，需要先转灰度或按通道解析，不能直接np.unique。
2.3 图像与掩膜的配对校验
配对校验不只是数数量，还要确认文件名能对上、尺寸一致、掩膜不是全黑。写一个批量校验脚本，跑一遍比肉眼翻图靠谱得多。
import os from PIL import Image def validate_pairs(img_dir, mask_dir): img_files = sorted(os.listdir(img_dir)) mask_files = sorted(os.listdir(mask_dir)) assert len(img_files) == len(mask_files), "图像与掩膜数量不一致" issues = [] for img_name, mask_name in zip(img_files, mask_files): img_path = os.path.join(img_dir, img_name) mask_path = os.path.join(mask_dir, mask_name) img = Image.open(img_path) mask = Image.open(mask_path) if img.size != mask.size: issues.append(f"尺寸不匹配: {img_name} {img.size} vs {mask_name} {mask.size}") mask_np = np.array(mask) if mask_np.max() == 0: issues.append(f"掩膜全黑: {mask_name}") return issues issues = validate_pairs('./hand_bone_dataset/images', './hand_bone_dataset/masks') for i in issues[:10]: print(i) print(f"共发现 {len(issues)} 个问题")逻辑说明：zip按排序后一一配对，前提是图像和掩膜文件名完全一致（包括扩展名）。尺寸不匹配在 X 光数据里很常见，因为有些掩膜是原图裁剪后再标注的。掩膜全黑说明这张图没有有效标注，训练时要么剔除，要么当负样本处理。参数上，如果文件名前缀一致但扩展名不同，需要先把名字归一化再配对。
3. 可视化验证：把灰度图和掩膜叠在一起看
3.1 为什么必须先可视化再训练
X 光图像的灰度分布和自然图像完全不同，骨骼、软组织、背景的对比度低，直接看掩膜可能觉得「标得挺好」，但叠到原图上就会发现边缘偏移、细小骨段漏标。可视化是成本最低的质检手段，也是排查「模型学不动」的第一入口。常见做法是把原图转成三通道，掩膜用半透明色覆盖，再并排显示。
import matplotlib.pyplot as plt import numpy as np from PIL import Image def visualize_overlay(img_path, mask_path, alpha=0.4): img = np.array(Image.open(img_path).convert('L')) mask = np.array(Image.open(mask_path)) # 原图转 RGB，掩膜区域涂红 img_rgb = np.stack([img]*3, axis=-1) overlay = img_rgb.copy() overlay[mask > 0] = [255, 0, 0] blended = (img_rgb * (1 - alpha) + overlay * alpha).astype(np.uint8) fig, axes = plt.subplots(1, 3, figsize=(15, 5)) axes[0].imshow(img, cmap='gray'); axes[0].set_title('原图') axes[1].imshow(mask, cmap='gray'); axes[1].set_title('掩膜') axes[2].imshow(blended); axes[2].set_title('叠加') for ax in axes: ax.axis('off') plt.tight_layout() plt.savefig('overlay_check.png', dpi=150) plt.show() visualize_overlay('./hand_bone_dataset/images/0001.png', './hand_bone_dataset/masks/0001.png')逻辑说明：convert('L')把 X 光图转灰度，避免彩色通道干扰；mask > 0把所有非背景像素涂红，alpha控制透明度，太低看不清边界，太高盖住原图细节，0.3~0.5 比较合适。保存成图片而不是只show，方便批量抽查。参数上，如果掩膜是多类，需要按类别给不同颜色，不能统一涂红。
3.2 批量生成缩略图墙，快速定位脏数据
单张看效率低，批量拼成网格能一眼扫出异常样本。下面这个脚本把前 16 张的叠加图拼成 4x4 网格。
def grid_overlay(img_dir, mask_dir, n=16, cols=4): img_files = sorted(os.listdir(img_dir))[:n] rows = (n + cols - 1) // cols fig, axes = plt.subplots(rows, cols, figsize=(cols*3, rows*3)) for ax, name in zip(axes.flatten(), img_files): img = np.array(Image.open(os.path.join(img_dir, name)).convert('L')) mask_path = os.path.join(mask_dir, name) if not os.path.exists(mask_path): ax.set_title(f'缺失掩膜: {name}'); ax.axis('off'); continue mask = np.array(Image.open(mask_path)) img_rgb = np.stack([img]*3, axis=-1) img_rgb[mask > 0] = [255, 0, 0] ax.imshow(img_rgb); ax.set_title(name, fontsize=8); ax.axis('off') plt.tight_layout() plt.savefig('grid_check.png', dpi=120) grid_overlay('./hand_bone_dataset/images', './hand_bone_dataset/masks')逻辑说明：axes.flatten()把二维子图数组拉平，方便和文件列表zip。遇到缺失掩膜时直接标红提示，不中断整个流程。参数上，n和cols按你的屏幕和数据集大小调，16 张足够发现系统性问题。这一步的血泪经验是：别跳过可视化直接开训，否则你会在 loss 不降的时候怀疑模型、怀疑学习率、怀疑人生，最后发现是掩膜和图像错位。
3.3 灰度分布检查：X 光的对比度陷阱
X 光片常有曝光不均的问题，同一批数据里有的偏亮、有的偏暗。如果直接归一化到 [0,1]，暗图的骨骼细节会被压掉。建议先统计每张图的均值和方差，看看分布是否集中。
def gray_stats(img_dir, sample=50): files = sorted(os.listdir(img_dir))[:sample] means, stds = [], [] for name in files: img = np.array(Image.open(os.path.join(img_dir, name)).convert('L'), dtype=np.float32) means.append(img.mean()); stds.append(img.std()) print(f"均值范围: {min(means):.1f} ~ {max(means):.1f}") print(f"标准差范围: {min(stds):.1f} ~ {max(stds):.1f}") return means, stds gray_stats('./hand_bone_dataset/images')逻辑说明：均值和标准差范围过大，说明曝光差异明显，需要考虑直方图均衡化或自适应归一化。参数上，sample=50是抽样数量，数据量大时可以只抽一部分。如果均值集中在很窄的区间，说明数据一致性较好，常规归一化就够。
4. 训练前处理：从掩膜到标签、增强与划分
4.1 掩膜转标签：别让类别索引错位
分割模型通常要求标签是 0 到 N-1 的连续整数。如果 classes 文件里背景是 0、骨是 1，那掩膜可以直接用；如果掩膜里骨是 255，就需要映射。写一个转换函数，把原始掩膜映射成训练用标签。
def mask_to_label(mask, mapping): """mapping: {原始像素值: 训练标签}""" label = np.zeros_like(mask, dtype=np.uint8) for raw_val, new_val in mapping.items(): label[mask == raw_val] = new_val return label # 假设原始掩膜里 0 是背景，255 是骨 mapping = {0: 0, 255: 1} raw_mask = np.array(Image.open('./hand_bone_dataset/masks/0001.png')) label = mask_to_label(raw_mask, mapping) print("转换后唯一值:", np.unique(label))逻辑说明：mapping显式定义原始值到训练标签的对应关系，避免隐式假设。np.zeros_like保证输出尺寸和类型一致。参数上，如果有多类，mapping 要覆盖所有原始像素值，漏掉的会被当成背景。这一步的坑在于：有些标注工具用 1 表示背景、2 表示前景，而你按 0/1 处理，结果就是模型把背景学成前景。
4.2 数据增强：X 光图能做什么、不能做什么
医学图像增强和自然图像不一样。水平翻转要谨慎——左右手掌骨镜像后解剖结构变了，如果任务不区分左右手，翻转可以；如果区分，翻转会制造错误标签。旋转、缩放、弹性变形相对安全，亮度对比度扰动也能提升鲁棒性。
import albumentations as A train_transform = A.Compose([ A.RandomRotate90(p=0.5), A.ShiftScaleRotate(shift_limit=0.05, scale_limit=0.1, rotate_limit=15, p=0.7), A.RandomBrightnessContrast(brightness_limit=0.2, contrast_limit=0.2, p=0.5), A.ElasticTransform(alpha=1, sigma=50, p=0.3), ]) # 注意：图像和掩膜要同步变换 augmented = train_transform(image=img, mask=label)逻辑说明：ShiftScaleRotate的rotate_limit=15控制旋转角度，太大可能把骨骼转出画面；ElasticTransform模拟软组织形变，alpha和sigma控制形变强度。参数上，p是触发概率，训练集可以高一些，验证集不要用增强。关键点：图像和掩膜必须用同一个 transform，albumentations 的Compose会自动同步，但如果你手动写增强，很容易只转图像不转掩膜。
4.3 数据集划分：别按文件名顺序切
按文件名顺序切分是常见翻车点。如果数据是按患者或时间采集的，前 80% 和后 20% 可能来自不同分布，验证集指标会虚高或虚低。常见做法是先打乱索引再切，或者按患者 ID 分组切分。
import random def split_dataset(img_dir, mask_dir, val_ratio=0.2, seed=42): files = sorted(os.listdir(img_dir)) random.seed(seed) random.shuffle(files) n_val = int(len(files) * val_ratio) val_files = files[:n_val] train_files = files[n_val:] return train_files, val_files train_files, val_files = split_dataset('./hand_bone_dataset/images', './hand_bone_dataset/masks') print(f"训练集: {len(train_files)}, 验证集: {len(val_files)}")逻辑说明：random.seed(seed)保证可复现，shuffle打乱后再切，避免顺序偏差。参数上，val_ratio=0.2是常见比例，数据量小时可以降到 0.1。如果数据有患者 ID，应该按 ID 分组，确保同一患者的图不会同时出现在训练和验证集。
5. 避坑与排查：掌骨分割里最容易翻车的 5 个点
5.1 掩膜像素值和 classes 索引对不上
现象：训练 loss 一直不降，或者预测结果全是背景/全是前景。原因：掩膜里骨骼像素是 255，但代码按 1 处理，模型学到的标签全是 0。解决：用 2.2 节的check_mask_values先打印唯一像素值，再用mask_to_label显式映射，不要靠猜。
5.2 图像和掩膜尺寸不一致导致错位
现象：叠加图里掩膜整体偏移，或者边缘出现黑边。原因：部分掩膜是原图裁剪后标注的，尺寸和原图不同，resize时又没同步。解决：在validate_pairs里检查尺寸，不一致的要么重新对齐，要么剔除。如果必须 resize，图像和掩膜用同一组参数，掩膜用最近邻插值，别用双线性。
5.3 灰度归一化把骨骼细节压没了
现象：模型对细小骨段分割效果差，边缘模糊。原因：直接除以 255 做全局归一化，暗图的骨骼对比度被压缩。解决：先做直方图均衡化或 CLAHE，再归一化；或者按每张图的均值和标准差做标准化，而不是固定除以 255。
5.4 数据增强把解剖结构转坏了
现象：训练集指标很高，验证集一塌糊涂。原因：用了垂直翻转或大角度旋转，掌骨解剖结构被破坏，模型学到了错误模式。解决：医学图像增强要保守，旋转控制在 ±15 度以内，翻转只在任务不区分左右手时用。验证集不做增强。
5.5 验证集和训练集分布不一致
现象：验证 loss 比训练 loss 高很多，且不收敛。原因：按文件名顺序切分，训练集和验证集来自不同曝光条件或不同采集设备。解决：打乱后再切，或者按患者/设备分组切分。切完后用 3.3 节的灰度统计分别看训练集和验证集的均值分布，差异大就重新切。
6. 进阶技巧：用可视化反推标注质量与模型瓶颈
6.1 把预测结果和标注叠在一起看，比看指标有用
训练到一定阶段后，mIoU、Dice 这些指标只能告诉你「好不好」，不能告诉你「哪里不好」。把模型预测、人工标注、原图三者叠在一起，能直接看出模型是漏标了细小骨段，还是把软组织误判成了骨。
def compare_pred_gt(img_path, gt_path, pred_path): img = np.array(Image.open(img_path).convert('L')) gt = np.array(Image.open(gt_path)) pred = np.array(Image.open(pred_path)) img_rgb = np.stack([img]*3, axis=-1) # 绿色是标注，红色是预测，黄色是重合 vis = img_rgb.copy() vis[gt > 0] = [0, 255, 0] vis[pred > 0] = [255, 0, 0] vis[(gt > 0) & (pred > 0)] = [255, 255, 0] plt.figure(figsize=(8, 8)) plt.imshow(vis); plt.title('绿=标注 红=预测 黄=重合'); plt.axis('off') plt.savefig('compare.png', dpi=150); plt.show()逻辑说明：先涂绿再涂红，重合区域最后涂黄，这样一眼能看出漏标（只有绿）和误判（只有红）。参数上，如果类别多，需要扩展成多通道配色。这个技巧我一般用在训练中期，挑几张指标最差的样本看，比盯着 loss 曲线有效得多。
6.2 用混淆矩阵定位类别边界问题
二分割任务里，混淆矩阵能告诉你模型是把背景判成骨多，还是把骨判成背景多。前者说明模型太激进，后者说明太保守。根据这个调整pos_weight或损失函数里的类别权重。
from sklearn.metrics import confusion_matrix def seg_confusion(gt_masks, pred_masks, n_classes=2): gt_flat = np.concatenate([m.flatten() for m in gt_masks]) pred_flat = np.concatenate([m.flatten() for m in pred_masks]) cm = confusion_matrix(gt_flat, pred_flat, labels=list(range(n_classes))) print("混淆矩阵:") print(cm) return cm逻辑说明：把所有掩膜拉平后算混淆矩阵，labels指定类别顺序，避免缺失类别导致矩阵错位。参数上，n_classes=2对应二分割，多类时改大。如果背景判成骨的比例高，可以在损失里给背景更高权重，或者用 Dice Loss 替代交叉熵。
6.3 一个我常犯的错：忘了检查掩膜的位深
最后说一个很隐蔽的坑。有些掩膜保存成 16 位 PNG，np.array读出来是uint16，像素值范围 0~65535，而你的代码按uint8处理，mask > 0虽然能工作，但mask == 255这种判断会失效。我一般会在读掩膜后加一句print(mask.dtype, mask.max())，确认位深和最大值。如果是 16 位但实际只用 0 和 1，先转成uint8再处理，省得后面映射时出玄学问题。
这套流程跑下来，从拿到数据集到能开始训练，大概半天时间。真正花时间的不是写代码，而是验证数据质量——掩膜对不对、类别映射对不对、增强有没有破坏解剖结构。希望帮到你。
本文还有配套的精品资源，点击获取
