src/lib.rs

   1 // flow-rbp: A library for packing rectangles into two-dimensional finite bins.
   2 // zlib License (see LICENSE)
   3
   4 #![warn(missing_docs)]
   5
   6 //! This crates provides a library for packing rectangles into two-dimensional finite bins using
   7 //! different heuristic methods for placement.
   8 //!
   9 //! The two-dimensional rectangle bin packing is a classical problem in combinatorial optimization.
  10 //! In this problem, one is given a sequence of rectangles `(R1, R2, ... Rn), Ri = (wi, hi)` and
  11 //! the task is to find a packing of these items into a minimum number of bins of size `(W, H)`. No two
  12 //! rectangles may intersect or be contained inside one another. This library uses an algorithm
  13 //! sometimes referred as `The Maximal Rectangles ALgorithm`. This algorithm stores a list of free
  14 //! rectangles that represents the free area of the bin.
  15 //!
  16 //! Placement can be tweaked by using different heuristic methods such as
  17 //! [`ShortSideFit`](crate::rbp::FreeRectHeuristic::ShortSideFit),
  18 //! [`LongSideFit`](crate::rbp::FreeRectHeuristic::LongSideFit),
  19 //! [`AreaFit`](crate::rbp::FreeRectHeuristic::AreaFit),
  20 //! [`BottomLeft`](crate::rbp::FreeRectHeuristic::BottomLeft) and
  21 //! [`ContactPoint`](crate::rbp::FreeRectHeuristic::ContactPoint).
  22 //!
  23 //! # Examples
  24 //!
  25 //! ```
  26 //! use flow_rbp::FreeRectHeuristic;
  27 //! use flow_rbp::RectsBinPack;
  28 //!
  29 //! // create a new bin of size 32x32 which allows rotation:
  30 //! let mut rbp = RectsBinPack::new(32, 32, true).unwrap();
  31 //!
  32 //! // make sure occupancy is zero:
  33 //! assert_eq!(rbp.get_occupancy(), 0.0);
  34 //!
  35 //! // add a few rects that should fit:
  36 //! assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  37 //! assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  38 //! assert_eq!(rbp.get_occupancy(), 0.5);
  39 //! assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  40 //! assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  41 //! assert_eq!(rbp.get_occupancy(), 1.0);
  42 //!
  43 //! // this rect will not fit and therefore returns None:
  44 //! assert_eq!(rbp.insert(1, 1, FreeRectHeuristic::BottomLeft).is_none(), true);
  45 //!
  46 //! ```
  47
  48 #[doc(hidden)]
  49 pub mod rbp;
  50
  51 // re-export types:
  52 pub use crate::rbp::FreeRectHeuristic;
  53 pub use crate::rbp::Rect2D;
  54 pub use crate::rbp::RectsBinPack;
  55 pub use crate::rbp::RectsBinPackError;