Metadata-Version: 2.4
Name: picx-image-optimizer
Version: 0.1.0
Summary: A tiny Python image optimization toolkit for batch compression and web assets.
Project-URL: Homepage, https://github.com/ingeniousfrog/picx
Project-URL: Issues, https://github.com/ingeniousfrog/picx/issues
Project-URL: Repository, https://github.com/ingeniousfrog/picx
Author: ingeniousfrog
License: MIT
License-File: LICENSE
Keywords: compression,image,optimization,tiff,tiles,webp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Requires-Dist: pillow>=10.0
Requires-Dist: pyvips>=2.2
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# picx

picx is a small Python image optimization package for web assets, blogs, avatars,
and batch cleanup jobs. The package installs a CLI named `picx` and exposes a
compact Python API under `picx`.

## Features

- Compress single images or entire directories.
- Convert between `jpg`, `png`, `webp`, `avif`, and `tiff` outputs.
- Read `jpg`, `jpeg`, `png`, `webp`, `avif`, `tif`, and `tiff` inputs.
- Resize with `max_width` and `max_height`.
- Strip image metadata by default.
- Search for the highest quality under a target byte size.
- Render CLI compression reports with Rich.
- Use `web`, `blog`, `avatar`, and `lossless` presets.

## Install

```bash
pip install -e ".[dev]"
```

`pip install picx-image-optimizer` installs the pyvips Python backend package. pyvips also
needs the native libvips system library for large-image processing. pip cannot
install this native system library for every platform, so install it once with
your OS or environment package manager:

```bash
brew install vips
# or
conda install -c conda-forge libvips pyvips
```

Install libvips in the same environment that runs `picx`. For example, if you
run `picx` inside `conda activate comfyui`, install libvips inside that conda
environment. Mixing Homebrew libvips with Anaconda/conda libraries can still
fail on macOS with dynamic-library or code-signature errors.

## CLI

Optimize one image:

```bash
picx image ./photo.png --output ./dist/photo.webp --format webp --quality 82
```

Optimize a directory recursively while preserving relative paths:

```bash
picx dir ./images ./out --format webp --preset web
```

Try a target size in bytes:

```bash
picx image ./hero.jpg --output ./out/hero.webp --format webp --target-size 120000
```

Handle trusted large images with Pillow:

```bash
picx image ./texture.tif --output ./texture.webp --format webp --allow-large --max-pixels 400000000
```

Use the pyvips backend for large images:

```bash
picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips
```

WebP has a per-side dimension limit of 16383 pixels. If either width or height
is larger, resize first or use tiling:

```bash
picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips --max-height 16000
```

Create tiles and a manifest for very large images:

```bash
picx tile ./texture.tif ./tiles --tile-size 1024 --format webp
```

## Python API

```python
from picx import optimize_dir, optimize_image, tile_image

single = optimize_image(
    "photo.png",
    output="dist/photo.webp",
    format="webp",
    quality=82,
    max_width=1600,
    strip_meta=True,
)

batch = optimize_dir(
    "images",
    "out",
    format="webp",
    preset="blog",
    recursive=True,
)

tiles = tile_image("texture.tif", "tiles", tile_size=1024, format="webp")
```

`optimize_image()` and `optimize_dir()` return `OptimizeResult` objects with:

- `original_size`
- `output_size`
- `savings_ratio`
- `skipped`
- `error`
- `source_path`
- `output_path`

## Presets

| Preset | Output | Purpose |
| --- | --- | --- |
| `web` | webp, quality 82, max width 1920 | General website images |
| `blog` | webp, quality 78, max width 1600 | Blog and article images |
| `avatar` | webp, quality 85, max 256 x 256 | Profile images |
| `lossless` | png, quality 100 | Lossless-ish cleanup with metadata stripping |

## Development

```bash
python3 -m pytest
```

picx uses Pillow by default and includes the pyvips Python backend package.
The pyvips backend also requires the native libvips system library, which pip
does not install automatically. Install libvips in the same environment that
runs `picx`.

## Large Images

By default, picx keeps Pillow's large-image safety posture. If an image exceeds
the configured pixel limit, picx reports a clear error with next steps instead
of showing a raw traceback. For trusted images, use `--allow-large` and optionally
set `--max-pixels`. For memory-efficient processing, install system libvips and
select `--backend pyvips` or keep the default `--backend auto`.

For single-file WebP output, keep both width and height at or below 16383 pixels.
Images larger than that should be resized with `--max-width` / `--max-height`, or
exported with `picx tile` instead.

`picx tile` writes image tiles plus `manifest.json`. The manifest is an index,
not a merged image: it records the original size, tile size, output format,
levels, and every tile's path and coordinates so another tool can display or
reconstruct the tile layout reliably.
