OpenCV cv2.circle() 坐标类型错误排查与修复指南

1. 问题描述

在使用 OpenCV 的 cv2.circle() 函数绘制圆形时，程序抛出如下错误：

复制代码

OpenCV(4.6.0) :-1: error: (-5:Bad argument) in function 'circle'
> Overload resolution failed:
>  - Can't parse 'center'. Sequence item with index 0 has a wrong type
>  - Can't parse 'center'. Sequence item with index 0 has a wrong type

错误核心信息：

复制代码

Can't parse 'center'. Sequence item with index 0 has a wrong type

含义：cv2.circle() 的 center（圆心坐标）参数中，索引为 0 的元素类型不正确。

2. 根本原因

cv2.circle() 要求 center 和 radius 参数必须是整数（int）类型，不能是浮点数（float）。

Python 3 中，除法运算符 / 始终返回浮点数，这是最常见的触发原因。

python 复制代码

# Python 3 中：
10 / 3   # 结果是 3.3333...（float）
10 // 3  # 结果是 3（int）

当浮点数被传入 cv2.circle() 时，OpenCV 无法解析，直接报错。

3. 常见触发场景与修复方法

3.1 场景一：除法运算产生浮点坐标

计算图像中心点时，使用 / 除法导致坐标为浮点数。

python 复制代码

height, width = img.shape[:2]

#  错误写法 ------ center 为 (360.0, 640.0)，类型为 float
center = (height / 2, width / 2)
cv2.circle(img, center, 5, (0, 0, 255), -1)

修复方法：

python 复制代码

#  方法 1：使用整除 //
center = (height // 2, width // 2)

#  方法 2：显式 int() 转换
center = (int(height / 2), int(width / 2))

cv2.circle(img, center, 5, (0, 0, 255), -1)

3.2 场景二：特征检测返回浮点坐标

cv2.goodFeaturesToTrack()、cv2.cornerHarris() 等特征检测函数返回的坐标默认是浮点型。

python 复制代码

corners = cv2.goodFeaturesToTrack(gray, 1000, 0.01, 10)

for i in corners:
    x, y = i.ravel()
    #  错误写法 ------ x, y 为 float
    # cv2.circle(img, (x, y), 2, (0, 0, 255), -1)

    #  正确写法
    cv2.circle(img, (int(x), int(y)), 2, (0, 0, 255), -1)

3.3 场景三：深度学习模型输出浮点坐标

YOLO、SSD 等目标检测模型输出的中心点坐标通常为浮点数。

python 复制代码

# 模型输出
center_x = 320.75
center_y = 240.50
radius = 15.0

#  错误写法
# cv2.circle(img, (center_x, center_y), radius, (0, 255, 0), 2)

#  正确写法 ------ center 和 radius 都要转 int
cv2.circle(img, (int(center_x), int(center_y)), int(radius), (0, 255, 0), 2)

3.4 场景四：NumPy 数组元素类型问题

从 NumPy 数组中取出的元素可能是 np.int64、np.float32 等类型，OpenCV 不一定能正确解析。

python 复制代码

import numpy as np

point = np.array([320.5, 240.7])

#  错误写法
# cv2.circle(img, tuple(point), 5, (0, 0, 255), -1)

#  正确写法
cv2.circle(img, (int(point[0]), int(point[1])), 5, (0, 0, 255), -1)

4. 快速排查方法

在报错行之前插入打印语句，定位具体是哪个变量类型不对：

python 复制代码

print(f"center = {center}, type(x) = {type(center[0])}, type(y) = {type(center[1])}")
cv2.circle(img, center, radius, color, thickness)

如果输出类似：

复制代码

center = (320.0, 240.0), type(x) = <class 'float'>, type(y) = <class 'float'>

即可确认是浮点数问题，用 int() 转换即可。

5. 防御性编程建议

在实际项目中，建议封装一个安全的画圆函数，统一处理类型转换：

python 复制代码

import cv2


def safe_circle(img, center, radius, color, thickness=1):
    """
    安全绘制圆形，自动将坐标和半径转换为整数
    """
    x = int(center[0])
    y = int(center[1])
    r = int(radius)
    cv2.circle(img, (x, y), r, color, thickness)
    return img

使用方式：

python 复制代码

# 无论传入 float 还是 int，都不会报错
safe_circle(img, (320.7, 240.3), 15.9, (0, 255, 0), 2)

6. 总结

项目	说明
报错原因	`cv2.circle()` 的 `center` 参数包含浮点数
核心规则	`center` 和 `radius` 必须是 int 类型
常见来源	`/` 除法、特征检测、模型输出、NumPy 数组
修复方式	使用 `int()` 显式转换，或使用 `//` 整除
最佳实践	封装安全函数，统一处理类型转换

一句话总结： OpenCV 绘图函数的坐标参数不接受浮点数，传入前务必用 int() 转换。