wimf 2.0.0

Worst IMage Format - A high-performance wavelet-based image codec

WIMF — Worst IMage Format

WIMF is an experimental, versioned image codec with a Python frontend and a portable C++17 backend. New still images use the WIM2 hybrid container: every 128×128 tile independently chooses Raw, Predictive, Palette, or CDF Wavelet coding and records its mode, entropy backend, bounds, size, offset, and checksum.

The format is under active development. WIM2 still-image coding, ROI decoding, high bit depth, native kernels, optional anti-rot recovery, and indexed chrono history are implemented. Legacy WIMF/AWIF decoding remains available; animation and coefficient watermark creation still use v1.

Highlights

• Per-tile hybrid selection with Fast, Balanced, and Extreme search presets.
• Exact lossless coding and quality-controlled CDF 9/7 lossy wavelets.
• Palette coding for local regions with at most 256 colors.
• Spatial prediction with row-level predictor selection.
• Independently decodable tiles for bounded ROI reads.
• RGB, RGBA, grayscale, and 8/10/16-bit pixel pipelines.
• Zstandard-compressed structured symbols and per-tile CRC32 checksums.
• Optional WIM2 anti-rot data capable of repairing up to two damaged shards.
• Indexed WIM2 chrono states with random state decoding.
• Portable C++17 kernels with a Python reference fallback.

Installation

Precompiled PyPI wheels are the intended release path but are not advertised as published until the release workflow has completed. For development:

git clone https://github.com/benchware/WorstImageFormat.git
cd WorstImageFormat
python -m pip install -e .

A matching wheel does not require a local compiler. Source installations require a C++17 compiler and pybind11; the Python fallback remains usable when the native extension is unavailable.

Python API

from PIL import Image
import wimf

image = Image.open("photo.png")

# Balanced per-tile selection is the default.
wimf.save("photo.wimf", image, quality=7, codec="auto", threads=None)

# Exact reconstruction and explicit legacy output.
wimf.save("exact.wimf", image, lossless=True)
wimf.save("legacy.wimf", image, lossless=True, format_version=1)

decoded = wimf.open("photo.wimf")
decoded.pil.save("decoded.png")

codec accepts auto, wavelet, predictive, palette, or raw. preset accepts Fast, Balanced, or Extreme.

ROI decoding

decoder = wimf.WIMFDecoder("large.wimf")
region = decoder.decode(roi=(1024, 768, 640, 480))

Only intersecting WIM2 tile payloads are decompressed.

Anti-rot and chrono history

encoder = wimf.WIMFEncoder(image).set_anti_rot()
encoder.add_chrono_state(edited_image)
payload = encoder.encode(lossless=True)

decoder = wimf.WIMFDecoder(payload)
original = decoder.decode_chrono_state(0)
edited = decoder.decode_chrono_state(1)
print(decoder.was_protected, decoder.was_repaired)

WIM2 extensions are appended after the base tile payload. Existing WIM2 files remain valid and older readers can still decode the primary image.

Runtime diagnostics

print(wimf.runtime_info())

The result reports whether native kernels are active, architecture, SIMD path, hardware and effective thread counts, codec version, and Zstandard version.

Command-line tools

• wimf-convert converts images and exposes quality, codec, metadata, and benchmark options.
• wimf-view opens the desktop viewer.
• wimf-cat renders supported images in compatible terminals.
• wimf-meta inspects and edits legacy metadata.

Compatibility and status

Capability	WIM2	Legacy decode
Hybrid still images	Implemented	WIMF v1 supported
Lossless and lossy coding	Implemented	Supported
ROI and independent tiles	Implemented	Format-dependent
Anti-rot	Two-shard WIM2 extension	ROT! supported
Chrono history	Indexed WIM2 extension	AWIF states supported
Animation creation	Planned	v1 only
Wavelet watermark creation	Planned	v1 only

See the WIM2 format overview, native embedding guide, and release checklist for implementation and publishing details.

Verification and roadmap

CI runs Python quality checks, native and fallback codec tests, standalone C++ tests on Windows/Linux/macOS, source-distribution validation, and an image-based codec report. The active roadmap is:

• Profile and move remaining candidate orchestration into the native core.
• Verify and distribute ARM64 wheels with NEON equivalence coverage.
• Publish signed PyPI wheels and a source distribution after release validation.
• Design browser/WASM portability without changing the WIM2 bitstream.
• Migrate animation and watermark creation only after the still-image path meets throughput targets.

Target performance is at least 10 MP/s Balanced encoding and 50 MP/s decoding on reference hardware; benchmark results are hardware-dependent and are not claimed until measured.

License

WIMF is licensed under GPL-3.0-or-later.