Scalerack

Python image resizing, resampling, downscaling, and pixel-art upscaling for NumPy arrays and Pillow images.

Install

pip install scalerack
pip install scalerack[cli]
pip install scalerack[all]

Usage

import scalerack

big = scalerack.mitchell(image, factor=2.5)
thumb = scalerack.box(photo, width=320)
sprite = scalerack.scale3x(pil_sprite)
out = scalerack.resize("lanczos", image, factor=2)

Algorithms

bicubic

Scale with the classic Keys bicubic kernel.

Sharper than bilinear with mild overshoot; the general-purpose default when Lanczos rings too much.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• a (float, default -0.5): Keys sharpness coefficient (-0.5 standard; -0.75 sharper, more halo-prone).

bilinear

Scale with linear interpolation over the triangle kernel.

A fast, artifact-light baseline; visibly softer than the cubic and sinc families.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

box

Scale by averaging each output pixel’s exact source footprint.

The best-behaved choice for downscaling (area interpolation); upscaling degenerates to nearest-neighbor blocks.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

catmull_rom

Scale with the Catmull-Rom interpolating spline.

Sharper than Mitchell; a good pick when extra acutance is worth a little more ringing.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

channel_median

Downscale with a coverage-weighted median computed per channel.

Each output channel is independently reduced to the median of its exact source footprint. This robustly rejects isolated channel outliers, but can construct a color vector that did not occur in the source image.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

content_adaptive_downscale

Downscale with detail-preserving content-adaptive kernels (Kopf et al. 2013).

Each output pixel is a bilateral Gaussian kernel in joint space/color, fit by EM. Kernels start color-crisp; the locality and staircase constraints selectively smooth misbehaving kernels by raising their color variance. For the paper’s pixel-art mode pass staircase_constraint=False. Sharpness accumulates with iterations; the max_iter default is calibrated to reproduce the sharpness of the paper’s published results (running to full convergence over-sharpens). Pixel art converges early on its own.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• staircase_constraint (bool, default True):
• locality_constraint (bool, default True):
• spatial_constraints (bool, default True):
• variance_constraints (bool, default True):
• max_iter (int, default 30):
• color_sigma (float, default 0.0001):
• tol (float, default 0.0005):
• strict_pseudocode_init (bool, default False):
• locality_threshold (float | None, default None):
• edge_strength_threshold (float | None, default None):
• variance_bounds (tuple, default (0.05, 0.1)):

depixelize

Vectorize pixel art into smooth outlines (Kopf-Lischinski 2011) at any target size.

Intended for hard-edged, limited-palette pixel art at enlarging factors; factors at or below 1 are accepted but produce odd-looking results. The paper’s optional harmonic-map cell relaxation is omitted.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• iterations (int, default 2): Curve-relaxation sweeps; higher values smooth staircases more aggressively at the cost of drifting from the source shapes, 0 disables.
• supersample (int, default 2): Antialiasing oversampling factor per output axis; higher values give softer edges and cost proportionally more time and memory.

eagle2x

Enlarge pixel art exactly 2x with the classic Eagle corner-rounding rules.

eagle3x

Enlarge pixel art exactly 3x with the community Eagle3x extension of the Eagle rules.

fsr

Upscale with AMD FSR 1: EASU edge-adaptive upsampling plus RCAS sharpening.

Designed for continuous-tone content; AMD’s published quality presets span factors of about 1.3x to 2x per axis (larger factors work but soften). Upscaling only; a factor of exactly 1 applies pure RCAS sharpening.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• sharpness (float | None, default 0.2): RCAS strength in stops of attenuation: 0.0 is maximum sharpening and each additional stop halves the effect; None disables the pass entirely (EASU-only output).

hq2x

Enlarge pixel art exactly 2x with Maxim Stepin’s hq2x pattern interpolation.

hq3x

Enlarge pixel art exactly 3x with Maxim Stepin’s hq3x pattern interpolation.

hq4x

Enlarge pixel art exactly 4x with Maxim Stepin’s hq4x pattern interpolation.

lanczos

Scale with a Lanczos windowed-sinc kernel.

The high-detail standard for photographic content; may ring at hard edges.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• taps (int, default 3): Number of sinc lobes; more is sharper, slower, and more ring-prone.

magic_kernel_sharp

Scale with Costella’s Magic Kernel Sharp.

A crisp modern alternative to plain cubic kernels.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• version (int, default 2021): 2013 (slightly sharpening, cheaper) or 2021 (spectrally flatter).

mitchell

Scale with the Mitchell-Netravali BC-spline.

The safe offline default balancing blur, anisotropy, and ringing.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• b (float, default 0.3333333333333333): BC-spline B parameter.
• c (float, default 0.3333333333333333): BC-spline C parameter.

nearest

Scale by copying the nearest source pixel.

Preserves exact pixel values; the right choice for masks, label maps, and deliberately blocky display of low-resolution art.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

sai2x

Enlarge pixel art exactly 2x with Kreed’s 2xSaI edge-aware interpolation.

scale2x

Enlarge pixel art exactly 2x with the Scale2x (EPX) neighborhood rules.

scale3x

Enlarge pixel art exactly 3x with the Scale3x neighborhood rules.

scale4x

Enlarge pixel art exactly 4x by applying Scale2x twice.

super2xsai

Enlarge pixel art exactly 2x with Kreed’s Super 2xSaI, the family’s strongest blur.

supereagle

Enlarge pixel art exactly 2x with Kreed’s SuperEagle edge detection and blending.

superxbr

Enlarge pixel art exactly 2x with Hyllian’s Super xBR hybrid interpolation.

vector_median

Downscale by selecting the vector median of each source footprint.

The vector median is the source pixel whose color vector has the smallest coverage-weighted sum of Euclidean distances to the other pixels in an output pixel’s exact source footprint. Unlike channel-wise medians, it always returns a color that occurred in the source image.

• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.

xbrz

Enlarge pixel art 2x-6x with Zenju’s xBRZ edge-slope detection and blending.

API

resize

Scale an image with the algorithm named by method.

Translates the request into whatever sizing the algorithm exposes: a factor becomes width/height (and vice versa) where needed.

• method (str): Algorithm name (a key of ALGORITHMS).
• factor (float | None, default None): Scale factor.
• width (int | None, default None): Target output width.
• height (int | None, default None): Target output height.
• **opts (object): Algorithm-specific options.

Exceptions

• ScalerackError - Base class for every error raised by scalerack.
• UnknownAlgorithmError - Raised when an algorithm name is not a known scalerack algorithm.
• InvalidFactorError - Raised when a sizing request violates the algorithm’s constraints.
• UnsupportedImageError - Raised when an input image has an unsupported type, shape, mode, or dtype.