Metadata-Version: 2.4
Name: wimf
Version: 2.0.0
Summary: Worst IMage Format - A high-performance wavelet-based image codec
Author-email: BenchWare <ivanm12453@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/benchware/WorstImageFormat
Project-URL: Documentation, https://github.com/benchware/WorstImageFormat/tree/main/docs
Project-URL: Issues, https://github.com/benchware/WorstImageFormat/issues
Project-URL: Changelog, https://github.com/benchware/WorstImageFormat/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/benchware/WorstImageFormat
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: zstandard>=0.22
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benchware/WorstImageFormat/main/.github/assets/white.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/benchware/WorstImageFormat/main/.github/assets/dark.png">
    <img alt="Worst Image Format" src="https://raw.githubusercontent.com/benchware/WorstImageFormat/main/.github/assets/dark.png" width="500">
  </picture>
</p>

# 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:

```bash
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

```python
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

```python
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

```python
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

```python
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](docs/wim2-format.md), [native embedding guide](docs/native-core.md), and
[release checklist](docs/release-checklist.md) 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.
