Scalerack

Scalerack is a Python image resizing, resampling, upscaling, downscaling, and pixel-art scaling library with a CLI. It offers many image scaling algorithms through one unified interface, supports NumPy arrays and Pillow images, and preserves the input format on output. Included methods range from classical filters such as nearest, box, bilinear, bicubic, Mitchell, Catmull-Rom, Lanczos, Magic Kernel Sharp, and EWA/Jinc to gamma-correct resampling, edge-aware pixel-art scalers such as Scale2x/3x/4x, hq2x/hq3x/hq4x, xBRZ, super-xBR, EASU/RCAS, depixelization, vectorizing, Seam Carving, and perceptual downscaling with L0 Gradient Minimization.

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

Install

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

Install with uv

uv tool install "scalerack[cli]"              # install the CLI as a user tool
uvx --from "scalerack[cli]" scalerack list    # run once without installing

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. Named methods link to their original work where available.

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)
channel_median
vector_median

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
eagle2x Eagle
eagle3x Eagle 3x (community 3x extension of Eagle)
sai2x 2xSaI (Derek "Kreed" Liauw Kie Fa, 1999)
supereagle SuperEagle (Derek "Kreed" Liauw Kie Fa, 1999)
super2xsai Super 2xSaI (Derek "Kreed" Liauw Kie Fa, 1999)
hq2x hq2x (Maxim Stepin, 2003)
hq3x hq3x (Maxim Stepin, 2003)
hq4x hq4x (Maxim Stepin, 2003)
xbrz (2x-6x) xBRZ (Zenju)
superxbr Super xBR (Hyllian, 2015; MIT reference port)

Vectorizing scalers

Vectorizing scalers reconstruct smooth resolution-independent region outlines before rasterizing at the target size, so they support arbitrary (non-integer) factors.

Algorithm	Photo reconstruction	Sprite upscale
Original
depixelize Depixelizing Pixel Art

Gallery sources: Dietmar Rabich's Münster market (CC BY-SA 4.0), Andrew Pons's macaw (CC0 1.0), and LucasVB's Pixelart TV (CC BY-SA 3.0), and the pixel-art scaling comparison, 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
uv run python scripts/generate_docs.py      # regenerate docs/index.md

cd docs
bundle config set path vendor/bundle && bundle install
bundle exec jekyll serve --source . --destination _site # --host 127.0.0.1 --port 4000

License

Scalerack's current source tree is licensed under the Mozilla Public License 2.0.

The implementations are best-effort expressions based on the cited public descriptions, specifications, and papers, with credit to original authors and work wherever possible. Common technical elements such as kernels, coefficients, thresholds, and lookup tables may also appear in other implementations, including implementations available under different licenses; MPL-2.0 applies to the contributions and rights Scalerack's contributors can grant.