resample

Documentation

Overview

Package resample resizes RGBA images with a choice of separable filters: nearest-neighbour, bilinear, box/area, bicubic (Catmull-Rom) and Lanczos (a=3). It is the shared resizer the go-gfx consumers — go-images, go-widgets, go-webengine, desktop icon/thumbnail rendering — build on instead of pulling in x/image/draw.

Every mode has a straight variant (Resize) and a premultiplied-alpha variant (ResizePremultiplied). Resizing mixes neighbouring pixels, and mixing straight (non-premultiplied) colour lets a fully transparent pixel's arbitrary colour bleed into the visible edge of a cut-out — a dark or pale fringe. ResizePremultiplied multiplies colour by alpha before filtering and divides it back out afterwards, which removes the fringe; it is what you want whenever the source has transparency. The two coincide on a fully opaque image.

The bicubic and Lanczos modes follow Pillow's convolution resampler: the filter footprint widens with the reduction factor, so they antialias a reduction as well as interpolate an enlargement. They match Pillow to a high PSNR (see docs/perf.md); the premultiplied variants match Pillow's premultiplied-alpha RGBA resize.

Index

• Constants
• Variables
• func Resize(src *raster.Image, w, h int, mode Mode) (*raster.Image, error)
• func ResizePremultiplied(src *raster.Image, w, h int, mode Mode) (*raster.Image, error)
• type Filter
• type Mode

Constants

const HaveSIMD = true

HaveSIMD reports that this build ships the SIMD axpy kernel, so the filtered vertical pass is routed through it. The per-arch CI job validates it against the scalar oracle.

const SIMDName = "SSE2"

SIMDName identifies the vector kernel family for the per-arch test log.

Variables

var ParThreshold = 1 << 14 // 16384 pixels (e.g. 128x128)

ParThreshold is the minimum number of output pixels at which a separable pass fans out across goroutines. Below it the serial path runs. It is a var so tests can force the parallel path on small images.

Functions

func Resize

func Resize(src *raster.Image, w, h int, mode Mode) (*raster.Image, error)

Resize returns src scaled to w by h pixels using the given mode, filtering each channel independently (straight alpha). It returns an error if w or h is not positive, or for an unknown mode.

func ResizePremultiplied

func ResizePremultiplied(src *raster.Image, w, h int, mode Mode) (*raster.Image, error)

ResizePremultiplied is Resize with the colour channels filtered in premultiplied-alpha space, so a transparent pixel's colour does not bleed into the visible edge of a cut-out. On a fully opaque image it is identical to Resize.

Bicubic and Lanczos premultiply in float64 inside the kernel (full precision); Bilinear and Box premultiply in the byte domain around their kernels; Nearest selects whole pixels and never blends, so it is unchanged. It returns an error if w or h is not positive, or for an unknown mode.

Types

type Filter

type Filter struct {
	Support float64
	At      func(x float64) float64
}

A Filter is a separable resampling kernel: Support is the radius of its non-zero region at unit scale, and At evaluates the kernel at a signed distance x (in source pixels) from a sample centre. The bicubic and Lanczos modes are built from the two filters below; a caller does not construct Filters directly.

type Mode

type Mode int

Mode selects the resampling filter.

const (
	// Nearest selects the source pixel nearest each destination pixel. Fast and
	// exact for integer enlargements, but blocky and aliasing.
	Nearest Mode = iota
	// Bilinear linearly interpolates the four nearest source pixels. Smoother
	// than Nearest, but only ever looks at four neighbours, so it aliases a heavy
	// reduction.
	Bilinear
	// Box averages the source region each destination pixel covers, weighting
	// every source pixel by how much of it falls inside — PIL's Image.BOX /
	// OpenCV's INTER_AREA / scikit-image's downscale_local_mean at integer ratios.
	// The plain antialiasing reduction filter; enlarging, it reduces to Nearest.
	Box
	// Bicubic resamples with the Keys cubic (a = -1/2, the Catmull-Rom spline),
	// a smooth four-tap kernel whose footprint widens with the reduction factor:
	// sharper than Bilinear when enlarging and a proper antialiasing low-pass when
	// reducing. Pillow's BICUBIC / x/image/draw's CatmullRom.
	Bicubic
	// Lanczos resamples with the a = 3 windowed-sinc kernel: wider and sharper
	// than Bicubic at more cost, the highest-fidelity mode either direction.
	// Pillow's LANCZOS / x/image/draw's Lanczos.
	Lanczos
)