printCAD GitHub Download

Scripting

printCAD runs Lua 5.4 scripts. Everything the application and its workbenches can do by command is a function under pc, called with named arguments in braces:

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 30, height = 20}
local pad = pc.design.pad{sketch = s, length = 12}
pc.design.set{feature = pad, length = 20}

The Design workbench's commands also answer to part (pc.part.pad, part.set), so older scripts, recordings and key settings keep working.

Where scripts run

Working with commands

Recording

Scripts › Record… records what you do from then on; Stop saves it as recording_<n>.lua in the scripts folder, where the Scripts menu lists it. The status bar shows the recording with a Stop button.

A click and a script run the same code: every tool ends in the command it stands for, and the recording is the list of those commands.

Variables and formulas

Any number of a feature can be set by a formula over variables and other objects' dimensions, and follows when they change:

pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm"}
pc.var.set{set = "Printer", name = "wall", formula = "3 * Printer.nozzle"}
local pad = pc.design.pad{sketch = s, length = 5}
pc.doc.set_formula{id = pad, parameter = "length", formula = "Printer.wall * 10"}
print(pc.var.eval{formula = "Pad.length"}.text)  -- 12 mm

pc.doc.parameters{id = ...} lists a feature's numbers and what formulas call them. See Variables and formulas for what a formula can say.

Examples

A plate with a centred hole, sized from the command line, written as 3MF:

-- A plate with a hole, sized from the command line
local w, h = tonumber(arg[1]) or 40, tonumber(arg[2]) or 30
local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = w, height = h}
local pad = pc.design.pad{sketch = s, length = 4}
local body = pc.doc.feature{id = pad}.body
local hole = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.circle{sketch = hole, x = w / 2, y = h / 2, radius = 3}
pc.design.pocket{sketch = hole, through_all = true}
pc.doc.rebuild()
print(pc.doc.measure{body = body}.volume)
pc.file.export{path = "plate.3mf"}

A constrained sketch:

local s = pc.sketch.new{}
local line = pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 30, y2 = 2}
pc.sketch.constrain{sketch = s, kind = "horizontal", items = {line}}
pc.sketch.constrain{sketch = s, kind = "dimension", items = {line}, value = 25}
print(show(pc.sketch.status{sketch = s}))

One body on another:

local top = function(body)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] > 0.99 then return f end
  end
end
local bottom = function(body)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] < -0.99 then return f end
  end
end
pc.asm.mate{body = lid, face = bottom(lid), other = box, other_face = top(box)}

Longer workflows, each a script that checks what it made, are under recipes.

Commands

Some commands carry notes (what they refuse, do without saying, or are easily mistaken for) and an example. The test suite runs every example of every command, and every recipe, from an empty document, so they work as written.

doc

pc.doc.info: The document's name, file and unit.

Notes:

Example: A new document, edited.

local info = pc.doc.info()
assert(info.unit == "mm" and info.file == nil and not info.modified)
pc.sketch.new{plane = "XY"}
assert(pc.doc.info().modified, "an edit marks it modified")

pc.doc.agent_rules: The rules an AI agent keeps to on this document; Preferences hold the ones for every document.

Notes:

See also pc.doc.set_agent_rules.

pc.doc.set_agent_rules: Set the rules an AI agent working on this document keeps to; they are saved with the document.

Notes:

See also pc.doc.agent_rules.

pc.doc.bodies: List the bodies.

Notes:

See also pc.doc.features, pc.doc.set_body.

Example: A padded block's one body.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.doc.set_body{body = body, material = {name = "PLA", density = 1.24}}
local bodies = pc.doc.bodies()
assert(#bodies == 1 and bodies[1].id == body and bodies[1].visible)
assert(bodies[1].features[1] == s and bodies[1].features[2] == pad)
assert(bodies[1].material.name == "PLA")
assert(math.abs(bodies[1].material.density - 1.24) < 1e-6)

pc.doc.features: List the features in build order.

Notes:

See also pc.doc.feature, pc.doc.bodies.

Example: A pad and its sketch, in order.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local list = pc.doc.features{body = body}
assert(#list == 2)
assert(list[1].id == s and list[1].kind == "Sketch")
assert(list[2].id == pad and list[2].kind == "Pad" and list[2].error == nil)
assert(not list[1].visible, "a pad hides its sketch")

pc.doc.feature: A feature with its fields.

Notes:

See also pc.doc.parameters, pc.doc.features.

Example: A pad's length, kept and worked out.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local f = pc.doc.feature{id = pad}
assert(f.kind == "Pad" and f.fields.Pad.length == 5 and f.fields.Pad.sketch == s)
assert(f.values == nil, "no formula: values is fields")
pc.doc.set_formula{id = pad, parameter = "length", formula = "2 * 4 mm"}
f = pc.doc.feature{id = pad}
assert(f.fields.Pad.length == 5 and f.values.Pad.length == 8)

pc.doc.selection: What is selected.

Notes:

See also pc.doc.select.

pc.doc.select: Select a body or a feature, as a click on its row.

Notes:

See also pc.doc.selection, pc.doc.set_tip.

pc.doc.coupon: Make a calibration coupon to print.

Notes:

See also pc.inspect.compensation.

Example: The coupon builds, with a hole and a pin per diameter.

local c = pc.doc.coupon{diameters = {4, 6}, gaps = {0.4}, overhangs = {45}}
assert(#pc.doc.rebuild() == 0, "every feature builds")
assert(#c.holes == 2 and #c.pins == 2 and c.holes[2].diameter == 6)
local m = pc.doc.measure{body = c.body}
assert(math.abs(m.max[3] - 9) < 1e-6, "the pins stand 6 mm on the 3 mm plate")
local holes = 0
for _, f in ipairs(pc.doc.faces{body = c.body}) do
  if f.kind == "cylinder" then holes = holes + 1 end
end
assert(holes == 4, holes)

pc.doc.new_body: Make an empty body.

Notes:

See also pc.doc.bodies.

Example: A named body with a pad in it.

local lid = pc.doc.new_body{name = "Lid"}
local s = pc.sketch.new{plane = "XY", body = lid}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 2}
assert(pc.doc.feature{id = pad}.body == lid)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = lid}.volume - 400) < 1e-6)
assert(pc.doc.bodies()[1].name == "Lid")

pc.doc.rename: Rename a body, a feature or a note (its text).

Notes:

See also pc.var.rename.

Example: A formula follows a renamed pad.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
pc.doc.set_formula{id = pad, parameter = "length2", formula = "Pad.length * 2"}
pc.doc.rename{id = pad, name = "Base"}
assert(pc.doc.feature{id = pad}.name == "Base")
assert(pc.doc.parameters{id = pad}[2].formula == "Base.length * 2")
pc.doc.rename{id = pc.doc.feature{id = pad}.body, name = "Bracket"}
assert(pc.doc.bodies()[1].name == "Bracket")

pc.doc.set_body: Change a body's colour, how much shows through, material or placement, whether it is frozen or a scan, whether clicks pick it, or how it lies for printing.

Notes:

See also pc.doc.set_face_color, pc.doc.measure.

Example: A block moved and turned.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
pc.doc.set_body{body = body, translation = {x = 100, y = 0, z = 0}, color = {r = 0.9, g = 0.4, b = 0.1}}
local m = pc.doc.measure{body = body}
assert(math.abs(m.min[1] - 100) < 1e-4 and math.abs(m.max[1] - 120) < 1e-4)
-- A quarter turn about Z, about the body's origin.
local h = math.sqrt(0.5)
pc.doc.set_body{body = body, rotation = {x = 0, y = 0, z = h, w = h}}
m = pc.doc.measure{body = body}
assert(math.abs(m.min[1] - 90) < 1e-4 and math.abs(m.max[2] - 20) < 1e-4)
assert(math.abs(m.volume - 1000) < 1e-6)

pc.doc.set_textures: Set the textures pressed into a body's faces for printing.

Notes:

See also pc.doc.faces, pc.file.export.

Example: Ribs on the top face, in the exported mesh.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 6, height = 6}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local top
for _, face in ipairs(pc.doc.faces{body = body}) do
  if face.kind == "plane" and face.normal[3] > 0.99 then top = face.index end
end
local path = pc.file.temp_path{name = "ribs.stl"}
local function triangles()
  return pc.file.export{path = path, format = "stl"}.triangles
end
local plain = triangles()
pc.doc.set_textures{body = body, textures = {{
  texture = {pattern = "Ribs", projection = {Planar = "Z"}, tile_mm = 3, depth_mm = 0.5},
  faces = {top},
}}}
assert(triangles() > 100 * plain, "the ribs are pressed into the exported mesh")
assert(math.abs(pc.doc.measure{body = body}.volume - 180) < 1e-6, "the solid keeps its shape")
pc.doc.set_textures{body = body, textures = {}}
assert(triangles() == plain)

pc.doc.set_face_color: Colour one face of a body, over the body's colour.

Notes:

See also pc.doc.faces, pc.doc.set_body.

Example: A pad's top painted red, then the body's colour again.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local top
for _, face in ipairs(pc.doc.faces{body = body}) do
  if face.kind == "plane" and face.normal[3] > 0.99 then top = face.index end
end
local function colours()
  for _, b in ipairs(pc.doc.bodies()) do
    if b.id == body then return b.face_colors end
  end
end
pc.doc.set_face_color{body = body, face = top, color = {r = 1, g = 0, b = 0}}
local red = colours()
assert(#red == 1 and red[1].face == top and red[1].color.r == 1 and red[1].color.g == 0)
pc.doc.set_face_color{body = body, face = top}
assert(#colours() == 0, "the body's colour again")

pc.doc.linked_copy: A linked copy of a body beside it: the same shape, following every change.

Notes:

See also pc.doc.set_body.

Example: A copy that follows its original.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local copy = pc.doc.linked_copy{body = body}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = copy}
assert(math.abs(m.volume - 1000) < 1e-6)
assert(math.abs(m.min[1] - 30) < 1e-4, "10 mm clear of the original along X")
pc.doc.set_value{id = pad, parameter = "length", value = 8}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = copy}.volume - 1600) < 1e-6, "it follows")

pc.doc.array: Repeat a body along a line, around an axis, along a path or at points: each repeat a linked copy.

Notes:

See also pc.doc.set_array, pc.doc.linked_copy.

Example: A row of four, then a ring.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local row = pc.doc.array{body = body, count = 4, spacing = 25}
assert(#row.instances == 3 and #pc.doc.bodies() == 4)
local last = pc.doc.measure{body = row.instances[3]}
assert(math.abs(last.min[1] - 75) < 1e-4, "three spacings along X")
assert(math.abs(last.volume - 500) < 1e-6, "the source's shape")
pc.doc.set_array{array = row.id, remove = true}
assert(#pc.doc.bodies() == 1, "its copies go with it")
local ring = pc.doc.array{body = body, kind = "polar", count = 4,
                          center = {x = -20, y = 0, z = 0}}
local opposite = pc.doc.measure{body = ring.instances[2]}
assert(math.abs(opposite.max[1] + 40) < 1e-4, "half a turn about the axis")

pc.doc.set_array: Change an array of linked copies: its count, spacing, angle, axis, path, points or skipped occurrences.

Notes:

See also pc.doc.array.

Example: A row grown, one skipped, then brought back.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local row = pc.doc.array{body = body, count = 3, spacing = 20}
local first = row.instances[1]
row = pc.doc.set_array{array = row.id, count = 5, spacing = 30, skip = {2}}
assert(#row.instances == 3 and row.instances[1] == first, "the copy it had is kept")
local far = pc.doc.measure{body = row.instances[3]}
assert(math.abs(far.min[1] - 120) < 1e-4, "occurrence 4, four spacings out")
row = pc.doc.set_array{array = row.id, skip = {}}
assert(#row.instances == 4 and #pc.doc.bodies() == 5)

pc.doc.move_after: Move a feature in its body's history to just after another.

Notes:

See also pc.doc.move.

Example: A sketch brought forward, its pocket kept after the pad.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{plane = "XY", offset = 5, body = body}
pc.sketch.circle{sketch = top, x = 10, y = 5, radius = 2}
local hole = pc.design.pocket{sketch = top, depth = 3}
local ok, why = pcall(pc.doc.move_after, {id = hole, after = s})
assert(not ok and tostring(why):find("depend on each other"), tostring(why))
pc.doc.move_after{id = top, after = s}
local order = pc.doc.features{body = body}
assert(order[1].id == s and order[2].id == top and order[3].id == pad and order[4].id == hole)
assert(#pc.doc.rebuild() == 0)

pc.doc.recompute: Build a body again from its history.

Notes:

See also pc.doc.rebuild, pc.doc.set_body.

Example: A body built again from its sketch.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
pc.doc.recompute{body = body}
assert(#pc.doc.rebuild() == 0, "built again from the sketch")
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6)
pc.doc.set_body{body = body, frozen = true}
local ok, why = pcall(pc.doc.recompute, {body = body})
assert(not ok and tostring(why):find("is frozen"), tostring(why))
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6, "kept")

pc.doc.set_visible: Show or hide a body, a feature or a note.

Notes:

See also pc.doc.suppress.

Example: A sketch shown, a body hidden.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.doc.set_visible{id = s, visible = true}
assert(pc.doc.feature{id = s}.visible)
pc.doc.set_visible{id = body, visible = false}
assert(not pc.doc.bodies()[1].visible)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6, "hidden, still built")

pc.doc.delete: Delete a body, a feature or a note.

Notes:

See also pc.doc.suppress.

Example: A fillet taken away again.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local round = pc.design.fillet{body = body, radius = 1}
pc.doc.delete{id = round}
assert(#pc.doc.rebuild() == 0)
assert(#pc.doc.faces{body = body} == 6, "the block is square again")
assert(#pc.doc.features{body = body} == 2, "the sketch and the pad")

pc.doc.repair: Repair the shapes the kernel's checker calls broken.

Notes:

See also pc.doc.rebuild.

pc.doc.convert_to_solid: Turn mesh bodies into solids.

Notes:

See also pc.doc.refine, pc.doc.rebuild.

pc.doc.refine: Rebuild converted solids' facets on the cylinders, cones, spheres and tori they approximate.

Notes:

See also pc.doc.convert_to_solid.

pc.doc.replace_shape: Read a body's shape from another file: its first solid becomes the shape the body's features build on.

Notes:

See also pc.doc.rebuild.

pc.doc.suppress: Leave a feature out of its body's solid, or back in.

Notes:

See also pc.doc.set_visible, pc.doc.set_tip, pc.doc.delete.

Example: A pocket left out and put back.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{plane = "XY", offset = 5, body = body}
pc.sketch.circle{sketch = top, x = 10, y = 5, radius = 2}
local hole = pc.design.pocket{sketch = top, depth = 3}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - (1000 - math.pi * 4 * 3)) < 1e-3)
pc.doc.suppress{id = hole}
assert(pc.doc.feature{id = hole}.suppressed)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6, "the plain block")
pc.doc.suppress{id = hole, suppressed = false}
assert(#pc.doc.rebuild() == 0)
assert(pc.doc.measure{body = body}.volume < 1000, "cut again")

pc.doc.move: Move a feature one step in its body's history.

Notes:

See also pc.doc.move_after, pc.doc.set_tip.

Example: A pad stays after its sketch; a fillet moved before it fails.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local round = pc.design.fillet{body = body, radius = 1}
local ok, why = pcall(pc.doc.move, {id = pad, up = true})
assert(not ok and tostring(why):find("built from"), tostring(why))
assert(pc.doc.move{id = round, up = true})
assert(pc.doc.features{body = body}[2].id == round)
local failed = pc.doc.rebuild()
assert(#failed == 2 and failed[1].feature == round, "a fillet before the pad has nothing to round")

pc.doc.set_tip: Build a body only up to a feature, or all of it again.

Notes:

See also pc.doc.move, pc.doc.suppress.

Example: A body built only up to its pad.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{plane = "XY", offset = 5, body = body}
pc.sketch.circle{sketch = top, x = 10, y = 5, radius = 2}
local hole = pc.design.pocket{sketch = top, depth = 3}
pc.doc.set_tip{id = pad}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6, "built up to the pad")
pc.doc.set_tip{id = pad, clear = true}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - (1000 - math.pi * 12)) < 1e-3)

pc.doc.undo: Undo the newest step, as Edit › Undo does.

Notes:

See also pc.doc.rebuild.

Example: Take back the last call.

local body = pc.doc.new_body{}
pc.doc.rename{id = body, name = "Bracket"}
assert(pc.doc.undo() == "doc.rename")
assert(pc.doc.bodies()[1].name ~= "Bracket")
assert(pc.doc.redo() == "doc.rename")
assert(pc.doc.bodies()[1].name == "Bracket")
pc.doc.undo()
pc.doc.undo()
assert(#pc.doc.bodies() == 0)

pc.doc.redo: Redo the step undone last, as Edit › Redo does.

Notes:

See also pc.doc.rebuild.

Example: Take back the last call.

local body = pc.doc.new_body{}
pc.doc.rename{id = body, name = "Bracket"}
assert(pc.doc.undo() == "doc.rename")
assert(pc.doc.bodies()[1].name ~= "Bracket")
assert(pc.doc.redo() == "doc.rename")
assert(pc.doc.bodies()[1].name == "Bracket")
pc.doc.undo()
pc.doc.undo()
assert(#pc.doc.bodies() == 0)

pc.doc.rebuild: Rebuild every solid that changed, repair or convert what was asked, and wait.

Notes:

See also pc.doc.measure, pc.doc.faces.

Example: A profile that does not close is told here.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.polyline{sketch = s, points = {{0, 0}, {10, 0}, {10, 10}}}
local pad = pc.design.pad{sketch = s, length = 5}
local failed = pc.doc.rebuild()
assert(#failed == 1 and failed[1].feature == pad, "the pad failed")
assert(failed[1].error:find("not closed"), failed[1].error)

pc.doc.note_add: Put a numbered note on a face, an edge or a point of a body: a leader from the point to a label, drawn in the view and written to STEP.

Notes:

See also pc.doc.notes, pc.doc.note_set, pc.doc.note_remove.

Example: A note on a pad's top follows it as the pad grows.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local note = pc.doc.note_add{body = body, text = "=Pad.length", point = {10, 5, 6}}
local n = pc.doc.notes{body = body}[1]
assert(n.id == note and n.number == 1 and n.text == "=Pad.length" and n.shows == "5 mm")
assert(math.abs(n.point[3] - 5) < 1e-4, "taken to the top face")
pc.doc.set_value{id = pad, parameter = "length", value = 8}
assert(#pc.doc.rebuild() == 0)
n = pc.doc.notes{body = body}[1]
assert(math.abs(n.point[3] - 8) < 1e-4, "the note follows the face")
assert(n.label[3] > n.point[3] and n.shows == "8 mm")

pc.doc.note_set: Change a note's text, label or visibility, resolve it or answer its question.

Notes:

See also pc.doc.note_add, pc.doc.notes.

Example: A note reworded and hidden; an agent resolves it but cannot reword it.

local body = pc.doc.new_body{name = "Plate"}
local note = pc.doc.note_add{body = body, text = "Draft"}
pc.doc.note_set{id = note, text = "Final", visible = false}
local n = pc.doc.notes{body = body}[1]
assert(n.text == "Final" and not n.visible)
pc.doc.note_set{number = n.number, done = "Thickened", author = "agent"}
assert(not pcall(pc.doc.note_set, {id = note, text = "Gone", author = "agent"}))
n = pc.doc.notes{body = body}[1]
assert(n.text == "Final" and n.done == "Thickened")

pc.doc.notes_open: The notes not yet resolved.

Notes:

See also pc.doc.notes.

Example: A question asked, answered, and no longer open.

local body = pc.doc.new_body{}
local q = pc.doc.note_add{body = body, text = "Is this face the datum?", asks = true}
local open = pc.doc.notes_open{}
assert(#open == 1 and open[1].asks and not open[1].from_file)
pc.doc.note_set{id = q, done = "Yes: the bottom face"}
assert(#pc.doc.notes_open{} == 0)
local n = pc.doc.notes{body = body}[1]
assert(n.resolved and n.done == "Yes: the bottom face")

pc.doc.note_remove: Take a note away.

See also pc.doc.note_add.

Example: A note added and taken away.

local body = pc.doc.new_body{}
local note = pc.doc.note_add{body = body, text = "Temporary"}
pc.doc.note_remove{id = note}
assert(#pc.doc.notes{body = body} == 0)

pc.doc.notes: List the notes on bodies.

Notes:

See also pc.doc.note_add.

Example: A note on a bore says what it is on, and is lost when the bore goes.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{plane = "XY", offset = 5, body = body}
pc.sketch.circle{sketch = top, x = 10, y = 5, radius = 2}
local hole = pc.design.pocket{sketch = top, depth = 3}
assert(#pc.doc.rebuild() == 0)
pc.doc.note_add{body = body, point = {12, 5, 4}, text = "Make this 4.2"}
local n = pc.doc.notes()[1]
assert(n.on == "face" and n.author == "user" and not n.lost)
assert(n.surface.kind == "cylinder" and math.abs(n.surface.radius - 2) < 1e-4)
assert(n.feature == hole, "the pocket made the bore")
pc.doc.suppress{id = hole}
assert(#pc.doc.rebuild() == 0)
assert(pc.doc.notes()[1].lost, "the bore is gone")

pc.doc.faces: The faces of a body's solid, where it sits.

Notes:

See also pc.doc.measure.

Example: A moved block's top, where it sits and as a feature takes it.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 4}}.body
pc.asm.place{body = body, translation = {0, 0, 50}}
assert(#pc.doc.rebuild() == 0)
local function top(faces)
  for _, face in ipairs(faces) do
    if face.kind == "plane" and face.normal[3] > 0.99 then return face end
  end
end
assert(math.abs(top(pc.doc.faces{body = body}).point[3] - 54) < 1e-6)
local own = top(pc.doc.faces{body = body, frame = "body"})
assert(math.abs(own.point[3] - 4) < 1e-6, "4 in the body's own frame")

pc.doc.edges: The edges of a body's solid, where it sits.

Notes:

See also pc.doc.faces.

Example: A cylinder's rims and seam.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 5}
local pad = pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = pad}.body
local rims, seams = 0, 0
for _, edge in ipairs(pc.doc.edges{body = body}) do
  if edge.kind == "circle" then
    rims = rims + 1
    assert(math.abs(edge.radius - 5) < 1e-6 and #edge.faces == 2)
    assert(math.abs(edge.length - 2 * math.pi * 5) < 0.05, "measured along the outline")
  elseif #edge.faces == 1 then
    seams = seams + 1
    assert(edge.kind == "line" and math.abs(edge.length - 10) < 1e-6)
  end
end
assert(rims == 2 and seams == 1, "the top and bottom rims and the side's seam")

pc.doc.measure: A body's volume, surface area, centre and bounds.

Notes:

See also pc.doc.rebuild, pc.doc.faces.

Example: A cylinder's volume and bounds.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 5}
local pad = pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - math.pi * 25 * 10) < 1e-3, m.volume)
assert(math.abs(m.max[3] - 10) < 1e-6 and math.abs(m.min[1] + 5) < 1e-6)
assert(math.abs(m.centre[3] - 5) < 1e-6)
-- It turns most easily about its own axis: V r² / 2.
local least = m.inertia.principal[1]
assert(math.abs(least.moment - math.pi * 3125) < 1, least.moment)
assert(math.abs(math.abs(least.axis[3]) - 1) < 1e-6)

pc.doc.print_layout: Where the print layout puts each copy: every part flat on its resting face (or as doc.set_body's print_on chose), as many as the parts list prints, packed on the bed.

Notes:

See also pc.asm.parts, pc.asm.part, pc.file.export.

Example: Three posts laid down on the bed.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 20}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 60}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.part{body = post, print = 3}
local layout = pc.doc.print_layout{bed = {x = 200, y = 200, z = 200}, gap = 5}
assert(layout.plates == 1 and #layout.pieces == 3)
for _, p in ipairs(layout.pieces) do
  assert(math.abs(p.min[3]) < 1e-3, "on the bed")
  assert(math.abs(p.max[3] - 10) < 1e-3, "lying on a 20 × 60 side")
  assert(p.min[1] >= 2.5 - 1e-3 and p.max[1] <= 197.5 + 1e-3)
end

pc.doc.report_pdf: Write a printable report of what the workbenches measured, as a PDF.

Notes:

See also pc.inspect.report, pc.doc.picture.

pc.doc.picture: Write a PNG of the bodies: the same for the same arguments whatever the user's camera (except view "current").

Notes:

See also pc.doc.faces, pc.doc.edges.

Example: A small isometric picture.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.png"}
local shot = pc.doc.picture{path = path, view = "iso", size = {160, 120}}
assert(shot.path == path and shot.width == 160 and shot.height == 120)
assert(shot.renderer == "cpu")

pc.doc.parameters: A feature's numbers that formulas set and read.

Notes:

See also pc.doc.set_formula, pc.doc.set_value.

Example: A pad's length as formulas see it.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local length
for _, p in ipairs(pc.doc.parameters{id = pad}) do
  if p.name == "length" then length = p end
end
assert(length.key == "/Pad/length" and length.kind == "length")
assert(length.value == 5 and length.text == "5 mm" and length.formula == nil)

pc.doc.set_formula: Set one of a feature's numbers by a formula, or take the formula away.

Notes:

See also pc.doc.parameters, pc.doc.set_value, pc.var.set.

Example: A pad's length following a variable.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm"}
local got = pc.doc.set_formula{id = pad, parameter = "length", formula = "Printer.nozzle * 10"}
assert(math.abs(got.value - 4) < 1e-9 and got.error == nil)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 800) < 1e-6)
pc.var.set{set = "Printer", name = "nozzle", formula = "0.6 mm"}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1200) < 1e-6, "the pad follows")
local kept = pc.doc.set_formula{id = pad, parameter = "length"}
assert(math.abs(kept.value - 6) < 1e-9 and kept.formula == nil, "the 6 mm it came to stays")
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1200) < 1e-6)
local bad = pc.doc.set_formula{id = pad, parameter = "length", formula = "30 deg"}
assert(bad.value == nil and bad.error:find("angle"), bad.error)

pc.doc.set_value: Set one of a feature's numbers, taking away any formula on it.

Notes:

See also pc.doc.set_formula, pc.doc.parameters.

Example: A length set by hand over a formula.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.doc.set_formula{id = pad, parameter = "length", formula = "2 * 4 mm"}
pc.doc.set_value{id = pad, parameter = "length", value = 7}
local length = pc.doc.parameters{id = pad}[1]
assert(length.name == "length" and length.value == 7 and length.formula == nil)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1400) < 1e-6)

pc.doc.sections: The document's saved sections.

Notes:

See also pc.doc.save_section, pc.view.section.

pc.doc.save_section: Keep a section with the document by name, to switch the view to later.

Notes:

See also pc.doc.sections, pc.doc.remove_section.

Example: Sections kept, one replaced, one a wedge.

pc.doc.save_section{name = "Mid", axis = "z", offset = 5}
pc.doc.save_section{name = "Bore", origin = {0, 18, 13}, normal = {0, 1, 0}}
pc.doc.save_section{name = "Mid", axis = "z", offset = 7, flipped = true}
pc.doc.save_section{name = "Quarter", axis = "z", offset = 7,
  wedge_normal = {1, 0, 0}, wedge_origin = {20, 0, 0}}
local kept = pc.doc.sections()
assert(#kept == 3 and kept[1].name == "Mid" and kept[1].offset == 7)
assert(kept[1].flipped and kept[2].origin[2] == 18 and kept[2].wedge == nil)
assert(kept[3].wedge.origin[1] == 20)

pc.doc.remove_section: Drop a saved section.

Notes:

See also pc.doc.sections.

file

pc.file.temp_path: A new file's path in this run's private folder, for a script's own files.

Notes:

See also pc.file.export, pc.file.import.

Example: Two files of one name.

local a = pc.file.temp_path{name = "part.stl"}
local b = pc.file.temp_path{name = "part.stl", text = "solid empty\nendsolid empty\n"}
assert(a ~= b and a:sub(-4) == ".stl" and b:sub(-4) == ".stl")

pc.file.new: New.

pc.file.open: Open.

Notes:

See also pc.file.save_as.

Example: Save, then open the file again.

local path = pc.file.temp_path{name = "kept.prtcad"}
local body = pc.doc.new_body{name = "Kept"}
pc.file.save_as{path = path}
pc.doc.rename{id = body, name = "Changed"}
assert(not pcall(pc.file.open, {path = path}), "unsaved edits are kept")
pc.file.open{path = path, discard = true}
assert(pc.doc.bodies()[1].name == "Kept")

pc.file.save: Save.

pc.file.save_as: Save as.

pc.file.save_all: Save all.

Notes:

pc.file.import: Import.

pc.file.export: Export.

Notes:

pc.file.send_to_slicer: Send to slicer.

pc.file.print_layout: Print layout.

var

pc.var.new: Make a variable set.

Notes:

See also pc.var.set, pc.var.list.

Example: A set and one variable.

local set = pc.var.new{name = "Printer"}
pc.var.set{set = set, name = "nozzle", formula = "0.4 mm"}
local sets = pc.var.list()
assert(#sets == 1 and sets[1].id == set and sets[1].name == "Printer")
assert(pc.var.eval{formula = "Printer.nozzle"}.value == 0.4)
local ok, why = pcall(pc.var.new, {name = "Printer"})
assert(not ok and tostring(why):find("already called"), tostring(why))

pc.var.set: Set a variable to a formula, adding it when new.

Notes:

See also pc.var.eval, pc.doc.set_formula, pc.config.set.

Example: A wall that follows the nozzle.

pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm"}
local wall = pc.var.set{set = "Printer", name = "wall", formula = "3 * Printer.nozzle"}
assert(math.abs(wall.value - 1.2) < 1e-9 and wall.kind == "length")
pc.var.set{set = "Printer", name = "nozzle", formula = "0.6 mm", comment = "hardened steel"}
assert(math.abs(pc.var.eval{formula = "Printer.wall"}.value - 1.8) < 1e-9, "wall follows")
local loop = pc.var.set{set = "Printer", name = "loop", formula = "Printer.loop + 1"}
assert(loop.value == nil and loop.error:find("loop"), "kept, with its error")

pc.var.remove: Take a variable out of its set.

Notes:

See also pc.var.rename, pc.config.remove_variable.

Example: A variable taken away from under a formula.

pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm"}
pc.var.set{set = "Printer", name = "wall", formula = "3 * Printer.nozzle"}
pc.var.remove{set = "Printer", name = "nozzle"}
local vars = pc.var.list{set = "Printer"}[1].variables
assert(#vars == 1 and vars[1].name == "wall")
assert(vars[1].value == nil and vars[1].error:find("no nozzle"), "what read it fails")

pc.var.rename: Rename a variable, and every formula that reads it.

Notes:

See also pc.doc.rename.

Example: A pad's formula follows the new name.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "h", formula = "8 mm"}
pc.doc.set_formula{id = pad, parameter = "length", formula = "Size.h"}
pc.var.rename{set = "Size", name = "h", to = "height"}
assert(pc.doc.parameters{id = pad}[1].formula == "Size.height")
assert(pc.doc.parameters{id = pad}[1].value == 8)

pc.var.list: The variable sets and what each variable comes to.

Notes:

See also pc.var.eval, pc.config.list.

Example: Each variable's formula, value and comment.

pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm", comment = "brass"}
pc.var.set{set = "Printer", name = "angle", formula = "45"}
local vars = pc.var.list{set = "Printer"}[1].variables
assert(vars[1].name == "nozzle" and vars[1].formula == "0.4 mm" and vars[1].comment == "brass")
assert(vars[1].value == 0.4 and vars[1].kind == "length" and vars[1].text == "0.4 mm")
assert(vars[2].kind == "number" and vars[2].value == 45, "a bare number has no unit")

pc.var.eval: What a formula comes to in this document.

Notes:

See also pc.var.set, pc.var.list.

Example: Units worked out.

pc.var.new{name = "Printer"}
pc.var.set{set = "Printer", name = "nozzle", formula = "0.4 mm"}
local wall = pc.var.eval{formula = "3 * Printer.nozzle + 1 in"}
assert(math.abs(wall.value - 26.6) < 1e-9 and wall.kind == "length")
local area = pc.var.eval{formula = "2 mm * 3 mm"}
assert(area.kind == "area" and area.value == 6)
assert(math.abs(pc.var.eval{formula = "sin(30)"}.value - 0.5) < 1e-12, "degrees")

config

pc.config.list: The configurations: the variables they set, each row, and which is in effect.

Notes:

See also pc.config.activate, pc.var.list.

Example: Two sizes, the large one in effect.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.add_variable{variable = "Size.width"}
pc.config.new{name = "Small"}
pc.config.set{name = "Small", variable = "Size.width", value = "30 mm"}
pc.config.new{name = "Large", like = "Small"}
pc.config.set{name = "Large", variable = "Size.width", value = "60 mm"}
pc.config.activate{name = "Large"}
local t = pc.config.list()
assert(t.columns[1] == "Size.width" and t.active == "Large")
assert(t.rows[1].name == "Small" and t.rows[1].values[1] == "30 mm")
assert(t.rows[2].name == "Large" and t.rows[2].values[1] == "60 mm")
assert(pc.var.eval{formula = "Size.width"}.value == 60)

pc.config.new: Add a configuration.

Notes:

See also pc.config.set, pc.config.activate.

Example: A configuration copied from another.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.add_variable{variable = "Size.width"}
pc.config.new{name = "Large"}
pc.config.set{name = "Large", variable = "Size.width", value = "60 mm"}
pc.config.new{name = "Large, thin", like = "Large"}
local rows = pc.config.list().rows
assert(#rows == 2 and rows[2].values[1] == "60 mm", "copied from Large")
assert(pc.config.list().active == nil, "a new configuration is not put in effect")

pc.config.remove: Remove a configuration.

Notes:

See also pc.config.activate.

Example: The configuration in effect removed.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.add_variable{variable = "Size.width"}
pc.config.new{name = "Large"}
pc.config.set{name = "Large", variable = "Size.width", value = "60 mm"}
pc.config.activate{name = "Large"}
pc.config.remove{name = "Large"}
assert(#pc.config.list().rows == 0 and pc.config.list().active == nil)
assert(pc.var.eval{formula = "Size.width"}.value == 40, "the variable's own formula again")

pc.config.rename: Rename a configuration.

Notes:

Example: The one in effect renamed.

pc.config.new{name = "Big"}
pc.config.activate{name = "Big"}
pc.config.rename{name = "Big", to = "Large"}
local t = pc.config.list()
assert(t.rows[1].name == "Large" and t.active == "Large")

pc.config.add_variable: Let the configurations set a variable: it becomes a column.

Notes:

See also pc.config.set, pc.var.set.

Example: A column, empty in every row.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.new{name = "Large"}
pc.config.add_variable{variable = "Size.width"}
local t = pc.config.list()
assert(t.columns[1] == "Size.width" and t.rows[1].values[1] == "", "empty: the variable's own")
local ok, why = pcall(pc.config.add_variable, {variable = "width"})
assert(not ok and tostring(why):find("Set.name"), tostring(why))

pc.config.remove_variable: Take a variable's column away.

Notes:

See also pc.config.add_variable, pc.var.remove.

Example: The column gone, the variable its own again.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.add_variable{variable = "Size.width"}
pc.config.new{name = "Large"}
pc.config.set{name = "Large", variable = "Size.width", value = "60 mm"}
pc.config.activate{name = "Large"}
assert(pc.var.eval{formula = "Size.width"}.value == 60)
pc.config.remove_variable{variable = "Size.width"}
assert(#pc.config.list().columns == 0)
assert(pc.var.eval{formula = "Size.width"}.value == 40, "its own formula again")

pc.config.set: What a configuration gives a variable: a formula, or empty for its own.

Notes:

See also pc.config.add_variable, pc.config.activate, pc.var.set.

Example: A value given, then left to the variable.

pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "width", formula = "40 mm"}
pc.config.add_variable{variable = "Size.width"}
pc.config.new{name = "Large"}
pc.config.set{name = "Large", variable = "Size.width", value = "1.5 * 40 mm"}
pc.config.activate{name = "Large"}
assert(pc.var.eval{formula = "Size.width"}.value == 60)
pc.config.set{name = "Large", variable = "Size.width", value = ""}
assert(pc.var.eval{formula = "Size.width"}.value == 40, "empty: the variable's own")

pc.config.leave_out: The bodies a configuration leaves out: not drawn, picked, exported or checked.

Notes:

See also pc.config.list, pc.config.activate.

Example: A lid left out of one configuration.

local function box(z)
  local s = pc.sketch.new{plane = "XY", offset = z}
  pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local base, lid = box(0), box(5)
assert(#pc.doc.rebuild() == 0)
pc.config.new{name = "Open"}
pc.config.leave_out{name = "Open", bodies = {lid}}
assert(pc.config.list().rows[1].left_out[1] == lid)
pc.config.leave_out{name = "Open", bodies = {}}
assert(#pc.config.list().rows[1].left_out == 0, "an empty list leaves none out")
local ok, why = pcall(pc.config.leave_out, {name = "Closed", bodies = {lid}})
assert(not ok, "no configuration is called Closed")

pc.config.activate: Put a configuration in effect.

Notes:

See also pc.config.list, pc.config.set.

Example: A pad's length switched by configuration.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.var.new{name = "Size"}
pc.var.set{set = "Size", name = "height", formula = "5 mm"}
pc.doc.set_formula{id = pad, parameter = "length", formula = "Size.height"}
pc.config.add_variable{variable = "Size.height"}
pc.config.new{name = "Tall"}
pc.config.set{name = "Tall", variable = "Size.height", value = "12 mm"}
pc.config.activate{name = "Tall"}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 2400) < 1e-6)
pc.config.activate{}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-6, "its own 5 mm again")

app

pc.app.workbenches: The workbenches, in the order they load.

pc.app.print_compensation: Set what mesh exports scale each body by to make up for the printer's shrinkage.

Notes:

See also pc.inspect.compensation.

pc.app.workbench: Switch to a workbench.

pc.app.tool: Start a toolbar tool, as a click on it does.

pc.app.tools: The tools of a workbench.

pc.app.quit: Quit.

pc.app.log: Log panel.

scan

pc.scan.mark: Mark part of a scan's surface, the part the tools that work on some of a scan take.

Notes:

view

pc.view.section: Cut the view at a plane, a saved section or none.

Notes:

See also pc.doc.save_section.

pc.view.fit_all: Fit all.

pc.view.fit_selection: Fit selection.

pc.view.isolate: Isolate the selection, or show everything again.

pc.view.show_all: Show every body.

pc.view.isometric: Isometric view.

pc.view.front: Front view.

pc.view.top: Top view.

pc.view.right: Right view.

pc.view.rear: Rear view.

pc.view.bottom: Bottom view.

pc.view.left: Left view.

pc.view.orthographic: Orthographic.

pc.view.perspective: Perspective.

pc.view.shaded_edges: Shaded with edges.

pc.view.shaded: Shaded.

pc.view.wireframe: Wireframe.

pc.view.note: Note.

pc.view.print_bed: Print bed.

pc.view.annotations: Annotations.

pc.view.grid: Grid.

pc.view.split: Split view.

pc.view.split_link: Link split cameras.

pc.view.origin_planes: Origin planes.

pc.view.left_panel: Fold the left panel.

pc.view.fullscreen: Full screen.

pc.view.clipping_plane: Clipping plane.

pc.view.measure: Measure.

edit

pc.edit.cut: Cut.

pc.edit.copy: Copy.

pc.edit.paste: Paste.

pc.edit.rename: Rename the selected item.

pc.edit.properties: Properties of the selected item.

pc.edit.recompute: Recompute all.

pc.edit.repeat: Repeat the last tool.

tab

pc.tab.new: New tab.

pc.tab.close: Close tab.

pc.tab.reopen: Reopen closed tab.

pc.tab.next: Next tab.

pc.tab.previous: Previous tab.

sketch

pc.sketch.new: Make an empty sketch on a base plane.

Notes:

See also pc.doc.new_body, pc.sketch.rect, pc.design.datum.

Example: Two sketches in one body.

local body = pc.doc.new_body{name = "Bracket"}
local base = pc.sketch.new{body = body, plane = "XY"}
local side = pc.sketch.new{body = body, plane = "XZ", offset = 5}
assert(pc.doc.feature{id = base}.body == body)
assert(pc.doc.feature{id = side}.body == body)
assert(#pc.doc.bodies() == 1, "both sketches went in the one body")

pc.sketch.import_dxf: Make a sketch of a DXF drawing: its lines, arcs, circles, ellipses and polylines as sketch curves, splines as lines through points on them, hidden ones as construction, ends that meet sharing one point.

Notes:

See also pc.sketch.new, pc.sketch.repair.

pc.sketch.image: Lay a picture (PNG or JPEG) on a sketch's plane to draw over: in the sketch given or being edited, else in a new one.

Notes:

See also pc.sketch.set_image.

pc.sketch.set_image: Move, size, turn or fade a sketch's picture, or take it away.

Notes:

See also pc.sketch.image.

pc.sketch.point: Add a point.

Notes:

See also pc.sketch.constrain, pc.sketch.geometry.

Example: A corner made first and shared.

local s = pc.sketch.new{plane = "XY"}
local corner = pc.sketch.point{sketch = s, x = 10, y = 5}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 5}
local ends = 0
for _, g in ipairs(pc.doc.feature{id = s}.fields.sketch.geometry) do
  if g.Line and (g.Line.start == corner or g.Line["end"] == corner) then ends = ends + 1 end
end
assert(ends == 2, "the rectangle's corner is the point made first")

pc.sketch.line: Add a line from (x1, y1) to (x2, y2).

Notes:

See also pc.sketch.polyline, pc.sketch.point.

Example: Three lines end to end close a triangle.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 30, y2 = 0}
pc.sketch.line{sketch = s, x1 = 30, y1 = 0, x2 = 0, y2 = 20}
pc.sketch.line{sketch = s, x1 = 0, y1 = 20, x2 = 0, y2 = 0}
assert(#pc.sketch.constraints{sketch = s} == 0, "nothing holds a line level")
local pad = pc.design.pad{sketch = s, length = 4}
assert(#pc.doc.rebuild() == 0, "the ends are shared, so the triangle closes")
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 30 * 20 / 2 * 4) < 1e-3)

pc.sketch.polyline: Add lines through a list of points, each ending where the next starts; a level or upright one is held so.

Notes:

See also pc.sketch.rect, pc.sketch.line.

Example: A closed triangle padded.

local s = pc.sketch.new{plane = "XY"}
local lines = pc.sketch.polyline{sketch = s, points = {{0, 0}, {30, 0}, {0, 20}}, closed = true}
assert(#lines == 3)
local pad = pc.design.pad{sketch = s, length = 5}
assert(#pc.doc.rebuild() == 0, "the triangle closes")
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 30 * 20 / 2 * 5) < 1e-3)

pc.sketch.rect: Add a rectangle from its corner (x, y), its width and its height: its sides held level and upright.

Notes:

See also pc.sketch.polyline, pc.sketch.constrain.

Example: A plate centred on the origin.

local s = pc.sketch.new{plane = "XY"}
local sides = pc.sketch.rect{sketch = s, x = -20, y = -15, width = 40, height = 30}
assert(#sides == 4)
local pad = pc.design.pad{sketch = s, length = 3}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 40 * 30 * 3) < 1e-3)
assert(math.abs(m.centre[1]) < 1e-6 and math.abs(m.centre[2]) < 1e-6, "centred")

pc.sketch.circle: Add a circle.

Notes:

See also pc.design.hole.

Example: A washer: a ring padded from two circles.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 10}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 4}
local pad = pc.design.pad{sketch = s, length = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - math.pi * (100 - 16) * 2) < 0.01, m.volume)

pc.sketch.arc: Add an arc, counter-clockwise from the start angle to the end angle.

Notes:

See also pc.sketch.circle, pc.sketch.draw.

Example: A half disc closed by a line.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.arc{sketch = s, x = 0, y = 0, radius = 10, start = -90, ["end"] = 90}
pc.sketch.line{sketch = s, x1 = 0, y1 = 10, x2 = 0, y2 = -10}
local pad = pc.design.pad{sketch = s, length = 2}
assert(#pc.doc.rebuild() == 0, "the line ends on the arc's ends")
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - math.pi * 100 / 2 * 2) < 0.01, m.volume)
assert(m.min[1] > -1e-6, "counter-clockwise from -90 to 90 is the right half")

pc.sketch.export_dxf: Sketch as layered DXF.

Notes:

See also pc.sketch.export_csv, pc.sketch.import_dxf.

Example: A circle in inches, read back.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 25.4}
local path = pc.file.temp_path{name = "circle.dxf"}
local out = pc.sketch.export_dxf{sketch = s, path = path, units = "inch"}
assert(out.curves == 1 and out.notes == 1, out.notes)
local function radius(sketch)
  for _, e in ipairs(pc.sketch.geometry{sketch = sketch}) do
    if e.kind == "circle" then return e.radius end
  end
end
local inches = pc.sketch.import_dxf{path = path, scale = 1}
assert(math.abs(radius(inches) - 1) < 1e-9, "written in inches")
local back = pc.sketch.import_dxf{path = path}
assert(math.abs(radius(back) - 25.4) < 1e-9, "declared in inches")

pc.sketch.export_svg: Sketch as SVG.

Notes:

pc.sketch.export_csv: Elements and dimensions as CSV.

Notes:

See also pc.sketch.export_dxf.

Example: A line's length.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 30, y2 = 40}
local out = pc.sketch.export_csv{sketch = s}
assert(out.csv:find(",50,,mm", 1, true), out.csv)
assert(out.csv:sub(1, 2) == "# ", "the traceability line first")

pc.sketch.align_image: Square a picture to the sketch: a point on it to the origin, another along +x.

See also pc.sketch.turn_image.

pc.sketch.turn_image: Turn a picture by quarter turns about the origin, or mirror it.

See also pc.sketch.align_image.

pc.sketch.bolt_circle: The circle through the centres of holes, and how far each strays from it.

Notes:

See also pc.sketch.fit_edge.

pc.sketch.calibrate_axis: Scale a picture along one of its own axes so two points are a known distance apart.

Notes:

See also pc.sketch.calibrate_image, pc.sketch.save_scanner_profile.

pc.sketch.save_scanner_profile: Keep a calibrated picture's scale as a scanner profile for later pictures.

Notes:

pc.sketch.image_profile: Read a part on a picture as radius against angle, its peaks counted.

Notes:

See also pc.sketch.image_objects.

pc.sketch.calibrate_image: Scale a picture so a circle on it, at a point of its rim, is a known size across.

Notes:

See also pc.sketch.fit_edge.

pc.sketch.image_objects: Find the separate parts on the sketch's pictures, and measure each.

Notes:

See also pc.sketch.fit_edge.

pc.sketch.fit_edge: Fit a line or a circle to a reference picture's edge where a point lands.

Notes:

See also pc.sketch.image.

pc.sketch.candidates: What the sketch's geometry was probably designed at, and the relations it nearly keeps.

Notes:

See also pc.sketch.design_values, pc.sketch.fit_scan.

pc.sketch.design_values: Hold lines and rounds at their probable design values with driving dimensions.

See also pc.sketch.candidates.

pc.sketch.geometry: List the sketch's elements with their points.

Notes:

See also pc.sketch.constraints, pc.doc.feature.

Example: Ends and centres are points of their own.

local s = pc.sketch.new{plane = "XY"}
local l = pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
pc.sketch.circle{sketch = s, x = 5, y = 5, radius = 2}
local count = {}
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do
  count[e.kind] = (count[e.kind] or 0) + 1
  if e.id == l then assert(e.points[2][1] == 10 and e.points[2][2] == 0) end
end
assert(count.line == 1 and count.circle == 1)
assert(count.point == 3, "the line's ends and the centre are points of their own")

pc.sketch.constrain: Constrain elements, as the constraint's toolbar button does for a selection.

Notes:

See also pc.sketch.status, pc.sketch.set_value, pc.sketch.constraints.

Example: A plate fully constrained from its corner on the origin.

local s = pc.sketch.new{plane = "XY"}
local corner = pc.sketch.point{sketch = s, x = 1, y = 1}
local sides = pc.sketch.rect{sketch = s, x = 1, y = 1, width = 20, height = 10}
pc.sketch.constrain{sketch = s, kind = "coincident", items = {corner, "origin"}}
pc.sketch.constrain{sketch = s, kind = "distance", items = {sides[1]}, value = 40}
pc.sketch.constrain{sketch = s, kind = "distance", items = {sides[2]}, value = 25}
assert(pc.sketch.status{sketch = s}.dof == 0, "fully constrained")
local pad = pc.design.pad{sketch = s, length = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 40 * 25 * 2) < 1e-3)
assert(math.abs(m.min[1]) < 1e-6 and math.abs(m.min[2]) < 1e-6, "its corner on the origin")

pc.sketch.set_value: Change a dimension's value.

Notes:

See also pc.sketch.constrain, pc.doc.parameters, pc.doc.set_formula.

Example: A circle's diameter changed after it was dimensioned.

local s = pc.sketch.new{plane = "XY"}
local c = pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 5}
local d = pc.sketch.constrain{sketch = s, kind = "diameter", items = {c}}
pc.sketch.set_value{sketch = s, constraint = d[1], value = 20}
assert(pc.sketch.constraints{sketch = s}[1].value == 20)
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - math.pi * 10 ^ 2) < 0.01, m.volume)

pc.sketch.draw: Run a drawing or editing tool over points of the sketch, as clicks there would.

Notes:

See also pc.sketch.polyline, pc.sketch.rect, pc.sketch.circle.

Example: A slot drawn by its centre line.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "slot", points = {{0, 0}, {20, 0}}, params = {slot_width = 6}}
assert(#made.elements > 0 and #made.constraints > 0)
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - (20 * 6 + math.pi * 3 ^ 2)) < 1e-3, m.volume)

pc.sketch.drag: Drag elements by a step, the rest of the sketch following its constraints.

Notes:

See also pc.sketch.set_value.

Example: A rectangle stretched by its corner.

local s = pc.sketch.new{plane = "XY"}
local corner = pc.sketch.point{sketch = s, x = 20, y = 10}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
pc.sketch.drag{sketch = s, items = {corner}, by = {10, 5}}
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do
  if e.id == corner then
    assert(math.abs(e.points[1][1] - 30) < 1e-4 and math.abs(e.points[1][2] - 15) < 1e-4)
  end
end
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 30 * 15) < 1e-2, "still a rectangle, stretched")

pc.sketch.attachment: Move a sketch off what it was placed on: along its normal, across it, turned about it.

Notes:

See also pc.sketch.new, pc.design.datum, pc.sketch.set_plane.

Example: A sketch set 5 mm off its datum.

local body = pc.doc.new_body{name = "Plate"}
local datum = pc.design.datum{body = body, kind = "plane", plane = "XY", offset = {0, 0, 10}}
local s = pc.sketch.new{body = body, on = datum}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 4, height = 2}
pc.sketch.attachment{sketch = s, offset = 5}
pc.sketch.attachment{sketch = s, offset = 5}
pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.min[3] - 15) < 1e-6, "5 mm off the datum at 10, however often it is set")

pc.sketch.external_from: Bring another sketch's curves and points, or a datum, into this sketch: external geometry that follows them.

Notes:

See also pc.sketch.external_defining, pc.sketch.carbon_copy.

Example: A circle from the sketch below, counted, padded and following its source.

local body = pc.doc.new_body{name = "Boss"}
local base = pc.sketch.new{body = body, plane = "XY"}
local circle = pc.sketch.circle{sketch = base, x = 0, y = 0, radius = 5}
local radius = pc.sketch.constrain{sketch = base, kind = "radius", items = {circle}, value = 5}
local top = pc.sketch.new{body = body, plane = "XY", offset = 10}
local made = pc.sketch.external_from{sketch = top, from = base, counts = true}
assert(#made.elements == 2, "the circle and its centre")
pc.design.pad{sketch = top, length = 3}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - math.pi * 25 * 3) < 0.01, m.volume)
assert(math.abs(m.min[3] - 10) < 1e-6)
pc.sketch.set_value{sketch = base, constraint = radius[1], value = 6}
assert(#pc.doc.rebuild() == 0)
m = pc.doc.measure{body = body}
assert(math.abs(m.volume - math.pi * 36 * 3) < 0.01, "the copy follows: " .. m.volume)

pc.sketch.external_defining: Count external geometry in the sketch's profiles, or leave it only guiding.

Notes:

See also pc.sketch.external_from, pc.sketch.external.

Example: A guide made to count.

local body = pc.doc.new_body{name = "Boss"}
local base = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.circle{sketch = base, x = 0, y = 0, radius = 5}
local top = pc.sketch.new{body = body, plane = "XY", offset = 10}
local made = pc.sketch.external_from{sketch = top, from = base}
local pad = pc.design.pad{sketch = top, length = 3}
assert(#pc.doc.rebuild() == 1, "a guide alone is no profile")
pc.sketch.external_defining{sketch = top, items = made.elements}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - math.pi * 25 * 3) < 0.01, m.volume)

pc.sketch.solver_settings: How far the solver goes on this sketch.

Notes:

See also pc.sketch.status.

Example: Settings kept on the sketch.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 5}
pc.sketch.solver_settings{sketch = s, iterations = 500, tolerance = 1e-6}
local solver = pc.doc.feature{id = s}.fields.sketch.solver
assert(solver.max_iterations == 500 and solver.tolerance == 1e-6)
assert(pc.sketch.status{sketch = s}.solved)

pc.sketch.repair: Join ends of curves that nearly meet, and remove curves of no size, doubled curves and constraints left naming nothing.

Notes:

See also pc.sketch.import_dxf, pc.sketch.status.

Example: Ends that miss by microns joined.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
pc.sketch.line{sketch = s, x1 = 10.005, y1 = 0, x2 = 0, y2 = 10}
pc.sketch.line{sketch = s, x1 = 0, y1 = 10, x2 = 0, y2 = 0.003}
local said = pc.sketch.repair{sketch = s}
assert(said:find("2 end"), said)
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 50) < 0.01, m.volume)
assert(pc.sketch.repair{sketch = s} == "nothing to repair")

pc.sketch.restore: Put the sketch back as data holds it: an editing session cancelled.

Notes:

See also pc.doc.feature.

Example: Edits put back.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 5}
local saved = pc.doc.feature{id = s}.fields
pc.sketch.circle{sketch = s, x = 5, y = 2, radius = 1}
assert(#pc.sketch.geometry{sketch = s} == 10)
pc.sketch.restore{sketch = s, data = saved}
assert(#pc.sketch.geometry{sketch = s} == 8, "the circle and its centre are gone")

pc.sketch.set_plane: Move the sketch onto another plane, its geometry kept in its own coordinates.

Notes:

See also pc.sketch.attachment, pc.sketch.new.

Example: A sketch moved onto a plane facing +X.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 4}
pc.sketch.set_plane{sketch = s, normal = {1, 0, 0}, origin = {5, 0, 0}, x_axis = {0, 1, 0}}
local pad = pc.design.pad{sketch = s, length = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.min[1] - 5) < 1e-6 and math.abs(m.max[1] - 7) < 1e-6, "padded along +X from x = 5")
assert(math.abs(m.max[2] - 10) < 1e-6 and math.abs(m.max[3] - 4) < 1e-6, "sketch x along Y, y along Z")

pc.sketch.array: Repeat elements in rows and columns.

Notes:

See also pc.sketch.draw, pc.design.linear_pattern.

Example: A plate with six holes in two rows.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 50, height = 30}
local hole = pc.sketch.circle{sketch = s, x = 10, y = 10, radius = 2}
local made = pc.sketch.array{sketch = s, items = {hole}, rows = 2, cols = 3, dx = 15, dy = 10}
assert(#made.elements == 10, "five more circles and their centres: the original is the first")
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - (50 * 30 - 6 * math.pi * 4)) < 0.01, m.volume)

pc.sketch.text: Write text from a point, in a frame or along curves: one object whose letters are closed outlines.

Notes:

See also pc.sketch.text_edit.

Example: Letters padded from the baseline.

local s = pc.sketch.new{plane = "XY"}
local t = pc.sketch.text{sketch = s, text = "PC", at = {0, 0}, size = 10}
assert(t.text and t.point)
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.min[2]) < 0.2, "the baseline is at y = 0")
assert(m.max[2] > 6 and m.max[2] < 10, "capitals stand under the 10 mm em")

pc.sketch.text_edit: Change a text block: what it says, its font, size, spacing or angle.

Notes:

See also pc.sketch.text, pc.doc.set_formula.

Example: Text whose height a variable sets.

local s = pc.sketch.new{plane = "XY"}
local t = pc.sketch.text{sketch = s, text = "I", at = {0, 0}, size = 10}
pc.var.new{name = "Label"}
pc.var.set{set = "Label", name = "height", formula = "10 mm"}
pc.doc.set_formula{id = s, parameter = t.text .. "/size", formula = "Label.height"}
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = pad}.body
local small = pc.doc.measure{body = body}
pc.var.set{set = "Label", name = "height", formula = "20 mm"}
assert(#pc.doc.rebuild() == 0)
local large = pc.doc.measure{body = body}
assert(math.abs(large.max[2] - 2 * small.max[2]) < 1e-3, "twice as tall")

pc.sketch.explode_text: Turn a text block into plain lines and splines, which can then be edited one by one.

Notes:

See also pc.sketch.text.

Example: A letter exploded and still padded.

local s = pc.sketch.new{plane = "XY"}
local t = pc.sketch.text{sketch = s, text = "L", at = {0, 0}, size = 10}
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = pad}.body
local before = pc.doc.measure{body = body}.volume
local left = pc.sketch.explode_text{sketch = s, block = t.text}
assert(#left.curves > 0)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - before) < 1e-6)

pc.sketch.to_bspline: Make lines, arcs, circles, ellipses and conics into splines that are exactly them.

Notes:

See also pc.sketch.join, pc.sketch.spline_degree.

Example: A circle made a spline pads the same disc.

local s = pc.sketch.new{plane = "XY"}
local c = pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 5}
local made = pc.sketch.to_bspline{sketch = s, items = {c}}
assert(#made.elements > 0)
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do
  assert(e.id ~= c, "the circle is replaced")
end
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - math.pi * 25) < 0.01, "exactly the circle: " .. m.volume)

pc.sketch.spline_degree: Raise or lower the degree of splines: raising keeps the curve, lowering fits the nearest one.

Notes:

See also pc.sketch.spline_knots, pc.sketch.to_bspline.

Example: A cubic raised to degree 4.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "bspline", points = {{0, 0}, {10, 10}, {20, 0}, {30, 10}, "finish"}}
local spline = made.elements[#made.elements]
local function shape()
  for _, g in ipairs(pc.doc.feature{id = s}.fields.sketch.geometry) do
    if g.BSpline then return g.BSpline end
  end
end
assert(#shape().control_points == 4)
pc.sketch.spline_degree{sketch = s, items = {spline}, by = 1}
assert(shape().degree == 4 and #shape().control_points == 5)

pc.sketch.insert_knot: Insert a knot into a spline where it passes nearest a point, the curve unchanged.

Notes:

See also pc.sketch.knot_multiplicity, pc.sketch.spline_knots.

Example: A knot inserted halfway.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "bspline", points = {{0, 0}, {10, 10}, {20, 0}, {30, 10}, "finish"}}
local spline = made.elements[#made.elements]
assert(#pc.sketch.spline_knots{sketch = s, spline = spline} == 0)
pc.sketch.insert_knot{sketch = s, spline = spline, at = {15, 5}}
local knots = pc.sketch.spline_knots{sketch = s, spline = spline}
assert(#knots == 1 and knots[1].multiplicity == 1)
assert(math.abs(knots[1].knot - 0.5) < 1e-6, "halfway along this symmetric spline")

pc.sketch.knot_multiplicity: Set how many times a spline's knot stands: 1 up to the degree, or 0 to remove it.

Notes:

See also pc.sketch.spline_knots, pc.sketch.insert_knot.

Example: A knot doubled, then removed.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "bspline", points = {{0, 0}, {10, 10}, {20, 0}, {30, 10}, "finish"}}
local spline = made.elements[#made.elements]
pc.sketch.insert_knot{sketch = s, spline = spline, at = {15, 5}}
local knot = pc.sketch.spline_knots{sketch = s, spline = spline}[1].knot
pc.sketch.knot_multiplicity{sketch = s, spline = spline, knot = knot, multiplicity = 2}
assert(pc.sketch.spline_knots{sketch = s, spline = spline}[1].multiplicity == 2)
pc.sketch.knot_multiplicity{sketch = s, spline = spline, knot = knot, multiplicity = 0}
assert(#pc.sketch.spline_knots{sketch = s, spline = spline} == 0, "0 removes it")

pc.sketch.spline_knots: A spline's knots inside its ends and how many times each stands.

Notes:

See also pc.sketch.insert_knot, pc.sketch.knot_multiplicity.

Example: A half circle as a spline has one double knot.

local s = pc.sketch.new{plane = "XY"}
local arc = pc.sketch.arc{sketch = s, x = 0, y = 0, radius = 5, start = 0, ["end"] = 180}
local made = pc.sketch.to_bspline{sketch = s, items = {arc}}
local spline = made.elements[#made.elements]
local knots = pc.sketch.spline_knots{sketch = s, spline = spline}
assert(#knots == 1, "the knots at its ends are not listed")
assert(knots[1].knot == 0.5 and knots[1].multiplicity == 2)

pc.sketch.spline_weight: Weigh a spline's control point: more pulls the curve toward it.

Notes:

See also pc.sketch.to_bspline.

Example: A control point weighed three times.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "bspline", points = {{0, 0}, {10, 10}, {20, 0}, {30, 10}, "finish"}}
local spline = made.elements[#made.elements]
local function shape()
  for _, g in ipairs(pc.doc.feature{id = s}.fields.sketch.geometry) do
    if g.BSpline then return g.BSpline end
  end
end
local second = shape().control_points[2]
pc.sketch.spline_weight{sketch = s, spline = spline, point = second, weight = 3}
local weights = shape().weights
assert(weights[2] == 3 and weights[1] == 1)

pc.sketch.join: Merge curves that meet end to end into one B-spline following them.

Notes:

See also pc.sketch.to_bspline.

Example: A line and a quarter arc made one spline.

local s = pc.sketch.new{plane = "XY"}
local line = pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local arc = pc.sketch.arc{sketch = s, x = 10, y = 5, radius = 5, start = -90, ["end"] = 0}
local made = pc.sketch.join{sketch = s, items = {line, arc}}
assert(#made.elements > 0)
local count = {}
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do count[e.kind] = (count[e.kind] or 0) + 1 end
assert(count.line == nil and count.arc == nil, "both are replaced")
assert(count.other == 1, "by one spline")

pc.sketch.set_constraint: Make constraints driving or reference, active or not, parked or not.

Notes:

See also pc.sketch.set_value, pc.sketch.status.

Example: A repeated dimension made a reference.

local s = pc.sketch.new{plane = "XY"}
local sides = pc.sketch.rect{sketch = s, x = 0, y = 0, width = 30, height = 15}
pc.sketch.constrain{sketch = s, kind = "distance", items = {sides[1]}, value = 30}
local top = pc.sketch.constrain{sketch = s, kind = "distance", items = {sides[3]}}
assert(#pc.sketch.status{sketch = s}.redundant > 0, "the top's length says the bottom's again")
pc.sketch.set_constraint{sketch = s, items = top, driving = false}
assert(#pc.sketch.status{sketch = s}.redundant == 0, "a reference only measures")

pc.sketch.mirror_sketch: Mirror this sketch's geometry across its Y axis into a new sketch on the same plane.

Notes:

See also pc.sketch.merge, pc.sketch.draw.

Example: A rectangle mirrored across the Y axis.

local body = pc.doc.new_body{name = "Wing"}
local s = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.rect{sketch = s, x = 5, y = 0, width = 10, height = 5}
local mirrored = pc.sketch.mirror_sketch{sketch = s}
assert(pc.doc.feature{id = mirrored}.body == body)
assert(#pc.sketch.geometry{sketch = s} == 8, "the original keeps only its own")
pc.design.pad{sketch = mirrored, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.min[1] + 15) < 1e-6 and math.abs(m.max[1] + 5) < 1e-6, "across the sketch's Y axis")

pc.sketch.merge: A new sketch holding this one's geometry and other sketches', mapped onto its plane.

Notes:

See also pc.sketch.carbon_copy, pc.sketch.mirror_sketch.

Example: Two sketches merged and padded as one.

local body = pc.doc.new_body{name = "Pair"}
local left = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.rect{sketch = left, x = -15, y = 0, width = 10, height = 5}
local right = pc.sketch.new{body = body, plane = "XY", offset = 3}
pc.sketch.circle{sketch = right, x = 10, y = 2, radius = 2}
local merged = pc.sketch.merge{sketch = left, with = {right}}
assert(#pc.sketch.geometry{sketch = merged} == 10)
pc.design.pad{sketch = merged, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - (50 + math.pi * 4)) < 0.01, m.volume)
assert(math.abs(m.max[3] - 1) < 1e-6, "on the first sketch's plane")

pc.sketch.carbon_copy: Copy another sketch's geometry into this one, mapped onto its plane.

Notes:

See also pc.sketch.merge, pc.sketch.external_from.

Example: A rectangle copied onto a sketch above it.

local body = pc.doc.new_body{name = "Stack"}
local base = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.rect{sketch = base, x = 0, y = 0, width = 10, height = 5}
local top = pc.sketch.new{body = body, plane = "XY", offset = 5}
local made = pc.sketch.carbon_copy{sketch = top, from = base}
assert(#made.elements == 8 and #made.constraints == 4, "the lines, their ends and their constraints")
pc.design.pad{sketch = top, length = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 100) < 1e-3 and math.abs(m.min[3] - 5) < 1e-6)

pc.sketch.paste: Add geometry held as a sketch of its own, moved by a step.

Notes:

See also pc.sketch.carbon_copy.

Example: A rectangle pasted beside itself.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 5}
local clip = pc.doc.feature{id = s}.fields.sketch
local made = pc.sketch.paste{sketch = s, clipboard = clip, by = {20, 0}}
assert(#made.elements == 8)
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 100) < 1e-3 and math.abs(m.max[1] - 30) < 1e-6)

pc.sketch.external: Project edges of solids into the sketch as fixed references.

Notes:

See also pc.sketch.intersection, pc.doc.edges, pc.sketch.external_defining.

Example: A block's top edges projected and padded higher.

local body = pc.doc.new_body{name = "Block"}
local base = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.rect{sketch = base, x = 0, y = 0, width = 20, height = 10}
pc.design.pad{sketch = base, length = 5}
assert(#pc.doc.rebuild() == 0)
local top = pc.sketch.new{body = body, plane = "XY", offset = 5}
local made = pc.sketch.external{sketch = top, counts = true, edges = {
  {body = body, point = {10, 0, 5}, direction = {1, 0, 0}},
  {body = body, point = {20, 5, 5}, direction = {0, 1, 0}},
  {body = body, point = {10, 10, 5}, direction = {1, 0, 0}},
  {body = body, point = {0, 5, 5}, direction = {0, 1, 0}},
}}
assert(#made.elements > 0)
pc.design.pad{sketch = top, length = 3}
assert(#pc.doc.rebuild() == 0, "the four top edges close a profile")
assert(math.abs(pc.doc.measure{body = body}.volume - 20 * 10 * 8) < 1e-3)

pc.sketch.fit_scan: Fit lines and arcs to where every visible scan crosses the sketch plane.

Notes:

See also pc.sketch.intersection.

pc.sketch.intersection: Add where faces of solids cross the sketch plane, as fixed references.

Notes:

See also pc.sketch.external, pc.doc.faces.

Example: Where a block's top face crosses a sketch through its middle.

local body = pc.doc.new_body{name = "Block"}
local base = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.rect{sketch = base, x = 0, y = 0, width = 20, height = 10}
pc.design.pad{sketch = base, length = 5}
assert(#pc.doc.rebuild() == 0)
local cut = pc.sketch.new{body = body, plane = "XZ", offset = -5}
local made = pc.sketch.intersection{sketch = cut, faces = {{body = body, point = {10, 5, 5}, normal = {0, 0, 1}}}}
assert(#made.elements == 3, "a line and its two ends")
for _, e in ipairs(pc.sketch.geometry{sketch = cut}) do
  if e.kind == "line" then
    assert(e.external and e.points[1][2] == 5 and e.points[2][2] == 5, "the top face, at sketch y = 5")
  end
end

pc.sketch.constraints: List the sketch's constraints.

Notes:

See also pc.sketch.status, pc.sketch.set_constraint.

Example: An angle listed in degrees.

local s = pc.sketch.new{plane = "XY"}
local a = pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local b = pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 10}
local made = pc.sketch.constrain{sketch = s, kind = "angle", items = {a, b}}
local listed = pc.sketch.constraints{sketch = s}
assert(#listed == 1 and listed[1].id == made[1])
assert(listed[1].kind == "Angle" and math.abs(listed[1].value - 45) < 1e-4, "degrees")
assert(listed[1].items[1] == a and listed[1].items[2] == b)

pc.sketch.regions: List the regions the sketch's curves close.

Notes:

See also pc.design.pad, pc.sketch.wall_thickness.

Example: Two crossing circles close three regions.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 10}
pc.sketch.circle{sketch = s, x = 10, y = 0, radius = 10}
local regions = pc.sketch.regions{sketch = s}
assert(#regions == 3)
local lens = 2 * 100 * math.acos(0.5) - 5 * math.sqrt(300)
local found = false
for _, r in ipairs(regions) do
  assert(r.default, "every region is material")
  if math.abs(r.x - 5) < 1 then
    found = true
    assert(math.abs(r.area - lens) < 0.01 * lens, r.area)
  end
end
assert(found, "the lens sits between the centres")

pc.sketch.wall_thickness: How thin the sketch's closed profile gets, for printing.

Notes:

See also pc.sketch.status.

Example: A frame with 1 mm walls.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
pc.sketch.rect{sketch = s, x = 1, y = 1, width = 18, height = 8}
local wall = pc.sketch.wall_thickness{sketch = s, minimum = 2.5}
assert(math.abs(wall.thinnest - 1) < 1e-4, "the frame's wall is 1 mm")
assert(wall.thin and wall.minimum == 2.5)
assert(not pc.sketch.wall_thickness{sketch = s, minimum = 0.5}.thin)

pc.sketch.status: How constrained the sketch is, and what conflicts.

Notes:

See also pc.sketch.constrain, pc.sketch.constraints.

Example: A circle constrained, then over-constrained.

local s = pc.sketch.new{plane = "XY"}
local c = pc.sketch.circle{sketch = s, x = 3, y = 4, radius = 5}
assert(pc.sketch.status{sketch = s}.dof == 3, "a centre that moves and a radius")
pc.sketch.constrain{sketch = s, kind = "radius", items = {c}, value = 5}
local centre = pc.sketch.geometry{sketch = s}[1].id
pc.sketch.constrain{sketch = s, kind = "lock", items = {centre}}
local status = pc.sketch.status{sketch = s}
assert(status.dof == 0 and status.solved and #status.conflicting == 0)
local other = pc.sketch.circle{sketch = s, x = 20, y = 4, radius = 6}
pc.sketch.constrain{sketch = s, kind = "equal", items = {c, other}}
pc.sketch.constrain{sketch = s, kind = "diameter", items = {other}, value = 12}
status = pc.sketch.status{sketch = s}
assert(not status.solved and #status.conflicting == 3, "radius 5, equal, diameter 12")

pc.sketch.delete: Delete elements or constraints, and what depends on them.

Notes:

See also pc.sketch.construction, pc.sketch.repair.

Example: A corner deleted with the two lines on it.

local s = pc.sketch.new{plane = "XY"}
local corner = pc.sketch.point{sketch = s, x = 20, y = 10}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
assert(#pc.sketch.constraints{sketch = s} == 4)
pc.sketch.delete{sketch = s, items = {corner}}
local lines = 0
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do
  if e.kind == "line" then lines = lines + 1 end
end
assert(lines == 2, "the two lines ending on the corner went with it")
assert(#pc.sketch.constraints{sketch = s} == 2, "and the constraints on them")

pc.sketch.construction: Make elements construction geometry, or normal again.

Notes:

See also pc.sketch.draw, pc.sketch.delete.

Example: A circle that guides, then cuts.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local guide = pc.sketch.circle{sketch = s, x = 10, y = 5, radius = 3}
pc.sketch.construction{sketch = s, items = {guide}}
local pad = pc.design.pad{sketch = s, length = 1}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - 200) < 1e-3, "a construction circle cuts no hole")
pc.sketch.construction{sketch = s, items = {guide}, on = false}
assert(#pc.doc.rebuild() == 0)
m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
assert(math.abs(m.volume - (200 - math.pi * 9)) < 0.01, m.volume)

pc.sketch.internal_geometry: Show or hide curves' internal geometry: an ellipse's axes and foci, a parabola's or hyperbola's axis and focus, a B-spline's control polygon, as construction held to its curve.

Notes:

See also pc.sketch.draw, pc.sketch.constrain.

Example: An ellipse's axes and foci shown and hidden.

local s = pc.sketch.new{plane = "XY"}
local made = pc.sketch.draw{sketch = s, tool = "ellipse", points = {{0, 0}, {10, 0}, {0, 4}}}
local ellipse = made.elements[#made.elements]
local shown = pc.sketch.internal_geometry{sketch = s, items = {ellipse}}
assert(shown.shown and #shown.elements == 8, "two axes with their ends, and two foci")
for _, e in ipairs(pc.sketch.geometry{sketch = s}) do
  if e.kind == "line" then assert(e.construction) end
end
local hidden = pc.sketch.internal_geometry{sketch = s, items = {ellipse}}
assert(not hidden.shown and #pc.sketch.geometry{sketch = s} == 2, "the same call again takes them away")

pc.sketch.section_view: Cut away everything on the viewer's side of the sketch plane while it is edited.

Notes:

Example: The setting kept on the sketch.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.section_view{sketch = s}
assert(pc.doc.feature{id = s}.fields.section_view == true)
pc.sketch.section_view{sketch = s, on = false}
assert(pc.doc.feature{id = s}.fields.section_view == nil)

pc.sketch.remove_axis_alignment: Turn lines' horizontal and vertical constraints into parallel and perpendicular ones among them: the group keeps its shape and turns as a whole.

Notes:

See also pc.sketch.constrain, pc.sketch.status.

Example: A rectangle freed to turn.

local s = pc.sketch.new{plane = "XY"}
local sides = pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
assert(pc.sketch.status{sketch = s}.dof == 4)
assert(pc.sketch.remove_axis_alignment{sketch = s, items = sides} == 4)
for _, c in ipairs(pc.sketch.constraints{sketch = s}) do
  assert(c.kind == "Parallel" or c.kind == "Perpendicular", c.kind)
end
assert(pc.sketch.status{sketch = s}.dof == 5, "still a rectangle, free to turn")

pc.sketch.generator: Change the numbers a generated sketch is made from, or detach it into a plain sketch: a gear, a sprocket, a shaft or a keyway.

Notes:

See also pc.design.gear, pc.design.sprocket, pc.design.shaft, pc.doc.set_formula.

Example: A gear's teeth changed, and the tip diameter with them.

local gear = pc.design.gear{module = 1.5, teeth = 20}
assert(pc.sketch.generator{sketch = gear}.tip_diameter == 1.5 * 22)
local size = pc.sketch.generator{sketch = gear, teeth = 30}
assert(size.pitch_diameter == 1.5 * 30 and size.tip_diameter == 1.5 * 32)
pc.sketch.generator{sketch = gear, detach = true}
assert(pc.doc.feature{id = gear}.fields.generator == nil, "a plain sketch")

design

pc.design.pad: Pad a sketch.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.sketch.new, pc.sketch.regions, pc.design.pocket.

Example: The lens two crossing circles share, padded alone.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 10}
pc.sketch.circle{sketch = s, x = 10, y = 0, radius = 10}
local lens
for _, r in ipairs(pc.sketch.regions{sketch = s}) do
  if math.abs(r.x - 5) < 1 then lens = r.name end
end
local pad = pc.design.pad{sketch = s, length = 5, regions = {lens}}
assert(#pc.doc.rebuild() == 0, "the lens pads")
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
local area = 2 * 100 * math.acos(0.5) - 5 * math.sqrt(300)
assert(math.abs(m.volume - 5 * area) < 1e-3, m.volume)
assert(math.abs(m.min[1]) < 1e-6 and math.abs(m.max[1] - 10) < 1e-6)

pc.design.pocket: Cut a sketch into the body.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.sketch.new, pc.design.hole.

Example: A square window cut through a plate.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 30}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.rect{sketch = top, x = 15, y = 10, width = 10, height = 10}
pc.design.pocket{sketch = top, through_all = true}
assert(#pc.doc.rebuild() == 0, "the pocket builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (40 * 30 - 10 * 10) * 5) < 1e-3, volume)
assert(#pc.doc.faces{body = body} == 10, "six faces and four walls")

pc.design.revolve: Turn a sketch about an axis.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.groove, pc.design.helix.

Example: A tube turned from a rectangle beside the axis.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.rect{sketch = s, x = 10, y = 0, width = 5, height = 20}
local tube = pc.design.revolve{sketch = s}
assert(#pc.doc.rebuild() == 0, "the revolution builds")
local body = pc.doc.feature{id = tube}.body
-- The sketch's y axis on XZ is the world's Z: a tube 10 to 15 mm out, 20 tall.
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - math.pi * (15 ^ 2 - 10 ^ 2) * 20) < 1e-3, volume)

pc.design.groove: Cut a sketch turned about an axis.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.revolve, pc.design.pocket.

Example: A ring groove cut into a turned shaft.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 20}
local shaft = pc.design.revolve{sketch = s}
local body = pc.doc.feature{id = shaft}.body
local ring = pc.sketch.new{body = body, plane = "XZ"}
pc.sketch.rect{sketch = ring, x = 8, y = 8, width = 2, height = 4}
pc.design.groove{sketch = ring}
assert(#pc.doc.rebuild() == 0, "the groove builds")
-- A 4 mm wide ring cut 2 mm deep into a 10 mm radius shaft.
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (math.pi * 100 * 20 - math.pi * (100 - 64) * 4)) < 1e-3, volume)

pc.design.loft: Loft through sketches.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.subtractive_loft, pc.design.pipe.

Example: A square frustum lofted between two rectangles.

local base = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = base, x = -10, y = -10, width = 20, height = 20}
local body = pc.doc.feature{id = base}.body
local top = pc.sketch.new{body = body, plane = "XY", offset = 15}
pc.sketch.rect{sketch = top, x = -5, y = -5, width = 10, height = 10}
pc.design.loft{sections = {base, top}, ruled = true}
assert(#pc.doc.rebuild() == 0, "the loft builds")
-- A frustum of a square pyramid: h / 3 * (A1 + A2 + sqrt(A1 * A2)).
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - 15 / 3 * (400 + 100 + 200)) < 1e-3, volume)
assert(#pc.doc.faces{body = body} == 6)

pc.design.subtractive_loft: Cut a loft through sketches.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.loft.

Example: A conical dimple: a circle lofted down to a point and cut.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = -10, y = -10, width = 20, height = 20}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
local mouth = pc.sketch.new{body = body, plane = "XY", offset = 10}
pc.sketch.circle{sketch = mouth, x = 0, y = 0, radius = 5}
local tip = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.point{sketch = tip, x = 0, y = 0}
pc.design.subtractive_loft{sections = {mouth, tip}}
assert(#pc.doc.rebuild() == 0, "the cut builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (4000 - math.pi * 25 * 6 / 3)) < 1e-3, volume)

pc.design.pipe: Sweep a sketch along a path.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.subtractive_pipe, pc.sketch.polyline.

Example: A rod swept up and across along a bent path.

local profile = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = profile, x = 0, y = 0, radius = 2}
local body = pc.doc.feature{id = profile}.body
local path = pc.sketch.new{body = body, plane = "XZ"}
pc.sketch.polyline{sketch = path, points = {{0, 0}, {0, 20}, {15, 20}}}
-- Up 20 mm and across 15: the path is the body's latest other sketch.
local pipe = pc.design.pipe{sketch = profile}
assert(#pc.doc.rebuild() == 0, "the pipe builds")
assert(pc.doc.feature{id = pipe}.fields.Pipe.spine == path)
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - math.pi * 4 * 35) < 1e-3, volume)

pc.design.subtractive_pipe: Cut a sketch swept along a path.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.pipe.

Example: A half-round channel cut along the top of a block.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
local profile = pc.sketch.new{body = body, plane = "YZ"}
pc.sketch.circle{sketch = profile, x = 5, y = 10, radius = 2}
local path = pc.sketch.new{body = body, plane = "XZ", offset = -5}
pc.sketch.line{sketch = path, x1 = 0, y1 = 10, x2 = 20, y2 = 10}
pc.design.subtractive_pipe{sketch = profile, spine = path}
assert(#pc.doc.rebuild() == 0, "the channel builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (2000 - math.pi * 4 * 20 / 2)) < 1e-3, volume)

pc.design.helix: Sweep a sketch along a helix.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.subtractive_helix, pc.design.revolve.

Example: A square section swept a quarter turn.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.rect{sketch = s, x = 9, y = 0, width = 2, height = 2}
local coil = pc.design.helix{sketch = s, mode = "PitchTurns", pitch = 4, turns = 0.25}
assert(#pc.doc.rebuild() == 0, "the helix builds")
local body = pc.doc.feature{id = coil}.body
-- A 2 x 2 square whose centre runs a quarter turn at radius 10.
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - 4 * 2 * math.pi * 10 / 4) < 1e-3, volume)

pc.design.subtractive_helix: Cut a sketch swept along a helix.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.helix, pc.design.hole.

Example: A thread-like groove cut a quarter turn into a cylinder.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
local groove = pc.sketch.new{body = body, plane = "XZ"}
pc.sketch.rect{sketch = groove, x = 9, y = 4, width = 2, height = 2}
pc.design.subtractive_helix{sketch = groove, mode = "PitchTurns", pitch = 4, turns = 0.25}
assert(#pc.doc.rebuild() == 0, "the cut builds")
-- Only the half of the square inside the cylinder (1 x 2, centre at radius 9.5) is cut.
local cut = 2 * 2 * math.pi * 9.5 / 4
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (math.pi * 100 * 10 - cut)) < 1e-2, volume)

pc.design.primitive: Add a box, cylinder, sphere, cone, torus, ellipsoid, prism, wedge or tube.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.subtractive_primitive, pc.doc.new_body.

Example: A box with a cylinder standing on it.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 20, width = 10, height = 5}}}
pc.design.primitive{body = body, variant = "cylinder",
  kind = {Cylinder = {radius = 2, height = 6, angle_deg = 360}},
  placement = {origin = {10, 5, 5}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
assert(#pc.doc.rebuild() == 0, "the box and the post build")
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - (1000 + math.pi * 4 * 6)) < 1e-3, m.volume)
assert(math.abs(m.max[3] - 11) < 1e-6, "the post stands on the box")

pc.design.subtractive_primitive: Cut a box, cylinder, sphere, cone, torus, ellipsoid, prism, wedge or tube.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.primitive, pc.design.hole.

Example: A cylinder cut through the default box.

local body = pc.doc.new_body{}
pc.design.primitive{body = body}
pc.design.subtractive_primitive{body = body, variant = "cylinder",
  kind = {Cylinder = {radius = 3, height = 10, angle_deg = 360}},
  placement = {origin = {5, 5, 0}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
assert(#pc.doc.rebuild() == 0, "the box and the bore build")
-- The default box is 10 mm each way from the origin.
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1000 - math.pi * 9 * 10)) < 1e-3, volume)

pc.design.hole: Drill holes at a sketch's circles and points.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.sketch.circle, pc.design.pocket.

Example: An M3 clearance hole with a nut trap at its mouth.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 30, height = 20}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 6}}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 6}
pc.sketch.point{sketch = at, x = 15, y = 10}
pc.design.hole{sketch = at, thread = "M3", through_all = true, nut_trap = true}
assert(#pc.doc.rebuild() == 0, "the hole and its trap build")
-- The nut, 5.5 across the flats and 2.4 thick, each with 0.3 more.
local hex = math.sqrt(3) / 2 * 5.8 ^ 2
local bore = math.pi * 1.7 ^ 2
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (30 * 20 * 6 - bore * 3.3 - hex * 2.7)) < 1e-3, volume)

pc.design.thread: Cut a thread into a shaft's or a bore's round face.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.hole, pc.design.subtractive_helix.

Example: An M6 thread cut down a 6 mm shaft.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, variant = "cylinder",
  kind = {Cylinder = {radius = 3, height = 4, angle_deg = 360}}}
assert(#pc.doc.rebuild() == 0)
local plain = pc.doc.measure{body = body}.volume
-- Picked near the top: the thread starts at the top end.
pc.design.thread{body = body, face_point = {3, 0, 3.8}, face_normal = {1, 0, 0}, thread = "M6"}
assert(#pc.doc.rebuild() == 0, "the thread builds")
-- The groove takes about half the ring between the major and minor diameters.
local minor = 3 - 1.082532 / 2
local ring = math.pi * (9 - minor * minor) * 4
local cut = plain - pc.doc.measure{body = body}.volume
assert(cut > ring * 0.3 and cut < ring * 0.7, cut)

pc.design.rib: Grow a web from an open sketch line until it meets the solid.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.pad, pc.sketch.line.

Example: A web across a channel, from a line between its walls.

local body = pc.doc.new_body{}
local box = function(x, l, h)
  pc.design.primitive{body = body, kind = {Box = {length = l, width = 20, height = h}},
    placement = {origin = {x, -20, 0}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
end
box(0, 20, 2)
box(0, 2, 20)
box(18, 2, 20)
assert(#pc.doc.rebuild() == 0)
local channel = pc.doc.measure{body = body}.volume
local s = pc.sketch.new{body = body, plane = "XZ", offset = 10}
pc.sketch.line{sketch = s, x1 = 6, y1 = 12, x2 = 14, y2 = 12}
pc.design.rib{sketch = s, thickness = 2}
assert(#pc.doc.rebuild() == 0, "the rib builds")
-- Between the walls (16 mm), from the line down to the floor (10 mm), 2 mm thick.
local web = pc.doc.measure{body = body}.volume - channel
assert(math.abs(web - 16 * 10 * 2) < 1e-3, web)

pc.design.fillet: Round edges.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.design.chamfer.

Example: Every edge of a cube rounded with rolling-ball corners.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local pad = pc.design.pad{sketch = s, length = 20}
local body = pc.doc.feature{id = pad}.body
pc.design.fillet{body = body, radius = 3, mode = "Radius", corner = "RollingBall"}
assert(#pc.doc.rebuild() == 0, "the fillet builds")
-- The cube shrunk by the radius and grown back by a ball.
local core = 20 - 6
local want = core ^ 3 + 6 * core ^ 2 * 3 + 3 * math.pi * 9 * core
  + 4 / 3 * math.pi * 27
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - want) < 0.01, volume)

pc.design.chamfer: Bevel edges.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.design.fillet.

Example: The top face's edges bevelled.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 30}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
pc.design.chamfer{body = body, size = 2,
  edges = {Faces = {{point = {20, 15, 10}, normal = {0, 0, 1}}}}}
assert(#pc.doc.rebuild() == 0, "the chamfer builds")
assert(#pc.doc.faces{body = body} == 10, "six faces and four bevels")
-- A 2 x 2 prism along each edge, less what two share at a corner.
local taken = 2 * (40 + 30) * 2 - 4 * 8 / 3
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (12000 - taken)) < 0.01, volume)

pc.design.draft: Tilt faces.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.design.thickness.

Example: One side of a block drafted 10 degrees from its bottom.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
-- The bottom is the neutral plane; the right side leans out 10 degrees above it.
pc.design.draft{body = body, angle_deg = 10,
  face_point = {10, 5, 0}, face_normal = {0, 0, -1},
  faces = {{point = {20, 5, 5}, normal = {1, 0, 0}}}}
assert(#pc.doc.rebuild() == 0, "the draft builds")
local lean = 10 * math.tan(math.rad(10))
local m = pc.doc.measure{body = body}
assert(math.abs(m.max[1] - (20 + lean)) < 1e-4, m.max[1])
assert(math.abs(m.volume - (2000 + lean * 10 / 2 * 10)) < 1e-3, m.volume)

pc.design.thickness: Hollow the solid.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.design.draft.

Example: A block hollowed into an open box.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
-- An open box: the top face taken away, 1 mm walls left inside.
pc.design.thickness{body = body, face_point = {10, 5, 10}, face_normal = {0, 0, 1}}
assert(#pc.doc.rebuild() == 0, "the shell builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (2000 - 18 * 8 * 9)) < 1e-3, volume)

pc.design.delete_faces: Delete faces and close the openings from their neighbours.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.design.recognize_holes.

Example: A through hole closed by deleting its wall.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 20, width = 10, height = 5}}}
local at = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.circle{sketch = at, x = 10, y = 5, radius = 2}
pc.design.pocket{sketch = at, through_all = true}
-- The bore's wall, picked at x = 12 where it faces the axis: the hole closes.
pc.design.delete_faces{body = body, face_point = {12, 5, 2.5}, face_normal = {-1, 0, 0}}
assert(#pc.doc.rebuild() == 0, "the deletion builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - 1000) < 1e-3, volume)
assert(#pc.doc.faces{body = body} == 6)

pc.design.offset_faces: Push or pull faces along their normals, their neighbours following.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.move_faces, pc.doc.faces.

Example: A hole widened by 1 mm all round.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.circle{sketch = at, x = 10, y = 5, radius = 2}
pc.design.pocket{sketch = at, through_all = true}
-- A bore's outward normal points at its axis: a negative distance widens it.
pc.design.offset_faces{body = body, distance = -1,
  face_point = {12, 5, 2.5}, face_normal = {-1, 0, 0}}
assert(#pc.doc.rebuild() == 0, "the offset builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1000 - math.pi * 9 * 5)) < 1e-3, volume)

pc.design.scale_body: Scale the whole solid about a point.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.scaled.

Example: A box doubled about its centre, then stretched along X alone.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 10, width = 10, height = 10}}}
local scale = pc.design.scale_body{body = body, factor = 2, about = "BodyCentre"}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 8000) < 1e-6)
assert(math.abs(m.min[1] + 5) < 1e-6 and math.abs(m.max[1] - 15) < 1e-6)
pc.design.set{feature = scale, per_axis = true, factors = {3, 1, 1}, about = "Origin"}
assert(#pc.doc.rebuild() == 0)
m = pc.doc.measure{body = body}
assert(math.abs(m.max[1] - 30) < 1e-6 and math.abs(m.max[2] - 10) < 1e-6)

pc.design.offset_solid: Grow or shrink the whole solid by a distance.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.offset_faces, pc.design.thickness.

Example: A box grown by a millimetre, then shrunk by one.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 10, width = 10, height = 10}}}
local offset = pc.design.offset_solid{body = body, distance = 1}
assert(#pc.doc.rebuild() == 0)
local size = function()
  local m = pc.doc.measure{body = body}
  return m.max[1] - m.min[1], m.max[2] - m.min[2], m.max[3] - m.min[3]
end
local x, y, z = size()
assert(math.abs(x - 12) < 1e-6 and math.abs(y - 12) < 1e-6 and math.abs(z - 12) < 1e-6)
pc.design.set{feature = offset, distance = -1}
assert(#pc.doc.rebuild() == 0)
x = size()
assert(math.abs(x - 8) < 1e-6 and math.abs(pc.doc.measure{body = body}.volume - 512) < 1e-6)

pc.design.move_faces: Move or turn faces, their neighbours following.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.offset_faces, pc.doc.faces.

Example: A block's top face tilted about its middle.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
-- The top face turned 10 degrees about a line across its middle.
pc.design.move_faces{body = body, face_point = {10, 5, 10}, face_normal = {0, 0, 1},
  translation = {0, 0, 0}, angle_deg = 10, axis_point = {10, 0, 10}, axis_dir = {0, 1, 0}}
assert(#pc.doc.rebuild() == 0, "the move builds")
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 2000) < 1e-3, "what one end gains the other loses")
assert(math.abs(m.max[3] - (10 + 10 * math.tan(math.rad(10)))) < 1e-4, m.max[3])

pc.design.project: Project a sketch onto faces as split lines, an emboss or a deboss.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.faces, pc.sketch.new.

Example: A raised label on a cylinder's side.

local body = pc.doc.new_body{}
pc.design.primitive{body = body,
  kind = {Cylinder = {radius = 10, height = 20, angle_deg = 360}}}
-- A sketch standing in front of the side, facing away from it.
local label = pc.sketch.new{body = body, origin = {0, -15, 10},
  normal = {0, -1, 0}, x_axis = {1, 0, 0}}
pc.sketch.rect{sketch = label, x = -3, y = -2, width = 6, height = 4}
pc.design.project{sketch = label, mode = "Emboss", height = 1,
  face_point = {0, -10, 10}, face_normal = {0, -1, 0}}
assert(#pc.doc.rebuild() == 0, "the emboss builds")
local volume = pc.doc.measure{body = body}.volume
-- A ring sector 10 to 11 mm out, as wide as the label, 4 mm tall.
local added = 2 * math.asin(0.3) * (121 - 100) / 2 * 4
assert(math.abs(volume - (math.pi * 100 * 20 + added)) < 0.1 * added, volume)

pc.design.text: Write text on a face: raised, sunk or imprinted, wrapped onto a curved one.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.project, pc.sketch.text.

Example: A raised label on a box's top.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 40, width = 20, height = 10}}}
local label = pc.design.text{body = body, text = "OK", size = 8, height = 1,
  face_point = {20, 10, 10}, face_normal = {0, 0, 1}}
assert(#pc.doc.rebuild() == 0, "the text builds")
local m = pc.doc.measure{body = body}
assert(m.max[3] > 10.9 and m.max[3] < 11.1, "letters stand 1 mm proud")
assert(m.volume > 40 * 20 * 10, "material added")

pc.design.mirror: Mirror the last feature.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.linear_pattern.

Example: A post mirrored across the YZ plane.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = -10, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local corner = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.rect{sketch = corner, x = 5, y = 0, width = 3, height = 3}
local post = pc.design.pad{sketch = corner, length = 4}
pc.design.mirror{body = body, originals = {post}, plane = "YZ"}
assert(#pc.doc.rebuild() == 0, "the mirror builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1000 + 2 * 36)) < 1e-6, volume)

pc.design.linear_pattern: Repeat the last feature along a line.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.polar_pattern.

Example: A hole repeated three times along X.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 30, height = 10}
local pad = pc.design.pad{sketch = s, length = 4}
local body = pc.doc.feature{id = pad}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.circle{sketch = at, x = 5, y = 5, radius = 2}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- Three holes 10 mm apart: 20 mm from the first to the last.
local pattern = pc.design.linear_pattern{body = body, originals = {hole}, axis = "X", length = 20, occurrences = 3}
assert(#pc.doc.rebuild() == 0, "the pattern builds")
local xs = {}
for _, face in ipairs(pc.doc.faces{body = body}) do
  if face.kind == "cylinder" then xs[#xs + 1] = face.axis.point[1] end
end
table.sort(xs)
assert(#xs == 3 and math.abs(xs[1] - 5) < 1e-6 and math.abs(xs[3] - 25) < 1e-6)
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (30 * 10 - 3 * math.pi * 4) * 4) < 1e-3, volume)
-- The middle hole left out: the original is occurrence 0.
pc.design.set{feature = pattern, skipped = {1}}
assert(#pc.doc.rebuild() == 0, "the pattern builds")
volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (30 * 10 - 2 * math.pi * 4) * 4) < 1e-3, volume)

pc.design.polar_pattern: Repeat the last feature about an axis.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.linear_pattern.

Example: Six holes round a disc.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 20}
local disc = pc.design.pad{sketch = s, length = 3}
local body = pc.doc.feature{id = disc}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 3}
pc.sketch.circle{sketch = at, x = 12, y = 0, radius = 2}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- Six holes around Z: 360 degrees is the whole turn, not a seventh copy on the first.
pc.design.polar_pattern{body = body, originals = {hole}, axis = "Z", angle_deg = 360, occurrences = 6}
assert(#pc.doc.rebuild() == 0, "the pattern builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (math.pi * 400 - 6 * math.pi * 4) * 3) < 1e-3, volume)

pc.design.circular_pattern: Repeat the last feature in concentric rings about an axis.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.polar_pattern.

Example: Two rings of holes round a disc, four and eight.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 30}
local disc = pc.design.pad{sketch = s, length = 3}
local body = pc.doc.feature{id = disc}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 3}
pc.sketch.circle{sketch = at, x = 10, y = 0, radius = 2}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- The inner ring at radius 10, the outer 10 mm further out.
pc.design.circular_pattern{body = body, originals = {hole}, axis = "Z",
  outward = "X", spacing = 10, counts = {4, 8}}
assert(#pc.doc.rebuild() == 0, "the rings build")
local holes = 0
for _, face in ipairs(pc.doc.faces{body = body}) do
  if face.kind == "cylinder" and face.radius < 3 then holes = holes + 1 end
end
assert(holes == 12, holes)
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (math.pi * 900 - 12 * math.pi * 4) * 3) < 1e-3, volume)

pc.design.point_pattern: Repeat the last feature at a sketch's points.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.hole.

Example: A hole at each corner of a plate.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 30}
local plate = pc.design.pad{sketch = s, length = 4}
local body = pc.doc.feature{id = plate}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.circle{sketch = at, x = 5, y = 5, radius = 1.5}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- The first point is where the hole stands.
local corners = pc.sketch.new{body = body, plane = "XY", offset = 4}
for _, p in ipairs({{5, 5}, {35, 5}, {35, 25}, {5, 25}}) do
  pc.sketch.point{sketch = corners, x = p[1], y = p[2]}
end
pc.design.point_pattern{sketch = corners, originals = {hole}}
assert(#pc.doc.rebuild() == 0, "the pattern builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1200 - 4 * math.pi * 2.25) * 4) < 1e-3, volume)

pc.design.path_pattern: Repeat the last feature along a sketch's curves or an edge.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.polar_pattern, pc.doc.edges.

Example: Five holes along an arc.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = -40, y = -40, width = 80, height = 80}
local plate = pc.design.pad{sketch = s, length = 4}
local body = pc.doc.feature{id = plate}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.circle{sketch = at, x = 30, y = 0, radius = 2}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- A quarter arc of radius 30 from where the hole stands.
local arc = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.arc{sketch = arc, x = 0, y = 0, radius = 30, start = 0, ["end"] = 90}
pc.design.path_pattern{sketch = arc, originals = {hole}, occurrences = 5}
assert(#pc.doc.rebuild() == 0, "the pattern builds")
local ys = {}
for _, face in ipairs(pc.doc.faces{body = body}) do
  if face.kind == "cylinder" then ys[#ys + 1] = face.axis.point[2] end
end
table.sort(ys)
assert(#ys == 5 and math.abs(ys[5] - 30) < 1e-6, #ys)
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (6400 - 5 * math.pi * 4) * 4) < 1e-3, volume)

pc.design.fill_pattern: Repeat the last feature over a sketch's area or a flat face in a grid or honeycomb.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.point_pattern.

Example: A plate vented with a honeycomb of holes.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 30}
local plate = pc.design.pad{sketch = s, length = 4}
local body = pc.doc.feature{id = plate}.body
local at = pc.sketch.new{body = body, plane = "XY", offset = 4}
pc.sketch.circle{sketch = at, x = 5, y = 5, radius = 1.5}
local hole = pc.design.pocket{sketch = at, through_all = true}
-- The plate's outline is the region; each hole's rim stays 1 mm inside.
pc.design.fill_pattern{sketch = s, originals = {hole}, lattice = "Honeycomb",
  spacing = 8, margin = 1}
assert(#pc.doc.rebuild() == 0, "the fill builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1200 - 18 * math.pi * 2.25) * 4) < 1e-3, volume)

pc.design.scaled: Scale the last feature.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.design.linear_pattern.

Example: A block repeated at 1.5 and 2 times its size.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 10, y = 0, width = 10, height = 10}
local pad = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = pad}.body
-- Three occurrences, the original counted: scaled 1, 1.5 and 2 about the origin.
pc.design.scaled{body = body, originals = {pad},
  steps = {{Scale = {factor = 2, center = {0, 0, 0}, occurrences = 3}}}}
assert(#pc.doc.rebuild() == 0, "the scaled copies build")
local m = pc.doc.measure{body = body}
assert(math.abs(m.max[1] - 40) < 1e-6, m.max[1])
-- 1000 + 3375 + 8000, less the two overlaps (500 and 2250).
assert(math.abs(m.volume - 9625) < 1e-3, m.volume)

pc.design.boolean: Combine with another body.

Notes:

See also pc.doc.rebuild, pc.design.set, pc.doc.new_body, pc.doc.set_visible.

Example: A corner cut out of a block by another body.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local block = pc.design.pad{sketch = s, length = 10}
local body = pc.doc.feature{id = block}.body
local t = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = t, x = 20, y = 20, radius = 5}
local post = pc.design.pad{sketch = t, length = 30}
local tool = pc.doc.feature{id = post}.body
pc.design.boolean{body = body, tool_body = tool, kind = "Cut"}
assert(#pc.doc.rebuild() == 0, "the boolean builds")
-- A quarter of the post stands in the block's corner.
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (4000 - math.pi * 25 / 4 * 10)) < 1e-3, volume)
assert(pc.doc.measure{body = tool}.volume > 0, "the tool body keeps its own solid")

pc.design.set: Change fields of a Design feature or a datum.

Notes:

See also pc.doc.feature, pc.doc.set_formula.

Example: A pad made taller.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
pc.design.set{feature = pad, length = 8}
assert(pc.doc.feature{id = pad}.fields.Pad.length == 8)
assert(#pc.doc.rebuild() == 0, "the pad builds")
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - 20 * 10 * 8) < 1e-3, volume)

pc.design.datum: Add a datum plane, line, point or coordinate system.

Notes:

See also pc.sketch.new, pc.design.set.

Example: A boss on a plane that follows the top face.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
-- A plane on the top face, its origin where the face was given.
local plane = pc.design.datum{kind = "plane", body = body, mode = "face",
  face_point = {10, 5, 5}, face_normal = {0, 0, 1}}
local on = pc.sketch.new{body = body, on = plane}
pc.sketch.circle{sketch = on, x = 0, y = 0, radius = 2}
pc.design.pad{sketch = on, length = 3}
assert(#pc.doc.rebuild() == 0, "the boss builds")
assert(math.abs(pc.doc.measure{body = body}.volume - (1000 + math.pi * 4 * 3)) < 1e-3)
-- The plane follows the face: a taller block lifts the boss with it.
pc.design.set{feature = pad, length = 8}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.max[3] - 11) < 1e-6)

pc.design.borrow: Borrow another body's sketch, or faces and edges of its solid.

Notes:

See also pc.design.freeze, pc.design.map_sketch, pc.doc.faces.

Example: A sketch and a face of one body padded in another.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local base = pc.design.pad{sketch = s, length = 5}
local lender = pc.doc.feature{id = base}.body
local body = pc.doc.new_body{}
-- The other body's sketch, borrowed: a feature takes the borrow as its sketch.
local lent = pc.design.borrow{body = body, sketch = s}
local copy = pc.design.pad{sketch = lent, length = 3}
assert(pc.doc.feature{id = copy}.body == body)
-- Its top face, borrowed once the lender is built: a pad takes it as its profile.
assert(#pc.doc.rebuild() == 0)
local face = pc.design.borrow{body = body, from = lender,
  faces = {{point = {10, 5, 5}, normal = {0, 0, 1}}}}
pc.design.pad{body = body, profile_borrowed = {borrow = face, index = 0}, length = 2}
assert(#pc.doc.rebuild() == 0, "both pads build")
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 20 * 10 * (3 + 2)) < 1e-3, m.volume)
assert(math.abs(m.max[3] - 7) < 1e-6, "the second pad stands on the lent face")

pc.design.read_hole: A round's size off a scan, and the nearest standard.

Notes:

See also pc.design.hole, pc.design.fillet.

Example: A clearance hole scanned and read as an M6's.

local plate = pc.doc.new_body{}
pc.design.primitive{body = plate, kind = {Box = {length = 30, width = 20, height = 5}}}
pc.design.subtractive_primitive{body = plate, variant = "cylinder",
  kind = {Cylinder = {radius = 3.3, height = 7, angle_deg = 360}},
  placement = {origin = {12, 10, -1}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {plate}, tolerance = 0.002}
pc.doc.set_visible{id = plate, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local r = pc.design.read_hole{scan = scan, at = {15.3, 10, 2.5}}
assert(r.hole and math.abs(r.diameter - 6.6) < 0.01 and math.abs(r.depth - 5) < 0.01, r.diameter)
assert(r.nearest[1].size == "M6" and r.nearest[1].as == "normal clearance", r.nearest[1].size)
assert(r.fillet == nil and r.sweep > 300, r.sweep)

pc.design.snap_to_scan: Move a face of the body onto a scan.

Notes:

See also pc.design.move_faces, pc.design.offset_faces.

Example: A block's top snapped 0.4 mm up and its bore widened to the scan's.

local function block(height, radius)
  local b = pc.doc.new_body{}
  pc.design.primitive{body = b, kind = {Box = {length = 20, width = 10, height = height}}}
  pc.design.subtractive_primitive{body = b, variant = "cylinder",
    kind = {Cylinder = {radius = radius, height = 20, angle_deg = 360}},
    placement = {origin = {10, 5, -5}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
  return b
end
local printed = block(5.4, 3.2)
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {printed}, tolerance = 0.002}
pc.doc.set_visible{id = printed, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local model = block(5, 3)
assert(#pc.doc.rebuild() == 0)
local top = pc.design.snap_to_scan{body = model, face_point = {2, 2, 5},
  face_normal = {0, 0, 1}, scan = scan, at = {2, 2, 5.4}}
assert(math.abs(top.moved - 0.4) < 1e-3 and top.angle < 0.01, top.moved)
local bore = pc.design.snap_to_scan{body = model, face_point = {13, 5, 2},
  face_normal = {-1, 0, 0}, scan = scan, at = {13.2, 5, 2.5}}
assert(math.abs(bore.fitted - 3.2) < 0.01 and bore.design == 3, bore.fitted)
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = model}
local want = 20 * 10 * 5.4 - math.pi * 3.2 ^ 2 * 5.4
assert(math.abs(m.volume - want) < 0.5, m.volume)

pc.design.scan_symmetry: A scan's symmetry plane as a datum, for Mirror.

Notes:

See also pc.design.mirror, pc.inspect.use_symmetry.

Example: A scan of a block with a blind hole on its middle line, symmetric about x = 10 alone.

local block = pc.doc.new_body{}
pc.design.primitive{body = block, kind = {Box = {length = 20, width = 12, height = 5}}}
pc.design.subtractive_primitive{body = block, variant = "cylinder",
  kind = {Cylinder = {radius = 2, height = 7, angle_deg = 360}},
  placement = {origin = {10, 3, 2}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {block}, tolerance = 0.002}
pc.doc.set_visible{id = block, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local model = pc.doc.new_body{}
local s = pc.design.scan_symmetry{scan = scan, body = model}
assert(s.rms < 0.01 and math.abs(math.abs(s.normal.x) - 1) < 1e-3, s.rms)
assert(math.abs(s.point.x - 10) < 0.01, s.point.x)
-- Half the block modelled, then mirrored about the scan's plane.
pc.design.primitive{body = model, kind = {Box = {length = 10, width = 12, height = 5}}}
pc.design.mirror{body = model}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = model}
assert(math.abs(m.min[1]) < 1e-6 and math.abs(m.max[1] - 20) < 0.01, m.max[1])

pc.design.read_thread: A thread's pitch, size and hand off a scan.

Notes:

See also pc.design.read_hole, pc.design.hole.

Example: A scanned M8 thread read back: a synthetic scan of a bolt's thread, 1.25 pitch, right-handed, written as an STL and imported.

local stl = {"solid bolt\n"}
local function write(text) stl[#stl + 1] = text end
local pitch, turns, around, along = 1.25, 5, 48, 120
local function at(i, j)
  local a = 2 * math.pi * i / around
  local t = turns * pitch * j / along
  local phase = (t / pitch - a / (2 * math.pi)) % 1
  local r = 4 - 0.68 * math.abs(2 * phase - 1)
  return {r * math.cos(a), r * math.sin(a), t}
end
local function facet(p, q, s)
  write("facet normal 0 0 0\nouter loop\n")
  for _, v in ipairs({p, q, s}) do
    write(string.format("vertex %.6f %.6f %.6f\n", v[1], v[2], v[3]))
  end
  write("endloop\nendfacet\n")
end
for j = 0, along - 1 do
  for i = 0, around - 1 do
    local a, b = at(i, j), at(i + 1, j)
    local c, d = at(i + 1, j + 1), at(i, j + 1)
    facet(a, b, c)
    facet(a, c, d)
  end
end
write("endsolid bolt\n")
local path = pc.file.temp_path{name = "bolt.stl", text = table.concat(stl)}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local p = at(10, 60)
local t = pc.design.read_thread{scan = scan, at = {p[1], p[2], p[3]}}
assert(math.abs(t.pitch - 1.25) < 0.01 and t.right_handed and not t.internal, t.pitch)
assert(t.nearest[1].size == "M8", t.nearest[1].size)

pc.design.scan_deviation: How a body lies against a scan.

Notes:

See also pc.inspect.compare.

Example: A scan of a 10 mm cube against a body 2 mm short of it.

local cube = pc.doc.new_body{}
pc.design.primitive{body = cube}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {cube}}
pc.doc.set_visible{id = cube, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local short = pc.doc.new_body{}
pc.design.primitive{body = short, kind = {Box = {length = 10, width = 10, height = 8}}}
assert(#pc.doc.rebuild() == 0)
local d = pc.design.scan_deviation{body = short, scan = scan}
assert(d.within == 0.5 and d.outside == 0.5 and d.inside == 0, d.within)

pc.design.recognize_holes: Make the round holes of a body's solid Hole features: their faces deleted, and each set of alike holes drilled again from a sketch of their centres.

Notes:

See also pc.design.hole, pc.design.delete_faces.

Example: Two bores made a Hole feature and widened.

local body = pc.doc.new_body{}
pc.design.primitive{body = body, kind = {Box = {length = 20, width = 10, height = 5}}}
local at = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.circle{sketch = at, x = 5, y = 5, radius = 2}
pc.sketch.circle{sketch = at, x = 15, y = 5, radius = 2}
pc.design.pocket{sketch = at, through_all = true}
assert(#pc.doc.rebuild() == 0)
local made = pc.design.recognize_holes{body = body}
-- The two alike bores: one Delete Faces, one sketch of centres and one Hole.
assert(made.holes == 2 and made.left == 0 and #made.features == 3)
assert(#pc.doc.rebuild() == 0, "the holes drill again")
local hole = made.features[3]
assert(pc.doc.feature{id = hole}.fields.Hole.diameter == 4)
pc.design.set{feature = hole, diameter = 6}
assert(#pc.doc.rebuild() == 0)
local volume = pc.doc.measure{body = body}.volume
assert(math.abs(volume - (1000 - 2 * math.pi * 9 * 5)) < 1e-3, volume)

pc.design.split: Split a body in two along a plane or a sketch, each piece a body following it.

Notes:

See also pc.design.set, pc.doc.measure.

Example: A plate split in two, and the pieces following an edit.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 20}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local pieces = pc.design.split{body = body, plane = "YZ", offset = 10}
assert(#pieces == 2 and #pc.doc.rebuild() == 0)
local volume = function(b) return pc.doc.measure{body = b}.volume end
assert(math.abs(volume(pieces[1]) - 3000) < 1e-3, volume(pieces[1]))
assert(math.abs(volume(pieces[2]) - 1000) < 1e-3, volume(pieces[2]))
-- The pieces follow the body split.
pc.design.set{feature = pad, length = 10}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(volume(pieces[1]) + volume(pieces[2]) - 8000) < 1e-3)
-- One piece's cut moved moves the other's.
local cut = pc.doc.features{body = pieces[1]}[2].id
pc.design.set{feature = cut, offset = 20}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(volume(pieces[2]) - 4000) < 1e-3, volume(pieces[2]))

pc.design.separate: Make each piece of a body's solid a body of its own, following it.

Notes:

See also pc.doc.measure.

Example: A plate pocketed through into two pieces, separated.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 20}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local slot = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.rect{sketch = slot, x = 10, y = -1, width = 2, height = 22}
pc.design.pocket{sketch = slot, through_all = true}
assert(#pc.doc.rebuild() == 0)
local pieces = pc.design.separate{body = body}
assert(#pieces == 2 and #pc.doc.rebuild() == 0)
local a = pc.doc.measure{body = pieces[1]}.volume
local b = pc.doc.measure{body = pieces[2]}.volume
assert(math.abs(a + b - 3800) < 1e-3, a + b)
assert(math.abs(math.min(a, b) - 1000) < 1e-3, math.min(a, b))
-- A body of one piece has nothing to separate.
assert(not pcall(pc.design.separate, {body = pieces[1]}))

pc.design.section: Cut a body by a plane and keep the outline as a sketch, or several parallel cuts.

Notes:

See also pc.design.pad, pc.sketch.regions.

Example: A plate with a hole cut across its middle and the outline padded again.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 20}
pc.sketch.circle{sketch = s, x = 20, y = 10, radius = 5}
local pad = pc.design.pad{sketch = s, length = 6}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local cut = pc.design.section{body = body, plane = "XY", offset = 3}
assert(#cut == 1)
local again = pc.design.pad{sketch = cut[1], length = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = again}.body}
assert(math.abs(m.volume - 2 * (800 - math.pi * 25)) < 1e-3, m.volume)

pc.design.freeze: Freeze borrowed geometry as it is now, or let it follow its source again.

Notes:

See also pc.design.borrow.

Example: A borrowed sketch frozen, then followed again.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local body = pc.doc.new_body{}
local lent = pc.design.borrow{body = body, sketch = s}
pc.design.pad{sketch = lent, length = 3}
pc.design.freeze{feature = lent}
-- A rectangle added to the source after the freeze is not taken.
pc.sketch.rect{sketch = s, x = 30, y = 0, width = 10, height = 10}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 600) < 1e-3)
pc.design.freeze{feature = lent, frozen = false}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 900) < 1e-3, "following it again")

pc.design.map_sketch: Put an existing sketch on a flat face its body borrows from another body; the sketch then follows the face.

Notes:

See also pc.design.borrow, pc.sketch.set_plane.

Example: A post's sketch moved onto a face another body lends.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local block = pc.design.pad{sketch = s, length = 10}
local lender = pc.doc.feature{id = block}.body
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.new_body{}
local top = pc.design.borrow{body = body, from = lender,
  faces = {{point = {10, 10, 10}, normal = {0, 0, 1}}}}
local post = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.circle{sketch = post, x = 10, y = 10, radius = 3}
pc.design.pad{sketch = post, length = 5}
pc.design.map_sketch{sketch = post, borrow = top}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.min[3] - 10) < 1e-6, "on the lent top")
-- The lender grows: the post rises with its top.
pc.design.set{feature = block, length = 15}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.min[3] - 15) < 1e-6, "follows the top")

pc.design.move_to_body: Move a feature into another body's history, with the sketch and datums only it uses.

Notes:

See also pc.design.duplicate, pc.doc.new_body.

Example: A boss moved into a body of its own.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local top = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.rect{sketch = top, x = 0, y = 0, width = 5, height = 5}
local boss = pc.design.pad{sketch = top, length = 5}
local other = pc.doc.new_body{}
local moved = pc.design.move_to_body{feature = boss, body = other}
-- The boss went with the sketch only it used.
assert(#moved == 2 and moved[1] == top and moved[2] == boss)
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.volume - 1000) < 1e-3)
assert(math.abs(pc.doc.measure{body = other}.volume - 125) < 1e-3)

pc.design.duplicate: Make a copy of a feature, with its own copies of the sketches and datums it reads.

Notes:

See also pc.design.set, pc.design.move_to_body.

Example: A pad copied and turned to grow the other way.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
local made = pc.design.duplicate{feature = pad}
-- A sketch of its own and the copied pad, last.
assert(#made == 2 and made[1] ~= s)
local copy = made[2]
pc.design.set{feature = copy, reversed = true}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 1000) < 1e-3 and math.abs(m.min[3] + 5) < 1e-6, m.volume)

pc.design.centre_line: Measure the centre line of a tube-like solid between two of its faces.

Notes:

See also pc.doc.faces, pc.doc.measure.

Example: The centre line of a quarter bend.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.circle{sketch = s, x = 10, y = 0, radius = 2}
local bend = pc.design.revolve{sketch = s, angle_deg = 90}
assert(#pc.doc.rebuild() == 0, "the bend builds")
local body = pc.doc.feature{id = bend}.body
local line = pc.design.centre_line{body = body,
  from_point = {10, 0, 0}, from_normal = {0, -1, 0},
  to_point = {0, 10, 0}, to_normal = {-1, 0, 0}}
-- A quarter circle of radius 10.
assert(math.abs(line.length - math.pi * 10 / 2) < 0.05, line.length)
assert(not line.straight)

pc.design.gear: Make an involute spur gear's profile, outer or internal (ring), as a sketch to pad.

Notes:

See also pc.sketch.generator, pc.design.pad.

Example: A 12-tooth gear padded 5 mm.

local gear = pc.design.gear{module = 2, teeth = 12, bore = 6}
assert(pc.sketch.generator{sketch = gear}.undercut, "12 teeth are undercut")
local pad = pc.design.pad{sketch = gear, length = 5}
assert(#pc.doc.rebuild() == 0, "the gear builds")
local m = pc.doc.measure{body = pc.doc.feature{id = pad}.body}
-- The tip circle is 2 * (12 + 2) = 28 mm across; a tooth points along X.
assert(math.abs(m.max[1] - 14) < 1e-3 and math.abs(m.min[1] + 14) < 1e-3)
assert(math.abs(m.max[3] - 5) < 1e-6)

pc.design.sprocket: Make a roller chain sprocket's profile (ISO 606 teeth), as a sketch to pad.

Notes:

See also pc.sketch.generator, pc.design.pad.

Example: A 9-tooth sprocket, its diameters read back.

local sprocket = pc.design.sprocket{teeth = 9, bore = 6}
local size = pc.sketch.generator{sketch = sprocket}
-- A chain's pitch circle: the pitch over the sine of half a tooth's angle.
assert(math.abs(size.pitch_diameter - 12.7 / math.sin(math.pi / 9)) < 1e-3)
local pad = pc.design.pad{sketch = sprocket, length = 3}
assert(#pc.doc.rebuild() == 0, "the sprocket builds")

pc.design.shaft: Make a stepped shaft's half section, as a sketch to revolve about its vertical axis.

Notes:

See also pc.sketch.generator, pc.design.revolve.

Example: A two-step shaft turned from its section.

local section = pc.design.shaft{start_chamfer = 0,
  sections = {{length = 20, diameter = 10}, {length = 30, diameter = 16}}}
local turn = pc.design.revolve{sketch = section}
assert(#pc.doc.rebuild() == 0, "the shaft builds")
local m = pc.doc.measure{body = pc.doc.feature{id = turn}.body}
local volume = math.pi * (5 ^ 2 * 20 + 8 ^ 2 * 30)
assert(math.abs(m.volume - volume) < 1e-3, m.volume)
assert(math.abs(m.max[3] - 50) < 1e-6, "50 mm long, up Z")

pc.design.keyway: Make the slot of a parallel key in a shaft (DIN 6885), as a sketch to pocket.

Notes:

See also pc.sketch.generator, pc.design.pocket, pc.design.shaft.

Example: A keyway pocketed into a 20 mm shaft.

local section = pc.design.shaft{start_chamfer = 0, sections = {{length = 60, diameter = 20}}}
local turn = pc.design.revolve{sketch = section}
local body = pc.doc.feature{id = turn}.body
assert(#pc.doc.rebuild() == 0)
local before = pc.doc.measure{body = body}.volume
local key = pc.design.keyway{body = body, shaft = 20, length = 25,
  face_point = {10, 0, 30}, face_normal = {1, 0, 0}, along = {0, 0, 1}}
local size = pc.sketch.generator{sketch = key}
-- A 20 mm shaft takes a 6 x 6 key, 3.5 mm into the shaft.
assert(size.width == 6 and size.depth == 3.5)
pc.design.pocket{sketch = key, depth = size.depth}
assert(#pc.doc.rebuild() == 0, "the keyway cuts")
local m = pc.doc.measure{body = body}
-- The slot's footprint, 142.3 mm², at most 3.5 mm deep, and
-- no less than 3.04 at its sides, where the shaft curves away.
local taken = before - m.volume
assert(taken > 142.27 * 3.03 and taken < 142.27 * 3.5, taken)
assert(math.abs(m.max[3] - 60) < 1e-6, "the shaft keeps its length")

surface

pc.surface.extrude: Extrude curves into a surface.

Notes:

See also pc.sketch.new, pc.surface.check.

Example: Two walls from an open outline.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.polyline{sketch = s, points = {{10, 0}, {0, 0}, {0, 10}}}
local walls = pc.surface.extrude{sketches = {s}, length = 5}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = walls}.body
assert(#pc.doc.faces{body = body} == 2, "a face per line")
local m = pc.doc.measure{body = body}
assert(math.abs(m.area - 100) < 1e-6 and m.volume == nil, "a sheet, open")
assert(math.abs(m.max[3] - 5) < 1e-6)

-- A wall standing on the top edge of the first, in a body of its own.
local top
for _, e in ipairs(pc.doc.edges{body = body}) do
  if math.abs(e.point[3] - 5) < 1e-6 and math.abs(e.point[2]) < 1e-6 then top = e end
end
local on = pc.surface.extrude{direction = "Z", length = 2, curves = {
  {BodyEdge = {body = body, edge = {point = top.point, direction = top.direction}}}}}
assert(#pc.doc.rebuild() == 0)
local other = pc.doc.measure{body = pc.doc.feature{id = on}.body}
assert(math.abs(other.min[3] - 5) < 1e-6 and math.abs(other.max[3] - 7) < 1e-6)

pc.surface.revolve: Revolve curves about an axis into a surface.

Notes:

See also pc.sketch.new, pc.surface.check.

Example: A cylinder's side from a line.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.line{sketch = s, x1 = 5, y1 = 0, x2 = 5, y2 = 10}
local tube = pc.surface.revolve{sketches = {s}}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = tube}.body}
assert(math.abs(m.area - 2 * math.pi * 5 * 10) < 1e-3, m.area)
assert(math.abs(m.min[1] + 5) < 1e-6 and math.abs(m.max[3] - 10) < 1e-6)

pc.surface.planar: Fill closed flat loops with a planar surface.

Notes:

See also pc.sketch.new, pc.surface.sew.

Example: A plate with a hole.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
pc.sketch.circle{sketch = s, x = 10, y = 5, radius = 2}
local plate = pc.surface.planar{sketches = {s}}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = plate}.body
assert(#pc.doc.faces{body = body} == 1)
local area = pc.doc.measure{body = body}.area
assert(math.abs(area - (200 - math.pi * 4)) < 1e-3, area)

pc.surface.fill: Fill the hole curves close with a surface.

Notes:

See also pc.sketch.new, pc.surface.planar.

Example: A disc filling a circle.

local s = pc.sketch.new{plane = "XY", offset = 20}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 5}
local cap = pc.surface.fill{sketches = {s}}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = cap}.body}
assert(math.abs(m.area - math.pi * 25) < 1e-3, m.area)
assert(math.abs(m.min[3] - 20) < 1e-6 and math.abs(m.max[3] - 20) < 1e-6)

pc.surface.ruled: Span two curves with straight lines.

Notes:

See also pc.sketch.new, pc.surface.loft.

Example: A slanted strip between two lines.

local a = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = a, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local b = pc.sketch.new{plane = "XY", offset = 5}
pc.sketch.line{sketch = b, x1 = 0, y1 = 3, x2 = 10, y2 = 3}
local strip = pc.surface.ruled{sketches = {a, b}}
assert(#pc.doc.rebuild() == 0)
local area = pc.doc.measure{body = pc.doc.feature{id = strip}.body}.area
assert(math.abs(area - 10 * math.sqrt(34)) < 1e-3, area)

pc.surface.loft: Loft a surface through sections in order.

Notes:

See also pc.sketch.new, pc.surface.ruled.

Example: A bulge through three circles.

local function ring(z, r)
  local s = pc.sketch.new{plane = "XY", offset = z}
  pc.sketch.circle{sketch = s, x = 0, y = 0, radius = r}
  return s
end
local loft = pc.surface.loft{sketches = {ring(0, 5), ring(10, 8), ring(20, 5)}}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = loft}.body
assert(#pc.doc.faces{body = body} == 1)
local m = pc.doc.measure{body = body}
assert(math.abs(m.max[1] - 8) < 1e-3 and math.abs(m.max[3] - 20) < 1e-6)

-- Two lines, bowed between them by two arched guides.
local function edge(z)
  local s = pc.sketch.new{body = body, plane = "XY", offset = z}
  pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
  return s
end
local function guide(x)
  -- Through (0, 0), (3, 5) and (0, 10) on YZ: y, then z.
  local s = pc.sketch.new{body = body, plane = "YZ", offset = x}
  local r, a = 17 / 3, math.deg(math.atan(5, 8 / 3))
  pc.sketch.arc{sketch = s, x = 3 - r, y = 5, radius = r, start = -a, ["end"] = a}
  return {Sketch = s}
end
local bowed = pc.surface.loft{body = body, sketches = {edge(0), edge(10)},
  guides = {guide(0), guide(10)}}
assert(#pc.doc.rebuild() == 0)
local faces = pc.doc.faces{body = body}
assert(#faces == 2, "the bulge and the bowed sheet")
assert(math.abs(pc.doc.measure{body = body}.max[2] - 8) < 1e-3)

pc.surface.sweep: Sweep a profile along a path into a surface.

Notes:

See also pc.sketch.new, pc.surface.loft.

Example: A tube along a line.

local profile = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = profile, x = 0, y = 0, radius = 2}
local path = pc.sketch.new{plane = "XZ"}
pc.sketch.line{sketch = path, x1 = 0, y1 = 0, x2 = 0, y2 = 20}
local tube = pc.surface.sweep{sketches = {profile, path}}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = tube}.body}
assert(math.abs(m.area - 2 * math.pi * 2 * 20) < 1e-3, m.area)
assert(math.abs(m.max[3] - 20) < 1e-6)

-- An arch between two rails that spread from 10 apart to 14.
local arch = pc.sketch.new{plane = "XZ"}
pc.sketch.arc{sketch = arch, x = 5, y = 0, radius = 5, start = 0, ["end"] = 180}
local body = pc.doc.feature{id = arch}.body
local left = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.line{sketch = left, x1 = 10, y1 = 0, x2 = 14, y2 = 20}
local right = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.line{sketch = right, x1 = 0, y1 = 0, x2 = 0, y2 = 20}
pc.surface.sweep{body = body, sketches = {arch, left},
  second_rail = {{Sketch = right}}}
assert(#pc.doc.rebuild() == 0)
m = pc.doc.measure{body = body}
assert(math.abs(m.max[1] - 14) < 1e-2 and math.abs(m.max[3] - 7) < 2e-2,
  "wider and taller at the far end")

pc.surface.offset: Copy faces at a distance along their normals.

Notes:

See also pc.doc.faces, pc.surface.thicken.

Example: A sheet copied 3 mm up.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
assert(#pc.doc.rebuild() == 0)
local face = pc.doc.faces{body = body}[1]
pc.surface.offset{body = body, faces = {face}, distance = 3}
assert(#pc.doc.rebuild() == 0)
assert(#pc.doc.faces{body = body} == 2, "the sheet and its copy")
assert(math.abs(pc.doc.measure{body = body}.max[3] - 3) < 1e-6)

pc.surface.extend: Extend faces past picked edges.

Notes:

See also pc.doc.edges.

Example: A sheet grown 5 mm past one side.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
assert(#pc.doc.rebuild() == 0)
local side
for _, e in ipairs(pc.doc.edges{body = body}) do
  if math.abs(e.point[1] - 10) < 1e-6 then side = e end
end
pc.surface.extend{body = body, length = 5,
  edges = {{point = side.point, direction = side.direction}}}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.area - 150) < 1e-6 and math.abs(m.max[1] - 15) < 1e-6)
assert(#pc.doc.faces{body = body} == 1, "still one face")

pc.surface.blend: Bridge two edges with a surface.

Notes:

See also pc.doc.edges, pc.surface.fill.

Example: A bridge between two strips.

local a = pc.sketch.new{plane = "XY", offset = 0}
pc.sketch.line{sketch = a, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local low = pc.surface.extrude{sketches = {a}, length = 5, direction = "Y"}
local body = pc.doc.feature{id = low}.body
local b = pc.sketch.new{body = body, plane = "XY", offset = 10}
pc.sketch.line{sketch = b, x1 = 0, y1 = 10, x2 = 10, y2 = 10}
pc.surface.extrude{body = body, sketches = {b}, length = 5, direction = "Y"}
assert(#pc.doc.rebuild() == 0)
local first, second
for _, e in ipairs(pc.doc.edges{body = body}) do
  if math.abs(e.point[2] - 5) < 1e-6 and math.abs(e.point[3]) < 1e-6 then first = e end
  if math.abs(e.point[2] - 10) < 1e-6 and math.abs(e.point[3] - 10) < 1e-6 then second = e end
end
pc.surface.blend{body = body,
  first = {point = first.point, direction = first.direction},
  second = {point = second.point, direction = second.direction}}
assert(#pc.doc.rebuild() == 0)
assert(#pc.doc.faces{body = body} == 3, "two strips and the bridge")
assert(pc.doc.measure{body = body}.area > 200)

pc.surface.split: Split faces along curves.

Notes:

See also pc.doc.faces, pc.surface.trim.

Example: A sheet cut in two along a line.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
assert(#pc.doc.rebuild() == 0)
local face = pc.doc.faces{body = body}[1]
local cut = pc.sketch.new{body = body, plane = "XY", offset = 5}
pc.sketch.line{sketch = cut, x1 = 4, y1 = -1, x2 = 4, y2 = 11}
pc.surface.split{body = body, faces = {face}, sketches = {cut}}
assert(#pc.doc.rebuild() == 0)
local areas = {}
for _, f in ipairs(pc.doc.faces{body = body}) do areas[#areas + 1] = f.area end
table.sort(areas)
assert(#areas == 2 and math.abs(areas[1] - 40) < 1e-3 and math.abs(areas[2] - 60) < 1e-3)

pc.surface.sew: Sew the body's surfaces together.

Notes:

See also pc.surface.check, pc.surface.fillet, pc.surface.planar.

Example: Two walls joined at their corner.

local a = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = a, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local wall = pc.surface.extrude{sketches = {a}, length = 5}
local body = pc.doc.feature{id = wall}.body
local b = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.line{sketch = b, x1 = 0, y1 = 10, x2 = 0, y2 = 0}
pc.surface.extrude{body = body, sketches = {b}, length = 5}
assert(#pc.doc.rebuild() == 0)
assert(#pc.surface.check{body = body} == 0, "touching, not joined")
pc.surface.sew{body = body}
assert(#pc.doc.rebuild() == 0)
assert(#pc.surface.check{body = body} == 1, "one shared edge")

pc.surface.fillet: Round edges where two faces of a surface meet.

Notes:

See also pc.surface.sew, pc.doc.edges.

Example: Two walls rounded at their corner.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.polyline{sketch = s, points = {{10, 0}, {0, 0}, {0, 10}}}
local walls = pc.surface.extrude{sketches = {s}, length = 5}
local body = pc.doc.feature{id = walls}.body
assert(#pc.doc.rebuild() == 0)
local corner
for _, e in ipairs(pc.doc.edges{body = body}) do
  if #e.faces == 2 then corner = e end
end
pc.surface.fillet{body = body, radius = 2,
  edges = {{point = corner.point, direction = corner.direction}}}
assert(#pc.doc.rebuild() == 0)
assert(#pc.doc.faces{body = body} == 3, "two walls and the round")
local area = pc.doc.measure{body = body}.area
assert(math.abs(area - (100 - 4 * 5 + math.pi * 5)) < 1e-3, area)

pc.surface.fillet_faces: Round between two faces that share no edge.

Notes:

See also pc.surface.fillet, pc.doc.faces.

Example: Two walls of an L that stop short of the corner, rounded together.

local a = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = a, x1 = 2, y1 = 0, x2 = 10, y2 = 0}
local body = pc.doc.feature{id = pc.surface.extrude{sketches = {a}, length = 5}}.body
local b = pc.sketch.new{body = body, plane = "XY"}
pc.sketch.line{sketch = b, x1 = 0, y1 = 10, x2 = 0, y2 = 2}
pc.surface.extrude{body = body, sketches = {b}, length = 5}
assert(#pc.doc.rebuild() == 0)
local first, second
for _, f in ipairs(pc.doc.faces{body = body}) do
  if math.abs(f.point[2]) < 1e-6 then first = f else second = f end
end
pc.surface.fillet_faces{body = body, first = first, second = second, radius = 3,
  flip_first = true, flip_second = true}
assert(#pc.doc.rebuild() == 0)
assert(#pc.doc.faces{body = body} == 3, "two walls and the round")
assert(#pc.surface.check{body = body} == 2, "one sheet")
local area = pc.doc.measure{body = body}.area
assert(math.abs(area - (2 * 7 * 5 + math.pi * 3 / 2 * 5)) < 1e-2, area)

pc.surface.thicken: Thicken the body's surfaces into solids.

Notes:

See also pc.surface.sew, pc.surface.offset.

Example: A sheet given 2 mm.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
pc.surface.thicken{body = body, thickness = 2}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 200) < 1e-6, m.volume)
assert(#pc.doc.faces{body = body} == 6, "a box")

pc.surface.trim: Keep what of the body lies on one side of a plane.

Notes:

See also pc.surface.split, pc.surface.mirror.

Example: A sheet cut at x = 4, either side kept.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
local trim = pc.surface.trim{body = body, plane = "YZ", offset = 4}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.area - 60) < 1e-6 and math.abs(m.min[1] - 4) < 1e-6)
pc.surface.set{feature = trim, flip = true}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.area - 40) < 1e-6)

pc.surface.mirror: Add the body's reflection in a plane.

Notes:

See also pc.surface.trim.

Example: A sheet and its reflection.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.surface.planar{sketches = {s}}}.body
pc.surface.mirror{body = body, plane = "YZ"}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.area - 200) < 1e-6 and math.abs(m.min[1] + 10) < 1e-6)
assert(#pc.doc.faces{body = body} == 2)

pc.surface.fit_scan: Fit a plane or cylinder to a region of a scan.

Notes:

See also pc.sketch.new, pc.surface.fit_scan_spline, pc.inspect.grow, pc.surface.sew.

Example: A scanned box's top and side fitted as planes that cross past the edge.

local box = pc.doc.new_body{}
pc.design.primitive{body = box, kind = {Box = {length = 20, width = 10, height = 6}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {box}}
pc.doc.set_visible{id = box, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local top = pc.surface.fit_scan{scan = scan, at = {10, 5, 6}}
local body = pc.doc.feature{id = top}.body
pc.surface.fit_scan{scan = scan, at = {20, 5, 3}, body = body, extend = 0.5}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
-- The top reaches past x = 20, the side above z = 6.
assert(m.max[1] > 22 and m.max[3] > 7, m.max[1])

pc.surface.trim_scan: Keep the pieces of the surfaces that lie on a scan.

Notes:

See also pc.surface.fit_scan, pc.surface.sew.

Example: A scanned box's six sides fitted, trimmed by the scan into the box again.

local box = pc.doc.new_body{}
pc.design.primitive{body = box, kind = {Box = {length = 20, width = 10, height = 6}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {box}}
pc.doc.set_visible{id = box, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local body
for _, at in ipairs({{10, 5, 6}, {10, 5, 0}, {0, 5, 3}, {20, 5, 3}, {10, 0, 3}, {10, 10, 3}}) do
  local f = pc.surface.fit_scan{scan = scan, at = at, body = body}
  body = pc.doc.feature{id = f}.body
end
pc.surface.trim_scan{body = body, scan = scan}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = body}
assert(math.abs(m.volume - 1200) < 0.01, m.volume)

pc.surface.fit_scan_spline: Fit a B-spline surface to a region of a scan of any shape.

Notes:

See also pc.sketch.new, pc.surface.fit_scan, pc.surface.trim_scan.

Example: A wavy sheet, scanned, fitted as one free-form surface.

local stl = {"solid wave\n"}
local function write(text) stl[#stl + 1] = text end
local n = 30
local function at(i, j)
  local x, y = 20 * i / n, 20 * j / n
  return {x, y, 2 * math.sin(x / 4)}
end
local function facet(p, q, s)
  write("facet normal 0 0 0\nouter loop\n")
  for _, v in ipairs({p, q, s}) do
    write(string.format("vertex %.6f %.6f %.6f\n", v[1], v[2], v[3]))
  end
  write("endloop\nendfacet\n")
end
for i = 0, n - 1 do
  for j = 0, n - 1 do
    facet(at(i, j), at(i + 1, j), at(i + 1, j + 1))
    facet(at(i, j), at(i + 1, j + 1), at(i, j + 1))
  end
end
write("endsolid wave\n")
local path = pc.file.temp_path{name = "wave.stl", text = table.concat(stl)}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local sheet = pc.surface.fit_scan_spline{scan = scan, at = {10, 10, 2 * math.sin(2.5)}}
assert(#pc.doc.rebuild() == 0)
local m = pc.doc.measure{body = pc.doc.feature{id = sheet}.body}
assert(math.abs(m.max[3] - 2) < 0.1 and math.abs(m.max[1] - 20) < 0.1, m.max[3])

pc.surface.fit_network: Fit a network of tangent patches to a scan.

Notes:

See also pc.sketch.new, pc.surface.fit_scan_spline, pc.surface.check.

Example: A wavy scan fitted as three patches meeting tangent at a T-junction.

local stl = {"solid wave\n"}
local function write(text) stl[#stl + 1] = text end
local n = 30
local function z(x) return 2 * math.sin(x / 4) end
local function at(i, j)
  local x, y = 20 * i / n, 20 * j / n
  return {x, y, z(x)}
end
local function facet(p, q, s)
  write("facet normal 0 0 0\nouter loop\n")
  for _, v in ipairs({p, q, s}) do
    write(string.format("vertex %.6f %.6f %.6f\n", v[1], v[2], v[3]))
  end
  write("endloop\nendfacet\n")
end
for i = 0, n - 1 do
  for j = 0, n - 1 do
    facet(at(i, j), at(i + 1, j), at(i + 1, j + 1))
    facet(at(i, j), at(i + 1, j + 1), at(i, j + 1))
  end
end
write("endsolid wave\n")
local path = pc.file.temp_path{name = "wave.stl", text = table.concat(stl)}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local function line(x1, y1, x2, y2)
  local pts = {}
  for k = 0, 20 do
    local x, y = x1 + (x2 - x1) * k / 20, y1 + (y2 - y1) * k / 20
    pts[#pts + 1] = {x, y, z(x)}
  end
  return pts
end
local sheet = pc.surface.fit_network{scan = scan,
  polylines = {line(0, 0, 10, 0), line(10, 0, 20, 0), line(20, 0, 20, 8),
    line(20, 20, 10, 20), line(10, 20, 0, 20), line(0, 20, 0, 0),
    line(10, 0, 10, 8), line(20, 8, 20, 20), line(10, 8, 10, 20),
    line(10, 8, 20, 8)},
  patches = {{2, 3, -10, -7}, {10, 8, 4, -9}},
  chained = {{{1}, {7, 9}, {5}, {6}}}, corrections = 2}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = sheet}.body
local joins = pc.surface.check{body = body}
assert(#joins == 3)
for _, join in ipairs(joins) do
  assert(join.gap < 0.00001 and join.angle_deg < 0.01, "tangent at the junction")
end
local m = pc.doc.measure{body = body}
assert(math.abs(m.max[3] - 2) < 0.05 and math.abs(m.max[1] - 20) < 0.01, m.max[1] .. " " .. m.max[3])

pc.surface.check: Measure how a body's faces meet at each shared edge.

Notes:

See also pc.surface.sew, pc.surface.fillet.

Example: A sharp corner, then rounded.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.polyline{sketch = s, points = {{10, 0}, {0, 0}, {0, 10}}}
local walls = pc.surface.extrude{sketches = {s}, length = 5}
local body = pc.doc.feature{id = walls}.body
assert(#pc.doc.rebuild() == 0)
local joins = pc.surface.check{body = body}
assert(#joins == 1 and math.abs(joins[1].angle_deg - 90) < 1e-6, "one square crease")
assert(joins[1].gap < 1e-9)
pc.surface.fillet{body = body, radius = 2,
  edges = {{point = joins[1].point, direction = {0, 0, 1}}}}
assert(#pc.doc.rebuild() == 0)
joins = pc.surface.check{body = body}
assert(#joins == 2, "the round meets each wall")
for _, j in ipairs(joins) do
  assert(j.angle_deg < 0.01 and j.join == "G1", "tangent, the curvature jumps")
  assert(math.abs(j.curvature - 0.5) < 1e-3, "from flat to a 2 mm round")
end

pc.surface.curvature: Paint a body with how sharply its surfaces bend.

Notes:

See also pc.surface.zebra, pc.surface.check.

Example: A tube's side bends one way only.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.line{sketch = s, x1 = 5, y1 = 0, x2 = 5, y2 = 10}
local tube = pc.surface.revolve{sketches = {s}}
assert(#pc.doc.rebuild() == 0)
local body = pc.doc.feature{id = tube}.body
local k = pc.surface.curvature{body = body}
assert(math.abs(k.low) < 1e-9 and math.abs(k.high) < 1e-9, "unrolls flat")
k = pc.surface.curvature{body = body, measure = "mean"}
assert(math.abs(math.abs(k.low) - 0.1) < 1e-6 and math.abs(k.high - k.low) < 1e-6,
  "half of 1/5 everywhere")

pc.surface.zebra: Paint a body with zebra stripes.

Notes:

See also pc.surface.curvature, pc.surface.check.

Example: Stripes on a tube.

local s = pc.sketch.new{plane = "XZ"}
pc.sketch.line{sketch = s, x1 = 5, y1 = 0, x2 = 5, y2 = 10}
local body = pc.doc.feature{id = pc.surface.revolve{sketches = {s}}}.body
assert(#pc.doc.rebuild() == 0)
assert(pc.surface.zebra{body = body, stripes = 8} == nil)
local ok = pcall(pc.surface.zebra, {body = body, axis = "W"})
assert(not ok, "X, Y or Z")

pc.surface.set: Change fields of a surface step.

Notes:

Example: A wall made taller.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.line{sketch = s, x1 = 0, y1 = 0, x2 = 10, y2 = 0}
local wall = pc.surface.extrude{sketches = {s}, length = 5}
local body = pc.doc.feature{id = wall}.body
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.area - 50) < 1e-6)
pc.surface.set{feature = wall, length = 8}
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = body}.area - 80) < 1e-6)

asm

pc.asm.mate: Put two flat faces against each other.

Notes:

See also pc.asm.set, pc.asm.distance, pc.asm.flip.

Example: A lid set on a base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local at = pc.asm.placement{body = lid}.translation
assert(at[1] == 0 and at[2] == 0 and math.abs(at[3] - 5) < 1e-4,
  "lifted onto the top, not moved across")
assert(pc.asm.freedom{body = lid}[1].free == 3,
  "it may still slide and turn on the face")

pc.asm.align: Put two round faces on one axis.

Notes:

See also pc.asm.set, pc.asm.hinge, pc.asm.slider.

Example: A wheel on a shaft, held 8 mm up.

local function pin(x, r, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.circle{sketch = s, x = x, y = 0, radius = r}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function round(body)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.axis then return f end
  end
end
local shaft = pin(0, 5, 20)
local wheel = pin(40, 15, 4)
assert(#pc.doc.rebuild() == 0)
pc.asm.align{body = wheel, face = round(wheel),
  other = shaft, other_face = round(shaft), slide_drive = 8}
local at = pc.asm.placement{body = wheel}.translation
assert(math.abs(at[1] + 40) < 1e-3 and math.abs(at[3] - 8) < 1e-3,
  "on the shaft's axis, 8 mm up")
assert(pc.asm.freedom{body = wheel}[1].free == 1,
  "the slide is held, the turn is free")

pc.asm.angle: Hold two faces or axes at an angle.

Notes:

See also pc.asm.set, pc.asm.parallel, pc.asm.perpendicular.

Example: A plate held at 30 degrees to a base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local plate = box(40, 10, 10, 2)
assert(#pc.doc.rebuild() == 0)
pc.asm.angle{body = plate, face = facing(plate, 1),
  other = base, other_face = facing(base, 1), degrees = 30}
local w = pc.asm.placement{body = plate}.rotation[4]
assert(math.abs(math.deg(2 * math.acos(w)) - 30) < 1e-3, "turned 30 degrees")
assert(pc.asm.freedom{body = plate}[1].free == 5, "only the angle is held")

pc.asm.hinge: Put two axes on one line, the body free only to turn about it.

Notes:

See also pc.asm.set, pc.asm.travel, pc.asm.turn, pc.asm.couple, pc.asm.motion.

Example: An arm on a post, turned a quarter turn.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = 20, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local axis = {axis = {point = {0, 22, 0}, direction = {0, 0, 1}}}
local post_axis = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = axis,
  other = post, other_face = post_axis}
assert(pc.asm.freedom{body = arm}[1].free == 1, "it turns about the post")
pc.asm.set{joint = h, drive = 90}
assert(math.abs(pc.asm.travel{joint = h} - 90) < 1e-3)
local q = pc.asm.placement{body = arm}.rotation
assert(math.abs(q[3] - math.sin(math.rad(45))) < 1e-4, "a quarter turn about +Z")

pc.asm.slider: Put two axes on one line without turning, the body free only to slide along it.

Notes:

See also pc.asm.set, pc.asm.travel, pc.asm.couple, pc.asm.align.

Example: A carriage on a rail, 30 mm along.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local rail = box(0, 100, 10, 5)
local carriage = box(0, 20, 10, 5)
assert(#pc.doc.rebuild() == 0)
local below = {axis = {point = {0, 5, 0}, direction = {1, 0, 0}}}
local along = {axis = {point = {0, 5, 5}, direction = {1, 0, 0}}}
local s = pc.asm.slider{body = carriage, face = below,
  other = rail, other_face = along, limits = {0, 80}}
pc.asm.set{joint = s, drive = 30}
local at = pc.asm.placement{body = carriage}.translation
assert(math.abs(at[1] - 30) < 1e-3 and math.abs(at[3] - 5) < 1e-3,
  "on the rail, 30 mm along")
assert(math.abs(pc.asm.travel{joint = s} - 30) < 1e-3)

pc.asm.fix: Hold a body to another where it sits.

Notes:

See also pc.asm.set, pc.asm.group, pc.asm.ground.

Example: A tag that follows its base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 20, 20, 5)
local tag = box(30, 5, 5, 5)
assert(#pc.doc.rebuild() == 0)
pc.asm.fix{body = tag, other = base}
assert(pc.asm.freedom{body = tag}[1].free == 0)
pc.asm.move{body = base, by = {0, 0, 10}}
pc.asm.solve{}
local at = pc.asm.placement{body = tag}.translation
assert(math.abs(at[3] - 10) < 1e-4, "the tag follows the base")

pc.asm.parallel: Keep two faces or axes parallel.

Notes:

See also pc.asm.set, pc.asm.angle, pc.asm.perpendicular, pc.asm.mate.

Example: A tilted plate turned back square.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 20, 20, 5)
local plate = box(40, 10, 10, 2)
assert(#pc.doc.rebuild() == 0)
pc.asm.move{body = plate, turn = 20, axis = {0, 1, 0}}
local top = pc.doc.faces{body = plate}[6]
local base_top = pc.doc.faces{body = base}[6]
pc.asm.parallel{body = plate, face = top, other = base, other_face = base_top}
local w = pc.asm.placement{body = plate}.rotation[4]
assert(math.abs(w - 1) < 1e-6, "turned back square")
assert(pc.asm.freedom{body = plate}[1].free == 4,
  "it still slides every way and turns about Z")

pc.asm.perpendicular: Keep two faces or axes square to each other.

Notes:

See also pc.asm.set, pc.asm.parallel, pc.asm.angle.

Example: A fin stood square to a base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 20, 20, 5)
local fin = box(40, 10, 10, 2)
assert(#pc.doc.rebuild() == 0)
pc.asm.move{body = fin, turn = 60, axis = {0, 1, 0}}
pc.asm.perpendicular{body = fin, face = pc.doc.faces{body = fin}[6],
  other = base, other_face = pc.doc.faces{body = base}[6]}
local n = pc.doc.faces{body = fin}[6].normal
assert(math.abs(n[3]) < 1e-4, "the fin's face stands square to the base's top")
assert(pc.asm.freedom{body = fin}[1].free == 5)

pc.asm.distance: Keep two faces, axes or points a distance apart: along a face, from an axis, between axes or points.

Notes:

See also pc.asm.set, pc.asm.mate.

Example: A plate held 10 mm above a base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local plate = box(40, 10, 10, 2)
assert(#pc.doc.rebuild() == 0)
pc.asm.distance{body = plate, face = facing(plate, -1),
  other = base, other_face = facing(base, 1), offset = 10}
local at = pc.asm.placement{body = plate}.translation
assert(math.abs(at[3] - 15) < 1e-4, "10 mm above the base's top")

pc.asm.tangent: Rest a round face on a flat one.

Notes:

See also pc.asm.set, pc.asm.mate, pc.asm.cam.

Example: A roller against a block's side.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 40, height = 40}
local base = pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
local r = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = r, x = 80, y = 0, radius = 3}
local roller = pc.doc.feature{id = pc.design.pad{sketch = r, length = 10}}.body
assert(#pc.doc.rebuild() == 0)
local side, round
for _, f in ipairs(pc.doc.faces{body = base}) do
  if f.normal and f.normal[1] > 0.99 then side = f end
end
for _, f in ipairs(pc.doc.faces{body = roller}) do
  if f.axis then round = f end
end
pc.asm.tangent{body = roller, face = round, other = base, other_face = side}
local at = pc.asm.placement{body = roller}.translation
assert(math.abs(80 + at[1] - 43) < 1e-3, "its axis 3 mm out from x = 40")

pc.asm.ball: Put two points together, the body free to turn every way about them.

Notes:

See also pc.asm.set, pc.asm.universal, pc.asm.distance.

Example: An arm's corner on a base's corner.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 40, 40, 5)
local arm = box(60, 30, 4, 4)
assert(#pc.doc.rebuild() == 0)
pc.asm.ball{body = arm, face = {point = {60, 0, 4}},
  other = base, other_face = {point = {40, 40, 5}}}
local at = pc.asm.placement{body = arm}.translation
assert(math.abs(at[1] + 20) < 1e-4 and math.abs(at[2] - 40) < 1e-4
  and math.abs(at[3] - 1) < 1e-4, "the arm's corner on the base's corner")
assert(pc.asm.freedom{body = arm}[1].free == 3, "it turns every way")

pc.asm.universal: Cross two yokes' pins at one point, square to each other: the body turns about either.

Notes:

See also pc.asm.set, pc.asm.ball, pc.asm.hinge.

Example: Two pins crossed at one point.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 40, 40, 5)
local arm = box(60, 30, 4, 4)
assert(#pc.doc.rebuild() == 0)
local along_x = {axis = {point = {60, 2, 2}, direction = {1, 0, 0}}}
local up_z = {axis = {point = {20, 20, 10}, direction = {0, 0, 1}}}
pc.asm.universal{body = arm, face = along_x, other = base, other_face = up_z}
local free = pc.asm.freedom{body = arm}[1]
assert(free.free == 2 and free.motions[1].turn and free.motions[2].turn)
local at = pc.asm.placement{body = arm}.translation
assert(math.abs(at[1] + 40) < 1e-3 and math.abs(at[3] - 8) < 1e-3,
  "the two pins cross at (20, 20, 10)")

pc.asm.slot: Keep a point on a line, as a pin slides in a slot.

Notes:

See also pc.asm.set, pc.asm.path, pc.asm.slider.

Example: A pin kept on a line.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 40, 40, 5)
local arm = box(60, 30, 4, 4)
assert(#pc.doc.rebuild() == 0)
local edge = {axis = {point = {0, 40, 5}, direction = {1, 0, 0}}}
local pin = {point = {60, 0, 0}}
pc.asm.slot{body = arm, face = pin, other = base, other_face = edge}
local at = pc.asm.placement{body = arm}.translation
assert(math.abs(at[2] - 40) < 1e-4 and math.abs(at[3] - 5) < 1e-4,
  "the pin on the base's back top edge")
local free = pc.asm.freedom{body = arm}[1]
assert(free.free == 4 and free.motions[4].slide[1] == 1,
  "three turns and a slide along X")

pc.asm.path: Keep a point on an edge of any shape: it runs along it.

Notes:

See also pc.asm.set, pc.asm.slot, pc.asm.cam.

Example: A corner run along a disc's rim.

local d = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = d, x = 0, y = 0, radius = 20}
local disc = pc.doc.feature{id = pc.design.pad{sketch = d, length = 5}}.body
local r = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = r, x = 60, y = 0, width = 4, height = 4}
local rider = pc.doc.feature{id = pc.design.pad{sketch = r, length = 4}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.path{body = rider, face = {point = {60, 0, 0}},
  other = disc, other_face = {point = {0, 20, 5}}}
local at = pc.asm.placement{body = rider}.translation
local x, y, z = 60 + at[1], at[2], at[3]
assert(math.abs(math.sqrt(x * x + y * y) - 20) < 0.01 and math.abs(z - 5) < 1e-3,
  "the rider's corner on the disc's top rim")

pc.asm.cam: Keep a follower on a cam's face, a roller's radius off it.

Notes:

See also pc.asm.set, pc.asm.path, pc.asm.tangent.

Example: A follower 2 mm off a round cam.

local d = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = d, x = 0, y = 0, radius = 20}
local cam = pc.doc.feature{id = pc.design.pad{sketch = d, length = 5}}.body
local r = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = r, x = 60, y = 0, width = 4, height = 4}
local follower = pc.doc.feature{id = pc.design.pad{sketch = r, length = 4}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.cam{body = follower, face = {point = {60, 0, 0}},
  other = cam, other_face = {point = {20, 0, 2}}, radius = 2}
local p = pc.asm.placement{body = follower}
local q, t = p.rotation, p.translation
-- Where the follower's point (60, 0, 0) is now: turned by q, then moved by t.
local x = 60 * (1 - 2 * (q[2] ^ 2 + q[3] ^ 2)) + t[1]
local y = 60 * 2 * (q[1] * q[2] + q[3] * q[4]) + t[2]
assert(math.abs(math.sqrt(x * x + y * y) - 22) < 0.1,
  "2 mm off the cam's 20 mm face")

pc.asm.width: Centre a tab's two faces between a slot's two walls.

Notes:

See also pc.asm.set, pc.asm.mate, pc.asm.distance.

Example: A tab centred between two walls.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 5, height = 20}
pc.sketch.rect{sketch = s, x = 15, y = 0, width = 5, height = 20}
local walls = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local t = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = t, x = 40, y = 0, width = 6, height = 10}
local tab = pc.doc.feature{id = pc.design.pad{sketch = t, length = 10}}.body
assert(#pc.doc.rebuild() == 0)
local function side(body, sign, x)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    local n = f.normal
    if n and n[1] * sign > 0.99 and math.abs(f.point[1] - x) < 1e-3 then
      return f
    end
  end
end
pc.asm.width{body = tab, face = side(tab, -1, 40), face2 = side(tab, 1, 46),
  other = walls, other_face = side(walls, 1, 5), other_face2 = side(walls, -1, 15)}
local at = pc.asm.placement{body = tab}.translation
assert(math.abs(at[1] + 33) < 1e-3, "the 6 mm tab centred in the 10 mm gap")

pc.asm.couple: Tie two joints' motions together: gears or a belt between two hinges, a rack and pinion or a screw between a hinge and a slider.

Notes:

See also pc.asm.hinge, pc.asm.slider, pc.asm.set.

Example: Two gears, the second half as fast the other way.

local function disc(x, r)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.circle{sketch = s, x = x, y = 30, radius = r}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 3}}.body
end
local f = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = f, x = -50, y = 0, width = 100, height = 10}
local frame = pc.doc.feature{id = pc.design.pad{sketch = f, length = 2}}.body
local small, big = disc(0, 10), disc(30, 20)
assert(#pc.doc.rebuild() == 0)
local function at(x)
  return {axis = {point = {x, 30, 0}, direction = {0, 0, 1}}}
end
local h1 = pc.asm.hinge{body = small, face = at(0), other = frame, other_face = at(0)}
local h2 = pc.asm.hinge{body = big, face = at(30), other = frame, other_face = at(30)}
pc.asm.couple{driver = h1, driven = h2, ratio = 0.5}
pc.asm.set{joint = h1, drive = 40}
assert(math.abs(pc.asm.travel{joint = h2} + 20) < 1e-3,
  "gears: half as far, the other way")

pc.asm.set: Change a joint's gap, side, angle or radius, or a coupling's joints and ratio.

Notes:

See also pc.asm.couple, pc.asm.turn.

Example: A mate's gap changed, then the mate made a distance.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
local j = pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local function height() return pc.asm.placement{body = lid}.translation[3] end
pc.asm.set{joint = j, offset = 2}
assert(math.abs(height() - 7) < 1e-4, "a 2 mm gap")
pc.asm.set{joint = j, kind = "distance", offset = 4}
assert(pc.doc.feature{id = j}.kind == "Distance")
assert(math.abs(height() - 9) < 1e-4, "4 mm apart")

pc.asm.copy: Insert linked copies of a body: each takes its shape and follows it, placed on its own.

Notes:

See also pc.asm.mirror, pc.asm.parts.

Example: Two copies in a row and a ring of three.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local pad = pc.design.pad{sketch = s, length = 5}
local body = pc.doc.feature{id = pad}.body
assert(#pc.doc.rebuild() == 0)
local copies = pc.asm.copy{body = body, count = 2}
assert(#copies == 2)
local second = pc.asm.placement{body = copies[2]}.translation
assert(math.abs(second[1] - 44) < 1e-4, "22 mm apart along X")
pc.doc.set_value{id = pad, parameter = "length", value = 8}
assert(#pc.doc.rebuild() == 0)
local volume = pc.doc.measure{body = copies[1]}.volume
assert(math.abs(volume - 20 * 10 * 8) < 1e-3, "the copy follows")
local z = {point = {0, 0, 0}, direction = {0, 0, 1}}
local ring = pc.asm.copy{body = body, count = 3, around = z}
local w = pc.asm.placement{body = ring[1]}.rotation[4]
assert(math.abs(math.deg(2 * math.acos(w)) - 90) < 1e-3,
  "a whole turn shared by four")

pc.asm.mirror: Insert a linked copy that is a body's mirror image, following every change to it.

Notes:

See also pc.asm.copy.

Example: A block mirrored across X = 0.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 10, y = 0, width = 20, height = 10}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
assert(#pc.doc.rebuild() == 0)
local m = pc.asm.mirror{body = body, point = {0, 0, 0}, normal = {1, 0, 0}}
local faces = pc.doc.faces{body = m}
assert(#faces == 6)
for _, f in ipairs(faces) do
  local x = f.point[1]
  assert(x <= -10 + 1e-4 and x >= -30 - 1e-4, "on the other side of X = 0")
end
assert(#pc.doc.rebuild() == 0)
assert(math.abs(pc.doc.measure{body = m}.volume - 1000) < 1e-6, "its solid, mirrored")

pc.asm.replace: Put another body in a body's place, with its joints found again on the new body's faces.

Notes:

See also pc.asm.copy.

Example: A lid swapped for a thicker one.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
local thicker = box(80, 12, 12, 4)
assert(#pc.doc.rebuild() == 0)
local j = pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local report = pc.asm.replace{body = lid, with = thicker}
assert(#report.kept == 1 and #report.unmatched == 0)
assert(pc.doc.feature{id = j}.body == thicker, "the mate is on the new body")
local at = pc.asm.placement{body = thicker}.translation
assert(math.abs(at[3] - 5) < 1e-4, "on the base's top")
for _, b in ipairs(pc.doc.bodies()) do
  if b.id == lid then assert(not b.visible, "the old lid is hidden") end
end

pc.asm.group: Lock bodies together where they sit, in one rigid group.

Notes:

See also pc.asm.component, pc.asm.fix.

Example: Two blocks locked together.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 5, height = 5}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local a, b = box(0), box(10)
assert(#pc.doc.rebuild() == 0)
pc.asm.group{bodies = {a, b}}
assert(pc.asm.freedom{body = b}[1].free == 0, "b holds to a")
pc.asm.move{body = a, by = {0, 10, 0}}
assert(pc.asm.placement{body = b}.translation[2] == 0, "a move places one body")
pc.asm.solve{}
local at = pc.asm.placement{body = b}.translation
assert(math.abs(at[2] - 10) < 1e-4, "the solve brings b along")

pc.asm.component: Put bodies in a new component: one row in the tree that moves as one, or, flexible, keeps the joints inside it live; components nest.

Notes:

See also pc.asm.component_set, pc.asm.component_add, pc.asm.group.

Example: Two blocks that move as one.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 5, height = 5}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local a, b, c = box(0), box(10), box(20)
assert(#pc.doc.rebuild() == 0)
pc.asm.component{bodies = {a, b}, name = "Pair"}
pc.asm.move{body = a, by = {0, 7, 0}}
assert(pc.asm.placement{body = b}.translation[2] == 7, "b moves with a")
assert(pc.asm.placement{body = c}.translation[2] == 0, "c is not in it")

pc.asm.component_set: Rename a component, move it, or make it rigid or flexible.

Notes:

See also pc.asm.component, pc.asm.component_add.

Example: A component renamed, made flexible and rigid again.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 5, height = 5}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local a, b = box(0), box(10)
assert(#pc.doc.rebuild() == 0)
local k = pc.asm.component{bodies = {a, b}}
pc.asm.component_set{component = k, name = "Loose pair", flexible = true}
pc.asm.move{body = a, by = {0, 7, 0}}
assert(pc.asm.placement{body = b}.translation[2] == 0, "flexible: a moves alone")
pc.asm.component_set{component = k, flexible = false}
pc.asm.move{body = a, by = {0, 1, 0}}
assert(pc.asm.placement{body = b}.translation[2] == 1, "rigid: they move as one")

pc.asm.component_add: Put bodies in a component, or take them out.

Notes:

See also pc.asm.component, pc.asm.component_remove.

Example: A body put in a component and taken out again.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 5, height = 5}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local a, b, c = box(0), box(10), box(20)
assert(#pc.doc.rebuild() == 0)
local k = pc.asm.component{bodies = {a, b}}
pc.asm.component_add{bodies = {c}, component = k}
pc.asm.move{body = a, by = {0, 0, 3}}
assert(pc.asm.placement{body = c}.translation[3] == 3, "c moves with them")
pc.asm.component_add{bodies = {c}}
pc.asm.move{body = a, by = {0, 0, 3}}
assert(pc.asm.placement{body = c}.translation[3] == 3, "taken out, it stays")

pc.asm.component_remove: Take a component apart: its bodies and components go one level up.

Notes:

See also pc.asm.component.

Example: A component taken apart.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 5, height = 5}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
end
local a, b = box(0), box(10)
assert(#pc.doc.rebuild() == 0)
local k = pc.asm.component{bodies = {a, b}}
pc.asm.component_remove{component = k}
pc.asm.move{body = a, by = {0, 0, 3}}
assert(pc.asm.placement{body = b}.translation[3] == 0, "apart, a moves alone")
local renamed = pcall(pc.asm.component_set, {component = k, name = "Gone"})
assert(not renamed, "the component is gone")

pc.asm.motion: Keep a motion over time: hinges and sliders each driven by a formula of t, seconds.

Notes:

See also pc.asm.motion_frames, pc.asm.trace, pc.asm.motion_clashes.

Example: A hinge turned 90 degrees a second, then changed.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z}
local m = pc.asm.motion{drives = {{joint = h, formula = "90 * t"}}, ["end"] = 1}
assert(#pc.asm.motion_frames{study = m} == 21, "0 to 1 s every 0.05 s")
local slower = {{joint = h, formula = "45 * t"}}
pc.asm.motion{study = m, drives = slower, ["end"] = 1, step = 0.5}
assert(#pc.asm.motion_frames{study = m} == 3, "the same motion, changed")
assert(pc.asm.travel{joint = h} == 0, "making it moves nothing")

pc.asm.motion_frames: Every body's placement at each frame of a motion; nothing is moved.

Notes:

See also pc.asm.motion, pc.asm.trace.

Example: Where an arm is at the end of its motion.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z}
local drives = {{joint = h, formula = "90 * t"}}
local m = pc.asm.motion{drives = drives, ["end"] = 1, step = 0.25}
local frames = pc.asm.motion_frames{study = m}
local last = frames[#frames]
assert(#frames == 5 and last.t == 1)
for _, b in ipairs(last.bodies) do
  if b.body == arm then
    local turned = math.deg(2 * math.acos(b.rotation[4]))
    assert(math.abs(turned - 90) < 1e-3, "a quarter turn at 1 s")
  end
end
assert(pc.asm.placement{body = arm}.rotation[4] == 1, "the arm has not moved")

pc.asm.trace: Follow a point of a body through a motion: where it is and how fast at each frame.

Notes:

See also pc.asm.motion_frames, pc.asm.motion.

Example: The tip of a turning arm.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z}
local m = pc.asm.motion{drives = {{joint = h, formula = "90 * t"}}, ["end"] = 1}
local path = pc.asm.trace{study = m, body = arm, point = {28, 0, 0}}
local last = path[#path]
assert(math.abs(last.point[2] - 28) < 1e-3, "the arm's tip ends on +Y")
assert(math.abs(last.speed - 28 * math.pi / 2) < 0.1,
  "a quarter turn a second at 28 mm")

pc.asm.exploded_view: Keep an exploded view: steps, each turning, spreading and shifting some bodies, played in order.

Notes:

See also pc.asm.explode_at.

Example: A lid lifted, then the base moved aside.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
local view = pc.asm.exploded_view{steps = {
  {bodies = {lid}, shift = {0, 0, 20}},
  {bodies = {base}, shift = {-15, 0, 0}},
}}
for _, p in ipairs(pc.asm.explode_at{view = view, at = 2}) do
  if p.body == lid then assert(p.translation[3] == 20) end
  if p.body == base then assert(p.translation[1] == -15) end
end
assert(pc.asm.placement{body = lid}.translation[3] == 0, "nothing has moved")

pc.asm.explode_at: Where an exploded view puts every body, part way through its steps.

Notes:

See also pc.asm.exploded_view.

Example: Half way through the second step.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local lid = pc.doc.feature{id = pc.design.pad{sketch = s, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local view = pc.asm.exploded_view{steps = {
  {bodies = {lid}, shift = {0, 0, 20}},
  {bodies = {lid}, shift = {10, 0, 0}},
}}
local at = pc.asm.explode_at{view = view, at = 1.5}[1].translation
assert(at[1] == 5 and at[3] == 20, "the first step done, half the second")
local past = pc.asm.explode_at{view = view, at = 9}[1].translation
assert(past[1] == 10, "past the last step is the last step")

pc.asm.save_state: Save where every body sits, which are hidden and where drives hold, under a name.

Notes:

See also pc.asm.restore_state.

Example: A state saved again after a change.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z,
  drive = 0}
local closed = pc.asm.save_state{name = "Closed"}
pc.asm.set{joint = h, drive = 90}
pc.asm.save_state{state = closed}
pc.asm.set{joint = h, drive = 10}
pc.asm.restore_state{state = closed}
assert(math.abs(pc.asm.travel{joint = h} - 90) < 1e-3, "saved again at 90")

pc.asm.restore_state: Put the assembly back as a saved state has it.

Notes:

See also pc.asm.save_state.

Example: An opened arm put back, shown again.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z,
  drive = 0}
local closed = pc.asm.save_state{name = "Closed"}
pc.asm.set{joint = h, drive = 90}
pc.doc.set_visible{id = arm, visible = false}
pc.asm.restore_state{state = closed}
assert(math.abs(pc.asm.travel{joint = h}) < 1e-3, "the drive is back at 0")
for _, b in ipairs(pc.doc.bodies()) do
  if b.id == arm then assert(b.visible, "and the arm is shown again") end
end

pc.asm.redundant: The joints that hold nothing a body's other joints do not.

Notes:

See also pc.asm.freedom.

Example: A parallel that a mate makes needless.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local p = pc.asm.parallel{body = lid, face = facing(lid, 1),
  other = base, other_face = facing(base, 1)}
local extra = pc.asm.redundant{}
assert(#extra == 1 and extra[1].joint == p and extra[1].name == "Parallel 1",
  "the mate already keeps them parallel")

pc.asm.motion_clashes: Step a hinge's or a slider's drive through a range and find where bodies collide.

Notes:

See also pc.asm.interference, pc.asm.motion.

Example: An arm swung into a post.

local function box(x, y, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = y, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(-5, -5, 10, 10, 2)
local arm = box(-2, -2, 30, 4, 3)
local post = box(0, 15, 4, 4, 10)
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = base, other_face = z}
local clashes = pc.asm.motion_clashes{joint = h, low = 0, high = 180, steps = 3}
assert(#clashes == 1 and clashes[1].at == 90,
  "the arm hits the post a quarter turn round")
assert(clashes[1].volume > 0)
assert(pc.asm.travel{joint = h} == 0, "the arm is left where it was")

pc.asm.turn: Turn a joint's body about the joint's axis or normal, the joint keeping it there.

Notes:

See also pc.asm.flip, pc.asm.travel.

Example: A mated block turned a quarter turn on its face.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(5, 10, 4, 3)
assert(#pc.doc.rebuild() == 0)
local j = pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
pc.asm.turn{joint = j, degrees = 90}
local q = pc.asm.placement{body = lid}.rotation
assert(math.abs(math.deg(2 * math.acos(q[4])) - 90) < 1e-3, "a quarter turn")
assert(math.abs(q[3]) > 0.7, "about Z")
assert(math.abs(facing(lid, -1).point[3] - 5) < 1e-4, "still on the top")

pc.asm.flip: Turn a joint's body over, half a turn across the joint's axis or normal.

Notes:

See also pc.asm.turn, pc.asm.set.

Example: A wheel turned over on its hinge.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local w = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = w, x = 30, y = 0, radius = 10}
local wheel = pc.doc.feature{id = pc.design.pad{sketch = w, length = 4}}.body
assert(#pc.doc.rebuild() == 0)
local function axis(x)
  return {axis = {point = {x, 0, 0}, direction = {0, 0, 1}}}
end
local h = pc.asm.hinge{body = wheel, face = axis(30),
  other = post, other_face = axis(0), offset = 3}
pc.asm.flip{joint = h}
local q = pc.asm.placement{body = wheel}.rotation
assert(math.abs(q[4]) < 1e-4, "half a turn")
assert(math.abs(q[3]) < 1e-4, "about an axis square to the hinge's")

pc.asm.turn90: Turn a joint's own turn a quarter turn, its body following.

Notes:

See also pc.asm.turn, pc.asm.travel.

Example: A hinge held at 30° whose zero is turned a quarter turn.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local w = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = w, x = 0, y = -2, width = 20, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = w, length = 2}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z,
  drive = 30}
pc.asm.turn90{joint = h}
assert(math.abs(pc.asm.travel{joint = h} - 30) < 1e-3, "still 30° on the hinge")
local q = pc.asm.placement{body = arm}.rotation
assert(math.abs(math.deg(2 * math.acos(q[4])) - 120) < 1e-2,
  "the arm a quarter turn further round")

pc.asm.select_joints: Select every joint that holds a body.

Notes:

See also pc.asm.redundant, pc.asm.unmet.

Example: A lid mated to a grounded base, and a block mated onto the lid.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
local block = box(80, 4, 4, 3)
assert(#pc.doc.rebuild() == 0)
local g = pc.asm.ground{body = base}
local m = pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
pc.asm.mate{body = block, face = facing(block, -1),
  other = lid, other_face = facing(lid, 1)}
local held = pc.asm.select_joints{body = base}
assert(#held == 2 and held[1].joint == g and held[2].joint == m,
  "the ground and the mate onto it")
assert(#pc.asm.select_joints{body = lid} == 2, "the lid's mate and the one onto it")

pc.asm.unmet: The joints and couplings that do not hold where the bodies sit.

Notes:

See also pc.asm.redundant, pc.asm.select_joints.

Example: A mate that holds.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
assert(#pc.asm.unmet{} == 0, "the mate holds")

pc.asm.interference: Where solid bodies share material: each pair that clashes, how much and where.

Notes:

See also pc.asm.motion_clashes, pc.asm.mass.

Example: A lid sunk 1 mm into its base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local base = box(0, 20, 20, 5)
local lid = box(5, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.move{body = lid, by = {0, 0, 5}}
assert(#pc.asm.interference{}.clashes == 0, "resting on the top is no clash")
pc.asm.move{body = lid, by = {0, 0, -1}}
local found = pc.asm.interference{}
assert(found.checked == 2 and #found.clashes == 1)
local clash = found.clashes[1]
assert(math.abs(clash.volume - 10 * 10 * 1) < 1e-3, "1 mm of the lid sunk in")
assert(math.abs(clash.centre[3] - 4.5) < 1e-3)

pc.asm.mass: The mass, centre of mass and inertia of the solid bodies at one density.

Notes:

See also pc.asm.parts, pc.asm.interference.

Example: A block's mass at 1.24 g/cm³.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local block = pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
assert(#pc.doc.rebuild() == 0)
local m = pc.asm.mass{density = 1.24}
assert(math.abs(m.volume - 2000) < 1e-3)
assert(math.abs(m.mass - 2.48) < 1e-6, "2 cm³ at 1.24 g/cm³")
assert(m.centre[1] == 10 and m.centre[3] == 2.5)
-- About its centre, g·mm²: m (20² + 20²) / 12 about Z.
assert(math.abs(m.inertia.tensor[3][3] - 2.48 * 800 / 12) < 1e-6)

pc.asm.parts: Every part, bodies of the same shape counted together.

Notes:

See also pc.asm.part, pc.asm.parts_table, pc.asm.copy.

Example: A plate and its copies counted as one part.

local function box(x)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = 10, height = 10}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = 2}}.body
end
local plate = box(0)
local other = box(20)
assert(#pc.doc.rebuild() == 0)
pc.asm.copy{body = plate, count = 2}
local parts = pc.asm.parts{}
assert(#parts == 2, "alike bodies modelled apart are two parts")
local counts = {}
for _, p in ipairs(parts) do counts[p.quantity] = p end
assert(counts[3] and counts[3].size[3] == 2,
  "the plate and its two copies: one part, three of it")

pc.asm.part: Set what the parts list keeps for a part: its number, whether it is bought, its values in the added columns.

Notes:

See also pc.asm.parts, pc.asm.parts_table.

Example: A bought screw numbered on one of its copies.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local screw = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
assert(#pc.doc.rebuild() == 0)
local copies = pc.asm.copy{body = screw, count = 3}
pc.asm.part{body = copies[2], number = 4, bought = true,
  values = {Supplier = "ACME"}}
local p = pc.asm.parts{}[1]
assert(p.quantity == 4 and p.number == 4 and p.bought,
  "set on one, kept for the part")
assert(p.values.Supplier == "ACME")

pc.asm.print_material: Set the material the parts list weighs printed parts in.

Notes:

See also pc.asm.parts, pc.asm.part.

Example: A plate's filament in PETG, two to print.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 10}
local plate = pc.doc.feature{id = pc.design.pad{sketch = s, length = 5}}.body
assert(#pc.doc.rebuild() == 0)
local m = pc.asm.print_material{name = "petg"}
assert(m.name == "PETG" and math.abs(m.density - 1.27) < 1e-6)
pc.asm.part{body = plate, print = 2}
local p = pc.asm.parts{}[1]
assert(p.print == 2 and math.abs(p.volume - 1000) < 1e-3)
assert(math.abs(p.mass - 1.27) < 1e-4, "1 cm³ at 1.27 g/cm³")

pc.asm.parts_table: Replace what the parts list keeps, whole.

Notes:

See also pc.asm.part, pc.asm.parts.

Example: The parts list written whole.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local screw = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.part{body = screw, number = 9, values = {Note = "old"}}
pc.asm.parts_table{table = {
  columns = {"Supplier"},
  entries = {[screw] = {number = 2, bought = true, values = {Supplier = "ACME"}}},
}}
local p = pc.asm.parts{}[1]
assert(p.number == 2 and p.bought and p.values.Supplier == "ACME")
assert(p.values.Note == nil, "what the table left out is gone")

pc.asm.travel: Where a hinge or a slider has got to: the hinge's angle in degrees, the slider's position in mm.

Notes:

See also pc.asm.hinge, pc.asm.slider, pc.asm.turn.

Example: A hinge's angle after its arm is moved.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.circle{sketch = s, x = 0, y = 0, radius = 3}
local post = pc.doc.feature{id = pc.design.pad{sketch = s, length = 10}}.body
local a = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = a, x = -2, y = -2, width = 30, height = 4}
local arm = pc.doc.feature{id = pc.design.pad{sketch = a, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local z = {axis = {point = {0, 0, 0}, direction = {0, 0, 1}}}
local h = pc.asm.hinge{body = arm, face = z, other = post, other_face = z}
assert(pc.asm.travel{joint = h} == 0, "0 where it was made")
pc.asm.move{body = arm, turn = 45}
assert(math.abs(pc.asm.travel{joint = h} - 45) < 1e-3,
  "read from where the arm sits")

pc.asm.ground: Keep a body where it is: the bodies joined to it are placed against it.

Notes:

See also pc.asm.fix, pc.asm.freedom.

Example: A base kept where it is.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
local g = pc.asm.ground{body = base}
assert(pc.asm.ground{body = base} == g, "grounding twice keeps one ground")
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
assert(pc.asm.placement{body = base}.translation[3] == 0, "the ground stays")
assert(pc.asm.ground{body = base, grounded = false} == nil)

pc.asm.freedom: What each jointed body may still do: the motions its joints leave open.

Notes:

See also pc.asm.redundant, pc.asm.solve.

Example: What a mate leaves a lid.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local all = pc.asm.freedom{}
assert(#all == 1 and all[1].body == lid, "the grounded base is not listed")
local turns, slides = 0, 0
for _, m in ipairs(all[1].motions) do
  if m.turn then turns = turns + 1; assert(m.turn.axis[3] == 1) end
  if m.slide then slides = slides + 1; assert(m.slide[3] == 0) end
end
assert(turns == 1 and slides == 2,
  "on a face: a turn about its normal and two slides along it")

pc.asm.solve: Place every body its joints hold.

Notes:

See also pc.asm.place, pc.asm.move.

Example: A lid put back on its base.

local function box(x, w, h, len)
  local s = pc.sketch.new{plane = "XY"}
  pc.sketch.rect{sketch = s, x = x, y = 0, width = w, height = h}
  return pc.doc.feature{id = pc.design.pad{sketch = s, length = len}}.body
end
local function facing(body, z)
  for _, f in ipairs(pc.doc.faces{body = body}) do
    if f.normal and f.normal[3] * z > 0.99 then return f end
  end
end
local base = box(0, 20, 20, 5)
local lid = box(40, 10, 10, 3)
assert(#pc.doc.rebuild() == 0)
pc.asm.mate{body = lid, face = facing(lid, -1),
  other = base, other_face = facing(base, 1)}
local function height() return pc.asm.placement{body = lid}.translation[3] end
pc.asm.place{body = lid, translation = {0, 0, 30}}
assert(height() == 30, "a placement does not solve")
assert(pc.asm.solve{} == "Moved 1 body; every joint holds")
assert(math.abs(height() - 5) < 1e-4)
assert(pc.asm.solve{} == "Every joint holds")

pc.asm.placement: Where a body sits.

Notes:

See also pc.asm.place, pc.asm.move.

Example: A body's placement before and after a move.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
local p = pc.asm.placement{body = body}
assert(p.translation[1] == 0 and p.rotation[4] == 1, "where it was modelled")
pc.asm.move{body = body, by = {5, 0, 0}, turn = 90}
p = pc.asm.placement{body = body}
assert(p.translation[1] == 5 and math.abs(p.rotation[3] - math.sqrt(0.5)) < 1e-6)

pc.asm.place: Put a body at a placement.

Notes:

See also pc.asm.move, pc.asm.placement, pc.asm.solve.

Example: A body lifted and turned.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.place{body = body, translation = {0, 0, 20}, rotation = {0, 0, 1, 1}}
local p = pc.asm.placement{body = body}
assert(p.translation[3] == 20)
local half = math.sqrt(0.5)
assert(math.abs(p.rotation[3] - half) < 1e-6, "the quaternion is normalised")
pc.asm.place{body = body, translation = {1, 2, 3}}
p = pc.asm.placement{body = body}
assert(math.abs(p.rotation[3] - half) < 1e-6, "the rotation left out is kept")

pc.asm.move: Move a body by a step and a turn.

Notes:

See also pc.asm.place, pc.asm.solve.

Example: A plate turned about its own centre.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 20, height = 20}
local body = pc.doc.feature{id = pc.design.pad{sketch = s, length = 3}}.body
assert(#pc.doc.rebuild() == 0)
pc.asm.move{body = body, turn = 90, about = {10, 10, 0}}
local t = pc.asm.placement{body = body}.translation
assert(math.abs(t[1] - 20) < 1e-4 and math.abs(t[2]) < 1e-4,
  "turned in place about its centre")
pc.asm.move{body = body, by = {0, 0, 5}}
t = pc.asm.placement{body = body}.translation
assert(math.abs(t[3] - 5) < 1e-4, "steps add up")

inspect

pc.inspect.align_datums: Align by datums.

Notes:

pc.inspect.align_points: Align a scan by points picked on it and on a reference.

Notes:

See also pc.inspect.best_fit.

pc.inspect.auto_align: Auto-align scan.

Notes:

pc.inspect.use_symmetry: Use scan symmetry.

Notes:

pc.inspect.section: Cut a scan by a plane, or a stack of planes.

Notes:

pc.inspect.shadow: Outline a scan's shadow clear of it, and stand it up as a block.

Notes:

pc.inspect.pin: Pin a map's reading on the part.

Notes:

pc.inspect.element_map: Map a scan's distance from one of its elements.

Notes:

pc.inspect.compensation: How a print came out per axis, and what scales it back.

Notes:

See also pc.inspect.best_fit.

pc.inspect.export_step: Write the elements as STEP construction geometry.

Notes:

pc.inspect.export_iges: Write the elements as IGES construction geometry.

Notes:

See also pc.inspect.export_step.

Example: A section saved as IGES with its naming warning.

local drum = pc.doc.new_body{}
pc.design.primitive{body = drum, variant = "cylinder",
  kind = {Cylinder = {radius = 5, height = 10, angle_deg = 360}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {drum}}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local cut = pc.inspect.section{scan = scan}
pc.doc.rename{id = cut.section, name = "Section, centre"}
local out = pc.file.temp_path{name = "part.igs"}
local saved = pc.inspect.export_iges{path = out, scan = scan}
assert(saved.path == out and saved.items == 1)
assert(#saved.warnings == 1)
assert(saved.warnings[1]:find("Section, centre", 1, true))

pc.inspect.tolerance: Keep a geometric tolerance on an element.

Notes:

Example: Datum position, profiles, runout and a median plane.

local model = pc.doc.new_body{}
pc.design.primitive{body = model, variant = "cylinder",
  kind = {Cylinder = {radius = 5, height = 10, angle_deg = 360}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {model}}
pc.doc.set_visible{id = model, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local axis = pc.inspect.grow{kind = "cylinder", scan = scan, at = {5,0,5}, method = "circumscribed"}.element
local bottom = pc.inspect.grow{kind = "plane", scan = scan, at = {0,0,0}}.element
local top = pc.inspect.grow{kind = "plane", scan = scan, at = {0,0,10}}.element
local middle = pc.inspect.construct{made = "plane", from = {bottom,top}}.element
local comparison = pc.inspect.compare{scan = scan, reference = model}.comparison
local section = pc.inspect.section{scan = scan}.section
local position = pc.inspect.tolerance{characteristic = "position", element = axis,
  datums = {{element = bottom}}, basic = {0,0,0}, limit = 0.05,
  material = "mmc", material_size = 10.2}
assert(position.pass and position.value < 0.01 and position.bonus > 0.19)
for _, kind in ipairs({"surface_profile", "line_profile"}) do
  local reading = pc.inspect.tolerance{characteristic = kind, element = axis,
    comparison = comparison, section = section, limit = 0.1, unequal = 0.01}
  assert(reading.pass and reading.value < 0.1)
end
for _, kind in ipairs({"circular_runout", "total_runout"}) do
  local reading = pc.inspect.tolerance{characteristic = kind, element = axis,
    datum = axis, limit = 0.05, section_width = 0.1}
  assert(reading.pass and reading.value < 0.05)
end
local symmetry = pc.inspect.tolerance{characteristic = "symmetry", element = bottom,
  opposed = top, datum = middle, limit = 0.05}
assert(symmetry.pass and symmetry.value < 0.01)
assert(#pc.inspect.report{}.tolerances == 6)

pc.inspect.walls: Map how thin or thick a body's walls are.

Notes:

pc.inspect.element_solid: The solid primitive a fitted element stands for.

Notes:

See also pc.design.primitive.

Example: A scanned cylinder fitted and made a body again.

local drum = pc.doc.new_body{}
pc.design.primitive{body = drum, variant = "cylinder",
  kind = {Cylinder = {radius = 5, height = 10, angle_deg = 360}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {drum}}
pc.doc.set_visible{id = drum, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local fit = pc.inspect.grow{kind = "cylinder", scan = scan, at = {5, 0, 5}}
local s = pc.inspect.element_solid{element = fit.element}
local copy = pc.doc.new_body{name = s.name}
pc.design.primitive{body = copy, kind = s.kind, placement = s.placement}
assert(#pc.doc.rebuild() == 0)
local v = pc.doc.measure{body = copy}.volume
assert(math.abs(v - math.pi * 25 * 10) < 0.02 * math.pi * 25 * 10, v)

pc.inspect.clearance: Map a part's room in what it fits into.

Notes:

Example: A 10 mm cube in a 12 mm square pocket has 1 mm all round; moved 1.5 mm, it presses 0.5 mm into one wall.

local box = pc.doc.new_body{}
pc.design.primitive{body = box, kind = {Box = {length = 30, width = 30, height = 10}}}
pc.design.subtractive_primitive{body = box, kind = {Box = {length = 12, width = 12, height = 20}},
placement = {origin = {9, 9, 2}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
local part = pc.doc.new_body{}
pc.design.primitive{body = part, kind = {Box = {length = 10, width = 10, height = 10}}}
assert(#pc.doc.rebuild() == 0)
pc.doc.set_body{body = part, translation = {10, 10, 4}}
local fit = pc.inspect.clearance{part = part, housing = box, min_gap = 0.5}
assert(fit.interfering == 0 and math.abs(fit.narrowest - 1) < 1e-6, fit.narrowest)
pc.doc.set_body{body = part, translation = {11.5, 10, 4}}
local tight = pc.inspect.clearance{part = part, housing = box}
assert(tight.interfering > 0 and math.abs(tight.deepest - 0.5) < 1e-6, tight.deepest)

pc.inspect.overhang: Map a body's overhangs as it would print.

Notes:

Example: A box standing on the bed needs no support; on its edge, half of it does.

local body = pc.doc.new_body{}
pc.design.primitive{body = body}
assert(#pc.doc.rebuild() == 0)
local o = pc.inspect.overhang{body = body}
assert(o.share == 0 and o.limit == 45, o.share)
local q = math.pi / 8
pc.doc.set_body{body = body, rotation = {x = math.sin(q), y = 0, z = 0, w = math.cos(q)}}
local tilted = pc.inspect.overhang{body = body, limit = 40}
assert(math.abs(tilted.steepest - 45) < 1e-3, tilted.steepest)

pc.inspect.hot_spots: Where a comparison is out of tolerance, as patches.

Notes:

pc.inspect.volume_errors: Missing and excess material of a comparison.

Notes:

See also pc.inspect.hot_spots.

Example: A print two millimetres short of its part reads a missing layer.

local part = pc.doc.new_body{}
pc.design.primitive{body = part, kind = {Box = {length = 20, width = 20, height = 12}}}
local short = pc.doc.new_body{}
pc.design.primitive{body = short, kind = {Box = {length = 20, width = 20, height = 10}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {short}}
pc.doc.set_visible{id = short, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local c = pc.inspect.compare{scan = scan, reference = part}
local v = pc.inspect.volume_errors{comparison = c.comparison, cell = 0.5}
local r = v.regions[1]
assert(r.side == "missing" and r.form == "layer", r.side)
assert(math.abs(r.volume - 800) < 80 and math.abs(r.depth - 2) < 0.3, r.volume)

pc.inspect.map_export: Write a comparison's distances to a file.

Notes:

pc.inspect.best_fit: Move a scan onto a reference body, best fit.

Notes:

pc.inspect.move: Move and turn a scan by numbers.

Notes:

pc.inspect.reset_alignment: Put a scan back where the scanner placed it.

pc.inspect.compare: Compare a scan with a reference body, point by point.

Notes:

pc.inspect.construct: Make a point, line, plane or circle from elements.

Notes:

pc.inspect.fit: Fit a shape to the marked part of a scan and keep it as an element.

Notes:

pc.inspect.dimension: Measure a distance, angle or diameter between elements.

Notes:

pc.inspect.grow: Fit a surface grown, or an edge traced, from a point on a scan.

Notes:

Example: A scanned bore's mating size sits inside its mean size.

local drum = pc.doc.new_body{}
pc.design.primitive{body = drum, variant = "cylinder",
  kind = {Cylinder = {radius = 5, height = 10, angle_deg = 360}}}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, bodies = {drum}}
pc.doc.set_visible{id = drum, visible = false}
pc.file.import{path = path, scan = true}
pc.doc.rebuild()
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
local mean = pc.inspect.grow{kind = "cylinder", scan = scan, at = {5, 0, 5}}
local inside = pc.inspect.grow{kind = "cylinder", scan = scan,
  at = {5, 0, 5}, method = "inscribed"}
assert(inside.method == "inscribed")
assert(inside.shape.Cylinder.radius <= mean.shape.Cylinder.radius + 1e-9)
assert(mean.zone.width <= mean.form + 1e-9, mean.zone.width)

pc.inspect.report: Every element and dimension of the inspection.

mesh

pc.mesh.boolean: Boolean a solid.

Notes:

Example: Drill a scan.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local pin = pc.doc.new_body{}
    pc.design.primitive{body = pin, kind = {Cylinder = {radius = 1, height = 12, angle_deg = 360}}, placement = {origin = {5, 5, -1}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
    assert(#pc.doc.rebuild() == 0)
    local step = pc.mesh.boolean{scan = scan, operand = pin}
    assert(#pc.doc.rebuild() == 0)
    local volume = pc.mesh.result{feature = step.feature}.report.Boolean.volume
    assert(math.abs(volume - (1000 - math.pi * 10)) < 1)

pc.mesh.thicken: Thicken or hollow.

Notes:

Example: Wall a cube in.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.thicken{scan = scan, thickness = 1}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.result{feature = step.feature}.report.Shell
    assert(r.hollow and math.abs(r.volume - 488) < 10)
    local walled = pc.mesh.inspect{scan = scan}
    assert(walled.open_edges == 0 and math.abs(walled.volume - r.volume) < 1e-3)

pc.mesh.trim_to_scan: Trim a piece.

Notes:

Example: Trim a cap to a broken top.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local cap = pc.doc.new_body{}
    pc.design.primitive{body = cap, kind = {Box = {length = 12, width = 12, height = 8}}, placement = {origin = {-1, -1, 8}, x_axis = {1, 0, 0}, z_axis = {0, 0, 1}}}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.trim_to_scan{scan = scan, body = cap, gap = 0.1}
    assert(math.abs(r.volume - 144 * 5.9) < 0.01)
    assert(math.abs(r.mating_area - 100) < 0.01 and math.abs(r.gap_median - 0.1) < 1e-6)

pc.mesh.preview_cut: Preview a cut.

Notes:

Example: Preview a cap.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local before = pc.mesh.inspect{scan = scan}.triangles
    local cut = pc.mesh.preview_cut{scan = scan, at = 5}
    assert(cut.faces > 0 and cut.report.Cut.capped_loops == 1)
    assert(cut.report.Cut.open_loops == 0)
    assert(pc.mesh.inspect{scan = scan}.triangles == before)

pc.mesh.export: Write a file.

Notes:

Example: Export and read back.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local path = pc.file.temp_path{name = "part.ply"}
    local result = pc.mesh.export{scan = scan, path = path}
    pc.file.import{path = path, scan = true}
    assert(result.triangles == pc.mesh.inspect{scan = scan}.triangles)

pc.mesh.fill: Fill holes.

Notes:

Example: Close the open top of a scan.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    pc.mesh.delete{scan = scan, box = {min = {-1, -1, 9.99}, max = {11, 11, 11}}}
    assert(#pc.doc.rebuild() == 0)
    assert(pc.mesh.inspect{scan = scan}.open_edges > 0)
    local step = pc.mesh.fill{scan = scan, holes_up_to = 15, fairing = "flat"}
    assert(#pc.doc.rebuild() == 0)
    assert(pc.mesh.inspect{scan = scan}.open_edges == 0)
    assert(math.abs(pc.mesh.inspect{scan = scan}.volume - 1000) < 10)
    assert(pc.mesh.result{feature = step.feature}.faces > 0)

pc.mesh.smooth: Smooth noise.

Notes:

Example: Bound a smoothing step's movement.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.smooth{scan = scan, move_at_most = 0.01}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.result{feature = step.feature}.report.Smooth
    assert(r.max <= 0.010001 and r.rms <= r.max)

pc.mesh.offset: Offset faces.

Notes:

Example: Expand a ten millimetre cube.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    pc.mesh.offset{scan = scan, distance = 0.1}
    assert(#pc.doc.rebuild() == 0)
    assert(math.abs(pc.mesh.inspect{scan = scan}.volume - 10.2^3) < 0.1)

pc.mesh.reduce: Reduce triangles.

Notes:

Example: Read a reduction's verified accuracy.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.reduce{scan = scan, tolerance = 0.01, triangle_limit = 50000}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.result{feature = step.feature}
    assert(r.faces <= 50000)
    assert(r.report.Reduce.p999 <= 0.01)
    assert(r.report.Reduce.within_share >= 0.999)

pc.mesh.remesh: Remesh evenly.

Notes:

Example: Remesh a cube to one millimetre edges.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.remesh{scan = scan, edge_length = 1}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.result{feature = step.feature}
    assert(r.faces > 1000)
    assert(r.report.Remesh.max < 1e-3)
    assert(math.abs(pc.mesh.inspect{scan = scan}.volume - 1000) < 0.01)

pc.mesh.subdivide: Subdivide triangles.

Notes:

Example: Round a cube.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.subdivide{scan = scan, levels = 3, smooth = true, keep_edges = false}
    assert(#pc.doc.rebuild() == 0)
    local r = pc.mesh.result{feature = step.feature}
    assert(r.faces == 12 * 64)
    assert(r.report.Subdivide.moved > 1)
    assert(pc.mesh.inspect{scan = scan}.volume < 1000)

pc.mesh.repair_intersections: Repair self-intersections.

Notes:

See also pc.mesh.intersections.

Example: Merge two overlapping cubes.

for _, at in ipairs{0, 5} do
    local s = pc.sketch.new{plane = "XY"}
    pc.sketch.rect{sketch = s, x = at, y = at, width = 10, height = 10}
    pc.design.pad{sketch = s, length = 10}
end
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "overlapping.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
assert(pc.mesh.intersections{scan = scan}.pairs > 0)
local step = pc.mesh.repair_intersections{scan = scan}
assert(#pc.doc.rebuild() == 0)
assert(pc.mesh.result{feature = step.feature}.report.Repair.crossings > 0)
assert(math.abs(pc.mesh.inspect{scan = scan}.volume - 1750) < 0.01)
assert(pc.mesh.intersections{scan = scan}.pairs == 0)

pc.mesh.result: Step results.

Notes:

Example: Read a built step.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.smooth{scan = scan, move_at_most = 0.01}
    assert(#pc.doc.rebuild() == 0)
    local result = pc.mesh.result{feature = step.feature}
    assert(result.faces > 0 and result.report.Smooth.max <= 0.010001)

pc.mesh.set: Edit a step.

Notes:

Example: Change an offset in place.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "part.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end

    local step = pc.mesh.offset{scan = scan, distance = 0.1}
    pc.mesh.set{feature = step.feature, op = {Offset = {region = "All", distance = 0.2}}}
    assert(#pc.doc.rebuild() == 0)
    assert(math.abs(pc.mesh.inspect{scan = scan}.volume - 10.4^3) < 0.1)

pc.mesh.islands: Remove specks.

pc.mesh.delete: Delete marked faces.

Notes:

pc.mesh.flip: Flip normals.

Notes:

pc.mesh.cut: Cut by a plane.

Notes:

pc.mesh.split: Split into bodies.

Notes:

Example: Split two parts scanned together.

local s = pc.sketch.new{plane = "XY"}
pc.sketch.rect{sketch = s, x = 0, y = 0, width = 10, height = 10}
pc.sketch.rect{sketch = s, x = 20, y = 0, width = 5, height = 5}
pc.design.pad{sketch = s, length = 10}
assert(#pc.doc.rebuild() == 0)
local path = pc.file.temp_path{name = "parts.stl"}
pc.file.export{path = path, format = "stl"}
pc.file.import{path = path, scan = true}
local scan
for _, b in ipairs(pc.doc.bodies()) do if b.scan then scan = b.id end end
assert(pc.mesh.inspect{scan = scan}.pieces == 2)
local split = pc.mesh.split{scan = scan}
assert(#split.bodies == 2)
local a = pc.mesh.inspect{scan = split.bodies[1]}.volume
local b = pc.mesh.inspect{scan = split.bodies[2]}.volume
assert(math.abs(math.min(a, b) - 250) < 1 and math.abs(math.max(a, b) - 1000) < 1)

pc.mesh.intersections: Find self-intersections.

Notes:

See also pc.mesh.repair_intersections.

pc.mesh.deviation: Edit deviation.

Notes:

pc.mesh.inspect: Topology and volume.

Notes:

project

pc.project.import: Bring a FreeCAD file's bodies, sketches, texts and links into the document: bodies of Design features, sketches and linked copies, and what has no counterpart as the shapes the file saved.

Notes:

This page's source