Files
ssw c303c315e5 rocr: rusto-rs 源码入库(上游 v0.2.5 基线 57609fc + 本地补丁)
- 源码 316 文件收编为 rusto-rs/ 文件夹,随本仓库管理
- 移除内部 .git(补丁已存档 docs/rusto-rs-metal-patch-20260912.patch,上游可随时 re-clone)
- target/ 与 docs/.yarn 缓存不入库;本地改动:ROCR_* 环境变量调优 + Metal 链接修复 + 预处理测试脚本
2026-09-12 17:30:04 +08:00

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)