Metadata-Version: 2.4
Name: legere
Version: 0.1.0
Summary: Compact CRNN OCR for printed text (Portuguese charset) — pure PyTorch, CPU-friendly, ~360k parameters
Author-email: Rafael Cezar <imrafaelcezar@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/imrafaelcezar/legere
Project-URL: Repository, https://github.com/imrafaelcezar/legere
Project-URL: Issues, https://github.com/imrafaelcezar/legere/issues
Keywords: ocr,crnn,ctc,pytorch,computer-vision,portuguese,text-recognition
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless>=4.8
Requires-Dist: pillow>=10.0
Provides-Extra: train
Requires-Dist: rich>=13.0; extra == "train"
Requires-Dist: psutil>=5.9; extra == "train"
Dynamic: license-file

# Legere

Compact CRNN OCR for printed text (Portuguese charset with accents, digits,
punctuation), built from scratch with PyTorch and trained entirely on
synthetic pages generated with PIL. No pretrained models, no OCR libraries.

- **~360k parameters** (hard limit enforced: 1M) — bundled weights are 1.4 MB
- CRNN: MobileNet-style depthwise separable CNN + 1 BiGRU(128) + linear head, CTC loss
- Classic (non-neural) deskew + projection-based line segmentation
- CPU-friendly: full-HD page in well under a second; INT8/TorchScript exports
- Trained weights ship inside the package — install and read pages immediately

## Install

```bash
pip install legere              # inference only
pip install legere[train]       # + training extras (rich, psutil)
```

From a checkout:

```bash
pip install -e .[train]
```

## Library usage

```python
from legere import Legere

ocr = Legere()                      # bundled weights, CPU
result = ocr.read("page.png")       # path, or a numpy array (gray or BGR)

print(result.text)                  # full text in reading order
print(result.skew_angle)            # estimated page skew (degrees)
for line in result.lines:
    print(line.text, line.bbox)     # per-line text + (x0, y0, x1, y1)
```

Options: `Legere(model="checkpoints/best.pt")` for your own checkpoint,
`Legere(model="exports/model_int8.ts.pt", torchscript=True)` for the INT8
export, `beam_width=8` for CTC beam search, `threads=N` to cap CPU threads.

## CLI

```bash
legere read page.png                    # text on stdout
legere page.png                         # same (shortcut)
legere read page.png --json out.json    # + per-line text and bboxes
legere read page.png --beam 8           # CTC beam search
legere read page.png --model exports/model_int8.ts.pt --torchscript

legere train                            # train on synthetic pages
legere export                           # TorchScript fp32 + INT8 exports
legere benchmark                        # CPU latency + page CER report
```

Pipeline of `read`: fit to 1920x1080 → adaptive binarization + deskew → line
segmentation by horizontal projection (rules removed via morphology) →
height-32 line batch through the CRNN → CTC greedy decode → text in reading
order.

## Project layout

```
src/legere/
├── charset.py        # character set + encode/decode helpers
├── model.py          # CompactCRNN, parameter budget, CTC greedy/beam decode
├── segment.py        # classic deskew + projection line segmentation
├── lines.py          # line-crop normalization and batching
├── inference.py      # Legere engine + full-page pipeline
├── metrics.py        # edit distance, CER, WER
├── cli.py            # `legere` command
├── data/model.pt     # bundled trained weights (state dict + charset)
└── training/         # synthetic pagegen, dataset stream, train/export/benchmark
```

## Training

Training data is generated on the fly: synthetic pages with headers,
paragraphs, key/value lines, tables, Portuguese-like words, dates, monetary
values and CPF/CNPJ, degraded with noise/blur/JPEG artifacts. Fonts are read
from `C:\Windows\Fonts` (training currently expects Windows).

```bash
legere train                          # live Rich dashboard
legere train --no-dashboard           # plain log lines
legere train --resume checkpoints/last.pt
```

Checkpoints go to `checkpoints/` (`best.pt` by validation CER, `last.pt`
every eval); metrics append to `runs/metrics.jsonl`. Training stops early
once CER < 1% holds with no further improvement, or on a clear plateau.
Useful flags: `--threads N`, `--width-budget N` (batch size via padded-width
budget; lower it to reduce RAM).

After training, refresh the packaged weights:

```bash
legere export --checkpoint checkpoints/best.pt --bundle src/legere/data/model.pt
```

## Export & benchmark

```bash
legere export        # writes exports/model_fp32.ts.pt and exports/model_int8.ts.pt
legere benchmark     # line/page CPU latency + full-page CER per variant
```

## Results

Bundled weights: validation CER 0.044% (line level, 2000-line fixed set) at
step 26k. `legere benchmark` reproduces line/page latency and full-page CER
on synthetic pages.

## License

MIT
