OpenCV报错解决：cornerSubPix断言失败 src.channels() == 1 的终极指南

一、 问题现象：令人头秃的 -215 断言错误

在进行相机标定、棋盘格角点提取或 Harris 角点优化时，很多开发者在调用 cv2.cornerSubPix 函数进行亚像素级精确定位时，经常会遇到如下崩溃报错：

D:\a\opencv-python\opencv-python\opencv\modules\imgproc\src\cornersubpix.cpp:66: 
error: (-215:Assertion failed) src.channels() == 1 in function 'cv::cornerSubPix'

看到满屏的红色报错和 -215 这种神秘的错误码，新手往往会感到无从下手。其实，这个报错的信息已经非常直白了：它要求输入图像的通道数必须等于 1，但你传入的图像不满足这个条件。

二、 报错原因深度解析

为什么 cv2.cornerSubPix 会强制要求单通道图像？

1. 算法原理限制：亚像素角点优化的核心是基于图像灰度梯度的变化来计算精确坐标的。彩色图片包含 B、G、R 三个通道的色彩信息，而算法只需要亮度（灰度）信息来进行数学迭代计算。
2. 默认读取习惯 ：我们平时使用 cv2.imread() 读取图片时，默认加载的是 BGR 格式的彩色图（即 3 个通道）。当你直接把这张原图丢给 cornerSubPix 时，OpenCV 检测到通道数为 3，于是触发了底层的断言保护机制，抛出异常防止后续计算出错。

三、 解决方案：一行代码轻松搞定

解决方法非常简单粗暴：在调用 **cv2.cornerSubPix** 之前，务必将你的彩色图片转换为单通道灰度图！

** 错误示范（会直接触发报错）：**

import cv2

# 假设 img 是你通过 cv2.imread 读取的原始彩色图片 (3通道)
img = cv2.imread('chessboard.jpg') 

term = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_COUNT, 30, 0.01)
# 直接把彩色图 img 传进去就会触发 channels() == 1 的断言失败
cv2.cornerSubPix(img, corners, (5, 5), (-1, -1), term) 

** 正确写法（标准操作流程）：**

import cv2

# 1. 读取原始彩色图片
img = cv2.imread('chessboard.jpg')

# 2. 【关键步骤】将图片转换为单通道灰度图
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# 3. 将 gray（单通道灰度图）作为第一个参数传入 cornerSubPix
term = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_COUNT, 30, 0.01)
cv2.cornerSubPix(gray, corners, (5, 5), (-1, -1), term)

只要加上 cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) 这行代码，99% 的情况下这个报错就能迎刃而解！

四、 进阶排查：除了通道数，还要注意这两个坑！

如果你已经把图片转成了灰度图，但依然报错或者程序运行不正常，建议顺便检查以下两个极易被忽视的细节：

1. 角点坐标的数据类型必须是 float32
cv2.cornerSubPix 对输入的角点数据类型有严格要求，必须是 32 位浮点数。如果传入的是整型或其他格式，可能会引发隐晦的错误。建议在传入前显式转换一下：

corners = corners.astype('float32')

2. 角点数组的形状要规范

OpenCV 期望接收到的 corners 形状通常是 (N, 1, 2) 或者 (N, 2) 的格式（其中 N 是角点数量）。如果你的角点数据是一维数组或者其他维度，也会导致函数无法正常工作。

五、 总结与完整代码模板

为了让大家能一步到位地解决问题，这里提供一个结合了上述所有注意事项的完整代码模板。你可以直接套用在自己的项目中：

import cv2
import numpy as np

def refine_corners(image_path, initial_corners):
    """
    安全的亚像素角点优化函数
    """
    # 1. 读取图片并转为灰度图（彻底解决 channels == 1 报错）
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 2. 确保角点数据类型为 float32
    corners = initial_corners.astype('float32')
    
    # 3. 设置迭代终止条件
    criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001)
    
    # 4. 执行亚像素优化
    refined_corners = cv2.cornerSubPix(gray, corners, (5, 5), (-1, -1), criteria)
    
    return refined_corners