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
88/// Bambu Studio project file parsers (plate info, filament config, print settings).
89pub mod bambu_config;
90/// Beam Lattice Extension parser.
91pub mod beamlattice_parser;
92/// Boolean Operations Extension parser.
93pub mod boolean_parser;
94/// Build element parser (`<build>` and `<item>` elements).
95pub mod build_parser;
96/// Component and components element parser.
97pub mod component_parser;
98/// XML-DSIG crypto structure parser (always available; no crypto operations).
99pub mod crypto_parser;
100/// Displacement Extension parser.
101pub mod displacement_parser;
102/// Materials and Properties Extension parser.
103pub mod material_parser;
104/// Mesh geometry parser (`<vertices>` and `<triangles>`).
105pub mod mesh_parser;
106/// Root model XML parser — main entry point for DOM-mode parsing.
107pub mod model_parser;
108#[cfg(feature = "crypto")]
109/// Secure Content Extension parser (requires `crypto` feature).
110pub mod secure_content_parser;
111/// Slice Extension parser.
112pub mod slice_parser;
113/// SAX/streaming parser for memory-efficient processing of large 3MF files.
114pub mod streaming;
115/// `ModelVisitor` trait for streaming parser callbacks.
116pub mod visitor;
117/// Volumetric Extension parser.
118pub mod volumetric_parser;
119/// Low-level XML parser primitives used by all parser modules.
120pub mod xml_parser;
121
122pub use bambu_config::{
123    parse_model_settings, parse_profile_config, parse_project_settings, parse_slice_info,
124};
125pub use crypto_parser::parse_signature;
126/// Primary entry point for parsing 3MF model XML.
127///
128/// Converts XML content into an in-memory [`Model`](crate::model::Model) structure with all resources,
129/// build instructions, and extension data.
130///
131/// # Parameters
132///
133/// - `reader`: Any type implementing `Read` (e.g., `File`, `Cursor<Vec<u8>>`, `&[u8]`)
134///
135/// # Returns
136///
137/// A complete [`Model`](crate::model::Model) with all parsed data.
138///
139/// # Errors
140///
141/// - [`Lib3mfError::InvalidStructure`](crate::error::Lib3mfError::InvalidStructure): Malformed XML or spec violations
142/// - [`Lib3mfError::Io`](crate::error::Lib3mfError::Io): I/O errors reading the stream
143///
144/// # Examples
145///
146/// ```no_run
147/// use lib3mf_core::parser::parse_model;
148/// use lib3mf_core::archive::{ZipArchiver, ArchiveReader, find_model_path};
149/// use std::fs::File;
150///
151/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
152/// let file = File::open("model.3mf")?;
153/// let mut archive = ZipArchiver::new(file)?;
154/// let model_path = find_model_path(&mut archive)?;
155/// let xml_data = archive.read_entry(&model_path)?;
156///
157/// let model = parse_model(std::io::Cursor::new(xml_data))?;
158/// println!("Parsed model with {} objects", model.resources.iter_objects().count());
159/// # Ok(())
160/// # }
161/// ```
162pub use model_parser::parse_model;
163pub use xml_parser::XmlParser;
lib3mf_core/parser/mod.rs

lib3mf_core/parser/
mod.rs
