更新记录

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 接入步骤

  1. 把整个 uni_modules/vf-vehicle-ocr/ 拷进项目的 uni_modules/ 目录。

  2. HBuilderX 4.61+ 打开项目,制作自定义基座(或直接云打包)。标准基座不会打入 ORT 与模型资源。

  3. 页面里 import 插件根目录(不要 import utssdk/ 下的文件):

    import { recognize, configure, getVersion, VfRecognizeResult } from '@/uni_modules/vf-vehicle-ocr'
  4. 用 uni.chooseImage 取图片路径,传给 recognize({ imagePath })。

  5. 打包后若报 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 接入时的五个要点

  1. 显示用 Uri 字段,不要用 Path 字段。原生绝对路径直接给 <image> 会空白,必须用带 file:// 的 croppedImageUri / correctedImageUri。
  2. 「重新识别」要用原图路径,不要拿裁剪图再识别一次(会二次裁剪、越裁越小)。示例页把原图单独存在 rawMain / rawExtra。
  3. 两张图要串行识别。两个 ORT 会话并发推理容易抢内存,示例页用回调串联跑第二张。
  4. 页面状态用基础类型(string / number / boolean / string[]),不要长期持有插件返回的大对象,规避 UTS 泛型与可空联合类型的平台差异。
  5. 字段只覆盖非空值。副页照片抽不到号牌是正常的,直接覆盖会把主页已填的值清空——示例页逐字段判空后再写。

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。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

当前版本不申请任何权限(仅做本地图片读写,沙盒路径与系统选择器已授权的 URI 均无需额外权限)。拍照/相册由宿主页面调用 uni.chooseImage 触发,相机权限由宿主 App 自行声明:Android(android.permission.CAMERA)、iOS(NSCameraUsageDescription);相册走系统选择器一般无需权限。Android 4.41+ 相册选原图时系统返回的 content:// URI 仅做只读访问并复制到应用私有缓存,识别后立即删除。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

当前版本(1.0.0)不采集任何数据、不发起任何网络请求:只在端侧读取调用方传入的本地图片,并把纠正图/裁剪图写到应用自己的沙盒缓存目录。识别出的行驶证字段仅在设备内存中处理,不上传、不落库、不回传给插件方。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。