lib3mf_core/validation/
mod.rs

1//! Progressive validation system for 3MF models.
2//!
3//! This module provides a four-level validation system that lets you choose the right balance
4//! between performance and thoroughness for your use case.
5//!
6//! ## Validation Levels
7//!
8//! The [`ValidationLevel`] enum defines four progressively stricter validation modes:
9//!
10//! ### Minimal
11//!
12//! Basic structural checks:
13//! - Required attributes present (`unit`, `id`, etc.)
14//! - Valid XML structure
15//! - No obviously malformed data
16//!
17//! **Performance**: Very fast (< 1ms for typical models)
18//! **Use case**: Quick sanity check, development testing
19//!
20//! ### Standard (Recommended)
21//!
22//! Reference integrity and semantic correctness:
23//! - All resource IDs are unique
24//! - Build items reference valid objects
25//! - Material references point to existing materials
26//! - Component references form valid DAG (no cycles)
27//! - Vertex indices within mesh bounds
28//!
29//! **Performance**: Fast (< 10ms for typical models)
30//! **Use case**: Production parsing, most applications
31//!
32//! ### Strict
33//!
34//! Full 3MF specification compliance:
35//! - All Standard checks
36//! - Metadata requirements enforced
37//! - No unknown attributes or elements
38//! - Extension namespaces correctly declared
39//!
40//! **Performance**: Moderate
41//! **Use case**: Spec conformance testing, quality assurance
42//!
43//! ### Paranoid
44//!
45//! Deep geometry analysis with advanced algorithms:
46//! - All Strict checks
47//! - Mesh manifoldness (edge-manifold, vertex-manifold)
48//! - Self-intersection detection (BVH-accelerated)
49//! - Orientation consistency (outward-facing normals)
50//! - Degenerate triangle detection
51//! - Island detection (connected components)
52//! - Type-specific constraints (Model objects must be manifold)
53//!
54//! **Performance**: Slow (can be seconds for complex models, O(n²) worst case)
55//! **Use case**: Critical manufacturing workflows, geometry repair pipelines
56//!
57//! ## Usage
58//!
59//! ```
60//! use lib3mf_core::{Model, validation::ValidationLevel};
61//!
62//! let model = Model::default();
63//!
64//! // Quick check
65//! let report = model.validate(ValidationLevel::Minimal);
66//! assert!(!report.has_errors());
67//!
68//! // Production use
69//! let report = model.validate(ValidationLevel::Standard);
70//! if report.has_errors() {
71//!     for item in &report.items {
72//!         eprintln!("[{}] {}", item.code, item.message);
73//!     }
74//! }
75//!
76//! // Critical applications
77//! let report = model.validate(ValidationLevel::Paranoid);
78//! ```
79//!
80//! ## Validation Report
81//!
82//! Validation returns a [`ValidationReport`] containing:
83//!
84//! - **Errors**: Spec violations, broken references, invalid geometry
85//! - **Warnings**: Suspicious patterns, deprecated features, non-standard usage
86//! - **Info**: Informational messages, optimization suggestions
87//!
88//! Each item includes:
89//! - Error code (numeric, for programmatic handling)
90//! - Human-readable message
91//! - Optional suggestion for fixing the issue
92//! - Optional context (e.g., "Object 5", "Triangle 123")
93//!
94//! ## Geometry Validation Algorithms
95//!
96//! The [`geometry`] module implements advanced mesh validation:
97//!
98//! - **Manifoldness**: Each edge shared by exactly 2 triangles (edge-manifold). Each vertex has
99//!   a single connected fan of triangles (vertex-manifold).
100//! - **Self-intersection**: BVH (Bounding Volume Hierarchy) acceleration for O(n log n) triangle-triangle
101//!   intersection tests. See [`bvh`] module.
102//! - **Orientation**: Directed edge analysis to detect reversed normals.
103//! - **Island detection**: Connected component analysis using depth-first search.
104//!
105//! ## Performance Optimization
106//!
107//! For large models, validation can be expensive. Strategies:
108//!
109//! - **Use Standard for production**: Catches 99% of issues in < 10ms
110//! - **Defer Paranoid to background**: Run geometry checks asynchronously
111//! - **Cache results**: Validation reports are cloneable and serializable
112//! - **Progressive checking**: Validate incrementally during parsing (not yet implemented)
113
114pub mod bvh;
115pub mod displacement;
116pub mod geometry;
117pub mod report;
118pub mod schema;
119pub mod semantic;
120
121use serde::{Deserialize, Serialize};
122
123/// Level of validation to perform.
124///
125/// This enum defines four progressively stricter validation modes. Higher levels include
126/// all checks from lower levels.
127#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
128pub enum ValidationLevel {
129    /// Basic structural checks (required attributes, valid XML).
130    ///
131    /// Very fast (< 1ms). Suitable for quick sanity checks during development.
132    ///
133    /// Checks:
134    /// - Required attributes present
135    /// - Valid data types (numbers parse, IDs are positive)
136    /// - No obviously malformed structures
137    Minimal,
138
139    /// Full 3MF Core Spec compliance (resource IDs, reference integrity).
140    ///
141    /// Fast (< 10ms). **Recommended for production use.**
142    ///
143    /// Includes all Minimal checks plus:
144    /// - Resource IDs are unique
145    /// - Build items reference valid objects
146    /// - Material/property references are valid
147    /// - Component references form valid DAG (no cycles)
148    /// - Vertex indices within mesh bounds
149    Standard,
150
151    /// Strict adherence to spec (metadata, no unknown attributes).
152    ///
153    /// Moderate performance. Suitable for conformance testing and quality assurance.
154    ///
155    /// Includes all Standard checks plus:
156    /// - Metadata requirements enforced
157    /// - No unknown attributes or elements
158    /// - Extension namespaces correctly declared
159    /// - Proper content type and relationship registration
160    Strict,
161
162    /// Deep geometry inspection (manifold checks, intersection tests).
163    ///
164    /// Slow (can be seconds for complex models). Use for critical manufacturing workflows.
165    ///
166    /// Includes all Strict checks plus:
167    /// - Mesh manifoldness (edge-manifold and vertex-manifold)
168    /// - Self-intersection detection (BVH-accelerated, still O(n²) worst case)
169    /// - Orientation consistency (outward-facing normals)
170    /// - Degenerate triangle detection
171    /// - Connected component analysis
172    /// - Type-specific geometry constraints
173    Paranoid,
174}
175
176// Re-exports
177pub use displacement::validate_displacement;
178pub use geometry::validate_geometry;
179pub use report::{ValidationReport, ValidationSeverity};
lib3mf_core/validation/mod.rs

lib3mf_core/validation/
mod.rs
