更新记录
1.0.6(2026-11-19)
优化插件旋转,提升插件识别率
平台兼容性
uni-app x(5.31)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | √ | √ | × | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | √ | √ |
vf-vehicle-ocr · VisionForge 行驶证离线OCR
行驶证端侧 OCR 插件。把一张行驶证照片的路径丢进来,插件在本机完成方向纠正 → 小角度倾斜矫正 → 卡面裁剪 → 正副面自动分区 → 中文识别 → 字段结构化,返回 20 个结构化字段、裁剪后的卡面图,以及每个文字行在「识别图 / 纠正图 / 原图」三套坐标系里的位置。
纯端侧推理,不联网、不上传、不申请任何权限。
| 项 | 值 |
|---|---|
| 插件 id | vf-vehicle-ocr |
| 版本 | 1.0.0 |
| 类型 | UTS API 插件 + 原生混编(Kotlin / Swift) |
| 支持平台 | Android、iOS |
| 未支持 | 鸿蒙(未实现)、Web / 小程序(调用返回 9020005) |
| HBuilderX | 4.61+(uni-app-x 5.31+) |
| 运行方式 | 必须自定义基座 / 云打包(含三方 ONNX Runtime 与 13 MB 模型资源,标准基座不含) |
| 网络与权限 | 不联网、不采集、不申请权限 |
1. 插件介绍
1.1 能力
| 能力 | 说明 |
|---|---|
| 自动方向纠正 | EXIF 归一化 + 0/90/270 候选枚举打分(横版正图直接跳过枚举),自动选正 |
| 方向二次判定 | 背景干扰导致判成倒置时,按「证件标题应在文字区顶部」的强几何特征再翻 180° |
| 小角度倾斜矫正 | 文字行基线线性回归,≤8° 自动拉正(deskew),超过就放弃矫正不动图 |
| 卡面裁剪 | 按文字框外接矩形 + 行驶证物理宽高比 1.46 反推卡面边界,裁掉桌面背景;裁剪后重新检测再识别,安全带不达标就放弃裁剪 |
| 正副面自动分区 | 「整本摊开拍一张」的照片,按正/副面独有词表打分自动切分左右或上下两页,两页各自抽字段再合并;单面照片绝不误切 |
| 逐行中文 OCR | PP-OCRv6 tiny 行级识别,每行先过 0/180 方向分类器再识别 |
| 20 个字段结构化 | 主页 11 字段 + 副页 9 字段;含 VIN 17 位校验位、号牌格式、注册/发证日期顺序交叉校验 |
| VIN 容错 | 严格匹配失败后枚举允许 I/O/Q 的 17 位窗口并归一化(O→0 / I→1 / Q→0),只接受校验位通过的候选,避免把错值当对值 |
| 三套坐标 | 每个文字框同时给出识别图 / 纠正图 / 原图坐标,画框不用自己换算 |
| 英文 key JSON | json 字段可直接落库或传后端 |
| 拒识 | 非行驶证返回 docType=other 并拒识,不返回垃圾字段;整本摊开但版式分低时可由双面分区撤销拒识 |
耗时(桌面 CPU 实测,52 张留出集,含双面分区):p50 428 ms / p95 601 ms。手机端通常 1~2 秒;首次调用额外包含模型加载与预热,之后会话复用。
1.2 目录结构
uni_modules/vf-vehicle-ocr/
├── package.json # 插件清单(id / 版本 / 平台 / 价格声明)
├── readme.md # 本文件
├── changelog.md # 更新日志
├── components/
│ └── vf-vehicle-ocr/
│ └── vf-vehicle-ocr.uvue # ★ 完整示例页:选图 → 识别 → 裁剪图显示 → 填表 → 耗时
├── tools/
│ └── check_contract.py # 发布前自检(资源哈希 / 常量契约 / 转译红线 / 字段覆盖)
└── utssdk/
├── interface.uts # 对外类型、错误码、函数签名
├── common.uts # 跨平台:JSON 解析 + 结果装配 + 业务 JSON 生成
├── fields.uts # 跨平台:字段抽取 + VIN / 号牌 / 日期校验
├── dualpage.uts # 跨平台:正副面分区与合并
├── app-android/
│ ├── index.uts # 入口(IO 线程推理,主线程回调)
│ ├── VehicleNative.kt # Kotlin 推理引擎
│ ├── config.json # onnxruntime-android / exifinterface
│ ├── AndroidManifest.xml
│ └── assets/ # 5 个模型(13 MB)
├── app-ios/
│ ├── index.uts # 入口
│ ├── VehicleNative.swift # Swift 推理引擎
│ ├── config.json # onnxruntime-objc 1.20.0
│ ├── info.plist
│ └── Resources/ # 同 5 个模型(13 MB)
└── web/
└── index.uts # 明确不支持,返回 9020005
字段抽取与双面分区放在 UTS 层(
fields.uts/dualpage.uts),Android / iOS 共用一份规则;原生层只负责几何、推理与文字行。这样两端算出来的字段永远一致。
1.3 模型资源
Android assets/ 与 iOS Resources/ 各一份,SHA256 一致:
| 文件 | 大小 | 作用 |
|---|---|---|
vf_vehicle_cls_v2.onnx |
3.0 MB | 自训版式分类 [1,3,160,160] RGB → other / vehicle_back / vehicle_front |
vf_vehicle_det_v2.onnx |
5.1 MB | 自训文字行检测 [1,3,256,256] RGB |
vf_ppocr_rec_v6.onnx |
4.3 MB | PP-OCRv6 tiny 中文识别 [1,3,48,W] BGR → 6906 类 |
vf_ppocr_angle_cls.onnx |
572 KB | 行级 0/180 方向分类 |
vf_ppocr_keys_v6.txt |
27 KB | CTC 字典 6904 行(运行期类表 = blank + 6904 + 空格 = 6906) |
类别顺序
other / vehicle_back / vehicle_front来自训练目录名字母序,与身份证插件的back / front / other不同,两套权重不可互换。识别(rec)与方向(angle)模型与vf-idcard-ocr是同一批,但资源各自打包(UTS 插件之间不共享 assets),因此同时安装两个插件会各自占用一份。
1.4 三方依赖
| 平台 | 依赖 |
|---|---|
| Android | com.microsoft.onnxruntime:onnxruntime-android:1.20.0、androidx.exifinterface:exifinterface:1.3.7 |
| iOS | onnxruntime-objc 1.20.0(CocoaPods,deploymentTarget 12.0) |
宿主若已内置同版本 ORT,可从 config.json 移除重复依赖避免冲突。
1.5 识别流程
图片路径
→ 路径归一(uni 虚拟路径 / content:// / file:// → 原生绝对路径)
→ EXIF 归一化 + 长边降采样到 ≤1600
→ 方向纠正(行方向投票定 180°,det 失败/文字侧躺才枚举 90/270)
→ 小角度倾斜矫正(≤8°,超限不动图)
→ 卡面裁剪(文字框外接矩形 + 1.46 宽高比,安全带不达标就放弃)
→ 裁剪图上重新做文字检测
→ 逐行 0/180 纠正 → 逐行 OCR
→ 正副面分区(词表打分 + 切点枚举,单面图 detected=false)
→ 逐页字段抽取(标签锚点 + 形态优先取值)→ 合并 + VIN / 号牌 / 日期交叉校验
→ 三套坐标逆映射输出
版式判为 other、或置信度低于 0.80 直接拒识(开启双面分区时,整本摊开且分区成功可撤销拒识)。不含透视矫正——拍摄明显变形时请在上层做边缘检测与透视变换。
2. 如何使用
2.1 接入步骤
-
把整个
uni_modules/vf-vehicle-ocr/拷进项目的uni_modules/目录。 -
HBuilderX 4.61+ 打开项目,制作自定义基座(或直接云打包)。标准基座不会打入 ORT 与模型资源。
-
页面里 import 插件根目录(不要 import
utssdk/下的文件):import { recognize, configure, getVersion, VfRecognizeResult } from '@/uni_modules/vf-vehicle-ocr' -
用
uni.chooseImage取图片路径,传给recognize({ imagePath })。 -
打包后若报
9020003,说明模型资源没进包:Android 用context.assets.open("vf_vehicle_cls_v2.onnx")验证,iOS 用Bundle.main.path(forResource:"vf_vehicle_cls_v2", ofType:"onnx")验证。
类型导入必须是值与类型混写的普通 import,写
import type会把运行时绑定擦掉。
2.2 发布前自检(可选)
改动插件后跑一次静态自检,覆盖资源哈希、常量契约、UTS 转译红线、字段覆盖等 8 组 97 项:
cd uni_modules/vf-vehicle-ocr
python tools/check_contract.py # 期望 PASS 97 / FAIL 0
2.3 API
| 函数 | 说明 |
|---|---|
recognize(options) |
异步识别。imagePath 必填;success / fail / complete 各触发一次 |
configure(config) |
可选,设置全局默认值;不调用即 auto / on / on / on / on |
getVersion() |
同步返回版本字符串 |
配置项全部是 string 枚举,不是 boolean(规避 UTS 结构入参 boolean 的平台差异):
| 参数 | 取值 | 默认 | 说明 |
|---|---|---|---|
backend |
'auto' / 'cpu' |
auto |
auto = 加速器优先(NNAPI / Core ML)+ 预热探测 + 自动降级 CPU |
angleCorrection |
'on' / 'off' |
on |
每行 OCR 前做 0/180 判定并翻转 |
saveImage |
'on' / 'off' |
on |
是否把纠正图 / 裁剪图落盘并回传路径 |
cropCard |
'on' / 'off' |
on |
关闭后用整图识别,便于 A/B 对比 |
dualPage |
'on' / 'off' |
on |
关闭后只按整图版式抽字段,不做正副面分区 |
// 全局配置一次,之后所有调用只传图片
configure({ backend: 'auto', angleCorrection: 'on', saveImage: 'on', cropCard: 'on', dualPage: 'on' })
// 单次覆盖
recognize({ imagePath: path, backend: 'cpu', dualPage: 'off', success: (res) => {} })
错误码
| 码 | 含义 |
|---|---|
9020001 |
路径为空 / 解析不出可读文件 |
9020002 |
图片解码失败(常见:HEIC 等不支持的编码) |
9020003 |
模型资源或推理会话失败(多为资源没进包) |
9020004 |
推理异常 |
9020005 |
平台不支持 |
9020006 |
参数非法 |
2.4 返回结果
| 字段 | 类型 | 说明 |
|---|---|---|
docType / docTypeScore / rejected / reason |
string / number / boolean / string | vehicle_front 主页、vehicle_back 副页、other 拒识 |
imageWidth / imageHeight |
number | EXIF 归一化后原图尺寸 |
correctedWidth / correctedHeight |
number | 旋转纠正后、裁剪前尺寸 |
recognitionWidth / recognitionHeight |
number | 识别图(裁剪后)尺寸 |
rotation / rotationReason / rotationAdjusted / exifOrientation |
number / string / boolean / number | 纠正角度、判定原因、是否触发二次判定、原始 EXIF |
deskewDeg |
number | 小角度倾斜矫正角度(正数=顺时针矫正),未矫正为 0 |
rotationScores |
VfRotationScore[] |
候选方向打分明细(调试旋转判定用) |
correctedImagePath / correctedImageUri |
string | 纠正图原生路径 / file:// URI |
cropped / cropReason |
boolean / string | 是否真的裁掉背景;card-crop / off / not-needed / guard-reject / rejected |
croppedImagePath / croppedImageUri |
string | 裁剪图原生路径 / file:// URI(页面显示用 Uri) |
cropBox / cropBoxOriginal |
VfRect |
裁剪框在纠正图 / 原图的坐标 |
contentBox / contentBoxCorrected / contentBoxOriginal |
VfRect |
文字区域外接矩形,三套坐标 |
lines |
VfTextLine[] |
全部文字行(按阅读顺序),含 box / boxCorrected / boxOriginal、text、textScore、angleFlipped |
fields |
VfVehicleFields |
20 个业务字段 + checks |
pages |
VfPageResult[] |
逐页明细:整本摊开时 1~2 项,单面图为空数组 |
dualPage |
VfDualPageInfo |
分区决策明细:detected / splitApplied / axis / cut / cutRatio / frontSide / separation / rescued |
json |
string | 业务结果 JSON(全英文 key、2 空格缩进),可直接落库 |
backend / costMs / costRotateMs / costOcrMs |
string / number | 实际后端与分段耗时 |
rawJson |
string | 原生层原始 JSON,扩展调试用 |
20 个字段
| 面 | 字段 |
|---|---|
主页 vehicle_front |
plateNumber(号牌号码)、vehicleType(车辆类型)、owner(所有人)、address(住址)、useCharacter(使用性质)、brandModel(品牌型号)、vin(车辆识别代号)、engineNumber(发动机号码)、registerDate(注册日期)、issueDate(发证日期)、issuingAuthority(发证机关) |
副页 vehicle_back |
fileNumber(档案编号)、approvedPassengers(核定载人数)、grossMass(总质量)、unladenMass(整备质量)、approvedLoad(核定载质量)、overallDimension(外廓尺寸)、tractionMass(准牵引总质量)、inspectionRecords(检验记录,多行用 \| 连接)、remarks(备注) |
未识别到的字段为空字符串。registerDate / issueDate 统一为 YYYY-MM-DD。
fields.checks(交叉校验,只做标记不拒识)
| 字段 | 说明 |
|---|---|
vinValid / vinChecksumOk / vinExpectedCheck / vinActualCheck |
VIN 17 位加权模 11 校验位结果 |
vinSource / vinRepaired |
VIN 来源(strict / wide-normalized / wide-cross-line / strict-unverified / 空)、是否经 I/O/Q 归一化修复 |
plateFormatOk |
号牌是否符合民用号牌字符集与长度 |
dateOrderOk / dateOrderKnown |
注册日期 ≤ 发证日期;缺日期时 dateOrderKnown=false |
ocrLineCount / ocrMeanConf |
参与抽取的行数与平均 OCR 置信度 |
reason |
校验失败的说明(成功为空串) |
画框换算:显示裁剪图时用 lines[i].box,按 显示宽度 / recognitionWidth 等比放大;要在用户原图上画框用 lines[i].boxOriginal,按 显示宽度 / imageWidth 换算。
双面合并规则:正副面都抽到同一字段时以主页为准;副页独有的字段直接来自副页。pages 里能看到每一页各自抽到了什么。
3. 接入示例代码
3.1 完整示例页(推荐先跑这个)
插件自带一份可直接运行的完整表单页:
uni_modules/vf-vehicle-ocr/components/vf-vehicle-ocr/vf-vehicle-ocr.uvue
两种跑法:
- 当独立页面:把该文件复制到
pages/vehicle-ocr/index.uvue,在pages.json注册路由即可。 - 当组件嵌入:uni-app x 的 easycom 会自动把
uni_modules/<插件>/components/<名>/<名>.uvue注册为<vf-vehicle-ocr />,直接写标签使用(该页是整页scroll-view布局,适合整页嵌入)。
它覆盖了这些内容,可作为接入模板直接删改:
| 区域 | 演示的能力 |
|---|---|
| 顶部 | 插件版本、auto / cpu 后端切换、双面分区开关、卡面裁剪开关(A/B 对比精度与速度) |
| 耗时总览 | 端到端耗时、costMs / costRotateMs / costOcrMs 分段、累计与识别张数、实际生效后端 |
| 两个图片区 | 主图(正页/整本)/ 附图(副页)各自「拍照」「相册」;选图即识别,按 docType 自动分流 |
| 图片显示 | 成功后图片区直接换成裁剪图(croppedImageUri),角标显示纠正角度,点击预览 |
| 表单 | 20 个字段自动填入且可手改(:value + @input,不用 v-model),只覆盖非空值 |
| 校验区 | VIN 校验位与来源、号牌格式、日期顺序、双面分区决策明细、裁剪框与三套坐标系 |
| 逐页明细 | 整本摊开时每一页的版式、行数、正/副面证据分与关键字段 |
| 文字行 | 逐行文本 + box / boxCorrected / boxOriginal 三套坐标(可折叠) |
| 底部 | 重新识别(两张图串行跑,避免 ORT 会话并发)、复制结果 JSON、清空 |
3.2 最小接入代码
一个页面里最少的可用代码(完整版见 3.1 的 uvue):
<template>
<view style="padding: 24rpx;">
<button @click="pick">选行驶证照片</button>
<image v-if="preview.length > 0" :src="preview" mode="widthFix" style="margin-top: 24rpx;" />
<text style="margin-top: 24rpx;">{{ summary }}</text>
</view>
</template>
<script setup lang="uts">
import { recognize, VfRecognizeResult } from '@/uni_modules/vf-vehicle-ocr'
const preview = ref<string>('')
const summary = ref<string>('')
function pick() : void {
uni.chooseImage({
count: 1,
sourceType: ['camera', 'album'],
success: (r) => {
const path = r.tempFilePaths[0]
recognize({
imagePath: path,
success: (res : VfRecognizeResult) : void => {
// 页面要显示的是「裁剪后只保留卡面」的图;没有则退回纠正图、原图
preview.value = res.croppedImageUri.length > 0 ? res.croppedImageUri
: (res.correctedImageUri.length > 0 ? res.correctedImageUri : path)
summary.value = `${res.fields.plateNumber} ${res.fields.vin} ${res.fields.owner}`
},
fail: (e) => {
summary.value = `识别失败 ${e.errCode}:${e.errMsg}`
}
})
}
})
}
</script>
3.3 常见场景片段
只判断是不是行驶证(不用字段)
recognize({
imagePath: path,
saveImage: 'off', // 不落盘,省 IO
dualPage: 'off', // 不做分区,省 OCR 后处理
success: (res : VfRecognizeResult) : void => {
if (res.rejected || res.docType == 'other') {
console.log('不是行驶证:' + res.reason)
return
}
console.log(res.docType == 'vehicle_front' ? '主页' : '副页')
}
})
只取 VIN,并对校验位把关
recognize({
imagePath: path,
success: (res : VfRecognizeResult) : void => {
const c = res.fields.checks
if (res.fields.vin.length == 17 && c.vinValid) {
console.log('VIN 可信:' + res.fields.vin + '(来源 ' + c.vinSource + ')')
} else {
// 校验位不过就别入库,让用户重拍或手填
console.log('VIN 待人工确认:' + res.fields.vin + ' 期望 ' + c.vinExpectedCheck + ' 实际 ' + c.vinActualCheck)
}
}
})
整本摊开拍一张,拿两页各自的字段
recognize({
imagePath: path,
dualPage: 'on',
success: (res : VfRecognizeResult) : void => {
if (!res.dualPage.detected) {
console.log('没用上双面分区,按整图抽:' + res.fields.plateNumber)
return
}
const pages = res.pages
let i = 0
while (i < pages.length) {
const p = pages[i]
// p.docType 是 vehicle_front / vehicle_back,p.fields 是该页自己的字段
console.log(`第 ${i + 1} 页 ${p.docType}:号牌 ${p.fields.plateNumber} 档案号 ${p.fields.fileNumber}`)
i++
}
// res.fields 是两页合并后的结果,可直接落库
}
})
直接落库:用 json 字段
recognize({
imagePath: path,
success: (res : VfRecognizeResult) : void => {
uni.request({
url: 'https://your.api/vehicle/save',
method: 'POST',
header: { 'content-type': 'application/json' },
data: JSON.parse(res.json), // 全英文 key,含 checks 与 dualPage
success: () : void => { console.log('已保存') }
} as RequestOptions)
}
})
3.4 接入时的五个要点
- 显示用
Uri字段,不要用Path字段。原生绝对路径直接给<image>会空白,必须用带file://的croppedImageUri/correctedImageUri。 - 「重新识别」要用原图路径,不要拿裁剪图再识别一次(会二次裁剪、越裁越小)。示例页把原图单独存在
rawMain/rawExtra。 - 两张图要串行识别。两个 ORT 会话并发推理容易抢内存,示例页用回调串联跑第二张。
- 页面状态用基础类型(
string/number/boolean/string[]),不要长期持有插件返回的大对象,规避 UTS 泛型与可空联合类型的平台差异。 - 字段只覆盖非空值。副页照片抽不到号牌是正常的,直接覆盖会把主页已填的值清空——示例页逐字段判空后再写。
4. 已知限制
| # | 限制 | 建议 |
|---|---|---|
| 1 | 只支持行驶证正页/副页 | 其他证照会判 other 拒识,需另训版式与字段规则 |
| 2 | 不含透视矫正、模糊/反光检测 | 拍摄时让证件占满画面、避免强反光与折角 |
| 3 | 端侧是逐行轻量 OCR | 对准确率要求极高时,可把 correctedImagePath 送服务端复核 |
| 4 | 外廓尺寸、检验记录依赖版式 | 副页多次年检盖章时会挤在一起,inspectionRecords 可能残缺。外廓尺寸是淡灰色小字,副页整图较小时(未做卡面裁剪的双面模式)可能读错数字,业务侧建议对 overallDimension 做范围校验(长 < 800mm 之类明显不合理)后再入库 |
| 5 | 同框多张证件未切分 | 只有正副页两页会被切分;三张以上同框请分次拍 |
| 6 | 模型资源 13 MB/平台 | 包体积敏感可只保留需要的变体并同步预处理 |
| 7 | 原图、纠正图含 PII | 插件不上传不加密,业务侧需自行加密存储并清理缓存文件 |
| 8 | 副页取值依赖「值在标签上方」的表格版式 | 副页字段按标签与值的相对位置取值,标签被遮挡、漏识或值写到别的格子里会留空(不会串到别的字段) |
| 9 | 方向纠正只认「文字行」证据 | 倒置(180°)靠逐行文字方向投票判定,侧躺(90°/270°)靠文字行形态与检测结果判定:整页文字被遮挡到检不出行、或只有少量文字时可能保持原方向,此时请拿正手机重拍 |
| 10 | 标签文字靠「字符锚点」容错 | 标签印刷小、OCR 常错一两个字(所有人 → 所南人、整备质量 → 整成量),这类情况仍能取值;但标签整体被漏检时该字段会留空 |
| 11 | 空值就是空值 | 核定载质量 / 准牵引总质量 在多数摩托车证件上本身印的是 ---,此时字段返回空串是正确结果;不要把它当成漏识别去兜底填值 |
| 12 | inspectionRecords 只收带日期的记录 |
栏目名 检验记录 与同格的燃料种类(汽油)会被过滤掉,多次年检才有真实记录串 |
5. 依赖与许可
PP-OCRv6 tiny 识别/方向模型与字典来自 rapidocr_onnxruntime(Apache-2.0 / PaddleOCR 相关许可);版式分类与文字行检测为本项目自训(YOLO11n)。商用分发前请核对模型许可证与分发条款,并在 App 隐私政策中说明「证件信息仅在本机处理、不上传」。
更新记录见 changelog.md。

收藏人数:
购买普通授权版(
试用
赞赏(0)
下载 5
赞赏 0
下载 12775795
赞赏 1960
赞赏
京公网安备:11010802035340号