| --- |
| license: apache-2.0 |
| library_name: flattener |
| pipeline_tag: image-to-image |
| language: |
| - en |
| - ko |
| tags: |
| - document-scanning |
| - document-dewarping |
| - onnx |
| - pytorch |
| --- |
| |
| # Flattener |
|
|
| Version 1.1.0 of the models for [Flattener](https://github.com/deveworld/flattener). |
| Flattener turns document photos and open books into flat, upright scans. |
| Processing runs locally. |
|
|
| ## Files |
|
|
| | File | Purpose | |
| |---|---| |
| | `dewarp.onnx`, `dewarp.pt` | Correct page perspective and curvature | |
| | `gate.onnx`, `gate.pt` | Detect the page region | |
| | `orient.onnx`, `orient.pt` | Predict text orientation | |
| | `manifest.json` | Load the three ONNX models together | |
| | `bundle.json` | Load the three PyTorch checkpoints together | |
|
|
| The ONNX models are exported from the PyTorch checkpoints and hold the same weights. |
| The scanner runs them with ONNX Runtime on the CPU by default. |
| The PyTorch checkpoints run on a CUDA GPU and are the starting point for training. |
| `manifest.json` and the orientation checkpoint include the calibrated orientation temperature and threshold. |
|
|
| ## Use |
|
|
| ```bash |
| uvx flattener-scan -i photo.jpg scan.jpg |
| ``` |
|
|
| The first scan downloads the ONNX models at revision `1.1.0`. |
| Later scans reuse the local Hugging Face cache, including offline. |
| With PyTorch installed and a CUDA GPU present (`uvx --with torch flattener-scan ...`), the scanner downloads and uses the PyTorch checkpoints instead. |
|
|
| Download the files to a chosen directory with: |
|
|
| ```bash |
| hf download DevWorld/flattener manifest.json dewarp.onnx gate.onnx orient.onnx --revision 1.1.0 --local-dir models |
| ``` |
|
|
| Then pass `--bundle models/manifest.json` to the scanner. |
|
|
| ## Training and use |
|
|
| The models were trained from scratch using SyntheticDoc renders, UVDoc paper captures, SmartDoc frames and generated pages. |
| The dewarp model blends a clean-page checkpoint with a checkpoint trained on additional creases and folds. |
| The page detection and orientation models include generated Korean and English documents. |
| See the [source repository](https://github.com/deveworld/flattener) for training, evaluation and browser export tools. |
|
|
| Pages cut off by the photo, heavy occlusion and low-resolution text can produce incomplete scans or uncertain orientation. |
| The scanner reports these conditions and supports manual page and orientation adjustments. |
|
|
| ## License |
|
|
| These model weights are licensed under [Apache-2.0](LICENSE). |
|
|
