metalgrow

AI-powered image upscaler accelerated on Apple Metal (MPS).

metalgrow runs super-resolution on Apple Silicon GPUs through PyTorch's MPS backend, with graceful fallbacks to CUDA and CPU. It ships with a bicubic baseline so the pipeline is runnable end-to-end, and exposes a clean seam for plugging in a learned backbone (Real-ESRGAN, SwinIR, etc.).

Table of contents

• Features
• Requirements
• Install
• Usage
• Project layout
• Roadmap
• Contributing
• License

Features

• 🍎 Apple Metal first — PyTorch MPS backend, zero config on Apple Silicon
• 🔁 Portable — automatic fallback to CUDA / CPU when MPS isn't available
• 🧩 Pluggable backbones — bicubic, Real-ESRGAN (x2/x4), SwinIR (x2/x4)
• 🧱 Tiled inference — process arbitrarily large images with feathered overlap blending
• 📂 Batch mode — upscale whole directories or globs with a progress bar
• 📦 Model registry — metalgrow models manages cached weights with sha256 verification
• 🧪 Tested — pytest suite covering the CPU baseline, tiling, batch mode, and registry

Requirements

• Python 3.11+
• macOS with Apple Silicon for MPS acceleration (optional — CPU/CUDA also work)

Install

git clone https://github.com/joaodotwork/metalgrow.git
cd metalgrow
uv venv && source .venv/bin/activate
uv pip install -e .

Or with plain pip:

python -m venv .venv && source .venv/bin/activate
pip install -e .

Usage

CLI

Single file:

metalgrow info
metalgrow upscale input.jpg out.png --scale 2
metalgrow upscale input.jpg out.png --scale 4 --device mps --backbone realesrgan-x4

Whole directory or glob (writes to a target directory, mirroring filenames):

metalgrow upscale ./photos ./photos-upscaled --scale 2 --backbone realesrgan-x2
metalgrow upscale "./photos/*.png" ./out --scale 2 --skip-existing

Manage cached model weights

metalgrow models list
metalgrow models download realesrgan-x4
metalgrow models rm realesrgan-x4

Weights cache to ~/.cache/metalgrow/ by default; override with the METALGROW_CACHE_DIR env var. Every download is sha256-verified.

See docs/models.md for a quality / speed / memory comparison (with benchmark numbers) and guidance on which backbone to pick, or docs/usage.md for the full CLI / library reference.

Library

from PIL import Image
from metalgrow import Upscaler

upscaler = Upscaler(backbone="realesrgan-x2", device="auto")  # auto | mps | cuda | cpu
result = upscaler.upscale(
    Image.open("input.jpg").convert("RGB"),
    scale=2.0,
    tile=256,        # optional — backbone has sensible defaults
    tile_pad=16,
)
result.save("out.png")

Project layout

src/metalgrow/
  device.py            # device auto-selection (MPS → CUDA → CPU)
  upscaler.py          # Upscaler class + tiled inference with overlap blending
  batch.py             # directory / glob batch mode
  weights.py           # weight registry, sha256 verification, cache management
  cli.py               # typer CLI (upscale, info, models)
  backbones/           # bicubic, realesrgan, swinir; plugin registry
tests/
docs/
  usage.md             # CLI recipes, library API, env vars, pitfalls
  models.md            # backbone comparison, benchmark snapshot, tiling
  benchmarks.md        # full (device × backbone × scale) tables
  architecture.md      # module layout, data flow, extension points

Roadmap

• Integrate a learned SR backbone (Real-ESRGAN default)
• Tiled inference for large images
• Batch / directory mode
• Model registry + weight download
• Second backbone family (SwinIR)
• GitHub Actions CI (lint + test on macOS + Linux)
• Benchmarks: MPS vs CPU (CUDA pending GPU runner)
• v0.1.0 release

Contributing

Issues and PRs are welcome. Please run ruff and pytest before opening a PR.

License

MIT — see LICENSE.

_{Made with 🔩 on Apple Silicon.}