README.md

   1 # flow-rbp
   2
   3 `flow-rbp` is a library for packing rectangles into two-dimensional finite bins
   4 using different heuristic methods for placement.
   5
   6 The two-dimensional rectangle bin packing is a classical problem in
   7 combinatorial optimization. In this problem, one is given a sequence of
   8 rectangles `(R1, R2, ... Rn), Ri = (wi, hi)` and the task is to find a packing
   9 of these items into a minimum number of bins of size `(W, H)`. No two
  10 rectangles may intersect or be contained inside one another. This library uses
  11 an algorithm sometimes referred as `The Maximal Rectangles ALgorithm`. This
  12 algorithm stores a list of free rectangles that represents the free area of the
  13 bin.
  14
  15 ## Usage
  16
  17 Add this to your `Cargo.toml`:
  18
  19 ```
  20 [dependencies]
  21 flow-rbp = { git = "https://luflow.net/git/flow-rbp.git", tag = "v0.1.0" }
  22 ```
  23
  24 Then:
  25
  26 ```rust
  27 use flow_rbp::FreeRectHeuristic;
  28 use flow_rbp::RectsBinPack;
  29
  30 // create a new bin of size 32x32 which allows rotation:
  31 let mut rbp = RectsBinPack::new(32, 32, true).unwrap();
  32
  33 // make sure occupancy is zero:
  34 assert_eq!(rbp.get_occupancy(), 0.0);
  35
  36 // add a few rects that should fit:
  37 assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  38 assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  39 assert_eq!(rbp.get_occupancy(), 0.5);
  40 assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  41 assert_eq!(rbp.insert(16, 16, FreeRectHeuristic::BottomLeft).is_some(), true);
  42 assert_eq!(rbp.get_occupancy(), 1.0);
  43
  44 // this rect will not fit and therefore returns None:
  45 assert_eq!(rbp.insert(1, 1, FreeRectHeuristic::BottomLeft).is_none(), true);
  46
  47 ```
  48
  49 ## LICENSE
  50
  51 See the file 'LICENSE' for license information.