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.

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 NEON and AVX2 SIMD acceleration and a Python reference fallback.

Known limitations

Compression ratios are actively improving. WIMF 2.2 introduced content-adaptive wavelet quantization, improved Zstandard compression levels, and quadratic rate-distortion scoring. The encoder now produces significantly smaller output for most workloads, but further tuning is expected in future releases without breaking decode compatibility.

Benchmarks and comparative metrics against PNG, WebP, AVIF, JPEG, and JPEG XL will be published separately once the codec reaches a stable performance baseline.

Installation

Install the published package with Python 3.10 or newer:

python -m pip install wimf

Precompiled wheels are published for Linux x86-64, Windows x86-64, macOS Intel, and macOS Apple Silicon across CPython 3.10–3.14. A matching wheel does not require a local compiler.

For development:

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

Source installations require a C++17 compiler and pybind11; the Python fallback remains usable when the native extension is unavailable.

Choose a configuration

Quality ranges from 1 through 10. Every quality is continuously tested under Fast, Balanced, and Extreme; the preset changes search effort, while quality controls lossy quantization.

Python API

from PIL import Image
import wimf

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

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

# 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")

# Memory-only applications can use bytes directly.
payload = wimf.encode(image, lossless=True, metadata={"author": "Arrow"})
decoded = wimf.decode(payload)
details = wimf.inspect(payload)

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

Complete save options

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.

Metadata without recompression

updated = wimf.rewrite_metadata(payload, {"author": "Arrow", "license": "CC0"})

WIM2 tile payloads remain byte-for-byte identical. Tile offsets and checksums are recalculated, history is retained, and anti-rot protection is regenerated when present.

Text transports

text = wimf.to_base64(payload, wrap=76)
assert wimf.from_base64(text) == payload

assert wimf.from_base16(wimf.to_base16(payload)) == payload
assert wimf.from_base32(wimf.to_base32(payload)) == payload

url = wimf.to_data_url(payload)
assert wimf.from_data_url(url) == payload

These helpers use strict RFC 4648 parsing, bounded input sizes, and whitespace-tolerant decoding. Data URLs use Base64 and the image/x-wimf MIME type. Base16, Base32, and Base64 are transport encodings-not compression-and expand data by roughly 100%, 60%, and 33%, respectively.

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.

Mandelbrot example

The included generator renders a Mandelbrot set with NumPy and writes WIMF directly:

python examples/mandelbrot_wimf.py mandelbrot.wimf --width 1920 --height 1080 --quality 7

Use --lossless, force a tile mode with --codec, or zoom using --center-x, --center-y, and --span.

Command-line tools

The unified command covers the normal workflow:

wimf encode photo.png photo.wimf --quality 7
wimf encode artwork.png artwork.wimf --lossless
wimf decode photo.wimf photo.png
wimf decode huge.wimf crop.png --roi 100 200 640 480
wimf info photo.wimf
wimf runtime
wimf view photo.wimf
wimf base16 encode photo.wimf photo.hex
wimf base32 encode photo.wimf photo.b32
wimf base64 encode photo.wimf photo.txt --data-url
wimf corrupt photo.wimf damaged.wimf --seed 42 --area payload
wimf diagnose damaged.wimf --unsafe-preview damaged-preview.png

Run wimf <command> --help for focused options. Metadata uses repeatable --metadata KEY=VALUE arguments. The original specialized commands remain available:

• wimf-convert and wimf-meta are deprecated compatibility tools in 2.2. Use the unified wimf CLI or WIMF Studio.
• AWIF authoring is deprecated. Existing animations remain readable, including historical timing metadata.
• wimf-studio opens the encoder, comparison viewer, tile inspector, protection/history tools, and codec lab.
• wimf-view is a compatibility alias that opens WIMF Studio.
• wimf-cat renders supported images in compatible terminals.
• wimf-meta inspects and edits legacy metadata.

Native C/C++ builds also provide wimf-native, a dependency-free process bridge for lossless PGM/PPM ↔ WIMF conversion.

Tested feature matrix

The visual report separately exercises synthetic mixed content, a credited nature photograph, and a credited animal photograph. It publishes decoded outputs, amplified differences, exact configurations, tile-mode counts, timings, WIMF payloads, and JSON metrics as CI artifacts.

Compatibility and status

See the WIM2 format overview, legacy migration guide, native embedding guide, desktop/application integrations, adoption roadmap, and release checklist.

Verification and roadmap

CI separates Python quality, cross-platform API/feature tests, legacy decode compatibility, standalone C++, sanitizers, packaging, visual evidence, and non-blocking performance measurements. Python-versus-C++ benchmarks cover current WIM2 still images on Windows, Linux, and macOS. The active roadmap is:

• Measure AVX2 and NEON SIMD acceleration across reference hardware (CRC-32 and predictive filter paths are implemented; wavelet lifting is scalar). Run tools/wimf_simd_bench.cpp locally or read CI job summaries - see docs/simd-benchmarks.md.
• Verify Linux ARM64 and Windows ARM64 wheels on dedicated native runners.
• Validate the memory-only synchronous core with Emscripten on the future web branch without changing the WIM2 bitstream.
• Publish signed standalone C/C++ development archives for the versioned ABI and conformance pack.
• Build on the Pillow plugin and native PGM/PPM bridge with ImageMagick, FFmpeg, and desktop thumbnailer integrations.
• Preserve legacy animation and watermark decoding without reviving their deprecated authoring paths.

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.

Reporting bugs

WIMF is experimental. If something breaks, please open a GitHub issue with your operating system, Python version, wimf runtime --json output, and a minimal sample file when possible. WIMF Studio's Help → Report a Bug command copies the relevant runtime diagnostics and opens the issue page.