ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/tomatoocr.md

@@ -0,0 +1,461 @@
+# TomatoOCR 模块
+
+TomatoOCR 模块提供基于 TomatoOCR 框架的文字识别和 YOLO 目标检测功能，支持多种识别模式和配置选项。
+
+该 ocr 为付费插件, 具体资费请联系https://www.52tomato.com, 如果购买请选择插件版-快点 JS-IOS
+
+## 功能概览
+
+- **文字识别**: 支持多语言文字识别，包括中文、英文、数字、繁体、日语、韩语等
+- **多种输入源**: 支持屏幕截图、文件路径、图像 ID 等多种输入方式
+- **灵活配置**: 提供丰富的参数配置选项
+- **点击点查找**: 根据文字内容查找可点击的位置
+
+## API 参考
+
+### 初始化方法
+
+#### `initializeWithConfig`
+
+初始化 TomatoOCR 引擎并设置基本配置。
+
+```lua
+---@param mode string
+---@param licenseData string
+---@param remark string?
+---@return any
+function initializeWithConfig(mode, licenseData, remark) end
+```
+
+**参数:**
+
+| 参数名        | 类型   | 是否必填 | 默认值 | 描述                                                               |
+| ------------- | ------ | -------- | ------ | ------------------------------------------------------------------ |
+| `mode`        | string | 是       |        | 运行模式，debug：调试模型；删除或传别的任何值为正式模式            |
+| `licenseData` | string | 是       |        | 授权码 请传入你在 TomatoOCR 官网申请的授权码 购买依赖版-IOS 后获取 |
+| `remark`      | string | 否       |        | 备注信息                                                           |
+
+**返回值:**
+
+- 成功时返回包含设备信息的对象，失败时返回 nil
+
+  | 参数名        | 类型   | 描述     |
+  | ------------- | ------ | -------- |
+  | `deviceId`    | string | 设备 ID  |
+  | `expiryTime`  | string | 过期时间 |
+  | `message`     | string | 消息     |
+  | `status`      | string | 状态     |
+  | `versionName` | string | 版本名称 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+-- 不带备注
+local result1 = tomatoocr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码"
+)
+-- 带备注
+local result2 = tomatoocr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码",
+  "测试环境"
+)
+print("结果1: " .. tostring(ToJsonString(result1)) .. ", 结果2: " .. tostring(ToJsonString(result2)))
+```
+
+### 配置方法
+
+#### `setHttpIntervalTime`
+
+设置 HTTP 请求间隔时间。
+
+```lua
+---@param second number
+function setHttpIntervalTime(second) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                              |
+| -------- | ------ | -------- | ------ | ------------------------------------------------- |
+| `second` | number | 是       |        | 间隔秒数，设置网络请求间隔时间，非必设置。0-86400 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setHttpIntervalTime(3600)
+```
+
+#### `setRecType`
+
+设置识别类型。
+
+```lua
+---@param recType string
+function setRecType(recType) end
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                                                                               |
+| --------- | ------ | -------- | ------ | ---------------------------------------------------------------------------------- |
+| `recType` | string | 是       |        | 识别类型，模型类型,默认 ch-3.0,除此之外还有 ch-2.0, ch, cht, japan, korean, number |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+-- 普通中英文识别，3.0版模型
+tomatoocr.setRecType("ch-3.0")
+-- 普通中英文识别，2.0版模型
+tomatoocr.setRecType("ch-2.0")
+-- 普通中英文识别，1.0版模型
+tomatoocr.setRecType("ch")
+-- 繁体
+tomatoocr.setRecType("cht")
+-- 日语
+tomatoocr.setRecType("japan")
+-- 韩语
+tomatoocr.setRecType("korean")
+-- 数字模型
+tomatoocr.setRecType("number")
+```
+
+#### `setDetBoxType`
+
+设置检测框类型。
+
+```lua
+---@param detBoxType string
+function setDetBoxType(detBoxType) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                               |
+| ------------ | ------ | -------- | ------ | ---------------------------------------------------------------------------------- |
+| `detBoxType` | string | 是       |        | 检测框类型，默认"rect": 由于手机上截图文本均为矩形文本；"quad"：可准确检测倾斜文本 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+-- 矩形文本
+tomatoocr.setDetBoxType("rect")
+-- 倾斜文本
+tomatoocr.setDetBoxType("quad")
+```
+
+#### `setDetScaleRatio`
+
+设置输入图片缩放大小的参数，非必设置，默认为 1.0。值范围 0.1-10.0 之间，如果图太小，可能出现检测不到的情况，则尝试放大图片，如设置 2.0；如果图太大，可能出现检测不到一起的情况，则尝试缩小图片，如设置 0.5
+
+```lua
+---@param detScaleRatio number
+function setDetScaleRatio(detScaleRatio) end
+```
+
+**参数:**
+
+| 参数名          | 类型   | 是否必填 | 默认值 | 描述           |
+| --------------- | ------ | -------- | ------ | -------------- |
+| `detScaleRatio` | number | 是       |        | 检测框缩放比例 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setDetScaleRatio(0.5)
+```
+
+#### `setDetUnclipRatio`
+
+设置检测框展开比例。
+
+```lua
+---@param detUnclipRatio number
+function setDetUnclipRatio(detUnclipRatio) end
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                            |
+| ---------------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `detUnclipRatio` | number | 是       |        | 设置检测模型框选文本范围大小的参数，非必设置，默认为 1.9。值范围 1.6-2.5 之间，值越大框选范围越大，值越小框选范围越小；当框选到了，但识别得分较低，就可以调整该参数改善准确率。 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setDetUnclipRatio(1.9)
+```
+
+#### `setRecScoreThreshold`
+
+设置识别分数阈值。
+
+```lua
+---@param recScoreThreshold number
+function setRecScoreThreshold(recScoreThreshold) end
+```
+
+**参数:**
+
+| 参数名              | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                     |
+| ------------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recScoreThreshold` | number | 是       |        | 设置识别模型过滤得分的参数，非必设置，默认 0.1。由于返回的识别结果数据太多太乱，可以通过设置该参数，过滤一些得分较低不准的数据，使得结果看起来更加简练。 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setRecScoreThreshold(0.1)
+```
+
+#### `setReturnType`
+
+设置返回类型。
+
+```lua
+---@param returnType string
+function setReturnType(returnType) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                 |
+| ------------ | ------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `returnType` | string | 是       |        | 设置调用插件识别返回格式的参数，非必设置，默认为 json。默认"json": 包含得分、坐标和文字；"text"：纯文字；"num"：纯数字；自定义输入想要返回的文本：".￥ 1234567890"，仅只返回这些内容 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setReturnType("json")
+```
+
+#### `setBinaryThresh`
+
+设置二值化阈值。
+
+```lua
+---@param binaryThresh number
+function setBinaryThresh(binaryThresh) end
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                                                                 |
+| -------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
+| `binaryThresh` | number | 是       |        | 设置图像二值化的参数，非必设置，默认 0，不进行二值化。二值化设定 0-255，常规情况下不需要设置，可配合中调试应用使用。 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setBinaryThresh(0)
+```
+
+#### `setRunMode`
+
+设置运行模式。
+
+```lua
+---@param runMode string
+function setRunMode(runMode) end
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                                                 |
+| --------- | ------ | -------- | ------ | ---------------------------------------------------- |
+| `runMode` | string | 是       |        | 运行模式，默认"fast": 快速模式；"accurate"：准确模式 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setRunMode("fast")
+```
+
+#### `setFilterColor`
+
+设置图像滤色参数。
+
+```lua
+---@param filterColor string
+---@param backgroundColor string
+function setFilterColor(filterColor, backgroundColor) end
+```
+
+**参数:**
+
+| 参数名            | 类型   | 是否必填 | 默认值 | 描述                                                                                               |
+| ----------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `filterColor`     | string | 是       | \_     | 颜色过滤，通过逗号相互连，第一个是颜色值，第二个是负偏色，第三个是正偏色；不同颜色之间以" \| "连接 |
+| `backgroundColor` | string | 是       | \_     | 滤色后的背景色，传""或 black 的时候，背景是黑色，传"white"的时候，背景是白色                       |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.setFilterColor("#41917A,38,38", "black")
+tomatoocr.setFilterColor("#41917A,38,38|#E091A8,50,50", "white")
+```
+
+### OCR 识别方法
+
+#### `ocrImage`
+
+对图像执行 OCR 识别。
+
+```lua
+---@param input string
+---@param type number
+---@param x number
+---@param y number
+---@param ex number
+---@param ey number
+---@return string
+function ocrImage(input, type, x, y, ex, ey) end
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                                                                                |
+| ------- | ------ | -------- | ------ | ----------------------------------------------------------------------------------- |
+| `input` | string | 是       |        | 输入源（imageId、URL 字符串、文件路径或"screen"）                                   |
+| `type`  | number | 是       |        | 识别类型，默认 3: 检测 + 识别；0: 只检测；1: 方向分类+识别；2: 只识别；3: 检测+识别 |
+| `x`     | number | 是       |        | 边界框左上角 x 坐标                                                                 |
+| `y`     | number | 是       |        | 边界框左上角 y 坐标                                                                 |
+| `ex`    | number | 是       |        | 边界框右下角 x 坐标                                                                 |
+| `ey`    | number | 是       |        | 边界框右下角 y 坐标                                                                 |
+
+**返回值:**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `string` | OCR 识别结果 JSON 字符串 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+-- 识别屏幕
+local result1 = tomatoocr.ocrImage("screen", 0, 0, 0, 0, 0)
+print("识别屏幕结果：" .. tostring(result1))
+-- 识别文件
+local result2 = tomatoocr.ocrImage("/path/to/image.png", 0, 0, 0, 0, 0)
+print("识别文件结果：" .. tostring(result2))
+-- 识别指定屏幕区域
+local result3 = tomatoocr.ocrImage("screen", 0, 100, 500, 300)
+print("识别指定屏幕区域结果：" .. tostring(result3))
+```
+
+### 点击点查找方法
+
+#### `findTapPoint`
+
+查找点击点。
+
+```lua
+---@param data string
+---@return string
+function findTapPoint(data) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `data` | string | 是       |        | 要找的文字 |
+
+**返回值:**
+
+| 类型     | 描述                                        |
+| -------- | ------------------------------------------- |
+| `string` | 找"要找的文字"的中心点 没有找到返回空字符串 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+local result = tomatoocr.findTapPoint(“确定”)
+print(result)
+```
+
+#### `findTapPoints`
+
+查找多个点击点。
+
+```lua
+---@param data string
+---@return string
+function findTapPoints(data) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `data` | string | 是       |        | 要找的文字 |
+
+**返回值:**
+
+| 类型     | 描述                                                    |
+| -------- | ------------------------------------------------------- |
+| `string` | 找"要找的文字"的所有相匹配的中心点 没有找到返回空字符串 |
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+local result = tomatoocr.findTapPoints(“确定”)
+print(result)
+```
+
+#### `release`
+
+释放 TomatoOCR SDK 已加载的 OCR 模型和内部资源。
+
+```lua
+function release() end
+```
+
+**示例:**
+
+```lua
+local tomatoocr = require("tomatoocr")
+tomatoocr.release()
+```
+
+## 完整示例
+
+```lua
+local tomatoocr = require("tomatoocr")
+-- 初始化 TomatoOCR 并设置基本配置
+local initResult = tomatoocr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码",
+  "测试环境" -- 可选备注
+)
+print("初始化结果:" + ToJsonString(initResult))
+-- 配置其他参数
+tomatoocr.setRecType("ch-3.0")
+-- 执行 OCR 识别
+local ocrResult = tomatoocr.ocrImage("screen", 3, 0, 0, 0, 0); -- 识别当前屏幕
+print("识别结果:" + ocrResult)
+-- 查找点击点
+local tapResult = tomatoocr.findTapPoint("登录")
+print("点击点坐标:" + tapResult)
+-- 释放 TomatoOCR 资源
+tomatoocr.release()
+```
+
+## 注意事项
+
+1. **参数配置**: 根据实际需求调整各种阈值和配置参数
+2. **错误处理**: 建议对返回的 JSON 结果进行错误检查