![Pikture Icon](Pikture.svg)
# PIKTURE (PIK)
**Fast. Small. Easy.**

PIKTURE is a high-performance, lossless image format designed for systems where decoding speed and binary simplicity are critical. It is built on the **FSE** philosophy: **F**ast execution, **S**mall file size, and **E**asy integration.

## 🚀 Why PIKTURE?
Standard formats like PNG are often bottlenecked by heavy decompression algorithms (DEFLATE/ZIP). PIKTURE replaces complex bit-shuffling with a hardware-friendly **INDEX + Delta** encoding. This allows the CPU to stream pixels directly to memory with minimal overhead, acting closer to a memory copy operation than a math-heavy decompression.

### ✨ Key Features
- **Lossless:** 100% bit-perfect reproduction of RGBA data.
- **Ultra-Fast:** Near-memcpy decoding speeds utilizing cache-friendly algorithms.
- **Hardware Acceleration:** Optional SIMD (AVX/NEON) and OpenMP multithreading support.
- **Small Footprint:** Two-file C library (`.c` / `.h`) with zero external dependencies.
- **Endian-Aware:** Cross-architecture compatibility (Little-Endian / Big-Endian).
- **Smart Alpha:** Automatically optimizes storage when transparency is not used.

---

## 📊 Performance Comparison
Benchmark results for loading a 5K professional image (Sample dimensions: 5120x2880):

| Format | Load Time | Dimensions |
| :--- | :--- | :--- |
| **PIK** | **0.111735 sec** | 5120x2880 |
| PNG | 0.193990 sec | 5120x2880 |

*PIKTURE decodes nearly 2x faster than standard PNG implementations on the same hardware without SIMD or OpenMP.*

---

## 🛠️ Implementation & Usage

The core library consists of only two files:
* `pikture.h` - Contains the data structures (`pikture_t`) and public API declarations.
* `pikture.c` - Contains the core encoding/decoding logic, hashing, and byte-stream processing.

### Basic API Example
Integrating PIKTURE into your C/C++ project is trivial:

```c
#include "pikture.h"
#include <stdio.h>

int main() {
    // Load an image
    pikture_t* img = pikture_load("image.pik");
    if (!img) {
        printf("Failed to load image!\n");
        return 1;
    }

    printf("Loaded %dx%d image.\n", img->width, img->height);

    // Save an image
    pikture_save("output.pik", img);

    // Free memory
    pikture_free(img);
    return 0;
}

```

---

## ⚙️ Building & Compilation

The project is designed to be highly portable. You can compile it using standard GCC/Clang or cross-compile it using the **Zig** toolchain.

### Build Scripts

```bash
# Run the build script to generate static and shared libraries
./build.sh   # UNIX (macOS / Linux)
./build.bat  # WINDOWS

```

### Advanced Compilation Flags

You can enable hardware-specific optimizations by passing the following preprocessor directives during compilation:

* `-DPIKT_USE_SIMD` : Enables vectorized instructions (AVX/SSE for x86_64, NEON for ARM64) to process multiple pixels per clock cycle.
* `-DPIKT_USE_THREADS` : Enables OpenMP multithreading. Divides the decoding/encoding workload across multiple CPU cores (perfect for large 4K/8K images).

**Example compilation with optimizations (GCC):**

```bash
gcc -O3 -DPIKT_USE_SIMD -DPIKT_USE_THREADS -fopenmp main.c pikture.c -o myapp

```

---

## 🔬 Technical Specification

PIKTURE is a binary format. All multi-byte integers in the header are stored in **Big-Endian** format.

### 1. File Header (11 Bytes)

| Offset | Size | Type | Description |
| --- | --- | --- | --- |
| `0x00` | 4 bytes | `char[4]` | Magic bytes: `"PIK!"` |
| `0x04` | 1 byte | `uint8_t` | Version number (Currently `101`) |
| `0x05` | 2 bytes | `uint16_t` | Image Width |
| `0x07` | 2 bytes | `uint16_t` | Image Height |
| `0x09` | 1 byte | `uint8_t` | Bit Depth (Currently `32` for RGBA) |
| `0x0A` | 1 byte | `uint8_t` | Endianness flag (`0` = Little, `1` = Big) |

### 2. Byte-Stream Protocol

Immediately following the header is the compressed pixel data payload. PIKTURE uses a custom command-byte protocol combined with a 64-color Least Recently Used (LRU) cache:

* `0x00 - 0x3F` (**INDEX**): Fetch the exact pixel from the 64-color LRU cache.
* `0x40 - 0x7F` (**DIFF**): Apply small RGB deltas (differences from the previous pixel).
* `0x80 - 0xBF` (**LUMA**): Apply green-relative color deltas (highly efficient for gradients).
* `0xC0 - 0xFD` (**RUN**): Repeat the exact same previous pixel `N` times (Run-Length Encoding).
* `0xFE` (**RGB**): Full 24-bit color change (Alpha remains unchanged). Followed by 3 bytes (R, G, B).
* `0xFF` (**RGBA**): Full 32-bit color change. Followed by 4 bytes (R, G, B, A).

---

## 📜 License

This project is licensed under the **MIT License**. Free to use, modify, and distribute for personal and commercial purposes.