ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apipython/image.md

@@ -0,0 +1,938 @@
+# 图片模块 (Image)
+
+图片模块提供了强大的图像处理功能，包括截图、图像识别、模板匹配、颜色查找、图像变换等。
+
+注意所有的 `imageId` 都需要在使用后释放，否则会导致内存泄漏。
+
+所有传递`imageId`的函数都可以使用`"screen"`作为参数，来表示对当前屏幕进行操作。
+
+`"screen"` 在设置为`Agent`模式，使用`快点Agent`截图，录屏模式使用录屏截图。
+
+所有传递`imageId`的函数都可以使用`"shortcut"`作为参数，来表示指定 HID 快捷指令截图
+
+所有传递`imageId`的函数都可以使用`"actionScreenshot"`作为参数，来表示指定 HID 快捷键系统截图
+
+所有传递`imageId`的函数都可以使用图片路径作为参数，来表示对指定图片进行操作，支持 res 目录文件，和手机文件路径。
+
+## 图片获取与管理
+
+### captureScreen - 截取屏幕
+
+```python
+def captureScreen(x: Optional[int] = 0, y: Optional[int] = 0, ex: Optional[int] = 0, ey: Optional[int] = 0) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `x`    | number | 否       | 0      | 区域左上角 X 坐标 |
+| `y`    | number | 否       | 0      | 区域左上角 Y 坐标 |
+| `ex`   | number | 否       | 0      | 区域右下角 X 坐标 |
+| `ey`   | number | 否       | 0      | 区域右下角 Y 坐标 |
+
+**返回值：**
+
+| 类型          | 描述                             |
+| ------------- | -------------------------------- |
+| `str \| None` | 截图的图片 ID，失败时返回 `None` |
+
+**示例：**
+
+```python
+# 截取全屏
+imageId = image.captureScreen()
+# 获取手机文档目录
+dir = file.getInternalDir("documents")
+if imageId:
+  print("截图成功")
+  image.saveTo(imageId, f"{dir}/screenshot.jpg")
+  image.release(imageId) # 记得释放内存
+else:
+  print("截图失败")
+
+# 截取指定区域
+imageId = image.captureScreen(100, 100, 200, 200)
+# 获取手机文档目录
+dir = file.getInternalDir("documents")
+if imageId:
+  print("截图成功")
+  image.saveTo(imageId, f"{dir}/screenshot.jpg")
+  image.release(imageId) # 记得释放内存
+else:
+  print("截图失败")
+```
+
+### captureFullScreen - 截取设备全屏。
+
+```python
+def captureFullScreen() -> Optional[str]
+```
+
+**返回值：**
+
+| 类型          | 描述                             |
+| ------------- | -------------------------------- |
+| `str \| None` | 截图的图片 ID，失败时返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+imageId = image.captureFullScreen()
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    print("截图成功")
+    image.saveTo(imageId, f"{dir_path}/screenshot.jpg")
+    image.release(imageId) # 记得释放内存
+else:
+    print("截图失败")
+```
+
+### captureRect - 截取设备指定区域。
+
+```python
+def captureRect(x: int, y: int, ex: int, ey: int) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名      | 类型 | 是否必填 | 默认值 | 描述           |
+| ----------- | ---- | -------- | ------ | -------------- |
+| `x,y,ex,ey` | int  | 是       | <br /> | 左上与右下坐标 |
+
+**返回值：**
+
+| 类型          | 描述                             |
+| ------------- | -------------------------------- |
+| `str \| None` | 截图的图片 ID，失败时返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureRect(100, 100, 200, 200)
+if imageId:
+    print("截图成功")
+    image.saveTo(imageId, "rect.jpg")
+    image.release(imageId)
+else:
+    print("截图失败")
+```
+
+### readImage - 从文件路径或imageId读取图片。
+
+```python
+def readImage(path: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                                                                    |
+| ------ | ---- | -------- | ------ | ----------------------------------------------------------------------- |
+| `path` | str  | 是       | <br /> | 图片文件路径 支持 res 目录文件和手机文件绝对路径，支持特殊标识的imageId |
+
+**返回值：**
+
+| 类型          | 描述                       |
+| ------------- | -------------------------- |
+| `str \| None` | 图片 ID，失败时返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.readImage("template.jpg")
+if imageId:
+    print("图片读取成功")
+    # 使用图片...
+    image.release(imageId)
+else:
+    print("图片读取失败")
+```
+
+### saveTo - 保存图片到指定路径。
+
+```python
+def saveTo(id: str, path: str) -> bool
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述     |
+| ------ | ---- | -------- | ------ | -------- |
+| `id`   | str  | 是       | <br /> | 图片 ID  |
+| `path` | str  | 是       | <br /> | 保存路径 |
+
+**返回值：**
+
+| 类型   | 描述                                  |
+| ------ | ------------------------------------- |
+| `bool` | `True` 表示保存成功，`False` 表示失败 |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+imageId = image.captureFullScreen()
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    image.saveTo(imageId, f"{dir_path}/screenshot.jpg")
+    image.release(imageId)
+```
+
+## 内存管理
+
+### release - 释放单个图片的内存。
+
+```python
+def release(id: str) -> None
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述            |
+| ------ | ---- | -------- | ------ | --------------- |
+| `id`   | str  | 是       | <br /> | 要释放的图片 ID |
+
+### releaseAll - 释放所有图片的内存。
+
+```python
+def releaseAll() -> None
+```
+
+### isRelease - 检查图片是否已被释放。
+
+```python
+def isRelease(id: str) -> bool
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述    |
+| ------ | ---- | -------- | ------ | ------- |
+| `id`   | str  | 是       | <br /> | 图片 ID |
+
+**返回值：**
+
+| 类型   | 描述                                  |
+| ------ | ------------------------------------- |
+| `bool` | `True` 表示已释放，`False` 表示未释放 |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    print(f"释放前: {image.isRelease(imageId)}") # False
+    image.release(imageId)
+    print(f"释放后: {image.isRelease(imageId)}") # True
+```
+
+## 图片信息
+
+### getSize - 获取图片尺寸。
+
+```python
+from typing import TypedDict, Optional
+
+class Size(TypedDict):
+    width: int
+    height: int
+
+def getSize(id: str) -> Optional[Size]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述    |
+| ------ | ---- | -------- | ------ | ------- |
+| `id`   | str  | 是       | <br /> | 图片 ID |
+
+**返回值：**
+
+| 类型           | 描述                                                           |
+| -------------- | -------------------------------------------------------------- |
+| `Size \| None` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    size = image.getSize(imageId)
+    if size:
+        print(f"图片尺寸: {size.width} x {size.height}")
+    image.release(imageId)
+```
+
+### pixel - 获取图片指定坐标的像素颜色值。
+
+```python
+def pixel(id: str, x: int, y: int) -> int
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述    |
+| ------ | ---- | -------- | ------ | ------- |
+| `id`   | str  | 是       | <br /> | 图片 ID |
+| `x,y`  | int  | 是       | <br /> | 坐标    |
+
+**返回值：**
+
+| 类型  | 描述           |
+| ----- | -------------- |
+| `int` | 颜色值（整型） |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    color = image.pixel(imageId, 100, 100)
+    colorHex = image.argb(color)
+    print(f"坐标 (100, 100) 的颜色: {colorHex}")
+    image.release(imageId)
+```
+
+### argb - 将整型颜色值转换为 16 进制 RGB 字符串。
+
+```python
+def argb(color: int) -> str
+```
+
+**参数：**
+
+| 参数名  | 类型 | 是否必填 | 默认值 | 描述       |
+| ------- | ---- | -------- | ------ | ---------- |
+| `color` | int  | 是       | <br /> | 整型颜色值 |
+
+**返回值：**
+
+| 类型  | 描述               |
+| ----- | ------------------ |
+| `str` | 16 进制 RGB 字符串 |
+
+## 颜色识别
+
+### findColor - 单点找色
+
+```python
+def findColor(id: str, color: str, threshold: float, x: int, y: int, ex: int, ey: int, limit: int, orz: int) -> List[Point]
+```
+
+**参数：**
+
+| 参数名      | 类型  | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ----------- | ----- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | str   | 是       | <br /> | 图片 ID                                                                                                                                                                                                                                 |
+| `color`     | str   | 是       | <br /> | 颜色值，支持 "主色-偏色" 格式，如 "#6DD1E6-#101010"                                                                                                                                                                                     |
+| `threshold` | float | 是       | <br /> | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `x,y,ex,ey` | int   | 是       | <br /> | 搜索区域左上与右下坐标                                                                                                                                                                                                                  |
+| `limit`     | int   | 是       | <br /> | 最大查找数量                                                                                                                                                                                                                            |
+| `orz`       | int   | 是       | <br /> | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `List[Point]` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```python
+from kuaijs import image, action
+
+imageId = image.captureFullScreen()
+if imageId:
+    # 查找蓝色按钮
+    points = image.findColor(
+        imageId,
+        "#1E90FF-#101010", # 蓝色，允许一定偏差
+        0.9, # 阈值
+        0,
+        0, # 搜索区域左上角
+        400,
+        800, # 搜索区域右下角
+        5, # 最多找 5 个
+        1 # 从左到右查找
+    )
+
+    if len(points) > 0:
+        print(f"找到 {len(points)} 个蓝色点")
+        # 点击第一个找到的点
+        action.click(points[0].x, points[0].y, 100, False)
+
+    image.release(imageId)
+```
+
+### findMultiColor - 多点找色
+
+```python
+def findMultiColor(id: str, firstColor: str, threshold: float, points: str, x: int, y: int, ex: int, ey: int, limit: int, orz: int) -> List[Point]
+```
+
+**参数：**
+
+| 参数名       | 类型  | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ------------ | ----- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`         | str   | 是       | <br /> | 图片 ID                                                                                                                                                                                                                                 |
+| `firstColor` | str   | 是       | <br /> | 第一个颜色                                                                                                                                                                                                                              |
+| `threshold`  | float | 是       | <br /> | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `points`     | str   | 是       | <br /> | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色`                                                                                                                                                             |
+| `x,y,ex,ey`  | int   | 是       | <br /> | 搜索区域左上与右下坐标                                                                                                                                                                                                                  |
+| `limit`      | int   | 是       | <br /> | 最大查找数量                                                                                                                                                                                                                            |
+| `orz`        | int   | 是       | <br /> | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型          | 描述                                           |
+| ------------- | ---------------------------------------------- |
+| `List[Point]` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```python
+from kuaijs import image, action
+
+imageId = image.captureFullScreen()
+if imageId:
+    # 查找特定的颜色组合（如按钮的特征颜色）
+    points = image.findMultiColor(
+        imageId,
+        "#1E90FF-#101010", # 主颜色
+        0.9, # 阈值
+        "10|0|#FFFFFF-#101010,20|0|#000000-#101010", # 相对位置的其他颜色
+        0,
+        0,
+        400,
+        800,
+        1,
+        1
+    )
+
+    if len(points) > 0:
+        print("找到匹配的颜色组合")
+        action.click(points[0].x, points[0].y, 100, False)
+
+    image.release(imageId)
+```
+
+### cmpColor - 多点比色
+
+```python
+def cmpColor(id: str, points: str, threshold: float) -> bool
+```
+
+**参数：**
+
+| 参数名      | 类型  | 是否必填 | 默认值 | 描述                                                                        |
+| ----------- | ----- | -------- | ------ | --------------------------------------------------------------------------- |
+| `id`        | str   | 是       | <br /> | 图片 ID                                                                     |
+| `points`    | str   | 是       | <br /> | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色` |
+| `threshold` | float | 是       | <br /> | 颜色匹配阈值 (0.0-1.0)                                                      |
+
+**返回值：**
+
+| 类型   | 描述                                        |
+| ------ | ------------------------------------------- |
+| `bool` | 如果颜色匹配则返回 `True`，否则返回 `False` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    # 检查特定区域是否为预期颜色
+    isMatch = image.cmpColor(
+        imageId,
+        "1|2|#6DD1E6-#101010",
+        0.9 # 阈值
+    )
+
+    if isMatch:
+        print("颜色匹配")
+
+    image.release(imageId)
+```
+
+## 图像识别
+
+### findImage - 找图
+
+```python
+def findImage(id: str, templateImageId: str, x: int, y: int, ex: int, ey: int, threshold: float, limit: int, method: int, rgb: bool = False, options: dict = {}) -> List[Rect]
+```
+
+**参数：**
+
+| 参数名                 | 类型         | 是否必填 | 默认值                      | 描述                                                                                                                          |
+| ---------------------- | ------------ | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `imageId`              | str          | 是       | <br />                      | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                |
+| `templateImageId`      | str          | 是       | <br />                      | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
+| `x, y`                 | int          | 是       | <br />                      | 搜索区域左上角坐标                                                                                                            |
+| `ex, ey`               | int          | 是       | <br />                      | 搜索区域右下角坐标                                                                                                            |
+| `threshold`            | float        | 是       | <br />                      | 匹配阈值 (0.0-1.0) 全分辨率匹配时建议 0.5-0.6 其他建议 0.9-0.995                                                              |
+| `limit`                | int          | 是       | <br />                      | 最大查找数量，每个模板图片最多找 limit 个匹配结果                                                                             |
+| `method`               | int          | 是       | <br />                      | 匹配方法 0 SIFT 全分辨率 1 TM_SQDIFF_NORMED 3 TM_CCORR_NORMED 5 TM_CCOEFF_NORMED 99 全分辨率缩放匹配法                        |
+| `rgb`                  | bool         | 否       | `False`                     | 是否使用 RGB 找图，默认 `False` 会自动转灰度找图                                                                              |
+| `options`              | dict         | 否       | `{}`                        | 选项                                                                                                                          |
+| `options.scaleFactors` | list\[float] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 缩放匹配法缩放因子数组，默认 `[1.0, 0.9, 1.1, 0.8, 1.2]` 会在这些缩放比例下进行匹配。                                         |
+
+**返回值：**
+
+| 类型         | 描述                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `List[Rect]` | 找到的匹配结果数组，每个元素包含位置、尺寸和置信度，其中 index 代表模板图片的索引从 0 开始 |
+
+**示例：**
+
+```python
+from kuaijs import image, action
+
+matches = image.findImage(
+    "screen",
+    "template.jpg|template2.jpg",
+    0,
+    0,
+    400,
+    800, # 搜索区域
+    0.8, # 80% 匹配度
+    3, # 最多找 3 个
+    5, # 匹配方法
+    False # 不使用 rgb 找图
+)
+
+if len(matches) > 0:
+    best = matches[0]
+    print(f"找到匹配，置信度: {best.confidence}")
+
+    # 点击匹配区域的中心
+    centerX = best.centerX
+    centerY = best.centerY
+    action.click(centerX, centerY, 100, False)
+```
+
+## 图像处理
+
+### clip - 裁剪图片。
+
+```python
+def clip(id: str, x: int, y: int, ex: int, ey: int) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名      | 类型 | 是否必填 | 默认值 | 描述               |
+| ----------- | ---- | -------- | ------ | ------------------ |
+| `id`        | str  | 是       | <br /> | 原图片 ID          |
+| `x,y,ex,ey` | int  | 是       | <br /> | 裁剪区域左上与右下 |
+
+**返回值：**
+
+| 类型          | 描述              |
+| ------------- | ----------------- |
+| `str \| None` | 裁剪后的新图片 ID |
+
+**示例：**
+
+```python
+from kuaijs import image, device, file
+
+imageId = image.captureFullScreen()
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    # 裁剪屏幕上半部分
+    screen = device.getScreenRealSize()
+    clippedId = image.clip(imageId, 0, 0, screen.width, screen.height // 2)
+
+    if clippedId:
+        image.saveTo(clippedId, f"{dir_path}/top_half.jpg")
+        image.release(clippedId)
+
+    image.release(imageId)
+```
+
+### rotateImage - 旋转图片。
+
+```python
+def rotateImage(id: str, degree: int) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述                          |
+| -------- | ---- | -------- | ------ | ----------------------------- |
+| `id`     | str  | 是       | <br /> | 原图片 ID                     |
+| `degree` | int  | 是       | <br /> | 旋转角度，仅支持 90、-90、180 |
+
+**返回值：**
+
+| 类型          | 描述                               |
+| ------------- | ---------------------------------- |
+| `str \| None` | 旋转后的新图片 ID；失败返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+imageId = image.readImage("photo.jpg")
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    rotatedId = image.rotateImage(imageId, 90)
+    if rotatedId:
+        image.saveTo(rotatedId, f"{dir_path}/photo_rotated.jpg")
+        image.release(rotatedId)
+    image.release(imageId)
+```
+
+### gray - 将图片转换为灰度图。
+
+```python
+def gray(id: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述      |
+| ------ | ---- | -------- | ------ | --------- |
+| `id`   | str  | 是       | <br /> | 原图片 ID |
+
+**返回值：**
+
+| 类型          | 描述                |
+| ------------- | ------------------- |
+| `str \| None` | 灰度化后的新图片 ID |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+imageId = image.captureFullScreen()
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    grayId = image.gray(imageId)
+    if grayId:
+        image.saveTo(grayId, f"{dir_path}/screenshot_gray.jpg")
+        image.release(grayId)
+    image.release(imageId)
+```
+
+### binaryzation - 将图片进行二值化处理。
+
+```python
+def binaryzation(id: str, threshold: float) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名      | 类型  | 是否必填 | 默认值 | 描述                   |
+| ----------- | ----- | -------- | ------ | ---------------------- |
+| `id`        | str   | 是       | <br /> | 原图片 ID              |
+| `threshold` | float | 是       | <br /> | 二值化阈值 (0.0-255.0) |
+
+**返回值：**
+
+| 类型          | 描述                |
+| ------------- | ------------------- |
+| `str \| None` | 二值化后的新图片 ID |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+imageId = image.captureFullScreen()
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    binaryId = image.binaryzation(imageId, 128)
+    if binaryId:
+        image.saveTo(binaryId, f"{dir_path}/screenshot_binary.jpg")
+        image.release(binaryId)
+    image.release(imageId)
+```
+
+### drawRect - 绘制矩形。
+
+```python
+def drawRect(id: str, x: int, y: int, ex: int, ey: int, color: str, thickness: int) -> None
+```
+
+**参数：**
+
+| 参数名      | 类型 | 是否必填 | 默认值 | 描述                        |
+| ----------- | ---- | -------- | ------ | --------------------------- |
+| `id`        | str  | 是       | <br /> | 原图片 ID                   |
+| `x,y,ex,ey` | int  | 是       | <br /> | 矩形左上与右下坐标          |
+| `color`     | str  | 是       | <br /> | 颜色，如 `#FF0000` 表示红色 |
+| `thickness` | int  | 是       | <br /> | 线宽                        |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+
+imageId = image.captureFullScreen()
+if imageId:
+    image.drawRect(imageId, 100, 100, 200, 200, "#FF0000", 2)
+    image.saveTo(imageId, f"{dir_path}/test.jpg")
+    image.release(imageId)
+```
+
+### scanCode - 扫码条码（支持一维码和二维码）
+
+```python
+def scanCode(id: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述      |
+| ------ | ---- | -------- | ------ | --------- |
+| `id`   | str  | 是       | <br /> | 原图片 ID |
+
+**返回值：**
+
+| 类型          | 描述                      |
+| ------------- | ------------------------- |
+| `str \| None` | 扫码结果；失败返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    result = image.scanCode(imageId)
+    if result:
+        print(f"扫码结果: {result}")
+    else:
+        print("扫码失败")
+    image.release(imageId)
+```
+
+## Base64 转换
+
+### base64ToImage - 将 Base64 字符串转换为图片。
+
+```python
+def base64ToImage(base64: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述          |
+| -------- | ---- | -------- | ------ | ------------- |
+| `base64` | str  | 是       | <br /> | Base64 字符串 |
+
+**返回值：**
+
+| 类型          | 描述            |
+| ------------- | --------------- |
+| `str \| None` | 转换后的图片 ID |
+
+**示例：**
+
+```python
+from kuaijs import image, file
+
+base64Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="
+imageId = image.base64ToImage(base64Data)
+
+# 获取手机文档目录
+dir_path = file.getInternalDir("documents")
+if imageId:
+    image.saveTo(imageId, f"{dir_path}/base64.jpg")
+    image.release(imageId)
+```
+
+### toBase64Format - 将图片转换为 Base64 字符串。
+
+```python
+def toBase64Format(id: str, format: str, q: int) -> str
+```
+
+**参数：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述                           |
+| -------- | ---- | -------- | ------ | ------------------------------ |
+| `id`     | str  | 是       | <br /> | 原图片 ID                      |
+| `format` | str  | 是       | <br /> | 图片格式（如 "jpg", "png"）    |
+| `q`      | int  | 是       | <br /> | 质量 (1-100)，数字越大质量越高 |
+
+**返回值：**
+
+| 类型  | 描述                   |
+| ----- | ---------------------- |
+| `str` | 转换后的 Base64 字符串 |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    base64 = image.toBase64Format(imageId, "jpg", 90)
+    print(f"Base64 数据: {base64[:100]}...")
+    image.release(imageId)
+```
+
+## OpenCV方法
+
+### captureMat - 截取屏幕并返回 OpenCV Mat（numpy.ndarray）
+
+```python
+def captureMat() -> any
+```
+
+**参数：**
+
+无
+
+**返回值：**
+
+| 类型  | 描述                                                                      |
+| ----- | ------------------------------------------------------------------------- |
+| `any` | OpenCV-Python Mat 对象（本质为 `numpy.ndarray`，BGR 格式，失败为 `None`） |
+
+**示例：**
+
+```python
+from kuaijs import image
+import cv2
+
+mat = image.captureMat()
+if mat is not None:
+    print("shape:", mat.shape)
+    gray = cv2.cvtColor(mat, cv2.COLOR_BGR2GRAY)
+```
+
+### readImageMat - 读取图片并返回 OpenCV Mat（numpy.ndarray）
+
+```python
+def readImageMat(path: str) -> any
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述         |
+| ------ | ---- | -------- | ------ | ------------ |
+| `path` | str  | 是       | <br /> | 图片路径/URL |
+
+**返回值：**
+
+| 类型  | 描述                                                                      |
+| ----- | ------------------------------------------------------------------------- |
+| `any` | OpenCV-Python Mat 对象（本质为 `numpy.ndarray`，BGR 格式，失败为 `None`） |
+
+**示例：**
+
+```python
+from kuaijs import image
+import cv2
+
+mat = image.readImageMat("/tmp/a.jpg")
+if mat is not None:
+    edges = cv2.Canny(mat, 100, 200)
+    print(edges.shape)
+```
+
+### imageIdToMat - 将图片ID转换为 OpenCV Mat（numpy.ndarray）
+
+```python
+def imageIdToMat(imageId: str) -> any
+```
+
+**参数：**
+
+| 参数名    | 类型 | 是否必填 | 默认值 | 描述   |
+| --------- | ---- | -------- | ------ | ------ |
+| `imageId` | str  | 是       | <br /> | 图片ID |
+
+**返回值：**
+
+| 类型  | 描述                                                                      |
+| ----- | ------------------------------------------------------------------------- |
+| `any` | OpenCV-Python Mat 对象（本质为 `numpy.ndarray`，BGR 格式，失败为 `None`） |
+
+**示例：**
+
+```python
+from kuaijs import image
+import cv2
+
+img_id = image.captureFullScreen()
+if img_id:
+    mat = image.imageIdToMat(img_id)
+    if mat is not None:
+        blur = cv2.GaussianBlur(mat, (5, 5), 0)
+        print(blur.shape)
+    image.release(img_id)
+```
+
+## 安卓独有方法
+
+### getBitmap - 获取安卓的Bitmap对象
+
+此方法仅在安卓可用，用于获取图片的 Bitmap 对象。
+
+```python
+def getBitmap(imageId: str) -> any:
+```
+
+**参数：**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述      |
+| --------- | ------ | -------- | ------ | --------- |
+| `imageId` | string | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型  | 描述             |
+| ----- | ---------------- |
+| `any` | 安卓的Bitmap对象 |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    bitmap = image.getBitmap(imageId)
+    print(f"Bitmap 对象: {bitmap}")
+    # 注意：使用完 Bitmap 后，需要调用 recycle() 方法释放内存
+    bitmap.recycle()
+    image.release(imageId)
+
+# 快捷获取截屏bitmap
+bitmap = image.getBitmap("screen");
+print(f"Bitmap 对象: {bitmap}")
+bitmap.recycle();
+```