semantic-scene 0.1.1

//! Generic dataset loading traits.
use std::{
    io::{BufRead, BufReader, Cursor},
    path::Path,
};

use crate::SemanticScene;

/// Trait implemented by semantic scene datasets.
///
/// `from_reader` is the required primitive so loaders can work with files,
/// in-memory buffers, compressed streams, and test fixtures. `from_str` and
/// `from_path` are convenience methods implemented in terms of it.
pub trait Dataset {
    /// Dataset-specific options.
    type Options: Default;
    /// Dataset-specific error type.
    type Error;
    /// Dataset-specific object category type.
    type ObjectCategory: Clone;
    /// Dataset-specific region category type.
    type RegionCategory: Clone;

    /// Loads a semantic scene from any buffered reader.
    ///
    /// # Errors
    ///
    /// Returns dataset-specific errors for I/O, parse, and validation failures.
    fn from_reader<R: BufRead>(
        reader: R,
        options: Self::Options,
    ) -> Result<SemanticScene<Self::ObjectCategory, Self::RegionCategory>, Self::Error>;

    /// Loads a semantic scene from an in-memory string.
    ///
    /// # Errors
    ///
    /// Returns dataset-specific parse and validation failures.
    fn from_str(
        input: &str,
        options: Self::Options,
    ) -> Result<SemanticScene<Self::ObjectCategory, Self::RegionCategory>, Self::Error> {
        Self::from_reader(Cursor::new(input), options)
    }

    /// Loads a semantic scene from a path.
    ///
    /// # Errors
    ///
    /// Returns I/O errors from opening the file or dataset-specific parse and validation failures.
    fn from_path(
        path: impl AsRef<Path>,
        options: Self::Options,
    ) -> Result<SemanticScene<Self::ObjectCategory, Self::RegionCategory>, Self::Error>
    where
        Self::Error: From<std::io::Error>,
    {
        let file = std::fs::File::open(path)?;
        Self::from_reader(BufReader::new(file), options)
    }
}