image

stable

Open, create, transform, and encode raster images using a handle-based API.

use plugin image::{open, new, from_bytes, …}

32 functions Image

/ filter jk navigate Esc clear

Functions (32)

open Open an image file from disk
new Create a blank RGBA image
from_bytes Decode an image from raw bytes
from_rgba_bytes Create an image from raw RGBA pixel data
save Save image to a file
width Get image width in pixels
height Get image height in pixels
dimensions Get width and height as a table
resize Resize to exact dimensions
resize_fit Resize within bounds, preserve aspect ratio
crop Crop a rectangular region
rotate Rotate by 0, 90, 180, or 270 degrees
rotate90 Rotate 90 degrees clockwise
rotate180 Rotate 180 degrees
rotate270 Rotate 270 degrees clockwise
fliph Flip horizontally
flipv Flip vertically
grayscale Convert to grayscale
blur Apply Gaussian blur
sharpen Apply unsharp mask sharpening
brighten Adjust brightness by integer offset
brightness Adjust brightness by float factor
contrast Adjust contrast
invert Invert all pixel colors
hue_rotate Rotate hue by degrees
pixel Read a single pixel's RGBA values
set_pixel Write a single pixel's RGBA values
overlay Composite one image onto another
copy Clone the image into a new handle
to_bytes Export raw RGBA bytes
encode_png Encode image as PNG bytes
encode_jpeg Encode image as JPEG bytes

open(path) → Image

Open an image file from disk

Opens an image file from the filesystem and returns an Image handle. Supports PNG, JPEG, GIF, BMP, ICO, TIFF, and WebP.

use plugin image::{open, save}

let img = open("photo.jpg")
print("Loaded {img.width()}x{img.height()}")

new(width, height) → Image

Create a blank RGBA image

Creates a new blank transparent RGBA image with the given dimensions.

use plugin image::{new}

let canvas = new(800, 600)
canvas.save("blank.png")

from_bytes(bytes) → Image

Decode an image from raw bytes

Decodes an image from a byte array (e.g. from a file read or HTTP response body). Format is auto-detected.

use plugin image::{from_bytes}

let data = std::fs::read("photo.webp")
let img = from_bytes(data)
print(img.width())

from_rgba_bytes(bytes, width, height) → Image

Create an image from raw RGBA pixel data

Creates an image from raw RGBA pixel data. The bytes array must have exactly width * height * 4 bytes.

use plugin image::{from_rgba_bytes, new}

let base = new(2, 2)
let raw = base.to_bytes()
let copy = from_rgba_bytes(raw, 2, 2)
print(copy.width())

save(img, path, format?) → nil

Save image to a file

Saves the image to disk. The format is inferred from the file extension unless you pass an explicit format string ("png", "jpg", "gif", "bmp", "webp", etc.).

use plugin image::{open}

let img = open("input.png")
let resized = img.resize(320, 240)
resized.save("output.jpg", "jpg")

width(img) → int

Get image width in pixels

Returns the image width in pixels.

use plugin image::{open}

let img = open("photo.png")
print(img.width())

height(img) → int

Get image height in pixels

Returns the image height in pixels.

use plugin image::{open}

let img = open("photo.png")
print(img.height())

dimensions(img) → table

Get width and height as a table

Returns {width, height} as a table.

use plugin image::{open}

let img = open("photo.png")
let d = img.dimensions()
print("{d["width"]}x{d["height"]}")

resize(img, width, height, filter?) → Image

Resize to exact dimensions

Resizes the image to exactly the given dimensions. Optional filter: "nearest", "linear", "lanczos3" (default), "catmullrom", "gaussian".

use plugin image::{open}

let img = open("photo.jpg")
let thumb = img.resize(128, 128, "lanczos3")
thumb.save("thumb.jpg")

resize_fit(img, max_width, max_height) → Image

Resize within bounds, preserve aspect ratio

Resizes the image to fit within the given bounds while preserving the aspect ratio. Uses Lanczos3 filter.

use plugin image::{open}

let img = open("large.jpg")
let fitted = img.resize_fit(1920, 1080)
fitted.save("fitted.jpg")

crop(img, x, y, width, height) → Image

Crop a rectangular region

Crops a rectangular region from the image starting at (x, y) with the given size.

use plugin image::{open}

let img = open("screenshot.png")
let region = img.crop(100, 50, 400, 300)
region.save("cropped.png")

rotate(img, degrees) → Image

Rotate by 0, 90, 180, or 270 degrees

Rotates the image by 0, 90, 180, or 270 degrees. Negative values are supported (-90 = 270).

use plugin image::{open}

let img = open("portrait.jpg")
let landscape = img.rotate(90)
landscape.save("landscape.jpg")

rotate90(img) → Image

Rotate 90 degrees clockwise

Rotates the image 90 degrees clockwise.

use plugin image::{open}

let img = open("photo.jpg")
img.rotate90().save("rotated.jpg")

use plugin image::{open}

let img = open("photo.jpg")
img.fliph().save("mirrored.jpg")

flipv(img) → Image

Flip vertically

Flips the image vertically (mirror top-bottom).

grayscale(img) → Image

Convert to grayscale

Converts the image to grayscale.

use plugin image::{open}

let img = open("color.jpg")
img.grayscale().save("gray.jpg")

blur(img, sigma) → Image

Apply Gaussian blur

Applies a Gaussian blur. Higher sigma values produce stronger blur.

use plugin image::{open}

let img = open("sharp.jpg")
img.blur(2.5).save("blurred.jpg")

sharpen(img, sigma?, threshold?) → Image

Apply unsharp mask sharpening

Applies unsharp mask sharpening. Default sigma is 1.5, default threshold is 1.

use plugin image::{open}

let img = open("soft.jpg")
img.sharpen(2.0, 2).save("sharp.jpg")

brighten(img, value) → Image

Adjust brightness by integer offset

Adjusts brightness by an integer offset. Positive values brighten, negative values darken.

use plugin image::{open}

let img = open("dark.jpg")
img.brighten(30).save("brighter.jpg")

brightness(img, factor) → Image

Adjust brightness by float factor

Adjusts brightness by a float factor. 1.0 is unchanged, 1.5 is brighter, 0.5 is darker.

use plugin image::{open}

let img = open("photo.jpg")
img.brightness(1.3).save("bright.jpg")

contrast(img, value) → Image

Adjust contrast

Adjusts contrast by a float value. Positive increases contrast, negative decreases it.

use plugin image::{open}

let img = open("flat.jpg")
img.contrast(15.0).save("contrasty.jpg")

invert(img) → Image

Invert all pixel colors

Inverts all pixel colors (produces a negative image).

use plugin image::{open}

let img = open("photo.jpg")
img.invert().save("negative.jpg")

hue_rotate(img, degrees) → Image

Rotate hue by degrees

Rotates the hue of all pixels by the given number of degrees on the color wheel.

use plugin image::{open}

let img = open("colorful.jpg")
img.hue_rotate(120).save("hue_shifted.jpg")

pixel(img, x, y) → table

Read a single pixel's RGBA values

Reads the RGBA values of a single pixel at (x, y). Returns {r, g, b, a} with values 0–255.

use plugin image::{open}

let img = open("photo.png")
let p = img.pixel(0, 0)
print("R={p["r"]} G={p["g"]} B={p["b"]} A={p["a"]}")

set_pixel(img, x, y, r, g, b, a?) → Image

Write a single pixel's RGBA values

Writes an RGBA pixel at (x, y). Alpha defaults to 255 if omitted. Only works on RGBA8 images (created with new() or from_rgba_bytes()).

use plugin image::{new}

let img = new(10, 10)
let img2 = img.set_pixel(5, 5, 255, 0, 0, 255)
img2.save("dot.png")

overlay(base, overlay_img, x, y) → Image

Composite one image onto another

Composites overlay_img on top of base at position (x, y). Returns the resulting image.

use plugin image::{open}

let bg = open("background.png")
let logo = open("logo.png")
let result = bg.overlay(logo, 10, 10)
result.save("combined.png")

copy(img) → Image

Clone the image into a new handle

Creates a deep copy of the image as a new handle.

use plugin image::{open}

let original = open("photo.jpg")
let backup = original.copy()

to_bytes(img) → bytes

Export raw RGBA bytes

Exports the image as raw RGBA byte data (4 bytes per pixel, row-major order).

use plugin image::{open}

let img = open("photo.png")
let raw = img.to_bytes()
print("Byte count: {raw.len()}")

encode_png(img) → bytes

Encode image as PNG bytes

Encodes the image as a PNG byte array without writing to disk.

use plugin image::{open}

let img = open("photo.jpg")
let png_bytes = img.encode_png()

encode_jpeg(img, quality?) → bytes

Encode image as JPEG bytes

Encodes the image as a JPEG byte array. Quality defaults to 85 (0–100).

use plugin image::{open}

let img = open("photo.png")
let jpeg_bytes = img.encode_jpeg(90)

View source code