Enum SpectrumFile 

pub enum SpectrumFile {
    Single {
        schema_version: String,
        spectrum: Box<SpectrumRecord>,
    },
    Batch {
        schema_version: String,
        batch_metadata: Option<Box<BatchMetadata>>,
        spectra: Vec<SpectrumRecord>,
    },
}

The top-level structure of a spectrum JSON file. Tagged by file_type: either "single" or "batch".

Variants

Single

Fields

schema_version: String

spectrum: Box<SpectrumRecord>

Batch

Fields

schema_version: String

batch_metadata: Option<Box<BatchMetadata>>

spectra: Vec<SpectrumRecord>

Implementations

impl SpectrumFile

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Load and fully validate a UV-Vis JSON file from a file path. Runs structural schema validation then cross-field checks.

pub fn from_json_str(json: &str) -> Result<Self>

Load and fully validate a UV-Vis JSON file from a JSON string.

pub fn from_str_unchecked(json: &str) -> Result<Self>

Deserialise without any validation. Useful when you fully trust the source.

pub fn spectra(&self) -> Vec<&SpectrumRecord>

Returns all spectra in the file (works for both single and batch).

Examples found in repository

examples/cie_csv_to_json.rs (line 878)

fn main() {
    let args: Vec<String> = env::args().collect();
    let mut input_dir = PathBuf::from("data/cie-raw");
    let mut output_dir = PathBuf::from("data/spectral-io/cie");

    let mut i = 1usize;
    while i < args.len() {
        match args[i].as_str() {
            "--input" => {
                i += 1;
                if i < args.len() {
                    input_dir = PathBuf::from(&args[i]);
                }
            }
            "--output" => {
                i += 1;
                if i < args.len() {
                    output_dir = PathBuf::from(&args[i]);
                }
            }
            arg => {
                eprintln!("Unknown argument: {arg}");
                process::exit(1);
            }
        }
        i += 1;
    }

    let datasets = datasets();
    let mut ok = 0usize;
    let mut skipped = 0usize;
    let mut failed = 0usize;

    for ds in &datasets {
        let csv_path = input_dir.join(ds.csv_file);
        if !csv_path.exists() {
            eprintln!("  SKIP  {} (file not found)", ds.csv_file);
            skipped += 1;
            continue;
        }

        let raw_owned = match fs::read_to_string(&csv_path) {
            Ok(s) => s,
            Err(e) => {
                eprintln!("  ERROR reading {}: {e}", ds.csv_file);
                failed += 1;
                continue;
            }
        };
        // Strip a UTF-8 BOM that some CIE files carry; if left in place it
        // ends up in the middle of the synthetic header + raw concatenation
        // where csv_parse's own BOM strip (which only fires at position 0)
        // cannot reach it.
        let raw = raw_owned.strip_prefix('\u{FEFF}').unwrap_or(&raw_owned);

        let n_cols = count_data_cols(raw);
        if n_cols == 0 {
            eprintln!("  ERROR {}: no data rows found", ds.csv_file);
            failed += 1;
            continue;
        }

        let synthetic = format!("{}{}", build_header(ds, n_cols), raw);

        let mut file = match SpectrumFile::from_csv_str(&synthetic) {
            Ok(f) => f,
            Err(e) => {
                eprintln!("  ERROR parsing {}: {e}", ds.csv_file);
                failed += 1;
                continue;
            }
        };

        strip_nan_entries(&mut file);
        set_provenance(&mut file, ds.csv_file);

        let out_dir = output_dir.join(ds.subdir);
        if let Err(e) = fs::create_dir_all(&out_dir) {
            eprintln!("  ERROR creating {}: {e}", out_dir.display());
            failed += 1;
            continue;
        }

        let json = match serde_json::to_string_pretty(&file) {
            Ok(j) => j,
            Err(e) => {
                eprintln!("  ERROR serialising {}: {e}", ds.json_file);
                failed += 1;
                continue;
            }
        };

        let out_path = out_dir.join(ds.json_file);
        if let Err(e) = fs::write(&out_path, &json) {
            eprintln!("  ERROR writing {}: {e}", out_path.display());
            failed += 1;
            continue;
        }

        let n_spectra = file.spectra().len();
        eprintln!(
            "  OK    {} → {} ({} {})",
            ds.csv_file,
            out_path.display(),
            n_spectra,
            if n_spectra == 1 {
                "spectrum"
            } else {
                "spectra"
            }
        );
        ok += 1;
    }

    // Alpha-opic handled separately (per-column wavelength ranges)
    if convert_alpha_opic(&input_dir, &output_dir) {
        ok += 1;
    } else if !input_dir.join("CIE_a-opic_action_spectra.csv").exists() {
        skipped += 1;
    } else {
        failed += 1;
    }

    eprintln!();
    eprintln!("{ok} converted, {skipped} skipped, {failed} failed");
    if failed > 0 {
        process::exit(1);
    }
}

pub fn schema_version(&self) -> &str

The schema version declared in the file.

pub fn batch_metadata(&self) -> Option<&BatchMetadata>

Batch metadata, if this is a batch file.

impl SpectrumFile

pub fn from_spectrashop_path<P: AsRef<Path>>(path: P) -> Result<Self>

Load a SpectraShop text-export file from a path.

Parses the SpectraShop tab-separated text format (.txt) and converts each data record into a SpectrumRecord. File-level metadata (illuminant, observer, geometry, etc.) is applied to every record. Returns SpectrumFile::Single for one record or SpectrumFile::Batch for multiple records.

Non-UTF-8 bytes (e.g. Latin-1 encoded files) are replaced with U+FFFD.

Examples found in repository

examples/spectrashop_to_json.rs (line 58)

fn main() {
    let args: Vec<String> = env::args().collect();
    let prog = &args[0];

    let mut copyright: Option<String> = None;
    let mut positional: Vec<String> = Vec::new();

    let mut i = 1;
    while i < args.len() {
        match args[i].as_str() {
            "-c" => {
                i += 1;
                if i >= args.len() {
                    eprintln!("error: -c requires an argument");
                    usage(prog);
                }
                copyright = Some(args[i].clone());
            }
            arg if arg.starts_with('-') => {
                eprintln!("error: unknown option '{arg}'");
                usage(prog);
            }
            _ => positional.push(args[i].clone()),
        }
        i += 1;
    }

    if positional.is_empty() {
        usage(prog);
    }

    let input = PathBuf::from(&positional[0]);
    let output: Option<PathBuf> = positional.get(1).map(PathBuf::from);

    let mut file = SpectrumFile::from_spectrashop_path(&input).unwrap_or_else(|e| {
        eprintln!("error: {e}");
        process::exit(1);
    });

    if let Some(ref cr) = copyright {
        match &mut file {
            SpectrumFile::Single { spectrum, .. } => {
                spectrum.metadata.copyright = Some(cr.clone());
            }
            SpectrumFile::Batch { spectra, .. } => {
                for sp in spectra.iter_mut() {
                    sp.metadata.copyright = Some(cr.clone());
                }
            }
        }
    }

    let json = serde_json::to_string_pretty(&file).unwrap_or_else(|e| {
        eprintln!("error serialising to JSON: {e}");
        process::exit(1);
    });

    match output {
        Some(ref path) => {
            fs::write(path, &json).unwrap_or_else(|e| {
                eprintln!("error writing to {}: {e}", path.display());
                process::exit(1);
            });
            eprintln!("Written to {}", path.display());
        }
        None => print!("{json}"),
    }
}

pub fn from_spectrashop_str(input: &str) -> Result<Self>

Parse a SpectraShop text-export string.

See SpectrumFile::from_spectrashop_path for format details.

impl SpectrumFile

pub fn from_csv_path<P: AsRef<Path>>(path: P) -> Result<Self>

Load a CSV or TSV spectral data file from a path.

The delimiter (tab or comma) is auto-detected. An optional header block of KEY: VALUE lines precedes the data. The first row whose first cell parses as a number starts the data block; the immediately preceding non-blank line (if non-numeric) is treated as the column-header row. First data column = wavelength in nm; each subsequent column becomes one SpectrumRecord. Returns SpectrumFile::Single for one data column or SpectrumFile::Batch for multiple.

pub fn from_csv_str(input: &str) -> Result<Self>

Parse a CSV or TSV spectral data string.

See SpectrumFile::from_csv_path for format details.

Examples found in repository

examples/cie_csv_to_json.rs (line 843)

fn main() {
    let args: Vec<String> = env::args().collect();
    let mut input_dir = PathBuf::from("data/cie-raw");
    let mut output_dir = PathBuf::from("data/spectral-io/cie");

    let mut i = 1usize;
    while i < args.len() {
        match args[i].as_str() {
            "--input" => {
                i += 1;
                if i < args.len() {
                    input_dir = PathBuf::from(&args[i]);
                }
            }
            "--output" => {
                i += 1;
                if i < args.len() {
                    output_dir = PathBuf::from(&args[i]);
                }
            }
            arg => {
                eprintln!("Unknown argument: {arg}");
                process::exit(1);
            }
        }
        i += 1;
    }

    let datasets = datasets();
    let mut ok = 0usize;
    let mut skipped = 0usize;
    let mut failed = 0usize;

    for ds in &datasets {
        let csv_path = input_dir.join(ds.csv_file);
        if !csv_path.exists() {
            eprintln!("  SKIP  {} (file not found)", ds.csv_file);
            skipped += 1;
            continue;
        }

        let raw_owned = match fs::read_to_string(&csv_path) {
            Ok(s) => s,
            Err(e) => {
                eprintln!("  ERROR reading {}: {e}", ds.csv_file);
                failed += 1;
                continue;
            }
        };
        // Strip a UTF-8 BOM that some CIE files carry; if left in place it
        // ends up in the middle of the synthetic header + raw concatenation
        // where csv_parse's own BOM strip (which only fires at position 0)
        // cannot reach it.
        let raw = raw_owned.strip_prefix('\u{FEFF}').unwrap_or(&raw_owned);

        let n_cols = count_data_cols(raw);
        if n_cols == 0 {
            eprintln!("  ERROR {}: no data rows found", ds.csv_file);
            failed += 1;
            continue;
        }

        let synthetic = format!("{}{}", build_header(ds, n_cols), raw);

        let mut file = match SpectrumFile::from_csv_str(&synthetic) {
            Ok(f) => f,
            Err(e) => {
                eprintln!("  ERROR parsing {}: {e}", ds.csv_file);
                failed += 1;
                continue;
            }
        };

        strip_nan_entries(&mut file);
        set_provenance(&mut file, ds.csv_file);

        let out_dir = output_dir.join(ds.subdir);
        if let Err(e) = fs::create_dir_all(&out_dir) {
            eprintln!("  ERROR creating {}: {e}", out_dir.display());
            failed += 1;
            continue;
        }

        let json = match serde_json::to_string_pretty(&file) {
            Ok(j) => j,
            Err(e) => {
                eprintln!("  ERROR serialising {}: {e}", ds.json_file);
                failed += 1;
                continue;
            }
        };

        let out_path = out_dir.join(ds.json_file);
        if let Err(e) = fs::write(&out_path, &json) {
            eprintln!("  ERROR writing {}: {e}", out_path.display());
            failed += 1;
            continue;
        }

        let n_spectra = file.spectra().len();
        eprintln!(
            "  OK    {} → {} ({} {})",
            ds.csv_file,
            out_path.display(),
            n_spectra,
            if n_spectra == 1 {
                "spectrum"
            } else {
                "spectra"
            }
        );
        ok += 1;
    }

    // Alpha-opic handled separately (per-column wavelength ranges)
    if convert_alpha_opic(&input_dir, &output_dir) {
        ok += 1;
    } else if !input_dir.join("CIE_a-opic_action_spectra.csv").exists() {
        skipped += 1;
    } else {
        failed += 1;
    }

    eprintln!();
    eprintln!("{ok} converted, {skipped} skipped, {failed} failed");
    if failed > 0 {
        process::exit(1);
    }
}

pub fn to_tsv(&self) -> String

Serialise to a tab-separated string.

Writes a KEY: VALUE metadata header derived from the first spectrum, followed by a column-header row and one data row per wavelength point. For a batch file all spectra are written as parallel columns sharing the wavelength axis of the first spectrum.

pub fn to_csv(&self) -> String

Serialise to a comma-separated string.

See SpectrumFile::to_tsv for format details.

pub fn write_tsv<P: AsRef<Path>>(&self, path: P) -> Result<()>

Write a tab-separated file to the given path.

pub fn write_csv<P: AsRef<Path>>(&self, path: P) -> Result<()>

Write a comma-separated file to the given path.

Trait Implementations

impl Clone for SpectrumFile

fn clone(&self) -> SpectrumFile

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SpectrumFile

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SpectrumFile

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromStr for SpectrumFile

type Err = SpectrumFileError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl Serialize for SpectrumFile

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.