ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/opencv.md

@@ -0,0 +1,870 @@
+# OpenCV 模块 (cv)
+
+提供图像读写、颜色与阈值、滤波、几何变换、绘制、模板/特征匹配、轮廓、形态学、直方图、霍夫、扫码等能力。
+可通过 `require("cv")` 或 `require("opencv")` 获取。无中文别名。方法与常量对齐 JS `cv`。
+
+注意：
+
+- Mat 用字符串句柄表示。
+- 多数算子返回新句柄；`rectangle` / `circle` / `line` / `putText` / `fillPoly` / `polylines` / `drawContours` / `floodFill` / `ellipse` / `drawMarker` / `arrowedLine` / `fillConvexPoly` 等会就地修改输入 Mat（或 options 中指定的目标句柄）。
+- 与 `image` 可通过 `fromImageId` / `toImageId` 互通（独立拷贝）。
+- 路径 / msbundle / imageId / `screen` 等读图只用 `imread`；其它 API 只接受 Mat 句柄；`imdecode` 只解 base64。
+- 用完请 `release` / `releaseAll`。
+- 颜色参数为 **BGR**；也可用 `#RRGGBB`。
+- options 用 Lua 表：`{ code = cv.COLOR_BGR2GRAY }`；点集用 `{ { x = 1, y = 2 }, ... }`。
+
+## 功能一览
+
+| 类别 | API |
+| --- | --- |
+| 读图 / 截屏 | `capture` · `imread` · `imdecode` · `imwrite` · `imencode` · `fromImageId` / `toImageId` |
+| Mat | `Mat` / `zeros` / `ones` · `clone` · `empty` / `isRelease` · `release` / `releaseAll` · `getSize` / `at` / `set` · `copyTo` |
+| 颜色 / 阈值 | `cvtColor` · `threshold` · `adaptiveThreshold` · `inRange` · `CLAHE` / `equalizeHist` |
+| 算术 / 位运算 | `add` / `subtract` / `multiply` / `divide` · bitwise_* · `absdiff` · `addWeighted` · `convertScaleAbs` · `normalize` / `norm` · `meanStdDev` · `findNonZero` · `countNonZero` · `minMaxLoc` / `mean` / `sum` · `split` / `merge` · `hconcat` / `vconcat` · `LUT` · `compare` · `min` / `max` · `extractChannel` |
+| 滤波边缘 | `GaussianBlur` / `blur` / `medianBlur` / `bilateralFilter` / `boxFilter` · `Canny` / `Sobel` / `Laplacian` / `Scharr` · `filter2D` · `pyrDown` / `pyrUp` · `fastNlMeansDenoising` / `fastNlMeansDenoisingColored` · `inpaint` |
+| 几何 | `resize` / `crop` / `rotate` / `flip` · `copyMakeBorder` · `warpAffine` / `warpPerspective` · `getRotationMatrix2D` · `getAffineTransform` · `getPerspectiveTransform` · `invertAffineTransform` · `findHomography` · `perspectiveTransform` · `estimateAffine2D` / `estimateAffinePartial2D` · `getRectSubPix` · `phaseCorrelate` |
+| 绘制 | `rectangle` / `circle` / `line` / `ellipse` / `arrowedLine` / `drawMarker` · `putText` / `fillPoly` / `fillConvexPoly` / `polylines` / `drawContours` · `getTextSize` |
+| 匹配 | `matchTemplate` / `matchTemplateLoc` · `SIFT` / `ORB` / `FAST` · `BFMatcher` / `knnMatch` · `FlannBasedMatcher` / `flannKnnMatch` · `drawKeypoints` / `drawMatches` |
+| 轮廓 | `findContours` · `boundingRect` / `minAreaRect` / `boxPoints` · `contourArea` / `arcLength` / `approxPolyDP` / `convexHull` / `convexityDefects` / `isContourConvex` · `moments` / `HuMoments` / `matchShapes` · `pointPolygonTest` · `fitEllipse` / `fitLine` / `minEnclosingCircle` |
+| 霍夫 / 连通域 | `HoughLinesP` / `HoughCircles` · `connectedComponents` / `connectedComponentsWithStats` · `distanceTransform` · `floodFill` · `goodFeaturesToTrack` / `cornerHarris` / `cornerSubPix` |
+| 直方图 | `calcHist` · `compareHist` · `calcBackProject` |
+| 扫码 | `encodeQRCode` · `detectQRCode` · `detectBarcode` |
+
+## 已导出方法
+
+读图/截屏：`capture` · `imread` · `imdecode` · `imwrite` · `imencode` · `fromImageId` · `toImageId`
+
+Mat：`Mat` · `zeros` · `ones` · `clone` · `empty` · `isRelease` · `release` · `releaseAll` · `getSize` · `at` · `set` · `copyTo`
+
+颜色/阈值：`cvtColor` · `threshold` · `adaptiveThreshold` · `inRange` · `CLAHE` · `equalizeHist`
+
+算术/位运算：`add` · `subtract` · `multiply` · `divide` · `bitwise_and` · `bitwise_or` · `bitwise_xor` · `bitwise_not` · `absdiff` · `addWeighted` · `convertScaleAbs` · `normalize` · `norm` · `meanStdDev` · `findNonZero` · `countNonZero` · `minMaxLoc` · `mean` · `sum` · `split` · `merge` · `hconcat` · `vconcat` · `LUT` · `compare` · `min` · `max` · `extractChannel`
+
+滤波/边缘：`GaussianBlur` · `blur` · `medianBlur` · `bilateralFilter` · `boxFilter` · `Canny` · `Sobel` · `Laplacian` · `Scharr` · `filter2D` · `pyrDown` · `pyrUp` · `fastNlMeansDenoising` · `fastNlMeansDenoisingColored` · `inpaint`
+
+几何：`resize` · `crop` · `rotate` · `flip` · `copyMakeBorder` · `warpAffine` · `warpPerspective` · `getRotationMatrix2D` · `getAffineTransform` · `getPerspectiveTransform` · `invertAffineTransform` · `findHomography` · `perspectiveTransform` · `estimateAffine2D` · `estimateAffinePartial2D` · `getRectSubPix` · `phaseCorrelate`
+
+绘制：`rectangle` · `circle` · `line` · `ellipse` · `arrowedLine` · `drawMarker` · `putText` · `fillPoly` · `fillConvexPoly` · `polylines` · `drawContours` · `getTextSize`
+
+匹配/轮廓/形态学：`matchTemplate` · `matchTemplateLoc` · `SIFT` · `ORB` · `FAST` · `BFMatcher` · `knnMatch` · `FlannBasedMatcher` · `flannKnnMatch` · `drawKeypoints` · `drawMatches` · `findContours` · `boundingRect` · `minAreaRect` · `boxPoints` · `contourArea` · `arcLength` · `approxPolyDP` · `convexHull` · `convexityDefects` · `isContourConvex` · `moments` · `HuMoments` · `matchShapes` · `pointPolygonTest` · `fitEllipse` · `fitLine` · `minEnclosingCircle` · `erode` · `dilate` · `morphologyEx` · `getStructuringElement`
+
+霍夫/连通域/直方图/扫码：`HoughLinesP` · `HoughCircles` · `connectedComponents` · `connectedComponentsWithStats` · `distanceTransform` · `floodFill` · `goodFeaturesToTrack` · `cornerHarris` · `cornerSubPix` · `calcHist` · `compareHist` · `calcBackProject` · `encodeQRCode` · `detectQRCode` · `detectBarcode`
+
+```lua
+local cv = require("cv")
+local file = require("file")
+
+local src = cv.capture()
+local gray = cv.cvtColor(src, { code = cv.COLOR_BGR2GRAY })
+local edges = cv.Canny(gray, { threshold1 = 100, threshold2 = 200 })
+local feat = cv.SIFT(gray, { nfeatures = 500 })
+if feat then
+  logi("keypoints=" .. tostring(#feat.keypoints))
+  cv.release(feat.descriptors)
+end
+cv.imwrite(file.getInternalDir("documents") .. "/edges.png", edges)
+cv.releaseAll()
+```
+
+### capture / Mat - 截屏为 Mat
+
+```lua
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@return Mat|nil
+function capture(x, y, ex, ey) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `x` | number | 否 | 0 | 区域左上角 X 坐标 |
+| `y` | number | 否 | 0 | 区域左上角 Y 坐标 |
+| `ex` | number | 否 | 0 | 区域右下角 X 坐标 |
+| `ey` | number | 否 | 0 | 区域右下角 Y 坐标 |
+
+无参或全 0 表示全屏。
+
+**返回值：**
+
+| 类型 | 描述 |
+| --- | --- |
+| `string` | Mat 句柄，失败返回 `nil` |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local full = cv.capture()
+local roi = cv.capture(100, 100, 300, 300)
+cv.release(full)
+cv.release(roi)
+```
+
+### imread / Mat - 读取图片为 Mat（唯一路径类入口）
+
+```lua
+---@param path string
+---@return Mat|nil
+function imread(path) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `path` | string | 是 | - | 见下方支持的输入源 |
+
+**支持的输入源：**
+
+| 输入 | 说明 |
+| --- | --- |
+| msbundle/res 相对路径 | 如 `"template.png"`、`"images/logo.jpg"` |
+| 手机绝对路径 | 如 documents 下文件 |
+| `$MS_IMG$_…` | `image` 模块 imageId |
+| `"screen"` | 当前屏幕截图 |
+| `"shortcut"` | HID 快捷指令截图 |
+| `"actionScreenshot"` | HID 系统截图 |
+| `"vpnScreenshot"` | VPN/iDevice 截图 |
+| `http://` / `https://` | 网络图片 |
+| `media:n` | 相册第 n 张（从 1 起） |
+| `data:image/...;base64,...` | data URI |
+
+**返回值：**
+
+| 类型 | 描述 |
+| --- | --- |
+| `string` | Mat 句柄，失败返回 `nil` |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local a = cv.imread("template.png")
+local dir = file.getInternalDir("documents")
+local b = cv.imread(`${dir}/shot.jpg`)
+local imageId = image.captureFullScreen()
+local c = cv.imread(imageId)
+image.release(imageId)
+cv.release(a)
+cv.release(b)
+cv.release(c)
+```
+
+### imdecode / Mat - 解码 base64 为 Mat
+
+```lua
+---@param data string
+---@return Mat|nil
+function imdecode(data) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `data` | string | 是 | - | 纯 base64，或 `data:image/...;base64,...` |
+
+**说明：** 不解析文件路径 / msbundle / imageId；路径类请用 `imread`。常与 `imencode` 成对使用。
+
+**返回值：** Mat 句柄；失败 `nil`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local m = cv.imread("template.png")
+local b64 = cv.imencode(".png", m)
+local again = cv.imdecode(b64)
+cv.release(m)
+cv.release(again)
+```
+
+### imwrite / Mat - 保存 Mat 到本地文件
+
+```lua
+---@param path string
+---@param mat Mat
+---@return boolean
+function imwrite(path, mat) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `path` | string | 是 | - | 本地绝对路径（写入磁盘，不是 msbundle） |
+| `mat` | Mat | 是 | - | Mat 句柄 |
+
+**返回值：** 成功 `true`，失败 `false`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local src = cv.capture()
+cv.imwrite(`${file.getInternalDir("documents")}/out.png`, src)
+cv.release(src)
+```
+
+### imencode / Mat - 编码 Mat 为 base64
+
+```lua
+---@param ext string
+---@param mat Mat
+---@param quality number?
+---@return string|nil
+function imencode(ext, mat, quality) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `ext` | string | 是 | - | 如 `.png` / `.jpg` / `png` |
+| `mat` | Mat | 是 | - | Mat 句柄 |
+| `quality` | number | 否 | 90 | JPEG 质量（仅 jpg 有效） |
+
+**返回值：** 纯 base64 字符串（无 data URI 前缀）；失败 `nil`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local b64 = cv.imencode(".jpg", mat, { quality = 85 })
+```
+
+### fromImageId / toImageId - 与 image 互通
+
+```lua
+---@param imageId string
+---@return Mat|nil
+function fromImageId(imageId) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `imageId` | string | 是 | - | `image` 模块句柄 |
+| `mat` | Mat | 是 | - | `cv` Mat 句柄 |
+
+**说明：** 均为独立拷贝。`fromImageId(id)` 与 `imread(id)` 对 imageId 效果相同。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local imageId = image.captureFullScreen()
+local mat = cv.fromImageId(imageId)
+image.release(imageId)
+local outId = cv.toImageId(mat)
+cv.release(mat)
+image.release(outId)
+```
+
+### Mat / zeros / ones - 创建矩阵
+
+```lua
+---@param options table
+---@return Mat|nil
+function Mat(options) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `rows` / `cols` | number | 是 | - | 行 / 列 |
+| `type` | number | 否 | `CV_8UC3` | 如 `cv.CV_8UC1` |
+| `scalar` | number[] | 否 | - | 仅 `Mat`：填充值 |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local z = cv.zeros({ rows = 100, cols = 100, type = cv.CV_8UC3 })
+local filled = cv.Mat({ rows = 10, cols = 10, type = cv.CV_8UC1, scalar = [255] })
+cv.release(z)
+cv.release(filled)
+```
+
+### clone / empty / isRelease / release / releaseAll
+
+```lua
+---@param mat Mat
+---@return Mat|nil
+function clone(mat) end
+```
+
+**说明：**
+
+- `clone` 返回新句柄。
+- `empty`：无效句柄或空 Mat 为 `true`。
+- `isRelease`：句柄已释放为 `true`。
+- `releaseAll`：释放当前全部 Mat 句柄。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local a = cv.capture()
+local b = cv.clone(a)
+cv.release(a)
+logi(cv.isRelease(a)); // true
+cv.release(b)
+```
+
+### getSize / at / set / copyTo
+
+```lua
+---@param mat Mat
+---@return MatInfo|nil
+function getSize(mat) end
+```
+
+---
+
+### cvtColor - 颜色空间转换
+
+```lua
+---@param mat Mat
+---@param code number
+---@return Mat|nil
+function cvtColor(mat, code) end
+```
+
+### threshold - 固定阈值
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function threshold(mat, options) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `thresh` | number | 否 | 127 | 阈值 |
+| `maxval` | number | 否 | 255 | 最大值 |
+| `type` | number | 否 | `THRESH_BINARY` | 如 `THRESH_BINARY` / `THRESH_OTSU` |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local bin = cv.threshold(gray, { thresh = 127, maxval = 255, type = cv.THRESH_BINARY })
+local otsu = cv.threshold(gray, { type = cv.THRESH_BINARY | cv.THRESH_OTSU })
+```
+
+### adaptiveThreshold - 自适应阈值
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function adaptiveThreshold(mat, options) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `maxValue` | number | 否 | 255 | 最大值 |
+| `adaptiveMethod` | number | 否 | `ADAPTIVE_THRESH_GAUSSIAN_C` | 或 `ADAPTIVE_THRESH_MEAN_C` |
+| `thresholdType` | number | 否 | `THRESH_BINARY` | |
+| `blockSize` | number | 否 | 11 | 奇数邻域 |
+| `C` | number | 否 | 2 | 常数偏移 |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local bin = cv.adaptiveThreshold(gray, {
+  maxValue = 255,
+  adaptiveMethod = cv.ADAPTIVE_THRESH_GAUSSIAN_C,
+  thresholdType = cv.THRESH_BINARY,
+  blockSize = 11,
+  C = 2,
+})
+```
+
+### inRange - 范围掩膜
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function inRange(mat, options) end
+```
+
+**参数：** `lowerb` / `upperb` 为各通道下/上限数组。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local hsv = cv.cvtColor(src, { code = cv.COLOR_BGR2HSV })
+local mask = cv.inRange(hsv, { lower = [0, 80, 80], upper = [20, 255, 255] })
+```
+
+### countNonZero / minMaxLoc / mean / split / merge
+
+```lua
+---@param mat Mat
+---@return number
+function countNonZero(mat) end
+```
+
+---
+
+### GaussianBlur / blur / medianBlur / bilateralFilter
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function GaussianBlur(mat, options) end
+```
+
+`ksize` 可为 `5`、`[5,5]` 或 `{ width, height }`。高斯核尺寸需为奇数。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local g = cv.GaussianBlur(src, { ksize = 5, sigmaX = 1.5 })
+local m = cv.medianBlur(src, { ksize = 5 })
+local b = cv.bilateralFilter(src, { d = 9, sigmaColor = 75, sigmaSpace = 75 })
+```
+
+### Canny / Sobel / Laplacian / equalizeHist
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function Canny(mat, options) end
+```
+
+**Canny 参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `threshold1` | number | 否 | 100 | 低阈值 |
+| `threshold2` | number | 否 | 200 | 高阈值 |
+| `apertureSize` | number | 否 | 3 | Sobel 孔径 |
+| `L2gradient` | boolean | 否 | false | 是否用 L2 范数 |
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local edges = cv.Canny(gray, { threshold1 = 50, threshold2 = 150 })
+local sx = cv.Sobel(gray, { dx = 1, dy = 0, ksize = 3 })
+local histEq = cv.equalizeHist(gray)
+```
+
+### resize - 缩放
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function resize(mat, options) end
+```
+
+用 `width`/`height` 指定目标尺寸；也可设为 0 并用 `fx`/`fy` 按比例缩放。`interpolation` 如 `cv.INTER_LINEAR`、`cv.INTER_AREA`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local small = cv.resize(src, { width = 360, height = 640 })
+local half = cv.resize(src, { fx = 0.5, fy = 0.5, interpolation = cv.INTER_AREA })
+```
+
+### crop - 裁剪 ROI（拷贝）
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function crop(mat, options) end
+```
+
+参数与 `cv.capture` / `image.captureFullScreen` 一致，使用左上角与右下角。
+
+参数为 `{ x, y, ex, ey }`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local roi = cv.crop(src, { x = 10, y = 10, ex = 110, ey = 110 })
+```
+
+### rotate / flip / copyMakeBorder
+
+```lua
+---@param mat Mat
+---@param rotateCode number
+---@return Mat|nil
+function rotate(mat, rotateCode) end
+```
+
+### getRotationMatrix2D / warpAffine
+
+```lua
+---@param options table
+---@return Mat|nil
+function getRotationMatrix2D(options) end
+```
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local M = cv.getRotationMatrix2D({ center = { x = 100, y = 100 }, angle = 30, scale = 1 })
+local out = cv.warpAffine(src, { M, width = 200, height = 200 })
+cv.release(M)
+cv.release(out)
+```
+
+### rectangle / circle / line / putText - 就地绘制
+
+```lua
+---@param mat Mat
+---@param options RectangleOptions
+---@return Mat|nil
+function rectangle(mat, options) end
+```
+
+就地修改并返回**同一句柄**。`color` 为 BGR 数组或 `#RRGGBB`。
+
+**rectangle 参数：** `pt1`+`pt2`，或 `rect`；以及 `color`、`thickness`。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+cv.rectangle(src, {
+  pt1 = { x = 10, y = 10 },
+  pt2 = { x = 100, y = 80 },
+  color = [0, 0, 255],
+  thickness = 2,
+})
+cv.circle(src, { center = { x = 50, y = 50 }, radius = 20, color = "#00FF00", thickness = -1 })
+cv.line(src, { pt1 = { x = 0, y = 0 }, pt2 = { x = 100, y = 100 }, color = [255, 0, 0], thickness = 2 })
+cv.putText(src, {
+  text = "hello",
+  org = { x = 20, y = 40 },
+  fontFace = cv.FONT_HERSHEY_SIMPLEX,
+  fontScale = 1,
+  color = [255, 255, 255],
+  thickness = 2,
+})
+```
+
+### fillPoly / polylines / drawContours
+
+```lua
+---@param mat Mat
+---@param options table
+---@return Mat|nil
+function fillPoly(mat, options) end
+```
+
+就地绘制。`contourIdx` 为 `-1`（默认）表示画全部。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+cv.polylines(src, {
+  pts = [[{ x = 0, y = 0 }, { x = 100, y = 0 }, { x = 100, y = 80 }, { x = 0, y = 80 }]],
+  isClosed = true,
+  color = [0, 255, 0],
+  thickness = 2,
+})
+```
+
+---
+
+### matchTemplate / matchTemplateLoc
+
+```lua
+---@param image Mat
+---@param templ Mat
+---@param methodOrOptions table?
+---@return Mat|nil
+function matchTemplate(image, templ, methodOrOptions) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `image` | Mat | 是 | - | 大图 |
+| `templ` | Mat | 是 | - | 模板（须小于大图） |
+| `method` | number | 否 | `TM_CCOEFF_NORMED` | 匹配方法 |
+
+**matchTemplateLoc 返回：** `{ x, y, minVal, maxVal }`（最佳位置取自 max 或 min，取决于 method）。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local loc = cv.matchTemplateLoc(src, templ, { method = cv.TM_CCOEFF_NORMED })
+logi(`best=(${loc.x},${loc.y}) max=${loc.maxVal}`)
+cv.rectangle(src, {
+  pt1 = { x = loc.x, y = loc.y },
+  pt2 = { x = loc.x + tw, y = loc.y + th },
+  color = [0, 0, 255],
+  thickness = 2,
+})
+```
+
+### findContours
+
+```lua
+---@param mat Mat
+---@param options table?
+function findContours(mat, options) end
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `mode` | number | 否 | `RETR_EXTERNAL` | 如 `RETR_LIST` / `RETR_TREE` |
+| `method` | number | 否 | `CHAIN_APPROX_SIMPLE` | 如 `CHAIN_APPROX_NONE` |
+
+**返回值：** `contours` 为点集；`hierarchy` 为每个轮廓的 `[next, prev, child, parent]`（`-1` 表示无）。
+
+输入一般为二值图。
+
+**示例：**
+
+```lua
+local cv = require("cv")
+local { contours, hierarchy } = cv.findContours(bin, { mode = cv.RETR_TREE, method = cv.CHAIN_APPROX_SIMPLE })
+logi(`count=${contours.length} h0=${hierarchy[0]}`)
+```
+
+### boundingRect / minAreaRect / contourArea / arcLength / approxPolyDP
+
+```lua
+---@param matOrPoints Mat|Point[]
+---@return Rect|nil
+function boundingRect(matOrPoints) end
+```
+
+**示例：**
+
+```lua
+local cv = require("cv")
+for _, c in ipairs(contours) do
+  local area = cv.contourArea(c)
+  if (area < 100) continue
+  local rect = cv.boundingRect(c)
+  local hull = cv.convexHull(c)
+  local approx = cv.approxPolyDP(c, { epsilon = 0.02 * cv.arcLength(c, true), closed = true })
+  cv.rectangle(src, { rect, color = {0, 255, 0}, thickness = 1 })
+end
+```
+
+---
+
+## 算术 / 直方图 / Flann / 扫码 / 矩阵
+
+### add / subtract / multiply / divide
+
+```lua
+---@param src1 Mat
+---@param options { src2: Mat, mask?: Mat, scale?: number }
+---@return Mat|nil
+function add(src1, options) end
+```
+
+`multiply` / `divide` 可用 `scale`。失败返回 `nil`。
+
+```lua
+local sum = cv.add(a, { src2 = b })
+local scaled = cv.multiply(a, { src2 = b, scale = 0.5 })
+```
+
+### normalize / norm / meanStdDev / findNonZero / hconcat / vconcat
+
+```lua
+local n01 = cv.normalize(gray, { alpha = 0, beta = 255, normType = cv.NORM_MINMAX })
+local pts = cv.findNonZero(mask)
+local side = cv.hconcat({ left, right })
+```
+
+### getPerspectiveTransform / getAffineTransform
+
+透视 ≥4 点，仿射 ≥3 点。
+
+```lua
+local M = cv.getPerspectiveTransform({
+  srcPoints = { { x = 10, y = 10 }, { x = 200, y = 20 }, { x = 190, y = 300 }, { x = 20, y = 280 } },
+  dstPoints = { { x = 0, y = 0 }, { x = 300, y = 0 }, { x = 300, y = 400 }, { x = 0, y = 400 } },
+})
+local warped = cv.warpPerspective(src, { M = M, width = 300, height = 400 })
+```
+
+### FlannBasedMatcher / flannKnnMatch
+
+SIFT 等浮点描述子可用 Flann；ORB 建议 `BFMatcher` + `NORM_HAMMING`。
+
+```lua
+local knn = cv.flannKnnMatch(f2.descriptors, f1.descriptors, { k = 2, ratio = 0.75 })
+```
+
+### calcHist / compareHist / calcBackProject
+
+默认通道 `{0}`、`histSize {256}`、`ranges {0, 256}`。
+
+```lua
+local h1 = cv.calcHist(gray1)
+local h2 = cv.calcHist(gray2)
+local score = cv.compareHist(h1, h2, { method = cv.HISTCMP_CORREL })
+```
+
+### encodeQRCode / detectQRCode / detectBarcode
+
+`encodeQRCode` 返回可显示/可识别的 BGR Mat。
+
+```lua
+local qrMat = cv.encodeQRCode("https://example.com")
+local qr = cv.detectQRCode(qrMat) -- { decoded, points }
+```
+
+### filter2D / ellipse / getTextSize
+
+`ellipse` 就地绘制；`thickness = cv.FILLED` 表示填充。
+
+---
+
+## 特征点 / 描述子 / 匹配 / 单应
+
+返回 `{ keypoints, descriptors }`。描述子是 Mat 句柄，用完需 `cv.release(descriptors)`。
+
+`KeyPoint`：`x` / `y` / `size` / `angle` / `response` / `octave` / `class_id`
+`DMatch`：`queryIdx` / `trainIdx` / `distance`
+
+### SIFT / ORB / FAST
+
+```lua
+local feat = cv.SIFT(gray, { nfeatures = 500 })
+local orb = cv.ORB(gray, { nfeatures = 500 })
+local fast = cv.FAST(gray, { threshold = 20, nonmaxSuppression = true })
+```
+
+### BFMatcher / knnMatch / drawKeypoints / drawMatches
+
+```lua
+local matches = cv.BFMatcher(f2.descriptors, f1.descriptors, { normType = cv.NORM_HAMMING })
+local vis = cv.drawKeypoints(src, { keypoints = feat.keypoints, color = {0, 255, 0} })
+```
+
+也支持对象写法：`cv.BFMatcher({ queryDescriptors = d1, trainDescriptors = d2 })`。
+
+### findHomography / warpPerspective / perspectiveTransform
+
+```lua
+local H = cv.findHomography({ srcPoints = srcPts, dstPoints = dstPts, method = cv.RANSAC })
+local corners = cv.perspectiveTransform(pts, { M = H })
+```
+
+### goodFeaturesToTrack / HoughLinesP / HoughCircles / CLAHE / pyrDown / pyrUp / Scharr / boxFilter / floodFill
+
+```lua
+local corners = cv.goodFeaturesToTrack(gray, { maxCorners = 100, qualityLevel = 0.01, minDistance = 10 })
+local lines = cv.HoughLinesP(edges, { threshold = 50, minLineLength = 30, maxLineGap = 10 })
+local circles = cv.HoughCircles(gray, { method = cv.HOUGH_GRADIENT, dp = 1, minDist = 30 })
+local eq = cv.CLAHE(gray, { clipLimit = 2.0 })
+```
+
+`floodFill` 就地填充。
+
+### convexHull / moments / HuMoments / matchShapes / connectedComponentsWithStats / distanceTransform
+
+```lua
+local hull = cv.convexHull(contour)
+local m = cv.moments(contour)
+local d = cv.matchShapes(c1, c2, { method = cv.CONTOURS_MATCH_I1 })
+```
+
+---
+
+## Photo / Core / 绘制扩展
+
+### inpaint / fastNlMeansDenoising / fastNlMeansDenoisingColored
+
+```lua
+local out = cv.inpaint(src, { mask = mask, flags = cv.INPAINT_TELEA })
+local d1 = cv.fastNlMeansDenoising(gray, { h = 3 })
+local d2 = cv.fastNlMeansDenoisingColored(src, { h = 3, hColor = 3 })
+```
+
+### LUT / compare / min / max / extractChannel / sum
+
+`cmpop` 使用 `CMP_EQ` / `CMP_GT` / `CMP_GE` / `CMP_LT` / `CMP_LE` / `CMP_NE`。
+
+```lua
+local maskGt = cv.compare(a, { src2 = b, cmpop = cv.CMP_GT })
+```
+
+### invertAffineTransform / getRectSubPix / phaseCorrelate / estimateAffine2D / estimateAffinePartial2D
+
+```lua
+local shift = cv.phaseCorrelate(prevGray, { src2 = gray })
+local affine = cv.estimateAffinePartial2D({ srcPoints = srcPts, dstPoints = dstPts, method = cv.RANSAC })
+```
+
+### cornerHarris / cornerSubPix / boxPoints / pointPolygonTest / minEnclosingCircle / fitEllipse / fitLine
+
+```lua
+local line = cv.fitLine(points) -- { vx, vy, x0, y0 }
+local ell = cv.fitEllipse(contour) -- { center, size, angle }
+```
+
+### connectedComponents / convexityDefects / isContourConvex
+
+```lua
+local cc = cv.connectedComponents(bin, { connectivity = 8 })
+local defects = cv.convexityDefects(contour, { hull = hull })
+cv.release(cc.labels)
+```
+
+### drawMarker / arrowedLine / fillConvexPoly（就地）
+
+```lua
+cv.drawMarker(src, { position = { x = 100, y = 80 }, markerType = cv.MARKER_CROSS })
+cv.arrowedLine(src, { pt1 = { x = 10, y = 10 }, pt2 = { x = 120, y = 80 }, color = {0, 255, 0} })
+cv.fillConvexPoly(src, { pts = { { x = 20, y = 20 }, { x = 70, y = 20 }, { x = 45, y = 60 } }, color = {128, 0, 128} })
+```
+
+## 常用常量
+
+挂在 `cv` 上，例如：
+
+- 颜色：`COLOR_BGR2GRAY`、`COLOR_RGB2GRAY`、`COLOR_BGR2HSV`、`COLOR_BGR2RGB`、…
+- 阈值：`THRESH_BINARY`、`THRESH_OTSU`、…
+- 模板匹配：`TM_CCOEFF_NORMED`、…
+- 轮廓：`RETR_TREE`、`CHAIN_APPROX_SIMPLE`
+- 匹配：`NORM_HAMMING`、`NORM_L2`、`RANSAC`
+- 霍夫：`HOUGH_GRADIENT`
+- 修复：`INPAINT_TELEA`、`INPAINT_NS`
+- 比较：`CMP_GT` 等
+- 标记：`MARKER_CROSS` 等
+- 直方图：`HISTCMP_CORREL` 等
+- 线型：`LINE_AA`、`FILLED`
+