Backport packing enhancements from 3.1.0

.scrutinizer.yml

@@ -24,3 +24,4 @@ build:
         coverage:
             file: 'build/behat.clover'
             format: 'clover'
+      - php-scrutinizer-run

.travis.yml

@@ -1,3 +1,4 @@
+group: travis_latest
 language: php
 sudo: false
 

behat.yml

@@ -1,7 +1,13 @@
 default:
+  suites:
+    packer:
+      paths:
+        - '%paths.base%/features/common'
+      contexts: [ PackerContext ]
+
   extensions:
     LeanPHP\Behat\CodeCoverage\Extension:
-      auth:       ~
+      auth: ~
       drivers:
         - local
       filter:
@@ -15,6 +21,6 @@ default:
               'src':
                 prefix: ''
       report:
-        format:   clover
+        format: clover
         options:
           target: build/behat.clover

docs/conf.py

@@ -46,7 +46,7 @@
 
 # General information about the project.
 project = u'BoxPacker'
-copyright = u'2017, Doug Wright'
+copyright = u'2018, Doug Wright'
 author = u'Doug Wright'
 
 # The version info for the project you're documenting, acts as replacement for

docs/index.rst

@@ -11,7 +11,6 @@ License
 -------
 BoxPacker is licensed under the `MIT license`_.
 
-.. _NP-hard problem: http://en.wikipedia.org/wiki/Bin_packing_problem
 .. _MIT license: https://github.com/dvdoug/BoxPacker/blob/master/license.txt
 
 

docs/principles.rst

@@ -16,8 +16,6 @@ At a high level, the algorithm works like this:
  * Pack largest (by volume) items first
  * Pack vertically up the side of the box
  * Pack side-by-side where item under consideration fits alongside the previous item
- * Only very small overhangs are allowed (10%) to prevent items bending in transit
- * The available width/height for each layer will therefore decrease as the stack of items gets taller
  * If more than 1 box is needed to accommodate all of the items, then aim for boxes of roughly equal weight
    (e.g. 3 medium size/weight boxes are better than 1 small light box and 2 that are large and heavy)
 

features/bootstrap/FeatureContext.php → features/bootstrap/PackerContext.php

@@ -16,22 +16,25 @@
 /**
  * Defines application features from the specific context.
  */
-class FeatureContext implements Context
+class PackerContext implements Context
 {
     /** @var Box */
-    private $box;
+    protected $box;
 
     /** @var BoxList */
-    private $boxList;
+    protected $boxList;
 
     /** @var ItemList */
-    private $itemList;
+    protected $itemList;
 
     /** @var PackedBox */
-    private $packedBox;
+    protected $packedBox;
 
     /** @var PackedBoxList */
-    private $packedBoxList;
+    protected $packedBoxList;
+
+    /** @var string */
+    protected $packerClass = 'DVDoug\BoxPacker\Packer';
 
     /**
      * Initializes context.
@@ -121,7 +124,8 @@ public function thereIsAKeepFlatItem(
      */
     public function iDoAPacking()
     {
-        $packer = new Packer();
+        /** @var Packer $packer */
+        $packer = new $this->packerClass();
         $packer->setBoxes($this->boxList);
         $packer->setItems($this->itemList);
         $this->packedBoxList = $packer->pack();

license.txt

@@ -1,4 +1,4 @@
-Copyright (C) 2012-2017 Doug Wright
+Copyright (C) 2012-2018 Doug Wright
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/ItemList.php

@@ -42,7 +42,7 @@ public function compare($itemA, $itemB)
     /**
      * Get copy of this list as a standard PHP array.
      *
-     * @return array
+     * @return Item[]
      */
     public function asArray()
     {

src/ItemTooLargeException.php

@@ -8,11 +8,13 @@
 
 namespace DVDoug\BoxPacker;
 
+use RuntimeException;
+
 /**
  * Class ItemTooLargeException
  * Exception used when an item is too large to pack.
  */
-class ItemTooLargeException extends \RuntimeException
+class ItemTooLargeException extends RuntimeException
 {
     /** @var Item */
     public $item;

src/LayerStabiliser.php

@@ -0,0 +1,70 @@
+<?php
+/**
+ * Box packing (3D bin packing, knapsack problem).
+ *
+ * @author Doug Wright
+ */
+
+namespace DVDoug\BoxPacker;
+
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
+
+/**
+ * Applies load stability to generated result.
+ *
+ * @author Doug Wright
+ */
+class LayerStabiliser implements LoggerAwareInterface
+{
+    use LoggerAwareTrait;
+
+    /**
+     * Constructor.
+     */
+    public function __construct()
+    {
+        $this->logger = new NullLogger();
+    }
+
+    /**
+     * @param PackedLayer[] $packedLayers
+     *
+     * @return PackedLayer[]
+     */
+    public function stabilise(array $packedLayers)
+    {
+        // first re-order according to footprint
+        $stabilisedLayers = [];
+        usort($packedLayers, [$this, 'compare']);
+
+        // then for each item in the layer, re-calculate each item's z position
+        $currentZ = 0;
+        foreach ($packedLayers as $oldZLayer) {
+            $oldZStart = $oldZLayer->getStartDepth();
+            $newZLayer = new PackedLayer();
+            foreach ($oldZLayer->getItems() as $oldZItem) {
+                $newZ = $oldZItem->getZ() - $oldZStart + $currentZ;
+                $newZItem = new PackedItem($oldZItem->getItem(), $oldZItem->getX(), $oldZItem->getY(), $newZ, $oldZItem->getWidth(), $oldZItem->getLength(), $oldZItem->getDepth());
+                $newZLayer->insert($newZItem);
+            }
+
+            $stabilisedLayers[] = $newZLayer;
+            $currentZ += $newZLayer->getDepth();
+        }
+
+        return $stabilisedLayers;
+    }
+
+    /**
+     * @param PackedLayer $layerA
+     * @param PackedLayer $layerB
+     *
+     * @return int
+     */
+    private function compare(PackedLayer $layerA, PackedLayer $layerB)
+    {
+        return ($layerB->getFootprint() - $layerA->getFootprint()) ?: ($layerB->getDepth() - $layerA->getDepth());
+    }
+}

src/OrientatedItemFactory.php

@@ -19,16 +19,26 @@ class OrientatedItemFactory implements LoggerAwareInterface
 {
     use LoggerAwareTrait;
 
+    /** @var Item */
+    protected $item;
+
+    /** @var Box */
+    protected $box;
+
     /**
      * @var OrientatedItem[]
      */
     protected static $emptyBoxCache = [];
 
+    public function __construct(Item $item, Box $box)
+    {
+        $this->item = $item;
+        $this->box = $box;
+    }
+
     /**
      * Get the best orientation for an item.
      *
-     * @param Box                 $box
-     * @param Item                $item
      * @param OrientatedItem|null $prevItem
      * @param Item|null           $nextItem
      * @param bool                $isLastItem
@@ -39,17 +49,15 @@ class OrientatedItemFactory implements LoggerAwareInterface
      * @return OrientatedItem|null
      */
     public function getBestOrientation(
-        Box $box,
-        Item $item,
-        $prevItem,
-        $nextItem,
+        OrientatedItem $prevItem = null,
+        Item $nextItem = null,
         $isLastItem,
         $widthLeft,
         $lengthLeft,
         $depthLeft
     ) {
-        $possibleOrientations = $this->getPossibleOrientations($item, $prevItem, $widthLeft, $lengthLeft, $depthLeft);
-        $usableOrientations = $this->getUsableOrientations($possibleOrientations, $box, $item, $isLastItem);
+        $possibleOrientations = $this->getPossibleOrientations($this->item, $prevItem, $widthLeft, $lengthLeft, $depthLeft);
+        $usableOrientations = $this->getUsableOrientations($possibleOrientations, $isLastItem);
 
         if (empty($usableOrientations)) {
             return;
@@ -72,9 +80,9 @@ public function getBestOrientation(
                 if ($nextItem) {
                     $nextItemFitA = count($this->getPossibleOrientations($nextItem, $a, $orientationAWidthLeft, $orientationALengthLeft, $depthLeft));
                     $nextItemFitB = count($this->getPossibleOrientations($nextItem, $b, $orientationBWidthLeft, $orientationBLengthLeft, $depthLeft));
-                    if ($nextItem && $nextItemFitA && !$nextItemFitB) {
+                    if ($nextItemFitA && !$nextItemFitB) {
                         return -1;
-                    } elseif ($nextItem && $nextItemFitB && !$nextItemFitA) {
+                    } elseif ($nextItemFitB && !$nextItemFitA) {
                         return 1;
                     }
                 }
@@ -102,7 +110,7 @@ public function getBestOrientation(
      */
     public function getPossibleOrientations(
         Item $item,
-        $prevItem,
+        OrientatedItem $prevItem = null,
         $widthLeft,
         $lengthLeft,
         $depthLeft
@@ -135,36 +143,33 @@ public function getPossibleOrientations(
     }
 
     /**
-     * @param Item $item
-     * @param Box  $box
-     *
      * @return OrientatedItem[]
      */
-    public function getPossibleOrientationsInEmptyBox(Item $item, Box $box)
+    public function getPossibleOrientationsInEmptyBox()
     {
-        $cacheKey = $item->getWidth().
+        $cacheKey = $this->item->getWidth().
             '|'.
-            $item->getLength().
+            $this->item->getLength().
             '|'.
-            $item->getDepth().
+            $this->item->getDepth().
             '|'.
-            ($item->getKeepFlat() ? '2D' : '3D').
+            ($this->item->getKeepFlat() ? '2D' : '3D').
             '|'.
-            $box->getInnerWidth().
+            $this->box->getInnerWidth().
             '|'.
-            $box->getInnerLength().
+            $this->box->getInnerLength().
             '|'.
-            $box->getInnerDepth();
+            $this->box->getInnerDepth();
 
         if (isset(static::$emptyBoxCache[$cacheKey])) {
             $orientations = static::$emptyBoxCache[$cacheKey];
         } else {
             $orientations = $this->getPossibleOrientations(
-                $item,
+                $this->item,
                 null,
-                $box->getInnerWidth(),
-                $box->getInnerLength(),
-                $box->getInnerDepth()
+                $this->box->getInnerWidth(),
+                $this->box->getInnerLength(),
+                $this->box->getInnerDepth()
             );
             static::$emptyBoxCache[$cacheKey] = $orientations;
         }
@@ -174,34 +179,25 @@ public function getPossibleOrientationsInEmptyBox(Item $item, Box $box)
 
     /**
      * @param OrientatedItem[] $possibleOrientations
-     * @param Box              $box
-     * @param Item             $item
      * @param bool             $isLastItem
      *
      * @return OrientatedItem[]
      */
     protected function getUsableOrientations(
         $possibleOrientations,
-        Box $box,
-        Item $item,
         $isLastItem
     ) {
-        /*
-         * Divide possible orientations into stable (low centre of gravity) and unstable (high centre of gravity)
-         */
-        $stableOrientations = [];
-        $unstableOrientations = [];
+        $orientationsToUse = $stableOrientations = $unstableOrientations = [];
 
-        foreach ($possibleOrientations as $o => $orientation) {
+        // Divide possible orientations into stable (low centre of gravity) and unstable (high centre of gravity)
+        foreach ($possibleOrientations as $orientation) {
             if ($orientation->isStable()) {
                 $stableOrientations[] = $orientation;
             } else {
                 $unstableOrientations[] = $orientation;
             }
         }
 
-        $orientationsToUse = [];
-
         /*
          * We prefer to use stable orientations only, but allow unstable ones if either
          * the item is the last one left to pack OR
@@ -210,14 +206,7 @@ protected function getUsableOrientations(
         if (count($stableOrientations) > 0) {
             $orientationsToUse = $stableOrientations;
         } elseif (count($unstableOrientations) > 0) {
-            $orientationsInEmptyBox = $this->getPossibleOrientationsInEmptyBox($item, $box);
-
-            $stableOrientationsInEmptyBox = array_filter(
-                $orientationsInEmptyBox,
-                function (OrientatedItem $orientation) {
-                    return $orientation->isStable();
-                }
-            );
+            $stableOrientationsInEmptyBox = $this->getStableOrientationsInEmptyBox();
 
             if ($isLastItem || count($stableOrientationsInEmptyBox) == 0) {
                 $orientationsToUse = $unstableOrientations;
@@ -226,4 +215,21 @@ function (OrientatedItem $orientation) {
 
         return $orientationsToUse;
     }
+
+    /**
+     * Return the orientations for this item if it were to be placed into the box with nothing else.
+     *
+     * @return array
+     */
+    protected function getStableOrientationsInEmptyBox()
+    {
+        $orientationsInEmptyBox = $this->getPossibleOrientationsInEmptyBox();
+
+        return array_filter(
+            $orientationsInEmptyBox,
+            function (OrientatedItem $orientation) {
+                return $orientation->isStable();
+            }
+        );
+    }
 }