Metadata-Version: 2.5
Name: flattener-scan
Version: 1.0.1
Summary: Document photo scanner: page detection, orientation, dewarping and one render
Project-URL: Homepage, https://github.com/deveworld/flattener
Project-URL: Source, https://github.com/deveworld/flattener
Project-URL: Issues, https://github.com/deveworld/flattener/issues
Project-URL: Benchmarks, https://github.com/deveworld/flattener/blob/main/docs/BENCHMARKS.md
Project-URL: Models, https://huggingface.co/DevWorld/flattener
Author: World
License-Expression: Apache-2.0 AND MIT AND OFL-1.1
License-File: LICENSE
License-File: src/flattener/assets/fonts/OFL.txt
Keywords: document dewarping,document rectification,document scanner,ocr preprocessing,page detection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.13,>=3.12
Requires-Dist: huggingface-hub<3,>=1
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pillow<13,>=11
Requires-Dist: torch<3,>=2.7
Description-Content-Type: text/markdown

# Flattener

**Open-source SOTA document scanner.**

Turn document photos and open books into flat, upright scans.
Flattener detects pages, corrects orientation and curvature, and splits book spreads.
Everything runs locally.
Inference, training, data preparation and evaluation code are included.

See [benchmark results and reproduction instructions](https://github.com/deveworld/flattener/blob/main/docs/BENCHMARKS.md).

## Scan

Flattener needs Python 3.12 and is tested on Linux x86_64 with CPU PyTorch.

```bash
uvx --torch-backend cpu flattener-scan photo.jpg --out scans
```

Or install it with pip:

```bash
pip install flattener-scan --extra-index-url https://download.pytorch.org/whl/cpu
flattener photo.jpg --out scans
```

`--torch-backend cpu` and the extra index install the CPU build of PyTorch.
Without them, Linux gets the CUDA build, which is several gigabytes larger.

To work from a clone of this repository, use `uv sync --python 3.12` and run `uv run flattener`.

The first scan downloads the Apache-2.0 models from [Hugging Face](https://huggingface.co/DevWorld/flattener), version `1.0.0`.
Later scans reuse the local Hugging Face cache and work offline.
Set `HF_HOME` to choose a different cache directory.

Pass multiple photos for a batch.
Results include an image and a `.scan.json` record with outcomes and timings.
Book spreads produce separate page files.
Use `--region`, `--quad`, `--quarter` or `--output-size` for manual control; run `flattener --help` for all options.

From Python:

```python
from flattener.scan.io import save_scan
from flattener.scan.pipeline import Scanner

scanner = Scanner.load()
result = scanner.scan("photo.jpg")
save_scan(result, "scans", "photo")
```

Use `scanner.scan_pages("book.jpg")` for automatic spread splitting.

## Browser app

Scan single pages locally with WebGPU or CPU/WASM, edit the result and save a PNG.
See the [web app guide](https://github.com/deveworld/flattener/blob/main/web/README.md) for setup, capabilities and static hosting.

## Training

All three scanner models are trained from scratch on redistributable data.

- [Dewarp](https://github.com/deveworld/flattener/blob/main/docs/DEWARP.md)
- [Page detection](https://github.com/deveworld/flattener/blob/main/docs/PAGE_GATE.md)
- [Orientation](https://github.com/deveworld/flattener/blob/main/docs/ORIENT.md)

Run the Python tests with `uv run pytest -q`.

## License

Project code is [Apache-2.0](https://github.com/deveworld/flattener/blob/main/LICENSE).
