README.md

---
license: mit
---
# Introduction

This repository hosts the [EasyOCR](https://github.com/JaidedAI/EasyOCR) models — the
[CRAFT detector](https://github.com/clovaai/CRAFT-pytorch) and the [CRNN recognizer](https://www.jaided.ai/easyocr/modelhub/) — for the
[React Native ExecuTorch](https://www.npmjs.com/package/react-native-executorch) library,
exported to `.pte` for the **ExecuTorch** runtime (XNNPACK, CoreML and Vulkan backends).

If you'd like to run these models in your own ExecuTorch runtime, refer to the
[official documentation](https://pytorch.org/executorch/stable/index.html) for setup instructions.

Each language ships as **one fused `.pte`** (CRAFT *detect* + CRNN *recognize* in a single
file) per backend, with a single **dynamic** `detect` method and one fixed-width `recognize`
method (no per-size method buckets). The `.pte` is a pure tensor→tensor function; all
pre/post-processing (resize, normalize, box extraction, crop, CTC decode) is the client's job
and is driven by `config.json`. EasyOCR is the *fallback* pipeline —
[PP-OCRv6](https://huggingface.co/software-mansion/react-native-executorch-pp-ocrv6) is primary.

## Languages

| code | charset size | code | charset size |
|---|---|---|---|
| english | 96 | korean | 1008 |
| latin | 351 | telugu | 165 |
| japanese | 2214 | kannada | 167 |
| zh_sim | 6718 | cyrillic | 207 |

All languages share the same CRAFT detector and CRNN architecture — they differ **only** in
the recognizer charset. The detector half of each fused PTE is identical across languages.
Charset index `i` maps to logit `i + 1` (logit `0` is the CTC blank).

## Methods & I/O contract

| method | input | output |
|---|---|---|
| `detect` (CRAFT) | `[1,3,H,W]` f32 RGB, **ImageNet-normalized by the client**: `(x/255 − mean)/std`, `mean=[0.485,0.456,0.406]`, `std=[0.229,0.224,0.225]` | score `[1,H/2,W/2,2]` (region + affinity, NHWC) and feature `[1,32,H/2,W/2]` |
| `recognize` (CRNN) | `[1,3,64,512]` f32 RGB, client-normalized `(x/255 − 0.5)/0.5` (RGB→gray conv is baked) | `[1,127,V]` probs (softmax baked) |

**Nothing is baked for input normalization** — the client normalizes before calling, with
*different* norms per method (ImageNet for detect, `0.5/0.5` for recognize).

## Shape discovery (companion methods)

Every method carries exactly **one** no-arg discovery companion:

- `get_dynamic_dims_<method>` — dynamic method. One `int32 [rank, 3]` tensor per tensor
  input; rows are `[min, max, step]` (static dims `[n, n, 1]`).
- `get_enum_shapes_<method>` — enumerated/fixed method. One `int32 [N, rank]` tensor per
  tensor input; each row is a complete legal shape (cross-dimension coupling is exact —
  `1280×320` listed does **not** imply `320×1280`). Snap inputs to the nearest row.

| backend | `detect` | `recognize` |
|---|---|---|
| `xnnpack` | `get_dynamic_dims_detect` → H, W ∈ `[320, 1280]` step 32 | `get_enum_shapes_recognize` → `[[1,3,64,512]]` |
| `vulkan` | `get_dynamic_dims_detect` → H ∈ `[800, 1280]`, W ∈ `[320, 1280]` step 32 | `get_enum_shapes_recognize` → `[[1,3,64,512]]` |
| `coreml` | `get_enum_shapes_detect` → `800²`, `1280²`, `1280×320` | `get_enum_shapes_recognize` → `[[1,3,64,512]]` |

`detect` runs once per image; `recognize` runs once per text line (the client snaps every
crop to width 512 — the CRNN's BiLSTM only delegates at a fixed time dimension).

## Backends

| backend | target | detect | recognize | warm latency (detect @800² / recognize) |
|---|---|---|---|---|
| `xnnpack` | CPU | int8, dynamic (see note) | int8 @512 | ~810 ms / ~24 ms (Galaxy S24) |
| `coreml` | Apple ANE | weight-only int8, enumerated | weight-only int8 @512 | ~83 ms / ~27 ms (Apple M-series ANE) |
| `vulkan` | Android GPU | fp16, dynamic (resize) | int8 @512 on **XNNPACK** (mixed-delegate) | ~750 ms / ~24 ms (Galaxy S24, Xclipse 940) |

> **XNNPACK detect accuracy note:** the int8 detector is calibrated for sizes **≤ 800 px**
> (its accurate operating band). Larger inputs up to 1280 are accepted but **best-effort** —
> static-activation int8 is not stable at ≥ 960 px (this was equally true, though unmeasured,
> of the previous per-bucket builds). Prefer resizing pages to ≤ 800 on CPU; the Vulkan and
> CoreML detectors are accurate over their full advertised ranges.

## CoreML notes (iOS)

- The CoreML `.pte` is a **multifunction** Core ML model (`detect` + `recognize` share one
  precompiled `.mlmodelc`). Requires **iOS 18+** and an ExecuTorch runtime ≥ 1.3.
- First-ever load on a device triggers a one-time per-shape ANE specialization (OS-cached
  afterwards) — warm each model once after install.

## Compatibility

If you intend to use these models outside of React Native ExecuTorch, make sure your runtime is
compatible with the **ExecuTorch** version used to export the `.pte` files. For more details, see
the compatibility note in the
[ExecuTorch GitHub repository](https://github.com/pytorch/executorch/blob/main/runtime/COMPATIBILITY.md).
If you work with React Native ExecuTorch, the library constants guarantee compatibility with the
runtime used behind the scenes.