photo-restorer 0.1.1

Local-first Python library for photo restoration, face enhancement, color correction, and perceptual pre-downscaling.

photo-restorer

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

pip install photo-restorer

Checking the version

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 for the full configuration guide.

Quickstart

Optimize a single image

from photo_restorer import optimize_image

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

Optimize multiple local images

from photo_restorer import optimize_images

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

Restore faces only

from photo_restorer import restore_faces

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

Correct colors only

from photo_restorer import correct_colors

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

Apply perceptual pre-downscale only

from photo_restorer import pre_downscale_image

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

Reuse a stateful client

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.

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 for the complete exception hierarchy and handling guidance.

Additional docs

• Configuration
• Errors
• Providers

Contributing

Development workflow, editable installs, linting, testing, and release steps live in CONTRIBUTING.md.