DOCS / TUTORIAL

Getting started in Java

Add com.packvium:packvium, build items and containers with builders, call Packer.pack(), and read why an item was left out.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Java 17 or newer, no runtime dependencies. The artifact is released on its own line rather than with the suite: 1.3.0 implements the 1.3.0 contract, so request fields added in 1.4 and later, a pallet overhang limit for one, are not in it yet and are refused with unsupported_feature.

implementation("com.packvium:packvium:1.3.0")

02Build items, run pack() and read the result#

Items and containers are immutable values made by builders. Lengths are decimal strings, so Dimensions.inches("12 3/8", "8 1/2", "3/4") is stored exactly and never rounded to millimetres. Positions come back as exact integer ticks.

import com.packvium.Packer;
import com.packvium.config.PackingConfig;
import com.packvium.domain.Container;
import com.packvium.domain.Dimensions;
import com.packvium.domain.Item;
import com.packvium.domain.PackedContainer;
import com.packvium.domain.Placement;
import com.packvium.result.PackingResult;
import java.util.List;

PackingResult result = new Packer(PackingConfig.balanced()).pack(
        List.of(Item.builder("book", Dimensions.mm("210", "140", "30")).quantity(4).build()),
        List.of(Container.builder("box", Dimensions.mm("400", "300", "250")).build()));

System.out.println(result.status().wireName());   // feasible
for (PackedContainer container : result.containers()) {
    for (Placement placement : container.placements()) {
        // book#1 Point[x=0, y=0, z=0] HWL -- coordinates are exact ticks (1/16000 mm)
        System.out.println(placement.instance().id() + " " + placement.position() + " " + placement.rotation());
    }
}

03Handle items the engine could not place#

Each refused unit is listed in result.unpacked() with a structured reason. Explain.unpackedItem, in com.packvium.explain, turns that reason into a sentence, so the refusal can be shown to a person without teaching them the reason codes.

for (UnpackedItem unpacked : result.unpacked()) {
    System.out.println(unpacked.instance().item().id() + " " + Explain.unpackedItem(unpacked));
}

04Pack a JSON request#

The JSON document every other engine reads is the same contract here. JsonReader, RequestPacker and JsonWriter live in com.packvium.serialization: parse the request, pack it, and read the result as the map the contract describes.

Map<?, ?> request = (Map<?, ?>) JsonReader.parse(REQUEST);
Map<String, Object> result = RequestPacker.pack(request);

System.out.println(JsonWriter.write(result.get("unpacked_items")));

05Hand the result to a warehouse system#

OperationalArtifact builds the operational artifact: the plan, the box sizes in ticks, the values a work order prints and the request that produced it, as one document. ArtifactExports turns it into canonical JSON, a CSV and a printable HTML work order, with no solver, renderer or clock involved. For the same result the bytes are the ones every other engine builds.

Map<String, Object> result = RequestPacker.pack(request);
// The loading order comes from LoadingDependencyGraph.safeLoadingOrder; without one the
// work order's steps are not numbered.
Map<String, Object> artifact = OperationalArtifact.build(request, result, Map.of(0, List.of(1, 0)));
String json = ArtifactExports.json(artifact);               // RFC 8785: the same bytes in every engine
String csv = ArtifactExports.csv(artifact);                 // a row per step, then a row per unplaced item
String workOrder = ArtifactExports.workOrderHtml(artifact); // one self-contained page, no script

06Where it differs from the reference engine#

A valid request gets the reference engine's result, byte for byte, on the 1.3.0 conformance corpus. Outside that corpus the port differs in one place: lengths and weights are 64-bit ticks, so a value that would overflow is refused.

07Next steps#

Read the request and result contract for the fields the port serves, those up to 1.3, run your own dimensions in the Playground, or open the examples directory of the repository: eleven files that run with the JDK source launcher, each checked against the reference engine's output.