Scalerack

Many image up- and downscaling algorithms behind one unified interface: classical kernel resampling, edge-aware reconstruction for crisp low-resolution art, vectorizing and perceptual downscaling approaches. Whatever goes in comes back out in the same format:

• NumPy arrays: (H, W), (H, W, 3), (H, W, 4) in uint8, float32, float64
• Pillow images: L, RGB, RGBA

Install

PyPI package

pip install scalerack          # core resampler
pip install scalerack[cli]     # command line interface
pip install scalerack[all]     # everything

Usage

import scalerack

big = scalerack.mitchell(image, factor=2.5)
thumb = scalerack.box(photo, width=320)  # height inferred
crisp = scalerack.magic_kernel_sharp(image, width=100, height=100, version=2021)
sprite = scalerack.scale3x(pil_sprite)  # fixed 3x

# generic dispatch
out = scalerack.resize("catmull_rom", image, 2)

# all algorithm names
print(*scalerack.ALGORITHMS)

Invalid parameters (unsupported factor, wrong input type, missing extra) raise exceptions.

CLI (with the cli extra):

scalerack scale input.png output.png --method lanczos --factor 2
scalerack scale photo.png thumb.png --method box --width 320   # height inferred from aspect ratio
scalerack scale sprite.png big.png --method scale4x --factor 4
scalerack list

Algorithms

Check the code documentation for algorithm details.

Classical resamplers

Downscale previews are generated as 4x reductions (0.25x output size). Photo reconstruction previews first degrade the source with Lanczos at 0.25x, then upscale the degraded image back toward the original size. Sprite downscale previews reduce the pixel-art source directly, and sprite upscale previews enlarge the pixel-art source directly.

Algorithm	Photo downscale	Sprite downscale	Photo reconstruction	Sprite upscale
Original
nearest
box
bilinear
bicubic Cubic convolution interpolation
mitchell Mitchell-Netravali filter
catmull_rom Catmull-Rom spline
lanczos Lanczos resampling
magic_kernel_sharp Magic Kernel Sharp

Downscalers

Downscaling algorithm usually focus on preserving detail.

Algorithm	Photo downscale	Sprite downscale
content_adaptive_downscale Content-Adaptive Image Downscaling (Does not fully reproduce paper results)

Pixel-art scalers

Some algorithms may output different results depending on the fixed scale factor.

Algorithm	Photo reconstruction	Sprite upscale
Original
scale2x Scale2x / EPX
scale3x Scale3x / EPX
scale4x Scale4x / EPX

Sources: Münster market, macaw, and Pixelart TV, via Wikimedia Commons.

Roadmap

Machine-learning upscalers are out of scope.

Development

uv sync --group dev
uv run pre-commit install                   # ruff check + format on commit
uv run pytest                               # smoke suite
uv run mypy src                             # type check
uv run python scripts/generate_previews.py  # regenerate the gallery above

License

MIT. All bundled algorithms are implemented from scratch from their specifications or papers.