pub fn self_similarity(
features: &[f32],
n_frames: usize,
n_dims: usize,
out: &mut [f32],
) -> Result<(), AudioError>Expand description
Compute the cosine self-similarity matrix of a per-frame feature matrix.
features is a row-major n_frames × n_dims matrix: frame i occupies
features[i*n_dims .. i*n_dims + n_dims]. These frames are provided by the
caller (e.g. from crate::features::mel::mfcc() or chroma / tonal features)
— this function never recomputes features.
The similarity is the cosine of the angle between two feature vectors,
S[i,j] = (x_i · x_j) / (‖x_i‖ ‖x_j‖), in [-1, 1] (clamped against
floating-point overshoot). When either frame has zero norm its similarity to
every other frame is defined as 0.0. The matrix is symmetric with a unit
diagonal for non-zero frames.
§Caller-buffer contract (zero internal frames² allocation)
The full n_frames × n_frames result is written, row-major, into the
caller-provided out buffer (out[i*n_frames + j] = S[i,j]). This function
performs no heap allocation — the inherently O(frames²) storage is the
caller’s out, and the O(frames²·dims) compute uses only scalar locals.
out.len() must be at least n_frames * n_frames.
§Errors
AudioError::InvalidParameterifn_frames == 0,n_dims == 0, orfeatures.len() < n_frames * n_dims.AudioError::OutputBufferTooSmallifout.len() < n_frames * n_frames.