Metadata-Version: 2.4
Name: aglaia
Version: 0.1.0a4
Summary: Webcam book scanner for macOS — capture, dewarp, binarize, OCR to searchable PDF/Markdown.
License: # PolyForm Shield License 1.0.0
        
        <https://polyformproject.org/licenses/shield/1.0.0>
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree to them
        as both strict obligations and conditions to all your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the software to do
        everything you might do with the software that would otherwise
        infringe the licensor's copyright in it for any permitted purpose.
        However, you may only distribute the software according to
        [Distribution License](#distribution-license) and make changes or new
        works based on the software according to
        [Changes and New Works License](#changes-and-new-works-license).
        
        ## Distribution License
        
        The licensor grants you an additional copyright license to distribute
        copies of the software. Your license to distribute covers distributing
        the software with changes and new works permitted by
        [Changes and New Works License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of the
        software from you also gets a copy of these terms or the URL for them
        above, as well as copies of any plain-text lines beginning with
        `Required Notice:` that the licensor provided with the software. For
        example:
        
        > Required Notice: Copyright Yann Barbotin (https://aglaia.bibli.cc)
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license to make
        changes and new works based on the software for any permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software that covers
        patent claims the licensor can license, or becomes able to license,
        that you would infringe by using the software.
        
        ## Noncompete
        
        Any purpose is a permitted purpose, except for providing to others any
        product that competes with the software.
        
        If you use this software to market a product as a substitute for the
        functionality or value of the software, it competes with the software.
        A product may compete regardless how it is designed or deployed. For
        example, a product may compete even if it provides its functionality
        via any kind of interface (including services, libraries or plug-ins),
        even if it is ported to a different platforms or programming
        languages, and even if it is provided free of charge.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the law. These
        terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any of your
        licenses to anyone else, or prevent the licensor from granting
        licenses to anyone else. These terms do not imply any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes or
        contributes to infringement of any patent, your patent license for the
        software granted under these terms ends immediately. If your company
        makes such a claim, your patent license ends immediately for work on
        behalf of your company.
        
        ## Violations
        
        The first time you are notified in writing that you have violated any
        of these terms, or done anything with the software not covered by your
        licenses, your licenses can nonetheless continue if you come into full
        compliance with these terms, and take practical steps to correct past
        violations, within 32 days of receiving notice. Otherwise, all your
        licenses end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is, without any
        warranty or condition, and the licensor will not be liable to you for
        any damages arising out of these terms or the use or nature of the
        software, under any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these terms, and
        the **software** is the software the licensor makes available under
        these terms.
        
        **You** refers to the individual or entity agreeing to these terms.
        
        **Your company** is any legal entity, sole proprietorship, or other
        kind of organization that you work for, plus all organizations that
        have control over, are under the control of, or are under common
        control with that organization. **Control** means ownership of
        substantially all the assets of an entity, or the power to direct its
        management and policies by vote, contract, or otherwise. Control can
        be direct or indirect.
        
        **Your licenses** are all the licenses granted to you for the software
        under these terms.
        
        **Use** means anything you do with the software requiring one of your
        licenses.
        
        ---
        
        Required Notice: Copyright Yann Barbotin (https://aglaia.bibli.cc)
        
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: doxapy>=0.9.4
Requires-Dist: jax>=0.9.0
Requires-Dist: jaxlib>=0.9.0
Requires-Dist: ml-dtypes>=0.5.4
Requires-Dist: numpy<2.1.0,>=1.26.0
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: page-dewarp>=0.2.7
Requires-Dist: pikepdf>=10.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: pypdfium2>=4.30.0
Requires-Dist: python-slugify>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.11.0
Provides-Extra: surya
Requires-Dist: surya-ocr>=0.20.0; extra == "surya"
Requires-Dist: torch<3,>=2.7.0; extra == "surya"
Provides-Extra: paddle
Requires-Dist: paddleocr[doc-parser]>=3.6.0; extra == "paddle"
Requires-Dist: paddlepaddle>=3.2.1; extra == "paddle"
Requires-Dist: mlx-vlm>=0.6.0; extra == "paddle"
Provides-Extra: gui
Requires-Dist: pyside6-essentials>=6.7.0; extra == "gui"
Requires-Dist: pyqtdarktheme>=2.1.0; extra == "gui"
Provides-Extra: voice
Requires-Dist: vosk>=0.3.45; sys_platform != "darwin" and extra == "voice"
Requires-Dist: vosk==0.3.44; sys_platform == "darwin" and extra == "voice"
Requires-Dist: sounddevice>=0.4.6; extra == "voice"
Provides-Extra: macos
Requires-Dist: pyobjc-framework-avfoundation>=10.0; extra == "macos"
Requires-Dist: pyobjc-framework-cocoa>=10.0; extra == "macos"
Requires-Dist: pyobjc-framework-speech>=10.0; extra == "macos"
Requires-Dist: pyobjc-framework-vision>=10.0; extra == "macos"
Requires-Dist: mlx>=0.20; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "macos"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: reportlab>=4.0.0; extra == "dev"
Provides-Extra: package
Requires-Dist: pyinstaller>=6.10.0; extra == "package"
Provides-Extra: cuda
Requires-Dist: jax[cuda12]>=0.9.0; extra == "cuda"
Provides-Extra: jbig2
Requires-Dist: aglaia_jbig2; extra == "jbig2"
Provides-Extra: cloud
Requires-Dist: mistralai>=1.0.0; extra == "cloud"
Requires-Dist: keyring>=24.0.0; extra == "cloud"
Provides-Extra: keyring-bitwarden
Requires-Dist: bitwarden-keyring>=0.3.1; extra == "keyring-bitwarden"
Provides-Extra: keyring-1password
Requires-Dist: onepassword-keyring>=0.1.1; extra == "keyring-1password"
Dynamic: license-file

<a id="readme-top"></a>

<!-- PROJECT SHIELDS -->
[![Release][release-shield]][release-url]
[![CI][ci-shield]][ci-url]
[![Issues][issues-shield]][issues-url]
[![Python 3.12][python-shield]][python-url]
[![Platforms][platforms-shield]][release-url]
[![Made in France][france-shield]][france-url]
[![License: PolyForm Shield][license-shield]][license-url]

<!-- PROJECT HEADER -->
<br />
<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./aglaia/assets/brand/aglaia-dark.png" />
    <img alt="Aglaïa" src="./aglaia/assets/brand/aglaia-light.png" width="380" />
  </picture>

  <p align="center">
    Turn a webcam and a stack of pages into clean, deskewed, dewarped,
    searchable PDFs — locally, on your machine.
    <br />
    <a href="https://aglaia.bibli.cc/docs"><strong>Explore the docs »</strong></a>
    <br />
    <br />
    <a href="https://aglaia.bibli.cc">Website</a>
    ·
    <a href="https://github.com/yb85/aglaia/releases/latest">Download</a>
    ·
    <a href="https://github.com/yb85/aglaia/issues/new?labels=bug">Report Bug</a>
    ·
    <a href="https://github.com/yb85/aglaia/issues/new?labels=enhancement">Request Feature</a>
  </p>
</div>

> [!WARNING]
> **Alpha software — it will crash.** Aglaïa is under active development and
> still in testing. It is fairly well tested on **macOS**, but **not yet** on
> **Linux** or **Windows** — expect bugs and rough edges there. Keep your
> originals; don't rely on it for anything irreplaceable. Bug reports welcome.

<!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project</a>
      <ul><li><a href="#built-with">Built With</a></li></ul>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#download">Download</a></li>
        <li><a href="#install-from-the-command-line">Install from the command line</a></li>
      </ul>
    </li>
    <li><a href="#usage">Usage</a></li>
    <li><a href="#how-it-works">How It Works</a></li>
    <li><a href="#roadmap">Roadmap</a></li>
    <li><a href="#contributing">Contributing</a></li>
    <li><a href="#license">License</a></li>
    <li><a href="#contact">Contact</a></li>
    <li><a href="#acknowledgments">Acknowledgments</a></li>
  </ol>
</details>

<!-- ABOUT THE PROJECT -->
## About The Project

The goal of this project is to provide a simple, comprehensive, extendable, tool for end-to-end book scanning.

Book scanning is usually done using custom rigs — *eg* [Custom rigs on diybookscanner.org](https://www.diybookscanner.org/en/designs.html)

This is a fine way of doing things which has many advantages : you control the perspective, the geometry, the illumination, …
**BUT** it is not portable and requires a quite substancial time and resources investment.

At the other end of the spectrum you have ugly phone pictures, and a myriad of "Free Scanner" aps on the iOS appStore which all repackage the simple homography and detection primitives of the Apple Vision SDK : if you are not scanning flat sheets of paper you are out of luck 

**Aglaia** wants to do the following : **Provide a comprehensive solution to book scanning**, *ie* allow to use **physical books** and **the tools you have** (a laptop and a phone, maybe a camera) **in any situation** you could be (at your desk, on bench outside, at the libray…) to produce **high-quality digital materials** suitable for :
- archiving, indexing and printing : **clean, OCRed PDFs**
- feeding knowledgebases and AI research tools : **well structured Markdown files**

The slider section on the project website demonstrates this purpose :
![3 different scanning situations](./docs/assets/sliders_readme.png)


**Aglaïa**'s purpose is similar to **Scantailor**'s, but it tries to reduce the friction with better import (images, pdf or capture), exports (pdf with OCR, markdown, ...), built-in OCR, extendability through custom pipelines, exporters and plugins and more modern algorithms. 

### What the default pipeline will do to a standard book ?

In a few word Aglaïa will produce precisely cut binarized text pages with perspective and page curvature correction. On a modern laptop it can process roughly 1 page / sec.

To achieve it, it relies on :

- a coarse scan-based deskewing followed  by a robust and precise page extraction using lightweight ML text recognition models
- a finer page based deskewing followed by a robust binarization which can tolerate very unequal illumination and handle border constraints
- keystone and page curvature correction. This is the most computationally demanding part, handed out to JAX/CUDA or JAX/MLX libraries if available
- a final replay to intelligently compose the coordinate and morphological transforms to avoid successive interpolation artifacts, especially severe on bilevel images

![Operator composition (Smart replay) prevents re-interpolation artifacts](./docs/assets/replay.png)



> [!NOTE]
> **Cross-platform.** Native GUI builds ship for **macOS** (signed/notarized
> DMG, Apple Silicon), **Windows** (installer) and **Linux** (AppImage), plus
> `pip install aglaia` on any platform. On macOS, Apple Vision powers page
> detection and on-device OCR; off macOS, Aglaïa falls back to EAST/DBnet for
> layout and to Surya / PaddleOCR-VL / Mistral for OCR. Voice control (Vosk)
> is offline and cross-platform.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### How much does it costs ?

It's free. [Donations are appreciated](https://ko-fi.com/yb_85) to help cover developpement costs (signing and notarization, AI coding tool)


### Built With

* [![Python][python-shield]][python-url] managed with [uv](https://docs.astral.sh/uv/)
* **PySide6** — cross-platform desktop GUI
* **OpenCV · NumPy · SciPy · Pillow** — image processing
* **page-dewarp + JAX / MLX** — cubic-sheet page dewarp (MLX on Apple Silicon). The original project has been highly modified and extended
* **doxapy** — binarization (Wolf / Sauvola)
* **pikepdf · pypdfium2** — PDF I/O
* **Apple Vision · Speech** (pyobjc, macOS) — OCR, layout, with EAST/DBnet fallbacks
* **Surya · PaddleOCR-VL · Mistral Document AI** — cross-platform OCR engines
* **Vosk** — offline voice control (cross-platform)
* **SQLite (FTS5)** — project + full-text store

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->
## Getting Started

### Download

Grab the latest build for your platform — the release CI publishes
fixed-name "latest" artifacts, so these links never go stale:

| Platform | Download | Notes |
|---|---|---|
| **macOS** (Apple Silicon) | [`Aglaia-macos-arm64.dmg`](https://github.com/yb85/aglaia/releases/latest/download/Aglaia-macos-arm64.dmg) | Signed + notarized. Open and drag to Applications. |
| **Windows** (x64) | [`Aglaia-windows-x64-setup.exe`](https://github.com/yb85/aglaia/releases/latest/download/Aglaia-windows-x64-setup.exe) | Installer; registers the `.agl` file type. **Not code-signed** — SmartScreen will warn; click **More info → Run anyway**. Verify with [`SHA256SUMS-windows.txt`](https://github.com/yb85/aglaia/releases/latest/download/SHA256SUMS-windows.txt). |
| **Linux** (x86_64) | [`Aglaia-x86_64.AppImage`](https://github.com/yb85/aglaia/releases/latest/download/Aglaia-x86_64.AppImage) | `chmod +x`, then run. Needs FUSE (`fuse2`). |

### Install from the command line

CLI-only or scripted setups (any platform) install via **uv** or **pip**:

```sh
# from PyPI — installs the `aglaia` command
pip install aglaia                  # lean base: headless pipeline, no Qt
pip install "aglaia[gui]"           # Windows / Linux GUI (Qt)
pip install "aglaia[gui,macos]"     # macOS GUI: Vision, Speech, MLX dewarp
```

```sh
# or build from source with the extras you want
git clone https://github.com/yb85/aglaia.git && cd aglaia
uv sync --extra gui --extra macos   # macOS GUI
uv sync --extra gui                 # Windows / Linux GUI
uv sync                             # headless: CLI pipeline, no Qt
```

Optional extras: `--extra surya` / `--extra paddle` (OCR engines),
`--extra voice` (Vosk), `--extra cloud` (Mistral), `--extra cuda` (NVIDIA
GPU dewarp on Linux).

**First run (CLI-only installs):** run the one-time setup to pick and download
the offline models, seed the default pipelines, and bootstrap the config:

```sh
aglaia --setup        # interactive: choose models (DBnet, EAST, Surya…), download, configure
```

This is the terminal equivalent of the GUI's first-run wizard. A headless batch
run refuses to start until the install is configured (`--setup` or the GUI).
The GUI installs run the wizard automatically on first launch.

>[!WARNING] Build with the right options
> The `--extra` options are mandatory to interface models and backends with python. If you download the models or install cuda drivers on your computer but forget to include teh relevant extra options, they won't be used
>

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE -->
## Usage

```sh
# Capture GUI (webcam + processing chain + voice control)
uv run aglaia ~/scans/my-book        # or just `aglaia …` once installed

# Headless CLI batch — same chain, no Qt
uv run aglaia ~/scans/my-book.agl --headless -p aglaia/config/pipelines/book_curved_x2.yaml
```

Key flags: `--setup` (first-run config), `-c/--config`, `-p/--pipeline`,
`--workers`, `--export`, `--ocr`, `--input-dpi`, `--headless`,
`--camera-id`. The import panel accepts multiple images and PDFs (per-page
extract or render). Page detection defaults to **DBnet** (`auto` resolves
DBnet → Apple Vision on macOS → EAST); `aglaia --setup` and the in-app
downloader fetch the models, or drop them into `./model/` / `./models/`.

_For the full guide, see the [documentation](https://aglaia.bibli.cc/docs)._

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- HOW IT WORKS -->
## How It Works

```
capture → DPI fix → deskew → layout detect → keystone → dewarp → binarize → OCR → export
```

Every step is a pluggable processor defined in a YAML pipeline. Add your
own by dropping `aglaia/processors/<NewProc>.py` (the registry auto-discovers
it) — or, at runtime, drop a `.py` into `<APP_DATA>/plugins/` and approve
it in the trust prompt. See
[Architecture](https://aglaia.bibli.cc/docs/reference/architecture) and
[Processors](https://aglaia.bibli.cc/docs/reference/processors).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTRIBUTING -->
## Contributing

Work is tracked via GitHub issues + milestones — one issue per discrete
unit of work. Before non-trivial work, open an issue. Branch names
reference it (`feat/123-slug`); PRs close via `Closes #N`.

1. Fork the project
2. Create your branch (`git checkout -b feat/123-amazing-feature`)
3. Make changes; keep `ruff`, `mypy --strict`, and `pytest` green
4. Commit (`git commit -m 'feat: add amazing feature'`)
5. Push and open a Pull Request

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- LICENSE -->
## License

Source-available under the **[PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/)**
— see [`LICENSE`](LICENSE).

>[!WARNING] This is not strictly-speaking "open-source" !
>
> the reason is not to make it one day a commercial product, but to avoid trivial SaaS repackaging which hurts the developpment of free Apps.
>

You may use, modify, and redistribute the software for **any purpose
except building a product that competes with it**. Otherwise free.

Repackaging it and removing the donation link is direct competition.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTACT -->
## Contact

aglaia@bibli.cc

Project: [github.com/yb85/aglaia](https://github.com/yb85/aglaia) ·
Website: [aglaia.bibli.cc](https://aglaia.bibli.cc)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- ACKNOWLEDGMENTS -->
## Acknowledgments

See [ABOUT page](./ABOUT.md).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES -->
[release-shield]: https://img.shields.io/github/v/release/yb85/aglaia?style=for-the-badge
[release-url]: https://github.com/yb85/aglaia/releases/latest
[ci-shield]: https://img.shields.io/github/actions/workflow/status/yb85/aglaia/ci.yml?style=for-the-badge&label=CI
[ci-url]: https://github.com/yb85/aglaia/actions/workflows/ci.yml
[issues-shield]: https://img.shields.io/github/issues/yb85/aglaia?style=for-the-badge
[issues-url]: https://github.com/yb85/aglaia/issues
[python-shield]: https://img.shields.io/badge/python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white
[python-url]: https://www.python.org/
[platforms-shield]: https://img.shields.io/badge/macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-555?style=for-the-badge
[france-shield]: https://img.shields.io/badge/Made%20in-France%20%F0%9F%87%AB%F0%9F%87%B7-777?style=for-the-badge
[france-url]: https://github.com/yb85/aglaia
[license-shield]: https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-orange?style=for-the-badge
[license-url]: https://polyformproject.org/licenses/shield/1.0.0/
