lib3mf_core/parser/
mod.rs

1//! XML-to-Model parsing pipeline for 3MF files.
2//!
3//! This module converts XML content from a 3MF archive into the in-memory [`Model`](crate::model::Model)
4//! structure. It handles the Core 3MF specification and all major extensions.
5//!
6//! ## Two Parsing Modes
7//!
8//! The parser provides two modes optimized for different use cases:
9//!
10//! ### DOM Mode (Default)
11//!
12//! The [`parse_model`] function loads the entire XML document into memory and constructs the complete
13//! [`Model`](crate::model::Model) structure. This is:
14//!
15//! - **Fast**: Single-pass parsing with efficient XML handling
16//! - **Simple**: Returns a complete model ready to use
17//! - **Suitable for**: Files under 100MB (typical use case)
18//!
19//! ```no_run
20//! use lib3mf_core::parser::parse_model;
21//! use std::io::Cursor;
22//!
23//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
24//! let xml_data = b"<model xmlns='http://schemas.microsoft.com/3dmanufacturing/core/2015/02'>...</model>";
25//! let model = parse_model(Cursor::new(xml_data))?;
26//! println!("Loaded {} objects", model.resources.iter_objects().count());
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! ### SAX/Streaming Mode (For Large Files)
32//!
33//! The [`streaming`] module provides event-based parsing with constant memory usage via the
34//! [`ModelVisitor`](visitor::ModelVisitor) trait. This is:
35//!
36//! - **Memory-efficient**: Constant memory regardless of file size
37//! - **Suitable for**: Files over 100MB, or memory-constrained environments
38//! - **More complex**: Requires implementing visitor callbacks
39//!
40//! See [`streaming`] module documentation for details.
41//!
42//! ## Parser Architecture
43//!
44//! The parser is organized into specialized modules:
45//!
46//! ### Core Parsers
47//!
48//! - [`model_parser`]: Orchestrates parsing of the `<model>` root element
49//! - [`mesh_parser`]: Parses `<mesh>` geometry (vertices, triangles)
50//! - [`material_parser`]: Parses material resources (base materials, colors, textures, composites)
51//! - [`build_parser`]: Parses `<build>` section (what to print and where)
52//! - [`component_parser`]: Parses `<components>` (object references and transformations)
53//!
54//! ### Extension Parsers
55//!
56//! - [`beamlattice_parser`]: Beam Lattice Extension (structural lattices)
57//! - [`slice_parser`]: Slice Extension (2D layer-based geometry for DLP/SLA)
58//! - [`volumetric_parser`]: Volumetric Extension (voxel data)
59//! - [`boolean_parser`]: Boolean Operations Extension (CSG operations)
60//! - [`displacement_parser`]: Displacement Extension (texture-driven surface modification)
61//! - [`crypto_parser`]: Digital signature metadata (always available, parses XML only)
62//! - [`secure_content_parser`]: Secure Content Extension (encryption/decryption, requires `crypto` feature)
63//!
64//! ### Vendor Extensions
65//!
66//! - [`bambu_config`]: Bambu Studio project files (plates, filament data, print times)
67//!
68//! ## Crypto vs Secure Content
69//!
70//! The parser distinguishes between two related modules:
71//!
72//! - **`crypto_parser`**: Always available. Parses XML structure of `<Signature>` elements but doesn't
73//!   verify them. This allows reading signed files without crypto dependencies.
74//! - **`secure_content_parser`**: Behind `crypto` feature. Handles encryption/decryption and signature
75//!   verification. Requires base64, aes-gcm, rsa, sha1, sha2, x509-parser dependencies.
76//!
77//! ## Error Handling
78//!
79//! All parsing functions return [`Result<T, Lib3mfError>`](crate::error::Result):
80//!
81//! - **InvalidStructure**: Malformed XML, missing required attributes, spec violations
82//! - **Io**: File reading errors, ZIP errors
83//! - **ResourceNotFound**: References to non-existent resource IDs
84//! - **FeatureNotEnabled**: Trying to use `secure_content_parser` without `crypto` feature
85//!
86//! The parser never panics on invalid input.
87
88pub mod bambu_config;
89pub mod beamlattice_parser;
90pub mod boolean_parser;
91pub mod build_parser;
92pub mod component_parser;
93pub mod crypto_parser;
94pub mod displacement_parser;
95pub mod material_parser;
96pub mod mesh_parser;
97pub mod model_parser;
98#[cfg(feature = "crypto")]
99pub mod secure_content_parser;
100pub mod slice_parser;
101pub mod streaming;
102pub mod visitor;
103pub mod volumetric_parser;
104pub mod xml_parser;
105
106pub use bambu_config::parse_model_settings;
107pub use crypto_parser::parse_signature;
108/// Primary entry point for parsing 3MF model XML.
109///
110/// Converts XML content into an in-memory [`Model`](crate::model::Model) structure with all resources,
111/// build instructions, and extension data.
112///
113/// # Parameters
114///
115/// - `reader`: Any type implementing `Read` (e.g., `File`, `Cursor<Vec<u8>>`, `&[u8]`)
116///
117/// # Returns
118///
119/// A complete [`Model`](crate::model::Model) with all parsed data.
120///
121/// # Errors
122///
123/// - [`Lib3mfError::InvalidStructure`](crate::error::Lib3mfError::InvalidStructure): Malformed XML or spec violations
124/// - [`Lib3mfError::Io`](crate::error::Lib3mfError::Io): I/O errors reading the stream
125///
126/// # Examples
127///
128/// ```no_run
129/// use lib3mf_core::parser::parse_model;
130/// use lib3mf_core::archive::{ZipArchiver, ArchiveReader, find_model_path};
131/// use std::fs::File;
132///
133/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
134/// let file = File::open("model.3mf")?;
135/// let mut archive = ZipArchiver::new(file)?;
136/// let model_path = find_model_path(&mut archive)?;
137/// let xml_data = archive.read_entry(&model_path)?;
138///
139/// let model = parse_model(std::io::Cursor::new(xml_data))?;
140/// println!("Parsed model with {} objects", model.resources.iter_objects().count());
141/// # Ok(())
142/// # }
143/// ```
144pub use model_parser::parse_model;
145pub use xml_parser::XmlParser;
lib3mf_core/parser/mod.rs

lib3mf_core/parser/
mod.rs
