vision - PythonIDE Docs

图片 OCR（文字识别）：从图片字节提取可见文字。新代码请 import vision（与 vision_fix 等价）。

边界：专注文字识别（OCR）。人脸、条码、矩形检测请用 vision_helper。需要能导入 Vision 框架或 objc_util；纯 ctypes 回退不支持 OCR。

#模块概览

项	说明
导入	`import vision`
适合做什么	名片识别、截图取字、票据文字提取
调用时机	OCR 放在按钮回调；传入图片 `bytes`
推荐顺序	读图/选图 → `recognize_text_from_image_data(data)`
依赖	`is_vision_available()` 为 `True` 时再调用

#快速开始

从本地图片文件读取并识别文字：

python

import vision

if not vision.is_vision_available():
    print("Vision 框架不可用")
else:
    with open("/path/to/photo.jpg", "rb") as f:
        data = f.read()
    text = vision.recognize_text_from_image_data(data)
    print(text or "未识别到文字")

检查框架并获取底层类（高级用法）：

python

import vision

engine = vision.setup_vision_framework()
if engine:
    print("导入方式:", engine.get("method"))

#AppUI 示例

选图后 OCR，结果展示在界面上。

python

import appui
import photos
import vision

state = appui.State(
    available="—",
    status="尚未识别",
    text="",
)


def refresh_available():
    state.available = "是" if vision.is_vision_available() else "否"


def ocr_from_photos():
    refresh_available()
    if state.available != "是":
        state.status = "Vision 不可用"
        return

    data = photos.pick_image(raw_data=True)
    if not data:
        state.status = "未选择图片"
        return

    result = vision.recognize_text_from_image_data(data)
    if not result:
        state.batch_update(status="未识别到文字", text="")
        return

    preview = result[:200] + ("…" if len(result) > 200 else "")
    state.batch_update(status=f"共 {len(result)} 字符", text=preview)


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("OCR", [
                appui.Button("选图并识别", action=ocr_from_photos)
                .button_style("bordered_prominent"),
            ]),
            appui.Section("结果", [
                appui.LabeledContent("Vision", value=state.available),
                appui.LabeledContent("状态", value=state.status),
                appui.Text(state.text or "—").foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("文字识别")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`is_vision_available()`	Vision 是否可用 → `bool`
`setup_vision_framework()`	返回底层类字典或 `None`
`recognize_text_from_image_data(image_data)`	OCR → `str` 或 `None`

#可用性

is_vision_available() — 检测能否通过直接导入或 objc_util 使用 Vision。

setup_vision_framework() — 返回包含 VNRecognizeTextRequest、VNImageRequestHandler 等类的字典；method 字段为 direct_import 或 objc_util。

#OCR

recognize_text_from_image_data(image_data) — 传入图片原始 bytes，返回多行合并的识别文本；失败返回 None。

python

with open(path, "rb") as f:
    text = vision.recognize_text_from_image_data(f.read())

识别级别为 accurate（setRecognitionLevel_(1)），适合文档与截图。

#常见错误

错误写法	后果	修正
传文件路径而非 `bytes`	类型错误	先 `open(path, "rb").read()`
未检查 `is_vision_available()`	返回 `None` 难排查	先判断可用性
在 `body()` 里自动 OCR	每次刷新重复识别	放进按钮回调
需要扫二维码	能力不匹配	用 `vision_helper.detect_barcodes`

#相关文档

文档	用途
vision_helper	人脸、条码、分类、矩形检测
photos	选图与 Base64
objc_util	底层 Vision 类访问

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。