计算机视觉 / 系统课时
检查图像是否读取成功
检查图像是否读取成功
cv2.imread 读取失败时通常不会抛出详细异常,而是返回空结果,因此只看后续报错很难判断原因。本节用固定的检查顺序区分错误路径、权限问题、目录误传和文件无法解码,并给出可直接运行的诊断脚本。
学习目标
- 能正确判断
cv2.imread是否返回有效图像 - 能按路径、文件类型、权限和解码能力逐层定位失败原因
- 能从当前工作目录识别相对路径导致的读取错误
先检查返回值,再追根因
Python 中成功读取后通常得到 NumPy 数组;失败时常见结果是 None。因此业务代码至少要先判断 image is None,不能直接访问 image.shape。
读取失败的原因不止一种:相对路径可能指错位置,目标可能其实是目录,当前进程可能没有读取权限,文件也可能损坏或采用当前 OpenCV 构建不支持的编码。按照固定顺序检查,可以避免把所有问题都归结为“路径错误”。

用最小诊断脚本定位问题
把 data/input/sample.jpg 替换为实际文件后运行下面脚本。它先打印当前工作目录,再逐层验证路径、文件类型和权限,最后才调用 OpenCV 解码。
from pathlib import Path
import os
import cv2
path = Path("data/input/sample.jpg")
print(f"cwd={Path.cwd()}")
print(f"exists={path.exists()}, is_file={path.is_file()}")
# 先把文件系统问题与图像解码问题分开。
if not path.exists():
raise SystemExit("FAIL: 文件不存在")
if not path.is_file():
raise SystemExit("FAIL: 路径不是普通文件")
if not os.access(path, os.R_OK):
raise SystemExit("FAIL: 当前进程没有读取权限")
# 文件系统检查通过后,再把失败范围收敛到图像解码。
image = cv2.imread(str(path), cv2.IMREAD_COLOR)
if image is None or image.size == 0:
raise SystemExit("FAIL: OpenCV 无法解码该文件")
print(f"OK: shape={image.shape}, dtype={image.dtype}")预期输出
cwd=<PATH>
exists=True, is_file=True
OK: shape=(<HEIGHT>, <WIDTH>, 3), dtype=uint8<PATH>、<HEIGHT> 和 <WIDTH> 会随运行位置和图片尺寸变化;关键是 exists=True、is_file=True,并最终得到非空的 shape。
根据失败位置判断根因
如果脚本在“文件不存在”停止,先检查文件名、大小写和 cwd;相对路径是相对于当前工作目录解析的,不一定相对于脚本文件所在目录。若提示“路径不是普通文件”,通常是把文件夹路径误传给了 imread。
如果在权限检查处失败,应确认当前用户或运行服务对文件有读取权限。若前三项都通过,但 cv2.imread 仍然得到空结果,重点检查文件是否损坏、扩展名与真实格式是否一致,以及当前 OpenCV 是否包含对应格式的解码器。
验证修复是否真正生效
修复后再次运行同一诊断脚本,不要只以“没有报错”为标准。最终应同时满足:文件存在、路径指向普通文件、进程可读,并且 OpenCV 返回非空数组;随后再检查 shape 与 dtype 是否符合预期。
对于批量任务,建议把这套检查放在进入处理循环之前,或在每个文件读取后立即验证。这样错误会在读取阶段暴露,而不是等到 cvtColor、resize 等后续操作时报出更难理解的断言错误。