视觉与摄像头 AI 规范 ​

本文档用于 AI 生成摄像头、模板匹配、MJPEG 推流相关 Lua 代码。参数规则已按 HexLuaAPI_IMG.hpp 和 OpenCV 封装约束整理。

⚠️ 本文档已同步更新至新版摄像头 API（v2）。旧版 CameraInit(camera_id, capture_type, resolution) 已废弃，请使用新版接口。

OpenCV 基础 ​

生成视觉代码时优先写：

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

规则：

• 读取图片用 cv.imread(path)。
• 保存图片用 cv.imwrite(path, mat)。
• Lua 中图片宽高使用 mat.width、mat.height，不要写 Python 的 shape[:2]。
• 项目内图片路径使用相对路径。
• 涉及 OpenCV 类、静态成员、实例方法、cv.Mat 与 Python 代码转换时，参考 OpenCV 类与对象 AI 规范。

摄像头设备 ​

local devices = listCameraDevices()
local formats = getCameraFormats("/dev/video0")
local ok = setCameraFormat("/dev/video0", 1280, 720, "MJPG", 60)

规则：

• listCameraDevices() 无参数，返回设备列表。
• getCameraFormats(node) 的 node 是设备路径，例如 "/dev/video0"。
• setCameraFormat(node, width, height, pix, fps)：
  • node：字符串。
  • width / height / fps：整数。
  • pix：像素格式字符串，例如 "MJPG"。
• 注意：setCameraFormat 必须在 CameraInit() 之前调用，否则无效。

摄像头初始化 ​

CameraInit()                    -- 默认 cached 模式
CameraInit(0, 0)                -- cached 模式
CameraInit(0, 1)                -- blocking 模式
CameraInit(0, 0, 640)           -- cached 模式，正方形默认 640

参数：

• unused：可选，占位参数，通常传 0 或不传
• mode：可选，采集模式，默认 0
  • 0：cached。有新帧时更新缓存；无新帧时返回上一次缓存帧
  • 1：blocking。等待新帧，适合每次调用尽量拿到新画面的场景
• square_default_size：可选，正方形取帧接口默认尺寸，默认 320

返回值：整数状态码

• 0：成功
• 1：摄像头打开失败
• 2：视频帧读取失败

AI 生成规则：如需初始化摄像头，使用上述参数结构，不要凭空生成旧版参数格式。

采集帧 ​

浅拷贝接口（适合实时推理） ​

local frame = CameraGetLatestFrame()              -- 默认 1920x1080
local frame = CameraGetLatestFrame(1280, 720)      -- 指定裁切尺寸
local square = CameraGetLatestFrameSquare()        -- 默认 320x320
local square = CameraGetLatestFrameSquare(640)     -- 指定正方形尺寸

• CameraGetLatestFrame([width [, height]])：裁切后取最新一帧，默认 1920x1080
• CameraGetLatestFrameSquare([size])：取最新正方形裁剪帧
• 返回值：成功返回 cv.Mat，失败返回 nil
• 拷贝语义：浅拷贝，复用内部缓存，速度快。适合"取图后马上推理并丢弃"的场景

深拷贝接口（适合保存/绘制） ​

local frame = CameraGetLatestFrameCopy()           -- 深拷贝完整帧
local frame = CameraGetLatestFrameCopy(1280, 720)   -- 指定尺寸深拷贝
local square = CameraGetLatestFrameSquareCopy()     -- 深拷贝正方形帧
local square = CameraGetLatestFrameSquareCopy(640)  -- 指定正方形尺寸深拷贝

• 拷贝语义：深拷贝，每次创建独立图像对象。适合 cv.imwrite()、画框、推流、GUI 显示

非阻塞取帧 ​

local has_frame, frame = CameraGetFrameNormal()
local has_frame, frame = CameraGetFrameNormal(1920, 1080)

• 固定使用 normal 非阻塞模式，不受 CameraInit() mode 参数影响
• 返回 (has_frame, frame)：has_frame=true 时有新帧，否则为 nil
• 拷贝语义：浅拷贝，适合"有新帧才处理"的实时循环

选择建议 ​

模板匹配 ​

可用函数：

ensure24BitBGR(mat)
templateMatchingStandard(...)
multiScaleTemplateMatching(...)
multiScaleTemplateMatchingNMS(...)

AI 生成规则：

• 模板匹配前确认输入是 cv.Mat。
• 图片可能需要先转为 24 位 BGR，可使用 ensure24BitBGR(mat)。
• 不要把文件路径直接传给模板匹配函数，先 cv.imread。

MJPEG 推流 ​

local ok = StartMJPEGServer(5656)
local pushed = StreamPushFrame(frame)
local stopped = StopMJPEGServer()

规则：

• StartMJPEGServer(port)：port 可选/整数，常用 5656。
• StreamPushFrame(mat)：参数必须是 cv.Mat。
• StopMJPEGServer()：停止推流服务。

AI 生成禁忌 ​

• 不要生成 cv.imshow、cv.waitKey、cv.destroyAllWindows。
• 不要写 Python 风格的 img.shape。
• 不要在没有 cv.Mat 的情况下调用模板匹配或推流。
• 不要在循环内无限创建新图像对象而不控制频率；必要时使用 collectgarbage()。