thumbnail
stableProvides fast RGBA image manipulation utilities including resizing, cropping, flipping, blurring, brightness adjustment, and color analysis — all operating on raw byte buffers.
use plugin thumbnail::{downscale, average_color, crop_center, …} Functions (12)
- downscale Nearest-neighbor downscale of an RGBA image
- average_color Compute average RGBA color of an image
- crop_center Crop the center region of an image
- aspect_fit Calculate dimensions that fit within a bounding box
- blur_fast Box blur applied N times to approximate Gaussian
- crop Crop an arbitrary rectangular region
- resize_bilinear Bilinear interpolation resize of an RGBA image
- grayscale Convert RGBA image to grayscale using luminance
- flip_horizontal Mirror image left-to-right
- flip_vertical Flip image upside-down
- brightness Multiply RGB channels by a scale factor
- rotate_90_cw Rotate image 90 degrees clockwise
Overview
thumbnail is a dependency-free toolkit for manipulating images that are held in
memory as raw RGBA byte buffers. Every pixel is four contiguous bytes — red,
green, blue, alpha — so an image is simply width * height * 4 bytes plus the two
integer dimensions you pass alongside it. There are no opaque image handles: each
function takes a byte buffer and its dimensions and returns either a new byte
buffer or a small table describing the result. Use it to build thumbnails, crop
and resize for display, apply quick visual effects (blur, grayscale, brightness),
or extract a representative color for placeholders.
The mental model is a pipeline: you start with bytes and dimensions, transform
them with one operation, and feed the output (and any new dimensions) into the
next. Most operations keep the dimensions you give them, but the ones that change
the geometry — aspect_fit and rotate_90_cw — hand back the new width and
height so you always know the size of the buffer you are holding.
Common patterns
Fit an image inside a bounding box while preserving its aspect ratio, then resize:
use plugin thumbnail::{aspect_fit, resize_bilinear}
let dims = aspect_fit(3840, 2160, 800, 600)
let thumb = resize_bilinear(image_bytes, 3840, 2160, dims["width"], dims["height"])
print("thumbnail is {dims["width"]}x{dims["height"]}")
Produce a square, softened preview by cropping the center and blurring it:
use plugin thumbnail::{crop_center, blur_fast}
let square = crop_center(image_bytes, 1280, 720, 720, 720)
let preview = blur_fast(square, 720, 720, 2)
Derive a placeholder color from an image and report it:
use plugin thumbnail::{average_color}
let c = average_color(image_bytes, 800, 600)
print("placeholder rgb({c["r"]}, {c["g"]}, {c["b"]})")
Nearest-neighbor downscale of an RGBA image
Downscales an RGBA image using nearest-neighbor sampling. Faster than bilinear but produces blocky results at large scale differences. The input must be a raw RGBA byte buffer of size src_w * src_h * 4.
use plugin thumbnail::{downscale}
let small = downscale(image_bytes, 1920, 1080, 320, 180)
Combine it with aspect_fit to produce a correctly proportioned tiny preview:
use plugin thumbnail::{aspect_fit, downscale}
let dims = aspect_fit(1920, 1080, 160, 160)
let tiny = downscale(image_bytes, 1920, 1080, dims["width"], dims["height"])
Compute average RGBA color of an image
Computes the average red, green, blue, and alpha values across all pixels, returning a table {r, g, b, a} with integer values 0–255. Useful for generating placeholder colors or palette analysis.
use plugin thumbnail::{average_color}
let color = average_color(image_bytes, 800, 600)
print("Red: {color["r"]}, Green: {color["g"]}")
Sample the dominant color of a blurred copy for a softer placeholder tone:
use plugin thumbnail::{blur_fast, average_color}
let soft = blur_fast(image_bytes, 800, 600, 4)
let tint = average_color(soft, 800, 600)
print("tint alpha: {tint["a"]}")
Crop the center region of an image
Extracts a centered rectangle of new_w x new_h from the image. The crop dimensions must not exceed the source dimensions. Useful for producing square thumbnails from rectangular images.
use plugin thumbnail::{crop_center}
let square = crop_center(image_bytes, 1280, 720, 720, 720)
Calculate dimensions that fit within a bounding box
Calculates the largest dimensions that fit within max_w x max_h while preserving the original aspect ratio. Returns {width, height} as integers. Does not resize pixels — use with resize_bilinear or downscale.
use plugin thumbnail::{aspect_fit, resize_bilinear}
let dims = aspect_fit(3840, 2160, 800, 600)
let resized = resize_bilinear(image_bytes, 3840, 2160, dims["width"], dims["height"])
Box blur applied N times to approximate Gaussian
Applies a 3x3 box blur to the image for the given number of passes. More passes approximate a Gaussian blur. Each pass blurs the result of the previous one, providing a smooth effect at low cost.
use plugin thumbnail::{blur_fast}
let blurred = blur_fast(image_bytes, 640, 480, 3)
Crop an arbitrary rectangular region
Crops a rectangular region starting at (x, y) with dimensions crop_w x crop_h. The region must fall entirely within the source image bounds.
use plugin thumbnail::{crop}
let region = crop(image_bytes, 1920, 1080, 100, 50, 400, 300)
Cut out the top-left quadrant of an image by passing explicit coordinates:
use plugin thumbnail::{crop}
let quadrant = crop(image_bytes, 1024, 768, 0, 0, 512, 384)
Bilinear interpolation resize of an RGBA image
Resizes an RGBA image using bilinear interpolation, which produces smoother results than nearest-neighbor at the cost of slightly more computation. Suitable for generating display-quality thumbnails.
use plugin thumbnail::{resize_bilinear, aspect_fit}
let dims = aspect_fit(4096, 2048, 1024, 512)
let thumb = resize_bilinear(image_bytes, 4096, 2048, dims["width"], dims["height"])
Convert RGBA image to grayscale using luminance
Converts an RGBA image to grayscale using the standard luminance formula (0.299R + 0.587G + 0.114B). Alpha channel is preserved unchanged. Returns a new byte buffer of the same size.
use plugin thumbnail::{grayscale}
let gray = grayscale(image_bytes, 640, 480)
Chain it with brightness to create a faded, dimmed disabled-state thumbnail:
use plugin thumbnail::{grayscale, brightness}
let gray = grayscale(image_bytes, 640, 480)
let faded = brightness(gray, 640, 480, 0.6)
Mirror image left-to-right
Mirrors the image along its vertical axis (left becomes right). Operates on raw RGBA pixels. Useful for generating mirrored thumbnails or sprite variants.
use plugin thumbnail::{flip_horizontal}
let mirrored = flip_horizontal(image_bytes, 512, 512)
Flip image upside-down
Flips the image upside down by reversing the row order. Returns a new RGBA byte buffer with the same dimensions.
use plugin thumbnail::{flip_vertical}
let flipped = flip_vertical(image_bytes, 512, 256)
Multiply RGB channels by a scale factor
Multiplies each RGB channel by factor. Values above 1.0 brighten the image; values below 1.0 darken it. Alpha is left unchanged. Output is clamped to the 0–255 range.
use plugin thumbnail::{brightness}
let bright = brightness(image_bytes, 800, 600, 1.5)
let dark = brightness(image_bytes, 800, 600, 0.4)
Rotate image 90 degrees clockwise
Rotates the image 90 degrees clockwise. Because the dimensions swap, the result is returned as a table {bytes, width, height} so you can read the new size.
use plugin thumbnail::{rotate_90_cw}
let result = rotate_90_cw(image_bytes, 1920, 1080)
let rotated_bytes = result["bytes"]
let new_w = result["width"]
let new_h = result["height"]
Feed the rotated buffer and its swapped dimensions straight into another step:
use plugin thumbnail::{rotate_90_cw, resize_bilinear}
let r = rotate_90_cw(image_bytes, 1280, 720)
let small = resize_bilinear(r["bytes"], r["width"], r["height"], 360, 640)