From bf6128cb889094ad719b755f41bff52c19663fcf Mon Sep 17 00:00:00 2001 From: Chinedu Francis Nwafili Date: Mon, 9 Mar 2020 05:49:17 -0400 Subject: [PATCH] Document more suitable containers fn --- Cargo.toml | 2 +- README.md | 5 ++--- src/bin_section.rs | 9 +++++++++ src/lib.rs | 7 ++++--- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 23a3611..17287b8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rectangle-pack" -version = "0.1.0" +version = "0.1.1" authors = ["Chinedu Francis Nwafili "] edition = "2018" keywords = ["texture", "atlas", "bin", "box", "packer"] diff --git a/README.md b/README.md index bfdce98..e4b693e 100644 --- a/README.md +++ b/README.md @@ -189,11 +189,10 @@ We started with the algorithm described in [rectpack2D] and then made some adjus support our goal of flexibly supporting all use cases. -- The heuristic is provided by the caller instead of having `rectangle-pack` decide on the heuristic. +- The heuristic is provided by the caller instead of having `rectangle-pack` decide on a user provided heuristic. - When splitting an available section of a bin into two new sections of a bin - we do not decide on how the split should occur arbitrarily. - Instead, we base it on the heuristic. Whichever split (vertical or horizontal) produces the largest delta between the heuristic scores of the - two new bins will be used. + Instead, we base it on the user provided `more_suitable_containers` heuristic function. - There is a third dimension. diff --git a/src/bin_section.rs b/src/bin_section.rs index be0d3f3..cff1b98 100644 --- a/src/bin_section.rs +++ b/src/bin_section.rs @@ -4,6 +4,15 @@ use std::fmt::{Display, Formatter}; /// Given two sets of containers, which of these is the more suitable for our packing. /// +/// Useful when we're determining how to split up the remaining volume/area of a box/rectangle. +/// +/// For example - we might deem it best to cut the remaining region vertically, or horizontally, +/// or along the Z-axis. +/// +/// This decision is based on the more suitable contains heuristic. We determine all 6 possible +/// ways to divide up remaining space, sort them using the more suitable contains heuristic function +/// and choose the best one. +/// /// Ordering::Greater means the first set of containers is better. /// Ordering::Less means the second set of containers is better. pub type MoreSuitableContainersFn = diff --git a/src/lib.rs b/src/lib.rs index 65a7f5c..c47ba2c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,7 +8,8 @@ use std::fmt::{Debug, Display, Formatter}; use std::hash::Hash; pub use crate::bin_section::contains_smallest_box; -use crate::bin_section::{BinSection, MoreSuitableContainersFn}; +use crate::bin_section::BinSection; +pub use crate::bin_section::MoreSuitableContainersFn; use crate::grouped_rects_to_place::Group; pub use crate::grouped_rects_to_place::GroupedRectsToPlace; pub use crate::target_bin::TargetBin; @@ -369,7 +370,7 @@ mod tests { ) } - /// If we have two inbound rects the smallest one should be placed first. + /// If we have two inbound rects the largest one should be placed first. #[test] fn places_largest_rectangles_first() { let mut groups: GroupedRectsToPlace<_, ()> = GroupedRectsToPlace::new(); @@ -426,7 +427,7 @@ mod tests { /// /// 1. First place the largest rectangle into the smallest bin. /// - /// 2. Second place largest rectangle into the next available bin (i.e. the largest one). + /// 2. Second place the remaining rectangle into the next available bin (i.e. the largest one). #[test] fn two_rects_two_bins() { let mut groups: GroupedRectsToPlace<_, ()> = GroupedRectsToPlace::new();