Struct Filter 

pub struct Filter { /* private fields */ }

A 2D convolution kernel (filter / mask / window).

Kernel Layout

The kernel is stored in row-major order as a flat Vec<f32>. For a 3×3 Sobel-X kernel:

     j=0  j=1  j=2         Flat storage:
i=0 [  1    0   -1  ]      index: 0  1  2  3  4  5  6  7  8
i=1 [  2    0   -2  ]      value: 1, 0,-1, 2, 0,-2, 1, 0,-1
i=2 [  1    0   -1  ]

Access formula: kernel[i * width + j]

Implementations

impl Filter

pub fn new(width: usize, height: usize) -> Self

Creates a zero-initialised filter of given dimensions.

Filter::new(3, 3) → [0, 0, 0, 0, 0, 0, 0, 0, 0]

pub fn from(kernel_buffer: Vec<f32>, width: usize, height: usize) -> Self

Creates a filter from a pre-computed flat kernel buffer.

The buffer must have exactly width × height elements, stored row-major (row 0 first, then row 1, etc.).

Panics

Exits the process if kernel_buffer.len() != width * height.

pub fn width(&self) -> usize

Returns the filter width (number of columns).

pub fn height(&self) -> usize

Returns the filter height (number of rows).

pub fn kernel(&self) -> Vec<f32>

Returns a clone of the kernel data as a flat Vec<f32>.

pub fn get_element(&self, x: usize, y: usize) -> Option<f32>

Returns the element at (row, col), or None if out of bounds.

pub fn set_value_at_pos(&mut self, val: f32, position: (usize, usize))

Sets the element at (row, col) to the given value.

Panics

Exits the process if the position is out of bounds.

pub fn try_separable(&self) -> Option<(Vec<f32>, Vec<f32>)>

Tests whether this kernel is separable — i.e. can be expressed as the outer product of a column vector and a row vector.

The Concept

A 2D kernel K can sometimes be factored:  K = col × rowᵀ

  [ a ]                 [ a·c  a·d  a·e ]
  [ b ] × [ c  d  e ] = [ b·c  b·d  b·e ]

  col 2×1  row 1×3      kernel 2×3

When separable, convolution can use two 1D passes instead of one 2D pass: O(fw·fh) → O(fw + fh) per output pixel.

Decomposition Algorithm

1. Find the largest absolute value in the kernel — this is the pivot.
2. Extract the pivot’s row as the row vector.
3. Extract the pivot’s column, divided by the pivot value, as the column vector.
4. Verify that for every element: col[i] × row[j] ≈ kernel[i][j]. If any element deviates beyond 1e-4, the kernel is not separable.

Example: Sobel-X = [1,0,-1; 2,0,-2; 1,0,-1]

  Pivot = |2| at (1,0)          col = col₀ / 2 = [1/2, 2/2, 1/2]
  row   = row₁ = [2, 0, -2]     row = row₁      = [2, 0, -2]

  Verify: [0.5] × [2, 0, -2] = [1,0,-1; 2,0,-2; 1,0,-1]  ✓
          [1.0]
          [0.5]

Returns

• Some((col_vec, row_vec)) — col has height elements, row has width elements.
• None — kernel is not separable (or is all zeros).

pub fn display(&self)

Pretty-prints the kernel as a formatted table to stdout.

Trait Implementations

impl Clone for Filter

fn clone(&self) -> Filter

Returns a duplicate of the value.

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

Performs copy-assignment from source.