OpenCV-Python cv.add()计算结果与官方文档不符的解决求助

核心问题 #

你的问题出在输入数组的维度以及OpenCV与NumPy 2.x版本的兼容性上：当输入是一维uint8数组时，cv.add()在NumPy 2.2.6环境下默认输出了float64类型，导致饱和加法的逻辑没有生效。

解决方案1：使用二维数组（符合OpenCV图像格式） #

OpenCV的图像处理函数更适配二维数组（哪怕是单个像素），将输入改为二维uint8数组即可得到正确的饱和结果：

import cv2 as cv
import numpy as np

x = np.uint8([[250]])  # 二维数组格式
y = np.uint8([[10]])

print(f"x+y = {x+y}")
print(f"cv.add(x,y) = {cv.add(x,y)}")

输出结果：

[[4]]
[[255]]

解决方案2：手动指定输出类型 #

如果需要使用一维数组，可以在调用cv.add()时显式指定输出的 dtype 为cv.CV_8U（对应uint8），强制执行饱和加法：

import cv2 as cv
import numpy as np

x = np.uint8([250])
y = np.uint8([10])

result = cv.add(x, y, dtype=cv.CV_8U)
print(f"cv.add(x,y) = {result}")

输出结果：

[255]

原因解释 #

NumPy 2.x版本对数据类型的处理逻辑有调整，当OpenCV处理一维uint8数组时，默认的输出类型推断出现偏差，返回了float64类型。此时数值直接相加得到260，没有触发饱和截断；而当输入是二维数组（符合图像的shape），或者显式指定输出类型为uint8时，OpenCV会按照文档描述的饱和加法逻辑执行，将超过255的数值截断为255。

内容的提问来源于stack exchange，提问作者13 stef