a3s-use-ocr 0.1.2

Typed built-in optical character recognition for A3S Use
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# A3S Use OCR

`a3s-use-ocr` implements the first-party built-in OCR domain for A3S Use. A3S
Code receives it as `mcp__use_ocr__*` through the release-matched Use registry,
without installing a separate extension. The native CLI and standard stdio MCP
share one local PP-OCRv6 implementation.

There is one OCR provider:

- provider: `pp-ocr-v6`
- engine: `onnx-runtime`
- model bundle: `PP-OCRv6_small`

The first extraction installs or repairs the pinned detection and recognition
models when networking and first-use installation are allowed. Prepare them
explicitly when deterministic startup or offline work is required:

```bash
a3s install use/ocr
a3s install use/ocr --force
```

`A3S_OCR_MODEL_DIR` can point development builds at an explicit model bundle.
`A3S_USE_OCR_HOME` overrides the managed model root for packaging, tests, or an
isolated installation. Neither setting selects another OCR backend.

## Workflow

For each bounded local image, the native engine:

1. decodes the image and applies PP-OCRv6 BGR normalization;
2. runs `PP-OCRv6_small_det` through ONNX Runtime;
3. applies DB post-processing, polygon unclipping, and reading-order sorting;
4. perspective-rectifies each text polygon and rotates tall crops;
5. runs batched `PP-OCRv6_small_rec` inference; and
6. applies CTC decoding and returns text, recognition/detection confidence,
   polygons, bounding boxes, and the source SHA-256.

All inference stays in the local `a3s-use` process. It does not require Python
or PaddlePaddle, does not call an OCR API, and does not transfer image bytes off
the device.

## Commands

```bash
a3s use ocr doctor --json
a3s use ocr extract ./scan.png --json
a3s use mcp serve ocr
```

`doctor` is read-only and never downloads anything. Direct CLI extraction
prepares missing or damaged A3S-managed models automatically. Through MCP, the
`use` worker calls the separate `ocr_install` mutation, which must pass parent
confirmation before extraction continues. `A3S_OFFLINE=1` and
`A3S_NO_AUTO_INSTALL=1` prohibit this first-use download.

Supported inputs are bounded local PNG, JPEG, WebP, GIF, BMP, and TIFF files.
URLs and PDF rasterization are outside this crate.