Fold: the drawing folded in 3D

POST /fold runs the template with the values given and folds it as ParametrIQ's 3D view does, with the same engine: its cut lines cut out the panels, and its creases (and perforations, partial cuts and V-cuts) fold them. The board is as thick as the template's T variable (the material's thickness, as the material sets give it), or half a millimetre if it has none.

It comes back as meshes ready to draw with WebGL, three.js, a game engine or anything else that draws triangles, at a number of steps from flat (0) to folded (1). Go between two steps yourself to animate it smoothly: the Viewer does exactly this. The body is a template (as template, or as source from one of your storages) and values for its labelled variables, as described on the API page, and optionally steps: how many fold values to give, from 2 to 33 (9 if left out), and appearance: how it is to look, an appearance's id from GET /appearances ("denim", "corrugated-bc-kraft", "stainless-brushed" …). Left out, it looks as the appearance for the drawing's material does (its T choice, "BC double wall (7 mm)"), else as plain white board.

What comes back

Field	What it is
`steps`	The fold values the meshes are given at, from 0 to 1. A design that is slow to fold (a curved crease bends the sheet at every step) is given fewer; the last is always 1.
`thickness`	The board's thickness, in the drawing's units.
`target`, `cameraDistance`	Where to look (the design's centre, x y z) and from how far.
`floorZ`	Where the floor is, just under the flat blank. Z is up.
`sun`	Where the sun is (x, y, z), the radius its shadow map covers, and how wide the floor is.
`net`	The flat net's min x, y, width and height: the faces' texture coordinates span it.
`look`	How it looks: the appearance's `id`, `name` and the `material` it was chosen for; `registers`, the 3D shader's appearance registers (four floats each, from register `register`), as the Viewer and ParametrIQ's 3D view use them; `seeThrough` and the tinted `shadow` such a material casts; the `images` it names.
`creases`	At each step, the creases whose grooves show on the inside: base64 of float32 a.x, a.y, b.x, b.y each, in the net.
`meshes`	Each mesh: its `name`, `kind` (`Panel`, `Fillet` or `Flex`), whether it is `doubleSided`, its `shapes`, its place at each step, and its `parent`: the mesh it turns relative to (an index into `meshes`, −1 for none).
`warnings`	What couldn't be folded as drawn.

Each of a mesh's shapes is a triangle list (no indices):

positions: base64 of little-endian float32 x, y, z for each vertex;
normals: base64 of int8 x, y, z for each vertex, each component ×127;
uvs: base64 of float32 u, v for each vertex: a face's place in net (0 to 1), an edge's distance along it and depth into the board (over twice the thickness);
edge (corrugated and honeycomb only): base64 of float32, seven for each vertex: the flutes' and cells' data the shader needs to draw the cut edge;
groups: start vertex, vertex count and material group (0 inside, 1 outside, 2 edge), in threes.

Each of its steps (one per fold value) gives its matrix there (a 4×4 matrix, row by row, acting on column vectors), which shape it has (−1 for none) and whether it is visible. A shape that doesn't change between steps is sent once.

To draw fold value f between steps a and b, place the meshes parents first. For a mesh with a parent, take its matrix relative to the parent at each step (the parent's matrix inverted, times its own), go between those two as a screw motion (the turn from one to the other as a turn about one fixed axis, plus a slide along it, taken a fraction of the way), and put the result on the parent's place at f. A panel then turns about its hinge and stays on its fold line all the way. (Blending each world matrix on its own, position in a straight line and rotation by slerp, carries a panel off its hinge between the steps: tens of millimetres on a carton.) A mesh with no parent goes between its two matrices as a screw motion too. If its two shapes differ but have as many vertices, blend their positions as well. Each crease folds over part of the way from flat to folded, one after another, so more steps follow the order of folding more closely.

No content (204) comes back if the drawing has nothing to fold (no cut lines).

Example

POST /fold
X-API-KEY: your-api-key
Content-Type: application/json

{
  "template": "…a carton's drawing text…",
  "values": { "L": 120, "W": 60, "D": 180 },
  "steps": 5
}

{
  "steps": [0, 0.25, 0.5, 0.75, 1],
  "thickness": 0.45,
  "target": [100.8, 75.4, 31.2],
  "cameraDistance": 420.5,
  "floorZ": -0.425,
  "sun": [281.1, -158.8, 772.4, 220.3, 1056.2],
  "net": [-12, -98.5, 210.4, 330],
  "look": { "id": "gc2-board", "name": "GC2 folding boxboard, white back", "material": "Folding boxboard 0.45 mm",
            "register": 35, "registers": [0, -1, 0.45, 0, …], "seeThrough": false, "shadow": [0, 0, 0, 0, 0.003], "images": [] },
  "creases": [ "AAAAAA…", … ],
  "meshes": [
    {
      "name": "s0", "kind": "Panel", "doubleSided": false,
      "shapes": [ { "positions": "AAAAAAAA…", "normals": "AAB/AAB/…", "uvs": "AAAAAA…", "groups": [0, 6, 0, 6, 6, 1, 12, 558, 2] } ],
      "steps": [ { "matrix": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], "shape": 0, "visible": true }, … ],
      "parent": -1
    },
    …
  ],
  "warnings": []
}

A typical carton is about 1 MB of JSON at 9 steps, and about a tenth of that compressed: ask for it compressed (Accept-Encoding: br, gzip).

See also: API, Appearances, Measure, Viewer.