# local-OCR

**Repository Path**: lefan_suitable/local-ocr

## Basic Information

- **Project Name**: local-OCR
- **Description**: 基于 PaddleOCR 的纯离线 OCR 识别插件，无需联网，隐私安全
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lf-OCR 离线识别插件

> 基于 **PaddleOCR** 的纯离线 OCR 识别插件，无需联网，隐私安全

## ✨ 特性

- 🚀 **高性能** - 基于 PaddleOCR，识别速度快、准确率高
- 🔒 **纯离线** - 所有资源本地化，无需网络即可使用
- 🎯 **中文优化** - 专为中文场景优化，识别效果出色
- 📱 **多平台** - 支持 H5、App (Android/iOS)
- 🪪 **证件识别** - 内置身份证、银行卡、驾驶证模板
- ✅ **智能验证** - 自动验证证件有效性，返回详细验证信息
- 🔄 **自动识别** - 智能判断证件正反面，无需手动指定
- 🔧 **易于扩展** - 支持自定义模型和识别模板

---

## 📦 安装

### uni_modules 方式（推荐）

1. 在 HBuilder 插件市场搜索 `lf-OCR`
2. 点击导入到项目

### 手动安装

将 `uni_modules/lf-OCR` 复制到项目的 `uni_modules` 目录

---

## 📱 平台兼容性

| 平台          | 支持 | 说明               |
| ------------- | ---- | ------------------ |
| H5            | ✅   | 完全支持           |
| App (Android) | ✅   | 通过 web-view      |
| App (iOS)     | ✅   | 通过 web-view      |
| 微信小程序    | ❌   | 不支持 WebAssembly |
| 其他小程序    | ❌   | 不支持 WebAssembly |

---

## 🎮 使用方式

### 方式一：使用 SDK（推荐）

```javascript
import lfOCR from "@/uni_modules/lf-OCR/index.js";

// 初始化
await lfOCR.init({
  onProgress: (msg) => console.log("加载进度:", msg),
});

// 识别图片
const result = await lfOCR.recognize(imagePath, "idCard");
console.log("识别结果:", result);
```

### 方式二：使用组件

```vue
<template>
  <view class="page">
    <lf-ocr @result="onResult" @error="onError" />
  </view>
</template>

<script>
export default {
  methods: {
    onResult(data) {
      console.log("识别结果:", data.text);
      console.log("解析数据:", data.parsedData);
      console.log("是否有效:", data.parsedData.valid);
    },
    onError(err) {
      console.error("识别失败:", err);
    },
  },
};
</script>
```

### 方式三：使用 web-view

```vue
<template>
  <web-view
    src="/uni_modules/lf-OCR/hybrid/html/ocr.html"
    @message="onMessage"
  />
</template>

<script>
export default {
  methods: {
    onMessage(event) {
      const data = event.detail.data[0];
      if (data.type === "OCR_RESULT") {
        console.log("识别结果:", data.data);
      }
    },
  },
};
</script>
```

---

## 🔧 API 文档

### SDK 方法

```javascript
import lfOCR from "@/uni_modules/lf-OCR/index.js";

// 初始化引擎
await lfOCR.init(options);

// 识别图片
// template: "general" | "idCard" | "bankCard" | "driverLicense"
const result = await lfOCR.recognize(imagePath, template);

// 检查引擎状态
const isReady = lfOCR.isReady();

// 销毁引擎
lfOCR.destroy();
```

### 模板解析器

```javascript
import {
  // 身份证
  parseIdCard,
  parseIdCardFront,
  parseIdCardBack,
  detectIdCardSide,
  // 银行卡
  parseBankCard,
  // 驾驶证
  parseDriverLicense,
  // 通用
  parseGeneral,
} from "@/uni_modules/lf-OCR/index.js";
```

### 校验工具

```javascript
import {
  validateIdCard,
  validateBankCard,
  validateDriverLicenseNumber,
  validatePhone,
  validateEmail,
  validateLicenseClass,
} from "@/uni_modules/lf-OCR/index.js";
```

### 格式化工具

```javascript
import {
  formatDate,
  formatAmount,
  formatPhone,
  formatBankCard,
  formatDuration,
} from "@/uni_modules/lf-OCR/index.js";
```

---

## 📋 返回数据格式

### 身份证正面

```javascript
{
  name: "张三",
  gender: "男",
  ethnicity: "汉族",
  birthDate: "1990年01月01日",
  address: "北京市朝阳区某某街道123号",
  idNumber: "110101199001011234",
  valid: true,
  side: "front",
  validationDetails: { ... }
}
```

### 身份证背面

```javascript
{
  authority: "北京市公安局朝阳分局",
  validPeriod: {
    start: "2015.01.01",
    end: "2025.01.01"  // 或 "长期"
  },
  valid: true,
  isExpired: false,
  side: "back"
}
```

### 银行卡

```javascript
{
  cardNumber: "6222021234567890123",
  cardNumberFormatted: "6222 0212 3456 7890 123",
  bankName: "中国工商银行",
  cardType: "借记卡",
  expiryDate: "12/25",
  valid: true,
  isExpired: false
}
```

### 驾驶证

```javascript
{
  licenseNumber: "123456789012345678",
  name: "张三",
  gender: "男",
  nationality: "中国",
  address: "北京市朝阳区某某街道123号",
  birthDate: "1990-01-01",
  firstIssueDate: "2010-01-01",
  licenseClass: "C1",
  licenseClassDesc: "小型汽车",
  validPeriod: {
    start: "2020.01.01",
    end: "2026.01.01"
  },
  valid: true,
  page: "main"  // 或 "sub"
}
```

---

## 💡 使用示例

### 身份证识别

```javascript
import { parseIdCard, validateIdCard } from "@/uni_modules/lf-OCR/index.js";

// 自动判断正反面
const result = parseIdCard(ocrText);

if (result.side === "front") {
  console.log("姓名:", result.name);
  console.log("身份证号:", result.idNumber);

  // 验证身份证号
  const validation = validateIdCard(result.idNumber);
  if (validation.valid) {
    console.log("年龄:", validation.info.age);
    console.log("性别:", validation.info.gender);
  }
} else {
  console.log("签发机关:", result.authority);
  console.log("有效期:", result.validPeriod);
}
```

### 银行卡识别

```javascript
import { parseBankCard } from "@/uni_modules/lf-OCR/index.js";

const result = parseBankCard(ocrText);

if (result.valid) {
  console.log("卡号:", result.cardNumberFormatted);
  console.log("银行:", result.bankName);
  console.log("卡类型:", result.cardType);

  if (result.isExpired) {
    console.log("银行卡已过期");
  }
}
```

### 驾驶证识别

```javascript
import { parseDriverLicense } from "@/uni_modules/lf-OCR/index.js";

const result = parseDriverLicense(ocrText);

if (result.valid) {
  console.log("姓名:", result.name);
  console.log("准驾车型:", result.licenseClass, result.licenseClassDesc);
  console.log("有效期:", result.validPeriod);
}
```

---

## 🔧 扩展开发

### 更换 OCR 模型

插件使用 PaddleOCR 的 ONNX 模型，可以更换为其他兼容模型：

```
hybrid/html/models/
├── ppocr_det.onnx      # 文字检测模型
├── ppocr_rec.onnx      # 文字识别模型
└── ppocr_keys_v1.txt   # 字典文件
```

**更换步骤：**

1. 准备 ONNX 格式的检测模型和识别模型
2. 替换 `hybrid/html/models/` 目录下的对应文件
3. 如使用不同字典，同时替换 `ppocr_keys_v1.txt`

### 新增识别模板

在 `js_sdk/templates/` 目录下创建新模板：

```javascript
// js_sdk/templates/passport.js
export function parsePassport(text, lines = []) {
  const result = {
    name: "",
    passportNumber: "",
    nationality: "",
    birthDate: "",
    expiryDate: "",
    valid: false,
  };

  // 实现字段提取逻辑
  // ...

  return result;
}
```

**然后在入口文件中导出：**

```javascript
// index.js
export { parsePassport } from "./js_sdk/templates/passport.js";
```

### 添加新的校验规则

在 `js_sdk/utils/validators.js` 中添加：

```javascript
export function validatePassportNumber(passportNumber) {
  const result = {
    valid: false,
    message: "",
  };

  // 实现校验逻辑
  if (/^[A-Z]\d{8}$/.test(passportNumber)) {
    result.valid = true;
    result.message = "护照号码格式正确";
  } else {
    result.message = "护照号码格式不正确";
  }

  return result;
}
```

---

## ⚠️ 注意事项

1. **纯离线运行** - 所有模型和依赖已本地化，无需网络即可使用
2. **图片质量** - 清晰的图片识别效果更好，建议分辨率 ≥ 720p
3. **证件验证** - 插件会验证证件格式和有效性，但重要场景请结合后端验证
4. **隐私保护** - 所有识别在本地完成，不会上传任何数据到服务器
5. **资源大小** - 插件包含 OCR 模型文件，整体约 35MB

---

## 🔍 常见问题

### 识别准确率如何提高？

- 确保证件图片清晰、光线充足
- 避免反光、阴影
- 证件尽量占满取景框
- 保持证件水平，避免倾斜

### 如何判断证件是否有效？

```javascript
const result = parseIdCard(ocrText);
if (result.valid) {
  console.log("有效证件");
} else {
  console.log("验证详情:", result.validationDetails);
}
```

### 支持的证件类型

- ✅ 身份证（正反面）
- ✅ 银行卡
- ✅ 驾驶证（主页、副页）
- ✅ 通用文字识别

### 如何添加新证件类型？

参考「扩展开发」章节，在 `js_sdk/templates/` 目录下创建新模板文件。

---

## 📄 开源协议

MIT License

---