DOCS / TUTORIAL

Getting started in .NET

Add the Packvium NuGet package, build items and containers, call Packer.Pack(), read why an item was left out, and export a work order.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

NuGet package Packvium, for .NET 8 and .NET 10, with no runtime dependencies. It 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.

dotnet add package Packvium

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

Items and containers are immutable values. Every length is a string so that it can be exact: Dimensions.Inches("12 3/8", "8 1/2", "3/4") is stored as written and never rounded to millimetres. Positions come back as points in exact integer ticks of 1/16000 mm.

using Packvium.Domain;
using Packvium.Packing;

var result = new Packer(PackingConfig.Balanced()).Pack(
    [new Item("book", Dimensions.Mm("210", "140", "30"), quantity: 4)],
    [new Container("box", Dimensions.Mm("400", "300", "250"))]);

Console.WriteLine(result.Status.Value());               // feasible
foreach (var container in result.Containers)
{
    foreach (var placement in container.Placements)
    {
        Console.WriteLine($"{placement.Instance.Id} {placement.Position} {placement.Rotation}");
    }
}

03Handle items the engine could not place#

Each refused unit is listed in result.Unpacked with a reason code and the level of proof behind it, proven, observed, inferred or unknown_due_to_limit, so a refusal can be shown with how far to trust it.

foreach (var unpacked in result.Unpacked)
{
    // A reason code, and the level of proof behind it: proven, observed, inferred or unknown_due_to_limit.
    Console.WriteLine($"{unpacked.Instance.Item.Id}: {unpacked.Reason} ({unpacked.Proof.Level})");
}

04Pack a JSON request#

The JSON document every other engine reads is the same contract here. JsonApi.PackFromJson takes the request and returns the result document; a malformed request throws with the reference engine's message before any search runs.

using Packvium.Serialization;

var request = JsonReader.Parse("""
    {"items": [{"id": "box", "quantity": 8, "dimensions": {"length": "50", "width": "50", "height": "50"}}],
     "containers": [{"id": "carton", "inner_dimensions": {"length": "100", "width": "100", "height": "100"}}]}
    """);
var result = JsonApi.PackFromJson(request);

Console.WriteLine(PythonJson.Dumps(result, sortKeys: true, indent: 2));

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.

using Packvium.Artifacts;
using Packvium.Serialization;

var request = (JsonObject)JsonReader.Parse(requestJson);
var result = JsonApi.PackFromJson(request);

JsonObject artifact = OperationalArtifact.Build(request, result);
string json = ArtifactExports.Json(artifact);            // RFC 8785, the bytes every engine builds
string csv = ArtifactExports.Csv(artifact);              // CRLF rows, quoted only where needed
string html = ArtifactExports.WorkOrderHtml(artifact);   // no script, no external resource

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: 398 packing fixtures, the execution plan of each, 419 operational-artifact cases, the commerce cases and the operator-lock scenarios. Outside that corpus the port differs in a few places: lengths and weights are 64-bit ticks, so a value that would overflow is refused, a few schema-invalid values are refused where Python would coerce them, and there is no parallel portfolio.

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 repository, whose tests run every example against the reference output.