ms-vite-plugin 1.5.12 → 1.5.14

package/docs/api/opencv.md

@@ -71,7 +71,7 @@ function capture(
   y?: number,
   ex?: number,
   ey?: number,
-): Mat | null;
+): Mat | undefined;
 ```
 
 **参数：**
@@ -89,7 +89,7 @@ function capture(
 
 | 类型 | 描述 |
 | --- | --- |
-| `string` | Mat 句柄，失败返回 `null` |
+| `string` | Mat 句柄，失败返回 `undefined` |
 
 **示例：**
 
@@ -103,7 +103,7 @@ cv.release(roi);
 ### imread - 读取图片为 Mat（唯一路径类入口）
 
 ```typescript
-function imread(path: string): Mat | null;
+function imread(path: string): Mat | undefined;
 ```
 
 **参数：**
@@ -131,7 +131,7 @@ function imread(path: string): Mat | null;
 
 | 类型 | 描述 |
 | --- | --- |
-| `string` | Mat 句柄，失败返回 `null` |
+| `string` | Mat 句柄，失败返回 `undefined` |
 
 **示例：**
 
@@ -150,7 +150,7 @@ cv.release(c);
 ### imdecode - 解码 base64 为 Mat
 
 ```typescript
-function imdecode(data: string): Mat | null;
+function imdecode(data: string): Mat | undefined;
 ```
 
 **参数：**
@@ -161,7 +161,7 @@ function imdecode(data: string): Mat | null;
 
 **说明：** 不解析文件路径 / msbundle / imageId；路径类请用 `imread`。常与 `imencode` 成对使用。
 
-**返回值：** Mat 句柄；失败 `null`。
+**返回值：** Mat 句柄；失败 `undefined`。
 
 **示例：**
 
@@ -201,7 +201,7 @@ cv.release(src);
 ### imencode - 编码 Mat 为 base64
 
 ```typescript
-function imencode(ext: string, mat: Mat, quality?: number): string | null;
+function imencode(ext: string, mat: Mat, quality?: number): string | undefined;
 ```
 
 **参数：**
@@ -212,9 +212,9 @@ function imencode(ext: string, mat: Mat, quality?: number): string | null;
 | `mat` | Mat | 是 | - | Mat 句柄 |
 | `quality` | number | 否 | 90 | JPEG 质量，取值 1–100（仅 jpg 有效） |
 
-**说明：** 可用扩展名与通道限制同 `imwrite`，不支持的格式返回 `null`。
+**说明：** 可用扩展名与通道限制同 `imwrite`，不支持的格式返回 `undefined`。
 
-**返回值：** 纯 base64 字符串（无 data URI 前缀）；失败 `null`。
+**返回值：** 纯 base64 字符串（无 data URI 前缀）；失败 `undefined`。
 
 **示例：**
 
@@ -225,8 +225,8 @@ const b64 = cv.imencode(".jpg", mat, 85);
 ### fromImageId / toImageId - 与 image 互通
 
 ```typescript
-function fromImageId(imageId: string): Mat | null;
-function toImageId(mat: Mat): string | null;
+function fromImageId(imageId: string): Mat | undefined;
+function toImageId(mat: Mat): string | undefined;
 ```
 
 **参数：**
@@ -252,9 +252,9 @@ 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;
+function Mat(options: { rows: number; cols: number; type?: number; scalar?: number[] }): Mat | undefined;
+function zeros(options: { rows: number; cols: number; type?: number }): Mat | undefined;
+function ones(options: { rows: number; cols: number; type?: number }): Mat | undefined;
 ```
 
 **参数：**
@@ -277,7 +277,7 @@ cv.release(filled);
 ### clone / empty / isRelease / release / releaseAll
 
 ```typescript
-function clone(mat: Mat): Mat | null;
+function clone(mat: Mat): Mat | undefined;
 function empty(mat: Mat): boolean;
 function isRelease(mat: Mat): boolean;
 function release(mat: Mat): void;
@@ -304,7 +304,7 @@ cv.release(b);
 ### getSize / at / set / copyTo
 
 ```typescript
-function getSize(mat: Mat): MatInfo | null;
+function getSize(mat: Mat): MatInfo | undefined;
 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 });
@@ -319,14 +319,14 @@ cv.release(copy);
 ### cvtColor - 颜色空间转换
 
 ```typescript
-function cvtColor(mat: Mat, code: number): Mat | null;
+function cvtColor(mat: Mat, code: number): Mat | undefined;
 const hsv = cv.cvtColor(src, cv.COLOR_BGR2HSV);
 ```
 
 ### threshold - 固定阈值
 
 ```typescript
-function threshold(mat: Mat, options: { thresh?: number; maxval?: number; type?: number }): Mat | null;
+function threshold(mat: Mat, options: { thresh?: number; maxval?: number; type?: number }): Mat | undefined;
 ```
 
 **参数：**
@@ -353,7 +353,7 @@ function adaptiveThreshold(mat: Mat, options: {
   thresholdType?: number;
   blockSize?: number;
   C?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 **参数：**
@@ -381,7 +381,7 @@ const bin = cv.adaptiveThreshold(gray, {
 ### inRange - 范围掩膜
 
 ```typescript
-function inRange(mat: Mat, options: { lowerb: number[]; upperb: number[] }): Mat | null;
+function inRange(mat: Mat, options: { lowerb: number[]; upperb: number[] }): Mat | undefined;
 ```
 
 **参数：** `lowerb` / `upperb` 为各通道下/上限数组。
@@ -409,7 +409,7 @@ const abs = cv.convertScaleAbs(sobel, { alpha: 1, beta: 0 });
 
 ```typescript
 function countNonZero(mat: Mat): number;
-function minMaxLoc(mat: Mat, options?: { mask?: Mat }): MinMaxLocResult | null;
+function minMaxLoc(mat: Mat, options?: { mask?: Mat }): MinMaxLocResult | undefined;
 ```
 
 `minMaxLoc` / `countNonZero` 需要单通道，先转灰度：
@@ -431,11 +431,11 @@ 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;
+function GaussianBlur(mat: Mat, options: { ksize: number | [number, number] | Size; sigmaX?: number; sigmaY?: number }): Mat | undefined;
+function blur(mat: Mat, options: { ksize: number | [number, number] | Size }): Mat | undefined;
+function medianBlur(mat: Mat, options: { ksize: number }): Mat | undefined;
+function bilateralFilter(mat: Mat, options: { d?: number; sigmaColor?: number; sigmaSpace?: number }): Mat | undefined;
+function boxFilter(mat: Mat, options: { ksize: number | [number, number] | Size; ddepth?: number }): Mat | undefined;
 ```
 
 `ksize` 可为 `5`、`[5,5]` 或 `{ width, height }`。高斯核尺寸需为奇数。
@@ -451,12 +451,12 @@ 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;
+function Canny(mat: Mat, options: { threshold1?: number; threshold2?: number; apertureSize?: number; L2gradient?: boolean }): Mat | undefined;
+function Sobel(mat: Mat, options: { ddepth?: number; dx?: number; dy?: number; ksize?: number; scale?: number; delta?: number }): Mat | undefined;
+function Laplacian(mat: Mat, options: { ddepth?: number; ksize?: number; scale?: number; delta?: number }): Mat | undefined;
+function Scharr(mat: Mat, options: { ddepth?: number; dx?: number; dy?: number; scale?: number; delta?: number }): Mat | undefined;
+function equalizeHist(mat: Mat): Mat | undefined;
+function CLAHE(mat: Mat, options?: { clipLimit?: number; tileGridSize?: number | [number, number] | Size }): Mat | undefined;
 ```
 
 **Canny 参数：**
@@ -482,8 +482,8 @@ const histEq = cv.equalizeHist(gray);
 ### pyrDown / pyrUp - 金字塔采样
 
 ```typescript
-function pyrDown(mat: Mat): Mat | null;
-function pyrUp(mat: Mat): Mat | null;
+function pyrDown(mat: Mat): Mat | undefined;
+function pyrUp(mat: Mat): Mat | undefined;
 ```
 
 约缩小 / 放大一倍。大图特征匹配前可先 `pyrDown` 降采样。
@@ -508,7 +508,7 @@ function resize(mat: Mat, options: {
   fx?: number;
   fy?: number;
   interpolation?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 用 `width`/`height` 指定目标尺寸；也可设为 0 并用 `fx`/`fy` 按比例缩放。`interpolation` 如 `cv.INTER_LINEAR`、`cv.INTER_AREA`。
@@ -526,7 +526,7 @@ const half = cv.resize(src, { fx: 0.5, fy: 0.5, interpolation: cv.INTER_AREA });
 function crop(mat: Mat, options: {
   x?: number; y?: number;
   ex?: number; ey?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 参数与 `cv.capture` / `image.captureScreen` 一致，使用左上角与右下角。
@@ -542,7 +542,7 @@ 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;
+function rotate(mat: Mat, rotateCode: number): Mat | undefined;
 const f = cv.flip(src, 1);
 const padded = cv.copyMakeBorder(src, {
   top: 10, bottom: 10, left: 10, right: 10,
@@ -553,9 +553,9 @@ const padded = cv.copyMakeBorder(src, {
 ### 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;
+function getRotationMatrix2D(options: { center: Point | [number, number]; angle?: number; scale?: number }): Mat | undefined;
+function warpAffine(mat: Mat, options: { M: Mat; width?: number; height?: number; flags?: number }): Mat | undefined;
+function warpPerspective(mat: Mat, options: { M: Mat; width?: number; height?: number; flags?: number }): Mat | undefined;
 ```
 
 **示例：**
@@ -575,10 +575,10 @@ cv.release(out);
 `arrowedLine` / `drawMarker` 只能描边，传 0 或负值按 1 处理。
 
 ```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;
+function rectangle(mat: Mat, options: RectangleOptions): Mat | undefined;
+function circle(mat: Mat, options: CircleOptions): Mat | undefined;
+function line(mat: Mat, options: LineOptions): Mat | undefined;
+function putText(mat: Mat, options: PutTextOptions): Mat | undefined;
 ```
 
 **rectangle 参数：** `pt1`+`pt2`，或 `rect`；以及 `color`、`thickness`。
@@ -607,15 +607,15 @@ cv.putText(src, {
 ### 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 fillPoly(mat: Mat, options: { pts: Point[][] | Point[]; color?: number[] | string }): Mat | undefined;
+function polylines(mat: Mat, options: { pts: Point[][] | Point[]; isClosed?: boolean; color?: number[] | string; thickness?: number }): Mat | undefined;
 function drawContours(mat: Mat, options: {
   contours?: Point[][];
   pts?: Point[][];
   contourIdx?: number;
   color?: number[] | string;
   thickness?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 就地绘制。`contourIdx` 为 `-1`（默认）表示画全部。
@@ -638,8 +638,8 @@ cv.polylines(src, {
 ### 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;
+function matchTemplate(image: Mat, templ: Mat, methodOrOptions?: number | { method?: number; mask?: Mat }): Mat | undefined;
+function matchTemplateLoc(image: Mat, templ: Mat, methodOrOptions?: number | { method?: number }): MatchLocResult | undefined;
 ```
 
 **参数：**
@@ -668,7 +668,7 @@ cv.rectangle(src, {
 ### findContours
 
 ```typescript
-function findContours(mat: Mat, options?: { mode?: number; method?: number }): { contours: Point[][]; hierarchy: number[][] } | null;
+function findContours(mat: Mat, options?: { mode?: number; method?: number }): { contours: Point[][]; hierarchy: number[][] } | undefined;
 ```
 
 **参数：**
@@ -692,12 +692,12 @@ 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 boundingRect(matOrPoints: Mat | Point[]): Rect | undefined;
+function minAreaRect(points: Point[]): RotatedRect | undefined;
 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;
+function approxPolyDP(points: Point[], options: { epsilon?: number; closed?: boolean }): Point[] | undefined;
+function convexHull(points: Point[], options?: { clockwise?: boolean }): Point[] | undefined;
 ```
 
 **示例：**
@@ -716,9 +716,9 @@ for (const c of contours) {
 ### 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 moments(mat: Mat, options?: { binaryImage?: boolean }): MomentsResult | undefined;
+function moments(mat: Mat, binaryImage?: boolean): MomentsResult | undefined;
+function moments(points: Point[]): MomentsResult | undefined;
 function matchShapes(contour1: Mat, contour2: Mat, options?: { method?: number; parameter?: number }): number;
 const cx = m.m10 / m.m00;
 const cy = m.m01 / m.m00;
@@ -728,7 +728,7 @@ 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;
+function getStructuringElement(options: { shape?: number; ksize: number | [number, number] | Size }): Mat | undefined;
 const opened = cv.morphologyEx(bin, { op: cv.MORPH_OPEN, kernel: k });
 cv.release(k);
 cv.release(opened);
@@ -739,26 +739,26 @@ cv.release(opened);
 ```typescript
 function connectedComponentsWithStats(mat: Mat): {
   count: number;
-  labels: Mat | null;
-  stats: Mat | null;
-  centroids: Mat | null;
-} | null;
+  labels?: Mat;
+  stats?: Mat;
+  centroids?: Mat;
+} | undefined;
 
-function distanceTransform(mat: Mat, options?: { distanceType?: number; maskSize?: number }): Mat | null;
+function distanceTransform(mat: Mat, options?: { distanceType?: number; maskSize?: number }): Mat | undefined;
 
 function floodFill(mat: Mat, options: {
   seedPoint: Point | [number, number];
   newVal: number[] | string;
   loDiff?: number[] | string;
   upDiff?: number[] | string;
-}): { filled: number; rect: Rect } | null;
+}): { filled: number; rect: Rect } | undefined;
 
 function goodFeaturesToTrack(mat: Mat, options: {
   maxCorners?: number;
   qualityLevel?: number;
   minDistance?: number;
   mask?: Mat;
-}): Point[] | null;
+}): Point[] | undefined;
 ```
 
 **说明：**
@@ -789,13 +789,13 @@ const corners = cv.goodFeaturesToTrack(gray, {
 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;
+}): Array<{ x1: number; y1: number; x2: number; y2: number }> | undefined;
 
 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;
+}): Array<{ x: number; y: number; radius: number }> | undefined;
 ```
 
 输入一般为边缘图（直线）或灰度图（圆）。`method` 常用 `cv.HOUGH_GRADIENT`。
@@ -832,10 +832,10 @@ const circles = cv.HoughCircles(gray, {
 ### 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;
+function add(src1: Mat, options: { src2: Mat; mask?: Mat }): Mat | undefined;
+function subtract(src1: Mat, options: { src2: Mat; mask?: Mat }): Mat | undefined;
+function multiply(src1: Mat, options: { src2: Mat; scale?: number }): Mat | undefined;
+function divide(src1: Mat, options: { src2: Mat; scale?: number }): Mat | undefined;
 ```
 
 **示例：**
@@ -848,12 +848,12 @@ 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 normalize(mat: Mat, options?: { alpha?: number; beta?: number; normType?: number }): Mat | undefined;
 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;
+function meanStdDev(mat: Mat, options?: { mask?: Mat }): { mean: number[]; stddev: number[] } | undefined;
+function findNonZero(mat: Mat): Point[] | undefined;
+function hconcat(mats: Mat[]): Mat | undefined;
+function vconcat(mats: Mat[]): Mat | undefined;
 ```
 
 **示例：**
@@ -869,8 +869,8 @@ const side = cv.hconcat([left, right]);
 已知对应点求变换矩阵。透视 ≥4 点，仿射 ≥3 点。
 
 ```typescript
-function getPerspectiveTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | null;
-function getAffineTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | null;
+function getPerspectiveTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | undefined;
+function getAffineTransform(options: { srcPoints: Point[]; dstPoints: Point[] }): Mat | undefined;
 ```
 
 **示例：**
@@ -888,8 +888,8 @@ 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;
+function FlannBasedMatcher(queryDescriptors: Mat, trainDescriptors: Mat): DMatch[] | undefined;
+function flannKnnMatch(queryDescriptors: Mat, trainDescriptors: Mat, options?: { k?: number; ratio?: number }): DMatch[][] | undefined;
 ```
 
 SIFT 等浮点描述子可用 Flann；ORB 建议 `BFMatcher` + `NORM_HAMMING`。
@@ -904,7 +904,7 @@ 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 calcHist(mat: Mat, options?: { channels?: number[]; histSize?: number[]; ranges?: number[]; mask?: Mat; accumulate?: boolean }): Mat | undefined;
 function compareHist(H1: Mat, H2: Mat, options?: { method?: number }): number;
 ```
 
@@ -922,9 +922,9 @@ cv.release(h1); cv.release(h2);
 ### encodeQRCode / detectQRCode / detectBarcode
 
 ```typescript
-function encodeQRCode(text: string): Mat | null;
-function detectQRCode(mat: Mat): { decoded: string; points: Point[] } | null;
-function detectBarcode(mat: Mat): { decoded: string[]; types: string[]; points: Point[] } | null;
+function encodeQRCode(text: string): Mat | undefined;
+function detectQRCode(mat: Mat): { decoded: string; points: Point[] } | undefined;
+function detectBarcode(mat: Mat): { decoded: string[]; types: string[]; points: Point[] } | undefined;
 ```
 
 `encodeQRCode` 返回可显示/可识别的 BGR Mat（已放大并加静区），可直接交给 `detectQRCode`。
@@ -943,9 +943,9 @@ cv.release(qrMat);
 ### 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;
+function filter2D(mat: Mat, options: { kernel: Mat; ddepth?: number; delta?: number }): Mat | undefined;
+function ellipse(mat: Mat, options: { center: Point; axes: Size | [number, number]; angle?: number; startAngle?: number; endAngle?: number; color?: number[] | string; thickness?: number }): Mat | undefined;
+function getTextSize(options: { text: string; fontFace?: number; fontScale?: number; thickness?: number }): { width: number; height: number; baseLine: number } | undefined;
 ```
 
 `ellipse` 就地绘制；`thickness: cv.FILLED` 表示填充。
@@ -976,7 +976,7 @@ function getTextSize(options: { text: string; fontFace?: number; fontScale?: num
 | `distance` | number | 距离（越小越相似） |
 
 **FeatureResult：** `{ keypoints: KeyPoint[], descriptors: Mat | null }`  
-描述子是 Mat 句柄，用完需 `cv.release(descriptors)`。
+描述子是 Mat 句柄，用完需 `cv.release(descriptors)`。计算失败时 `descriptors` 为 `null`。
 
 ### SIFT
 
@@ -988,7 +988,7 @@ function SIFT(mat: Mat, options?: {
   edgeThreshold?: number;
   sigma?: number;
   mask?: Mat;
-}): FeatureResult | null;
+}): FeatureResult | undefined;
 ```
 
 **参数：**
@@ -1003,7 +1003,7 @@ function SIFT(mat: Mat, options?: {
 | `sigma` | number | 否 | 1.6 | 第 0 层高斯 sigma |
 | `mask` | Mat | 否 | - | 可选 ROI 掩膜 |
 
-**返回值：** `{ keypoints, descriptors }`；失败 `null`。
+**返回值：** `{ keypoints, descriptors }`；整次失败 `undefined`，描述子失败时 `descriptors` 为 `null`。
 
 **示例：**
 
@@ -1028,7 +1028,7 @@ function ORB(mat: Mat, options?: {
   scaleFactor?: number;
   nlevels?: number;
   mask?: Mat;
-}): FeatureResult | null;
+}): FeatureResult | undefined;
 ```
 
 **参数：**
@@ -1061,7 +1061,7 @@ cv.release(b.descriptors);
 function BFMatcher(queryDescriptors: Mat, trainDescriptors: Mat, options?: {
   normType?: number;
   crossCheck?: boolean;
-}): DMatch[] | null;
+}): DMatch[] | undefined;
 matches.sort((a, b) => a.distance - b.distance);
 const top = matches.slice(0, 30);
 ```
@@ -1073,7 +1073,7 @@ function knnMatch(queryDescriptors: Mat, trainDescriptors: Mat, options?: {
   k?: number;
   normType?: number;
   ratio?: number;
-}): DMatch[][] | null;
+}): DMatch[][] | undefined;
 ```
 
 **参数：**
@@ -1104,13 +1104,13 @@ logi(`good matches=${good.length}`);
 ### drawKeypoints / drawMatches
 
 ```typescript
-function drawKeypoints(mat: Mat, options: { keypoints: KeyPoint[]; color?: number[] | string }): Mat | null;
+function drawKeypoints(mat: Mat, options: { keypoints: KeyPoint[]; color?: number[] | string }): Mat | undefined;
 function drawMatches(img1: Mat, options: {
   img2: Mat;
   keypoints1: KeyPoint[];
   keypoints2: KeyPoint[];
   matches1to2: DMatch[];
-}): Mat | null;
+}): Mat | undefined;
 cv.imwrite(`${file.getInternalDir("documents")}/matches.png`, vis);
 cv.release(vis);
 ```
@@ -1123,9 +1123,9 @@ function findHomography(options: {
   dstPoints: Point[];
   method?: number;
   ransacReprojThreshold?: number;
-}): Mat | null;
+}): Mat | undefined;
 
-function perspectiveTransform(points: Point[], options: { M: Mat }): Point[] | null;
+function perspectiveTransform(points: Point[], options: { M: Mat }): Point[] | undefined;
 const templ = cv.imread("logo.png");
 const g1 = cv.cvtColor(src, cv.COLOR_BGR2GRAY);
 const g2 = cv.cvtColor(templ, cv.COLOR_BGR2GRAY);
@@ -1183,7 +1183,7 @@ cv.release(f2.descriptors);
 ### inpaint
 
 ```typescript
-function inpaint(mat: Mat, options: { mask: Mat; inpaintRadius?: number; flags?: number }): Mat | null;
+function inpaint(mat: Mat, options: { mask: Mat; inpaintRadius?: number; flags?: number }): Mat | undefined;
 ```
 
 | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
@@ -1201,10 +1201,10 @@ const out = cv.inpaint(src, { mask, flags: cv.INPAINT_TELEA });
 ```typescript
 function fastNlMeansDenoising(mat: Mat, options?: {
   h?: number; templateWindowSize?: number; searchWindowSize?: number;
-}): Mat | null;
+}): Mat | undefined;
 function fastNlMeansDenoisingColored(mat: Mat, options?: {
   h?: number; hColor?: number; templateWindowSize?: number; searchWindowSize?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 ```javascript
@@ -1217,10 +1217,10 @@ const d2 = cv.fastNlMeansDenoisingColored(src, { h: 3, hColor: 3 });
 ### 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;
+function LUT(mat: Mat, options: { lut: Mat }): Mat | undefined;
+function compare(src1: Mat, options: { src2: Mat; cmpop: number }): Mat | undefined;
+function min(src1: Mat, options: { src2: Mat }): Mat | undefined;
+function max(src1: Mat, options: { src2: Mat }): Mat | undefined;
 ```
 
 `cmpop` 使用 `CMP_EQ` / `CMP_GT` / `CMP_GE` / `CMP_LT` / `CMP_LE` / `CMP_NE`。
@@ -1235,14 +1235,14 @@ const lo = cv.min(a, { src2: b });
 ### connectedComponents / convexityDefects / isContourConvex / fitLine / fitEllipse
 
 ```typescript
-function connectedComponents(mat: Mat, options?: { connectivity?: number }): { count: number; labels: Mat } | null;
+function connectedComponents(mat: Mat, options?: { connectivity?: number }): { count: number; labels: Mat } | undefined;
 function convexityDefects(contour: Point[], options: { hull: number[] | Point[] }):
-  Array<{ start: number; end: number; farthest: number; depth: number }> | null;
+  Array<{ start: number; end: number; farthest: number; depth: number }> | undefined;
 function isContourConvex(contour: Point[]): boolean;
 function fitLine(points: Point[], options?: {
   distType?: number; param?: number; reps?: number; aeps?: number;
-}): [number, number, number, number] | null;
-function fitEllipse(points: Point[]): RotatedRect | null;
+}): [number, number, number, number] | undefined;
+function fitEllipse(points: Point[]): RotatedRect | undefined;
 ```
 
 `hull` 可为索引数组，或与 `convexHull` 返回格式相同的 Point[]。`fitEllipse` 至少需要 5 个点。
@@ -1261,16 +1261,16 @@ cv.release(cc.labels);
 ```typescript
 function getRectSubPix(mat: Mat, options: {
   patchSize: Size | [number, number]; center: Point;
-}): Mat | null;
+}): Mat | undefined;
 function phaseCorrelate(src1: Mat, options: { src2: Mat; window?: Mat }): {
   x: number; y: number; response?: number;
-} | null;
+} | undefined;
 function estimateAffine2D(options: {
   srcPoints: Point[]; dstPoints: Point[]; method?: number; ransacReprojThreshold?: number;
-}): Mat | null;
+}): Mat | undefined;
 function estimateAffinePartial2D(options: {
   srcPoints: Point[]; dstPoints: Point[]; method?: number; ransacReprojThreshold?: number;
-}): Mat | null;
+}): Mat | undefined;
 ```
 
 `phaseCorrelate` 估计两帧位移（滚动/拖拽）；`estimateAffinePartial2D` 为相似变换（平移+旋转+等比缩放）。
@@ -1286,11 +1286,11 @@ const M = cv.estimateAffinePartial2D({ srcPoints, dstPoints, method: cv.RANSAC }
 function drawMarker(mat: Mat, options: {
   position: Point; color?: number[] | string;
   markerType?: number; markerSize?: number; thickness?: number;
-}): Mat | null;
+}): Mat | undefined;
 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 | undefined;
+function fillConvexPoly(mat: Mat, options: { pts: Point[]; color?: number[] | string }): Mat | undefined;
 ```
 
 就地修改输入 Mat，返回同一句柄。适合调试标注匹配点、滑动方向等。
@@ -1337,6 +1337,6 @@ cv.fillConvexPoly(src, { pts: [{ x: 20, y: 20 }, { x: 70, y: 20 }, { x: 45, y: 6
 2. 路径 / msbundle / imageId / `screen` 只走 `imread`；其它 API 只接受 Mat 句柄。
 3. SIFT 描述子优先 `flannKnnMatch`；ORB 用 `BFMatcher` + `NORM_HAMMING`。
 4. 特征匹配前建议转灰度；大图可先 `pyrDown` / `resize`。
-5. `findHomography` 至少需要 4 对对应点，不足会返回 `null`。
+5. `findHomography` 至少需要 4 对对应点，不足会返回 `undefined`。
 6. 绘制类、`floodFill` 会改原图或指定目标句柄；需保留原图请先 `clone`。
 7. 与 `image` 互通时，两边句柄各自 `release`。

package/docs/api/plist.md

@@ -7,7 +7,7 @@
 ### read - 读取整个 plist。
 
 ```typescript
-function read(path: string): any | null;
+function read(path: string): any | undefined;
 ```
 
 **参数:**
@@ -60,7 +60,7 @@ plist.write(path, { name: "kuaijs" }, "binary");
 ### get - 按键读取。
 
 ```typescript
-function get(path: string, key: string | string[]): any | null;
+function get(path: string, key: string | string[]): any | undefined;
 ```
 
 **参数:**