lib3mf_converters/lib.rs
1//! # lib3mf-converters
2//!
3//! Format converters for converting between 3MF and other 3D file formats.
4//!
5//! ## Overview
6//!
7//! This crate provides importers and exporters for converting STL and OBJ files to and from the 3MF format.
8//! It builds on [`lib3mf_core`] to provide bi-directional conversion between these common 3D formats and the
9//! full 3MF [`Model`] representation.
10//!
11//! **Supported formats:**
12//! - **STL**: Binary STL only (80-byte header + triangle records)
13//! - **OBJ**: Basic geometry only (vertices and faces, no materials/textures)
14//!
15//! ## Quick Start
16//!
17//! ```no_run
18//! use lib3mf_converters::stl::StlImporter;
19//! use lib3mf_core::validation::ValidationLevel;
20//! use std::fs::File;
21//!
22//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
23//! // Import an STL file
24//! let file = File::open("model.stl")?;
25//! let model = StlImporter::read(file)?;
26//!
27//! // Validate the imported geometry
28//! let report = model.validate(ValidationLevel::Standard);
29//! if report.has_errors() {
30//! eprintln!("Imported model has validation errors");
31//! }
32//!
33//! // Access the mesh data
34//! println!("Imported {} objects", model.resources.iter_objects().count());
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Modules
40//!
41//! - [`stl`]: Binary STL import and export
42//! - [`obj`]: Wavefront OBJ import and export
43//!
44//! ## Limitations
45//!
46//! - **STL**: Only binary STL format is supported (ASCII STL is not supported)
47//! - **OBJ**: Materials (mtllib/usemtl), texture coordinates (vt), and normals (vn) are ignored during import
48//! - **OBJ**: Export does not include materials or textures, only geometry
49//! - Vertex deduplication in STL import uses bitwise float comparison (exact match required)
50//!
51//! ## Cross-References
52//!
53//! This crate works with types from [`lib3mf_core`], particularly:
54//! - [`lib3mf_core::model::Model`]: The primary 3MF model structure
55//! - [`lib3mf_core::model::Mesh`]: Triangle mesh geometry
56//! - [`lib3mf_core::error::Lib3mfError`]: Error type for conversion operations
57//!
58//! [`lib3mf_core`]: https://docs.rs/lib3mf-core
59//! [`Model`]: https://docs.rs/lib3mf-core/latest/lib3mf_core/model/struct.Model.html
60//! [`lib3mf_core::model::Model`]: https://docs.rs/lib3mf-core/latest/lib3mf_core/model/struct.Model.html
61//! [`lib3mf_core::model::Mesh`]: https://docs.rs/lib3mf-core/latest/lib3mf_core/model/struct.Mesh.html
62//! [`lib3mf_core::error::Lib3mfError`]: https://docs.rs/lib3mf-core/latest/lib3mf_core/error/enum.Lib3mfError.html
63
64pub mod obj;
65pub mod stl;