Metadata-Version: 2.4
Name: avix-engine
Version: 1.0.1
Summary: AVIX: The Ultra-Premium Archival Trust Format with SHA-256 Integrity Sentry.
Home-page: https://github.com/escrawl/avix-engine
Author: Escrawl Products
Author-email: contact@escrawl.com
Keywords: image compression lossless avix archival medical medical-imaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: zstandard>=0.19.0
Requires-Dist: numba>=0.56.0
Provides-Extra: gpu
Requires-Dist: cupy>=10.0.0; extra == "gpu"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AVIX: The Archival Trust Format

[![PyPI version](https://img.shields.io/pypi/v/avix-engine.svg?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/avix-engine/)
[![Python compatibility](https://img.shields.io/pypi/pyversions/avix-engine.svg?logo=python&logoColor=white)](https://pypi.org/project/avix-engine/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Platform support](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-lightgrey)](https://pypi.org/project/avix-engine/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> **A mathematically verified, parallelized lossless image format designed for absolute data preservation.**

AVIX (`avix-engine`) is an ultra-premium, hardware-accelerated image format designed for absolute mathematical trust. It is engineered specifically for industries where data loss, silent corruption, or storage overhead is critical—such as Medical Imaging (PACS/DICOM), Scientific Research (Satellite/Deep-Space), and VFX Studio Cold-Storage.

Unlike WebP, AVIF, or JPEG XL (which optimize for lossy web streaming), AVIX is designed for long-term archival safety, petabyte-scale local storage arrays, and native high-throughput parallel processing.

---

## Technical Specifications & Features

* **Cryptographic SHA-256 Sentry:** Every `.avix` file is sealed with an immutable 32-byte hash. If a storage sector suffers bit-rot over decades, the decoder halts with an exception instead of silently rendering corrupted medical or scientific pixels.
* **Linear Multi-Threaded Scaling:** Slices massive images into independent 1024x1024 tiles and compresses them concurrently across all available physical CPU cores, bypassing the single-threaded limits of legacy formats like PNG.
* **LLVM Native JIT Execution:** Utilizes Numba to dynamically compile spatial prediction algorithms (AVX2: Left, AVX3: Up, and AVX6: Paeth Gradient) into native 64-bit LLVM machine instructions on first execution.
* **Kernel-Level Streaming (mmap):** Accesses large-scale 8K+ images by mapping the file descriptor directly to the CPU cache, bypassing memory allocations and preventing Out-Of-Memory (OOM) crashes on constrained systems.
* **Instant Header Previews:** Embedded 128px high-fidelity thumbnails and JSON metadata can be retrieved in under 5 milliseconds without reading or decompressing the pixel payload.

---

## Technical Architecture & Data Flow

AVIX utilizes a multi-pass, block-based spatial prediction pipeline designed for zero-copy memory layouts:

```
  Uncompressed Image (RGB/RGBA)
              │
              ▼
    1024x1024 Block Tiling (Zero-Copy Slicing)
              │
              ▼
    YCoCg Color Decorrelation (Lossless Color Space)
              │
              ▼
┌───────────────────────────────────────────────┐
│     LLVM JIT-Compiled Spatial Filters         │
│  ├── AVX2: Left Predictor                     │
│  ├── AVX3: Up Predictor                       │
│  └── AVX6: Paeth Gradient Predictor (Optimal) │
└───────────────────────┬───────────────────────┘
                        │ (Fastest block chosen)
                        ▼
            Zstandard Entropy Encoding
                        │
                        ▼
         SHA-256 Sentry Seal Application
                        │
                        ▼
               Sealed .avix Archive
```

---

## Performance Benchmarks

*Tests performed on a 16-Core AMD Threadripper, compressing a 100MB 16-bit TIFF image:*

| Format | Compression Ratio | Save/Encode Speed | Decode Speed | Memory Footprint (RAM) | Cryptographic Verification? |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Raw TIFF** | 1.0x | 0.05s | 0.05s | ~250 MB | No |
| **PNG** | 1.6x | 12.4s | 1.1s | ~300 MB | No |
| **ZIP (on TIFF)** | 1.7x | 14.1s | 1.8s | ~400 MB | No |
| **AVIX (Archival)**| **2.1x** | **0.85s** | **0.32s** | **~45 MB (mmap)** | **Yes (SHA-256 Sentry)** |

---

## Installation

Install the stable core library and CLI directly via PyPI:

```bash
pip install avix-engine
```

For hardware offloading (CUDA hybrid mode), install with the optional GPU dependencies:
```bash
pip install avix-engine[gpu]
```

---

## Developer API

Integrating AVIX into existing pipelines takes only a few lines of code.

### 1. Lossless Encoding (Archival Save)
Compresses and seals any standard Pillow-supported image.
```python
import avix

# Compress a raw PNG/TIFF to an archival, SHA-256 sealed AVIX file
success = avix.encode('patient_scan_001.png', 'patient_scan_001.avix', mode='archival')
if success:
    print("Archive successfully sealed.")
```

### 2. Lossless Decoding (mmap Streaming)
Decodes the image directly to the CPU cache, running the integrity check automatically.
```python
import avix

try:
    # Directly streams file into memory using OS-level mmap
    img = avix.decode('patient_scan_001.avix')
    img.show()
except Exception as e:
    # Triggers immediately if the file suffered bit-rot on disk
    print(f"CRITICAL: Integrity validation failed! {e}")
```

### 3. High-Speed Preview Extraction
Extracts metadata and the embedded thumbnail without decompressing the pixel payload.
```python
import avix

# Returns a high-fidelity 128px Pillow Image in < 5ms
thumbnail = avix.extract_thumbnail('patient_scan_001.avix')
thumbnail.save('preview.jpg')
```

---

## Command Line Interface (CLI)

The package automatically registers a globally accessible `avix` shell command upon installation.

```bash
# Get usage details and CLI help
avix --help

# Compress an image using high-ratio archival predictions
avix compress input.png output.avix --mode archival

# Decompress and verify integrity
avix decompress output.avix restored.png

# Query file structure, dimensions, and SHA-256 seal status
avix info output.avix
```

---

## Comparative Advantages: AVIX vs. WebP / AVIF

Standard web formats like WebP and AVIF are designed to save network bandwidth on mobile devices by permanently throwing away visual data the human eye is poor at detecting. 

**AVIX throws away nothing.** It preserves raw mathematical reality. If you are a hospital storing an MRI, or a VFX studio archiving raw $100M film assets, AVIX guarantees that the mathematical array you decode is the exact bit-level array you put in, while delivering modern parallel speeds.

---

## License
AVIX is open-source software licensed under the [MIT License](file:///c:/Users/asus/OneDrive/Desktop/Escrawl%20Products/Pixel/LICENSE.txt). Developed and maintained by Escrawl Products.
