- 源码 316 文件收编为 rusto-rs/ 文件夹,随本仓库管理 - 移除内部 .git(补丁已存档 docs/rusto-rs-metal-patch-20260912.patch,上游可随时 re-clone) - target/ 与 docs/.yarn 缓存不入库;本地改动:ROCR_* 环境变量调优 + Metal 链接修复 + 预处理测试脚本
243 lines
5.2 KiB
Markdown
243 lines
5.2 KiB
Markdown
# Bundling Model Files with React Native RustO
|
|
|
|
This guide explains how to bundle OCR model files with your React Native application for both Android and iOS platforms.
|
|
|
|
## Overview
|
|
|
|
The React Native RustO package supports bundling model files directly into your application, eliminating the need to download models at runtime or manually specify file paths.
|
|
|
|
## Default Model Files
|
|
|
|
The package expects these default model files:
|
|
|
|
- `det.mnn` - Detection model
|
|
- `rec.mnn` - Recognition model
|
|
- `dict.txt` - Character dictionary
|
|
|
|
These files should be placed in the appropriate directories for each platform.
|
|
|
|
---
|
|
|
|
## Android Setup
|
|
|
|
### Option 1: Bundle with Main Android Package
|
|
|
|
Place model files in `packages/android/src/main/assets/`:
|
|
|
|
```
|
|
packages/android/src/main/assets/
|
|
├── det.mnn
|
|
├── rec.mnn
|
|
└── dict.txt
|
|
```
|
|
|
|
The React Native package will automatically include these assets through the dependency link.
|
|
|
|
### Option 2: Bundle with React Native Package
|
|
|
|
Place model files in `packages/react-native/android/src/main/assets/`:
|
|
|
|
```
|
|
packages/react-native/android/src/main/assets/
|
|
├── det.mnn
|
|
├── rec.mnn
|
|
└── dict.txt
|
|
```
|
|
|
|
### How It Works
|
|
|
|
The Android `build.gradle` is configured to include assets from both locations:
|
|
|
|
```gradle
|
|
sourceSets {
|
|
main {
|
|
assets.srcDirs = [
|
|
'src/main/assets',
|
|
'../../../android/src/main/assets'
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
When the app runs, the `RustO.initialize()` method automatically extracts these assets from the APK to the app's cache directory.
|
|
|
|
---
|
|
|
|
## iOS Setup
|
|
|
|
### 1. Create Models Directory
|
|
|
|
Create a `models` directory inside `packages/react-native/ios/`:
|
|
|
|
```bash
|
|
mkdir -p packages/react-native/ios/models
|
|
```
|
|
|
|
### 2. Copy Model Files
|
|
|
|
Place your model files in this directory:
|
|
|
|
```
|
|
packages/react-native/ios/models/
|
|
├── det.mnn
|
|
├── rec.mnn
|
|
└── dict.txt
|
|
```
|
|
|
|
### 3. Bundle Configuration
|
|
|
|
The `.podspec` file is already configured to bundle these models as resources:
|
|
|
|
```ruby
|
|
s.resource_bundles = {
|
|
'RustoModels' => [
|
|
'ios/models/*.mnn',
|
|
'ios/models/*.txt'
|
|
]
|
|
}
|
|
```
|
|
|
|
### How It Works
|
|
|
|
When the app runs, the Swift module checks the `RustoModels.bundle` resource bundle first, then falls back to the main bundle and documents directory.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### With Bundled Models (Recommended)
|
|
|
|
Simply call `initialize()` without parameters to use the bundled default models:
|
|
|
|
```typescript
|
|
import { initialize, detectText } from 'react-native-rusto';
|
|
|
|
// Initialize with bundled models
|
|
await initialize();
|
|
|
|
// Perform OCR. `{ uri }` accepts an absolute filesystem path or file: URI.
|
|
const results = await detectText({ uri: '/path/to/image.jpg' });
|
|
```
|
|
|
|
### With Custom Model Paths
|
|
|
|
You can specify custom model paths in config:
|
|
|
|
```typescript
|
|
// Initialize with custom models.
|
|
await initialize({
|
|
models: {
|
|
detection: '/custom/path/det_model.mnn',
|
|
recognition: '/custom/path/rec_model.mnn',
|
|
dictionary: '/custom/path/dictionary.txt',
|
|
},
|
|
});
|
|
```
|
|
|
|
### Partial Override
|
|
|
|
You can override only specific models:
|
|
|
|
```typescript
|
|
// Use bundled detector and recognizer, but custom dictionary.
|
|
await initialize({ models: { dictionary: '/custom/path/my_dict.txt' } });
|
|
|
|
// Or use custom detector with bundled recognizer and dictionary.
|
|
await initialize({ models: { detection: '/custom/det.mnn' } });
|
|
```
|
|
|
|
---
|
|
|
|
## File Size Considerations
|
|
|
|
Model files can be large (typically 5-50 MB each). Consider:
|
|
|
|
1. **APK/IPA Size**: Bundled models increase your app's download size
|
|
2. **Compression**: Both Android and iOS compress assets, reducing the impact
|
|
3. **On-Demand Loading**: For smaller app sizes, download models on first launch instead
|
|
|
|
---
|
|
|
|
## Copying Models from Source
|
|
|
|
To copy the default PPOCR_v5 models from the source repository:
|
|
|
|
### Android
|
|
|
|
```bash
|
|
# From the repository root
|
|
cp models/PPOCR_v5/det.mnn packages/android/src/main/assets/
|
|
cp models/PPOCR_v5/rec.mnn packages/android/src/main/assets/
|
|
cp models/PPOCR_v5/dict.txt packages/android/src/main/assets/
|
|
```
|
|
|
|
### iOS
|
|
|
|
```bash
|
|
# From the repository root
|
|
mkdir -p packages/react-native/ios/models
|
|
cp models/PPOCR_v5/det.mnn packages/react-native/ios/models/
|
|
cp models/PPOCR_v5/rec.mnn packages/react-native/ios/models/
|
|
cp models/PPOCR_v5/dict.txt packages/react-native/ios/models/
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### Android
|
|
|
|
Build and inspect the AAR:
|
|
|
|
```bash
|
|
cd packages/react-native/android
|
|
./gradlew assembleRelease
|
|
|
|
# Inspect the AAR contents
|
|
unzip -l build/outputs/aar/android-release.aar | grep assets
|
|
```
|
|
|
|
You should see:
|
|
|
|
```
|
|
assets/det.mnn
|
|
assets/rec.mnn
|
|
assets/dict.txt
|
|
```
|
|
|
|
### iOS
|
|
|
|
Build and inspect the app:
|
|
|
|
```bash
|
|
cd ios
|
|
pod install
|
|
```
|
|
|
|
The models will be bundled in `RustoModels.bundle` within your app's frameworks.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Models Not Found (Android)
|
|
|
|
1. Verify files are in `src/main/assets/`
|
|
2. Clean and rebuild: `./gradlew clean assembleRelease`
|
|
3. Check LogCat for "Failed to find model files" errors
|
|
|
|
### Models Not Found (iOS)
|
|
|
|
1. Verify files are in `ios/models/`
|
|
2. Run `pod install` to update the bundle
|
|
3. Clean build folder in Xcode (Cmd+Shift+K)
|
|
4. Check Xcode logs for resource bundle errors
|
|
|
|
### Large App Size
|
|
|
|
If bundled models make your app too large, consider:
|
|
|
|
1. Using smaller model variants
|
|
2. Downloading models on first launch
|
|
3. Using on-demand resources (iOS) or app bundles (Android)
|