u_nesting_d3/
lib.rs

1//! # U-Nesting 3D
2//!
3//! 3D bin packing algorithms for the U-Nesting spatial optimization engine.
4//!
5//! This crate provides box-based 3D packing with collision detection
6//! and various placement algorithms.
7//!
8//! ## Features
9//!
10//! - Box geometry with 6-orientation support
11//! - Multiple placement strategies (Layer, GA, BRKGA, SA, Extreme Point)
12//! - Mass and stacking constraints
13//! - Configurable orientation constraints (Any, Upright, Fixed)
14//! - Spatial indexing for fast collision queries
15//!
16//! ## Quick Start
17//!
18//! ```rust
19//! use u_nesting_d3::{Geometry3D, Boundary3D, Packer3D, Config, Strategy, Solver};
20//! use u_nesting_d3::geometry::OrientationConstraint;
21//!
22//! // Create boxes
23//! let box1 = Geometry3D::new("box1", 100.0, 50.0, 30.0)
24//!     .with_quantity(10)
25//!     .with_orientation(OrientationConstraint::Upright);
26//!
27//! // Create container
28//! let container = Boundary3D::new(500.0, 400.0, 300.0);
29//!
30//! // Configure and solve
31//! let config = Config::new()
32//!     .with_strategy(Strategy::ExtremePoint)
33//!     .with_spacing(1.0);
34//!
35//! let packer = Packer3D::new(config);
36//! let result = packer.solve(&[box1], &container).unwrap();
37//!
38//! println!("Placed {} boxes, utilization: {:.1}%",
39//!     result.placements.len(),
40//!     result.utilization * 100.0);
41//! ```
42//!
43//! ## Orientation Constraints
44//!
45//! ```rust
46//! use u_nesting_d3::{Geometry3D, geometry::OrientationConstraint};
47//!
48//! // Any orientation (6 rotations)
49//! let any = Geometry3D::new("b1", 10.0, 20.0, 30.0)
50//!     .with_orientation(OrientationConstraint::Any);
51//!
52//! // Upright only (2 rotations, height preserved)
53//! let upright = Geometry3D::new("b2", 10.0, 20.0, 30.0)
54//!     .with_orientation(OrientationConstraint::Upright);
55//!
56//! // Fixed (no rotation)
57//! let fixed = Geometry3D::new("b3", 10.0, 20.0, 30.0)
58//!     .with_orientation(OrientationConstraint::Fixed);
59//! ```
60//!
61//! ## Mass Constraints
62//!
63//! ```rust
64//! use u_nesting_d3::{Geometry3D, Boundary3D};
65//!
66//! let heavy_box = Geometry3D::new("heavy", 50.0, 50.0, 50.0)
67//!     .with_mass(10.0)
68//!     .with_quantity(5);
69//!
70//! let container = Boundary3D::new(200.0, 200.0, 200.0)
71//!     .with_max_mass(100.0);
72//! ```
73
74pub mod boundary;
75pub mod brkga_packing;
76pub mod extreme_point;
77pub mod ga_packing;
78pub mod geometry;
79pub mod packer;
80pub mod packing_utils;
81pub mod physics;
82pub mod sa_packing;
83pub mod spatial_index;
84pub mod stability;
85
86// Re-exports
87pub use boundary::Boundary3D;
88pub use geometry::Geometry3D;
89pub use packer::Packer3D;
90pub use physics::{PhysicsConfig, PhysicsResult, PhysicsSimulator};
91pub use spatial_index::{Aabb3D, SpatialEntry3D, SpatialIndex3D};
92pub use stability::{
93    PlacedBox, StabilityAnalyzer, StabilityConstraint, StabilityReport, StabilityResult,
94};
95pub use u_nesting_core::{Config, Error, Placement, Result, SolveResult, Solver, Strategy};
96
97/// Builds a [`Pack3DResponse`](u_nesting_core::api_types::Pack3DResponse) from a
98/// 3D solve result, decoding each placement's orientation index into a string
99/// label via the corresponding geometry's orientation set.
100///
101/// This is the canonical 3D wire-response builder shared by the C FFI and WASM
102/// bindings, so both emit the C# `PackingResult`/`Placement3D` contract
103/// (bins, depth `z`, and a string `orientation` — never the 2D
104/// [`SolveResponse`](u_nesting_core::api_types::SolveResponse) shape).
105#[cfg(feature = "serde")]
106pub fn build_pack3d_response(
107    result: &SolveResult<f64>,
108    geometries: &[Geometry3D],
109) -> u_nesting_core::api_types::Pack3DResponse {
110    use std::collections::HashMap;
111    use u_nesting_core::api_types::{Pack3DResponse, Placement3DResponse, API_VERSION};
112    use u_nesting_core::geometry::Geometry;
113
114    let geom_by_id: HashMap<&str, &Geometry3D> =
115        geometries.iter().map(|g| (g.id().as_str(), g)).collect();
116
117    let placements = result
118        .placements
119        .iter()
120        .map(|p| {
121            let orientation = geom_by_id
122                .get(p.geometry_id.as_str())
123                .map(|g| g.orientation_label(p.rotation_index.unwrap_or(0)))
124                .unwrap_or_else(|| "xyz".to_string());
125            Placement3DResponse {
126                geometry_id: p.geometry_id.clone(),
127                instance: p.instance,
128                bin_index: p.boundary_index,
129                x: p.position.first().copied().unwrap_or(0.0),
130                y: p.position.get(1).copied().unwrap_or(0.0),
131                z: p.position.get(2).copied().unwrap_or(0.0),
132                orientation,
133            }
134        })
135        .collect();
136
137    let unplaced_count = result
138        .total_requested
139        .saturating_sub(result.placements.len());
140
141    Pack3DResponse {
142        version: API_VERSION.to_string(),
143        success: true,
144        error: None,
145        placements,
146        bins_used: result.boundaries_used,
147        utilization: result.utilization,
148        total_requested: result.total_requested,
149        unplaced: result.unplaced.clone(),
150        unplaced_count,
151        all_placed: unplaced_count == 0,
152        elapsed_ms: result.computation_time_ms,
153    }
154}
u_nesting_d3/lib.rs

u_nesting_d3/
lib.rs
