# ExBoxPacker v0.2.0 - Table of Contents

> A faithful Elixir port of the BoxPacker 3D bin-packing / box-selection library.

## Pages

- [ExBoxPacker](readme.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

## Modules

- [ExBoxPacker](ExBoxPacker.md): A faithful Elixir port of [BoxPacker](https://github.com/dvdoug/BoxPacker) (PHP, v4.2.0), a 3D
bin-packing and box-selection engine. Given a set of items and a catalog of candidate boxes, it
chooses which boxes to use and computes how to physically arrange the items inside each one:
orthogonal rotation (`:never` / `:keep_flat` / `:best_fit`), per-box weight limits, weight
redistribution across boxes, stability, and optional placement constraints.
- [ExBoxPacker.Broadcast](ExBoxPacker.Broadcast.md): Config-driven event publisher for a live packing feed. No callbacks: when
`ExBoxPacker.Config.broadcast/0` is set (and `absinthe` is loaded), each event is
published via `Absinthe.Subscription.publish(endpoint, event, [{field, topic}])`.
- [ExBoxPacker.Broadcast.Event](ExBoxPacker.Broadcast.Event.md): A packing event streamed to subscribers: `:started`, `:box_packed`, or `:done`.
- [ExBoxPacker.Config](ExBoxPacker.Config.md): Single-key config reader. All library configuration lives under one key
- [ExBoxPacker.ConstrainedPlacementItem](ExBoxPacker.ConstrainedPlacementItem.md): Optional protocol for items with custom placement rules (e.g. max quantity per box, no
stacking). `can_be_packed?/8` is consulted for each candidate placement; return false to
forbid it. Implementing this slows packing. Port of BoxPacker's `ConstrainedPlacementItem`.

- [ExBoxPacker.LimitedSupplyBox](ExBoxPacker.LimitedSupplyBox.md): Optional protocol for boxes with a finite supply. A box implementing this is only used up
to `quantity_available/1` times. Boxes that do not implement it are treated as unlimited.
Port of BoxPacker's `LimitedSupplyBox`.

- [ExBoxPacker.LinkedItem](ExBoxPacker.LinkedItem.md): Optional protocol marking items that belong to a named group which must all ship together
in the same box (never split across boxes). Port of BoxPacker's `LinkedItem`.

- [ExBoxPacker.PackerPreview](ExBoxPacker.PackerPreview.md): A `forward`-able Plug that renders a 3D preview of packings captured via
`ExBoxPacker.Preview`.
- [ExBoxPacker.Preview](ExBoxPacker.Preview.md): Opt-in capture hook for the `ExBoxPacker.PackerPreview` dev visualiser.
- [ExBoxPacker.Preview.Collector](ExBoxPacker.Preview.Collector.md): In-memory store of recent packings for the `ExBoxPacker.PackerPreview` dev tool. Holds a
bounded ring buffer and notifies subscribed Server-Sent-Events connections of new packings.
Add it to your supervision tree (typically dev-only) to enable the preview.

- Packing
  - [ExBoxPacker.Engine.VolumePacker](ExBoxPacker.Engine.VolumePacker.md): Packs items into a single box. Functional port of BoxPacker's `VolumePacker`. Tries both
box footprint rotations (unless single-pass or the item set forbids rotation) and each
special first-item orientation, returning the permutation that packs the most (an exact
full pack short-circuits; otherwise highest volume utilisation).

  - [ExBoxPacker.Packer](ExBoxPacker.Packer.md): Top-level multi-box packer with catalog box selection. Faithful port of BoxPacker's
`Packer::doBasicPacking` + `getBoxList`.

- Items &amp; Boxes
  - [ExBoxPacker.Box](ExBoxPacker.Box.md): A box/container available for packing. Elixir analog of BoxPacker's `Box` interface.
  - [ExBoxPacker.Item](ExBoxPacker.Item.md): An item to be packed. Elixir analog of BoxPacker's `Item` interface.
  - [ExBoxPacker.Rotation](ExBoxPacker.Rotation.md): Allowed rotation modes for an item, mirroring BoxPacker's `Rotation` enum.
  - [ExBoxPacker.SimpleBox](ExBoxPacker.SimpleBox.md): A ready-made `ExBoxPacker.Box` implementation for the common case.
  - [ExBoxPacker.SimpleItem](ExBoxPacker.SimpleItem.md): A ready-made `ExBoxPacker.Item` implementation for the common case.

- Results
  - [ExBoxPacker.Result.PackedBox](ExBoxPacker.Result.PackedBox.md): A box together with the items packed into it, plus computed weight, space and
utilisation accessors. Port of BoxPacker's `PackedBox`.

  - [ExBoxPacker.Result.PackedBoxList](ExBoxPacker.Result.PackedBoxList.md): A collection of `ExBoxPacker.Result.PackedBox` with aggregate statistics. Port of BoxPacker's
`PackedBoxList`. Iteration/`to_list` order is defined by the configured `PackedBoxSorter`.

  - [ExBoxPacker.Result.PackedItem](ExBoxPacker.Result.PackedItem.md): An item placed inside a box: back-left-bottom corner at `(x, y, z)` with the given
post-rotation `width`/`length`/`depth`. `volume` is precomputed. Port of BoxPacker's `PackedItem`.

  - [ExBoxPacker.Result.PackedItemList](ExBoxPacker.Result.PackedItemList.md): A collection of `ExBoxPacker.Result.PackedItem` with cached total weight and volume.
Port of BoxPacker's `PackedItemList`.

- Sorting
  - [ExBoxPacker.Sorting.BoxSorter](ExBoxPacker.Sorting.BoxSorter.md): Behaviour for ordering candidate boxes (analog of BoxPacker's `BoxSorter`).
  - [ExBoxPacker.Sorting.DefaultBoxSorter](ExBoxPacker.Sorting.DefaultBoxSorter.md): Default box ordering: inner volume asc, then empty weight asc, then usable capacity asc.
  - [ExBoxPacker.Sorting.DefaultItemSorter](ExBoxPacker.Sorting.DefaultItemSorter.md): Default item ordering: volume desc, then weight desc, then description asc.
  - [ExBoxPacker.Sorting.DefaultPackedBoxSorter](ExBoxPacker.Sorting.DefaultPackedBoxSorter.md): Default packed-box ordering: item count desc, then volume utilisation desc, then used volume desc.
  - [ExBoxPacker.Sorting.ItemSorter](ExBoxPacker.Sorting.ItemSorter.md): Behaviour for ordering items before packing (analog of BoxPacker's `ItemSorter`).
  - [ExBoxPacker.Sorting.PackedBoxSorter](ExBoxPacker.Sorting.PackedBoxSorter.md): Behaviour for choosing the best packed box during selection (analog of BoxPacker's `PackedBoxSorter`).

- Errors
  - [ExBoxPacker.NoBoxesAvailableError](ExBoxPacker.NoBoxesAvailableError.md): Raised (by `pack!/3`) or returned in `{:error, _}` (by `pack/3`) when an item cannot be
packed into any available box. `affected_items` holds the items that could not be packed.
Port of BoxPacker's `NoBoxesAvailableException`.

- Exceptions
  - [ExBoxPacker.TimeoutError](ExBoxPacker.TimeoutError.md): Raised when packing exceeds the configured timeout. Port of BoxPacker's `TimeoutException`.

