ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apipython/tomatoocr.md

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