ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/image.md

@@ -0,0 +1,1177 @@
+# 图片模块 (Image)
+
+图片模块提供了强大的图像处理功能，包括截图、图像识别、模板匹配、颜色查找、图像变换等。
+
+注意所有的 `imageId` 都需要在使用后释放，否则会导致内存泄漏。
+
+所有传递`imageId`的函数都可以使用`"screen"`作为参数，来表示对当前屏幕进行操作。
+
+`"screen"` 在设置为`Agent`模式，使用`快点Agent`截图，录屏模式使用录屏截图。
+
+所有传递`imageId`的函数都可以使用`"shortcut"`作为参数，来表示指定 HID 快捷指令截图
+
+所有传递`imageId`的函数都可以使用`"actionScreenshot"`作为参数，来表示指定 HID 快捷键系统截图
+
+所有传递`imageId`的函数都可以使用图片路径作为参数，来表示对指定图片进行操作，支持 res 目录文件，和手机文件路径。
+
+## 图片获取与管理
+
+### captureScreen - 截取屏幕。
+
+坐标缺省 `0` 表示全屏。四个坐标都传 `0` 时与 `captureFullScreen` 相同。
+
+```lua
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@return string|nil
+function captureScreen(x, y, ex, ey) end
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `x`    | number | 否       | 0      | 区域左上角 X 坐标 |
+| `y`    | number | 否       | 0      | 区域左上角 Y 坐标 |
+| `ex`   | number | 否       | 0      | 区域右下角 X 坐标 |
+| `ey`   | number | 否       | 0      | 区域右下角 Y 坐标 |
+
+**返回值：**
+
+| 类型            | 描述                             |
+| --------------- | -------------------------------- |
+| `string \| nil` | 截图的图片 ID，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local file = require("file")
+local dir = file.getInternalDir("documents")
+
+-- 全屏截图
+local imageId = image.captureScreen()
+if imageId then
+  image.saveTo(imageId, dir .. "/screenshot.jpg")
+  image.release(imageId)
+end
+
+-- 截取指定区域
+local rectId = image.captureScreen(100, 100, 200, 200)
+if rectId then
+  image.saveTo(rectId, dir .. "/rect.jpg")
+  image.release(rectId)
+end
+```
+
+### captureFullScreen - 截取全屏。
+
+```lua
+---@return string|nil
+function captureFullScreen() end
+```
+
+**返回值：**
+
+| 类型            | 描述                             |
+| --------------- | -------------------------------- |
+| `string \| nil` | 截图的图片 ID，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local file = require("file")
+local imageId = image.captureFullScreen()
+local dir = file.getInternalDir("documents")
+if imageId then
+  print("截图成功")
+  image.saveTo(imageId, dir .. "/screenshot.jpg")
+  image.release(imageId)
+else
+  print("截图失败")
+end
+```
+
+### captureRect - 截取指定区域。
+
+```lua
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@return string|nil
+function captureRect(x, y, ex, ey) end
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `x`    | number | 否       | 0      | 区域左上角 X 坐标 |
+| `y`    | number | 否       | 0      | 区域左上角 Y 坐标 |
+| `ex`   | number | 否       | 0      | 区域右下角 X 坐标 |
+| `ey`   | number | 否       | 0      | 区域右下角 Y 坐标 |
+
+**返回值：**
+
+| 类型            | 描述                             |
+| --------------- | -------------------------------- |
+| `string \| nil` | 截图的图片 ID，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local file = require("file")
+local imageId = image.captureRect(100, 100, 200, 200)
+local dir = file.getInternalDir("documents")
+if imageId then
+  print("截图成功")
+  image.saveTo(imageId, dir .. "/screenshot.jpg")
+  image.release(imageId)
+else
+  print("截图失败")
+end
+```
+
+### readImage - 从文件路径或imageId读取图片。
+
+```lua
+---@param path string
+---@return string | nil
+function readImage(path) end
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                                                    |
+| ------ | ------ | -------- | ------ | ----------------------------------------------------------------------- |
+| `path` | string | 是       | -      | 图片文件路径 支持 res 目录文件和手机文件绝对路径，支持特殊标识的imageId |
+
+**返回值：**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `string` | 图片 ID，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.readImage("template.jpg")
+if imageId then
+  print("图片读取成功")
+-- 使用图片...
+  image.release(imageId)
+else
+  print("图片读取失败")
+end
+```
+
+### saveTo - 保存图片到指定路径。
+
+```lua
+---@param imageId string
+---@param filePath string
+---@return boolean
+function saveTo(imageId, filePath) end
+```
+
+**参数：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `imageId`  | string | 是       | -      | 图片 ID  |
+| `filePath` | string | 是       | -      | 保存路径 |
+
+**返回值：**
+
+| 类型      | 描述                                  |
+| --------- | ------------------------------------- |
+| `boolean` | `true` 表示保存成功，`false` 表示失败 |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+  image.saveTo(imageId, tostring(dir) .. "/screenshot.jpg")
+  image.release(imageId)
+end
+```
+
+## 内存管理
+
+### release - 释放单个图片的内存。
+
+```lua
+---@param imageId string
+function release(imageId) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述            |
+| --------- | ------ | -------- | ------ | --------------- |
+| `imageId` | string | 是       | -      | 要释放的图片 ID |
+
+### releaseAll - 释放所有图片的内存。
+
+```lua
+function releaseAll() end
+```
+
+### isRelease - 检查图片是否已被释放。
+
+```lua
+---@param imageId string
+---@return boolean
+function isRelease(imageId) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述    |
+| --------- | ------ | -------- | ------ | ------- |
+| `imageId` | string | 是       | -      | 图片 ID |
+
+**返回值：**
+
+| 类型      | 描述                                  |
+| --------- | ------------------------------------- |
+| `boolean` | `true` 表示已释放，`false` 表示未释放 |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  print("释放前: " .. tostring(image.isRelease(imageId))); -- false
+  image.release(imageId)
+  print("释放后: " .. tostring(image.isRelease(imageId))); -- true
+end
+```
+
+## 图片信息
+
+### getSize - 获取图片尺寸。
+
+```lua
+---@param imageId string
+---@return any
+function getSize(imageId) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述    |
+| --------- | ------ | -------- | ------ | ------- |
+| `imageId` | string | 是       | -      | 图片 ID |
+
+**返回值：**
+
+| 类型             | 描述                                                           |
+| ---------------- | -------------------------------------------------------------- |
+| `table \| nil` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  local size = image.getSize(imageId)
+  if size then
+    print("图片尺寸: " .. tostring(size.width) .. " x " .. tostring(size.height))
+  end
+  image.release(imageId)
+end
+```
+
+### pixel - 获取图片指定坐标的像素颜色值。
+
+```lua
+---@param imageId string
+---@param x number
+---@param y number
+---@return number
+function pixel(imageId, x, y) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述    |
+| --------- | ------ | -------- | ------ | ------- |
+| `imageId` | string | 是       | -      | 图片 ID |
+| `x`       | number | 是       | -      | X 坐标  |
+| `y`       | number | 是       | -      | Y 坐标  |
+
+**返回值：**
+
+| 类型     | 描述           |
+| -------- | -------------- |
+| `number` | 颜色值（整型） |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  local color = image.pixel(imageId, 100, 100)
+  local colorHex = image.argb(color)
+  print("坐标 (100, 100) 的颜色: " .. tostring(colorHex))
+  image.release(imageId)
+end
+```
+
+### argb - 将整型颜色值转换为 16 进制 RGB 字符串。
+
+```lua
+---@param color number
+---@return string
+function argb(color) end
+```
+
+**参数：**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述       |
+| ------- | ------ | -------- | ------ | ---------- |
+| `color` | number | 是       | -      | 整型颜色值 |
+
+**返回值：**
+
+| 类型     | 描述               |
+| -------- | ------------------ |
+| `string` | 16 进制 RGB 字符串 |
+
+## 颜色识别
+
+### findColor - 单点找色
+
+```lua
+---@param imageId string
+---@param color string
+---@param threshold number
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@param limit number
+---@param orz number
+---@return any
+function findColor(imageId, color, threshold, x, y, ex, ey, limit, orz) end
+```
+
+**参数：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ----------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `imageId`   | string | 是       | -      | 图片 ID                                                                                                                                                                                                                                 |
+| `color`     | string | 是       | -      | 颜色值，支持 "主色-偏色" 格式，如 "#6DD1E6-#101010"                                                                                                                                                                                     |
+| `threshold` | number | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `x, y`      | number | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `ex, ey`    | number | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `limit`     | number | 是       | -      | 最大查找数量                                                                                                                                                                                                                            |
+| `orz`       | number | 是       | -      | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型    | 描述                                           |
+| ------- | ---------------------------------------------- |
+| `array` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+-- 查找蓝色按钮
+  local points = image.findColor(
+    imageId,
+    "#1E90FF-#101010", -- 蓝色，允许一定偏差
+    0.9, -- 阈值
+    0,
+    0, -- 搜索区域左上角
+    400,
+    800, -- 搜索区域右下角
+    5, -- 最多找 5 个
+    1, -- 从左到右查找
+  )
+
+  if #points > 0 then
+    print("找到 " .. tostring(#points) .. " 个蓝色点")
+-- 点击第一个找到的点
+    action.click(points[1].x, points[1].y, 100, false)
+  end
+
+  image.release(imageId)
+end
+```
+
+### findMultiColor - 多点找色
+
+```lua
+---@param imageId string
+---@param firstColor string
+---@param threshold number
+---@param points string
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@param limit number
+---@param orz number
+---@return any
+function findMultiColor(imageId, firstColor, threshold, points, x, y, ex, ey, limit, orz) end
+```
+
+**参数：**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ------------ | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `imageId`    | string | 是       | -      | 图片 ID                                                                                                                                                                                                                                 |
+| `firstColor` | string | 是       | -      | 第一个颜色                                                                                                                                                                                                                              |
+| `threshold`  | number | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `points`     | string | 是       | -      | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色`                                                                                                                                                             |
+| `x, y`       | number | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `ex, ey`     | number | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `limit`      | number | 是       | -      | 最大查找数量                                                                                                                                                                                                                            |
+| `orz`        | number | 是       | -      | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型    | 描述                                           |
+| ------- | ---------------------------------------------- |
+| `array` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+-- 查找特定的颜色组合（如按钮的特征颜色）
+  local points = image.findMultiColor(
+    imageId,
+    "#1E90FF-#101010", -- 主颜色
+    0.9, -- 阈值
+    "10|0|#FFFFFF-#101010,20|0|#000000-#101010", -- 相对位置的其他颜色
+    0,
+    0,
+    400,
+    800,
+    1,
+    1,
+  )
+
+  if #points > 0 then
+    print("找到匹配的颜色组合")
+    action.click(points[1].x, points[1].y, 100, false)
+  end
+
+  image.release(imageId)
+end
+```
+
+### countColor - 统计颜色数量
+
+统计指定区域内命中目标颜色的像素数量。`colors` 可以传入一个或多个候选颜色，多个颜色使用 `|` 分隔，支持 `主色-偏色` 格式，如 `#0A0A0A-#101010|#FFFFFF-#101010`。同一个像素同时命中多个候选颜色时只统计一次。
+
+```lua
+---@param imageId string
+---@param colors string
+---@param threshold number
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@return number
+function countColor(imageId, colors, threshold, x, y, ex, ey) end
+```
+
+**参数：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                                                                 |
+| ----------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------ |
+| `imageId`   | string | 是       | -      | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID               |
+| `colors`    | string | 是       | -      | 颜色列表，支持 `主色-偏色\|主色-偏色` 格式，如 `#0A0A0A-#101010\|#FFFFFF-#101010` |
+| `threshold` | number | 是       | -      | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格                                           |
+| `x, y`      | number | 是       | -      | 统计区域左上角坐标                                                                   |
+| `ex, ey`    | number | 是       | -      | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界                              |
+
+**返回值：**
+
+| 类型     | 描述                                                                                 |
+| -------- | ------------------------------------------------------------------------------------ |
+| `number` | 命中目标颜色的像素数量；图片加载失败、颜色为空、颜色格式无效或区域不合法时返回 `0` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  local count = image.countColor(
+    imageId,
+    "#0A0A0A-#101010|#FFFFFF-#101010",
+    0.92,
+    100,
+    200,
+    500,
+    700,
+  )
+
+  print("目标区域命中颜色像素数量: " .. tostring(count))
+  image.release(imageId)
+end
+```
+
+### cmpColor - 多点比色
+
+```lua
+---@param imageId string
+---@param points string
+---@param threshold number
+---@return boolean
+function cmpColor(imageId, points, threshold) end
+```
+
+**参数：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                                                        |
+| ----------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
+| `imageId`   | string | 是       | -      | 图片 ID                                                                     |
+| `points`    | string | 是       | -      | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色` |
+| `threshold` | number | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                      |
+
+**返回值：**
+
+| 类型      | 描述                                        |
+| --------- | ------------------------------------------- |
+| `boolean` | 如果颜色匹配则返回 `true`，否则返回 `false` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+-- 检查特定区域是否为预期颜色
+  local isMatch = image.cmpColor(
+    imageId,
+    "1|2|#6DD1E6-#101010",
+    0.9, -- 阈值
+  )
+
+  if isMatch then
+    print("颜色匹配")
+  end
+
+  image.release(imageId)
+end
+```
+
+## 图像识别
+
+### findImage - 找图
+
+在大图（通常是屏幕截图）中查找小图（模板）。支持多种匹配算法，可按 `|` 同时传入多个模板。
+
+```lua
+---@param imageId string
+---@param templateImageId string
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@param threshold number
+---@param limit number
+---@param method number
+---@param rgb boolean?
+---@param options table?
+---@return any
+function findImage(imageId, templateImageId, x, y, ex, ey, threshold, limit, method, rgb, options) end
+```
+
+**参数：**
+
+| 参数名                 | 类型      | 是否必填 | 默认值                      | 描述                                                                                                                                 |
+| ---------------------- | --------- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `imageId`              | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                       |
+| `templateImageId`      | string    | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找        |
+| `x, y`                 | number    | 是       | -                           | 搜索区域左上角坐标                                                                                                                   |
+| `ex, ey`               | number    | 是       | -                           | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界                                                                              |
+| `threshold`            | number    | 是       | -                           | 匹配阈值 (0.0-1.0)。method `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995`                                   |
+| `limit`                | number    | 是       | -                           | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                                    |
+| `method`               | number    | 是       | -                           | 匹配方法，见下方说明                                                                                                                 |
+| `rgb`                  | boolean   | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                                     |
+| `options`              | table    | 否       | -                           | 额外选项，目前仅 method=`99` 时生效                                                                                                  |
+| `options.scaleFactors` | number\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
+
+#### method 匹配方法说明
+
+| method | 名称                   | 原理简述                                                                                         | 适用场景                                         | 速度     |
+| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- |
+| `5`    | TM_CCOEFF_NORMED       | 标准模板匹配（归一化相关系数），模板必须与目标**像素尺寸一致**                                   | 同分辨率、同尺寸截图模板，最常用                 | 快       |
+| `3`    | TM_CCORR_NORMED        | 标准模板匹配（归一化相关）                                                                       | 同尺寸模板；PNG 透明模板带 mask 时内部会优先用它 | 快       |
+| `1`    | TM_SQDIFF_NORMED       | 标准模板匹配（归一化平方差），分数越小越像，引擎已换算为越大越像                                 | 同尺寸模板                                       | 快       |
+| `0`    | SIFT 全分辨率          | 提取 SIFT 特征点做匹配，对旋转、轻微形变更鲁棒，不要求模板与目标同尺寸                           | 目标可能旋转/形变，或跨分辨率找图                | 较慢     |
+| `99`   | 全分辨率缩放匹配法     | 把**模板**按多个比例缩放后，再做 `TM_CCOEFF_NORMED` 模板匹配（有透明通道时用 `TM_CCORR_NORMED`） | 目标与模板尺寸不完全一致，但形状相同             | 中等偏慢 |
+
+#### 什么是「缩放」全分辨率找图（method = 99）
+
+这里的「缩放」**不是**把屏幕截图缩小，也**不是**设备显示缩放（`device.getScreenScale()`），而是：
+
+> 在匹配前，把**模板小图**按 `scaleFactors` 里的比例逐个放大/缩小，再与**原尺寸**搜索区域做模板匹配。
+
+- `factor = 1.0`：模板保持原像素尺寸去匹配
+- `factor < 1.0`：先把模板缩小再匹配（当前屏幕上的目标比模板更小）
+- `factor > 1.0`：先把模板放大再匹配（当前屏幕上的目标比模板更大）
+
+引擎内部是 `Imgproc.resize(template, fx=factor, fy=factor)`，**横向、纵向使用同一个比例**（等比缩放）。  
+返回结果里的 `width` / `height` 是缩放后的模板尺寸，`scaleX` / `scaleY` 是本次命中用到的比例。
+
+工作流程：
+
+1. 读取搜索区域（大图）和模板（小图），默认转灰度（`rgb=true` 时保留彩色）。
+2. 按 `scaleFactors` **数组顺序**，对模板执行等比缩放。
+3. 若缩放后的模板比搜索区域还大，跳过该比例。
+4. 用缩放后的模板做 `TM_CCOEFF_NORMED` 匹配（透明 PNG 用 `TM_CCORR_NORMED` + alpha mask）。
+5. 收集 `confidence >= threshold` 的命中；重叠区域去重，保留置信度更高者。
+6. 找满 `limit` 个后提前结束——所以**更可能命中的比例要放前面**。
+
+#### 如何选择 `scaleFactors`（重点）
+
+`scaleFactors` 不是随便填几个小数，而是回答这个问题：
+
+> 「模板图里的目标，到当前屏幕上会变成原来的几倍宽/高？」
+
+##### 1. 先算「目标比例」baseScale
+
+UI 随分辨率等比变化时（大多数 App / 游戏界面）：
+
+```text
+baseScale = 当前设备逻辑宽 / 截取模板时设备的逻辑宽
+```
+
+也可用高：
+
+```text
+baseScale = 当前设备逻辑高 / 截取模板时设备的逻辑高
+```
+
+宽高比一致时两者相同；不一致时优先用**与布局更相关的那条边**（竖屏 App 常用高，横屏游戏常用宽），或取两者平均。
+
+这里的「逻辑宽高」请用找图坐标系对应的尺寸，一般是 `device.getScreenRealSize()`（实际像素分辨率）。  
+**不要**把 `device.getScreenScale()`（屏幕 scale 因子）直接当成 `scaleFactors` 里的值——两者不是一回事。
+
+若你确切知道模板像素尺寸和屏幕上目标像素尺寸，也可以直接：
+
+```text
+baseScale = 屏幕上目标宽度(px) / 模板宽度(px)
+// 或
+baseScale = 屏幕上目标高度(px) / 模板高度(px)
+```
+
+**数值例子：**
+
+| 截模板设备     | 当前运行设备   | 计算                         | baseScale |
+| -------------- | -------------- | ---------------------------- | --------- |
+| iPhone 8 750px | 同机           | 750 / 750                    | `1.0`     |
+| 750 宽         | 1170 宽        | 1170 / 750                   | `1.56`    |
+| 1170 宽        | 750 宽         | 750 / 1170                   | `0.641`   |
+| 1080 宽安卓    | 1440 宽安卓    | 1440 / 1080                  | `1.333`   |
+| 模板按钮 120px | 屏上按钮 96px  | 96 / 120                     | `0.8`     |
+
+含义对照：
+
+| baseScale | 含义                                       | 引擎会对模板做什么      |
+| --------- | ------------------------------------------ | ----------------------- |
+| `1.0`     | 当前目标与模板同尺寸                       | 不缩放                  |
+| `0.64`    | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配         |
+| `1.56`    | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配      |
+
+##### 2. 再围绕 baseScale 生成搜索列表
+
+真实设备上还会有状态栏、安全区、App 缩放、截图工具裁切误差等，baseScale 很少绝对精确，所以要在 baseScale **附近扫一小段**：
+
+```text
+scaleFactors ≈ [ baseScale,
+                 baseScale ± step,
+                 baseScale ± 2*step,
+                 ... ]
+```
+
+推荐参数：
+
+| 项目           | 建议                                      | 原因 |
+| -------------- | ----------------------------------------- | ---- |
+| 中心值         | 算出来的 `baseScale`                      | 最可能命中，必须放第一位 |
+| 步进 `step`    | `0.05`～`0.1`                             | 太疏容易跳过真实尺寸；太密浪费时间 |
+| 半宽度         | `±0.1`～`±0.2`（约 ±10%～20%）            | 覆盖状态栏/安全区/轻微布局差 |
+| 总档数         | 3～7 个                                   | 每多一档就多跑一轮全图模板匹配 |
+| 阈值 threshold | `0.5`～`0.6` 起调                         | 缩放插值会降低相关分数，别用 0.9+ |
+| 顺序           | **baseScale 最先**，再左右交替扩开        | 找满 limit 会提前结束 |
+
+生成示例（伪代码思路）：
+
+```lua
+-- 截模板时的设备宽（写进脚本配置，或写在模板文件名里）
+local templateDeviceWidth = 750
+-- 当前设备实际宽
+local currentWidth = device.getScreenRealSize().width
+local baseScale = currentWidth / templateDeviceWidth
+-- 围绕 baseScale，步进 0.05，左右各扩 2 档 → 共 5 个
+local function buildScaleFactors(base, step = 0.05, halfRange = 2)
+  local list = [Number(base.toFixed(4))]
+  for i = 1, halfRange do
+    list.push(Number((base - step * i).toFixed(4)))
+    list.push(Number((base + step * i).toFixed(4)))
+  end
+-- 过滤掉无意义的比例
+  return list.filter((s) => s > 0.05  and  s < 8)
+end
+
+local scaleFactors = buildScaleFactors(baseScale)
+-- 例如 baseScale=1.56, step=0.05, halfRange=2
+-- → [1.56, 1.51, 1.61, 1.46, 1.66]
+```
+
+##### 3. 按场景怎么选
+
+| 场景 | 怎么设 `scaleFactors` | threshold |
+| ---- | --------------------- | --------- |
+| 模板就是本机截的，尺寸确定一致 | 不必用 99，直接 method `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
+| 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
+| 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
+| 完全不知道模板来源分辨率 | 先用 method `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
+| 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
+| 横竖屏切换 / 目标会旋转 | method `99` **不够**，改用 method `0` SIFT | `0.5`～`0.6` |
+
+默认值 `[1.0, 0.9, 1.1, 0.8, 1.2]` 的定位：
+
+- 假设「模板大致接近当前尺寸」，在 80%～120% 之间盲扫
+- **只适合尺寸差不大的兜底**，不适合 750 ↔ 1170 这种跨度（baseScale≈1.56，默认列表根本扫不到）
+- 生产脚本应**按设备算 baseScale**，不要依赖这组默认值硬扛跨分辨率
+
+##### 4. 常见误区
+
+1. **把 `device.getScreenScale()` 填进 scaleFactors**  
+   `getScreenScale()` 是屏幕 scale（如 2x/3x 显示倍率），不是「模板相对当前图」的缩放比。
+
+2. **跨大分辨率仍用默认 `[1.0, 0.9, 1.1, 0.8, 1.2]`**  
+   真实 baseScale 在 1.5 时，默认列表全军覆没。
+
+3. **threshold 仍用 0.9**  
+   resize 插值会损失细节，method `99` 相关分通常明显低于同尺寸 method `5`，建议从 `0.55` 左右调。
+
+4. **档位又多又密**  
+   全屏 × 10 个 factor ≈ 10 次模板匹配，卡顿明显。先算准 baseScale，再小范围扩。
+
+5. **模板含大量透明/JPEG 压缩噪点**  
+   缩放后更易误匹配；优先 PNG 透明模板，并尽量裁紧目标外轮廓。
+
+6. **搜索区域小于放大后的模板**  
+   该 factor 会被跳过。放大场景请保证 ROI 足够大，或全屏搜。
+
+##### 5. 与 method `0`（SIFT）怎么选
+
+|                | method `99` 缩放匹配               | method `0` SIFT                    |
+| -------------- | ---------------------------------- | ---------------------------------- |
+| 尺寸变化       | 支持（靠你提供的比例穷举）         | 支持（特征点，不靠固定比例）       |
+| 你需要知道比例 | 最好先算 baseScale                 | 不需要                             |
+| 旋转 / 形变    | 基本不支持                         | 较鲁棒                             |
+| 阈值建议       | `0.5`–`0.6`                        | `0.5`–`0.6`                        |
+| 透明 PNG 模板  | 支持（alpha 作权重 mask）          | 支持（alpha 作特征掩码）           |
+| 性能           | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢               |
+| 推荐           | 比例可估算的跨分辨率找图           | 比例未知、或有旋转/透视时          |
+
+**返回值：**
+
+| 类型    | 描述                                                                                                                                      |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `array` | 匹配结果数组。`index` 为模板在 `templateImageId` 中的索引（从 0 开始）。method=`99` 时额外包含 `scaleX`、`scaleY`（本次命中使用的缩放比） |
+
+**示例：**
+
+```lua
+local image = require("image")
+-- 1) 同分辨率标准找图（最常用，模板就是本机截的）
+local matches = image.findImage(
+  "screen",
+  "template.jpg|template2.jpg",
+  0,
+  0,
+  400,
+  800,
+  0.9,
+  3,
+  5, -- TM_CCOEFF_NORMED
+  false,
+)
+
+if #matches > 0 then
+  local best = matches[1]
+  print("找到匹配，置信度: " .. tostring(best.confidence))
+  action.click(best.centerX, best.centerY, 100, false)
+end
+-- 2) 缩放全分辨率找图：按「截模板设备宽 / 当前设备宽」计算比例
+--    假设模板是在宽度 750 的设备上截的
+local templateDeviceWidth = 750
+local currentWidth = device.getScreenRealSize().width
+local baseScale = currentWidth / templateDeviceWidth
+
+local function buildScaleFactors(base, step = 0.05, halfRange = 2)
+  local list = [Number(base.toFixed(4))]
+  for i = 1, halfRange do
+    list.push(Number((base - step * i).toFixed(4)))
+    list.push(Number((base + step * i).toFixed(4)))
+  end
+  return list.filter((s) => s > 0.05  and  s < 8)
+end
+
+local scaleFactors = buildScaleFactors(baseScale)
+-- 750 → 1170 时约等于 [1.56, 1.51, 1.61, 1.46, 1.66]
+print("baseScale=" .. tostring(baseScale.toFixed(3)) .. " scaleFactors=" .. tostring(ToJsonString(scaleFactors)))
+
+local scaled = image.findImage(
+  "screen",
+  "btn_start.png",
+  0,
+  0,
+  0,
+  0, -- 全屏；放大模板时 ROI 太小会被跳过
+  0.55, -- 多尺度建议 0.5-0.6，不要用 0.9
+  1,
+  99,
+  false,
+  { scaleFactors },
+)
+
+if #scaled > 0 then
+  local hit = scaled[1]
+  print(
+    "命中 scale=" .. tostring(hit.scaleX) .. " 尺寸=" .. tostring(hit.width) .. "x" .. tostring(hit.height) .. " 置信度=" .. tostring(hit.confidence),
+  )
+  action.click(hit.centerX, hit.centerY, 100, false)
+end
+-- 3) 已知模板宽和屏幕目标大概宽时，直接用像素比
+-- local baseScale = expectedTargetWidthPx / templateWidthPx
+```
+
+## 图像处理
+
+### clip - 裁剪图片。
+
+```lua
+---@param imageId string
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@return string
+function clip(imageId, x, y, ex, ey) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述               |
+| --------- | ------ | -------- | ------ | ------------------ |
+| `imageId` | string | 是       | -      | 原图片 ID          |
+| `x, y`    | number | 是       | -      | 裁剪区域左上角坐标 |
+| `ex, ey`  | number | 是       | -      | 裁剪区域右下角坐标 |
+
+**返回值：**
+
+| 类型     | 描述              |
+| -------- | ----------------- |
+| `string` | 裁剪后的新图片 ID |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+-- 裁剪屏幕上半部分
+  local screen = device.getScreenRealSize()
+  local clippedId = image.clip(imageId, 0, 0, screen.width, screen.height / 2)
+
+  if clippedId then
+    image.saveTo(clippedId, tostring(dir) .. "/top_half.jpg")
+    image.release(clippedId)
+  end
+
+  image.release(imageId)
+end
+```
+
+### rotateImage - 旋转图片。
+
+```lua
+---@param imageId string
+---@param degree number
+---@return string | nil
+function rotateImage(imageId, degree) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                          |
+| --------- | ------ | -------- | ------ | ----------------------------- |
+| `imageId` | string | 是       | -      | 原图片 ID                     |
+| `degree`  | number | 是       | -      | 旋转角度，只能是 90、-90、180 |
+
+**返回值：**
+
+| 类型             | 描述                                |
+| ---------------- | ----------------------------------- |
+| `string \| nil` | 旋转后的新图片 ID 失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.readImage("photo.jpg")
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+  local rotatedId = image.rotateImage(imageId, 90)
+  if rotatedId then
+    image.saveTo(rotatedId, tostring(dir) .. "/photo_rotated.jpg")
+    image.release(rotatedId)
+  end
+  image.release(imageId)
+end
+```
+
+### gray - 将图片转换为灰度图。
+
+```lua
+---@param imageId string
+---@return string
+function gray(imageId) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述      |
+| --------- | ------ | -------- | ------ | --------- |
+| `imageId` | string | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `string` | 灰度化后的新图片 ID |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+  local grayId = image.gray(imageId)
+  image.saveTo(grayId, tostring(dir) .. "/screenshot_gray.jpg")
+  image.release(grayId)
+  image.release(imageId)
+end
+```
+
+### binaryzation - 将图片进行二值化处理。
+
+```lua
+---@param imageId string
+---@param threshold number
+---@return string
+function binaryzation(imageId, threshold) end
+```
+
+**参数：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                   |
+| ----------- | ------ | -------- | ------ | ---------------------- |
+| `imageId`   | string | 是       | -      | 原图片 ID              |
+| `threshold` | number | 是       | -      | 二值化阈值 (0.0-255.0) |
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `string` | 二值化后的新图片 ID |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+  local binaryId = image.binaryzation(imageId, 128)
+  image.saveTo(binaryId, tostring(dir) .. "/screenshot_binary.jpg")
+  image.release(binaryId)
+  image.release(imageId)
+end
+```
+
+### drawRect - 绘制矩形。
+
+```lua
+---@param imageId string
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@param color string
+---@param thickness number
+function drawRect(imageId, x, y, ex, ey, color, thickness) end
+```
+
+**参数：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                        |
+| ----------- | ------ | -------- | ------ | --------------------------- |
+| `imageId`   | string | 是       | -      | 原图片 ID                   |
+| `x, y`      | number | 是       | -      | 矩形左上角坐标              |
+| `ex, ey`    | number | 是       | -      | 矩形右下角坐标              |
+| `color`     | string | 是       | -      | 颜色，如 "#FF0000" 表示红色 |
+| `thickness` | number | 是       | -      | 线宽                        |
+
+**示例：**
+
+```lua
+local image = require("image")
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+
+local imageId = image.captureFullScreen()
+if imageId then
+  image.drawRect(imageId, 100, 100, 200, 100, "#FF0000", 2)
+  image.saveTo(imageId, tostring(dir) .. "/test.jpg")
+  image.release(imageId)
+end
+```
+
+### scanCode - 扫码条码（支持一维码和二维码）
+
+```lua
+---@param imageId string
+---@return string | nil
+function scanCode(imageId) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述      |
+| --------- | ------ | -------- | ------ | --------- |
+| `imageId` | string | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型             | 描述                        |
+| ---------------- | --------------------------- |
+| `string \| nil` | 扫码结果，失败时返回 `nil` |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  local result = image.scanCode(imageId)
+  if result then
+    print("扫码结果: " .. tostring(result))
+  else
+    print("扫码失败")
+  end
+  image.release(imageId)
+end
+```
+
+## Base64 转换
+
+### base64ToImage - 将 Base64 字符串转换为图片。
+
+```lua
+---@param base64 string
+---@return string
+function base64ToImage(base64) end
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述          |
+| -------- | ------ | -------- | ------ | ------------- |
+| `base64` | string | 是       | -      | Base64 字符串 |
+
+**返回值：**
+
+| 类型     | 描述            |
+| -------- | --------------- |
+| `string` | 转换后的图片 ID |
+
+**示例：**
+
+```lua
+local image = require("image")
+local base64Data =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="
+local imageId = image.base64ToImage(base64Data)
+-- 获取手机文档目录
+local dir = file.getInternalDir("documents")
+if imageId then
+  image.saveTo(imageId, tostring(dir) .. "/base64.jpg")
+  image.release(imageId)
+end
+```
+
+### toBase64Format - 将图片转换为 Base64 字符串。
+
+```lua
+---@param imageId string
+---@param format string
+---@param q number
+---@return string
+function toBase64Format(imageId, format, q) end
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                           |
+| --------- | ------ | -------- | ------ | ------------------------------ |
+| `imageId` | string | 是       | -      | 原图片 ID                      |
+| `format`  | string | 是       | -      | 图片格式（如 "jpg", "png"）    |
+| `q`       | number | 是       | -      | 质量 (1-100)，数字越大质量越高 |
+
+**返回值：**
+
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `string` | 转换后的 Base64 字符串 |
+
+**示例：**
+
+```lua
+local image = require("image")
+local imageId = image.captureFullScreen()
+if imageId then
+  local base64 = image.toBase64Format(imageId, "jpg", 90)
+  print("Base64 数据: " .. tostring(base64.substring(0, 100)) .. "...")
+  image.release(imageId)
+end
+```
+