Metadata-Version: 2.4
Name: QRtsy
Version: 0.15.0
Summary: Encoder-neutral artistic QR rendering with adaptive image texture, semantic function patterns, presets, and QR-aware compensation
License-Expression: MIT
License-File: LICENSE
Author: Ricardo Newbery
Author-email: ric@digitalmarbles.com
Requires-Python: >=3.11, <4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: segno
Provides-Extra: server
Requires-Dist: litestar[standard] (>=2.24,<3) ; extra == "server"
Requires-Dist: pillow (>=12.3.0,<13.0.0)
Requires-Dist: segno (>=1.6.6,<2) ; extra == "segno"
Requires-Dist: segno (>=1.6.6,<2) ; extra == "server"
Description-Content-Type: text/markdown


# The QRtsy Project

<img align="left" width="110" height="110" 
 src="https://codeberg.org/newbery/qrtsy/raw/branch/master/src/qrtsy/server_assets/qrtsy-icon.png">

**QRtsy** (pronounced **“cue-artsy”**) is an experimental Python toolkit for
making pretty QR codes.

**QRtsy** combines a normal QR matrix with a source image, preserves the pixels that a
scanner most needs to sample, and leaves the remaining pixels available for the
image and optional texture effects. The result is a playground for exploring the
tradeoff between **visual appearance** and **scan reliability**.

**QRtsy** is designed primarily as a reusable, encoder-neutral Python library. It
also includes an optional [Segno](https://segno.readthedocs.io/) integration, a
command-line interface, and a local browser application for interactively trying
different settings.

> **QRtsy is alpha software.** Artistic QR codes deliberately spend some of the
> robustness of a conventional QR symbol. Always test generated codes with the
> actual phones, cameras, print sizes, display sizes, distances, angles, and
> lighting conditions in which you expect them to be used.


## Installation

QRtsy requires **Python 3.11 or newer**.

It is a good idea to install QRtsy into a dedicated Python virtual environment
rather than into your system Python. From the directory where you want to work:

```console
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

The rest of the installation instructions below use the standard Python `pip`
command installed within this **activated** virtual environment. If it's not
activated, you'll probably install the library somewhere unexpected and that
will just be confusing and maybe even break things. Remember to **activate**. 

> Instead of using `pip` directly, most Python code jockeys these days instead
> tend to use various third-party project tools to manage project virtual
> environments like [Poetry](https://python-poetry.org/) or
> [UV](https://docs.astral.sh/uv/). Pick your favorite tooling.

To install just the core QRtsy library with the encoder-neutral Pillow renderer:

```console
pip install qrtsy
```

To install QRtsy with Segno support for the convenience API, command-line
interface, and Segno converter plugin:

```console
pip install 'qrtsy[segno]'
```

Or to install QRtsy with the local browser application, which also includes Segno:

```console
pip install 'qrtsy[server]'
```

## Quickstart: Browser UI

After QRtsy has been installed, the easiest way to explore its features is with
the local web application:

```console
qrtsy-server
```

Then open `http://127.0.0.1:8000/` in your web browser.

Upload an image, enter the text or URL to encode, and experiment with the
controls while QRtsy updates the preview.

The UI includes full-color, posterized, and monochrome image modes; QR version,
mask, and error-correction controls; sampling-core sizing; function-pattern
shrinking; several free-pixel texture algorithms; optional luminance
compensation; built-in and custom presets; per-setting undo; and PNG download.

The **How does this work?** link opens the built-in manual at `/what`. The source
for that guide is also readable directly in the repository at
[`docs/what.md`](docs/what.md).

The server binds to `127.0.0.1` by default. Uploaded and generated images are
processed in memory rather than written to the server filesystem.


## Quickstart: Python

For most applications, the Segno convenience API is the simplest place to
start:

```python
from qrtsy import RenderOptions
from qrtsy.integrations.segno import save

save(
    "https://example.com/",
    "portrait.jpg",
    "qrcode.png",
    RenderOptions(
        module_size=8,
        core_size=3,
        border=4,
    ),
    segno_options={"error": "H", "version": 6},
)
```

Segno is optional because QRtsy itself does not encode payloads. The core
renderer consumes an encoder-neutral semantic `ModuleMatrix`, so other QR
encoders can be adapted without coupling the renderer to Segno.

If you already have a Segno QR code, QRtsy can render that directly:

```python
import segno

from qrtsy import RenderOptions
from qrtsy.integrations.segno import save_qr

qr = segno.make_qr("https://example.com/", error="H")
save_qr(
    qr,
    "portrait.jpg",
    "qrcode.png",
    RenderOptions(module_size=8, core_size=3, border=4),
)
```

When QRtsy and Segno are installed together, QRtsy also registers a Segno
converter named `qrtsy`:

```python
qr.to_qrtsy(
    "qrcode.png",
    image="portrait.jpg",
    module_size=8,
    core_size=3,
    border=4,
)
```

For a direct example of the encoder-neutral `ModuleMatrix` API, see
[`examples/matrix.py`](examples/matrix.py).


## Quickstart: Command line

The `qrtsy` command uses the optional Segno integration:

```console
qrtsy \
  'https://example.com/' \
  portrait.jpg \
  qrcode.png \
  --error H \
  --version 6 \
  --module-size 8 \
  --core-size 3 \
  --border 4
```

The CLI defaults to QR version 6. Use `--version auto` to let Segno choose the
smallest version that fits the payload.

For all available options:

```console
qrtsy --help
```

## Highlights

QRtsy currently supports:

- full-color, posterized, and monochrome image backgrounds;
- cover, contain, and stretch image fitting;
- configurable module size, quiet zone, and central QR sampling-core size;
- semantic treatment of data and QR function-pattern modules;
- optional shrinking of finder/separator, alignment, and timing patterns to
  expose more of the image;
- constrained Floyd–Steinberg dithering for monochrome rendering;
- optional free-pixel texture using ordered dither, seeded noise, randomized
  error diffusion, or directional flow diffusion;
- adaptive texture fade to keep texture concentrated in visually suitable image
  regions;
- QR-aware local luminance compensation;
- built-in presets plus custom Python and browser presets;
- JSON preset import/export;
- an optional Segno adapter and Segno converter plugin;
- a CLI and a Litestar/Uvicorn local experimentation server.

Most of these controls exist because there is no single “best” artistic QR code.
A setting that looks great for one photograph, payload, output size, and scanner
may perform badly for another.


## How it works

QRtsy separates **QR encoding** from **QR rendering**.

An encoder adapter converts a QR symbol into a semantic matrix whose modules are
classified as data, finder, separator, timing, alignment, format, version, fixed
dark, and so on. This is more information than a simple dark/light matrix and
lets the renderer treat different parts of the QR symbol differently.

For image-bearing modules, QRtsy can replace only a centered **sampling core**
with the required black or white QR value instead of painting the entire module.
The surrounding pixels remain available to show the source image. QR function
patterns can remain fully rendered, or selected patterns can be shrunk
explicitly for more aggressive experiments.

Optional texture passes can make the regular sampling-core grid less visually
obvious. Optional local compensation can then nudge free pixels within each
module to recover some of the luminance changed by forced QR pixels and texture.

For a walkthrough of the rendering pipeline, every UI setting, QR anatomy,
texture modes, compensation, and scannability tradeoffs, see
[`docs/what.md`](docs/what.md).


## Presets

QRtsy currently ships with three built-in renderer presets:

- `default` — the normal `RenderOptions` defaults;
- `scan-priority` — a more conservative starting point with a four-module quiet
  zone, large sampling cores, protected timing patterns, and no optional texture
  or compensation;
- `small-core-textured` — a more aggressive experimental style using one-pixel
  cores and randomized error-diffusion texture.

For example:

```python
from qrtsy import get_preset
from qrtsy.integrations.segno import save

options = get_preset("scan-priority").options
save("https://example.com/", "portrait.jpg", "qrcode.png", options)
```

Custom Python presets are process-local. Custom presets created in the browser
UI are stored in that browser's local storage and can be exported to or imported
from JSON.

## Scannability

QR error correction helps recover damaged codewords, but it does not make
arbitrary artistic changes safe. QRtsy intentionally exposes controls that can
make a symbol less robust.

A few practical rules of thumb:

- larger sampling cores are generally more scannable than smaller ones;
- leaving finder, alignment, and timing structures intact is generally more
  scannable than shrinking them;
- try at least a four-module quiet zone since that is the QR standard;
- texture and compensation are aesthetic tools; they can't increase scanning robustness;
- test the final physical or displayed result, not just a large desktop preview.

The built-in `scan-priority` preset is a useful conservative starting point, but
it is still not a guarantee. See the [scannability discussion](docs/what.md#scannability)
for more detail.


## Development

The project uses Poetry and Poe the Poet:

```console
poetry install --all-extras
poetry run poe check
```

Useful development tasks include:

```console
poetry run poe lint
poetry run poe format
poetry run poe typecheck
poetry run poe test
poetry run poe coverage
poetry run poe docs
poetry run poe build
poetry run poe server
```

`poe check` runs project validation, linting, format checking, type checking,
tests, and a documentation-generation consistency check.

The server manual is generated from `docs/what.md` by `docs/build_docs.py`.


## Current limitations

QRtsy is still deliberately experimental. Among the current limitations:

- output is raster/Pillow only;
- the QRtsy-supplied Segno adapter does not support Micro QR;
- local compensation can be slow;
- the renderer does not calculate or enforce a Reed–Solomon damage budget;
- Python custom presets are process-local while browser presets are local to
  that browser;
- Segno-specific module classification remains isolated behind the adapter
  because Segno documents that interface as experimental.

Expect APIs and rendering behavior to change while the project is in alpha.


## Acknowledgements

QRtsy owes its biggest debt to Andrew Taylor's
[Dithered QR Code Generator](https://www.andrewt.net/dithered-qr-codes/) and his
excellent explanation of
[how the technique works](https://www.andrewt.net/dithered-qr-codes/wtf/).
His use of small forced QR samples and error diffusion was the starting point for
much of this experimentation.

QRtsy does not try to reinvent QR encoding itself. The first supplied integration
uses [Segno](https://segno.readthedocs.io/), whose encoder, semantic module output,
and plugin architecture make it a particularly useful match for the project.

The built-in manual contains additional links to QR standards, tutorials,
research papers, and other aesthetic QR-code projects.

The QRtsy project icon was generated by the QRtsy server app using
*Painter Artist* by Gan Khoon Lay from 
[Noun Project](https://thenounproject.com/browse/icons/term/painter-artist/)
(licensed under
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/deed.en))
as the background image.

 
## License

QRtsy is released under the [MIT License](LICENSE).

“QR Code” is a registered trademark of DENSO WAVE INCORPORATED.

