Skip to content
qiannian edited this page Jul 1, 2026 · 11 revisions

OCR

文字识别

OCR 有两条识别路径:

  • 点阵字库识别:调用 SetDict/SetMemDict/AddDict 加载字库后,Ocr/OcrEx/FindStr 等接口会使用本地点阵字库匹配。
  • OCR HTTP 服务识别:当前字库为空时,会访问独立 OCR 服务 op_ocr_engine,适合不维护点阵字库的通用文字识别场景。

OCR 服务模式

使用场景

OCR HTTP 服务是独立进程,不嵌入 op_x86.dll/op_x64.dll 内部。OP 负责截图或读取图片,然后把原始像素通过 HTTP 发送给服务端,服务端返回文字、坐标和置信度。

适合使用 OCR 服务的场景:

  • 不想制作点阵字库,直接识别普通中文、英文或混合文本。
  • 字体、字号、抗锯齿、背景变化较多,点阵字库维护成本较高。
  • 需要识别整段文本、截图文字、UI 文案或图片文件中的文字。
  • 希望在 Tesseract 和 PaddleOCR 之间切换识别后端。

适合使用点阵字库的场景:

  • 字体固定、颜色固定,追求更可控的识别结果。
  • 需要配合 FindStr/FindStrEx 做游戏或模拟器 UI 找字。
  • 已有 OP 或大漠文本点阵字库,需要本地快速匹配。

启用条件

当前字库为空时,以下接口会走 OCR HTTP 服务:

  • Ocr
  • OcrEx
  • OcrAuto
  • OcrFromFile
  • OcrAutoFromFile
  • FindStr
  • FindStrEx

如果已经加载过点阵字库,OP 会优先使用本地点阵字库。需要切回 OCR 服务时,可以不调用 SetDict/SetMemDict/AddDict,或者清空当前字库:

idx = op.GetNowDict()
op.ClearDict(idx)

服务仓库

独立 OCR 服务仓库:

该仓库包含两类服务实现:

  • Tesseract 5 C++ HTTP 服务:默认端口 8080
  • PaddleOCR FastAPI 服务:默认端口 8081

两类服务保持相同 HTTP 协议,OP 端只需要切换服务地址即可。

服务协议

服务端提供以下接口:

方法 路径 说明
GET /health 健康检查
GET /api/v1/version 版本信息
POST /api/v1/ocr OCR 识别

POST /api/v1/ocr 的请求体为 JSON:

{
  "image": "<base64_of_raw_pixels>",
  "width": 640,
  "height": 480,
  "bpp": 4
}

字段说明:

字段 说明
image 原始像素字节的 Base64 字符串
width 图像宽度
height 图像高度
bpp 每像素字节数,支持 134

注意:服务接收的是原始像素字节,不是 PNG/JPG/BMP 文件本体。通过 OP 的 Ocr/OcrEx/OcrAutoFromFile 等接口调用时,OP 会自动完成截图、读取图片、像素转换和 HTTP 请求。

成功响应示例:

{
  "code": 0,
  "results": [
    {
      "text": "你好",
      "bbox": [10, 20, 120, 60],
      "confidence": 91.2
    }
  ]
}

OP 会读取 results 中的 textbboxconfidence,并用接口参数 sim 过滤识别结果。

默认后端

  • 默认后端:Tesseract
  • 默认地址:http://127.0.0.1:8080/api/v1/ocr
  • PaddleOCR 推荐地址:http://127.0.0.1:8081/api/v1/ocr

默认超时时间为 3000ms

启动 Tesseract 服务

先构建 op_ocr_engine

cmake -S . -B build_service
cmake --build build_service --config Release

准备 tessdata 目录,并放入语言模型,例如中文简体模型 chi_sim.traineddata

build_service/Release/ocr_server.exe --datapath tessdata --lang chi_sim --host 0.0.0.0 --port 8080

参数说明:

  • --datapath:Tesseract 模型目录。
  • --lang:语言模型名,中文简体常用 chi_sim
  • --host:监听地址,默认 0.0.0.0
  • --port:监听端口,默认 8080

启动 PaddleOCR 服务

PaddleOCR 服务位于 op_ocr_engine/py_paddle_server

pip install -r py_paddle_server/requirements.txt
python -m py_paddle_server.app --host 0.0.0.0 --port 8081 --print-results

也可以使用 uvicorn 启动:

python -m uvicorn py_paddle_server.app:app --host 0.0.0.0 --port 8081

常用环境变量:

环境变量 说明
PADDLE_LANG 识别语言,默认 ch
PADDLE_USE_GPU 是否使用 GPU
PADDLE_USE_ANGLE_CLS 是否开启方向分类
PADDLE_SHOW_LOG 是否打印 Paddle 日志
PADDLE_PRINT_RESULTS 是否打印每次请求识别结果
PADDLE_DET_MODEL_DIR 检测模型目录
PADDLE_REC_MODEL_DIR 识别模型目录
PADDLE_CLS_MODEL_DIR 方向分类模型目录

切换后端

SetOcrEngine(path_of_engine, dll_name, argv) 现在支持以下几种形式:

  • 直接传完整 URL:
    • http://127.0.0.1:8080/api/v1/ocr
    • http://127.0.0.1:8081/api/v1/ocr
  • 直接传后端别名:
    • tesseract
    • paddle
  • 通过 argv 指定:
    • --url=http://127.0.0.1:8081/api/v1/ocr --timeout=5000

如果只传服务根地址,例如 http://127.0.0.1:8081,OP 会自动补成 http://127.0.0.1:8081/api/v1/ocr

环境变量

  • OP_OCR_BACKEND=tesseract:默认走 http://127.0.0.1:8080/api/v1/ocr
  • OP_OCR_BACKEND=paddle:默认走 http://127.0.0.1:8081/api/v1/ocr
  • OP_OCR_URL=http://127.0.0.1:9000/api/v1/ocr:显式覆盖默认服务地址
  • OP_OCR_TIMEOUT_MS=5000:覆盖默认超时

Python 示例

from win32com.client import Dispatch

op = Dispatch("op.opsoft")

# 1) 使用后端别名切换到 PaddleOCR
op.SetOcrEngine("paddle", "", "--timeout=5000")

# 2) 或直接指定完整 URL
# op.SetOcrEngine("http://127.0.0.1:8081/api/v1/ocr", "", "--timeout=5000")

# 不加载点阵字库,或清空当前字库,才会使用 OCR HTTP 服务
op.ClearDict(op.GetNowDict())

text = op.OcrAutoFromFile("screen.bmp", 0.8)
print(text)

YOLO HTTP 检测

YOLO 检测也走独立 HTTP 服务。OP 负责截图、读取图片和发送原始像素,模型加载和推理由外部服务完成。

默认地址为 http://127.0.0.1:8090/api/v1/detectSetYoloEngine 可以传完整 URL,也可以传基础地址,例如 http://127.0.0.1:8090,OP 会自动补全 /api/v1/detect

支持的后端别名:

  • yolo
  • yolo11
  • yolov11
  • yolo_http
  • yolo_server

环境变量:

  • OP_YOLO_URL:显式指定 YOLO 服务地址
  • OP_YOLO_BACKEND:指定后端别名
  • OP_YOLO_TIMEOUT_MS:指定请求超时,单位毫秒

请求体使用原始像素的 Base64,不是图片文件本体:

{
  "image": "<base64_of_raw_pixels>",
  "width": 800,
  "height": 600,
  "bpp": 4,
  "conf": 0.25,
  "iou": 0.45
}

服务返回示例:

{
  "code": 0,
  "results": [
    {
      "class_id": 0,
      "label": "button",
      "bbox": [10, 20, 100, 120],
      "confidence": 0.95
    }
  ]
}

类名字段兼容 labelclass_namename,类别 ID 字段兼容 class_idcls,置信度字段兼容 confidenceconf

YoloDetect 返回的坐标会转换为屏幕或绑定窗口区域坐标;YoloDetectFromFile 返回图片文件内坐标。

接口目录

字库格式说明

OP 的点阵 OCR 支持两类字库输入:

  • OP 二进制字库:通常由 SaveDict 保存,SetDict 会优先按 OP 二进制 .dict 读取。
  • 大漠文本点阵字库:格式为 点阵HEX$文本$左.右.数量$高度,例如 FFFFFFFFFF$字$0.0.10$11

导入大漠文本字库时,OP 会在加载边界把大漠点阵转换成内部点阵格式;内部识别仍使用 OP 自己的匹配结构。需要注意的是,当前兼容解析按大漠默认点阵高度 11 切分点阵,最后一段“高度”会校验但不参与内部宽高计算。

支持大漠文本格式的入口:

  • SetDict(idx, file):文件入口,优先读取 OP 二进制字库,失败后按大漠文本字库逐行导入。
  • SetMemDict(idx, data, size):内存文本字库入口,支持大漠文本格式,也支持 OP 文本单条格式。
  • AddDict(idx, dict_info):单条字形入口,支持大漠文本格式,也支持 FetchWord/GetDict 返回的 OP 文本单条格式。

当当前字库为空时,Ocr/OcrEx/OcrAuto/OcrFromFile/OcrAutoFromFile 会走 OCR HTTP 服务;当当前字库有内容时,会优先使用本地点阵字库识别。

接口方法

SetOcrEngine

设置 OCR HTTP 引擎

long SetOcrEngine(path_of_engine,dll_name,argv)
参数 类型 描述
path_of_engine string OCR 后端别名或 URL,可传 tesseractpaddle
dll_name string 兼容参数,也可以传 OCR URL
argv string 参数字符串,例如"--url=http://127.0.0.1:8081/api/v1/ocr --timeout=5000"

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.SetOcrEngine("paddle","","--timeout=5000")

SetYoloEngine

设置 YOLO HTTP 引擎

long SetYoloEngine(path_of_engine,dll_name,argv)
参数 类型 描述
path_of_engine string YOLO 后端别名或 URL,可传 yoloyolo11
dll_name string 兼容参数,也可以传 YOLO URL
argv string 参数字符串,支持 --url=--timeout=

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.SetYoloEngine("http://127.0.0.1:8090","","--timeout=5000")

YoloDetect

检测屏幕区域中的目标

long YoloDetect(x1,y1,x2,y2,conf,iou,retjson)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
conf double 置信度阈值
iou double NMS 的 IOU 阈值
retjson string* 返回检测结果 JSON 字符串

返回值

类型:int

返回检测到的目标数量。请求失败、未绑定截图或检测失败时返回 0,retjson 为空。

示例

var retjson string
count = op.YoloDetect(0,0,800,600,0.25,0.45,&retjson)

YoloDetectFromFile

检测图片文件中的目标

long YoloDetectFromFile(file_name,conf,iou,retjson)
参数 类型 描述
file_name string 图片文件名
conf double 置信度阈值
iou double NMS 的 IOU 阈值
retjson string* 返回检测结果 JSON 字符串

返回值

类型:int

返回检测到的目标数量。文件不存在、请求失败或检测失败时返回 0,retjson 为空。

示例

var retjson string
count = op.YoloDetectFromFile("screen.bmp",0.25,0.45,&retjson)

SetDict

设置字库文件(index:范围:0-9)不能超过 10 个字库。支持 OP 二进制字库和大漠文本点阵字库。

long SetDict(index,file)
参数 类型 描述
index int 字库的序号,取值为 0-9
file string 字库文件名,支持 OP .dict 或大漠文本字库

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op_ret = op.SetDict(0,"test.txt")

注: 此函数速度很慢,全局初始化时调用一次即可,切换字库用 UseDict。文件导入时会优先尝试 OP 二进制字库,失败后按大漠文本点阵字库逐行解析。

SetMemDict

设置内存字库文件,支持大漠文本点阵字库内容。

long SetMemDict(idx,data,size)
参数 类型 描述
index int 字库的序号
data bytes 字库内容数据,可为大漠文本字库内容
size int 字库大小

返回值

类型:int

  • 0:失败
  • 1:成功

示例

// 该代码为golang示例
str := []byte("FFFFFFFFFF$这是不正确的字库数据,用于测试$0.0.3312$36")
op.SetMemDict(1, str, len(str))

UseDict

选择使用哪个字库文件进行识别(index:范围:0-9)

long UseDict(index)
参数 类型 描述
index int 字库的序号

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op_ret = op.UseDict(1)
ss = op.Ocr(0,0,2000,2000,"FFFFFF-000000",1.0)
op_ret = op.UseDict(0)
long UseDict(index)

GetDict

获取指定字库中的条目内容

string GetDict(idx,font_index)
参数 类型 描述
idx int 字库序号
font_index int 条目序号

返回值

类型:string

返回字库条目字符串,失败返回空字符串

示例

dict_info = op.GetDict(0,0)

AddDict

向指定字库添加一条字库信息。dict_info 可以是 FetchWord/GetDict 返回的 OP 文本单条格式,也可以是大漠文本点阵单条格式。

long AddDict(idx,dict_info)
参数 类型 描述
idx int 字库序号
dict_info string 字库条目,可来自 FetchWord/GetDict,也可使用大漠文本格式

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.AddDict(0,"A$4,3,8$5E0E")

SaveDict

保存指定字库到文件

long SaveDict(idx,file_name)
参数 类型 描述
idx int 字库序号
file_name string 文件名

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.SaveDict(0,"test.dict")

ClearDict

清空指定字库

long ClearDict(idx)
参数 类型 描述
idx int 字库序号

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.ClearDict(0)

GetDictCount

获取指定字库中的字符数量

long GetDictCount(idx)
参数 类型 描述
idx int 字库序号

返回值

类型:int

返回字库条目数量

示例

count = op.GetDictCount(0)

GetNowDict

获取当前使用的字库序号

long GetNowDict()

返回值

类型:int

返回当前字库序号

示例

idx = op.GetNowDict()

FetchWord

根据指定范围和颜色描述,提取字库条目信息

string FetchWord(x1,y1,x2,y2,color,word)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
color string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
word string 字符名称

返回值

类型:string

返回可传给 AddDict 的字库条目,区域为空或失败时返回空字符串

示例

dict_info = op.FetchWord(0,0,20,20,"000000-000000","A")
op.AddDict(0,dict_info)

GetWordsNoDict

不依赖字库,识别指定范围内所有满足颜色条件的词块位置和点阵信息

string GetWordsNoDict(x1,y1,x2,y2,color)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
color string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割

返回值

类型:string

返回格式为 x,y-word/x,y-word/

示例

result = op.GetWordsNoDict(0,0,200,200,"ffffff-000000")

GetWordResultCount

获取 GetWordsNoDict 结果中的词块数量

long GetWordResultCount(result)
参数 类型 描述
result string GetWordsNoDict 返回的字符串

返回值

类型:int

返回词块数量

示例

count = op.GetWordResultCount(result)

GetWordResultPos

获取 GetWordsNoDict 结果中指定词块的坐标

long GetWordResultPos(result,index,x,y)
参数 类型 描述
result string GetWordsNoDict 返回值
index int 词块序号,从 0 开始
x int* 变参指针: 返回 X 坐标
y int* 变参指针: 返回 Y 坐标

返回值

类型:int

  • 0:失败
  • 1:成功

示例

op.GetWordResultPos(result,0,&x,&y)

GetWordResultStr

获取 GetWordsNoDict 结果中指定词块的内容

string GetWordResultStr(result,index)
参数 类型 描述
result string GetWordsNoDict 返回值
index int 词块序号,从 0 开始

返回值

类型:string

返回词块内容,失败返回空字符串

示例

word = op.GetWordResultStr(result,0)

Ocr

识别屏幕范围(x1,y1,x2,y2)内符合 color_format 的字符串

若当前对象未设置字库,则使用 ocr 引擎进行文字识别

string Ocr(x1,y1,x2,y2,color_format,sim)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
color_format string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的字符串

示例

//RGB单色识别
s = op.Ocr(0,0,2000,2000,"9f2e3f-000000",1.0)
println(s)

//RGB单色差色识别
s = op.Ocr(0,0,2000,2000,"9f2e3f-030303",1.0)
println(s)

//RGB多色识别(最多支持10种,每种颜色用"|"分割)
s = op.Ocr(0,0,2000,2000,"9f2e3f-030303|2d3f2f-000000|3f9e4d-100000",1.0)
println(s)

OcrEx

该方法可以返回识别到的字符串,以及每个字符的坐标

若当前对象未设置字库,则使用 ocr 引擎进行文字识别

string OcrEx(x1,y1,x2,y2,color_format,sim)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
color_format string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的字符串以及坐标

示例

和 Ocr 函数相同,只是结果处理有所不同 如下

op_ret = op.OcrEx(0,0,2000,2000,"ffffff|000000",1.0)
ss = split(op_ret,"|")
index = 0
count = UBound(ss) + 1
Do While index < count
   TracePrint ss(index)
   sss = split(ss(index),"$")
   ocr_s = int(sss(0))
   x = int(sss(1))
   y = int(sss(2))
   TracePrint ocr_s & ","&x&","&y
   index = index+1
Loop

OcrAuto

识别屏幕范围(x1,y1,x2,y2)内的字符串,自动二值化,而无需指定颜色

适用于字体颜色和背景相差较大的场合

string OcrAuto(x1,y1,x2,y2,sim)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的字符串

示例

s = op.OcrAuto(0,0,100,200,1.0)
println(s)

OcrFromFile

从文件中识别图片

string OcrFromFile(file_name,color_format,sim)
参数 类型 描述
file_name string 文件名
color_format string 颜色格式串
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的字符串

示例

//RGB单色识别
s = op.OcrFromFile("test.png","9f2e3f-000000",1.0)
println(s)

OcrAutoFromFile

从文件中识别图片,自动二值化,无需指定颜色

string OcrAutoFromFile(file_name,sim)
参数 类型 描述
file_name string 文件名
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的字符串

示例

//RGB单色识别
s = op.OcrAutoFromFile("test.png",1.0)
println(s)

FindStr

在屏幕范围(x1,y1,x2,y2)内,查找 string(可以是任意个字符串的组合),并返回符合 color_format 的坐标位置

long FindStr(x1,y1,x2,y2,string,color_format,sim,intX,intY)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
string string 待查找的字符串,可以是字符串组合,比如"长安|洛阳|大雁塔",中间用"|"来分割
color_format string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
sim double 相似度,取值范围 0.1-1.0
intX int* 变参指针: 返回 X 坐标没找到返回-1
intY int* 变参指针: 返回 Y 坐标没找到返回-1

返回值

类型:int

返回字符串的索引 没找到返回-1, 比如"长安|洛阳",若找到长安,则返回 0

示例

此函数的原理是先 Ocr 识别,然后再查找,若当前对象未设置字库,则使用 ocr 引擎进行文字识别

op_ret = op.FindStr(0,0,2000,2000,"长安","9f2e3f-000000",1.0,intX,intY)
If intX >= 0 and intY >= 0 Then
     op.MoveTo intX,intY
End If



op_ret = op.FindStr(0,0,2000,2000,"yes|no","rrggbb-000000",1.0,intX,intY)
If intX >= 0 and intY >= 0 Then
     op.MoveTo intX,intY
End If

FindStrEx

在屏幕范围(x1,y1,x2,y2)内,查找 string(可以是任意字符串的组合)

该接口和 FindStr 类似,可以返回符合 color_format 的所有坐标位置

string FindStrEx(x1,y1,x2,y2,string,color_format,sim)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
string string 待查找的字符串,可以是字符串组合,比如"长安|洛阳|大雁塔",中间用"|"来分割
color_format string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回所有找到的坐标集合,格式如下: "id,x0,y0|id,x1,y1|......|id,xn,yn" 比如"0,100,20|2,30,40" 表示找到了两个,第一个,对应的是序号为 0 的字符串,坐标是(100,20),第二个是序号为 2 的字符串,坐标(30,40)

示例

此函数的原理是先 Ocr 识别,然后再查找,若当前对象未设置字库,则使用 ocr 引擎进行文字识别

op_ret = op.FindStrEx(0,0,2000,2000,"伤害|攻击|血量","eeddff-000000",1.0)
If len(op_ret) > 0 Then
   ss = split(op_ret,"|")
   index = 0
   count = UBound(ss) + 1
   Do While index < count
      TracePrint ss(index)
      sss = split(ss(index),",")
      id = int(sss(0))
      x = int(sss(1))
      y = int(sss(2))
      op.MoveTo x,y
      Delay 1000
      index = index+1
   Loop
End If

FindLine

在指定的屏幕坐标范围内,查找指定颜色的直线

string FindLine(x1,y1,x2,y2,color_format,sim)
参数 类型 描述
x1 int 区域的左上 X 坐标
y1 int 区域的左上 Y 坐标
x2 int 区域的右下 X 坐标
y2 int 区域的右下 Y 坐标
color_format string 颜色格式串,比如"FFFFFF-000000|CCCCCC-000000"每种颜色用"|"分割
sim double 相似度,取值范围 0.1-1.0

返回值

类型:string

返回识别到的结果

示例

Clone this wiki locally