DOCS / TUTORIAL

Getting started in Go

Add the Go module, build items and containers from validated specs, call Pack(), and read why an item was left out.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Go 1.13 or newer, standard library only. The module 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.

go get github.com/packvium/packvium-go

02Build items and containers#

A Spec struct describes an item or a container, and the New constructor validates it. Lengths are decimal strings with a unit, so a fractional inch such as "12 3/8" is stored exactly and never rounded to millimetres.

bookSize, _ := domain.DimensionsOf("210", "140", "30", "mm")
boxSize, _ := domain.DimensionsOf("400", "300", "250", "mm")
spec := domain.NewItemSpec("book", bookSize)
spec.Quantity = 4
book, err := domain.NewItem(spec)
if err != nil {
	log.Fatal(err)
}
box, err := domain.NewContainer(domain.ContainerSpec{ID: "box", InnerDimensions: boxSize})
if err != nil {
	log.Fatal(err)
}

03Run Pack() and read the result#

The packer takes a configuration and the extension set, here none. Every value in the result is immutable and reached through accessors; positions are exact integer ticks.

balanced, _ := config.New(config.Default(config.Balanced))
result, err := packer.New(balanced, algorithm.NoExtensions()).Pack([]*domain.Item{book}, []*domain.Container{box})
if err != nil {
	log.Fatal(err)
}
fmt.Println(result.Status) // feasible
for _, container := range result.Containers {
	for _, placement := range container.Placements() {
		// Coordinates are exact ticks: 1/16000 mm.
		fmt.Println(placement.Instance().ID(), placement.Position().X(), placement.Rotation())
	}
}

04Handle items the engine could not place#

Each refused unit is listed in result.Unpacked with a structured reason. explain.UnpackedItem turns that reason into a sentence, so the refusal can be shown to a person without teaching them the reason codes.

for _, unpacked := range result.Unpacked {
	text, err := explain.UnpackedItem(unpacked)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(unpacked.Instance.Item().ID(), text)
}

05The same JSON contract, from the command line#

cmd/packvium reads the JSON request every other engine reads, from a file argument or standard input, and writes the result JSON to standard output. A refused request exits with status 1 and prints the reason on standard error.

go build -o packvium ./cmd/packvium
echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],"containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' | ./packvium

06Hand the result to a warehouse system#

Package artifacts 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. It exports canonical JSON, a CSV and a printable HTML work order, and calls no solver, renderer or clock. For the same result the bytes are the ones every other engine builds.

// order is a loading order from sequence.SafeLoadingOrder, as examples/artifacts computes it.
artifact, err := artifacts.Build(request, result, map[int][]int{0: order})
if err != nil {
	log.Fatal(err)
}
fmt.Println(artifact["format"]) // packvium-operational-artifact/v1

canonical, _ := artifacts.ExportJSON(artifact)     // RFC 8785, the bytes every engine emits
csv, _ := artifacts.ExportCSV(artifact)            // RFC 4180, one row per step and unplaced item
html, _ := artifacts.ExportWorkOrderHTML(artifact) // a self-contained page to print

07Where 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 and the commerce cases. Outside that corpus the port is stricter in two places: lengths and weights are 64-bit ticks, so a value that would overflow is refused, and the JSON literals NaN and Infinity are refused.

08Next 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: one runnable program per topic, each checked against the reference engine's output.