Struct PixelSet 

pub struct PixelSet { /* private fields */ }

A compact, sorted collection of pixels, optimized for fast set-like operations and spatial queries.

Overview

PixelSet is a high-performance container that stores Pixel values in a strictly sorted (y, x) order. This ensures:

• Cache-friendly iteration (pixels are stored linearly in scanline order)
• Fast binary-search membership checks (O(log n) per lookup)
• Efficient merges, intersections, and differences (O(n) with linear scans)
• Minimal memory overhead compared to hash-based or tree-based structures

Usage

use image::DynamicImage;
use pixelset::{Pixel, PixelSet, Color};

let image = DynamicImage::new_rgb8(1, 1);
let mut set = PixelSet::from_image(&image);

Guarantees

Internally, pixel order is always sorted by (y, x).
Methods preserve this sorting parity with the exception of [new], which expects a sanitized sorted list.

Highly optimized for set operations, only struggling with additions or removals of individual pixels.

Implementations

impl PixelSet

pub fn is_empty(&self) -> bool

Returns true if the set contains no pixels.

pub fn has(&self, pixel: Pixel) -> bool

Returns true if the set contains the specified pixel, performing binary search.

Complexity: O(log n).

pub fn is_subset(&self, other: &PixelSet) -> bool

Returns true if every pixel in this set is also present in other.

Complexity: O(n log m).

pub fn len(&self) -> usize

Returns the number of pixels in this set.

pub fn filter(&self, predicate: impl Fn(Pixel) -> bool) -> Self

Returns a new PixelSet containing pixels whose colors in the given image satisfy a predicate.

pub fn filter_color( &self, image: &DynamicImage, predicate: impl Fn(Color) -> bool, ) -> Self

Returns a new PixelSet containing only pixels whose color in the given image exactly matches the specified color.

pub fn select(&self, image: &DynamicImage, query: Color) -> Self

Returns a new PixelSet containing only those pixels whose color in the provided image exactly matches the specified color.

pub fn apply(&self, applier: impl Fn(&mut PixelSet)) -> Self

Returns a modified copy of the PixelSet after applying a user-provided transformation function.

impl PixelSet

pub fn add(&mut self, pixel: Pixel)

Inserts a single new pixel into the set while maintaining sorted order and uniqueness.

Uses binary search to find the insertion point. Worst-case complexity: O(n) due to element shifting.

pub fn discard(&mut self, pixel: Pixel)

Removes a pixel from the set, maintaining sort order.

Uses binary search to locate the pixel. Worst-case complexity: O(n) due to element shifting.

pub fn extend(&self, other: &Self) -> Self

Returns a new PixelSet representing the union of this set and another, with all pixels from both sets are included.

Complexity: O(n + m).

pub fn without(&self, other: &Self) -> Self

Returns a new PixelSet with pixels in this set that are not in other, performing a set difference.

Complexity: O(n + m).

pub fn remove(&mut self, other: &Self)

Removes all pixels that appear in other from this set, modifying the set in-place.

Complexity: O(n + m).

pub fn and(&self, other: &Self) -> Self

Returns a new PixelSet containing only the pixels that appear in both sets, performing a set intersection.

Complexity: O(n + m)

pub fn intersects(&self, other: &Self) -> bool

Returns true if this set shares any pixel with another set.

Complexity: O(n log m).

impl PixelSet

pub fn new(pixels: Vec<Pixel>) -> Self

Creates a new PixelSet from an unsorted list of pixels.

The pixels are sorted into (y, x) order, removing all duplicates, operating in O(n) time with the usage of radix sort.

pub fn new_unchecked(pixels: Vec<Pixel>) -> Self

Constructs a PixelSet from a vector that is already known to be sorted in strictly ascending (y, x) order and contains no duplicates.

This constructor performs no validation. Callers must ensure the input satisfies sorting order and lacks duplicates.

pub fn empty() -> Self

Returns an empty PixelSet.

pub fn from_image(image: &DynamicImage) -> Self

Creates a PixelSet containing a pixel for every coordinate in the given image.

impl PixelSet

pub fn iter(&self) -> Iter<'_, Pixel>

Returns an iterator over immutable references to the pixels in this set.

pub fn iter_mut(&mut self) -> IterMut<'_, Pixel>

Returns an iterator over mutable references to the pixels in this set.

impl PixelSet

pub fn recolor<T: Into<Color>>( &self, image: &mut DynamicImage, applier: impl Fn(Pixel) -> Option<T>, )

Applies a color-producing function to each pixel and writes the resulting color into the image.

The closure may return None to indicate that a pixel’s color should remain unchanged.

pub fn fill(&self, image: &mut DynamicImage, color: Color)

Fills all pixels in the set with a single uniform color.

pub fn transform<T: Into<Color>>( &self, image: &mut DynamicImage, applier: impl Fn(Color) -> Option<T>, )

Reads the color of each pixel from the image, applies a transformation closure, and writes back a new color if one is produced.

pub fn neighbors(&self, image: &DynamicImage) -> Self

Returns a PixelSet representing all 8-connected neighbors of all pixels in this set, constrained to the image bounds.

pub fn touching(&self, other: &Self, image: &DynamicImage) -> Self

Returns the subset of pixels in this set that are adjacent to another set.

A pixel is included in the result if included in self, and adjacent to a pixel in other.

pub fn as_colors(&self, image: &DynamicImage) -> impl Iterator<Item = Color>

Returns an iterator over the colors of all pixels in this set when viewed in the provided image.

pub fn mean_color(&self, image: &DynamicImage) -> Option<Color>

Computes the average color of all pixels in the set when sampled from the given image.

Returns None if the set is empty.

Trait Implementations

impl Clone for PixelSet

fn clone(&self) -> PixelSet

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> IntoIterator for &'a PixelSet

type Item = &'a Pixel

The type of the elements being iterated over.

type IntoIter = Iter<'a, Pixel>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut PixelSet

type Item = &'a mut Pixel

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Pixel>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for PixelSet

type Item = Pixel

The type of the elements being iterated over.

type IntoIter = IntoIter<Pixel>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.