Development

Development

Run from source

git clone https://github.com/TonyD365/Inkhue && cd Inkhue
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt   # app + training + tools
.venv/bin/python -m inkhue                            # the app

requirements-app.txt alone is enough to run the app.

Command line

python -m inkhue.cli encode photo.jpg page.png --width-in 6
python -m inkhue.cli simulate page.png scan.png      # software print + scan
python -m inkhue.cli decode scan.png color.png

Tests, lint, benchmark

python -m pytest tests          # incl. the app window, headless
ruff check .
python scripts/benchmark.py     # ~1 min: 4 photos x 5 print/scan conditions x 3 seeds

Every pull request runs lint, tests on macOS / Windows / Linux, a packaged-app self-test and the benchmark against main (posted as a PR comment; a drop in decode success fails the check). PRs that touch packaging also build, install and self-test all four installers.

Train the neural refiner

python scripts/make_dataset.py data/div2k/DIV2K_train_HR --crops 8 --size 128 --out data/train.npz
python scripts/train.py --data data/train.npz --steps 8000          # Apple GPU (MPS) or CUDA
python -m inkhue.refiner_onnx models/refiner.pt models/refiner.onnx

The app ships only models/refiner.onnx. Include the benchmark result in your PR.

Releasing

1. Merge everything into main (branch protection requires the CI checks).
2. Create a GitHub release with a tag like v1.2.0, not marked pre-release.
3. The release workflow builds the four installers, installs and self-tests each, uploads them and SHA256SUMS.txt, and attests their provenance. Installed apps update from the release marked Latest.

Use a pre-release to test the build without updating anyone.

Rules

• Never change the on-paper format constants (inkhue/payload.py, halftone.py, layout.py) without a new VERSION and backwards-compatible decoding. tests/test_format.py enforces this.
• No encryption: hidden from the eye, not from people.