Skip to content

pixtreme.transform

transform

Geometric and multi-image layout transforms.

__all__ = ('resize', 'warp_affine', 'stack') module-attribute

resize(frame, *, width=None, height=None, factor=None, interpolation=None)

Resize a Frame geometrically without changing its metadata or colorimetry.

Pass width and height together, or pass factor alone; the modes are mutually exclusive. Factor dimensions use half-up rounding as floor(dim * factor + 0.5). When interpolation is omitted, any shrinking axis selects area and an all-nonshrinking resize selects lanczos4.

Every point-sampled kernel uses pixel-center coordinates src = (dst + 0.5) * (input / output) - 0.5 and replicate edge handling. Input Frame data must be float32; use px.values.cast_dtype or another explicit public value conversion before resizing other storage dtypes. Resize calculates float32 output independently per channel and does not clamp scene values or cubic/Lanczos overshoot. The result is always a new Frame and a new data allocation, including same-size calls.

stack(images, *, direction='vertical', adapt=False)

Concatenate Frames vertically or horizontally into a new Frame.

vertical places inputs from top to bottom and requires a common width; horizontal places them from left to right and requires a common height. With adapt=False, channels, colorspace, gamma, dtype, and that orthogonal dimension must already match.

With adapt=True, the first Frame is the master. Later Frames are first transformed to its channels, colorspace, and gamma when a deterministic equal-set reorder or RGB/YCbCr conversion exists, then resized to its orthogonal dimension with aspect preservation and half-up rounding. Dtype still must match, and multi-input adaptation requires float32. The result always owns new storage, including a single-input call.

warp_affine(frame, matrix, *, inverse=False, width=None, height=None, interpolation=None, border='constant', border_value=None)

Warp a float32 Frame with a declared forward 2x3 affine matrix.

matrix maps input pixel centers to output pixel centers, whose top-left centers are both (0, 0). Destination-driven inverse mapping samples the source at inverse(T) @ (x, y, 1), where T is the forward matrix when inverse=False and its inverse when inverse=True. Pass width and height together for another canvas, or omit both to retain the input dimensions.

interpolation accepts nearest, bilinear, bicubic, b-spline, mitchell, lanczos2, lanczos3, lanczos4, and area. Omission selects area when either effective forward column norm is below one and lanczos4 otherwise. Point kernels have fixed support; area averages the inverse-mapped pixel-cell parallelogram. border accepts mirror, replicate, wrap, and constant. Constant border_value=None means 0.0; explicit finite scene values may be negative or above one.

Resampling is float32 and independent per channel. It does not clamp scene values or specialize alpha and preserves colorspace, gamma, channels, and Frame matrix metadata. The result always owns new C-contiguous GPU storage. This function does not mutate the input Frame, its data or metadata, or the host/device geometry matrix. Convert other storage deliberately with px.values.cast_dtype, px.values.recode_dtype, or px.values.dequantize before calling it.