arthash 0.5.0

Placeholder-image hash family — DCT / CIRCLE / TRIANGLE / SQUARE / RECT / ROTATED_RECT / PIXEL modes share a unified Codec API. PyO3 binding to arthash-rs.

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)

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

Quick start

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.