Metadata-Version: 2.4
Name: pixiq
Version: 0.1.0
Summary: Intelligent image compression library with perceptual quality optimization
Project-URL: Documentation, https://github.com/bubaley/pixiq#readme
Project-URL: Homepage, https://github.com/bubaley/pixiq
Project-URL: Repository, https://github.com/bubaley/pixiq.git
Author-email: bubaley <bubaley.fu@gmail.com>
Maintainer-email: bubaley <bubaley.fu@gmail.com>
License: The MIT License (MIT)
        
        Copyright (c) 2025 bubaley
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Keywords: avif,compression,image,jpeg,perceptual,quality,webp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: numpy>=2.0.2
Requires-Dist: pillow-avif-plugin>=1.3.0
Requires-Dist: pillow>=9.0.0
Description-Content-Type: text/markdown

# Pixiq - Intelligent Image Compression

A library for intelligent image compression with perceptual quality preservation.

## Key Features

- Automatic quality selection to achieve target perceptual quality
- Support for JPEG, WEBP, and AVIF formats
- Image resizing capabilities
- Resaving compressed images with new resolutions
- Optimized hash calculation
- Complete input parameter validation
- Convenient methods for working with compression results

## Usage Example

```python
from PIL import Image
from pixiq import Pixiq

# Compress an image
result = Pixiq.compress(
    input=Image.open('input.jpg'),
    perceptual_quality=0.85,  # Target quality (0.0-1.0)
    max_size=2000,            # Maximum dimension size
    max_quality=95,           # Maximum compression quality
    output='output.avif'      # Output file
)

print(f'Selected quality: {result.selected_quality}')
print(f'File size: {result.file_size_kb:.1f} KB')
print(f'Dimensions: {result.dimensions}')

# Get information about the best iteration
best_iter = result.best_iteration
print(f'Best quality: {best_iter["quality"]}, error: {best_iter["error"]:.4f}')

# Resave with different resolution
result_small = result.save_thumbnail(max_size=600, output='output_600.avif')
print(f'600px file size: {result_small.file_size_kb:.1f} KB')
```

## API Reference

### Pixiq.compress()

Main method for compressing images with automatic quality selection.

**Parameters:**
- `input`: PIL Image - input image (required)
- `perceptual_quality`: float = 0.95 - target perceptual quality (0.0-1.0)
- `tolerance`: float = 0.005 - quality tolerance
- `max_quality`: int = None - maximum compression quality (1-100)
- `min_quality`: int = None - minimum compression quality (1-100)
- `max_size`: int = None - maximum image dimension
- `max_iter`: int = 5 - maximum number of search iterations
- `format`: str = None - output file format ('JPEG', 'WEBP', 'AVIF')
- `output`: str or io.BytesIO = None - output file path or buffer

**Returns:** CompressionResult

**Exceptions:**
- `TypeError`: if input parameters have incorrect types
- `ValueError`: if parameter values exceed allowed ranges
- `IOError`: on file saving errors

### CompressionResult

Class representing the result of image compression.

#### Properties:
- `compressed`: PIL Image - compressed image
- `iterations_count`: int - number of compression iterations
- `iterations_info`: list[dict] - information about each iteration
- `selected_quality`: int - selected compression quality
- `hash`: str - MD5 hash of compressed image
- `fmt`: str - file format
- `extra_save_args`: dict - additional save parameters

#### Computed Properties:
- `file_size_bytes`: int - file size in bytes
- `file_size_kb`: float - file size in kilobytes
- `dimensions`: tuple[int, int] - image dimensions (width, height)
- `last_iteration`: dict | None - information about the last iteration
- `best_iteration`: dict | None - information about the best iteration

#### Methods:
- `save_thumbnail(max_size, output=None)` - resaves thumbnail with new size
- `save(output)` - saves image to specified output

### Pixiq.save_thumbnail()

Static method for creating a thumbnail version of a compressed image.

**Parameters:**
- `result`: CompressionResult - result of previous compression
- `max_size`: int - new maximum dimension size
- `output`: str or io.BytesIO = None - output file path or buffer

**Returns:** new CompressionResult

## Supported Formats

- **JPEG**: with optimization and progressive scanning
- **WEBP**: with maximum compression method (method=6)
- **AVIF**: with maximum speed (speed=6)

## Compression Algorithm

1. Binary search over compression quality (1-100)
2. PSNR calculation between original and compressed images
3. PSNR to perceptual quality conversion (empirical formula)
4. Selection of quality with minimum error relative to target quality
5. Optimized hash calculation from compressed buffer

## Performance

- Optimized hash calculation (without re-encoding)
- Efficient memory usage
- Support for large images
- Smart file format detection
