Build · Use the library · Read the format · Explore the research · Contribute
RasterFold is a lossless RGB image codec written in C11. It turns 24-bit BMP and 8-bit PNG images into .fold files and restores every pixel exactly. Use the command line, or embed the same codec through a small, versioned C API.
The project is in active development. Windows and Linux executables and libraries are exercised locally.
- One format, identical bytes. Format v3 has an independent Python oracle and frozen known-answer files (version 2 files still decode). Thread count does not change encoded output.
- CLI and library. Five C entry points provide encoding, decoding, validated inspection, version discovery and memory release. Shared and static libraries use the same core as the CLI.
- Careful file handling. By default the CLI refuses existing destinations, writes an exclusive
.partialfile, flushes it, and publishes without replacing another file;--overwritereplaces a destination only when asked. - A local, pinned toolchain. LLVM and Ninja live under ignored
tools/directories, with checked download hashes. Windows builds retain their freestanding Win32 core. - Measured research. Compression ideas are tested on a corpus with separate tuning and confirmation sets. Historical Windows results remain available with their conditions and limitations.
| Target | Executable | Shared library | Static library |
|---|---|---|---|
| Windows x64 | rasterfold.exe |
rasterfold.dll + MinGW/MSVC import libraries |
librasterfold.a |
| Linux x64 | rasterfold |
librasterfold.so |
librasterfold.a |
python3 tools/provision.py
source .venv/bin/activate
./build.sh --target all
python3 scripts/check-all.py --all-targetsOutputs land in bin/<target>/, organized into bin/ for executables and Windows DLLs, lib/ for libraries, include/ for headers and symbols/ for Windows PDBs. The compiler and SDK downloads stay inside the repository and are not committed. Python, Git, PowerShell 7 (pwsh, for PowerShell gate and automation wrappers), and the native Linux C development headers are host prerequisites. The build guide covers Windows, individual targets, verification and packaging.
bin/linux-x64/bin/rasterfold encode --time input.bmp output.fold
bin/linux-x64/bin/rasterfold decode output.fold restored.bmp
bin/linux-x64/bin/rasterfold inspect output.foldUse bin/windows-x64/bin/rasterfold.exe on Windows. --threads 1 requests the single-thread path; the default uses up to nine channel and strip threads when the CPU allows it. The current CLI accepts RGB8 BMP and 8-bit RGB or fully opaque RGBA PNG. JPEG, a non-opaque alpha channel, and animation are not accepted; those are future work, not hidden capabilities.
Include rasterfold.h, link a shared or static library, and release returned allocations with rf_free. The API accepts packed or padded top-down RGB8, uses per-call errors, and supports concurrent calls with distinct output objects. It performs no file I/O.
The library guide explains ownership and linking. The C examples encode and decode PPM images and are compiled and exercised by the artifact tests.
The execution plan owns planned work. AGENTS.md and GEMINI.md define format fidelity, review and measurement rules. Claude Code and Antigravity can write; Codex is reviewer-only, with skills in .agents/skills/, campaign Stop hooks and scripts/campaign_guard.py. Independent reviews route through scripts/review-dispatch.py to GPT-6.2 Astra through the Codex CLI for both writers.
Contributions should improve images in general. A size or speed claim needs the measurement protocol, its inputs, command and thread count. Reproducing one attractive result is not enough to claim a general win over JPEG XL.
Read the contribution guide, security policy and code of conduct. RasterFold is licensed under GPL-3.0.
Current codec: format 3, C API 1.0, RGB8. Maximum dimension: 32768; maximum image: 33554432 pixels. The native converter and full Pages site are planned in the product vision.