Packvium for Python

Deterministic 3D cartonization and rectangular bin packing. Pure Python, no runtime dependencies, exact integer geometry.

Version 0.1.2 — early release. The public API is not frozen; pin an exact version. Read docs/GUARANTEES.md before relying on a result.

pip install packvium

Quick start

from packvium import Container, Dimensions, Item, Packer, PackingConfig

result = Packer(PackingConfig.balanced()).pack(
    items=[Item.create("book", Dimensions.mm("210", "140", "30"), quantity=4)],
    containers=[Container.create("box", Dimensions.mm("400", "300", "250"))],
)

print(result.status)                      # feasible
for container in result.containers:
    for placement in container.placements:
        print(placement.item_id, placement.position, placement.orientation)

Fractional inches are exact, not approximated:

Dimensions.inches("12 3/8", "8 1/2", "3/4")

There is also a CLI that reads a JSON request on standard input:

echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],
       "containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' \
  | python -m packvium

Examples

Runnable, in examples/. Each one is a single file you can read top to bottom and execute without a project around it. Every one of them is executed by the test suite on each release, so none of them can quietly stop working.

New here? Read basic.py, then objectives.py — between them they cover what most callers need. units.py and serialization.py explain the two design choices that surprise people. extensions.py is last on purpose: reach for it only after the fields in constraints.py have failed you.

PYTHONPATH=src python3 examples/objectives.py

What it does

• Exact arithmetic. Length is measured in ticks of 1/16000 mm and weight in 1/8 µg. No coordinate is ever a float, so no placement decision depends on rounding.
• Real constraints. Weight and payload limits, permitted rotations, keep-upright, floor-only, non-stackable, top-load limits, minimum support ratio, tag incompatibility, clearance and rectangular obstacles.
• A solver portfolio, not one algorithm. Regular-grid, layer, extreme-point, maximal-space and bounded exact search, selected by problem shape and profile.
• Answers you can check. Every solution is re-validated by logic independent of the search. Unplaced items come back with a reason code, not silently missing.
• Deterministic. The same input and seed produce the same result, always.
• Multi-container and nested. Split across containers, or pack containers into containers.
• Extensible. Register your own constraints, item orderings, candidate scorers, container selectors or complete solvers.

Documentation

Requirements

Python 3.9 or newer. No dependencies.

The Packvium family

One request and result contract, implemented independently in four engines (Rust, Python, PHP, JavaScript) and held to identical placements on a shared fixture set. Pick the package for your stack; mixing them in one system is safe.

Contributing

See CONTRIBUTING.md. Security reports go through the process in SECURITY.md, not public issues.

License

MIT. See LICENSE.