Zignal Python Bindings

Zero-dependency image processing primitives written in Zig and packaged for Python.

Feature Overview

All functionality is implemented in Zig with no runtime dependencies, making the wheel lightweight and easy to vendor.

Installation

pip install zignal-processing

• Python 3.11 – 3.15 (CPython)
• Prebuilt wheels ship for:
  • Linux x86_64 (manylinux_2_28)
  • macOS arm64
  • Windows x86_64
• Building from source requires Zig 0.17.0 or newer available on your PATH.

If CPython headers/libraries are in a non-standard location, set PYTHON_INCLUDE_DIR, PYTHON_LIBS_DIR, and PYTHON_LIB_NAME before installing.

Quickstart

import numpy as np
import zignal

# Load or create an image
img = zignal.Image.load("photo.jpg")                 # PNG/JPEG
canvas = zignal.Image(480, 640, color=zignal.Rgb(30, 144, 255)).canvas()

# Draw & process
canvas.draw_circle((120, 160), 60, zignal.Rgba(255, 255, 255, 180), fill=True)
img = img.gaussian_blur(1.5)
img = img.resize(0.5, zignal.Interpolation.BILINEAR)

# Pixels + NumPy (shared memory views)
img[10, 20] = zignal.Hsv(60, 100, 100)
np_view = img.to_numpy()                   # (rows, cols, 3) uint8 view
np_view[..., 0] = np.clip(np_view[..., 0] + 32, 0, 255)  # modifies img in-place
img2 = zignal.Image.from_numpy(np_view)    # zero-copy back into Zig

# Streaming stats & procedural noise
stats = zignal.RunningStats()
for value in np_view.mean(axis=-1).flat:
    stats.add(float(value))
noise = zignal.perlin(0.2, 0.4, amplitude=1.2, frequency=2.5, octaves=4)
print(f"μ={stats.mean:.3f} σ={stats.std_dev:.3f} perlin={noise:.3f}")

# Terminal preview (auto: kitty → iterm2 → sixel → sgr fallback)
print(f"{img:auto}")

# Save
img.save("out.png")

Documentation & Support

• Docs: https://arrufat.github.io/zignal/python/zignal.html
• Source: https://github.com/arrufat/zignal
• Issues: https://github.com/arrufat/zignal/issues

Development

zig build python                   # build extension + stubs (from the repo root)
cd bindings/python                 # or here: `zig build` (extension) / `zig build stubs`
uv venv && uv pip install -e .     # editable install
uv run pytest -q                   # run tests

Building Wheels

To build a wheel for your current platform:

cd bindings/python
uv run python -m build --wheel

To cross-compile or specify optimization:

ZIG_TARGET=x86_64-linux-gnu ZIG_OPTIMIZE=ReleaseFast uv run python -m build --wheel

Environment Variables

For portable Linux wheels, it is recommended to run auditwheel repair on the resulting wheel. On macOS, use delocate-wheel.

Contributing Bindings

Follow the bindings guide for argument parsing helpers, enum registration, image ownership, and stub generation.

Sponsors

Special thanks to B Factory, Inc, the Founding Sponsor of Zignal. They originally developed this library and graciously transferred ownership to the community to ensure its long-term maintenance and growth.

License

MIT