Metadata-Version: 2.4
Name: py-img-scaler
Version: 0.0.3
Summary: A cross-platform AI upscaling utility to upscale images to a higher resolution.
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.12.0
Requires-Dist: torchvision>=0.21.0
Requires-Dist: opencv-python>=4.10.0
Requires-Dist: tqdm>=4.67.0
Requires-Dist: torchsr>=1.0.4
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# py_img_scaler

A cross-platform, high-performance AI image upscaling tool.

Powered natively by `torchsr` (NinaSR). Supports hardware acceleration across NVIDIA, AMD, and Apple Silicon.

---

## Features

- **Cross-Platform Acceleration:** Native support for NVIDIA CUDA, AMD ROCm (Linux via HIP), and Apple Silicon (macOS via MPS).
- **VRAM Safety:** Smart local tiling/patching with edge-padding blending to prevent Out-of-Memory (OOM) errors on large files.

---

## Prerequisites & Installation

### 1. System Dependencies (Linux)

Ensure Python 3.14 (recommended) and your platform graphics drivers (ROCm/CUDA) are installed.

### 2. Automated Environment Setup

The project contains a platform-aware pipeline configuration tracker. Run the following command to completely clean, generate the virtual environment, and map the correct vendor binaries for your host OS:

```bash
make fresh
```

### Additional Make recipes

    `make venv`      - Create a clean local virtual environment using $(PYTHON_BIN)"
    `make install`   - Upgrade core tooling and install platform-specific packages"
    `make run`       - Execute py_img_scaler main loop"
    `make clean`     - Destroy virtual environment and cached bytecodes"
    `make lint`      - Runs, Black, Ruff, and MyPy checks"
    `make check`     - Only check Black, Ruff, and MyPy checks"
    `make test`      - Run all unit tests inside the tests directory"
---

## Usage Examples

### 1. Command-Line Interface (CLI)

#### CLI Arguments Matrix

| Short Flag | Long Flag | Description | Default / Allowed Values |
| :--- | :--- | :--- | :--- |
| `-s` | `--source` | Path to the directory containing input images. | *Required* |
| `-d` | `--destination` | Path to the directory for upscaled assets. | *Required* |
| `-m` | `--model` | Select target `torchsr` architecture scale depth. | `0`, `1`, or `2` |
| `-W` | `--width` | Force target width bounding configuration. | `1920` |
| `-H` | `--height` | Force target height bounding configuration. | `1080` |

Once your environment is provisioned, invoke the processing pipeline directly using explicit configuration flags:
```bash
    # Basic execution utilizing default resolutions
    py_img_scaler --source ./input_photos --destination ./upscaled_output --model 1

    # Advanced execution overriding targets for a crisp 5K Ultra-Wide frame canvas
    py_img_scaler -s ./wallpapers -d ./output -m 2 -W 5120 -H 2160    
```

### 2. Working with the API Directly

```python
import logging
from py_img_scaler import AIUpscaler, ContextConfiguration, setup_logging

# 1. Attach your application context to the logging stream
setup_logging()
logger = logging.getLogger("py_img_scaler.core")

# 2. Build your configuration layer context matrix
config = ContextConfiguration(
    model="1",            # NinaSR-B1 architecture pipeline footprint
    tile_size=400,        # Slicing chunk constraints to prevent VRAM crashes
    target_width=5120,    # Target 5K Wide aspect dimension matching
    target_height=2160    # Target 2160p height matching
)

try:
    # 3. Instantiate the execution engine (Auto-detects CUDA / MPS / CPU)
    # Will work on all platforms MacOS / Windows / Linux
    engine = AIUpscaler(config=config)
    
    # 4. Ingest and upscale individual physical media frames
    success = engine.upscale_img(
        input_path="./input_photos/raw_horizon.jpg",
        output_path="./output_upscaled_photos/5k_horizon.jpg"
    )
    
    if success:
        logger.info("Image upscale task executed successfully.")

except ValueError as e:
    logger.error(f"Configuration boundary violation detected: {e}")
except Exception as e:
    logger.exception(f"Engine processing crash: {e}")
```

## License

- This project is open-source software licensed under the **GNU General Public License v3.0 (GPLv3)**.

### Key Terms & Copyleft Requirements:

- See the accompanying `LICENSE` file at the root of this repository for the full legal text.
