Metadata-Version: 2.4
Name: vaepack
Version: 0.1.1
Summary: VAE-based image compression using latent space quantization and JPEG XL
License-Expression: MIT
Project-URL: Homepage, https://github.com/DVA305-VT26-Grupp4/Projektarbete
Project-URL: Repository, https://github.com/DVA305-VT26-Grupp4/Projektarbete
Project-URL: Issues, https://github.com/DVA305-VT26-Grupp4/Projektarbete/issues
Keywords: vae,image-compression,latent-space,jpeg-xl,sdxl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Processing
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: Pillow
Requires-Dist: imagecodecs
Requires-Dist: scikit-image
Requires-Dist: torch
Provides-Extra: diffusers
Requires-Dist: diffusers; extra == "diffusers"
Requires-Dist: transformers; extra == "diffusers"
Requires-Dist: accelerate; extra == "diffusers"
Requires-Dist: safetensors; extra == "diffusers"

# vaepack

VAE-based image compression using latent space quantization and JPEG XL.

`vaepack` encodes images into the latent space of a Variational Autoencoder
(SDXL), quantizes the latents to configurable bit-depth, and compresses the
result with JPEG XL inside a compact `.zvae` container.

> Alpha software. This project is experimental and not intended for production
> use. APIs and behavior may change without notice.

## Installation

### Recommended

Install the package with VAE support:

```bash
pip install "vaepack[diffusers]"
```

### Minimal

Install the core package only:

```bash
pip install vaepack
```

This is enough for container inspection and non-VAE utilities, but encoding and
decoding with the SDXL VAE requires the `diffusers` extra.

> Note: if you need GPU acceleration, install the appropriate PyTorch build
> first. See [pytorch.org](https://pytorch.org/get-started/locally/).

### From source

```bash
git clone https://github.com/DVA305-VT26-Grupp4/Projektarbete.git
cd Projektarbete
pip install -e ".[diffusers]"
```

## Quick start

### Python API

```python
from vaepack import compress, decompress

state = compress("photo.png", "photo.zvae", quant_bits=10, metrics=True)
print(state.metrics)

state = decompress("photo.zvae", "recon.png")
```

### Command line

```bash
zipvae compress photo.png -o photo.zvae --quant-bits 10 --metrics
zipvae decompress photo.zvae -o recon.png --reference photo.png --metrics
```

## What the package provides

- High-level `compress()` and `decompress()` helpers for notebooks and scripts
- A stage-based pipeline API for step-by-step experimentation
- A `.zvae` container format for compressed latents
- JPEG XL latent compression via `imagecodecs`
- PSNR and SSIM metrics
- A `zipvae` command-line interface

## Current limitations

- The project is still alpha quality.
- The packaged VAE backend is currently `sdxl`.
- The packaged codec backend is currently `jxl`.
- The first VAE load downloads weights from Hugging Face.
- Kodak benchmark assets and notebooks live in the source repository, not in the
  PyPI package.

## Examples and benchmark assets

The repository contains the batch benchmark script and the Colab notebook used
for Kodak experiments:

- [Repository](https://github.com/DVA305-VT26-Grupp4/Projektarbete)
- [Kodak batch script](https://github.com/DVA305-VT26-Grupp4/Projektarbete/blob/main/src/run_zipvae_batch.py)
- [Colab notebook](https://github.com/DVA305-VT26-Grupp4/Projektarbete/blob/main/src/run_zipvae_batch.ipynb)

For the full source, module-level docstrings, and issue tracker, use the
project links on PyPI or visit the repository directly.

## License

MIT
