ms-vite-plugin 1.4.39 → 1.4.40

package/docs/api/opencv.md

@@ -0,0 +1,1638 @@
+# OpenCV 模块 (cv)
+
+提供图像读写、颜色与阈值、滤波、几何变换、绘制、模板/特征匹配、轮廓、形态学、直方图、霍夫、扫码等能力。模块名为 `cv`，无中文别名。
+
+注意：
+
+- Mat 用字符串句柄表示，形如 `$CV_MAT$_…`。
+- 多数算子返回新句柄；`rectangle` / `circle` / `line` / `putText` / `fillPoly` / `polylines` / `drawContours` / `floodFill` / `ellipse` / `drawMarker` / `arrowedLine` / `fillConvexPoly` / `insertChannel` / `watershed` / `grabCut` 等会就地修改输入 Mat（或 options 中指定的目标句柄）。
+- 与 `image` 可通过 `fromImageId` / `toImageId` 互通（独立拷贝）。
+- 路径 / msbundle / imageId / `screen` 等读图只用 `imread`；其它 API 只接受 Mat 句柄；`imdecode` 只解 base64。
+- 用完请 `release` / `releaseAll`（同时存活句柄上限约 32）。
+- 颜色参数为 **BGR**；也可用 `#RRGGBB`。
+
+## 功能一览
+
+| 类别 | 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` · `applyColorMap` · `decolor` |
+| 算术 / 位运算 | `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` / `insertChannel` · `mixChannels` · `pow` / `sqrt` / `exp` / `log` · `magnitude` · `cartToPolar` / `polarToCart` · `PSNR` · `scaleAdd` |
+| 滤波边缘 | `GaussianBlur` / `blur` / `medianBlur` / `bilateralFilter` / `boxFilter` / `stackBlur` · `Canny` / `Sobel` / `Laplacian` / `Scharr` · `filter2D` / `sepFilter2D` · `pyrDown` / `pyrUp` · `edgePreservingFilter` · `detailEnhance` · `pencilSketch` · `stylization` · `fastNlMeansDenoising` / `fastNlMeansDenoisingColored` · `pyrMeanShiftFiltering` |
+| 几何 | `resize` / `crop` / `rotate` / `flip` · `copyMakeBorder` · `warpAffine` / `warpPerspective` / `warpPolar` · `remap` · `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` / `AKAZE` / `BRISK` / `KAZE` / `FAST` / `AGAST` / `MSER` / `SimpleBlobDetector` · `BFMatcher` / `knnMatch` · `FlannBasedMatcher` / `flannKnnMatch` · `drawKeypoints` / `drawMatches` |
+| 轮廓 | `findContours` · `boundingRect` / `minAreaRect` / `boxPoints` · `contourArea` / `arcLength` / `approxPolyDP` / `convexHull` / `convexityDefects` / `isContourConvex` · `moments` / `HuMoments` / `matchShapes` · `pointPolygonTest` · `fitEllipse` / `fitLine` / `minEnclosingCircle` |
+| 霍夫 / 连通域 / 分割 | `HoughLines` / `HoughLinesP` / `HoughCircles` / `LSD` · `connectedComponents` / `connectedComponentsWithStats` · `distanceTransform` · `floodFill` · `goodFeaturesToTrack` / `cornerHarris` / `cornerSubPix` / `cornerMinEigenVal` / `preCornerDetect` · `spatialGradient` · `watershed` / `grabCut` · `integral` |
+| 直方图 | `calcHist` · `compareHist` · `calcBackProject` |
+| Photo / 克隆 | `inpaint` · `seamlessClone` · `colorChange` · `illuminationChange` · `textureFlattening` |
+| 扫码 / 检测 | `detectQRCode` · `detectBarcode` · `encodeQRCode` · `CascadeClassifier` · `HOGDetect` |
+
+---
+
+## 快速示例
+
+```javascript
+const src = cv.capture();
+const gray = cv.cvtColor(src, { code: cv.COLOR_BGR2GRAY });
+const edges = cv.Canny(gray, { threshold1: 100, threshold2: 200 });
+const feat = cv.SIFT(gray, { nfeatures: 500 });
+logi(`keypoints=${feat.keypoints.length}`);
+cv.imwrite(`${file.getInternalDir("documents")}/edges.png`, edges);
+cv.release(src);
+cv.release(gray);
+cv.release(edges);
+cv.release(feat.descriptors);
+```
+
+与 `image` 模块衔接：
+
+```javascript
+const imageId = image.captureScreen();
+const mat = cv.imread(imageId); // 或 cv.fromImageId(imageId)
+image.release(imageId);
+const gray = cv.cvtColor(mat, { code: cv.COLOR_BGR2GRAY });
+const outId = cv.toImageId(gray);
+cv.release(mat);
+cv.release(gray);
+image.saveTo(outId, `${file.getInternalDir("documents")}/gray.jpg`);
+image.release(outId);
+```
+
+---
+
+## 句柄与生命周期
+
+### capture - 截屏为 Mat
+
+```typescript
+function capture(
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `x` | number | 否 | 0 | 区域左上角 X 坐标 |
+| `y` | number | 否 | 0 | 区域左上角 Y 坐标 |
+| `ex` | number | 否 | 0 | 区域右下角 X 坐标 |
+| `ey` | number | 否 | 0 | 区域右下角 Y 坐标 |
+
+无参或全 0 表示全屏。
+
+**返回值：**
+
+| 类型 | 描述 |
+| --- | --- |
+| `string` | Mat 句柄，失败返回 `null` |
+
+**示例：**
+
+```javascript
+const full = cv.capture();
+const roi = cv.capture(100, 100, 300, 300);
+cv.release(full);
+cv.release(roi);
+```
+
+### imread - 读取图片为 Mat（唯一路径类入口）
+
+```typescript
+function imread(path: string): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `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 句柄，失败返回 `null` |
+
+**示例：**
+
+```javascript
+const a = cv.imread("template.png");
+const dir = file.getInternalDir("documents");
+const b = cv.imread(`${dir}/shot.jpg`);
+const imageId = image.captureScreen();
+const c = cv.imread(imageId);
+image.release(imageId);
+cv.release(a);
+cv.release(b);
+cv.release(c);
+```
+
+### imdecode - 解码 base64 为 Mat
+
+```typescript
+function imdecode(data: string): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `data` | string | 是 | - | 纯 base64，或 `data:image/...;base64,...` |
+
+**说明：** 不解析文件路径 / msbundle / imageId；路径类请用 `imread`。常与 `imencode` 成对使用。
+
+**返回值：** Mat 句柄；失败 `null`。
+
+**示例：**
+
+```javascript
+const m = cv.imread("template.png");
+const b64 = cv.imencode(".png", m);
+const again = cv.imdecode(b64);
+cv.release(m);
+cv.release(again);
+```
+
+### imwrite - 保存 Mat 到本地文件
+
+```typescript
+function imwrite(path: string, mat: Mat): boolean;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `path` | string | 是 | - | 本地绝对路径（写入磁盘，不是 msbundle） |
+| `mat` | Mat | 是 | - | Mat 句柄 |
+
+**返回值：** 成功 `true`，失败 `false`。
+
+**示例：**
+
+```javascript
+const src = cv.capture();
+cv.imwrite(`${file.getInternalDir("documents")}/out.png`, src);
+cv.release(src);
+```
+
+### imencode - 编码 Mat 为 base64
+
+```typescript
+function imencode(ext: string, mat: Mat, quality?: number): string | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `ext` | string | 是 | - | 如 `.png` / `.jpg` / `png` |
+| `mat` | Mat | 是 | - | Mat 句柄 |
+| `quality` | number | 否 | 90 | JPEG 质量（仅 jpg 有效） |
+
+**返回值：** 纯 base64 字符串（无 data URI 前缀）；失败 `null`。
+
+**示例：**
+
+```javascript
+const b64 = cv.imencode(".jpg", mat, { quality: 85 });
+```
+
+### fromImageId / toImageId - 与 image 互通
+
+```typescript
+function fromImageId(imageId: string): Mat | null;
+function toImageId(mat: Mat): string | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `imageId` | string | 是 | - | `image` 模块句柄 |
+| `mat` | Mat | 是 | - | `cv` Mat 句柄 |
+
+**说明：** 均为独立拷贝。`fromImageId(id)` 与 `imread(id)` 对 imageId 效果相同。
+
+**示例：**
+
+```javascript
+const imageId = image.captureScreen();
+const mat = cv.fromImageId(imageId);
+image.release(imageId);
+const outId = cv.toImageId(mat);
+cv.release(mat);
+image.release(outId);
+```
+
+### Mat / zeros / ones - 创建矩阵
+
+```typescript
+function Mat(options: { rows: number; cols: number; type?: number; scalar?: number[] }): Mat | null;
+function zeros(options: { rows: number; cols: number; type?: number }): Mat | null;
+function ones(options: { rows: number; cols: number; type?: number }): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `rows` / `cols` | number | 是 | - | 行 / 列 |
+| `type` | number | 否 | `CV_8UC3` | 如 `cv.CV_8UC1` |
+| `scalar` | number[] | 否 | - | 仅 `Mat`：填充值 |
+
+**示例：**
+
+```javascript
+const z = cv.zeros({ rows: 100, cols: 100, type: cv.CV_8UC3 });
+const filled = cv.Mat({ rows: 10, cols: 10, type: cv.CV_8UC1, scalar: [255] });
+cv.release(z);
+cv.release(filled);
+```
+
+### clone / empty / isRelease / release / releaseAll
+
+```typescript
+function clone(mat: Mat): Mat | null;
+function empty(mat: Mat): boolean;
+function isRelease(mat: Mat): boolean;
+function release(mat: Mat): void;
+function releaseAll(): void;
+```
+
+**说明：**
+
+- `clone` 返回新句柄。
+- `empty`：无效句柄或空 Mat 为 `true`。
+- `isRelease`：句柄已释放为 `true`。
+- `releaseAll`：释放当前全部 Mat 句柄。
+
+**示例：**
+
+```javascript
+const a = cv.capture();
+const b = cv.clone(a);
+cv.release(a);
+logi(cv.isRelease(a)); // true
+cv.release(b);
+```
+
+### getSize / at / set / copyTo
+
+```typescript
+function getSize(mat: Mat): MatInfo | null;
+logi(`${info.width}x${info.height} ch=${info.channels}`);
+cv.set(mat, { row: 10, col: 10, value: [0, 0, 255] });
+const px = cv.at(mat, { row: 10, col: 10 });
+const copy = cv.copyTo(mat);
+cv.release(copy);
+```
+
+---
+
+## 颜色 / 运算
+
+### cvtColor - 颜色空间转换
+
+```typescript
+function cvtColor(mat: Mat, code: number): Mat | null;
+const hsv = cv.cvtColor(src, { code: cv.COLOR_BGR2HSV });
+```
+
+### threshold - 固定阈值
+
+```typescript
+function threshold(mat: Mat, options: { thresh?: number; maxval?: number; type?: number }): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `thresh` | number | 否 | 127 | 阈值 |
+| `maxval` | number | 否 | 255 | 最大值 |
+| `type` | number | 否 | `THRESH_BINARY` | 如 `THRESH_BINARY` / `THRESH_OTSU` |
+
+**示例：**
+
+```javascript
+const bin = cv.threshold(gray, { thresh: 127, maxval: 255, type: cv.THRESH_BINARY });
+const otsu = cv.threshold(gray, { type: cv.THRESH_BINARY | cv.THRESH_OTSU });
+```
+
+### adaptiveThreshold - 自适应阈值
+
+```typescript
+function adaptiveThreshold(mat: Mat, options: {
+  maxValue?: number;
+  adaptiveMethod?: number;
+  thresholdType?: number;
+  blockSize?: number;
+  C?: number;
+}): Mat | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `maxValue` | number | 否 | 255 | 最大值 |
+| `adaptiveMethod` | number | 否 | `ADAPTIVE_THRESH_GAUSSIAN_C` | 或 `ADAPTIVE_THRESH_MEAN_C` |
+| `thresholdType` | number | 否 | `THRESH_BINARY` | |
+| `blockSize` | number | 否 | 11 | 奇数邻域 |
+| `C` | number | 否 | 2 | 常数偏移 |
+
+**示例：**
+
+```javascript
+const bin = cv.adaptiveThreshold(gray, {
+  maxValue: 255,
+  adaptiveMethod: cv.ADAPTIVE_THRESH_GAUSSIAN_C,
+  thresholdType: cv.THRESH_BINARY,
+  blockSize: 11,
+  C: 2,
+});
+```
+
+### inRange - 范围掩膜
+
+```typescript
+function inRange(mat: Mat, options: { lowerb: number[]; upperb: number[] }): Mat | null;
+```
+
+**参数：** `lowerb` / `upperb` 为各通道下/上限数组。
+
+**示例：**
+
+```javascript
+const hsv = cv.cvtColor(src, { code: cv.COLOR_BGR2HSV });
+const mask = cv.inRange(hsv, { lower: [0, 80, 80], upper: [20, 255, 255] });
+```
+
+### bitwise_and / bitwise_or / bitwise_xor / bitwise_not
+
+```typescript
+const inv = cv.bitwise_not(mask);
+```
+
+### absdiff / addWeighted / convertScaleAbs
+
+```typescript
+const abs = cv.convertScaleAbs(sobel, { alpha: 1, beta: 0 });
+```
+
+### countNonZero / minMaxLoc / mean / split / merge
+
+```typescript
+function countNonZero(mat: Mat): number;
+const mm = cv.minMaxLoc(gray);
+logi(`max=${mm.maxVal} at (${mm.maxLoc.x},${mm.maxLoc.y})`);
+const chans = cv.split(src);
+const merged = cv.merge(chans);
+chans.forEach((c) => cv.release(c));
+cv.release(merged);
+```
+
+---
+
+## 滤波 / 边缘
+
+### GaussianBlur / blur / medianBlur / bilateralFilter / boxFilter
+
+```typescript
+function GaussianBlur(mat: Mat, options: { ksize: number | [number, number] | Size; sigmaX?: number; sigmaY?: number }): Mat | null;
+function blur(mat: Mat, options: { ksize: number | [number, number] | Size }): Mat | null;
+function medianBlur(mat: Mat, options: { ksize: number }): Mat | null;
+function bilateralFilter(mat: Mat, options: { d?: number; sigmaColor?: number; sigmaSpace?: number }): Mat | null;
+function boxFilter(mat: Mat, options: { ksize: number | [number, number] | Size; ddepth?: number }): Mat | null;
+```
+
+`ksize` 可为 `5`、`[5,5]` 或 `{ width, height }`。高斯核尺寸需为奇数。
+
+**示例：**
+
+```javascript
+const g = cv.GaussianBlur(src, { ksize: 5, sigmaX: 1.5 });
+const m = cv.medianBlur(src, { ksize: 5 });
+const b = cv.bilateralFilter(src, { d: 9, sigmaColor: 75, sigmaSpace: 75 });
+```
+
+### Canny / Sobel / Laplacian / Scharr / equalizeHist / CLAHE
+
+```typescript
+function Canny(mat: Mat, options: { threshold1?: number; threshold2?: number; apertureSize?: number; L2gradient?: boolean }): Mat | null;
+function Sobel(mat: Mat, options: { ddepth?: number; dx?: number; dy?: number; ksize?: number; scale?: number; delta?: number }): Mat | null;
+function Laplacian(mat: Mat, options: { ddepth?: number; ksize?: number; scale?: number; delta?: number }): Mat | null;
+function Scharr(mat: Mat, options: { ddepth?: number; dx?: number; dy?: number; scale?: number; delta?: number }): Mat | null;
+function equalizeHist(mat: Mat): Mat | null;
+function CLAHE(mat: Mat, options?: { clipLimit?: number; tileGridSize?: number | [number, number] | Size }): Mat | null;
+```
+
+**Canny 参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `threshold1` | number | 否 | 100 | 低阈值 |
+| `threshold2` | number | 否 | 200 | 高阈值 |
+| `apertureSize` | number | 否 | 3 | Sobel 孔径 |
+| `L2gradient` | boolean | 否 | false | 是否用 L2 范数 |
+
+**CLAHE 参数：** `clipLimit` 默认 40；`tileGridSize` 默认 `[8,8]`。输入一般为单通道灰度。
+
+**示例：**
+
+```javascript
+const edges = cv.Canny(gray, { threshold1: 50, threshold2: 150 });
+const sx = cv.Sobel(gray, { dx: 1, dy: 0, ksize: 3 });
+const eq = cv.CLAHE(gray, { clipLimit: 2.0, tileGridSize: [8, 8] });
+const histEq = cv.equalizeHist(gray);
+```
+
+### pyrDown / pyrUp - 金字塔采样
+
+```typescript
+function pyrDown(mat: Mat): Mat | null;
+function pyrUp(mat: Mat): Mat | null;
+```
+
+约缩小 / 放大一倍。大图特征匹配前可先 `pyrDown` 降采样。
+
+**示例：**
+
+```javascript
+const small = cv.pyrDown(src);
+const back = cv.pyrUp(small);
+```
+
+---
+
+## 几何 / 绘制
+
+### resize - 缩放
+
+```typescript
+function resize(mat: Mat, options: {
+  width?: number;
+  height?: number;
+  fx?: number;
+  fy?: number;
+  interpolation?: number;
+}): Mat | null;
+```
+
+用 `width`/`height` 指定目标尺寸；也可设为 0 并用 `fx`/`fy` 按比例缩放。`interpolation` 如 `cv.INTER_LINEAR`、`cv.INTER_AREA`。
+
+**示例：**
+
+```javascript
+const small = cv.resize(src, { width: 360, height: 640 });
+const half = cv.resize(src, { fx: 0.5, fy: 0.5, interpolation: cv.INTER_AREA });
+```
+
+### crop - 裁剪 ROI（拷贝）
+
+```typescript
+function crop(mat: Mat, options: {
+  x?: number; y?: number;
+  ex?: number; ey?: number;
+}): Mat | null;
+```
+
+参数与 `cv.capture` / `image.captureScreen` 一致，使用左上角与右下角。
+
+参数为 `{ x, y, ex, ey }`。
+
+**示例：**
+
+```javascript
+const roi = cv.crop(src, { x: 10, y: 10, ex: 110, ey: 110 });
+```
+
+### rotate / flip / copyMakeBorder
+
+```typescript
+function rotate(mat: Mat, rotateCode: number): Mat | null;
+const f = cv.flip(src, 1);
+const padded = cv.copyMakeBorder(src, {
+  top: 10, bottom: 10, left: 10, right: 10,
+  borderType: cv.BORDER_CONSTANT, value: [0, 0, 0],
+});
+```
+
+### getRotationMatrix2D / warpAffine / warpPerspective
+
+```typescript
+function getRotationMatrix2D(options: { center: Point | [number, number]; angle?: number; scale?: number }): Mat | null;
+function warpAffine(mat: Mat, options: { M: Mat; width?: number; height?: number; flags?: number }): Mat | null;
+function warpPerspective(mat: Mat, options: { M: Mat; width?: number; height?: number; flags?: number }): Mat | null;
+```
+
+**示例：**
+
+```javascript
+const M = cv.getRotationMatrix2D({ center: { x: 100, y: 100 }, angle: 30, scale: 1 });
+const out = cv.warpAffine(src, { M, width: 200, height: 200 });
+cv.release(M);
+cv.release(out);
+```
+
+### rectangle / circle / line / putText - 就地绘制
+
+就地修改并返回**同一句柄**。`color` 为 BGR 数组或 `#RRGGBB`。
+
+```typescript
+function rectangle(mat: Mat, options: RectangleOptions): Mat | null;
+function circle(mat: Mat, options: CircleOptions): Mat | null;
+function line(mat: Mat, options: LineOptions): Mat | null;
+function putText(mat: Mat, options: PutTextOptions): Mat | null;
+```
+
+**rectangle 参数：** `pt1`+`pt2`，或 `rect`；以及 `color`、`thickness`。
+
+**示例：**
+
+```javascript
+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
+
+```typescript
+function fillPoly(mat: Mat, options: { pts: Point[][] | Point[]; color?: number[] | string }): Mat | null;
+function polylines(mat: Mat, options: { pts: Point[][] | Point[]; isClosed?: boolean; color?: number[] | string; thickness?: number }): Mat | null;
+function drawContours(mat: Mat, options: {
+  contours?: Point[][];
+  pts?: Point[][];
+  contourIdx?: number;
+  color?: number[] | string;
+  thickness?: number;
+}): Mat | null;
+```
+
+就地绘制。`contourIdx` 为 `-1`（默认）表示画全部。
+
+**示例：**
+
+```javascript
+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
+
+```typescript
+function matchTemplate(image: Mat, templ: Mat, methodOrOptions?: number | { method?: number; mask?: Mat }): Mat | null;
+function matchTemplateLoc(image: Mat, templ: Mat, methodOrOptions?: number | { method?: number }): MatchLocResult | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `image` | Mat | 是 | - | 大图 |
+| `templ` | Mat | 是 | - | 模板（须小于大图） |
+| `method` | number | 否 | `TM_CCOEFF_NORMED` | 匹配方法 |
+
+**matchTemplateLoc 返回：** `{ x, y, minVal, maxVal }`（最佳位置取自 max 或 min，取决于 method）。
+
+**示例：**
+
+```javascript
+const 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
+
+```typescript
+function findContours(mat: Mat, options?: { mode?: number; method?: number }): { contours: Point[][]; hierarchy: number[][] } | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `mode` | number | 否 | `RETR_EXTERNAL` | 如 `RETR_LIST` / `RETR_TREE` |
+| `method` | number | 否 | `CHAIN_APPROX_SIMPLE` | 如 `CHAIN_APPROX_NONE` |
+
+**返回值：** `contours` 为点集；`hierarchy` 为每个轮廓的 `[next, prev, child, parent]`（`-1` 表示无）。
+
+输入一般为二值图。
+
+**示例：**
+
+```javascript
+const { 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 / convexHull
+
+```typescript
+function boundingRect(matOrPoints: Mat | Point[]): Rect | null;
+function minAreaRect(points: Point[]): RotatedRect | null;
+function contourArea(matOrPoints: Mat | Point[], orientedOrOptions?: boolean | { oriented?: boolean }): number;
+function arcLength(points: Point[], closedOrOptions?: boolean | { closed?: boolean; isClosed?: boolean }): number;
+function approxPolyDP(points: Point[], options: { epsilon?: number; closed?: boolean }): Point[] | null;
+function convexHull(points: Point[], options?: { clockwise?: boolean }): Point[] | null;
+```
+
+**示例：**
+
+```javascript
+for (const c of contours) {
+  const area = cv.contourArea(c);
+  if (area < 100) continue;
+  const rect = cv.boundingRect(c);
+  const hull = cv.convexHull(c);
+  const approx = cv.approxPolyDP(c, { epsilon: 0.02 * cv.arcLength(c, true), closed: true });
+  cv.rectangle(src, { rect, color: [0, 255, 0], thickness: 1 });
+}
+```
+
+### moments / matchShapes
+
+```typescript
+function moments(mat: Mat, options?: { binaryImage?: boolean }): MomentsResult | null;
+function moments(mat: Mat, binaryImage?: boolean): MomentsResult | null;
+function moments(points: Point[]): MomentsResult | null;
+function matchShapes(contour1: Mat, contour2: Mat, options?: { method?: number; parameter?: number }): number;
+const cx = m.m10 / m.m00;
+const cy = m.m01 / m.m00;
+const score = cv.matchShapes(c1, c2, { method: cv.CONTOURS_MATCH_I1 });
+```
+
+### erode / dilate / morphologyEx / getStructuringElement
+
+```typescript
+function getStructuringElement(options: { shape?: number; ksize: number | [number, number] | Size }): Mat | null;
+const opened = cv.morphologyEx(bin, { op: cv.MORPH_OPEN, kernel: k });
+cv.release(k);
+cv.release(opened);
+```
+
+### connectedComponentsWithStats / distanceTransform / floodFill / goodFeaturesToTrack
+
+```typescript
+function connectedComponentsWithStats(mat: Mat): {
+  count: number;
+  labels: Mat | null;
+  stats: Mat | null;
+  centroids: Mat | null;
+} | null;
+
+function distanceTransform(mat: Mat, options?: { distanceType?: number; maskSize?: number }): Mat | null;
+
+function floodFill(mat: Mat, options: {
+  seedPoint: Point | [number, number];
+  newVal: number[] | string;
+  loDiff?: number[] | string;
+  upDiff?: number[] | string;
+}): { filled: number; rect: Rect } | null;
+
+function goodFeaturesToTrack(mat: Mat, options: {
+  maxCorners?: number;
+  qualityLevel?: number;
+  minDistance?: number;
+  mask?: Mat;
+}): Point[] | null;
+```
+
+**说明：**
+
+- `connectedComponentsWithStats`：`stats` 可用 `CC_STAT_LEFT/TOP/WIDTH/HEIGHT/AREA` 读列。
+- `floodFill` **就地**修改输入图。
+- `goodFeaturesToTrack`：Shi-Tomasi 角点，输入建议灰度。
+
+**示例：**
+
+```javascript
+const cc = cv.connectedComponentsWithStats(bin);
+logi(`components=${cc.count}`);
+cv.release(cc.labels);
+cv.release(cc.stats);
+cv.release(cc.centroids);
+
+const corners = cv.goodFeaturesToTrack(gray, {
+  maxCorners: 50,
+  qualityLevel: 0.01,
+  minDistance: 10,
+});
+```
+
+### HoughLinesP / HoughCircles
+
+```typescript
+function HoughLinesP(mat: Mat, options: {
+  rho?: number; theta?: number; threshold?: number;
+  minLineLength?: number; maxLineGap?: number;
+}): Array<{ x1: number; y1: number; x2: number; y2: number }> | null;
+
+function HoughCircles(mat: Mat, options: {
+  method?: number; dp?: number; minDist?: number;
+  param1?: number; param2?: number;
+  minRadius?: number; maxRadius?: number;
+}): Array<{ x: number; y: number; radius: number }> | null;
+```
+
+输入一般为边缘图（直线）或灰度图（圆）。`method` 常用 `cv.HOUGH_GRADIENT`。
+
+**示例：**
+
+```javascript
+const lines = cv.HoughLinesP(edges, {
+  rho: 1,
+  theta: Math.PI / 180,
+  threshold: 80,
+  minLineLength: 40,
+  maxLineGap: 10,
+});
+for (const l of lines) {
+  cv.line(src, { pt1: { x: l.x1, y: l.y1 }, pt2: { x: l.x2, y: l.y2 }, color: [0, 255, 0], thickness: 1 });
+}
+
+const circles = cv.HoughCircles(gray, {
+  method: cv.HOUGH_GRADIENT,
+  dp: 1,
+  minDist: 30,
+  param1: 100,
+  param2: 30,
+  minRadius: 10,
+  maxRadius: 80,
+});
+```
+
+---
+
+## 算术 / 直方图 / Flann / 扫码 / 矩阵
+
+### add / subtract / multiply / divide
+
+```typescript
+function add(src1: Mat, options: { src2: Mat; mask?: Mat }): Mat | null;
+function subtract(src1: Mat, options: { src2: Mat; mask?: Mat }): Mat | null;
+function multiply(src1: Mat, options: { src2: Mat; scale?: number }): Mat | null;
+function divide(src1: Mat, options: { src2: Mat; scale?: number }): Mat | null;
+```
+
+**示例：**
+
+```javascript
+const sum = cv.add(a, { src2: b });
+const scaled = cv.multiply(a, { src2: b, scale: 0.5 });
+```
+
+### normalize / norm / meanStdDev / findNonZero / hconcat / vconcat
+
+```typescript
+function normalize(mat: Mat, options?: { alpha?: number; beta?: number; normType?: number }): Mat | null;
+function norm(mat: Mat, options?: { normType?: number; mask?: Mat; src2?: Mat }): number;
+function meanStdDev(mat: Mat, options?: { mask?: Mat }): { mean: number[]; stddev: number[] } | null;
+function findNonZero(mat: Mat): Point[] | null;
+function hconcat(mats: Mat[]): Mat | null;
+function vconcat(mats: Mat[]): Mat | null;
+```
+
+**示例：**
+
+```javascript
+const n01 = cv.normalize(gray, { alpha: 0, beta: 255, normType: cv.NORM_MINMAX });
+const pts = cv.findNonZero(mask);
+const side = cv.hconcat([left, right]);
+```
+
+### getPerspectiveTransform / getAffineTransform
+
+已知对应点求变换矩阵。透视 ≥4 点，仿射 ≥3 点。
+
+```typescript
+function getPerspectiveTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | null;
+function getAffineTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | null;
+```
+
+**示例：**
+
+```javascript
+const 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 }],
+});
+const warped = cv.warpPerspective(src, { M, width: 300, height: 400 });
+cv.release(M);
+cv.release(warped);
+```
+
+### FlannBasedMatcher / flannKnnMatch
+
+```typescript
+function FlannBasedMatcher(queryDescriptors: Mat, trainDescriptors: Mat): DMatch[] | null;
+function flannKnnMatch(queryDescriptors: Mat, trainDescriptors: Mat, options?: { k?: number; ratio?: number }): DMatch[][] | null;
+```
+
+SIFT 等浮点描述子可用 Flann；ORB 建议 `BFMatcher` + `NORM_HAMMING`。
+
+**示例：**
+
+```javascript
+const knn = cv.flannKnnMatch(f2.descriptors, f1.descriptors, { k: 2, ratio: 0.75 });
+const good = knn.map((g) => g[0]);
+```
+
+### calcHist / compareHist
+
+```typescript
+function calcHist(mat: Mat, options?: { channels?: number[]; histSize?: number[]; ranges?: number[]; mask?: Mat; accumulate?: boolean }): Mat | null;
+function compareHist(H1: Mat, H2: Mat, options?: { method?: number }): number;
+```
+
+默认通道 `[0]`、`histSize [256]`、`ranges [0,256]`。
+
+**示例：**
+
+```javascript
+const h1 = cv.calcHist(gray1);
+const h2 = cv.calcHist(gray2);
+const score = cv.compareHist(h1, h2, { method: cv.HISTCMP_CORREL });
+cv.release(h1); cv.release(h2);
+```
+
+### boxPoints / pointPolygonTest / minEnclosingCircle / fitEllipse
+
+```typescript
+function boxPoints(options: { center: Point; size: Size | [number, number]; angle?: number }): Point[] | null;
+function pointPolygonTest(contour: Point[], ptOrOptions: Point | { pt: Point; measureDist?: boolean }): number;
+function minEnclosingCircle(points: Point[]): { center: Point; radius: number } | null;
+function fitEllipse(points: Point[]): RotatedRect | null;
+```
+
+**示例：**
+
+```javascript
+const rr = cv.minAreaRect(contour);
+const corners = cv.boxPoints(rr);
+const inside = cv.pointPolygonTest(contour, { pt: { x: 100, y: 100 } });
+```
+
+### detectQRCode / detectBarcode
+
+```typescript
+function detectQRCode(mat: Mat): { decoded: string; points: Point[] } | null;
+function detectBarcode(mat: Mat): { decoded: string[]; types: string[]; points: Point[] } | null;
+```
+
+**示例：**
+
+```javascript
+const qr = cv.detectQRCode(src);
+if (qr) logi(qr.decoded);
+const codes = cv.detectBarcode(src);
+if (codes) logi(codes.decoded.join(","));
+```
+
+### filter2D / ellipse / getTextSize
+
+```typescript
+function filter2D(mat: Mat, options: { kernel: Mat; ddepth?: number; delta?: number }): Mat | null;
+function ellipse(mat: Mat, options: { center: Point; axes: Size | [number, number]; angle?: number; startAngle?: number; endAngle?: number; color?: number[] | string; thickness?: number }): Mat | null;
+function getTextSize(options: { text: string; fontFace?: number; fontScale?: number; thickness?: number }): { width: number; height: number; baseLine: number } | null;
+```
+
+`ellipse` 就地绘制；`thickness: cv.FILLED` 表示填充。
+
+---
+
+## 特征点 / 描述子 / 匹配 / 单应
+
+### 返回结构
+
+**KeyPoint：**
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| `x` / `y` | number | 坐标 |
+| `size` | number | 邻域直径 |
+| `angle` | number | 方向；不适用为 `-1` |
+| `response` | number | 响应强度 |
+| `octave` | number | 金字塔层 |
+| `class_id` | number | 类别 id |
+
+**DMatch：**
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| `queryIdx` | number | 查询描述子索引 |
+| `trainIdx` | number | 训练描述子索引 |
+| `distance` | number | 距离（越小越相似） |
+
+**FeatureResult：** `{ keypoints: KeyPoint[], descriptors: Mat | null }`  
+描述子是 Mat 句柄，用完需 `cv.release(descriptors)`。
+
+### SIFT
+
+```typescript
+function SIFT(mat: Mat, options?: {
+  nfeatures?: number;
+  nOctaveLayers?: number;
+  contrastThreshold?: number;
+  edgeThreshold?: number;
+  sigma?: number;
+  mask?: Mat;
+}): FeatureResult | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `mat` | Mat | 是 | - | 输入图（建议灰度） |
+| `nfeatures` | number | 否 | 0（不限制） | 保留最佳特征数量 |
+| `nOctaveLayers` | number | 否 | 3 | 每组 octave 层数 |
+| `contrastThreshold` | number | 否 | 0.04 | 对比度阈值，越大特征越少 |
+| `edgeThreshold` | number | 否 | 10 | 边缘过滤阈值 |
+| `sigma` | number | 否 | 1.6 | 第 0 层高斯 sigma |
+| `mask` | Mat | 否 | - | 可选 ROI 掩膜 |
+
+**返回值：** `{ keypoints, descriptors }`；失败 `null`。
+
+**示例：**
+
+```javascript
+const gray = cv.cvtColor(src, { code: cv.COLOR_BGR2GRAY });
+const feat = cv.SIFT(gray, { nfeatures: 500 });
+if (feat) {
+  logi(`SIFT keypoints=${feat.keypoints.length}`);
+  const vis = cv.drawKeypoints(src, { keypoints: feat.keypoints, color: [0, 255, 0] });
+  cv.imwrite(`${file.getInternalDir("documents")}/sift.png`, vis);
+  cv.release(vis);
+  cv.release(feat.descriptors);
+}
+cv.release(gray);
+```
+
+### ORB
+
+```typescript
+function ORB(mat: Mat, options?: {
+  nfeatures?: number;
+  scaleFactor?: number;
+  nlevels?: number;
+  mask?: Mat;
+}): FeatureResult | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `nfeatures` | number | 否 | 500 | 最大特征数 |
+| `scaleFactor` | number | 否 | 1.2 | 金字塔尺度因子 |
+| `nlevels` | number | 否 | 8 | 金字塔层数 |
+
+**说明：** ORB 描述子为二进制，匹配请用 `cv.NORM_HAMMING`（或 `NORM_HAMMING2`）。实时/循环优先 ORB。
+
+**示例：**
+
+```javascript
+const a = cv.ORB(img1, { nfeatures: 800 });
+const b = cv.ORB(img2, { nfeatures: 800 });
+const matches = cv.BFMatcher(a.descriptors, b.descriptors, {
+  normType: cv.NORM_HAMMING,
+  crossCheck: true,
+});
+logi(`matches=${matches.length}`);
+cv.release(a.descriptors);
+cv.release(b.descriptors);
+```
+
+### AKAZE / BRISK / FAST
+
+```typescript
+function AKAZE(mat: Mat, options?: { mask?: Mat }): FeatureResult | null;
+function BRISK(mat: Mat, options?: { thresh?: number; octaves?: number; mask?: Mat }): FeatureResult | null;
+function FAST(mat: Mat, options?: { threshold?: number; nonmaxSuppression?: boolean; mask?: Mat }): { keypoints: KeyPoint[] } | null;
+```
+
+**说明：**
+
+- `AKAZE` / `BRISK` 返回关键点 + 描述子。
+- `FAST` **只检测关键点**，无 `descriptors`。
+- `BRISK`：`thresh` 默认 30，`octaves` 默认 3。
+- `FAST`：`threshold` 默认 10，`nonmaxSuppression` 默认 `true`。
+
+**示例：**
+
+```javascript
+const fast = cv.FAST(gray, { threshold: 20 });
+logi(`FAST count=${fast.keypoints.length}`);
+const brisk = cv.BRISK(gray, { thresh: 30, octaves: 3 });
+cv.release(brisk.descriptors);
+```
+
+### BFMatcher
+
+```typescript
+function BFMatcher(queryDescriptors: Mat, trainDescriptors: Mat, options?: {
+  normType?: number;
+  crossCheck?: boolean;
+}): DMatch[] | null;
+matches.sort((a, b) => a.distance - b.distance);
+const top = matches.slice(0, 30);
+```
+
+### knnMatch
+
+```typescript
+function knnMatch(queryDescriptors: Mat, trainDescriptors: Mat, options?: {
+  k?: number;
+  normType?: number;
+  ratio?: number;
+}): DMatch[][] | null;
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `k` | number | 否 | 2 | 每个查询点取 K 个最近邻 |
+| `normType` | number | 否 | `NORM_L2` | 距离类型 |
+| `ratio` | number | 否 | - | 如 `0.75`：启用 Lowe ratio test，只保留通过筛选的最近邻 |
+
+**返回值：**
+
+- 未设 `ratio`：`DMatch[][]`，外层每个查询一组。
+- 设了 `ratio`：仅保留通过筛选的组，每组通常只含 1 个 `DMatch`。
+
+**示例：**
+
+```javascript
+const knn = cv.knnMatch(desc1, desc2, {
+  k: 2,
+  normType: cv.NORM_L2,
+  ratio: 0.75,
+});
+const good = knn.map((g) => g[0]);
+logi(`good matches=${good.length}`);
+```
+
+### drawKeypoints / drawMatches
+
+```typescript
+function drawKeypoints(mat: Mat, options: { keypoints: KeyPoint[]; color?: number[] | string }): Mat | null;
+function drawMatches(img1: Mat, options: {
+  img2: Mat;
+  keypoints1: KeyPoint[];
+  keypoints2: KeyPoint[];
+  matches1to2: DMatch[];
+}): Mat | null;
+cv.imwrite(`${file.getInternalDir("documents")}/matches.png`, vis);
+cv.release(vis);
+```
+
+### findHomography / perspectiveTransform / warpPerspective
+
+```typescript
+function findHomography(options: {
+  srcPoints: Point[];
+  dstPoints: Point[];
+  method?: number;
+  ransacReprojThreshold?: number;
+}): Mat | null;
+
+function perspectiveTransform(points: Point[], options: { M: Mat }): Point[] | null;
+const templ = cv.imread("logo.png");
+const g1 = cv.cvtColor(src, { code: cv.COLOR_BGR2GRAY });
+const g2 = cv.cvtColor(templ, { code: cv.COLOR_BGR2GRAY });
+
+const f1 = cv.SIFT(g1, { nfeatures: 800 });
+const f2 = cv.SIFT(g2, { nfeatures: 800 });
+const knn = cv.flannKnnMatch(f2.descriptors, f1.descriptors, {
+  k: 2,
+  ratio: 0.75,
+});
+const good = knn.map((g) => g[0]);
+
+if (good.length >= 4) {
+  const srcPts = good.map((m) => ({
+    x: f2.keypoints[m.queryIdx].x,
+    y: f2.keypoints[m.queryIdx].y,
+  }));
+  const dstPts = good.map((m) => ({
+    x: f1.keypoints[m.trainIdx].x,
+    y: f1.keypoints[m.trainIdx].y,
+  }));
+  const H = cv.findHomography({
+    srcPoints: srcPts,
+    dstPoints: dstPts,
+    method: cv.RANSAC,
+    ransacReprojThreshold: 5,
+  });
+  const w = cv.getSize(templ).width;
+  const h = cv.getSize(templ).height;
+  const corners = cv.perspectiveTransform(
+    [
+      { x: 0, y: 0 },
+      { x: w, y: 0 },
+      { x: w, y: h },
+      { x: 0, y: h },
+    ],
+    { M: H },
+  );
+  cv.polylines(src, { pts: [corners], isClosed: true, color: [0, 255, 0], thickness: 2 });
+  cv.release(H);
+}
+
+cv.release(src);
+cv.release(templ);
+cv.release(g1);
+cv.release(g2);
+cv.release(f1.descriptors);
+cv.release(f2.descriptors);
+```
+
+---
+
+## Photo / 修复与风格化
+
+### inpaint
+
+```typescript
+function inpaint(mat: Mat, options: { mask: Mat; inpaintRadius?: number; flags?: number }): Mat | null;
+```
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `mask` | Mat | 是 | - | 非零区域待修复 |
+| `inpaintRadius` | number | 否 | 3 | 邻域半径 |
+| `flags` | number | 否 | `INPAINT_TELEA` | `INPAINT_NS` / `INPAINT_TELEA` |
+
+```javascript
+const out = cv.inpaint(src, { mask, flags: cv.INPAINT_TELEA });
+```
+
+### fastNlMeansDenoising / fastNlMeansDenoisingColored
+
+```typescript
+function fastNlMeansDenoising(mat: Mat, options?: {
+  h?: number; templateWindowSize?: number; searchWindowSize?: number;
+}): Mat | null;
+function fastNlMeansDenoisingColored(mat: Mat, options?: {
+  h?: number; hColor?: number; templateWindowSize?: number; searchWindowSize?: number;
+}): Mat | null;
+```
+
+```javascript
+const d1 = cv.fastNlMeansDenoising(gray, { h: 3 });
+const d2 = cv.fastNlMeansDenoisingColored(src, { h: 3, hColor: 3 });
+```
+
+### edgePreservingFilter / detailEnhance / stylization
+
+```typescript
+function edgePreservingFilter(mat: Mat, options?: { flags?: number; sigma_s?: number; sigma_r?: number }): Mat | null;
+function detailEnhance(mat: Mat, options?: { sigma_s?: number; sigma_r?: number }): Mat | null;
+function stylization(mat: Mat, options?: { sigma_s?: number; sigma_r?: number }): Mat | null;
+```
+
+```javascript
+const soft = cv.edgePreservingFilter(src, { flags: cv.RECURS_FILTER });
+const sharp = cv.detailEnhance(src);
+const art = cv.stylization(src);
+```
+
+### pencilSketch / decolor
+
+```typescript
+function pencilSketch(mat: Mat, options?: {
+  sigma_s?: number; sigma_r?: number; shade_factor?: number;
+}): { gray: Mat; color: Mat } | null;
+function decolor(mat: Mat): { grayscale: Mat; colorBoost: Mat } | null;
+```
+
+返回两个新句柄，用完需分别 `release`。
+
+```javascript
+const sketch = cv.pencilSketch(src);
+const dc = cv.decolor(src);
+cv.release(sketch.gray); cv.release(sketch.color);
+cv.release(dc.grayscale); cv.release(dc.colorBoost);
+```
+
+### seamlessClone
+
+```typescript
+function seamlessClone(src: Mat, options: {
+  dst: Mat; mask: Mat; p?: Point; x?: number; y?: number; flags?: number;
+}): Mat | null;
+```
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| `dst` | Mat | 是 | - | 背景图 |
+| `mask` | Mat | 是 | - | 前景有效区域 |
+| `p` / `x,y` | Point | 是 | - | 贴入中心 |
+| `flags` | number | 否 | `NORMAL_CLONE` | `NORMAL_CLONE` / `MIXED_CLONE` / `MONOCHROME_TRANSFER` |
+
+```javascript
+const blend = cv.seamlessClone(fg, { dst: bg, mask, p: { x: 200, y: 150 }, flags: cv.NORMAL_CLONE });
+```
+
+### colorChange / illuminationChange / textureFlattening
+
+```typescript
+function colorChange(mat: Mat, options: { mask: Mat; red_mul?: number; green_mul?: number; blue_mul?: number }): Mat | null;
+function illuminationChange(mat: Mat, options: { mask: Mat; alpha?: number; beta?: number }): Mat | null;
+function textureFlattening(mat: Mat, options: {
+  mask: Mat; low_threshold?: number; high_threshold?: number; kernel_size?: number;
+}): Mat | null;
+```
+
+```javascript
+const c = cv.colorChange(src, { mask, red_mul: 1.5, green_mul: 1.0, blue_mul: 0.8 });
+const i = cv.illuminationChange(src, { mask, alpha: 0.2, beta: 0.4 });
+const f = cv.textureFlattening(src, { mask });
+```
+
+---
+
+## Core 扩展
+
+### LUT / compare / min / max
+
+```typescript
+function LUT(mat: Mat, options: { lut: Mat }): Mat | null;
+function compare(src1: Mat, options: { src2: Mat; cmpop: number }): Mat | null;
+function min(src1: Mat, options: { src2: Mat }): Mat | null;
+function max(src1: Mat, options: { src2: Mat }): Mat | null;
+```
+
+`cmpop` 使用 `CMP_EQ` / `CMP_GT` / `CMP_GE` / `CMP_LT` / `CMP_LE` / `CMP_NE`。
+
+```javascript
+const mask = cv.compare(a, { src2: b, cmpop: cv.CMP_GT });
+const lo = cv.min(a, { src2: b });
+```
+
+### extractChannel / insertChannel / mixChannels
+
+```typescript
+function extractChannel(mat: Mat, options: { coi: number }): Mat | null;
+/** 就地写入 dst，返回 dst 句柄 */
+function insertChannel(srcChannel: Mat, options: { dst: Mat; coi: number }): Mat | null;
+/** 就地改写 dst，成功返回 true */
+function mixChannels(options: { src: Mat[]; dst: Mat[]; fromTo: number[] }): boolean;
+```
+
+```javascript
+const b = cv.extractChannel(src, { coi: 0 });
+cv.insertChannel(b, { dst: out, coi: 0 }); // 就地改 out
+cv.mixChannels({ src: [src], dst: [out], fromTo: [0, 2, 1, 1, 2, 0] });
+```
+
+### pow / sqrt / exp / log / magnitude / cartToPolar / polarToCart
+
+```typescript
+function pow(mat: Mat, options: { power: number }): Mat | null;
+function sqrt(mat: Mat): Mat | null;
+function exp(mat: Mat): Mat | null;
+function log(mat: Mat): Mat | null;
+function magnitude(options: { x: Mat; y: Mat }): Mat | null;
+function cartToPolar(options: { x: Mat; y: Mat; angleInDegrees?: boolean }): { magnitude: Mat; angle: Mat } | null;
+function polarToCart(options: { magnitude: Mat; angle: Mat; angleInDegrees?: boolean }): { x: Mat; y: Mat } | null;
+```
+
+```javascript
+const mag = cv.magnitude({ x: dx, y: dy });
+const polar = cv.cartToPolar({ x: dx, y: dy, angleInDegrees: true });
+cv.release(polar.magnitude); cv.release(polar.angle);
+```
+
+### PSNR / scaleAdd / sum
+
+```typescript
+function PSNR(src1: Mat, options: { src2: Mat; R?: number }): number;
+function scaleAdd(src1: Mat, options: { alpha: number; src2: Mat }): Mat | null;
+function sum(mat: Mat): number[] | null;
+```
+
+```javascript
+const psnr = cv.PSNR(a, { src2: b });
+const s = cv.sum(src); // 各通道和
+```
+
+---
+
+## Imgproc 几何 / 滤波扩展
+
+### stackBlur / sepFilter2D / remap / warpPolar
+
+```typescript
+function stackBlur(mat: Mat, options: { ksize: number | [number, number] | Size }): Mat | null;
+function sepFilter2D(mat: Mat, options: { kernelX: Mat; kernelY: Mat; ddepth?: number; delta?: number }): Mat | null;
+function remap(mat: Mat, options: { map1: Mat; map2: Mat; interpolation?: number; borderMode?: number }): Mat | null;
+function warpPolar(mat: Mat, options: {
+  width?: number; height?: number;
+  center: Point; maxRadius: number; flags?: number;
+}): Mat | null;
+```
+
+```javascript
+const blur = cv.stackBlur(src, { ksize: 7 });
+const polar = cv.warpPolar(src, {
+  width: 300, height: 300, center: { x: 160, y: 160 }, maxRadius: 150,
+  flags: cv.INTER_LINEAR | cv.WARP_POLAR_LINEAR,
+});
+```
+
+### invertAffineTransform / getRectSubPix / phaseCorrelate
+
+```typescript
+function invertAffineTransform(M: Mat): Mat | null;
+function getRectSubPix(mat: Mat, options: {
+  patchSize: Size | [number, number]; center: Point;
+}): Mat | null;
+function phaseCorrelate(src1: Mat, options: { src2: Mat; window?: Mat }): {
+  x: number; y: number; response?: number;
+} | null;
+```
+
+```javascript
+const inv = cv.invertAffineTransform(M);
+const shift = cv.phaseCorrelate(a, { src2: b });
+```
+
+### HoughLines / LSD
+
+```typescript
+function HoughLines(mat: Mat, options?: {
+  rho?: number; theta?: number; threshold?: number; srn?: number; stn?: number;
+}): Array<{ rho: number; theta: number }> | null;
+function LSD(mat: Mat, options?: object): Array<{ x1: number; y1: number; x2: number; y2: number }> | null;
+```
+
+```javascript
+const lines = cv.HoughLines(edges, { threshold: 80 });
+const segs = cv.LSD(gray);
+```
+
+### cornerHarris / cornerSubPix / cornerMinEigenVal / preCornerDetect / spatialGradient
+
+```typescript
+function cornerHarris(mat: Mat, options?: { blockSize?: number; ksize?: number; k?: number }): Mat | null;
+function cornerSubPix(mat: Mat, options: {
+  corners: Point[]; winSize?: Size | [number, number]; zeroZone?: Size | [number, number];
+  criteria?: { type?: number; maxCount?: number; epsilon?: number };
+}): Point[] | null;
+function cornerMinEigenVal(mat: Mat, options?: { blockSize?: number; ksize?: number }): Mat | null;
+function preCornerDetect(mat: Mat, options?: { ksize?: number }): Mat | null;
+function spatialGradient(mat: Mat, options?: { ksize?: number }): { dx: Mat; dy: Mat } | null;
+```
+
+```javascript
+const corners = cv.goodFeaturesToTrack(gray, { maxCorners: 50, qualityLevel: 0.01, minDistance: 10 });
+const refined = cv.cornerSubPix(gray, { corners, winSize: [5, 5] });
+const g = cv.spatialGradient(gray);
+cv.release(g.dx); cv.release(g.dy);
+```
+
+### calcBackProject / applyColorMap / HuMoments / pyrMeanShiftFiltering / integral
+
+```typescript
+function calcBackProject(mat: Mat, options: {
+  hist: Mat; channels?: number[]; ranges?: number[]; scale?: number;
+}): Mat | null;
+function applyColorMap(mat: Mat, options: { colormap: number }): Mat | null;
+function HuMoments(contourOrMoments: Point[] | object | Mat): number[] | null;
+function pyrMeanShiftFiltering(mat: Mat, options?: { sp?: number; sr?: number; maxLevel?: number }): Mat | null;
+function integral(mat: Mat): Mat | null;
+```
+
+```javascript
+const back = cv.calcBackProject(hsv, { hist, channels: [0], ranges: [0, 180] });
+const heat = cv.applyColorMap(gray, { colormap: cv.COLORMAP_JET });
+const hu = cv.HuMoments(contour); // length 7
+```
+
+### drawMarker / arrowedLine / fillConvexPoly（就地）
+
+```typescript
+function drawMarker(mat: Mat, options: {
+  position: Point; color?: number[] | string;
+  markerType?: number; markerSize?: number; thickness?: number;
+}): Mat | null;
+function arrowedLine(mat: Mat, options: {
+  pt1: Point; pt2: Point; color?: number[] | string; thickness?: number; tipLength?: number;
+}): Mat | null;
+function fillConvexPoly(mat: Mat, options: { pts: Point[]; color?: number[] | string }): Mat | null;
+```
+
+就地修改输入 Mat，返回同一句柄。
+
+```javascript
+cv.drawMarker(src, { position: { x: 100, y: 80 }, markerType: cv.MARKER_CROSS });
+cv.arrowedLine(src, { pt1: { x: 10, y: 10 }, pt2: { x: 200, y: 120 }, color: [0, 0, 255] });
+cv.fillConvexPoly(src, { pts: [{ x: 10, y: 10 }, { x: 100, y: 20 }, { x: 50, y: 80 }], color: [0, 255, 0] });
+```
+
+### connectedComponents / convexityDefects / isContourConvex / fitLine
+
+```typescript
+function connectedComponents(mat: Mat, options?: { connectivity?: number }): { count: number; labels: Mat } | null;
+function convexityDefects(contour: Point[], options: { hull: number[] | Point[] }):
+  Array<{ start: number; end: number; farthest: number; depth: number }> | null;
+function isContourConvex(contour: Point[]): boolean;
+function fitLine(points: Point[], options?: {
+  distType?: number; param?: number; reps?: number; aeps?: number;
+}): [number, number, number, number] | null;
+```
+
+`hull` 可为索引数组，或与 `convexHull` 返回格式相同的 Point[]。
+
+```javascript
+const cc = cv.connectedComponents(bin, { connectivity: 8 });
+const hull = cv.convexHull(contour);
+const defects = cv.convexityDefects(contour, { hull });
+const line = cv.fitLine(points); // [vx, vy, x0, y0]
+cv.release(cc.labels);
+```
+
+### watershed / grabCut（就地）
+
+```typescript
+/** 就地改写 markers，返回 markers 句柄 */
+function watershed(mat: Mat, options: { markers: Mat }): Mat | null;
+/** 就地改写 mask，返回 mask 句柄 */
+function grabCut(mat: Mat, options: {
+  mask: Mat; rect?: Rect; iterCount?: number; mode?: number;
+}): Mat | null;
+```
+
+```javascript
+cv.watershed(src, { markers }); // 就地改 markers
+cv.grabCut(src, {
+  mask,
+  rect: { x: 50, y: 50, width: 200, height: 200 },
+  iterCount: 5,
+  mode: cv.GC_INIT_WITH_RECT,
+}); // 就地改 mask
+```
+
+---
+
+## Calib3d / Features / Objdetect
+
+### estimateAffine2D / estimateAffinePartial2D
+
+```typescript
+function estimateAffine2D(options: {
+  srcPoints: Point[]; dstPoints: Point[]; method?: number; ransacReprojThreshold?: number;
+}): Mat | null;
+function estimateAffinePartial2D(options: {
+  srcPoints: Point[]; dstPoints: Point[]; method?: number; ransacReprojThreshold?: number;
+}): Mat | null;
+```
+
+```javascript
+const M = cv.estimateAffine2D({
+  srcPoints, dstPoints, method: cv.RANSAC, ransacReprojThreshold: 3,
+});
+```
+
+### KAZE / MSER / SimpleBlobDetector / AGAST
+
+```typescript
+function KAZE(mat: Mat, options?: { mask?: Mat }): { keypoints: KeyPoint[]; descriptors: Mat | null } | null;
+function MSER(mat: Mat, options?: { mask?: Mat }): { keypoints: KeyPoint[] } | null;
+function SimpleBlobDetector(mat: Mat, options?: { mask?: Mat }): { keypoints: KeyPoint[] } | null;
+function AGAST(mat: Mat, options?: {
+  threshold?: number; nonmaxSuppression?: boolean; mask?: Mat;
+}): { keypoints: KeyPoint[] } | null;
+```
+
+```javascript
+const kaze = cv.KAZE(gray);
+const mser = cv.MSER(gray);
+const blobs = cv.SimpleBlobDetector(gray);
+const agast = cv.AGAST(gray, { threshold: 10 });
+if (kaze.descriptors) cv.release(kaze.descriptors);
+```
+
+### encodeQRCode / CascadeClassifier / HOGDetect
+
+```typescript
+function encodeQRCode(text: string): Mat | null;
+function CascadeClassifier(mat: Mat, options: {
+  cascadePath?: string; path?: string;
+  scaleFactor?: number; minNeighbors?: number; minSize?: Size | [number, number];
+}): Rect[] | null;
+function HOGDetect(mat: Mat, options?: object): Rect[] | null;
+```
+
+`CascadeClassifier` 需自行提供 xml 级联路径。
+
+```javascript
+const qr = cv.encodeQRCode('https://example.com');
+const faces = cv.CascadeClassifier(gray, {
+  cascadePath: '/path/to/haarcascade_frontalface_alt.xml',
+  scaleFactor: 1.1,
+  minNeighbors: 3,
+});
+const people = cv.HOGDetect(src);
+cv.release(qr);
+```
+
+---
+
+## 常用常量
+
+挂在 `cv` 上，例如：
+
+- 颜色：`COLOR_BGR2GRAY`、`COLOR_RGB2GRAY`、`COLOR_BGR2HSV`、`COLOR_BGR2RGB`、`COLOR_BGRA2BGR`、…
+- 阈值：`THRESH_BINARY`、`THRESH_BINARY_INV`、`THRESH_OTSU`、`THRESH_TRUNC`、…
+- 自适应：`ADAPTIVE_THRESH_MEAN_C`、`ADAPTIVE_THRESH_GAUSSIAN_C`
+- 模板匹配：`TM_SQDIFF`、`TM_CCORR_NORMED`、`TM_CCOEFF_NORMED`、…
+- 轮廓：`RETR_EXTERNAL`、`RETR_LIST`、`RETR_TREE`、`CHAIN_APPROX_SIMPLE`、…
+- 形态学：`MORPH_RECT`、`MORPH_OPEN`、`MORPH_CLOSE`、`MORPH_HITMISS`、…
+- 插值 / 旋转 / 边界：`INTER_*`、`ROTATE_*`、`BORDER_*`
+- 线型：`LINE_4` / `LINE_8` / `LINE_AA` / `FILLED`
+- 字体：`FONT_HERSHEY_SIMPLEX`、…
+- Mat 类型：`CV_8UC1`、`CV_8UC3`、`CV_8UC4`、`CV_32FC1`、`CV_32FC3`
+- 匹配距离：`NORM_L1`、`NORM_L2`、`NORM_HAMMING`、`NORM_HAMMING2`、`NORM_INF`、`NORM_MINMAX`
+- 直方图比较：`HISTCMP_CORREL` / `CHISQR` / `INTERSECT` / `BHATTACHARYYA` / …
+- 单应：`RANSAC`、`LMEDS`、`RHO`
+- 霍夫：`HOUGH_GRADIENT`、`HOUGH_GRADIENT_ALT`
+- 距离变换：`DIST_L1`、`DIST_L2`、`DIST_C`、`DIST_MASK_3`、`DIST_MASK_5`
+- 形状匹配：`CONTOURS_MATCH_I1` / `I2` / `I3`
+- 连通域统计列：`CC_STAT_LEFT` / `TOP` / `WIDTH` / `HEIGHT` / `AREA`
+- 读标志：`IMREAD_COLOR`、`IMREAD_GRAYSCALE`、`IMREAD_UNCHANGED`
+- 修复 / 风格：`INPAINT_NS`、`INPAINT_TELEA`、`RECURS_FILTER`、`NORMCONV_FILTER`
+- 无缝克隆：`NORMAL_CLONE`、`MIXED_CLONE`、`MONOCHROME_TRANSFER`
+- 比较：`CMP_EQ` / `CMP_GT` / `CMP_GE` / `CMP_LT` / `CMP_LE` / `CMP_NE`
+- 伪彩色：`COLORMAP_JET`、`COLORMAP_VIRIDIS`、`COLORMAP_TURBO`、`COLORMAP_HOT`、…
+- 极坐标：`WARP_POLAR_LINEAR`、`WARP_POLAR_LOG`
+- 标记：`MARKER_CROSS`、`MARKER_STAR`、`MARKER_DIAMOND`、…
+- GrabCut：`GC_BGD` / `GC_FGD` / `GC_PR_BGD` / `GC_PR_FGD`、`GC_INIT_WITH_RECT` / `GC_INIT_WITH_MASK` / `GC_EVAL`
+
+完整列表见类型提示 `types/opencv.d.ts`。
+
+---
+
+## 限制与建议
+
+1. 同时存活的 Mat 句柄有上限（约 32），用完请 `release`，或阶段结束 `releaseAll`；多返回值 API（如 `pencilSketch`、`decolor`、`cartToPolar`）需分别释放。
+2. 路径 / msbundle / imageId / `screen` 只走 `imread`；其它 API 只接受 Mat 句柄。
+3. SIFT 描述子优先 `flannKnnMatch`；ORB 用 `BFMatcher` + `NORM_HAMMING`。
+4. 特征匹配前建议转灰度；大图可先 `pyrDown` / `resize`。
+5. `findHomography` 至少需要 4 对对应点，不足会返回 `null`。
+6. 绘制类、`floodFill`、`insertChannel`、`watershed`、`grabCut` 会改原图或指定目标句柄；需保留原图请先 `clone`。
+7. 与 `image` 互通时，两边句柄各自 `release`。
+8. `CascadeClassifier` 需要设备上可访问的级联 xml 路径。