diff --git a/jagua-rs/src/collision_detection/mod.rs b/jagua-rs/src/collision_detection/mod.rs index 2bc00ba..c26e4c8 100644 --- a/jagua-rs/src/collision_detection/mod.rs +++ b/jagua-rs/src/collision_detection/mod.rs @@ -1,5 +1,8 @@ +/// Collision detection engine itself pub mod cd_engine; pub mod hazard; pub mod hazard_filter; + +/// Everything related to the Hazard Proximity Grid pub mod hpg; pub mod quadtree; diff --git a/jagua-rs/src/entities/bin.rs b/jagua-rs/src/entities/bin.rs index ebd9af9..6d1bcd5 100644 --- a/jagua-rs/src/entities/bin.rs +++ b/jagua-rs/src/entities/bin.rs @@ -14,15 +14,20 @@ use crate::geometry::transformation::Transformation; use crate::util::config::CDEConfig; /// A `Bin` is a container in which items can be placed. -/// Its interior is defined by an outer polygon and zero or more holes. #[derive(Clone, Debug)] pub struct Bin { pub id: usize, + /// The contour of the bin pub outer: Arc, + /// The cost of using the bin pub value: u64, + /// Every bin is centered around its centroid (using this transformation) pub centering_transform: Transformation, + /// Shapes of holes/defects in the bins, if any pub holes: Vec>, + /// Zones of different qualities in the bin, stored per quality. pub quality_zones: [Option; N_QUALITIES], + /// The starting state of the `CDEngine` for this bin. pub base_cde: Arc, pub area: f64, } @@ -62,7 +67,7 @@ impl Bin { let base_cde = CDEngine::new( outer.bbox().inflate_to_square(), - Self::generate_hazards(&outer, &holes, &quality_zones), + Bin::generate_hazards(&outer, &holes, &quality_zones), cde_config, ); let base_cde = Arc::new(base_cde); @@ -80,6 +85,7 @@ impl Bin { } } + /// Create a new `Bin` for a strip-packing problem. Instead of a shape, the bin is always rectangular. pub fn from_strip(id: usize, width: f64, height: f64, cde_config: CDEConfig) -> Self { let poly = SimplePolygon::from(AARectangle::new(0.0, 0.0, width, height)); let value = poly.area() as u64; @@ -99,27 +105,25 @@ impl Bin { holes: &[Arc], quality_zones: &[Option], ) -> Vec { + //Hazard induced by the outside of the bin let mut hazards = vec![Hazard::new(HazardEntity::BinExterior, outer.clone())]; + + //Hazard induced by any holes in the bin hazards.extend(holes.iter().enumerate().map(|(i, shape)| { let haz_entity = HazardEntity::BinHole { id: i }; Hazard::new(haz_entity, shape.clone()) })); - hazards.extend( - quality_zones - .iter() - .flatten() - .map(|q_zone| { - q_zone.zones.iter().enumerate().map(|(id, shape)| { - let haz_entity = HazardEntity::QualityZoneInferior { - quality: q_zone.quality, - id, - }; - Hazard::new(haz_entity, shape.clone()) - }) - }) - .flatten(), - ); + //Hazards induced by quality zones + for q_zone in quality_zones.iter().flatten() { + for (id, shape) in q_zone.zones.iter().enumerate() { + let haz_entity = HazardEntity::QualityZoneInferior { + quality: q_zone.quality, + id, + }; + hazards.push(Hazard::new(haz_entity, shape.clone())); + } + } hazards } diff --git a/jagua-rs/src/entities/instances/bin_packing.rs b/jagua-rs/src/entities/instances/bin_packing.rs index 891c101..71b1802 100644 --- a/jagua-rs/src/entities/instances/bin_packing.rs +++ b/jagua-rs/src/entities/instances/bin_packing.rs @@ -12,7 +12,7 @@ pub struct BPInstance { pub items: Vec<(Item, usize)>, /// Total area of all items in the instance pub item_area: f64, - + /// Set of bins available to pack the items, along with their quantities pub bins: Vec<(Bin, usize)>, } diff --git a/jagua-rs/src/entities/instances/strip_packing.rs b/jagua-rs/src/entities/instances/strip_packing.rs index 8e9173a..9dff304 100644 --- a/jagua-rs/src/entities/instances/strip_packing.rs +++ b/jagua-rs/src/entities/instances/strip_packing.rs @@ -6,8 +6,11 @@ use crate::geometry::geo_traits::Shape; /// The items are to be packed in such a way that the total width of the strip used is minimized. #[derive(Debug, Clone)] pub struct SPInstance { + /// The items to be packed and their quantities pub items: Vec<(Item, usize)>, + /// The total area of the items pub item_area: f64, + /// The (fixed) height of the strip pub strip_height: f64, } diff --git a/jagua-rs/src/entities/item.rs b/jagua-rs/src/entities/item.rs index d9b79a6..ce43aad 100644 --- a/jagua-rs/src/entities/item.rs +++ b/jagua-rs/src/entities/item.rs @@ -6,7 +6,7 @@ use crate::geometry::primitives::simple_polygon::SimplePolygon; use crate::geometry::transformation::Transformation; use crate::util::config::SPSurrogateConfig; -/// An `Item` can be placed in a `Bin`. +/// An `Item` to be placed in a `Bin`. #[derive(Clone, Debug)] pub struct Item { pub id: usize, diff --git a/jagua-rs/src/entities/placing_option.rs b/jagua-rs/src/entities/placing_option.rs index 4c58df6..83121af 100644 --- a/jagua-rs/src/entities/placing_option.rs +++ b/jagua-rs/src/entities/placing_option.rs @@ -5,9 +5,13 @@ use crate::geometry::transformation::Transformation; #[derive(Clone, Debug)] /// Encapsulates all required information to place an `Item` in a `Problem` pub struct PlacingOption { + /// Which layout to place the item in pub layout_index: LayoutIndex, + /// The id of the item to be placed pub item_id: usize, + /// The transformation to be applied to the item pub transform: Transformation, + /// The decomposition of the transformation pub d_transform: DTransformation, } diff --git a/jagua-rs/src/geometry/geo_enums.rs b/jagua-rs/src/geometry/geo_enums.rs index 7f22f96..21ade9c 100644 --- a/jagua-rs/src/geometry/geo_enums.rs +++ b/jagua-rs/src/geometry/geo_enums.rs @@ -23,7 +23,10 @@ pub enum GeoRelation { #[derive(Clone, Debug, PartialEq)] pub enum AllowedRotation { + /// No rotation is allowed None, + /// Any rotation is allowed Continuous, + /// Only a limited set of rotations is allowed Discrete(Vec), } diff --git a/jagua-rs/src/io/json_instance.rs b/jagua-rs/src/io/json_instance.rs index 3152190..8884cb6 100644 --- a/jagua-rs/src/io/json_instance.rs +++ b/jagua-rs/src/io/json_instance.rs @@ -25,8 +25,8 @@ pub struct JsonInstance { pub struct JsonBin { /// The cost of using this bin pub cost: u64, - /// Number of this bin available - pub stock: u64, + /// Number of this bin available, if not present, it is assumed to be unlimited + pub stock: Option, /// Polygon shape of the bin pub shape: JsonPoly, /// A list of zones with different quality levels @@ -47,8 +47,7 @@ pub struct JsonStrip { pub struct JsonItem { /// Number of times this item should be produced pub demand: u64, - /// List of allowed orientations angles (in degrees). - /// Some(_) if only the specified angles are allowed; None if continuous rotation is allowed + /// List of allowed orientations angles (in degrees), if not present, any orientation is allowed #[serde(skip_serializing_if = "Option::is_none")] pub allowed_orientations: Option>, /// Polygon shape of the item diff --git a/jagua-rs/src/io/parser.rs b/jagua-rs/src/io/parser.rs index 8051ca9..c7e5ec9 100644 --- a/jagua-rs/src/io/parser.rs +++ b/jagua-rs/src/io/parser.rs @@ -32,6 +32,7 @@ use crate::util::config::CDEConfig; use crate::util::polygon_simplification; use crate::util::polygon_simplification::{PolySimplConfig, PolySimplMode}; +/// Parses a `JsonInstance` into an `Instance`. pub struct Parser { poly_simpl_config: PolySimplConfig, cde_config: CDEConfig, @@ -51,6 +52,7 @@ impl Parser { } } + /// Parses a `JsonInstance` into an `Instance`. pub fn parse(&self, json_instance: &JsonInstance) -> Instance { let mut items: Vec<(Item, usize)> = vec![]; let mut instance = None; @@ -171,8 +173,9 @@ impl Parser { quality_zones, self.cde_config, ); + let stock = json_bin.stock.unwrap_or(u64::MAX) as usize; - (bin, json_bin.stock as usize) + (bin, stock) }); bin_join_handles.push(handle); } @@ -219,6 +222,7 @@ impl Parser { instance } + /// Parses a `JsonInstance` and accompanying `JsonLayout`s into an `Instance` and `Solution`. pub fn parse_and_build_solution( &self, json_instance: &JsonInstance, @@ -232,6 +236,7 @@ impl Parser { } } +/// Builds a `Solution` from a set of `JsonLayout`s and an `Instance`. fn build_solution_from_json( json_layouts: &[JsonLayout], instance: Arc, @@ -335,6 +340,7 @@ fn build_solution_from_json( problem.create_solution(&None) } +/// Composes a `JsonSolution` from a `Solution` and an `Instance`. pub fn compose_json_solution( solution: &Solution, instance: &Instance, @@ -442,7 +448,7 @@ fn json_shape_to_simple_polygon( (shape, centering_transform) } -pub fn simple_json_shape_to_simple_polygon( +fn simple_json_shape_to_simple_polygon( s_json_shape: &JsonSimplePoly, center_polygon: bool, simpl_config: PolySimplConfig, diff --git a/jagua-rs/src/lib.rs b/jagua-rs/src/lib.rs index e1928c2..b7efcb0 100644 --- a/jagua-rs/src/lib.rs +++ b/jagua-rs/src/lib.rs @@ -1,5 +1,14 @@ +/// Everything collision detection engine related pub mod collision_detection; + +/// Entities to model 2D irregular cutting and packing problems pub mod entities; + +/// Geometric primitives and base algorithms pub mod geometry; + +/// Parser and JSON (de)serialization pub mod io; + +/// Helper functions pub mod util; diff --git a/jagua-rs/src/util/mod.rs b/jagua-rs/src/util/mod.rs index 1283730..46d7c43 100644 --- a/jagua-rs/src/util/mod.rs +++ b/jagua-rs/src/util/mod.rs @@ -1,11 +1,17 @@ use crate::entities::layout::Layout; +/// Set of functions used throughout assure the correctness of the library. pub mod assertions; + +/// Configuration options for the library pub mod config; + pub mod f64a; + +/// Functions to simplify polygons in preprocessing pub mod polygon_simplification; -///Intended for debugging purposes +///Prints code to recreate a layout. Intended for debugging purposes. pub fn print_layout(layout: &Layout) { println!( "let mut layout = Layout::new(0, instance.bin({}).clone());",