draco_io/

traits.rs

//! Common traits for geometry readers and writers.
//!
//! These traits define the shared mesh and point-cloud API for the OBJ, PLY,
//! STL, and FBX adapters in this crate. They intentionally do not model a lossless
//! scene document; full glTF scene workflows use `draco-gltf::Document` and
//! `draco-gltf::Import` instead.
//!
//! # Usage
//!
//! Import the trait to access its methods:
//!
//! ```no_run
//! # #[cfg(feature = "obj-writer")]
//! # fn main() -> Result<(), std::io::Error> {
//! use draco_io::{Writer, ObjWriter};
//! # let mesh = draco_core::mesh::Mesh::new();
//!
//! let mut writer = ObjWriter::new();
//! writer.add_mesh(&mesh, Some("Name"))?;  // Calls trait method
//! writer.write("output.obj")?;
//! # Ok(())
//! # }
//! # #[cfg(not(feature = "obj-writer"))]
//! # fn main() {}
//! ```
//!
//! This enables generic functions:
//!
//! ```no_run
//! use std::io;
//! use draco_core::mesh::Mesh;
//! use draco_io::Writer;
//!
//! fn save<W: Writer>(mut w: W, mesh: &Mesh) -> io::Result<()> {
//!     w.add_mesh(mesh, Some("Model"))?;
//!     w.write("output.ext")
//! }
//! ```

use std::io::{self, Write};
use std::path::Path;

// Used by the writer-side helpers below, which carry this same gate.
#[cfg(any(
    feature = "obj-writer",
    feature = "ply-writer",
    feature = "stl-writer",
    feature = "fbx-writer"
))]
use draco_core::geometry_indices::PointIndex;
use draco_core::mesh::Mesh;

/// Common interface for geometry writers.
///
/// The mesh-format writers in this crate implement this trait:
///
/// ```no_run
/// use std::io;
/// use draco_core::mesh::Mesh;
/// use draco_io::Writer;
///
/// fn write_mesh<W: Writer>(mut writer: W, mesh: &Mesh) -> io::Result<()> {
///     writer.add_mesh(mesh, Some("MyMesh"))?;
///     writer.write("output.ext")
/// }
/// ```
pub trait Writer: Sized {
    /// Create a new writer instance.
    fn new() -> Self;

    /// Add a mesh to be written.
    ///
    /// # Arguments
    /// * `mesh` - The mesh to add
    /// * `name` - Optional name for the mesh (if format supports naming)
    ///
    /// # Returns
    /// * `Ok(())` on success
    /// * `Err` if the format cannot handle this mesh (e.g., compression failure)
    fn add_mesh(&mut self, mesh: &Mesh, name: Option<&str>) -> io::Result<()>;

    /// Write all added meshes to a file.
    ///
    /// # Arguments
    /// * `path` - Output file path
    fn write<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;

    /// Get the number of meshes/vertices added.
    fn vertex_count(&self) -> usize;

    /// Get the number of faces added (if applicable).
    fn face_count(&self) -> usize {
        0
    }
}

/// Common interface for geometry readers.
///
/// The mesh-format readers in this crate implement this trait:
///
/// ```no_run
/// use std::io;
/// use draco_core::mesh::Mesh;
/// use draco_io::Reader;
///
/// fn load_mesh<R: Reader>(path: &str) -> io::Result<Mesh> {
///     let mut reader = R::open(path)?;
///     reader.read_mesh()
/// }
/// ```
pub trait Reader: Sized {
    /// Open a file for reading.
    ///
    /// # Arguments
    /// * `path` - Input file path
    fn open<P: AsRef<Path>>(path: P) -> io::Result<Self>;

    /// Read multiple meshes (a scene) from the file.
    ///
    /// Formats that represent scenes or multiple mesh primitives should implement
    /// this method and return all meshes in the file or scene.
    fn read_meshes(&mut self) -> io::Result<Vec<Mesh>>;

    /// Read a single mesh from the file.
    ///
    /// Default implementation returns the first mesh from `read_meshes()`.
    fn read_mesh(&mut self) -> io::Result<Mesh> {
        let meshes = self.read_meshes()?;
        if let Some(m) = meshes.into_iter().next() {
            Ok(m)
        } else {
            Err(io::Error::new(io::ErrorKind::InvalidData, "No mesh found"))
        }
    }
}

/// Common interface for readers that can be constructed from in-memory bytes.
///
/// This complements [`Reader::open`] for callers that already have file bytes
/// loaded, or that are working in browser/embedded environments without direct
/// filesystem access.
pub trait ReadFromBytes: Sized {
    /// Create a reader from a complete file payload.
    fn from_bytes(bytes: &[u8]) -> io::Result<Self>;
}

/// Common interface for writers that can emit a complete file payload.
///
/// This complements [`Writer::write`] for callers that need to send bytes over
/// the network, store them in an archive, or run roundtrips without temporary
/// files.
pub trait WriteToBytes: Writer {
    /// Write all added data into a byte vector.
    fn write_to_vec(&self) -> io::Result<Vec<u8>>;

    /// Write all added data into an arbitrary byte sink.
    fn write_to<W: Write>(&self, writer: &mut W) -> io::Result<()> {
        writer.write_all(&self.write_to_vec()?)
    }
}

/// Extended writer trait for point cloud support.
///
/// Writers that can output point clouds (without faces) implement this trait.
pub trait PointCloudWriter: Writer {
    /// Add raw point positions.
    fn add_points(&mut self, points: &[[f32; 3]]);

    /// Add a single point.
    fn add_point(&mut self, point: [f32; 3]) {
        self.add_points(&[point]);
    }
}

/// Extended reader trait for point cloud support.
///
/// Readers that can read point clouds implement this trait.
pub trait PointCloudReader: Reader {
    /// Read point positions only (no faces or topology).
    fn read_points(&mut self) -> io::Result<Vec<[f32; 3]>>;
}

/// Refuses a mesh whose attribute values a writer would read past the end of.
///
/// Every mesh writer here reads attribute data as `point_index * byte_stride`,
/// for `point_index` in `0..num_points`, through the panicking
/// `DataBuffer::read` -- nine call sites across the four formats. That is
/// sound exactly when each attribute holds at least `num_points` values, and
/// nothing between a decoder and a writer re-checks it: the geometry arrives
/// from `MeshDecoder`, whose counts come from a header, or from a caller that
/// built it by hand.
///
/// One precondition, stated once, is what makes those nine reads provably in
/// range. Checking at each read instead would mean deciding, nine times, what
/// a writer should emit for a value that is not there -- and the honest answer
/// is nothing, which is what this returns.
///
/// Attributes with an explicit point map are covered by the same bound: the
/// writers index by point regardless, so a shorter value array is a mesh they
/// cannot represent either way.
#[cfg(any(
    feature = "obj-writer",
    feature = "ply-writer",
    feature = "stl-writer",
    feature = "fbx-writer"
))]
pub(crate) fn ensure_attributes_cover_points(mesh: &Mesh, format: &str) -> io::Result<()> {
    let num_points = mesh.num_points();
    for att_id in 0..mesh.num_attributes() {
        let attribute = mesh.attribute(att_id);
        if attribute.is_mapping_identity() {
            if attribute.size() < num_points {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    format!(
                        "{format} writer: attribute {att_id} ({:?}) holds {} values for {num_points} points",
                        attribute.attribute_type(),
                        attribute.size(),
                    ),
                ));
            }
            continue;
        }
        // With an explicit map the value count says nothing: several points
        // legitimately name one value, which is what a reader's finalization
        // and a Draco stream both produce. What has to hold is that every
        // point names a value that exists.
        for point in 0..num_points {
            let value = attribute.mapped_index(PointIndex(point as u32)).0 as usize;
            if value >= attribute.size() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    format!(
                        "{format} writer: attribute {att_id} ({:?}) maps point {point} to value {value} of {}",
                        attribute.attribute_type(),
                        attribute.size(),
                    ),
                ));
            }
        }
    }
    Ok(())
}

/// Where one point's value sits in an attribute's buffer.
///
/// Every writer here used to read `point * byte_stride`, which is the value's
/// address only while the mapping is the identity. It is not: a reader merges
/// values that repeat and a Draco stream carries the map it was written with,
/// so several points share one value and the point index stops being an
/// address. Upstream's writers resolve the map for the same reason.
#[cfg(any(
    feature = "obj-writer",
    feature = "ply-writer",
    feature = "stl-writer",
    feature = "fbx-writer"
))]
pub(crate) fn value_offset(attribute: &draco_core::PointAttribute, point: usize) -> usize {
    let value = if attribute.is_mapping_identity() {
        point
    } else {
        attribute.mapped_index(PointIndex(point as u32)).0 as usize
    };
    value.saturating_mul(attribute.byte_stride() as usize)
}

/// Ends mesh construction with [`draco_core::mesh::Mesh::finalize`], reporting
/// its refusal as the [`std::io::Error`] every reader in this crate returns.
///
/// The only way that pass fails is an attribute whose type its value
/// deduplication does not cover, which is a property of the file just read --
/// so `InvalidData` is the kind, not `Other`.
///
/// STL is absent from the gate and from the callers alike: the format carries
/// no vertex identity, so welding would be that reader inventing one.
#[cfg(any(feature = "obj-reader", feature = "ply-reader"))]
pub(crate) fn finalize_mesh(mesh: &mut draco_core::mesh::Mesh) -> std::io::Result<()> {
    mesh.finalize()
        .map_err(|error| std::io::Error::new(std::io::ErrorKind::InvalidData, error.to_string()))
}