Struct Image 

pub struct Image<B: Backend> {
    pub tensor: Tensor<B, 3>,
}

Represents an image represented by a 3D Burn Tensor of shape [C, H, W] (Channels, Height, Width). The pixel values are floats, normally scaled to [0.0, 1.0].

Fields

tensor: Tensor<B, 3>

The underlying 3D tensor of shape [C, H, W].

Implementations

impl<B: Backend> Image<B>

Color space conversion utilities for images.

pub fn rgb_to_hsv(&self) -> Result<Self>

Converts an RGB image to HSV (Hue, Saturation, Value) color space. Input must be a 3-channel image with values in [0, 1]. Returns a 3-channel image where H is in [0, 360]/360 (normalized to [0, 1]), S is in [0, 1], and V is in [0, 1].

pub fn hsv_to_rgb(&self) -> Result<Self>

Converts an HSV image to RGB color space. Input must be a 3-channel image where H is in [0, 1] (normalized from 360), S is in [0, 1], and V is in [0, 1].

pub fn rgb_to_hls(&self) -> Result<Self>

Converts an RGB image to HLS (Hue, Lightness, Saturation) color space. H is normalized to [0, 1] (from 360 degrees), L and S are in [0, 1].

pub fn hls_to_rgb(&self) -> Result<Self>

Converts an HLS image to RGB color space.

pub fn split_channels(&self) -> Result<Vec<Self>>

Splits a multi-channel image into individual single-channel images.

pub fn merge_channels(channels: &[Image<B>]) -> Result<Self>

Merges single-channel images into a multi-channel image.

pub fn rgb_to_xyz(&self) -> Result<Self>

Converts RGB to CIE XYZ color space. Uses sRGB D65 illuminant matrix.

pub fn xyz_to_rgb(&self) -> Result<Self>

Converts CIE XYZ to RGB color space.

pub fn rgb_to_lab(&self) -> Result<Self>

Converts RGB to CIE Lab* color space. Pipeline: RGB -> XYZ -> Lab* (D65 white point).

pub fn lab_to_rgb(&self) -> Result<Self>

Converts CIE Lab* to RGB color space.

pub fn rgb_to_yuv(&self) -> Result<Self>

Converts RGB to YUV (BT.601) color space.

pub fn yuv_to_rgb(&self) -> Result<Self>

Converts YUV (BT.601) to RGB color space.

pub fn rgb_to_ycrcb(&self) -> Result<Self>

Converts RGB to YCrCb (BT.601) color space.

pub fn rgb_to_cmyk(&self) -> Result<Self>

Converts an RGB image to CMYK (Cyan, Magenta, Yellow, Key/Black) color space. Input must be a 3-channel image with values in [0, 1]. Returns a 4-channel image with values in [0, 1].

pub fn cmyk_to_rgb(&self) -> Result<Self>

Converts a CMYK image to RGB color space. Input must be a 4-channel image with values in [0, 1]. Returns a 3-channel RGB image with values in [0, 1].

pub fn rgb_to_hsl(&self) -> Result<Self>

Converts an RGB image to HSL (Hue, Saturation, Lightness) color space. Input must be a 3-channel image with values in [0, 1]. H is normalized to [0, 1] (from 360 degrees), S and L are in [0, 1].

pub fn hsl_to_rgb(&self) -> Result<Self>

Converts an HSL image to RGB color space. Input must be a 3-channel image where H is in [0, 1] (from 360 degrees), S and L are in [0, 1]. Returns a 3-channel RGB image with values in [0, 1].

pub fn ycrcb_to_rgb(&self) -> Result<Self>

Converts YCrCb to RGB color space.

impl<B: Backend> Image<B>

pub fn find_contours(&self) -> Result<Vec<Contour>>

Scans a binary image (grayscale, thresholded) to find contours (connected components). Uses a basic boundary-following algorithm to find contiguous shapes.

pub fn find_contours_with_hierarchy( &self, mode: RetrievalMode, ) -> Result<(Vec<Vec<Point<usize>>>, Vec<[i32; 4]>)>

Finds contours in a binary image with hierarchy information.

Returns a tuple of (contours, hierarchy) where each hierarchy entry is [next, prev, child, parent] using -1 as a sentinel for “none”. The hierarchy encodes the nesting relationship between external contours and holes.

impl<B: Backend> Image<B>

pub fn add(&self, other: &Self) -> Result<Self>

Computes the element-wise sum of two images.

pub fn subtract(&self, other: &Self) -> Result<Self>

Computes the element-wise difference of two images.

pub fn multiply(&self, other: &Self) -> Result<Self>

Computes the element-wise multiplication of two images.

pub fn divide(&self, other: &Self) -> Result<Self>

Computes the element-wise division of two images.

pub fn absdiff(&self, other: &Self) -> Result<Self>

Computes the absolute difference between two images.

pub fn bitwise_and(&self, other: &Self) -> Result<Self>

Computes bitwise AND of two images at pixel/byte level (0..255).

pub fn bitwise_or(&self, other: &Self) -> Result<Self>

Computes bitwise OR of two images.

pub fn bitwise_xor(&self, other: &Self) -> Result<Self>

Computes bitwise XOR of two images.

pub fn bitwise_not(&self) -> Result<Self>

Computes bitwise NOT of the image.

pub fn mean(&self) -> Result<Vec<f64>>

Returns the average value of all elements in the image.

pub fn mean_std_dev(&self) -> Result<(Vec<f64>, Vec<f64>)>

Computes the mean and standard deviation of image elements channel-wise.

pub fn min_max_loc(&self) -> Result<(f64, f64, Point<usize>, Point<usize>)>

Finds global minimum and maximum values and their coordinate locations in a single-channel image.

pub fn count_non_zero(&self) -> Result<usize>

Counts non-zero pixels (value > 0.0).

pub fn in_range(&self, low: &[f32], high: &[f32]) -> Result<Self>

Produces a binary mask where pixels within the range [low, high] are set to 1.0. For multi-channel images, all channels must be in range for the pixel to be marked.

pub fn normalize(&self, min_val: f32, max_val: f32) -> Result<Self>

Normalizes the image to the given range [min_val, max_val].

impl<B: Backend> Image<B>

pub fn draw_line( self, p1: Point<usize>, p2: Point<usize>, color: Scalar, ) -> Result<Self>

Draws a line from p1 to p2 on the image. This operates on CPU by reading tensor, rasterizing, and uploading.

pub fn draw_rectangle( self, rect: Rect<usize>, color: Scalar, thickness: i32, ) -> Result<Self>

Draws a rectangle on the image. If thickness < 0, the rectangle is filled.

pub fn draw_circle( self, center: Point<usize>, radius: usize, color: Scalar, thickness: i32, ) -> Result<Self>

Draws a circle on the image. If thickness < 0, the circle is filled.

pub fn draw_text( self, text: &str, org: Point<usize>, scale: usize, color: Scalar, ) -> Result<Self>

Draws a text label on the image using the built-in 5x7 font.

pub fn draw_ellipse( self, center: Point<usize>, axes: (usize, usize), angle: f32, start_angle: f32, end_angle: f32, color: Scalar, thickness: i32, ) -> Result<Self>

Draws an ellipse on the image. center is the center of the ellipse, axes is (semi_major, semi_minor). angle is the rotation angle in degrees. start_angle and end_angle in degrees. If thickness < 0, the ellipse is filled.

pub fn draw_polyline( self, points: &[Point<usize>], color: Scalar, _thickness: i32, ) -> Result<Self>

Draws a polyline (connected line segments) on the image.

pub fn fill_poly(self, points: &[Point<usize>], color: Scalar) -> Result<Self>

Draws a filled polygon on the image using scanline fill.

pub fn draw_arrowed_line( self, p1: Point<usize>, p2: Point<usize>, color: Scalar, _thickness: i32, tip_length: f32, ) -> Result<Self>

Draws an arrowed line from p1 to p2 with an arrowhead.

pub fn draw_marker( self, center: Point<usize>, color: Scalar, marker_type: MarkerType, marker_size: usize, ) -> Result<Self>

Draws a marker symbol at a point.

impl<B: Backend> Image<B>

pub fn scharr(&self) -> Result<Self>

Applies Scharr operator to find horizontal and vertical gradients.

pub fn laplacian(&self) -> Result<Self>

Computes the Laplacian of an image.

impl<B: Backend> Image<B>

pub fn sobel(&self) -> Result<Self>

Applies Sobel edge detection to compute horizontal, vertical gradients, and magnitude. Returns the gradient magnitude image.

pub fn canny(&self, low_threshold: f32, high_threshold: f32) -> Result<Self>

Performs Canny edge detection. Steps: Grayscale -> Gaussian Blur -> Sobel Gradients -> Non-Maximum Suppression -> Hysteresis Thresholding.

pub fn hough_lines_p( &self, rho: f32, theta: f32, threshold: u32, min_line_length: u32, max_line_gap: u32, ) -> Result<Vec<LineSegment>>

Probabilistic Hough Line Transform (HoughLinesP). Detects line segments in a binary edge image. Returns a vector of line segments as ((x1,y1), (x2,y2)).

pub fn hough_circles( &self, dp: f32, min_dist: f32, param1: f32, param2: f32, min_radius: usize, max_radius: usize, ) -> Result<Vec<(usize, usize, usize)>>

Hough Circle Transform (HoughCircles) using gradient information. Detects circles in a grayscale image. Returns circles as (center_x, center_y, radius).

impl<B: Backend> Image<B>

pub fn bilateral_filter( &self, d: isize, sigma_color: f64, sigma_space: f64, ) -> Result<Self>

Applies a bilateral filter to smooth the image while preserving sharp edges.

pub fn sep_filter_2d(&self, kernel_x: &[f32], kernel_y: &[f32]) -> Result<Self>

Performs separable 2D convolution: first filtering horizontally with kernel_x, then filtering vertically with kernel_y.

impl<B: Backend> Image<B>

pub fn box_blur(self, kernel_size: usize) -> Result<Self>

Applies a box filter to blur the image with the specified kernel size.

pub fn gaussian_blur(self, kernel_size: usize, sigma: f64) -> Result<Self>

Applies a Gaussian blur filter to the image.

pub fn median_blur(self, kernel_size: usize) -> Result<Self>

Applies a median filter to reduce salt-and-pepper noise.

pub fn distance_transform(&self) -> Result<Self>

Computes the distance transform of a binary/grayscale image. Each pixel’s value becomes its Euclidean distance to the nearest zero pixel. Uses the Meijster algorithm (two-pass) for O(n) exact Euclidean distance transform.

pub fn filter2d( &self, kernel: &[&[f32]], anchor: Option<(isize, isize)>, delta: f32, ) -> Result<Self>

Applies an arbitrary 2D convolution kernel to the image. kernel is a 2D slice of shape [kh][kw]. Output is computed via valid convolution. anchor specifies the center of the kernel; if None, the center is (kw/2, kh/2). delta is added to each result pixel, and border controls out-of-bounds handling.

pub fn add_weighted( &self, other: &Self, alpha: f32, beta: f32, gamma: f32, ) -> Result<Self>

Computes weighted sum of two images: dst = src1 * alpha + src2 * beta + gamma.

pub fn convert_scale_abs(&self, scale: f32, shift: f32) -> Result<Self>

Computes dst = src * scale + shift, then optionally converts to abs.

pub fn copy_to(&self, dst: &mut Self, mask: Option<&Self>) -> Result<()>

Copies source image to destination within a masked region. Where mask is nonzero, dst = src; otherwise dst is unchanged.

pub fn laplacian_of_gaussian(&self, sigma: f32) -> Result<Self>

Computes the Laplacian of Gaussian (LoG) filter response. Applies Gaussian smoothing then Laplacian operator to detect edges/blobs. sigma controls the scale of the Gaussian kernel.

impl<B: Backend> Image<B>

pub fn calc_hist(&self) -> Result<Vec<Vec<u32>>>

Computes the 256-bin histogram for each channel. Returns a vector of vectors (one per channel), each containing 256 counts.

pub fn equalize_hist(&self) -> Result<Self>

Performs histogram equalization on a grayscale image to enhance contrast.

pub fn equalize_hist_color(&self) -> Result<Self>

Performs histogram equalization on a color image by converting to YCrCb, equalizing the Y channel, and converting back.

pub fn clahe(&self, clip_limit: f32, grid_size: usize) -> Result<Self>

Contrast Limited Adaptive Histogram Equalization (CLAHE). Divides the image into grid_size x grid_size tiles and applies histogram equalization to each tile independently with clip limit.

pub fn apply_lut(&self, lut: &[f32; 256]) -> Result<Self>

Applies a lookup table (LUT) to map pixel values. lut must have 256 entries mapping each possible pixel value (0..255) to a new value.

pub fn compare_hist(hist_a: &[f32], hist_b: &[f32], method: &str) -> Result<f64>

Compares two histograms using the specified method. Both histograms must have the same length.

pub fn compare_hist_color( hist_a: &[Vec<f32>], hist_b: &[Vec<f32>], method: &str, ) -> Result<Vec<f64>>

Compares two color histograms using the specified method. Returns per-channel comparison results.

pub fn calc_hist_2d( &self, channel_x: usize, channel_y: usize, bins: usize, ) -> Result<Tensor<B, 2>>

Computes a 2D histogram over two channels of a multi-channel image.

channel_x and channel_y select which channels to histogram (0-indexed). The result is a 2D tensor of shape [bins, bins] with counts normalized so that the maximum bin value equals 1.0.

pub fn equalize_hist_adaptive( &self, clip_limit: f32, grid_size: usize, ) -> Result<Self>

Adaptive histogram equalization (non-CLAHE version).

Divides the image into grid_size x grid_size tiles, equalizes each tile, and blends neighboring tiles using bilinear interpolation to avoid artifacts at tile boundaries.

impl<B: Backend> Image<B>

pub fn transpose(&self) -> Result<Self>

Transposes the image (swaps height and width).

pub fn warp_affine( &self, m: [[f64; 3]; 2], new_width: usize, new_height: usize, ) -> Result<Self>

Warps the image using a 2x3 affine transformation matrix.

pub fn warp_perspective( &self, m: [[f64; 3]; 3], new_width: usize, new_height: usize, ) -> Result<Self>

Warps the image using a 3x3 homography / perspective transformation matrix.

pub fn remap(&self, map_x: &Tensor<B, 2>, map_y: &Tensor<B, 2>) -> Result<Self>

Remaps pixel positions using horizontal and vertical coordinates maps.

pub fn undistort( &self, camera_matrix: &Tensor<B, 2>, dist_coeffs: &[f32], ) -> Result<Self>

Undistorts an image using a camera intrinsic matrix and distortion coefficients.

Supports up to 5 radial distortion coefficients (k1..k5) and 2 tangential distortion coefficients (p1, p2) following the Brown-Conrady model.

Arguments

• camera_matrix - 3x3 camera intrinsic matrix as a 2D tensor. Expected layout: [[fx, 0, cx], [0, fy, cy], [0, 0, 1]].
• dist_coeffs - Distortion coefficients [k1, k2, p1, p2, k3]. Any trailing values beyond the 5th element are ignored.

pub fn pyr_down(&self) -> Result<Self>

Downsample one level of the Gaussian pyramid.

The image is first convolved with a 5x5 Gaussian kernel (sigma = 1.0) and then every other row and column are discarded, halving both spatial dimensions while keeping the channel count unchanged.

pub fn pyr_up(&self) -> Result<Self>

Upsample one level of the Gaussian pyramid.

Inserts a zero row/column between every pair of existing rows/columns, convolves with the same 5x5 Gaussian kernel, and scales by 4 to compensate for the energy lost by the zero-insertion. The output dimensions are 2 * (h - 1) + 1 by 2 * (w - 1) + 1.

impl<B: Backend> Image<B>

pub fn resize(&self, new_width: usize, new_height: usize) -> Result<Self>

Resizes the image to the specified width and height using nearest-neighbor interpolation. This runs fully in parallel on the GPU/CPU backend using Burn’s tensor indexing.

pub fn crop( &self, x: usize, y: usize, width: usize, height: usize, ) -> Result<Self>

Crops a rectangular region from the image.

pub fn flip(&self, horizontal: bool, vertical: bool) -> Result<Self>

Flips the image.

• horizontal: Flip along the width dimension.
• vertical: Flip along the height dimension.

pub fn rotate(&self, angle_degrees: u32) -> Result<Self>

Rotates the image by 90, 180, or 270 degrees clockwise.

pub fn grayscale(&self) -> Result<Self>

Converts the image to grayscale using standard ITU-R BT.601 luma weights: Y = 0.299R + 0.587G + 0.114*B

pub fn to_rgb(&self) -> Result<Self>

Converts a single-channel grayscale image to a 3-channel RGB image.

pub fn gaussian_pyramid(&self, levels: usize) -> Result<Vec<Self>>

Builds a Gaussian pyramid with the specified number of levels. Each level is half the size of the previous one, smoothed with Gaussian blur.

pub fn integral_image(&self) -> Result<Image<B>>

Computes the integral image (summed area table) of the grayscale channel. Returns a tensor of shape [1, H+1, W+1] where integral[y][x] is the sum of all pixels in the rectangle (0,0) to (x-1, y-1).

pub fn flood_fill( &self, seed_x: usize, seed_y: usize, fill_value: f32, lo_diff: f32, hi_diff: f32, ) -> Result<Self>

Performs a flood fill operation starting from seed point (x, y). Fills connected pixels with fill_value if they are within lo_diff and hi_diff of the seed pixel value.

impl<B: Backend> Image<B>

pub fn new(tensor: Tensor<B, 3>) -> Self

Creates a new Image from a 3D Burn Tensor.

pub fn open(path: impl AsRef<Path>, device: &B::Device) -> Result<Self>

Loads an image from a file path using the default/given backend device.

pub fn save(&self, path: impl AsRef<Path>) -> Result<()>

Saves the image to a file path.

pub fn shape(&self) -> [usize; 3]

Returns the shape [C, H, W] of the image tensor.

pub fn channels(&self) -> usize

Returns the number of channels (C) of the image.

pub fn height(&self) -> usize

Returns the height (H) of the image.

pub fn width(&self) -> usize

Returns the width (W) of the image.

pub fn template_match( &self, template: &Image<B>, method: TemplateMatchMethod, ) -> Result<Tensor<B, 2>>

Performs template matching and returns the result map.

The template slides over the source image and computes a match score at each position. Returns a 2D tensor of shape [H - th + 1, W - tw + 1] where (th, tw) is the template size.

impl<B: Backend> Image<B>

pub fn morphology_ex(&self, op: MorphOp, kernel_size: usize) -> Result<Self>

Performs advanced morphological transformations.

impl<B: Backend> Image<B>

pub fn dilate_with_kernel(self, kernel: &[&[u8]]) -> Result<Self>

Dilates the image using the given structuring element. kernel is a 2D binary kernel (1 = active, 0 = inactive). For each pixel, it takes the maximum value in the active neighborhood.

pub fn erode_with_kernel(self, kernel: &[&[u8]]) -> Result<Self>

Erodes the image using the given structuring element. kernel is a 2D binary kernel (1 = active, 0 = inactive). For each pixel, it takes the minimum value in the active neighborhood.

pub fn dilate(self, kernel_size: usize) -> Result<Self>

Dilates the image by using a rectangular structuring element of the given size. For each pixel, it takes the maximum value in the neighborhood.

pub fn erode(self, kernel_size: usize) -> Result<Self>

Erodes the image by using a rectangular structuring element of the given size. For each pixel, it takes the minimum value in the neighborhood.

pub fn morph_open(self, kernel_size: usize) -> Result<Self>

Morphological opening (erosion followed by dilation).

pub fn morph_close(self, kernel_size: usize) -> Result<Self>

Morphological closing (dilation followed by erosion).

pub fn hit_or_miss( &self, pattern: &[&[u8]], bg_pattern: &[&[u8]], ) -> Result<Self>

Hit-or-miss transform for binary pattern matching.

pattern defines the foreground (1) pixels to match and bg_pattern defines the background (1 = must-be-background) pixels to match. Pixels in either pattern set to 0 are “don’t care”. Returns a binary image where matched structuring element origins are set to 1.0.

pub fn thin(&self) -> Result<Self>

Zhang-Suen thinning algorithm for binary images.

Iteratively removes boundary pixels that are not essential to connectivity until the skeleton is a single pixel wide. Expects a binary image with foreground = 1.0, background = 0.0.

pub fn skeleton(&self) -> Result<Self>

Morphological skeleton extraction.

Computes the skeleton by iteratively applying morphological opening with a structuring element and subtracting the opened result from the original, then accumulating the residuals. Uses a 3x3 cross kernel.

impl<B: Backend> Image<B>

pub fn add_gaussian_noise(&self, mean: f32, std_dev: f32) -> Result<Self>

Adds Gaussian noise with the given mean and standard deviation.

pub fn add_salt_pepper_noise(&self, amount: f32) -> Result<Self>

Adds salt-and-pepper (impulse) noise with the given probability. amount is the fraction of pixels to corrupt (0.0 to 1.0).

pub fn add_speckle_noise(&self, std_dev: f32) -> Result<Self>

Adds speckle (multiplicative) noise: pixel = pixel + pixel * noise.

impl<B: Backend> Image<B>

pub fn connected_components_with_stats( &self, ) -> Result<(Tensor<B, 2, Int>, Vec<ComponentStats>)>

Identifies connected components in a binary image and calculates statistics for each component. Returns labeled image tensor of shape [H, W] and stats list.

impl<B: Backend> Image<B>

pub fn threshold( &self, thresh: f32, maxval: f32, thresh_type: ThresholdType, ) -> Result<Self>

Applies a fixed-level threshold to each array element.

pub fn threshold_otsu(&self, maxval: f32) -> Result<Self>

Automatically computes a threshold using Otsu’s method and applies binary thresholding.

pub fn threshold_triangle(&self, maxval: f32) -> Result<Self>

Automatically computes a threshold using the Triangle method and applies binary thresholding.

The Triangle method draws a line from the histogram peak to the far end of the histogram, then finds the threshold at the point of maximum distance from the line.

pub fn adaptive_threshold( &self, maxval: f32, method: AdaptiveMethod, block_size: usize, c: f32, ) -> Result<Self>

Applies adaptive thresholding where each pixel gets its own threshold based on a neighborhood statistic.

Trait Implementations

impl<B: Clone + Backend> Clone for Image<B>

fn clone(&self) -> Image<B>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<B: Debug + Backend> Debug for Image<B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.