Struct TfSurface 

pub struct TfSurface<'a> {
    pub raster: &'a [f32],
    pub frame_count: usize,
    pub bin_count: usize,
    pub sample_rate: u32,
    pub hop_size: usize,
}

A time-frequency surface: frames × bins magnitude raster.

The raster is row-major: raster[frame * bins + bin]. This is a view (borrowed) — no heap allocation.

Fields

raster: &'a [f32]

frame_count: usize

bin_count: usize

sample_rate: u32

hop_size: usize

Implementations

impl<'a> TfSurface<'a>

pub fn new( raster: &'a [f32], frame_count: usize, bin_count: usize, sample_rate: u32, hop_size: usize, ) -> Self

Create a surface view from a raw raster slice.

raster.len() must equal frame_count * bin_count.

pub fn get(&self, frame: usize, bin: usize) -> f32

Get the magnitude at (frame, bin).

pub fn frame_to_time(&self, frame: usize) -> f32

Time in seconds for a given frame index.

pub fn bin_to_freq_linear(&self, bin: usize) -> f32

Frequency in Hz for a linear bin index (STFT).

pub fn bin_to_freq_log( &self, bin: usize, f_min: f32, bins_per_octave: usize, ) -> f32

Frequency in Hz for a log-spaced bin index (CQT). f_k = f_min * 2^(k / bins_per_octave)

pub fn sample_bilinear(&self, frame_f: f32, bin_f: f32) -> f32

Bilinear sample at fractional (frame_f, bin_f).

pub fn spectral_flux(&self, out: &mut [f32]) -> usize

Spectral flux: sum of positive magnitude differences between consecutive frames. Written to out (length frame_count - 1).

pub fn freq_gradient(&self, frame: usize, bin: usize) -> f32

Frequency gradient at (frame, bin) — central difference.

pub fn time_gradient(&self, frame: usize, bin: usize) -> f32

Time gradient at (frame, bin) — central difference.

pub fn ridge_bin(&self, frame: usize) -> usize

Find the ridge bin (peak magnitude) for a given frame. Returns the bin index of the maximum.

pub fn ridges(&self, out: &mut [usize]) -> usize

Collect ridge bins for all frames into out. Returns the number of ridges written (= frame_count).

pub fn to_height_mesh(&self, out_verts: &mut [f32]) -> usize

Convert to a height-map mesh: each (frame, bin) → (x, y, z) where x = time, y = freq, z = magnitude. Writes frame_count * bin_count vertices to out_verts as [x, y, z] triples. Returns the number of vertices written.

pub fn total_energy(&self) -> f32

Total energy (sum of all magnitudes).

pub fn frame_energy(&self, frame: usize) -> f32

Frame energy (sum of magnitudes in a single frame).

Trait Implementations

impl<'a> Clone for TfSurface<'a>

fn clone(&self) -> TfSurface<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for TfSurface<'a>

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

Formats the value using the given formatter.

impl<'a> Copy for TfSurface<'a>