黑匣开放平台文档

Appearance

On this page

OpenCV 类与对象 AI 规范 ​

本文档用于 AI 生成或转换 HexIDE 平台里的 Lua OpenCV 代码。重点解决 Python/OpenCV 代码直接照抄到 Lua 后最容易出错的类、对象、静态成员、矩阵访问问题。

导入方式 ​

所有 OpenCV Lua 代码优先使用下面写法：

lua
local opencv_lua = require("opencv_lua")
local cv = opencv_lua.cv

不要生成：

lua
local cv = require("cv")

禁用函数 ​

HexIDE 运行环境不支持 OpenCV 桌面窗口交互，AI 不要生成下面函数：

lua
cv.imshow(...)
cv.waitKey(...)
cv.destroyAllWindows()

Mat 宽高与属性 ​

Lua 中不要写 Python 的 img.shape。

错误写法：

lua
local h, w = img.shape[:2]

正确写法：

lua
local img = cv.imread("input.png")
if not img then
    print("读取图片失败")
    return
end

local h = img.height
local w = img.width

常用 Mat 属性和方法：

lua
local rows = mat.rows
local cols = mat.cols
local typ = mat:type()

实例方法必须使用冒号 ​

对象实例的方法用 : 调用，不要用 .。

Python：

python
cap = cv.VideoCapture(0)
ok, frame = cap.read()
cap.set(cv.CAP_PROP_FRAME_WIDTH, 1280)

Lua：

lua
local cap = cv.VideoCapture(0)
cap:set(cv.CAP_PROP_FRAME_WIDTH, 1280)
cap:set(cv.CAP_PROP_FRAME_HEIGHT, 720)

local ok, frame = cap:read()
if not ok or not frame then
    print("读取摄像头帧失败")
    return
end

常见实例方法示例：

lua
local ok = cap:isOpened()
local value = cap:get(cv.CAP_PROP_FPS)
cap:release()

local typ = mat:type()
local data = mat:table()

类方法与静态成员 ​

Python 为了兼容旧版本，有些类方法和常量会写成下划线形式。HexIDE 的 opencv_lua 不支持这种旧写法。

必须按类层级写：

Python 写法Lua 写法
cv.ml.SVM_create()cv.ml.SVM.create()
cv.ml.SVM_C_SVCcv.ml.SVM.C_SVC
cv.TERM_CRITERIA_MAX_ITERcv.TermCriteria.MAX_ITER

示例：

lua
local svm = cv.ml.SVM.create()
svm:setType(cv.ml.SVM.C_SVC)
svm:setKernel(cv.ml.SVM.LINEAR)

local criteria = cv.TermCriteria(cv.TermCriteria.MAX_ITER, 100, 1e-6)
svm:setTermCriteria(criteria)

AI 生成规则：

  • 看到 Python 的 xxx_create，优先转换为 xxx.create()。
  • 看到 Python 的 CLASS_CONST，优先转换为 CLASS.CONST。
  • 不要为了“看起来像 Python”而保留旧别名。

关键字参数 ​

如果 Python OpenCV 示例里使用关键字参数，Lua 中用 opencv_lua.kwargs({...})。

Python：

python
dst = cv.normalize(src, None, alpha=0, beta=255, norm_type=cv.NORM_MINMAX)

Lua：

lua
local dst = cv.normalize(src, opencv_lua.kwargs({
    alpha = 0,
    beta = 255,
    norm_type = cv.NORM_MINMAX,
}))

Python 数据结构转换 ​

PythonLua
(x, y){x, y}
(0, 0, 255){0, 0, 255}
[1, 2, 3]{1, 2, 3}
dict(a=1){ a = 1 }
len(list)#list

示例：

lua
cv.rectangle(img, {10, 20}, {200, 120}, {0, 0, 255}, 2)
cv.putText(img, "OK", {20, 50}, cv.FONT_HERSHEY_SIMPLEX, 1, {0, 255, 0}, 2)

Lua 索引与 OpenCV 索引 ​

Lua 表是 1 起始索引：

lua
local first = points[1]

但部分 OpenCV 参数仍然按 OpenCV 语义使用 0 起始，例如 drawContours 的 contourIdx。

lua
for i = 1, #contours do
    cv.drawContours(img, contours, i - 1, {0, 0, 255}, 2)
end

Mat 与 Lua table 互转 ​

如果需要在 Lua 里逐像素处理矩阵，先转成 table，处理完再转回 Mat。

lua
local rows = mat.rows
local cols = mat.cols
local typ = mat:type()
local data = mat:table()

for y = 1, rows do
    for x = 1, cols do
        local value = data[y][x]
        data[y][x] = value
    end
end

local newMat = cv.Mat.createFromArray(data, typ)

创建空 Mat：

lua
local img = cv.Mat.zeros({512, 512}, cv.CV_8UC3)

常用图片处理示例 ​

lua
local opencv_lua = require("opencv_lua")
local cv = opencv_lua.cv

local img = cv.imread("input.png")
if not img then
    print("读取图片失败")
    return
end

local gray = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
local ret, binary = cv.threshold(gray, 100, 255, cv.THRESH_BINARY)

local contours, hierarchy = cv.findContours(binary, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE)
print("轮廓数量:", #contours)

for i = 1, #contours do
    cv.drawContours(img, contours, i - 1, {0, 0, 255}, 2)
end

local ok = cv.imwrite("output.png", img)
print("保存结果:", ok)

常用摄像头示例 ​

lua
local opencv_lua = require("opencv_lua")
local cv = opencv_lua.cv

local cap = cv.VideoCapture(0)
if not cap:isOpened() then
    print("摄像头打开失败")
    return
end

cap:set(cv.CAP_PROP_FRAME_WIDTH, 1280)
cap:set(cv.CAP_PROP_FRAME_HEIGHT, 720)

while true do
    collectgarbage()

    local ok, frame = cap:read()
    if ok and frame then
        local gray = cv.cvtColor(frame, cv.COLOR_BGR2GRAY)
        cv.imwrite("latest.png", gray)
    end

    sleep(100)
end

AI 生成检查清单 ​

  • 是否使用 local cv = opencv_lua.cv。
  • 是否没有生成 cv.imshow、cv.waitKey、cv.destroyAllWindows。
  • 是否没有使用 img.shape。
  • 是否实例方法全部使用 :。
  • 是否类方法和常量使用 cv.Class.method / cv.Class.CONST。
  • 是否对 cv.imread、cap:read() 等可能失败的调用做了 nil/布尔判断。
  • 是否在摄像头循环、截图循环、推流循环中加入 sleep 或其它限速方式。