binmat — Binary Matrix Loader

Source: crates/fastdpplot-core/src/binmat.rs

---

MatrixDtype

Supported element types for a raw binary matrix.

pub enum MatrixDtype { U8, I16, I32, F32, F64 }

Variant	C equivalent	Bytes
U8	uint8_t	1
I16	int16_t	2
I32	int32_t	4
F32	float	4
F64	double	8

Methods

impl MatrixDtype {
    pub fn element_size(self) -> usize;
    pub fn parse(s: &str) -> Option<Self>;
}

parse accepts the string tags "u8", "i16", "i32", "f32", "f64".

---

MatrixData

A flat, row-major typed buffer.

pub enum MatrixData {
    U8(Vec<u8>),
    I16(Vec<i16>),
    I32(Vec<i32>),
    F32(Vec<f32>),
    F64(Vec<f64>),
}

Method

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

Converts every element to f32 in row-major order (used by the normalisation pipeline).

---

BinMatrix

A loaded raw binary matrix.

pub struct BinMatrix {
    pub rows: usize,
    pub cols: usize,
    pub dtype: MatrixDtype,
    pub data: MatrixData,
}

---

load_bin_matrix

pub fn load_bin_matrix(
    path: &str,
    rows: usize,
    cols: usize,
    dtype: MatrixDtype,
) -> Result<BinMatrix, FastDpError>

Load a raw binary matrix from path.

• Validates file_size == rows × cols × dtype.element_size().
• Reads bytes with read_exact — no unsafe transmute.
• Assumes little-endian byte order for multi-byte types.

Errors

Error	Condition
FastDpError::Io	File cannot be opened or read.
FastDpError::SizeMismatch	File size does not match rows × cols × element_size.

---

infer_dtype_from_size

pub fn infer_dtype_from_size(
    path: &str,
    rows: usize,
    cols: usize,
) -> Result<MatrixDtype, FastDpError>

Infer the element dtype by matching the file size to rows × cols × elem_size.

Tries dtypes in order: U8 → I16 → I32 → F32 → F64. Returns the first match, or FastDpError::CannotInferDtype if none match.

Ambiguous sizes

A matrix where rows × cols is divisible by multiple element sizes may yield an incorrect inference. In that case pass the dtype explicitly.

---

matrix_to_dotpoints

pub fn matrix_to_dotpoints(matrix: &BinMatrix) -> Vec<DotPoint>

Convert a BinMatrix to Vec<DotPoint>, emitting one [DotPoint] for every non-boundary matrix cell (row 0 and column 0 are gap-init penalties and are excluded).

There is no threshold parameter and no cells are filtered during conversion.

Raw i32 scores are cast directly to f32. No normalisation, min-max scaling, or sign adjustment is applied. Negative scores remain negative, zero stays zero, and positive scores remain positive, allowing the rendering layer to anchor zero as the neutral midpoint of the diverging colormap.

Output coordinates are 0-based sequence coordinates: matrix column c → x = c − 1, matrix row r → y = r − 1.

Parallelism

This function uses par_iter on rows, so it scales with the number of available CPU cores.