Deterministic packing

v0.2.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rectangle-pack"
-version = "0.1.6"
+version = "0.2.0"
 authors = ["Chinedu Francis Nwafili <[email protected]>"]
 edition = "2018"
 keywords = ["texture", "atlas", "bin", "box", "packer"]

README.md

@@ -28,18 +28,22 @@ use rectangle_pack::{
     volume_heuristic,
     contains_smallest_box
 };
-use std::collections::HashMap;
+use std::collections::BTreeMap;
 
-// A rectangle ID just needs to meet these trait bounds (ideally also Copy)
-#[derive(Debug, Hash, PartialEq, Eq, Clone)]
+// A rectangle ID just needs to meet these trait bounds (ideally also Copy).
+// So you could use a String, PathBuf, or any other type that meets these
+// trat bounds. You do not have to use a custom enum.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 enum MyCustomRectId {
     RectOne,
     RectTwo,
     RectThree,
 }
 
 // A target bin ID just needs to meet these trait bounds (ideally also Copy)
-#[derive(Debug, Hash, PartialEq, Eq, Clone)]
+// So you could use a u32, &str, or any other type that meets these
+// trat bounds. You do not have to use a custom enum.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 enum MyCustomBinId {
     DestinationBinOne,
     DestinationBinTwo,
@@ -51,7 +55,10 @@ enum MyCustomBinId {
 // into the same bin. If this isn't possible an error is returned.
 //
 // Groups are optional.
-#[derive(Debug, Hash, PartialEq, Eq, Clone)]
+//
+// You could use an i32, &'static str, or any other type that meets these
+// trat bounds. You do not have to use a custom enum.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 enum MyCustomGroupId {
     GroupIdOne
 }
@@ -73,7 +80,7 @@ rects_to_place.push_rect(
     RectToInsert::new(30, 30, 255)
 );
 
-let mut target_bins = HashMap::new();
+let mut target_bins = BTreeMap::new();
 target_bins.insert(MyCustomBinId::DestinationBinOne, TargetBin::new(2048, 2048, 255));
 target_bins.insert(MyCustomBinId::DestinationBinTwo, TargetBin::new(4096, 4096, 1020));
 
@@ -134,18 +141,23 @@ The API shouldn't know about the specifics of any of these requirements - it sho
 
 ## Features
 
-- Minimalist, generic API that pushes as much as possible into user-land.
+- Place any number of 2d / 3d rectangles into any number of 2d / 3d target bins.
+  - Supports three dimensional rectangles through a width + height + depth based API.
 
-- Arbitrarily grouping rectangles to ensure that they are placed in the same bin(s).
+- Generic API that pushes as much as possible into user-land for maximum flexibility.
 
-- Supports three dimensional rectangles through a width + height + depth based API.
+- Group rectangles using generic group id's when you need to ensure that certain rectangles will always end up sharing a bin with each other.
 
 - Supports two dimensional rectangles (depth = 1).
 
 - User provided heuristics to grant full control over the packing algorithm.
 
 - Zero dependencies, making it easier to embed it inside of a more use case specific library without introducing bloat.
 
+- Deterministic packing.
+  - Packing of the same inputs using the same heuristics and the same sized target bins will always lead to the same layout.
+    - This is useful anywhere that reproducible builds are useful, such as when generating a texture atlas that is meant to be cached based on the hash of the contents.
+
 ## Future Work
 
 The first version of `rectangle-pack` was designed to meet my own needs.
@@ -162,7 +174,7 @@ This could be accomplished by:
 
 1. The API exposes three booleans for every incoming rectangles, `allow_global_x_axis_rotation`, `allow_global_y_axis_rotation`, `allow_global_z_axis_rotation`.
 
-2. Let's say all three are enabled. When attempting to place the rectangle/box we should attempt it in all 6 possible orientations and then select the best placement (based on the `MoreSuitableContainersFn` heuristic).
+2. Let's say all three are enabled. When attempting to place the rectangle/box we should attempt it in all 6 possible orientations and then select the best placement (based on the `ComparePotentialContainersFn` heuristic).
 
 3. Return information to the caller about which axis ended up being rotated.
 

src/bin_section.rs

@@ -16,7 +16,7 @@ use std::fmt::{Display, Formatter};
 ///
 /// Ordering::Greater means the first set of containers is better.
 /// Ordering::Less means the second set of containers is better.
-pub type MoreSuitableContainersFn =
+pub type ComparePotentialContainersFn =
     dyn Fn([WidthHeightDepth; 3], [WidthHeightDepth; 3], &BoxSizeHeuristicFn) -> Ordering;
 
 /// Select the container that has the smallest box.
@@ -27,8 +27,8 @@ pub fn contains_smallest_box(
     mut container2: [WidthHeightDepth; 3],
     heuristic: &BoxSizeHeuristicFn,
 ) -> Ordering {
-    container1.sort_unstable_by(|a, b| heuristic(*a).cmp(&heuristic(*b)));
-    container2.sort_unstable_by(|a, b| heuristic(*a).cmp(&heuristic(*b)));
+    container1.sort_by(|a, b| heuristic(*a).cmp(&heuristic(*b)));
+    container2.sort_by(|a, b| heuristic(*a).cmp(&heuristic(*b)));
 
     match heuristic(container2[0]).cmp(&heuristic(container1[0])) {
         Ordering::Equal => heuristic(container2[1]).cmp(&heuristic(container1[1])),
@@ -78,7 +78,7 @@ impl BinSection {
         BinSection { x, y, z, whd }
     }
 
-    // TODO: Delete - just the old API
+    // TODO: Delete - just the old API before we had the WidthHeightDepth struct
     fn new_spread(x: u32, y: u32, z: u32, width: u32, height: u32, depth: u32) -> Self {
         BinSection {
             x,
@@ -149,7 +149,7 @@ impl BinSection {
     pub fn try_place(
         &self,
         incoming: &RectToInsert,
-        container_comparison_fn: &MoreSuitableContainersFn,
+        container_comparison_fn: &ComparePotentialContainersFn,
         heuristic_fn: &BoxSizeHeuristicFn,
     ) -> Result<(PackedLocation, [BinSection; 3]), BinSectionError> {
         self.incoming_can_fit(incoming)?;
@@ -163,7 +163,7 @@ impl BinSection {
             self.width_largest_height_second_largest_depth_smallest(incoming),
         ];
 
-        all_combinations.sort_unstable_by(|a, b| {
+        all_combinations.sort_by(|a, b| {
             container_comparison_fn(
                 [a[0].whd, a[1].whd, a[2].whd],
                 [b[0].whd, b[1].whd, b[2].whd],

src/grouped_rects_to_place.rs

@@ -1,6 +1,6 @@
 use crate::RectToInsert;
-use std::collections::hash_map::Entry;
-use std::collections::HashMap;
+use std::collections::btree_map::Entry;
+use std::collections::{BTreeMap, HashMap};
 use std::fmt::Debug;
 use std::hash::Hash;
 
@@ -14,20 +14,22 @@ use std::hash::Hash;
 #[derive(Debug)]
 pub struct GroupedRectsToPlace<RectToPlaceId, GroupId = ()>
 where
-    RectToPlaceId: Debug + Hash + Eq,
-    GroupId: Debug + Hash + Eq,
+    RectToPlaceId: Debug + Hash + Eq + Ord + PartialOrd,
+    GroupId: Debug + Hash + Eq + Ord + PartialOrd,
 {
+    // FIXME: inbound_id_to_group_id appears to be unused. If so, remove it. Also remove the
+    //  Hash and Eq constraints on RectToPlaceId if we remove this map
     pub(crate) inbound_id_to_group_ids: HashMap<RectToPlaceId, Vec<Group<GroupId, RectToPlaceId>>>,
-    pub(crate) group_id_to_inbound_ids: HashMap<Group<GroupId, RectToPlaceId>, Vec<RectToPlaceId>>,
+    pub(crate) group_id_to_inbound_ids: BTreeMap<Group<GroupId, RectToPlaceId>, Vec<RectToPlaceId>>,
     pub(crate) rects: HashMap<RectToPlaceId, RectToInsert>,
 }
 
 /// A group of rectangles that need to be placed together
-#[derive(Debug, Hash, Eq, PartialEq)]
+#[derive(Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum Group<GroupId, RectToPlaceId>
 where
-    GroupId: Debug + Hash + Eq + PartialEq,
-    RectToPlaceId: Debug,
+    GroupId: Debug + Hash + Eq + PartialEq + Ord + PartialOrd,
+    RectToPlaceId: Debug + Ord + PartialOrd,
 {
     /// An automatically generated (auto incrementing) group identifier for rectangles that were
     /// passed in without any associated group ids.
@@ -43,8 +45,8 @@ where
 
 impl<RectToPlaceId, GroupId> GroupedRectsToPlace<RectToPlaceId, GroupId>
 where
-    RectToPlaceId: Debug + Hash + Clone + Eq,
-    GroupId: Debug + Hash + Clone + Eq,
+    RectToPlaceId: Debug + Hash + Clone + Eq + Ord + PartialOrd,
+    GroupId: Debug + Hash + Clone + Eq + Ord + PartialOrd,
 {
     /// Create a new `LayeredRectGroups`
     pub fn new() -> Self {
@@ -141,8 +143,8 @@ mod tests {
         );
 
         assert_eq!(
-            lrg.group_id_to_inbound_ids[&Group::Grouped(0)],
-            vec![RectToPlaceId::One, RectToPlaceId::Two]
+            lrg.group_id_to_inbound_ids.get(&Group::Grouped(0)).unwrap(),
+            &vec![RectToPlaceId::One, RectToPlaceId::Two]
         );
     }
 
@@ -184,7 +186,7 @@ mod tests {
         assert_eq!(lrg.rects[&RectToPlaceId::One], RectToInsert::new(10, 10, 1));
     }
 
-    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Ord, PartialOrd)]
     enum RectToPlaceId {
         One,
         Two,