最小读图检查#

1
from pathlib import Path
2
import cv2
3

4
image_path = Path("images/demo.jpg")
5
img = cv2.imread(str(image_path))
6

7
if img is None:
8
    raise FileNotFoundError(f"failed to read image: {image_path.resolve()}")
9

10
print(img.shape, img.dtype)

shape 一般是 (height, width, channels)，OpenCV 默认按 BGR 通道读取彩色图。

常见失败原因#

• 路径写错，尤其是相对路径相对于当前运行目录，不是脚本所在目录。

• 文件名大小写不一致，Linux 区分大小写。

• 图片损坏或扩展名和真实格式不一致。

• 中文路径在某些环境下读取异常，需要先用简单英文路径排查。

批量读取时要记录失败文件#

1
bad = []
2
for p in Path("images").glob("*.jpg"):
3
    img = cv2.imread(str(p))
4
    if img is None:
5
        bad.append(str(p))
6

7
print("bad files", len(bad))
8
print(bad[:10])

读图后再谈处理#

很多视觉任务训练失败，根源是有一批图片根本没读进来。先确认图片数量、尺寸范围和通道，再进入增强、标注和模型训练。

实战复盘#

把《OpenCV 读取图片检查》用于真实视觉项目时，我会先做可视化抽查。图像任务里很多错误不会抛异常，例如颜色通道反了、检测框偏移、标签和图片不同步，但一张可视化结果就能暴露。

每个处理步骤都应该保存少量中间结果：原图、处理后图片、mask、绘制框图片或预测输出。不要只保存最终模型指标，因为指标无法告诉你是哪一步把数据处理坏了。

如果文章涉及批量处理，还要记录成功数量、失败数量和失败样本路径。视觉项目的数据量一大，没有失败清单就很难复查。

最小验收样例#

验收《OpenCV 读取图片检查》时，我会固定三张图片：一张正常样例、一张边界样例、一张容易失败的样例。每次改代码都用这三张图跑一遍，并保存输出结果。

视觉流程的验收必须能用眼睛确认。只打印数组 shape 或命令成功不够，至少要保存一张中间结果图或最终可视化图，确认处理效果和预期一致。

小结#

OpenCV 读图检查要简单直接：路径是否存在、返回是否 None、尺寸和通道是否符合预期。读图不稳，后面都不稳。