Metadata-Version: 2.4
Name: chiaroscuro-forge
Version: 0.3.0
Summary: An intelligent image enhancement tool inspired by Renaissance techniques
Home-page: https://github.com/MichailSemoglou/chiaroscuro-forge
Author: Michail Semoglou
Author-email: m.semoglou@tongji.edu.cn
License: MIT
Project-URL: Source, https://github.com/MichailSemoglou/chiaroscuro-forge
Project-URL: Issues, https://github.com/MichailSemoglou/chiaroscuro-forge/issues
Project-URL: Documentation, https://github.com/MichailSemoglou/chiaroscuro-forge/blob/main/README.md
Project-URL: Changelog, https://github.com/MichailSemoglou/chiaroscuro-forge/blob/main/MIGRATION.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-image>=0.18.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Chiaroscuro Forge

[![PyPI version](https://img.shields.io/pypi/v/chiaroscuro-forge.svg)](https://pypi.org/project/chiaroscuro-forge/)
[![PyPI downloads](https://img.shields.io/pypi/dm/chiaroscuro-forge.svg)](https://pypi.org/project/chiaroscuro-forge/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/chiaroscuro-forge?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/chiaroscuro-forge)
[![Python versions](https://img.shields.io/pypi/pyversions/chiaroscuro-forge.svg)](https://pypi.org/project/chiaroscuro-forge/)
[![License](https://img.shields.io/pypi/l/chiaroscuro-forge.svg)](https://github.com/MichailSemoglou/chiaroscuro-forge/blob/main/LICENSE)
[![Tests](https://github.com/MichailSemoglou/chiaroscuro-forge/workflows/Tests%20and%20Code%20Quality/badge.svg)](https://github.com/MichailSemoglou/chiaroscuro-forge/actions)
[![codecov](https://codecov.io/gh/MichailSemoglou/chiaroscuro-forge/branch/main/graph/badge.svg)](https://codecov.io/gh/MichailSemoglou/chiaroscuro-forge)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18200572.svg)](https://doi.org/10.5281/zenodo.18200572)

An intelligent image enhancement tool inspired by Renaissance techniques. Features automatic parameter detection, advanced color preservation, quality metrics, and parallel batch processing. Perfect for photographers and developers seeking to transform ordinary images with artistic precision.

## Features

- **Intelligent Enhancement**: Automatically analyzes image characteristics and applies optimal processing parameters
- **Advanced Color Preservation**: Maintains color fidelity while enhancing contrast and details
- **Multiple Enhancement Methods**: LAB, RGB, and ratio-based color processing modes
- **Quality Metrics**: Calculates SSIM, PSNR, MS-SSIM, and other perceptual quality scores
- **Batch Processing**: Process multiple images in parallel with detailed reporting
- **Preset System**: Save and reuse customized enhancement settings
- **Application Types**: Specialized processing for photography, documents, medical images, and art

## Installation

### Requirements

- Python 3.7+
- NumPy
- SciPy
- scikit-image

### Install from PyPI

```bash
pip install chiaroscuro-forge
```

After installing, the CLI entrypoint is available as:

```bash
chiaroscuro-forge --help
```

### Install from source

```bash
git clone https://github.com/MichailSemoglou/chiaroscuro-forge.git
cd chiaroscuro-forge
pip install -e .
```

## Quick Start

### Process a single image

```bash
chiaroscuro-forge input.jpg --output enhanced.jpg
```

### Analyze an image and suggest parameters

```bash
chiaroscuro-forge input.jpg --analyze
```

### Process multiple images in batch mode

```bash
chiaroscuro-forge "images/*.jpg" --output processed/ --batch
```

### Create and use presets

```bash
# Save parameters as preset
chiaroscuro-forge input.jpg --analyze --save-preset my_preset

# Use preset to process images
chiaroscuro-forge input.jpg --output enhanced.jpg --preset my_preset
```

## Command-Line Options

### Input/Output

- `image_path`: Path to input image or glob pattern for batch processing
- `--output, -o`: Path for output image or directory for batch processing
- `--batch, -b`: Enable batch processing mode

### Processing Parameters

- `--application, -a`: Application type (general, photography, medical, document, art)
- `--preset`: Name of a preset to use

### Analysis Options

- `--analyze`: Analyze image and suggest parameters
- `--analyze-batch`: Analyze multiple images and suggest optimal parameters
- `--compare`: Compare different processing methods
- `--compare-dir`: Output directory for comparison results

### Preset Management

- `--save-preset`: Save parameters as a preset
- `--list-presets`: List all available presets
- `--preset-description`: Description for the preset

### Batch Processing Options

- `--workers, -w`: Number of parallel workers (default: 4)
- `--skip-existing`: Skip files that have already been processed
- `--report`: Generate a JSON report with processing results
- `--log-file`: Path to log file for batch processing

## Examples

### Basic Enhancement

```bash
chiaroscuro-forge photo.jpg --output enhanced.jpg
```

### Custom Application Type

```bash
chiaroscuro-forge document.jpg --output enhanced.jpg --application document
```

### Analyze and Process

```bash
chiaroscuro-forge photo.jpg --analyze --output enhanced.jpg
```

### Compare Processing Methods

```bash
chiaroscuro-forge photo.jpg --compare
```

### Batch Processing with Report

```bash
chiaroscuro-forge "photos/*.jpg" --output enhanced/ --batch --workers 8 --report
```

## Python API

You can use Chiaroscuro Forge directly in your Python code:

### Get Image Statistics

```python
from chiaroscuro_forge import get_image_statistics

stats = get_image_statistics("photo.jpg")
print(f"Dimensions: {stats['dimensions']}")
print(f"Brightness: {stats['brightness']:.2f}")
print(f"Dynamic range: {stats['dynamic_range']:.2f}")
print(f"Contrast ratio: {stats['contrast_ratio']:.2f}")
```

### Process an Image

```python
from chiaroscuro_forge import process_image

processed, metrics = process_image(
    "input.jpg",
    output_path="enhanced.jpg",
    application_type="photography"
)
print(f"SSIM: {metrics['ssim']:.4f}")
print(f"PSNR: {metrics['psnr']:.2f} dB")
```

### Analyze Image Characteristics

```python
from chiaroscuro_forge import analyze_image_characteristics

analysis = analyze_image_characteristics("photo.jpg")
print(f"Suggested parameters: {analysis['suggested_params']}")
```

## Development

The project is structured around core image processing functions with a focus on quality and customizability:

- `get_image_statistics()`: Returns comprehensive image statistics (dimensions, intensity, histogram, dynamic range, contrast)
- `analyze_image_characteristics()`: Extracts characteristics from images
- `process_image()`: Main processing function with numerous customizable parameters
- `compare_processing_methods()`: Compares different enhancement approaches
- `batch_process_images()`: Handles processing of multiple images

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
