vsf 0.3.4

Versatile Storage Format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

//! Spectral data structures for representing wavelength-based colour information

/// A spectrum represents spectral data at regular wavelength intervals
///
/// This structure encapsulates spectral power distributions, colour matching functions,
/// or other wavelength-dependent data with a defined range and spacing.
#[derive(Debug, Clone)]
pub struct Spectrum {
    /// Starting wavelength in nanometers
    pub start_nm: f32,

    /// Ending wavelength in nanometers
    pub stop_nm: f32,

    /// Spacing between samples in nanometers
    pub spacing_nm: f32,

    /// Spectral data values
    /// For single-channel data (like SPD), this is one value per wavelength
    /// For multi-channel data (like LMS), this is N values per wavelength (interleaved)
    pub data: Vec<f32>,
}

impl Spectrum {
    /// Create a new spectrum with the given parameters
    pub fn new(start_nm: f32, stop_nm: f32, spacing_nm: f32, data: Vec<f32>) -> Self {
        Self {
            start_nm,
            stop_nm,
            spacing_nm,
            data,
        }
    }

    /// Get the number of wavelength samples in this spectrum
    pub fn num_samples(&self) -> usize {
        ((self.stop_nm - self.start_nm) / self.spacing_nm).round() as usize + 1
    }

    /// Get the wavelength for a given sample index
    pub fn wavelength_at(&self, index: usize) -> f32 {
        self.start_nm + (index as f32 * self.spacing_nm)
    }

    /// Check if a wavelength falls within this spectrum's range
    pub fn contains_wavelength(&self, wavelength_nm: f32) -> bool {
        wavelength_nm >= self.start_nm && wavelength_nm <= self.stop_nm
    }
}

/// A const-compatible spectrum for reference spectral data
///
/// This structure is designed for const declarations of reference spectral data
/// (like CIE colour matching functions) that live in the binary's .rodata section.
/// Uses a static slice instead of Vec for const compatibility.
#[derive(Debug, Clone, Copy)]
pub struct ConstSpectrum {
    /// Starting wavelength in nanometers
    pub start_nm: f32,

    /// Ending wavelength in nanometers
    pub stop_nm: f32,

    /// Spacing between samples in nanometers
    pub spacing_nm: f32,

    /// Number of channels (e.g., 1 for SPD, 3 for LMS)
    pub num_channels: usize,

    /// Spectral data values (static slice for const compatibility)
    /// For single-channel data (like SPD), this is one value per wavelength
    /// For multi-channel data (like LMS), this is N values per wavelength (interleaved)
    pub data: &'static [f32],
}

impl ConstSpectrum {
    /// Get the number of wavelength samples in this spectrum
    pub const fn num_samples(&self) -> usize {
        ((self.stop_nm - self.start_nm) / self.spacing_nm) as usize + 1
    }

    /// Get the wavelength for a given sample index
    pub const fn wavelength_at(&self, index: usize) -> f32 {
        self.start_nm + (index as f32 * self.spacing_nm)
    }

    /// Check if a wavelength falls within this spectrum's range
    pub const fn contains_wavelength(&self, wavelength_nm: f32) -> bool {
        wavelength_nm >= self.start_nm && wavelength_nm <= self.stop_nm
    }
}

/// Convert a ConstSpectrum reference to an owned Spectrum
///
/// Note: This converts multi-channel ConstSpectrum to single-channel Spectrum.
/// Use the appropriate conversion method if you need to preserve channel information.
impl From<&ConstSpectrum> for Spectrum {
    fn from(const_spectrum: &ConstSpectrum) -> Self {
        Self {
            start_nm: const_spectrum.start_nm,
            stop_nm: const_spectrum.stop_nm,
            spacing_nm: const_spectrum.spacing_nm,
            data: const_spectrum.data.to_vec(),
        }
    }
}

/// A three-channel spectrum representing LMS cone fundamentals or similar data
#[derive(Debug, Clone)]
pub struct Spectrum3 {
    /// Starting wavelength in nanometers
    pub start_nm: f32,

    /// Ending wavelength in nanometers
    pub stop_nm: f32,

    /// Spacing between samples in nanometers
    pub spacing_nm: f32,

    /// Spectral data values as [L, M, S] triplets
    /// Format: [l0, m0, s0, l1, m1, s1, ..., ln, mn, sn]
    pub data: Vec<f32>,
}

impl Spectrum3 {
    /// Create a new 3-channel spectrum
    pub fn new(start_nm: f32, stop_nm: f32, spacing_nm: f32, data: Vec<f32>) -> Self {
        Self {
            start_nm,
            stop_nm,
            spacing_nm,
            data,
        }
    }

    /// Get the number of wavelength samples
    pub fn num_samples(&self) -> usize {
        self.data.len() / 3
    }

    /// Get the wavelength for a given sample index
    pub fn wavelength_at(&self, index: usize) -> f32 {
        self.start_nm + (index as f32 * self.spacing_nm)
    }

    /// Get the three values at a given sample index
    pub fn get_at(&self, index: usize) -> Option<[f32; 3]> {
        if index * 3 + 2 < self.data.len() {
            Some([
                self.data[index * 3],
                self.data[index * 3 + 1],
                self.data[index * 3 + 2],
            ])
        } else {
            None
        }
    }

    /// Check if a wavelength falls within this spectrum's range
    pub fn contains_wavelength(&self, wavelength_nm: f32) -> bool {
        wavelength_nm >= self.start_nm && wavelength_nm <= self.stop_nm
    }
}