Loading Instruction / extension draft / 7 Oct 2026

3D Build-up Instruction

Pack the pieces planned into each ULD inside its real contour, color them by AWB, and number them in loading order. The warehouse gets a build-up sheet per ULD. Planners can still move any piece by hand.

Starts from: AWB lines already planned into a ULD slot in the Loading Instruction editor. Assigning AWBs to ULDs stays as it is.
Produces: A 3D build per ULD with a loading sequence for every piece, plus build-up pages in the Loading Instruction PDF.
Builds on: ULD profiles in pkg/uldcode, accepted dims, SHC master data, the DGR checks in the planner, and three.js already in belli.

How the algorithm works

Each ULD is a 3D bin-packing problem with cargo rules attached. Exact solvers prove optimal builds only for small instances, so we use the extreme-point heuristic that published ULD systems use (see Algorithm research): place one piece at a time at the best legal spot, run that many times with shuffled orders, keep the best build. The prototype in screen 2 builds a 50-piece pallet in about 0.2 s. It runs in a Web Worker, bigger builds get a time budget, and the same seed always gives the same build.

Envelope
Containers use the decoder's profile polygon (AKE: 156 cm floor widening to 201 cm from 64 cm up) extruded over the 153 cm depth, door on the profile face. Pallets use the base footprint up to the slot's build contour (LD 163, Q6 244, Q7 300 cm), with 5 cm net clearance in the bottom 15 cm.
Pieces
Expand each AWB line into boxes: accepted dims first, booked dims second, then dims the planner typed in the 3D view. Lines with no dims wait in the AWB list until the planner enters them. Weight per piece comes from the dims line, else the AWB's planned weight split by volume. Handling flags (no stack, this way up; ISO 780 marks, not SHCs) are set by the planner per AWB line in the 3D view.
Pre-checks
SHC rules for the ULD, one offload station, door opening, max gross weight, floor load. Anything that fails is listed before packing, never dropped silently.
Order
AWB groups heaviest and densest first, larger bases first inside a group, no-stack and AVI groups last.
Place
Containers build walls from the back to the door: each wall takes the depth of its leading piece, heavy pieces fill its bottom rows, lighter ones fill up to the contour. Pallets build level layers: each layer takes the height of its leading piece, shorter pieces stack up to the layer top so the next layer sits flat, then the whole build is centred on the base. Inside a wall or layer, take the lowest, deepest, leftmost legal extreme point (a corner of a placed box pushed down, back and left), preferring the one touching the most surface. A no-stack piece goes where it wastes the least headroom.
Search
Repeat about 50 times, varying which piece sets each wall depth or layer height, swapping groups of similar weight and adding a little score noise. Keep the best build by placed volume, then unplaced pieces, CG offset from the base centre, CG height, heavy-on-light stacks, and AWB pieces left on their own.
Sequence
Build a "loads before" graph: a piece waits for everything it rests on and, in a container, everything behind it that it would block. Containers go wall by wall from the back to the door, bottom up. Pallets go layer by layer, centre out. Ties keep the same AWB together. Each piece gets a sequence number and "piece 3 of 8".

Rule	Kind	Default
Inside the contour	HARD	Pallets keep 5 cm net clearance below 15 cm
No overlap; nothing on no-stack or AVI pieces	HARD
Base support of a stacked piece	HARD	75% for cartons, 100% from 150 kg
This way up	HARD	Turn on the floor only, unless the piece may tip
Container door and wing	HARD	Fits the door (AKE 147 × 155 cm); wing takes pieces up to 30 kg
Max gross weight, floor load	HARD	ULD type max; AKE 976, PMC 1,952 kg/m²
SHC rules set to Block	HARD	Org settings (screen 3)
CAO dangerous goods	HARD	On an outer face, labels out
Pallet centre of gravity	WARN	Within ±10% of width and length, height ≤ 122 cm
One offload station per ULD	WARN	Mixed stations: first-off pieces at door or top
Heavy pieces low	STRATEGY	Bottom rows of every wall; the base layer of a pallet
Dense centred, AWB together	SCORE	Shapes the choice, never blocks

Walls for containers, layers for pallets

A container is loaded through one door, so it fills from the back wall forward and each wall must stand on its own before the next. A pallet is open on all sides and netted, so it rises in level layers: each layer gives the next a flat floor and keeps the outer faces square for the net.

Manual edits

Drag a piece across the floor: it snaps to neighbouring faces and settles on whatever is below. Every move re-runs the hard rules and the sequence. Lock keeps a piece where it is; Re-optimize repacks only the unlocked pieces around it.

Why not an exact optimiser

3D packing is NP-hard. Exact solvers prove optimal builds only for small instances and cannot explain their answer. The heuristic runs in a fraction of a second, every rule is a readable check, and a planner can see why a piece went where it did. How far it sits from optimal on Lion's own builds is still open (D9).

Sources for defaults

IATA ULD specs, AirBridgeCargo and Nippon Cargo build-up guidelines, DGR, AHM 333. Confirm values against Lion's own charts before go-live.

Algorithm research

What it is called. An extreme-point heuristic run inside wall building for containers and layer building for pallets, with deepest-bottom-left placement, as a randomized greedy search, with the loading sequence from a topological sort.

Which problem it solves. Operations research calls it the 3D container loading problem, a form of 3D bin packing. Air cargo literature calls ULD build-up the Air Cargo Palletization Problem, one of four parts of load planning next to aircraft configuration, build-up scheduling, and weight and balance (Brandt & Nickel 2019). Spreading AWBs across ULD types, phase 3 here, is the multiple bin size bin packing problem.

Why the order matters. A greedy packer never revisits a choice, so the order it is fed decides the result. Every strong method searches over orders and reuses one placement rule to turn each order into a layout.

Extreme points Crainic, Perboli & Tadei 2008: Candidate spots. When a box lands, its far corners slide back toward the origin until they touch something. About six per box, and locked boxes are supported.
Walls and layers George & Robinson 1980; Bischoff & Ratcliff 1995: Containers fill wall by wall from the back; pallets fill in level layers. Inside each, the lowest, then deepest, then leftmost spot wins.
Randomized greedy search: Run the greedy packer many times with shuffled orders and a little noise, score each whole build, keep the best.
Topological sort: Order the pieces so each comes after everything it rests on or would block. Ties pick the wall, the layer and the AWB.

Extreme points. After A and B land, their corners slide back and down until they touch something. Each dot is a spot where the next piece can nest. Piece C takes the lowest spot that passes every rule, then the deepest, then the leftmost.

Loading sequence. Q waits for P because it rests on P. R waits for P because it would block P from the door. Sorting the graph gives P, Q, R: the back wall first, bottom up, then toward the door.

Other algorithm families

Family	Key work	How it works	Fit for Belli
Extreme points in walls or layers, randomized greedy OURS	Crainic et al. 2008; Heßler et al. 2024	Fill walls (containers) or layers (pallets) one piece at a time at the best legal spot, repeat with shuffled orders, keep the best build	A fraction of a second per build, every rule is a readable filter, handles contoured ULDs and locked pieces
Exact: MIP, branch and bound, constraint solvers	Martello, Pisinger & Vigo 2000; Paquay et al. 2016	A solver searches box positions under no-overlap constraints and proves the best answer	Optimal, but only small instances finish in practical time. Use offline to measure our gap
Wall building	George & Robinson 1980	Fill vertical walls from the back to the door, one box type per wall	Our container strategy, with extreme points inside each wall to handle mixed cargo
Layer building	Bischoff & Ratcliff 1995	Stack horizontal layers of similar height	Our pallet strategy; short pieces stack up to the layer top to keep it level
Block building + search	Parreño et al. 2008; Fanslau & Bortfeldt 2010; Araya et al. 2017	Group identical boxes into blocks, place blocks into empty cuboid spaces, search over the choices	Best on the standard benchmarks (about 90 to 96% fill). Blocks of one AWB keep it together. Seconds to minutes per build
Evolve the order	Gonçalves & Resende 2013	A genetic algorithm evolves box order and orientation; a placement rule like ours turns each one into a layout	Best upgrade path: reuses our placement code, an estimated 1 to 3 s in a worker
Heightmap (2.5D)	Robotic palletizing	Track a grid of heights and place where the surface stays flattest	Gravity and support come naturally, but no overhangs
Deep reinforcement learning	Zhao et al. 2021, 2022	A neural network picks each placement, trained in simulation	Built for robots that cannot see the next box. We know every piece, and it cannot explain itself. Skip
Stability and sequence	Ramos, Oliveira & Lopes 2016	Physics-based stability check, then the real loading order from a finished layout	Better than our 75% area rule; confirms our sequence-after-layout approach

Closest published work

Paquay, Limbourg & Schyns, 2018

Extreme points extended to contoured ULDs, with fragility, stability, orientation and weight capacity. A second phase picks which ULD types to use.

Heßler, Hintsch & Wienkamp, 2024

DB Schenker. Extreme points inside a randomized greedy search for cuboid and contoured ULDs, with stability, non-stackable items and CG limits. Reports better utilization than Paquay. The same design as ours.

TU Delft thesis, 2024

A MIP for small builds and an extreme-point heuristic for large ones, then scheduling the builds across warehouse workstations.

Upgrades worth borrowing, cheapest first

Five sort rules
Rotate between total AWB volume, largest piece, stackable first and random orders, and bias the noise toward the greedy pick instead of flat noise (Heßler et al.). Cheap and proven on ULDs.
Better stability
Accept a piece when all four bottom corners rest on something (Heßler et al.), or check its centre of gravity against the contact area (Ramos et al.), instead of a flat 75% of the base.
Spots on slopes
A candidate spot that lands on the AKE slope moves up until a box fits ("moving extreme points", Heßler et al.), which recovers wing space.
AWB blocks
Glue identical pieces of one AWB into a block before placing it. Cohesion and flat tops come free, with fewer decisions to make.
Genetic algorithm
Evolve order and orientation with our placement as the decoder (Gonçalves & Resende). Only if auto-build misses the D14 target.
Offline benchmark
Solve small real Lion builds exactly with a MIP (Paquay et al. 2016) to measure how far auto-build is from optimal.

Sources

Screens

Four screens on top of the current Load Planning editor. Dashed orange outlines mark what is new. Screen 2 runs the algorithm above on sample AWBs.

Load Planning editor: a build-up strip on every ULD card

Status, fill and one action per ULD, plus Auto-build all beside Add ULD. AWB lines are collapsed here to keep the cards short.

Operations / Load Planning

JT 0034CGK → DPS08 Oct 2026Draft v3

Saved

ULDs 4

AKE #16

Lower deckLD-3 (64 in)

PERPESELICOU

Weight

Volume

Built

PMC #16

Lower deckLD (64 in)

HEAPEREATELI

Weight

Volume

Needs rebuildPlan changed after build: +4 pcs on 990-55210120. 3 locked pieces stay put.

AKE #23

Lower deckLD-3 (64 in)

HUMEATHUM with EAT: blocked by rule

Weight412 / 1,588 kg

Volume2.1 / 4.3 m³

BlockedMove 990-55210186 (EAT) to another ULD to build.

PAG #13

Lower deckLD (64 in)

GEN

Weight1,240 / 6,033 kg

Volume6.4 / 10.8 m³

Not built18 pcs on 3 AWBs, all with dims.

3D build-up (live mock)

Opens full page from a ULD card. Scrub the loading sequence, click a piece to inspect it, drag the selected piece to move it, lock it, then re-optimize the rest. Ctrl + scroll or the buttons zoom.

3D build-upJT 0034

ULD contourCurrent step

Settings, Operations: Build-up rules

Org rules for SHCs that must not share a ULD, and the solver defaults. The planner's existing DGR checks appear as read-only system rules. The same rules also warn or block when an AWB is dropped into a ULD in the 2D planner.

Build-up rules

Applied when AWBs are planned into a ULD and when a ULD is built in 3D.

If a ULD contains	It must not also contain	When broken	Note for planners
Org rules
HUM	EATPESPEMPEP	Block	Human remains never travel with foodstuffs (AHM 333).
VAL	Any other cargo	Block	Valuables go alone in a sealed ULD.
HUM	AVI	Warn	Airline policy, not a technical rule.
PEF	PEP	Warn	Ethylene from fruit wilts flowers.
System rules (DGR, read only)
RPBRIS	AVIEATPESPEMPEP	Warn	DGR 9.3.14
RCLICE	AVI	Warn	DGR 9.3.13
RRY	AVIFIL	Warn	DGR 10.9.3
Explosives	Classes in Table 9.3.A	Warn	DGR Table 9.3.A, 9.3.2.2.5

Build-up defaults

Used by Auto-build and by the checks on manual moves.

Minimum base supportFor cartons. Pieces from 150 kg always need full support.%

Max piece weight in a container wingHeavy pieces in the wing can tip the container.kg

Pallet net clearanceNo cargo this close to the edge in the bottom 15 cm.cm

Pallet CG toleranceOf base width and length, measured from the centre.%

Keep AWB pieces togetherScores builds that keep each AWB in one block.

New build-up rule

Planners see this rule when both sides meet in one ULD, in the 2D planner and in the 3D build.

If a ULD contains

AVI + Add SHC

It must not also contain

EAT PER + Add SHC

Any other cargo

When broken

Block stops Auto-build and Publish until an AWB moves out.

Note for planners

Live animals do not travel with food in the same ULD.

Build-up sheet (PDF page per ULD)

Manifest header, the finished build, one plan per wall (per layer on pallets), the loading sequence and a sign-off box. Generated from the same AKE #1 build as screen 2. Long ULDs continue the table on a second page.

BUILD-UP INSTRUCTION

Loading Instruction v3, ULD AKE #1

Page 1 of 2
Printed 07 Oct 2026 14:20

Owner or operatorJT

RegistrationPK-LEO

Flight no.JT 0034

Date08 OCT 2026

Point of loadingCGK

Point of unloadingDPS

Finished build, seen from the door sideNumbers = loading sequence

Plan per wall, seen from the doorGrey = walls behind

Seq	AWB	Pc	L × W × H cm	Kg	Wall	Spot

ULD serial

Actual tare (kg)

Scale gross (kg)

Contour check ☐

Built by

Checked by

Generated by Belli from Loading Instruction v3 draft. Positions in cm from the back-left floor corner.JT 0034 / AKE #1

Data and API

Area	Change
ULD geometry	Nothing new for IATA types: `pkg/uldcode` already returns `base_mm` and a profile polygon for 14 container nicknames, and a pallet slot is its base up to the build contour height. Add door size per container profile and an optional override for non-IATA types. Chamfered pallet contours (Q6 on 767F, Q7 side positions on 747F) vary by aircraft position, so they come later with position data.
Pieces	Read `order_acceptance_dimensions` (pieces × L × W × H as accepted), fall back to booking `parcels` (which also carry per-piece weight). Dims the planner types for lines without any, and the `no_stack` / `this_way_up` flags, are stored with the build-up per AWB line, not on the AWB. Acceptance does not change. ONE Record's Piece carries the same two flags if they later move to acceptance.
SHC rules	New org table `build_up_rules`: codes, cannot-share codes or any other cargo, block or warn, note, active. The pairs in `lib/dg-segregation.ts` stay as read-only system rules.
Plan snapshot	Each slot in the version snapshot gets `build_up`: status, seed, placements (piece key, x, y, z, rotation, wall or layer, seq, locked) and metrics. Piece key = AWB + dims line + ordinal. Draft, publish and lock behave as today.
Server checks	Save and publish re-check bounds, overlaps and Block rules. The API never re-runs the solver.
3D and PDF	`three`, `@react-three/fiber` and `drei` are already dependencies (W&B prototype). The PDF draws its own isometric, wall and layer views as react-pdf SVG, like screen 4.

Open decisions

#	Question	Status	Recommendation or decision
D1	Where does the solver run?	Decided 8 Oct	Web Worker in the browser, so re-optimize is instant while dragging. The API only validates.
D2	AWB lines without dims	Decided 8 Oct	Decided against the cube default: the planner enters dims for those lines in the 3D view. Saved with the build-up only, not written back to the AWB. Lines without dims stay out of the build until entered.
D3	How is a piece identified?	Decided 8 Oct	AWB + dims line + ordinal ("piece 3 of 8"). Belli has no piece barcodes today.
D4	SHC rule scope in v1	Decided 8 Oct	Same ULD only. Distances inside a ULD (RRY transport index, AVI above dry ice) come later.
D5	Which rules ship as defaults?	Decided 8 Oct	The never-mix pairs: HUM with foodstuffs plus the DGR set. Policy pairs (HUM with AVI, AVI with EAT, PEP with PEF, VAL alone) wait for Lion's own chart.
D6	What happens when the plan changes after a build?	Decided 8 Oct	Mark the ULD "Needs rebuild", keep locked pieces, repack the rest when the planner asks.
D7	Pallet contour shape	Decided 8 Oct	Rectangle up to the build contour height in v1, which covers Lion's A330 lower deck. Per-position chamfers before freighter customers.
D8	Where does the sheet live?	Decided 8 Oct	Build-up pages inside the Loading Instruction PDF. A QR code to a tablet 3D view comes later.
D9	How good must auto-build be?	Decided 8 Oct	Decided: a fixed target that auto-build is tuned to meet (see D14). The cheap upgrades ship in v1; the genetic algorithm only if the target is missed.
D10	An AWB split across ULDs: which pieces go where?	Decided 8 Oct	The 3D build assigns specific pieces to each ULD, largest first into the first ULD, and the planner can swap them in 3D. Stored with the build-up; the 2D plan keeps piece counts only.
D11	When are "no stack" and "this way up" captured?	Decided 8 Oct	The planner sets them per AWB line in the 3D view; acceptance does not change. Default: stackable, this way up.
D12	Dims typed by the planner, then accepted dims arrive: which wins?	Decided 8 Oct	The planner's dims win until the planner clears them. When accepted dims arrive and differ, the line shows an "Accepted dims differ" hint with a one-click switch.
D13	Measure how many AWBs have piece dims before building?	Decided 8 Oct	Not measured; build anyway. Planners fill gaps through D2.
D15	Validate the printed sheet with the warehouse before rollout?	Decided 8 Oct	No pilot. The sheet rolls out with the Loading Instruction release.
D14	What is the fill target, and how is it measured?	Decided 8 Oct	Auto-build must place every planned piece whenever their total volume is at most 70% of the contour volume. This becomes a solver acceptance test.

Phasing

1See it

Envelope from the decoder and slot contour
Piece expansion; missing dims and handling flags entered in the 3D view
Solver with five sort rules, read-only 3D view, sequence
Build-up pages in the PDF

2Shape it

Drag, rotate, lock, re-optimize
Build-up rules settings
Same rules in the 2D planner

3Extend it

Tablet view from a QR code
Auto-assign AWBs across ULDs
Separation distances, per-position contours
Load-bearing limits per piece
Genetic algorithm if the D14 target is missed

Draft for discussion. Sample AWBs, agents and dims are invented. Geometry from pkg/uldcode; rule values from IATA ULD specs, AirBridgeCargo and Nippon Cargo build-up guidelines, DGR and AHM 333, to be confirmed against Lion's charts.