Metadata-Version: 2.4
Name: photo-restorer
Version: 0.1.1
Summary: Local-first Python library for photo restoration, face enhancement, color correction, and perceptual pre-downscaling.
Project-URL: Homepage, https://pypi.org/project/photo-restorer/
Project-URL: Repository, https://github.com/reiarthur/photo-restorer
Project-URL: Issues, https://github.com/reiarthur/photo-restorer/issues
Author-email: Arthur <arthur@sart.dev>
License: MIT License
        
        Copyright (c) 2026 King Arthur
        
        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: computer-vision,gfpgan,image-restoration,photo-restoration,realesrgan,super-resolution
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: basicsr<2,>=1.4.2
Requires-Dist: facexlib<1,>=0.3
Requires-Dist: gdown<7,>=6
Requires-Dist: gfpgan<2,>=1.3.8
Requires-Dist: huggingface-hub<2,>=1.11
Requires-Dist: numpy<3,>=2.2
Requires-Dist: opencv-python<5,>=4.13
Requires-Dist: pillow<13,>=11
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pyiqa<1,>=0.1.15.post2
Requires-Dist: realesrgan<1,>=0.3
Requires-Dist: requests<3,>=2.32
Requires-Dist: scikit-image<1,>=0.25
Requires-Dist: scipy<2,>=1.15
Requires-Dist: spandrel<1,>=0.4.2
Requires-Dist: torch<3,>=2.10
Requires-Dist: torchvision<1,>=0.25
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: twine>=6.2; extra == 'dev'
Description-Content-Type: text/markdown

# photo-restorer

[![PyPI version](https://img.shields.io/pypi/v/photo-restorer.svg)](https://pypi.org/project/photo-restorer/)
[![Python versions](https://img.shields.io/pypi/pyversions/photo-restorer.svg)](https://pypi.org/project/photo-restorer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`photo_restorer` is a local-first Python library for restoring and optimizing real photographs with a compact public API. It keeps the main processing flow on the local machine, uses weights under `models/` by default, and exposes high-level operations for full optimization, face restoration, color correction, and perceptual pre-downscaling.

## Supported operations

- Single-image optimization from local path, base64, or data URL
- Batch optimization for multiple local files
- Optional face restoration with GFPGAN
- Final color correction for real photographs
- Optional perceptual pre-downscale before full optimization
- Local model management rooted at `models/`

## Requirements

- Python 3.12 or higher
- Local runtime dependencies installed through `pip`
- Enough disk space for model weights under `models/`

## Install

```bash
pip install photo-restorer
```

## Checking the version

```python
import photo_restorer

print(photo_restorer.__version__)
```

## Configuration

The main workflow does not require API keys or remote service credentials.

Configuration is resolved lazily in this order:

1. Explicit parameters passed to `PhotoRestorer(...)` or to each function call
2. Environment variables from the current process

`photo_restorer` does not auto-load `.env` files.

### Providers and environment variables

| Item | Type | Notes |
| --- | --- | --- |
| Local models under `models/` | Runtime backend | Uses local weights for Real-ESRGAN, GFPGAN, and related helpers |
| Remote services | Provider | Not used by the main public API |
| `PHOTO_RESTORER_MODELS_ROOT` | Env var | Overrides the local models root |
| `PHOTO_RESTORER_USE_CPU` | Env var | Forces CPU execution when truthy |
| `PHOTO_RESTORER_FACE_RESTORATION` | Env var | Enables or disables the face pass |
| `PHOTO_RESTORER_PRE_DOWNSCALE` | Env var | Enables perceptual pre-downscaling |
| `PHOTO_RESTORER_OUTPUT_SUFFIX` | Env var | Changes the default batch output suffix |

See [docs/configuration.md](docs/configuration.md) for the full configuration guide.

## Quickstart

### Optimize a single image

```python
from photo_restorer import optimize_image

result_base64 = optimize_image(
    "examples/photo.jpg",
    pre_downscale=True,
)
```

### Optimize multiple local images

```python
from photo_restorer import optimize_images

optimize_images(
    ["examples/photo-1.jpg", "examples/photo-2.png"],
    suffix="_restored",
)
```

### Restore faces only

```python
from photo_restorer import restore_faces

restored_face_base64 = restore_faces(
    "examples/portrait.jpg",
    face_blend_weight=0.45,
)
```

### Correct colors only

```python
from photo_restorer import correct_colors

corrected_base64 = correct_colors("examples/faded-photo.jpg")
```

### Apply perceptual pre-downscale only

```python
from photo_restorer import pre_downscale_image

reduced_base64 = pre_downscale_image("examples/oversampled.png")
```

### Reuse a stateful client

```python
from photo_restorer import PhotoRestorer

client = PhotoRestorer(
    models_root="models",
    use_cpu=True,
)

optimized_base64 = client.optimize_image("examples/photo.jpg")
client.optimize_images(["examples/photo-1.jpg", "examples/photo-2.jpg"])
```

## Public API

| Module | Members | Purpose |
| --- | --- | --- |
| `photo_restorer` | `PhotoRestorer`, `optimize_image`, `optimize_images`, `restore_faces`, `correct_colors`, `pre_downscale_image` | Main high-level API |
| `photo_restorer.client` | `PhotoRestorer`, `optimize_image`, `optimize_images`, `restore_faces`, `correct_colors`, `pre_downscale_image` | Stateful client and convenience helpers |
| `photo_restorer.models` | `PhotoRestorerSettings`, `ImageOptimizationOptions`, `BatchOptimizationOptions`, `ModelArtifact` | Public Pydantic models |
| `photo_restorer.exceptions` | `PhotoRestorerError`, `ConfigurationError`, `ImageSourceError`, `InputImageNotFoundError`, `SameOutputDirectoryError`, `ModelProvisioningError`, `ProcessingError` | Public exception hierarchy |

## Error handling

All public exceptions inherit from `PhotoRestorerError`.

```python
from photo_restorer import optimize_image
from photo_restorer.exceptions import PhotoRestorerError

try:
    payload = optimize_image("examples/photo.jpg")
except PhotoRestorerError as exc:
    print(f"Restoration failed: {exc}")
```

See [docs/errors.md](docs/errors.md) for the complete exception hierarchy and handling guidance.

## Additional docs

- [Configuration](docs/configuration.md)
- [Errors](docs/errors.md)
- [Providers](docs/providers.md)

## Contributing

Development workflow, editable installs, linting, testing, and release steps live in [CONTRIBUTING.md](CONTRIBUTING.md).
