Metadata-Version: 2.4
Name: arthash
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
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 :: Rust
Classifier: Topic :: Multimedia :: Graphics
Requires-Dist: numpy>=2.0
Requires-Dist: pillow>=11.0
Summary: Placeholder-image hash family — DCT / CIRCLE / TRIANGLE / SQUARE / RECT / ROTATED_RECT / PIXEL modes share a unified Codec API. PyO3 binding to arthash-rs.
Keywords: thumbhash,placeholder,image,hash,perceptual,sqip,primitive
Author-email: Jianqi Pan <jannchie@gmail.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source, https://github.com/Jannchie/arthash

# arthash

Placeholder-image hash family. Seven modes share a unified Codec API:

| Shape          | Bytes (typical) | Notes |
|----------------|-----------------|-------|
| DCT            | ~21 B           | ThumbHash V4 derivative. Default. |
| CIRCLE         | varies          | SQIP-style overlapping circles. |
| TRIANGLE       | varies          | fogleman/primitive-style triangle mosaic. |
| SQUARE         | varies          | Axis-aligned squares (cx, cy, side). |
| RECT           | varies          | Axis-aligned rectangles (cx, cy, w, h). |
| ROTATED_RECT   | varies          | Rotated rectangles — `theta_bits` tunes angle steps. |
| PIXEL          | varies          | Retro-palette pixel mosaic. |

The implementation is a thin Python wrapper around the `arthash-rs` Rust crate
exposed via PyO3 — encode/decode/SVG all run in native code.

## Install (from source)

```bash
maturin develop --uv -m packages/arthash-py/Cargo.toml
```

## Quick start

```python
from arthash import encode, decode, to_svg, Codec, Preset, RenderStyle
from arthash.palettes import PICO8

# DCT (default)
h = encode("photo.jpg")
w, hh, rgba = decode(h, base_size=256)              # (h, w, 4) RGBA ndarray

# Named preset
codec = Codec.preset(Preset.LARGE_TRIANGLE)         # triangle, n=64
h = encode("photo.jpg", codec)

# Factory + palette
codec = Codec.triangle(n=24, palette=PICO8)
h = encode("photo.jpg", codec, seed=0)
svg = to_svg(h, codec, base_size=256,
             style=RenderStyle(blur=8.0))           # circle/triangle/etc.
```

`decode` always returns `(width, height, ndarray(h, w, 4))` regardless of
codec — alpha is 255 except for DCT-with-alpha sources.

## Visual styling — `RenderStyle`

`decode` and `to_svg` accept a `style=RenderStyle(blur=…, corner_radius=…)`
for visual softening. Both fields are applied identically across paths so
raster and SVG outputs stay visually consistent. `corner_radius` is only
honored for rect / square / rotated_rect codecs; other shapes silently
ignore it. `to_svg(..., blur=...)` still works but is deprecated since
0.3.0 — pass `style=RenderStyle(blur=...)` instead.

## Layout

- `python/arthash/` — public Python API (`Codec`, `ShapeType`, `SearchOptions`,
  `palettes`, `encode`, `decode`, `to_svg`).
- `src/lib.rs` — PyO3 binding to the `arthash` Rust crate. Compiled into
  `arthash._native`.
- `tests/` — pytest suite covering codec validation, V4 round-trip, shape
  round-trip, SVG generation, search-options, and the cross-language test
  vectors at `docs/test-vectors/vectors.json`.

