Reference

The cad library (Python)

cad is the Python library a model is written with: import cad, then the document types, their decorators and their operations, and the integrations' helpers. A model's script runs with cad run, which puts this release of the library and the integrations the script imports on its path, so a script names no installation of its own.

A program of your own that imports cad names the release exactly, cad==0.11.13 (with an integration's extra, cad[build123d]==0.11.13): PyPI's cad project holds unrelated earlier releases an open requirement would pick. cad requirement prints the exact requirement for this release.

cadmodule

CAD models as Python, built by its engine (cad.engine) into documents and the files they declare.

The root holds __version__, CadDeprecationWarning and the document types, one object each (cad.registry): model (a model built from code, held in the engine's memory, with no file), xbf, step, glb, stl, threemf, dxf, urdf, sdf, srdf, kicad_pcb and kicad_sch. A type is its decorator where it has one (@model, @step("arm.step")), its edit where its files are changed in place (with kicad_pcb.edit("board.kicad_pcb") as board:), its reader where it has one (step.read) and its operations, one to one with the cad <type> <operation> commands: .export and .snapshot, .inspect, and those named for what they do (.dfm, .solve, .drc, .erc, .validate). Our helpers that take build123d's objects are the build123d integration's, cad.build123d (memo, paint, the AP242 mechanism, a GLB's animation, measurements, flat patterns); those that take trimesh's are the trimesh integration's, cad.trimesh (a mesh's 3D printing measurements: printing, orientations); those that call MuJoCo are the mujoco integration's, cad.mujoco (a document as a mujoco.MjSpec, a part's collision chosen on it, the spec saved, and a MuJoCo model checked by MuJoCo's own compiler: spec, fit, save, check); those that take Blender's are the blender integration's, cad.blender (load: a GLB in Blender's scene, for a render); and OrcaSlicer's presets, written complete for its command line, are the orcaslicer integration's, cad.orcaslicer (presets, complete). Process control (cad serve, status, stop, server) is the cad command's alone. Every name loads on first use: import cad imports no CAD kernel, and import build123d binds a module the kernel loads into on its first attribute (_internal/lazy_kernel.py). The earlier spellings (cad.read_step, cad.export, cad.ap242, ...) are aliases of what they name now, each saying so once (_internal/aliases.py).

cad.__version__attribute

cad.__version__: str

The release of the library this is, as its distribution's metadata says it.

cad.CadDeprecationWarningclass

class cad.CadDeprecationWarning(FutureWarning)

A spelling the library still answers, under the name it has now. A FutureWarning, so Python shows it by default: the people who read it are a model's authors, not a library's developers.

Document types

One object a type, each its decorator where it has one, its reader, its edit, and its operations, one to one with the cad <type> <operation> commands.

cad.modelobject

The model document type, a model built from code and held in the engine's memory (cad.registry).

A model has no file behind it: it is addressed by its document id (cad run SCRIPT.py prints it) or the handle its call returns. @model declares one (@model(name=...); model(shape, name=...) hands a shape over), with no file of its own; the files it declares are the other types' decorators (@xbf("XBF/arm.xbf"), @step("arm.step")). Its operations are the cad model <operation> commands': model.export(handle_or_id, *destinations, tolerance=None, angle=None), model.snapshot(...), model.inspect(...) and model.dfm(handle_or_id, process="cnc") (or "sheet", "molding", "printing"), which checks it for manufacturing on its exact geometry, measured by the engine with the build123d integration (cad._internal.manufacturing), and model.solve(handle_or_id, study=..., out="results/"), a stress study of it (cad._internal.fea.operation), which reads an .xbf the engine writes of it in a temporary folder. A file is refused by name: arm.xbf is an xbf's (cad.xbf). Everything loads on first use: import cad.model imports no CAD kernel (cad._internal.document_type).

@cad.modeldecorator

@cad.model(
    target: Any = None,
    /,
    *,
    name: str | None = None,
    animations: Any = None,
) -> Any

@model or @model(name=...): declare a model; model(shape, name=...): hand a shape over as a named model (cad.engine.model.model).

cad.model.exportfunction

cad.model.export(
    source: Any,
    *destinations: Any,
    tolerance: float | None = None,
    angle: float | None = None,
    zero: str | None = None,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad model export: write the document to other files, each kind by its suffix (.step, .glb, .stl, .3mf, .dxf, .xbf, .xml (MJCF, its meshes beside it), .urdf (its meshes beside it)); --tolerance and --angle mesh a .glb, an .stl or a .3mf finer.

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.model.snapshotfunction

cad.model.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad model snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.model.inspectfunction

cad.model.inspect(
    source: Any,
    ref: str | None = None,
    *,
    query: str | None = None,
    progress: Any = None,
) -> Facts | list[Facts]

The command cad model inspect: what the document holds, then its build closure; with a ref, what one element or part is and what made it.

What a ref names in a document (refs: hand/finger.2/face 7, base/f:..., a copied /abs/kit.xbf#... line) and what made it. An element answers what the kernel measures of it — its points placed where its occurrence stands, in the document's frame — with its canonical ref, its occurrence's path and, of a model's document, made_by (a file names no model); a part or an assembly its volume and its mass: each part's volume times its material's density, summed (cli.weighed), its world bounds and a part's placement (_placed). One answer per selector (a list for several). Without ref, the build closure the xbf holds (previous): its engine, libraries, source, modules, inputs and key, read from the file alone. A ref that names nothing, or several things, is refused by name (refs.RefError). No query builds a missing model or writes its declared outputs. query="build" returns file metadata/closure or live build metadata; query="geometry" requires a ref, and query="closure" accepts none. query="summary" (cad xbf inspect DOC with no ref) is {"summary", "closure"}: what the document holds at a glance (_summary), and its closure, as the engine holds it; of a GLB, {"mesh"}: its nodes, meshes and animations, from its JSON alone (_mesh). query="structure" is the summary without bounds, volume or mass and requests no measurements. No form meshes anything. A part's volume and box are cached by geometry key and measured in batches. The summary's measurement goes, frame by frame, to progress (progress.py: inspect-measure, measure, counted as the engine tells each part's facts in), as export takes it — by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.model.dfmfunction

cad.model.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] | None = None,
    material: str | None = None,
    axes: int | None = None,
    turning: bool = False,
    tools: str | None = None,
    stock: str | None = None,
    thickness: float | None = None,
    k_factor: float | None = None,
    bend_radius: float | None = None,
    kerf: float | None = None,
    sheet_size: str | None = None,
    pull: str | None = None,
    wall_limit: float | None = None,
    zero_tol: float | None = None,
    cavities: int | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad model dfm: check it can be made: CNC machining (--process cnc), sheet metal (sheet), injection molding (molding) or 3D printing (printing), measured and judged against general, cited rules, each finding at a face's or an edge's ref.

Check a part for a manufacturing process: CNC machining, sheet metal, injection molding or 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A STEP, an xbf or a model's document is measured on its exact geometry, each finding at a face ref (cad xbf inspect DOC REF resolves it). The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit, refs). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: a model's document id the engine holds (cad run SCRIPT.py prints it), or the handle its call returns.
  • process: cnc, sheet, molding or printing; default, for a STEP, an xbf or a model, the process the parts declare (part.material = metals.aluminum(process=machined()): machined is cnc, molded molding, fdm, sls, mjf, slm and vat printing with technology fdm, sls, mjf, pbf and sla), when every part agrees.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • axes: cnc: the milling machine's axes, 3, 4 or 5; default 3.
  • turning: cnc: the part is turned on a lathe (its axis found), not milled.
  • tools: cnc: the end mill diameters available, in mm, comma separated (3,6,10); default none: a corner is held to the smallest tool that can exist (0.05 mm across, cad's own floor) and to how deep a tool of its size reaches; a radius of 1.25 mm or more (a 2.5 mm end mill's) is recommended.
  • stock: cnc: the stock's size in mm (100x60x25); default the part's box.
  • thickness: sheet: the stock's thickness in mm; default measured.
  • k_factor: sheet: the neutral axis's place in the thickness, for the flat pattern (the shop's bend table's); default a K-factor chart's, by the material and each bend's radius.
  • bend_radius: sheet: the shop's inside bend radius in mm, compared with the part's.
  • kerf: sheet: the cutting kerf in mm, for small features.
  • sheet_size: sheet: the shop's largest sheet in mm (1219x2438); default a standard 5 x 10 ft sheet (3048x1524), assumed.
  • pull: molding: the pull direction, an axis (z, -y) or x,y,z components; default z.
  • wall_limit: molding: faces at or above this many degrees from the pull are not walls; default 45.
  • zero_tol: molding: draft under this many degrees is zero draft; default 0.05.
  • cavities: molding: cavities in the mold, for the clamp force; default 1.
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: molding the pulls (x, y, z and the part's principal axes), printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.model.interferencefunction

cad.model.interference(
    source: Any,
    *,
    poses: Any = (),
    fits: Any = (),
    min_volume: float | None = None,
) -> Any

The command cad model interference: which parts share volume, as built and at each pose asked (--pose: a mechanism state, a configuration sequence at a time, or joint values): a pair with air between its parts ruled out on their meshes, every other measured exactly on the parts' own solids, the fits named on purpose (--fit A B) listed apart, and each pair it could not measure said.

cad.model.interference: which parts of the document share volume.

Every pair of parts whose boxes meet is answered, as built and at each pose asked, in one of the engine's checks processes: a pair whose meshes show air between the two parts shares nothing, and every other is measured exactly by the kernel on the parts' own solids. Each answer is kept in the engine's cache by the two parts' geometries and how one stands to the other, so a document edited is measured again only where a part that changed is one of the two, and a check stopped by its time goes on from what it had measured. Nothing is built or written, and the same check of an unchanged document is answered at once from the result the engine keeps: one that answered every pair.

poses: the poses to check at beside as built, each a pose as every command takes one: a mechanism state's name, a configuration sequence at a time of it ("walk@0.6"), or a {joint or coupling: value} table. The check takes the poses it is given and chooses none: every state, or a sequence every tenth of a second, is the caller's list. fits: the pairs meant to share volume (a press-fit pin, a bearing in its bore), each two refs or globs (("pin", "base")): listed apart, and no overlap. min_volume: a shared volume at or below it (mm3) is none; 0.001 by default, the rounding along a face where two parts touch.

Returns a cad.results.CheckResult: ok when no two parts share volume and every pair was answered; failed with an overlapping_parts finding for each pair that does (location and refs the two occurrences' paths, value the most volume shared, mm3); not_checked (reason: unmeasured) when none was found but a pair could not be measured — past its time, its process gone, the kernel's refusal — which is never a pass: asked again, the check goes on from what it measured. measurements holds the poses, the pairs counted (pairs: apart, kept, measured) and every row (overlaps, fits, unmeasured: each between its two parts, with every pose it holds at). An option the document does not answer — a pose it has no state or sequence for, a fit that names nothing — is refused by name (a ValueError); a document that does not read is not_checked by its reason; a check that did not complete raises as cad.engine.api.check says.

cad.model.solvefunction

cad.model.solve(
    source: Path,
    *,
    study: str | dict | None = None,
    out: Path | None = None,
    occurrence: str | None = None,
    deck: bool = False,
    verbose: bool = False,
) -> FeaResult

The command cad model solve: a linear static stress study of a part or a bonded assembly: with --study and --out DIR, the solve, its results written into DIR (result.json, result.glb, result.vtu, stress.png, displacement.png), each part's peak stress and safety factor, and a part that yields failing it; with no --study, the parts, the pairs that touch and a part's faces a study names.

A linear static stress study of a part or an assembly bonded where its parts touch.

With no study it lists what a study names, writing nothing: the document's parts, the pairs that touch (bonded by default) and one part's faces by ref with area, centre and a hint (plane, normal -Z, largest). With a study and --out it meshes (netgen), solves (CalculiX, from cad[calculix]; CAD_CCX names another) and writes its results into the folder --out names: result.json (every number, as --json prints it), result.glb (the deformed surface coloured by stress, any viewer opens it), result.vtu (the volume's fields, for meshio, PyVista or ParaView), stress.png and displacement.png (where a still can be drawn). Each part's peak stress and safety factor against its own material's yield are in the result. A part that yields or misses a check fails it, its results written all the same; a study whose answer would be wrong (a part nothing holds, a load no face takes) is refused. --json carries every number.

  • source: the part or the assembly: a .step or .xbf, or a model's document id the engine holds (cad model solve), or the handle its call returns.
  • study: the study: a JSON file path, inline JSON, or (a library caller) a dict: the fixed faces, the loads (forces, pressures, gravity, acceleration), a material where the model has none, an assembly's parts and connections and the checks to judge. Without it, the setup.
  • out: the folder a solve writes its results into, made when missing; a study's alone.
  • occurrence: the part whose faces the setup lists, by its name or ref, where the document holds several.
  • deck: also write ccx.inp, the input CalculiX solved (the finer solve's when there were two); a study's alone.
  • verbose: say every progress line and the timings on stderr. Without it a long solve still says how far it has got about every 10 s.

cad.model.rangesfunction

cad.model.ranges(
    source: Path,
    *,
    step: float = 1.0,
    clearance: float = 0.3,
    joint: tuple[str, ...] = (),
    verbose: bool = False,
) -> CheckResult

The command cad model ranges: each joint's stops found from the geometry: the joint turned or slid alone, a step at a time each way, until its parts meet another part; the stops and which parts meet, nothing written.

Each joint's stops, found from the geometry: where its parts first meet another part.

Each joint a person moves is turned (or slid) alone from the as-built pose, the joints that follow it with it and every other as built, a step at a time each way: a turn a full turn each way, a slide the document's extent. Its stop each way is where its child link meets its parent link (each with what is fixed to it): a stop whatever the other joints do, what its range declares. Where anything it moves meets another link first, in the pose the others stand in, that clash is said beside the stop. Two parts meet where they come within the clearance and within half their gap as built (less the 0.3 mm the surfaces are sampled to), or where their contact grows by about 15 mm^2 on a surface that stops the motion: parts touching already as built (a horn on its servo) meet only when their contact grows there or one is pushed into the other (a part resting on its parent, turned into it, stops where it lies), parts near as built (apart, within the clearance) only where their gap halves, and each joint's finding names them with their gap as built and at each stop. A pair touching as built on a surface about the joint's axis (a plate bolted to a motor's output, the output drawn as one solid with the motor's case) turns on it: neither that face nor what of the output lies within its reach (a boss, a pin, a bolt's seat) stops the joint, and the finding says the pair (turns on). A clash (anything the joint moves meeting another link, the other joints as built) belongs to the drawn pose, which a simulator's contacts hold: the range is the stop. Parts drawn one inside the other (overlapping as built, a vendor's simplified parts sunk into each other) meet only where one is pushed deeper into the other than drawn, by 0.6 mm more: each joint's finding names them with the volume they share and how deep, and a stop they make lies past the true one by up to about that depth. A larger clearance only narrows a range. Each joint's finding says its stops in degrees or millimetres around the as-built pose (and in its own values where that is not zero) and which two parts meet past each, every part tested against every other on its own surface. The model is not changed: adopt the numbers into its joints' ranges. --json carries every number.

  • source: the document: a .step or .xbf, or a model's document id the engine holds (cad model ranges), or the handle its call returns.
  • step: the sweep's step: degrees for a turning joint, millimetres for a sliding one; default 1.
  • clearance: how near two parts' surfaces come before they count as touching, in millimetres; default 0.3, the least (where they all but touch): a larger one stops each joint where its parts first come that near.
  • joint: sweep this joint alone (repeat it for several); default every joint a person moves. A name the document has no such joint by is refused, naming its joints.
  • verbose: say on stderr each step as it starts (reading the document, sampling its surfaces, each joint) and each joint's stops as it ends (a joint or a sampling that takes long is said either way).

cad.xbfobject

The XBF document type, the engine's own document saved as a file (cad.registry).

@xbf("XBF/arm.xbf") declares a model's XBF file; xbf.read(path) reads one into a model; its operations (xbf.export("arm.xbf", *destinations), ...) are the cad xbf <operation> commands', each of an .xbf file: a model the engine holds, by its handle or id, is cad.model's. xbf.dfm(source, process="cnc") (or "sheet", "molding", "printing") checks it for manufacturing on its exact geometry, with the build123d integration (cad._internal.manufacturing). xbf.solve(source, study=..., out="results/") runs a stress study on its part or bonded assembly, writing its results into that folder (with no study, it lists the parts, pairs and faces a study names), with the kernel, netgen and calculix integrations (cad._internal.fea.operation). Everything loads on first use: import cad.xbf imports no CAD kernel (cad._internal.document_type).

@cad.xbfdecorator

@cad.xbf(out: Any, *, name: str | None = None) -> Any

Declare an explicit output: @xbf(out='path.xbf'), optionally named within the script folder by name=. The output path is required; decoration builds nothing.

cad.xbf.readfunction

cad.xbf.read(path: Any) -> Any

An engine document (.xbf) as a build123d shape: a copy of its geometry, as read_step gives a STEP's — a compound tree of its assembly, every part and group named, coloured and given its materials (painted faces too) as the document has them, each element named as the document names it. Its mechanism and configurations are not imported: a part is a part. Read once per worker and held, keyed by the file's bytes, as read_step is. The fast way to bring a vendor STEP in: convert it once (cadgen export vendor.step vendor.xbf) and read the xbf.

cad.xbf.exportfunction

cad.xbf.export(
    source: Any,
    *destinations: Any,
    tolerance: float | None = None,
    angle: float | None = None,
    zero: str | None = None,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad xbf export: write the document to other files, each kind by its suffix (.step, .glb, .stl, .3mf, .dxf, .xbf, .xml (MJCF, its meshes beside it), .urdf (its meshes beside it)); --tolerance and --angle mesh a .glb, an .stl or a .3mf finer.

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.xbf.snapshotfunction

cad.xbf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad xbf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.xbf.inspectfunction

cad.xbf.inspect(
    source: Any,
    ref: str | None = None,
    *,
    query: str | None = None,
    progress: Any = None,
) -> Facts | list[Facts]

The command cad xbf inspect: what the document holds, then its build closure; with a ref, what one element or part is and what made it.

What a ref names in a document (refs: hand/finger.2/face 7, base/f:..., a copied /abs/kit.xbf#... line) and what made it. An element answers what the kernel measures of it — its points placed where its occurrence stands, in the document's frame — with its canonical ref, its occurrence's path and, of a model's document, made_by (a file names no model); a part or an assembly its volume and its mass: each part's volume times its material's density, summed (cli.weighed), its world bounds and a part's placement (_placed). One answer per selector (a list for several). Without ref, the build closure the xbf holds (previous): its engine, libraries, source, modules, inputs and key, read from the file alone. A ref that names nothing, or several things, is refused by name (refs.RefError). No query builds a missing model or writes its declared outputs. query="build" returns file metadata/closure or live build metadata; query="geometry" requires a ref, and query="closure" accepts none. query="summary" (cad xbf inspect DOC with no ref) is {"summary", "closure"}: what the document holds at a glance (_summary), and its closure, as the engine holds it; of a GLB, {"mesh"}: its nodes, meshes and animations, from its JSON alone (_mesh). query="structure" is the summary without bounds, volume or mass and requests no measurements. No form meshes anything. A part's volume and box are cached by geometry key and measured in batches. The summary's measurement goes, frame by frame, to progress (progress.py: inspect-measure, measure, counted as the engine tells each part's facts in), as export takes it — by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.xbf.dfmfunction

cad.xbf.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] | None = None,
    material: str | None = None,
    axes: int | None = None,
    turning: bool = False,
    tools: str | None = None,
    stock: str | None = None,
    thickness: float | None = None,
    k_factor: float | None = None,
    bend_radius: float | None = None,
    kerf: float | None = None,
    sheet_size: str | None = None,
    pull: str | None = None,
    wall_limit: float | None = None,
    zero_tol: float | None = None,
    cavities: int | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad xbf dfm: check it can be made: CNC machining (--process cnc), sheet metal (sheet), injection molding (molding) or 3D printing (printing), measured and judged against general, cited rules, each finding at a face's or an edge's ref.

Check a part for a manufacturing process: CNC machining, sheet metal, injection molding or 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A STEP, an xbf or a model's document is measured on its exact geometry, each finding at a face ref (cad xbf inspect DOC REF resolves it). The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit, refs). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .xbf file to check.
  • process: cnc, sheet, molding or printing; default, for a STEP, an xbf or a model, the process the parts declare (part.material = metals.aluminum(process=machined()): machined is cnc, molded molding, fdm, sls, mjf, slm and vat printing with technology fdm, sls, mjf, pbf and sla), when every part agrees.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • axes: cnc: the milling machine's axes, 3, 4 or 5; default 3.
  • turning: cnc: the part is turned on a lathe (its axis found), not milled.
  • tools: cnc: the end mill diameters available, in mm, comma separated (3,6,10); default none: a corner is held to the smallest tool that can exist (0.05 mm across, cad's own floor) and to how deep a tool of its size reaches; a radius of 1.25 mm or more (a 2.5 mm end mill's) is recommended.
  • stock: cnc: the stock's size in mm (100x60x25); default the part's box.
  • thickness: sheet: the stock's thickness in mm; default measured.
  • k_factor: sheet: the neutral axis's place in the thickness, for the flat pattern (the shop's bend table's); default a K-factor chart's, by the material and each bend's radius.
  • bend_radius: sheet: the shop's inside bend radius in mm, compared with the part's.
  • kerf: sheet: the cutting kerf in mm, for small features.
  • sheet_size: sheet: the shop's largest sheet in mm (1219x2438); default a standard 5 x 10 ft sheet (3048x1524), assumed.
  • pull: molding: the pull direction, an axis (z, -y) or x,y,z components; default z.
  • wall_limit: molding: faces at or above this many degrees from the pull are not walls; default 45.
  • zero_tol: molding: draft under this many degrees is zero draft; default 0.05.
  • cavities: molding: cavities in the mold, for the clamp force; default 1.
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: molding the pulls (x, y, z and the part's principal axes), printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.xbf.interferencefunction

cad.xbf.interference(
    source: Any,
    *,
    poses: Any = (),
    fits: Any = (),
    min_volume: float | None = None,
) -> Any

The command cad xbf interference: which parts share volume, as built and at each pose asked (--pose: a mechanism state, a configuration sequence at a time, or joint values): a pair with air between its parts ruled out on their meshes, every other measured exactly on the parts' own solids, the fits named on purpose (--fit A B) listed apart, and each pair it could not measure said.

cad.xbf.interference: which parts of the document share volume.

Every pair of parts whose boxes meet is answered, as built and at each pose asked, in one of the engine's checks processes: a pair whose meshes show air between the two parts shares nothing, and every other is measured exactly by the kernel on the parts' own solids. Each answer is kept in the engine's cache by the two parts' geometries and how one stands to the other, so a document edited is measured again only where a part that changed is one of the two, and a check stopped by its time goes on from what it had measured. Nothing is built or written, and the same check of an unchanged document is answered at once from the result the engine keeps: one that answered every pair.

poses: the poses to check at beside as built, each a pose as every command takes one: a mechanism state's name, a configuration sequence at a time of it ("walk@0.6"), or a {joint or coupling: value} table. The check takes the poses it is given and chooses none: every state, or a sequence every tenth of a second, is the caller's list. fits: the pairs meant to share volume (a press-fit pin, a bearing in its bore), each two refs or globs (("pin", "base")): listed apart, and no overlap. min_volume: a shared volume at or below it (mm3) is none; 0.001 by default, the rounding along a face where two parts touch.

Returns a cad.results.CheckResult: ok when no two parts share volume and every pair was answered; failed with an overlapping_parts finding for each pair that does (location and refs the two occurrences' paths, value the most volume shared, mm3); not_checked (reason: unmeasured) when none was found but a pair could not be measured — past its time, its process gone, the kernel's refusal — which is never a pass: asked again, the check goes on from what it measured. measurements holds the poses, the pairs counted (pairs: apart, kept, measured) and every row (overlaps, fits, unmeasured: each between its two parts, with every pose it holds at). An option the document does not answer — a pose it has no state or sequence for, a fit that names nothing — is refused by name (a ValueError); a document that does not read is not_checked by its reason; a check that did not complete raises as cad.engine.api.check says.

cad.xbf.solvefunction

cad.xbf.solve(
    source: Path,
    *,
    study: str | dict | None = None,
    out: Path | None = None,
    occurrence: str | None = None,
    deck: bool = False,
    verbose: bool = False,
) -> FeaResult

The command cad xbf solve: a linear static stress study of a part or a bonded assembly: with --study and --out DIR, the solve, its results written into DIR (result.json, result.glb, result.vtu, stress.png, displacement.png), each part's peak stress and safety factor, and a part that yields failing it; with no --study, the parts, the pairs that touch and a part's faces a study names.

A linear static stress study of a part or an assembly bonded where its parts touch.

With no study it lists what a study names, writing nothing: the document's parts, the pairs that touch (bonded by default) and one part's faces by ref with area, centre and a hint (plane, normal -Z, largest). With a study and --out it meshes (netgen), solves (CalculiX, from cad[calculix]; CAD_CCX names another) and writes its results into the folder --out names: result.json (every number, as --json prints it), result.glb (the deformed surface coloured by stress, any viewer opens it), result.vtu (the volume's fields, for meshio, PyVista or ParaView), stress.png and displacement.png (where a still can be drawn). Each part's peak stress and safety factor against its own material's yield are in the result. A part that yields or misses a check fails it, its results written all the same; a study whose answer would be wrong (a part nothing holds, a load no face takes) is refused. --json carries every number.

  • source: the part or the assembly: a .step or .xbf, or a model's document id the engine holds (cad model solve), or the handle its call returns.
  • study: the study: a JSON file path, inline JSON, or (a library caller) a dict: the fixed faces, the loads (forces, pressures, gravity, acceleration), a material where the model has none, an assembly's parts and connections and the checks to judge. Without it, the setup.
  • out: the folder a solve writes its results into, made when missing; a study's alone.
  • occurrence: the part whose faces the setup lists, by its name or ref, where the document holds several.
  • deck: also write ccx.inp, the input CalculiX solved (the finer solve's when there were two); a study's alone.
  • verbose: say every progress line and the timings on stderr. Without it a long solve still says how far it has got about every 10 s.

cad.xbf.rangesfunction

cad.xbf.ranges(
    source: Path,
    *,
    step: float = 1.0,
    clearance: float = 0.3,
    joint: tuple[str, ...] = (),
    verbose: bool = False,
) -> CheckResult

The command cad xbf ranges: each joint's stops found from the geometry: the joint turned or slid alone, a step at a time each way, until its parts meet another part; the stops and which parts meet, nothing written.

Each joint's stops, found from the geometry: where its parts first meet another part.

Each joint a person moves is turned (or slid) alone from the as-built pose, the joints that follow it with it and every other as built, a step at a time each way: a turn a full turn each way, a slide the document's extent. Its stop each way is where its child link meets its parent link (each with what is fixed to it): a stop whatever the other joints do, what its range declares. Where anything it moves meets another link first, in the pose the others stand in, that clash is said beside the stop. Two parts meet where they come within the clearance and within half their gap as built (less the 0.3 mm the surfaces are sampled to), or where their contact grows by about 15 mm^2 on a surface that stops the motion: parts touching already as built (a horn on its servo) meet only when their contact grows there or one is pushed into the other (a part resting on its parent, turned into it, stops where it lies), parts near as built (apart, within the clearance) only where their gap halves, and each joint's finding names them with their gap as built and at each stop. A pair touching as built on a surface about the joint's axis (a plate bolted to a motor's output, the output drawn as one solid with the motor's case) turns on it: neither that face nor what of the output lies within its reach (a boss, a pin, a bolt's seat) stops the joint, and the finding says the pair (turns on). A clash (anything the joint moves meeting another link, the other joints as built) belongs to the drawn pose, which a simulator's contacts hold: the range is the stop. Parts drawn one inside the other (overlapping as built, a vendor's simplified parts sunk into each other) meet only where one is pushed deeper into the other than drawn, by 0.6 mm more: each joint's finding names them with the volume they share and how deep, and a stop they make lies past the true one by up to about that depth. A larger clearance only narrows a range. Each joint's finding says its stops in degrees or millimetres around the as-built pose (and in its own values where that is not zero) and which two parts meet past each, every part tested against every other on its own surface. The model is not changed: adopt the numbers into its joints' ranges. --json carries every number.

  • source: the document: a .step or .xbf, or a model's document id the engine holds (cad model ranges), or the handle its call returns.
  • step: the sweep's step: degrees for a turning joint, millimetres for a sliding one; default 1.
  • clearance: how near two parts' surfaces come before they count as touching, in millimetres; default 0.3, the least (where they all but touch): a larger one stops each joint where its parts first come that near.
  • joint: sweep this joint alone (repeat it for several); default every joint a person moves. A name the document has no such joint by is refused, naming its joints.
  • verbose: say on stderr each step as it starts (reading the document, sampling its surfaces, each joint) and each joint's stops as it ends (a joint or a sampling that takes long is said either way).

cad.stepobject

The STEP document type, an ISO 10303 (AP242) exchange file (cad.registry).

@step("arm.step") declares a model's STEP file; step.read(path) reads one into a model; its operations (step.export(source, *destinations), ...) are the cad step <operation> commands'. step.dfm(source, process="cnc") (or "sheet", "molding", "printing") checks it for manufacturing on its exact geometry, with the build123d integration (cad._internal.manufacturing). step.solve(source, study=..., out="results/") runs a stress study on its part or bonded assembly, writing its results into that folder (with no study, it lists the parts, pairs and faces a study names), with the kernel, netgen and calculix integrations (cad._internal.fea.operation). Everything loads on first use: import cad.step imports no CAD kernel (cad._internal.document_type).

@cad.stepdecorator

@cad.step(out: Any, *, name: str | None = None) -> Any

Declare an explicit output: @step(out='path.step'), optionally named within the script folder by name=. The output path is required; decoration builds nothing.

cad.step.readfunction

cad.step.read(path: Any) -> Any

A STEP file as a build123d shape: a compound tree of its assembly, every part and group labelled, coloured and given its material as the file has them. Parsed once per worker and held, in a reader process of the build's (its working memory never the worker's): a later build's read of the same bytes is the memo's hit, the same objects.

cad.step.exportfunction

cad.step.export(
    source: Any,
    *destinations: Any,
    tolerance: float | None = None,
    angle: float | None = None,
    zero: str | None = None,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad step export: write the document to other files, each kind by its suffix (.step, .glb, .stl, .3mf, .dxf, .xbf, .xml (MJCF, its meshes beside it), .urdf (its meshes beside it)); --tolerance and --angle mesh a .glb, an .stl or a .3mf finer.

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.step.snapshotfunction

cad.step.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad step snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.step.inspectfunction

cad.step.inspect(
    source: Any,
    ref: str | None = None,
    *,
    query: str | None = None,
    progress: Any = None,
) -> Facts | list[Facts]

The command cad step inspect: what the document holds, then its build closure; with a ref, what one element or part is and what made it.

What a ref names in a document (refs: hand/finger.2/face 7, base/f:..., a copied /abs/kit.xbf#... line) and what made it. An element answers what the kernel measures of it — its points placed where its occurrence stands, in the document's frame — with its canonical ref, its occurrence's path and, of a model's document, made_by (a file names no model); a part or an assembly its volume and its mass: each part's volume times its material's density, summed (cli.weighed), its world bounds and a part's placement (_placed). One answer per selector (a list for several). Without ref, the build closure the xbf holds (previous): its engine, libraries, source, modules, inputs and key, read from the file alone. A ref that names nothing, or several things, is refused by name (refs.RefError). No query builds a missing model or writes its declared outputs. query="build" returns file metadata/closure or live build metadata; query="geometry" requires a ref, and query="closure" accepts none. query="summary" (cad xbf inspect DOC with no ref) is {"summary", "closure"}: what the document holds at a glance (_summary), and its closure, as the engine holds it; of a GLB, {"mesh"}: its nodes, meshes and animations, from its JSON alone (_mesh). query="structure" is the summary without bounds, volume or mass and requests no measurements. No form meshes anything. A part's volume and box are cached by geometry key and measured in batches. The summary's measurement goes, frame by frame, to progress (progress.py: inspect-measure, measure, counted as the engine tells each part's facts in), as export takes it — by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.step.dfmfunction

cad.step.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] | None = None,
    material: str | None = None,
    axes: int | None = None,
    turning: bool = False,
    tools: str | None = None,
    stock: str | None = None,
    thickness: float | None = None,
    k_factor: float | None = None,
    bend_radius: float | None = None,
    kerf: float | None = None,
    sheet_size: str | None = None,
    pull: str | None = None,
    wall_limit: float | None = None,
    zero_tol: float | None = None,
    cavities: int | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad step dfm: check it can be made: CNC machining (--process cnc), sheet metal (sheet), injection molding (molding) or 3D printing (printing), measured and judged against general, cited rules, each finding at a face's or an edge's ref.

Check a part for a manufacturing process: CNC machining, sheet metal, injection molding or 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A STEP, an xbf or a model's document is measured on its exact geometry, each finding at a face ref (cad xbf inspect DOC REF resolves it). The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit, refs). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .step or .stp file to check.
  • process: cnc, sheet, molding or printing; default, for a STEP, an xbf or a model, none: a STEP keeps no process.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • axes: cnc: the milling machine's axes, 3, 4 or 5; default 3.
  • turning: cnc: the part is turned on a lathe (its axis found), not milled.
  • tools: cnc: the end mill diameters available, in mm, comma separated (3,6,10); default none: a corner is held to the smallest tool that can exist (0.05 mm across, cad's own floor) and to how deep a tool of its size reaches; a radius of 1.25 mm or more (a 2.5 mm end mill's) is recommended.
  • stock: cnc: the stock's size in mm (100x60x25); default the part's box.
  • thickness: sheet: the stock's thickness in mm; default measured.
  • k_factor: sheet: the neutral axis's place in the thickness, for the flat pattern (the shop's bend table's); default a K-factor chart's, by the material and each bend's radius.
  • bend_radius: sheet: the shop's inside bend radius in mm, compared with the part's.
  • kerf: sheet: the cutting kerf in mm, for small features.
  • sheet_size: sheet: the shop's largest sheet in mm (1219x2438); default a standard 5 x 10 ft sheet (3048x1524), assumed.
  • pull: molding: the pull direction, an axis (z, -y) or x,y,z components; default z.
  • wall_limit: molding: faces at or above this many degrees from the pull are not walls; default 45.
  • zero_tol: molding: draft under this many degrees is zero draft; default 0.05.
  • cavities: molding: cavities in the mold, for the clamp force; default 1.
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: molding the pulls (x, y, z and the part's principal axes), printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.step.interferencefunction

cad.step.interference(
    source: Any,
    *,
    poses: Any = (),
    fits: Any = (),
    min_volume: float | None = None,
) -> Any

The command cad step interference: which parts share volume, as built and at each pose asked (--pose: a mechanism state, a configuration sequence at a time, or joint values): a pair with air between its parts ruled out on their meshes, every other measured exactly on the parts' own solids, the fits named on purpose (--fit A B) listed apart, and each pair it could not measure said.

cad.step.interference: which parts of the document share volume.

Every pair of parts whose boxes meet is answered, as built and at each pose asked, in one of the engine's checks processes: a pair whose meshes show air between the two parts shares nothing, and every other is measured exactly by the kernel on the parts' own solids. Each answer is kept in the engine's cache by the two parts' geometries and how one stands to the other, so a document edited is measured again only where a part that changed is one of the two, and a check stopped by its time goes on from what it had measured. Nothing is built or written, and the same check of an unchanged document is answered at once from the result the engine keeps: one that answered every pair.

poses: the poses to check at beside as built, each a pose as every command takes one: a mechanism state's name, a configuration sequence at a time of it ("walk@0.6"), or a {joint or coupling: value} table. The check takes the poses it is given and chooses none: every state, or a sequence every tenth of a second, is the caller's list. fits: the pairs meant to share volume (a press-fit pin, a bearing in its bore), each two refs or globs (("pin", "base")): listed apart, and no overlap. min_volume: a shared volume at or below it (mm3) is none; 0.001 by default, the rounding along a face where two parts touch.

Returns a cad.results.CheckResult: ok when no two parts share volume and every pair was answered; failed with an overlapping_parts finding for each pair that does (location and refs the two occurrences' paths, value the most volume shared, mm3); not_checked (reason: unmeasured) when none was found but a pair could not be measured — past its time, its process gone, the kernel's refusal — which is never a pass: asked again, the check goes on from what it measured. measurements holds the poses, the pairs counted (pairs: apart, kept, measured) and every row (overlaps, fits, unmeasured: each between its two parts, with every pose it holds at). An option the document does not answer — a pose it has no state or sequence for, a fit that names nothing — is refused by name (a ValueError); a document that does not read is not_checked by its reason; a check that did not complete raises as cad.engine.api.check says.

cad.step.solvefunction

cad.step.solve(
    source: Path,
    *,
    study: str | dict | None = None,
    out: Path | None = None,
    occurrence: str | None = None,
    deck: bool = False,
    verbose: bool = False,
) -> FeaResult

The command cad step solve: a linear static stress study of a part or a bonded assembly: with --study and --out DIR, the solve, its results written into DIR (result.json, result.glb, result.vtu, stress.png, displacement.png), each part's peak stress and safety factor, and a part that yields failing it; with no --study, the parts, the pairs that touch and a part's faces a study names.

A linear static stress study of a part or an assembly bonded where its parts touch.

With no study it lists what a study names, writing nothing: the document's parts, the pairs that touch (bonded by default) and one part's faces by ref with area, centre and a hint (plane, normal -Z, largest). With a study and --out it meshes (netgen), solves (CalculiX, from cad[calculix]; CAD_CCX names another) and writes its results into the folder --out names: result.json (every number, as --json prints it), result.glb (the deformed surface coloured by stress, any viewer opens it), result.vtu (the volume's fields, for meshio, PyVista or ParaView), stress.png and displacement.png (where a still can be drawn). Each part's peak stress and safety factor against its own material's yield are in the result. A part that yields or misses a check fails it, its results written all the same; a study whose answer would be wrong (a part nothing holds, a load no face takes) is refused. --json carries every number.

  • source: the part or the assembly: a .step or .xbf, or a model's document id the engine holds (cad model solve), or the handle its call returns.
  • study: the study: a JSON file path, inline JSON, or (a library caller) a dict: the fixed faces, the loads (forces, pressures, gravity, acceleration), a material where the model has none, an assembly's parts and connections and the checks to judge. Without it, the setup.
  • out: the folder a solve writes its results into, made when missing; a study's alone.
  • occurrence: the part whose faces the setup lists, by its name or ref, where the document holds several.
  • deck: also write ccx.inp, the input CalculiX solved (the finer solve's when there were two); a study's alone.
  • verbose: say every progress line and the timings on stderr. Without it a long solve still says how far it has got about every 10 s.

cad.step.rangesfunction

cad.step.ranges(
    source: Path,
    *,
    step: float = 1.0,
    clearance: float = 0.3,
    joint: tuple[str, ...] = (),
    verbose: bool = False,
) -> CheckResult

The command cad step ranges: each joint's stops found from the geometry: the joint turned or slid alone, a step at a time each way, until its parts meet another part; the stops and which parts meet, nothing written.

Each joint's stops, found from the geometry: where its parts first meet another part.

Each joint a person moves is turned (or slid) alone from the as-built pose, the joints that follow it with it and every other as built, a step at a time each way: a turn a full turn each way, a slide the document's extent. Its stop each way is where its child link meets its parent link (each with what is fixed to it): a stop whatever the other joints do, what its range declares. Where anything it moves meets another link first, in the pose the others stand in, that clash is said beside the stop. Two parts meet where they come within the clearance and within half their gap as built (less the 0.3 mm the surfaces are sampled to), or where their contact grows by about 15 mm^2 on a surface that stops the motion: parts touching already as built (a horn on its servo) meet only when their contact grows there or one is pushed into the other (a part resting on its parent, turned into it, stops where it lies), parts near as built (apart, within the clearance) only where their gap halves, and each joint's finding names them with their gap as built and at each stop. A pair touching as built on a surface about the joint's axis (a plate bolted to a motor's output, the output drawn as one solid with the motor's case) turns on it: neither that face nor what of the output lies within its reach (a boss, a pin, a bolt's seat) stops the joint, and the finding says the pair (turns on). A clash (anything the joint moves meeting another link, the other joints as built) belongs to the drawn pose, which a simulator's contacts hold: the range is the stop. Parts drawn one inside the other (overlapping as built, a vendor's simplified parts sunk into each other) meet only where one is pushed deeper into the other than drawn, by 0.6 mm more: each joint's finding names them with the volume they share and how deep, and a stop they make lies past the true one by up to about that depth. A larger clearance only narrows a range. Each joint's finding says its stops in degrees or millimetres around the as-built pose (and in its own values where that is not zero) and which two parts meet past each, every part tested against every other on its own surface. The model is not changed: adopt the numbers into its joints' ranges. --json carries every number.

  • source: the document: a .step or .xbf, or a model's document id the engine holds (cad model ranges), or the handle its call returns.
  • step: the sweep's step: degrees for a turning joint, millimetres for a sliding one; default 1.
  • clearance: how near two parts' surfaces come before they count as touching, in millimetres; default 0.3, the least (where they all but touch): a larger one stops each joint where its parts first come that near.
  • joint: sweep this joint alone (repeat it for several); default every joint a person moves. A name the document has no such joint by is refused, naming its joints.
  • verbose: say on stderr each step as it starts (reading the document, sampling its surfaces, each joint) and each joint's stops as it ends (a joint or a sampling that takes long is said either way).

cad.stlobject

The STL document type, a binary STL mesh (cad.registry).

@stl("arm.stl") declares a model's STL file; stl.read(path) reads one into a model; its operations (stl.export(source, *destinations), ...) are the cad stl <operation> commands'. stl.dfm(source) measures it for 3D printing (molding, CNC and sheet are judged on exact geometry), with the trimesh integration (cad._internal.manufacturing). Everything loads on first use: import cad.stl imports no CAD kernel (cad._internal.document_type).

@cad.stldecorator

@cad.stl(
    out: Any,
    *,
    name: str | None = None,
    tolerance: float | None = None,
    angle: float | None = None,
) -> Any

Declare an explicit output: @stl(out='path.stl'), optionally named within the script folder by name=. The output path is required; decoration builds nothing. tolerance= and angle= mesh it to within an absolute tolerance in mm and an angle in degrees, as cad xbf export --tolerance and --angle do.

cad.stl.readfunction

cad.stl.read(path: Any) -> Mesh

A mesh file (MESH_SUFFIXES: an .stl) as data, never a shape (Mesh: its vertices, triangles and name, and bounding_box()): what a model sizes or places B-rep by. In a build the read is the model's own, keyed by the file's bytes as read_step's is (one of the closure's inputs): a later build's read of the same bytes is this object, and a changed file runs the body that reads it. A file a model of the build writes is refused.

cad.stl.exportfunction

cad.stl.export(
    source: Any,
    *destinations: Any,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad stl export: write the mesh to the other mesh kinds (.glb, .stl, .3mf).

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.stl.snapshotfunction

cad.stl.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad stl snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.stl.dfmfunction

cad.stl.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] = 'printing',
    material: str | None = None,
    units: Literal['mm', 'cm', 'm', 'in', 'ft'] | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad stl dfm: check it can be 3D printed (--process printing), measured as a mesh and judged against general, cited rules.

Check a mesh for 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A mesh (STL, 3MF, GLB) is measured as triangles for 3D printing, each finding at x, y, z; CNC machining and sheet metal need the exact radii, axes and thicknesses a mesh does not hold, and injection molding's draft, undercuts and walls are judged on exact geometry: check the part's STEP or model for them. The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .stl file to check.
  • process: printing, the one process a mesh is checked for (the default); cnc, sheet and molding are judged on exact geometry: check the part's STEP or model for them.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • units: the file's length units (mm, cm, m, in, ft): an STL's (default mm), or a DXF's (default the ones it declares; needed where it declares none, as an R12 file).
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.glbobject

The GLB document type, a binary glTF scene (cad.registry).

@glb("arm.glb") declares a model's GLB file; its operations (glb.export(source, *destinations), ...) are the cad glb <operation> commands'. glb.dfm(source) measures it for 3D printing (molding, CNC and sheet are judged on exact geometry), with the trimesh integration (cad._internal.manufacturing). Everything loads on first use: import cad.glb imports no CAD kernel (cad._internal.document_type).

@cad.glbdecorator

@cad.glb(
    out: Any,
    *,
    name: str | None = None,
    tolerance: float | None = None,
    angle: float | None = None,
) -> Any

Declare an explicit output: @glb(out='path.glb'), optionally named within the script folder by name=. The output path is required; decoration builds nothing. tolerance= and angle= mesh it to within an absolute tolerance in mm and an angle in degrees, as cad xbf export --tolerance and --angle do.

cad.glb.exportfunction

cad.glb.export(
    source: Any,
    *destinations: Any,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad glb export: write the mesh to the other mesh kinds (.glb, .stl, .3mf).

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.glb.snapshotfunction

cad.glb.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad glb snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.glb.inspectfunction

cad.glb.inspect(
    source: Any,
    ref: str | None = None,
    *,
    query: str | None = None,
    progress: Any = None,
) -> Facts | list[Facts]

The command cad glb inspect: its nodes, meshes and animations.

What a ref names in a document (refs: hand/finger.2/face 7, base/f:..., a copied /abs/kit.xbf#... line) and what made it. An element answers what the kernel measures of it — its points placed where its occurrence stands, in the document's frame — with its canonical ref, its occurrence's path and, of a model's document, made_by (a file names no model); a part or an assembly its volume and its mass: each part's volume times its material's density, summed (cli.weighed), its world bounds and a part's placement (_placed). One answer per selector (a list for several). Without ref, the build closure the xbf holds (previous): its engine, libraries, source, modules, inputs and key, read from the file alone. A ref that names nothing, or several things, is refused by name (refs.RefError). No query builds a missing model or writes its declared outputs. query="build" returns file metadata/closure or live build metadata; query="geometry" requires a ref, and query="closure" accepts none. query="summary" (cad xbf inspect DOC with no ref) is {"summary", "closure"}: what the document holds at a glance (_summary), and its closure, as the engine holds it; of a GLB, {"mesh"}: its nodes, meshes and animations, from its JSON alone (_mesh). query="structure" is the summary without bounds, volume or mass and requests no measurements. No form meshes anything. A part's volume and box are cached by geometry key and measured in batches. The summary's measurement goes, frame by frame, to progress (progress.py: inspect-measure, measure, counted as the engine tells each part's facts in), as export takes it — by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.glb.dfmfunction

cad.glb.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] = 'printing',
    material: str | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad glb dfm: check it can be 3D printed (--process printing), measured as a mesh and judged against general, cited rules.

Check a mesh for 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A mesh (STL, 3MF, GLB) is measured as triangles for 3D printing, each finding at x, y, z; CNC machining and sheet metal need the exact radii, axes and thicknesses a mesh does not hold, and injection molding's draft, undercuts and walls are judged on exact geometry: check the part's STEP or model for them. The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .glb file to check.
  • process: printing, the one process a mesh is checked for (the default); cnc, sheet and molding are judged on exact geometry: check the part's STEP or model for them.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.threemfobject

The 3MF document type, a 3D Manufacturing Format package (cad.registry).

@threemf("arm.3mf") declares a model's 3MF file; its operations (threemf.export(source, *destinations), ...) are the cad threemf <operation> commands'. threemf.dfm(source) measures it for 3D printing (molding, CNC and sheet are judged on exact geometry), with the trimesh integration (cad._internal.manufacturing). Everything loads on first use: import cad.threemf imports no CAD kernel (cad._internal.document_type).

@cad.threemfdecorator

@cad.threemf(
    out: Any,
    *,
    name: str | None = None,
    tolerance: float | None = None,
    angle: float | None = None,
) -> Any

Declare an explicit output: @threemf(out='path.3mf'), optionally named within the script folder by name=. The output path is required; decoration builds nothing. tolerance= and angle= mesh it to within an absolute tolerance in mm and an angle in degrees, as cad xbf export --tolerance and --angle do.

cad.threemf.exportfunction

cad.threemf.export(
    source: Any,
    *destinations: Any,
    log: Callable[[str], None] | None = None,
    daemon: bool = True,
    progress: Callable[[dict], None] | None = None,
) -> list[Written]

The command cad threemf export: write the mesh to the other mesh kinds (.glb, .stl, .3mf).

Write a document to each destination, its kind from its suffix (.xbf, .step, .glb, .stl, .3mf, .dxf of a planar document, and .xml or .mjcf: an MJCF, the document's robot description as MuJoCo reads one, its meshes in an assets folder beside it, export/mjcf.py; .urdf: the same description as ROS reads one, its meshes in a meshes folder beside it, export/urdf.py): the document of an .xbf, of a .step read into one, of a handle (Document) or a document id (the one the engine holds, never built), or of a Model (called first, as this program's own call of it builds it); or a mesh file (.glb, .stl, .3mf) to the other two mesh kinds, each file holding what its format carries, with no CAD kernel loaded (a mesh has no B-rep: no xbf, STEP, DXF, MJCF or URDF is made from one). Several destinations read the document once. The file holds what the code built: no option selects a part or a state (README, the law of options). daemon=False does it in this process, cold. A GLB carries every configuration sequence the document defines, as a clip. A GLB, an STL and a 3MF are meshed at the engine's one tolerance, the viewer's (a quarter per cent of each part and 28.5 degrees), unless tolerance gives an absolute ceiling in millimetres (at least export.MIN_TOLERANCE), for a print whose fits are finer or a picture whose curves are, or angle a ceiling in degrees (export.MIN_ANGLE to export.MAX_ANGLE): each part is then meshed again at the finer of each for these files, and each file says it; every destination is then a GLB, an STL or a 3MF. An MJCF and a URDF are the robot description at the as-built state, unless zero names a mechanism state to take every joint's zero at (describe's The zero: the bodies posed there, each joint's value there its zero, its limits and the other states around it); every destination is then an MJCF or a URDF. Each robot file's Written.robot says what it holds, and the program's own call says it on stderr after the file's line (said.robot). A call the program's own code makes (python exports.py) says each file, as cad <type> export does. Where the export is goes, frame by frame, to progress (progress.py: its read of a file source, each destination's write), as _built takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.threemf.snapshotfunction

cad.threemf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad threemf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.threemf.dfmfunction

cad.threemf.dfm(
    source: Path,
    *,
    process: Literal['cnc', 'sheet', 'molding', 'printing'] = 'printing',
    material: str | None = None,
    technology: Literal['fdm', 'sls', 'sla', 'mjf', 'pbf'] | None = None,
    build_volume: str | None = None,
    angle_limit: float | None = None,
    samples: int | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: str | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> CheckResult

The command cad threemf dfm: check it can be 3D printed (--process printing), measured as a mesh and judged against general, cited rules.

Check a mesh for 3D printing. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

A mesh (STL, 3MF, GLB) is measured as triangles for 3D printing, each finding at x, y, z; CNC machining and sheet metal need the exact radii, axes and thicknesses a mesh does not hold, and injection molding's draft, undercuts and walls are judged on exact geometry: check the part's STEP or model for them. The measurements are facts; the verdicts are general rules, each from a published design guide and no shop's limit, each finding coded by its rule, with the limit, the source and what to change. A rule's feasibility limit broken is an error; a recommendation is a warning. For a named shop, compare the measurements with its own published limits. --json carries every measurement, every rule's outcome and each verdict as data (value, limit, unit). The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .3mf file to check.
  • process: printing, the one process a mesh is checked for (the default); cnc, sheet and molding are judged on exact geometry: check the part's STEP or model for them.
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • technology: printing: fdm, sls, sla, mjf or pbf (metal powder bed); default fdm.
  • build_volume: printing: the printer's build volume in mm (256x256x256); default a typical machine of the technology's, assumed.
  • angle_limit: printing: down-facing faces under this many degrees from horizontal need support; default the technology's.
  • samples: printing: rays cast for the wall-thickness field on a mesh; default 2000.
  • layer_height: printing: the layer height in mm, for stair-stepping; default the technology's.
  • nozzle: printing: fdm's nozzle diameter in mm; default 0.4.
  • printer: printing: a file of the printer's settings — a 3MF OrcaSlicer or Bambu Studio saved, or a complete machine preset JSON — for its build volume and nozzle; --build-volume and --nozzle win.
  • candidates: rank the candidates instead: printing the orientations.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.dxfobject

The DXF document type, a 2D drawing of a planar document (cad.registry).

@dxf("plate.dxf") declares a model's DXF file; its operations (dxf.snapshot(source, out), ...) are the cad dxf <operation> commands'. Everything loads on first use: import cad.dxf imports no CAD kernel (cad._internal.document_type).

@cad.dxfdecorator

@cad.dxf(out: Any, *, name: str | None = None) -> Any

Declare an explicit output: @dxf(out='path.dxf'), optionally named within the script folder by name=. The output path is required; decoration builds nothing.

cad.dxf.snapshotfunction

cad.dxf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad dxf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.dxf.dfmfunction

cad.dxf.dfm(
    source: Path,
    *,
    process: Literal['sheet'] = 'sheet',
    material: str | None = None,
    units: Literal['mm', 'cm', 'm', 'in', 'ft'] | None = None,
    thickness: float | None = None,
    k_factor: float | None = None,
    bend_radius: float | None = None,
    kerf: float | None = None,
    sheet_size: str | None = None,
    strict: bool = False,
) -> CheckResult

The command cad dxf dfm: check it as a sheet's cut file (--process sheet): closed contours, nothing cut twice, features against the kerf and the thickness, the sheet's size.

Check a sheet's cut file (a DXF) for laser, waterjet or router cutting: the sheet process. Exit 0: OK. Exit 1: FAILED, a finding is an error (with --strict, a warning too). Exit 3: NOT CHECKED, something was not judged: never a pass. Exit 2: the command line's mistake.

Its units, closed contours on the cut layers, curves cut twice (overlapping, crossing, zero-area), annotation on a cut layer, curves drawn as short lines, and holes, slots, webs and spacing against the kerf and the thickness, judged against general rules, each cited; each finding at a layer and an entity handle. A rule's feasibility limit broken is an error, a recommendation a warning; for a named shop, compare the measurements with its own published limits. --json carries every measurement and every rule's outcome. The last line and the exit status are the check's state. OK, exit 0: everything was measured and no finding is an error. FAILED, exit 1: a finding is an error (with --strict, a warning too): the part cannot be made by this process as drawn. NOT CHECKED, exit 3: the check did not judge what it was asked to — a source that does not read or holds no solid, a family that could not be measured, an engine that stopped — which is no verdict and never a pass. Exit 2: the command line's mistake.

  • source: the .dxf cut file to check.
  • process: sheet, the one process a DXF is checked for (the default).
  • material: the part's material (aluminum, steel, stainless, abs, pc, nylon, ...): picks the material's limits; default the material the part declares (part.material = metals.aluminum()), when every part agrees.
  • units: the file's length units (mm, cm, m, in, ft): an STL's (default mm), or a DXF's (default the ones it declares; needed where it declares none, as an R12 file).
  • thickness: sheet: the stock's thickness in mm; default measured.
  • k_factor: sheet: the neutral axis's place in the thickness, for the flat pattern (the shop's bend table's); default a K-factor chart's, by the material and each bend's radius.
  • bend_radius: sheet: the shop's inside bend radius in mm, compared with the part's.
  • kerf: sheet: the cutting kerf in mm, for small features.
  • sheet_size: sheet: the shop's largest sheet in mm (1219x2438); default a standard 5 x 10 ft sheet (3048x1524), assumed.
  • strict: a warning fails the check too (exit 1): a gate that takes no recommendation broken.

cad.urdfobject

The URDF document type (cad.registry), a robot description.

It has no decorator: a robot description is an AUTHORED file, not a document a model makes. urdf.validate is cad urdf validate; urdf.snapshot is cad urdf snapshot (cad.engine.snapshot).

cad urdf validate is an ADAPTER over validate rather than a generated mirror: --packages NAME=PATH is repeatable, and a repeatable key/value map is outside the annotation set a parser can be derived from. It still answers with the same CheckResult every validation does.

cad.urdf.snapshotfunction

cad.urdf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad urdf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.urdf.validatefunction

cad.urdf.validate(
    path: Path,
    *,
    strict: bool = False,
    packages: dict[str, Path] | None = None,
    verbose: bool = False,
) -> CheckResult

The command cad urdf validate: check it for conformance: structure, joints, inertials, mesh references.

Check one URDF robot description for conformance.

Collects every finding in one pass — structure, joints, inertials, mesh references — rather than stopping at the first. Errors always block; under strict warnings do too.

  • path: the .urdf file to check.
  • strict: treat warnings as blocking.
  • packages: package://NAME/... mesh URI roots, name -> directory.
  • verbose: narrate the target on stderr.

cad.srdfobject

The SRDF document type (cad.registry), a MoveIt2 semantic description.

No decorator, for the reason cad.urdf gives. cad srdf validate is a generated MIRROR of validate; cad srdf snapshot draws one.

An SRDF is only meaningful against its URDF. urdf= (--urdf) names it; without it, the paired URDF is found from the SRDF's robot name and directory, and a missing pairing is itself a finding.

cad.srdf.snapshotfunction

cad.srdf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad srdf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.srdf.validatefunction

cad.srdf.validate(
    path: Path,
    *,
    strict: bool = False,
    urdf: Path | None = None,
    verbose: bool = False,
) -> CheckResult

The command cad srdf validate: check it against its URDF: every name, chain, state and disabled pair.

Check one SRDF against its paired URDF.

Cross-validates every name, chain, state and disabled pair the SRDF declares against the robot the URDF actually describes. Errors always block; under strict warnings do too.

  • path: the .srdf file to check.
  • strict: treat warnings as blocking.
  • urdf: the URDF to check it against; found from its robot name and folder without it.
  • verbose: narrate the target on stderr.

cad.sdfobject

The SDF document type (cad.registry), an SDFormat world or model.

No decorator, for the reason cad.urdf gives: a world or model description is authored, not generated. cad sdf validate is a generated MIRROR of validate; cad sdf snapshot draws one (cad.engine.snapshot). GZ_CHECK_MODES is the vocabulary of its gz_check option.

cad.sdf.snapshotfunction

cad.sdf.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad sdf snapshot: draw it as the viewer does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.sdf.validatefunction

cad.sdf.validate(
    path: Path,
    *,
    strict: bool = False,
    gz_check: GzCheck = 'auto',
    gz_remote: bool = False,
    verbose: bool = False,
) -> CheckResult

The command cad sdf validate: check it for conformance, and with gz sdf --check where it is installed.

Check one SDFormat world or model for conformance.

The bundled checks are dependency-light and catch common structural errors; they are not a replacement for libsdformat or a target simulator. Errors always block; under strict warnings do too.

  • path: the .sdf file to check.
  • strict: treat warnings as blocking.
  • gz_check: run gz sdf --check as external validation — auto (when the tool is installed), required (fail without it), or never.
  • gz_remote: let gz sdf --check resolve the document's remote <uri> references (http, https, fuel). Off by default: gz does not run on a document that names one, so validating a file never fetches from a host the file names.
  • verbose: narrate the target on stderr.

cad.kicad_pcbobject

The KiCad PCB document type (cad.registry), a saved KiCad board.

A .kicad_pcb is an AUTHORED file, edited in KiCad, as text or in place by edit, never a document a model makes: the type has no decorator. Its functions take paths and our own board objects, so they are the type's, not the kicad integration's (the signature rule):

  • read parses the file and the .kicad_pro beside it with the standard library (cad.engine.formats.kicad), so a check script run with cad run imports it without the CAD kernel and without KiCad; inside is the even-odd test a check measures a pour or an outline with, in the same millimetres.
  • inspect is the board in one look as plain data — its format, thickness, size, layers, parts and nets — what cad kicad_pcb inspect prints; snapshot draws it flat, as cad kicad_pcb snapshot does.
  • edit opens the saved board in KiCad's IPC API for a with block, the kicad integration's (cad.kicad._session): the block gets KiPy's open board, which is saved at its end when it was changed (made by KiCad when the file is not there yet) and not at all when the block raises.
  • drc (KiCad's design rule check) and export (its fabrication, assembly and 3D outputs) run KiCad's own kicad-cli, the kicad integration's (kicode, cad[kicad]): they are the commands cad kicad_pcb drc and cad kicad_pcb export, one to one. Where this environment lacks kicode, the command runs them in the environment of cad[kicad] the engine makes on first need; a function called here says to install the extra (or run the script with cad run, which does).

cad.kicad_pcb.readfunction

cad.kicad_pcb.read(path: Path | str) -> BoardView

The KiCad board at path (a .kicad_pcb; any board KiCad opens) for board references.

Everything is in KiCad's frame: millimetres, y down, as the board file holds them. Reads the file and the .kicad_pro beside it (for net classes); runs nothing.

cad.kicad_pcb.exportfunction

cad.kicad_pcb.export(board: Path | str, to: str, out: Path | str) -> ExportResult

The command cad kicad_pcb export: write its fabrication and 3D outputs with KiCad into a folder: gerbers, drill, pos, bom, step, glb, odb, ipc2581, pdf or dxf.

KiCad's to export of the saved board into the folder out (cad kicad_pcb export BOARD --to KIND -o DIR): to is one of gerbers, drill, pos, bom, step, glb, odb, ipc2581, pdf and dxf (cad.kicad._export's table says what each writes). The result says the files written and any warning. RuntimeError in KiCad's words when it fails.

cad.kicad_pcb.snapshotfunction

cad.kicad_pcb.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad kicad_pcb snapshot: draw it flat, as the viewer's board view does, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.kicad_pcb.inspectfunction

cad.kicad_pcb.inspect(path: Path | str) -> dict

The command cad kicad_pcb inspect: what the board holds: its format, thickness, size, layers, parts and nets.

What the board at path holds, as plain data: file, format, thickness, size, layers, parts, nets and counts (cad kicad_pcb inspect).

cad.kicad_pcb.drcfunction

cad.kicad_pcb.drc(board: Path) -> CheckResult

The command cad kicad_pcb drc: KiCad's design rule check: errors and unconnected items fail it, warnings are said.

Check the KiCad board BOARD with KiCad's design rule check.

Runs kicad-cli pcb drc on the saved file with every severity reported and lists each violation and unconnected item with where it is (millimetres from the board's origin). The board fails when any error-severity violation or any unconnected item exists; warnings are reported and do not fail it. The result's measurements["drc"] is every finding as KiCad reported it, each item with its uuid and position.

  • board: the .kicad_pcb to check (its .kicad_pro beside it carries the rules).

cad.kicad_pcb.editfunction

cad.kicad_pcb.edit(board: Path | str) -> AbstractContextManager[Any]

The board at board open in KiCad, for a with block: with kicad_pcb.edit("board.kicad_pcb") as b: hands the block KiPy's open board (kicode's kicode.board.Board), through kicode's headless kicad-cli api-server. At the block's end the board is saved when it was changed (KiCad's own modified state), so a block that changes nothing leaves the file byte for byte; when the block raises, nothing is saved and the exception goes on. A board not there yet is made by KiCad, with its project, and saved. A kicad_sch.edit of the same project inside the block shares its KiCad. A saved board is checked for the nets KiCad moved (it gives copper the net of a pad it overlaps): each track, via, copper shape or zone saved on another net than the block gave it, else the file had, is a warning on stderr and, after the block, one of b.net_changes (kind, id, ref, was, now, pad, joined). Needs the kicad extra (cad[kicad]; cad run gives a script that calls it the extra).

cad.kicad_pcb.insidefunction

cad.kicad_pcb.inside(point: XY, polygon: Sequence[XY]) -> bool

Even-odd: KiCad's fills are single outlines with their holes cut in by slits.

cad.kicad_schobject

The KiCad schematic document type (cad.registry), a saved KiCad schematic.

A .kicad_sch is an AUTHORED file, edited in KiCad, as text or in place by edit, never a document a model makes: the type has no decorator. A schematic is a hierarchy: its project's root sheet (the <project>.kicad_sch beside the .kicad_pro) and the sheets it places, each a file of its own. Its functions take paths and plain values, so they are the type's, not the kicad integration's (the signature rule):

  • read reads the whole hierarchy from the root, whichever of its sheets it is given, with the standard library (cad.engine.formats.kicad.schematic), so a script run with cad run imports it without the CAD kernel and without KiCad: its sheets, symbols and their pins, wires, labels and the nets they make, and resolve(ref) for a reference in the board's grammar (#U3, #U3.7, #net:VBUS) and the schematic's own (#sheet:/Power/, #wire:<uuid>).
  • inspect is the schematic in one look as plain data — its sheets, parts and nets, and what a reference names — what cad kicad_sch inspect prints; snapshot draws one sheet flat, as cad kicad_sch snapshot does.
  • edit opens the saved schematic in KiCad's IPC API for a with block, the kicad integration's (cad.kicad._session): its project's symbol libraries loaded, saved at the block's end when it was changed and not at all when the block raises.
  • erc (KiCad's electrical rules check) and export (a pdf, svgs, the netlist, a BOM) run KiCad's own kicad-cli, the kicad integration's (kicode, cad[kicad]), as the board's do: they are the commands cad kicad_sch erc and cad kicad_sch export, one to one. Where this environment lacks kicode, the command runs them in the environment of cad[kicad] the engine makes on first need; a function called here says to install the extra (or run the script with cad run, which does).

cad.kicad_sch.readfunction

cad.kicad_sch.read(path: Path | str) -> SchematicView

The KiCad schematic at path (a .kicad_sch: the root sheet or any sheet of its project's hierarchy) for references: every sheet from the project's root down, its symbols and its nets.

Everything is in KiCad's frame: millimetres, y down, on each sheet's page. Reads the sheet files alone; runs nothing.

cad.kicad_sch.exportfunction

cad.kicad_sch.export(schematic: Path | str, to: str, out: Path | str) -> ExportResult

The command cad kicad_sch export: write it with KiCad: a pdf, an svg per sheet, the netlist or a BOM, into a folder.

KiCad's to export of the saved schematic's hierarchy into the folder out (cad kicad_sch export SCHEMATIC --to KIND -o DIR): to is one of pdf (every sheet), svg (one a sheet), netlist (the one a board imports) and bom. The result says the files written. RuntimeError in KiCad's words when it fails.

cad.kicad_sch.snapshotfunction

cad.kicad_sch.snapshot(
    source: Any = None,
    out: Any = None,
    *,
    job: Any = None,
    display: Any = None,
    camera: Any = None,
    grid: bool = False,
    preview: bool = False,
    pose: Any = None,
    width: int | None = None,
    height: int | None = None,
    size_profile: str | None = None,
    daemon: bool = True,
    annotation: Any = None,
    measurements: Any = None,
    progress: Any = None,
) -> Drawn | list[Drawn]

The command cad kicad_sch snapshot: draw one sheet flat, as KiCad's schematic editor shows it, into a PNG.

Draw a document (.xbf, .step, or a document id: the one the engine holds) or a mesh file (.glb, .stl, .3mf) into out (a .png) as the viewer draws it: one picture, a Drawn. A Model is called first, as the program's own call of it builds it: the document drawn is the one the engine then holds, whether or not an xbf of it is on disk. annotation (the viewer's annotation: its file's path, its object, or the Quick Edit packet that carries it) and measurements are drawn over the model; camera="authored" draws it from the view the annotation's ink was drawn in, which the packet holds. out a folder (a path ending in a separator, or one that is there) is given a name inside it, the source's stem and the time (snapshot.picture_path). A snapshot refused or failed leaves the file at out as it was (snapshot.write_png). preview draws the viewer's Preview in place of a display mode: the model lit in a studio, in its materials, on a floor with its shadow, in perspective.

job in place of out is every picture a job names (cad <type> snapshot --job), a list of Drawn: a Quick Edit packet (the .snapshot.json the viewer writes, its path or its object), a job or a list of jobs, each job a view drawn as it was — its camera, display, hidden and isolated parts, pose, the packet's ink and dimensions — at its output settings, into each of its outputs (snapshot.job_pictures). source is then drawn in place of every job's input; a flag given overrides every job. Every request is checked before anything renders, and a picture that fails writes none of the job's, leaving every output as it was.

Where each picture is goes, frame by frame, to progress (progress.py: scene while the document is served, meshed and its scene made, draw while the frame is drawn, write as the picture is written), as export takes it: by default a bar on stderr when it is a terminal and nowhere when it is not, False nowhere, a callable each frame.

cad.kicad_sch.inspectfunction

cad.kicad_sch.inspect(path: Path | str, ref: str | None = None) -> dict

The command cad kicad_sch inspect: what the schematic holds: its sheets, parts and nets; with a ref, what that names.

What the schematic at path holds, as plain data: file, root, format, sheets, parts, nets and counts; with ref, resolved: what that reference names (cad kicad_sch inspect).

cad.kicad_sch.ercfunction

cad.kicad_sch.erc(schematic: Path) -> CheckResult

The command cad kicad_sch erc: KiCad's electrical rules check: errors fail it, warnings are said.

Check the KiCad schematic SCHEMATIC with KiCad's electrical rules check.

Runs kicad-cli sch erc on the saved hierarchy (from its project's root sheet) with every severity reported, and lists each violation with its sheet and where it is (millimetres on that sheet's page). Beside KiCad's, a warning for every pin joined some other way besides, and every wire's end, that lies on a wire's span with no junction there (pin_on_wire_span, wire_end_on_wire_span): KiCad joins them and its ERC passes. A pin whose one connection is a wire's span is KiCad's own straight run through a pin (it saves a rail drawn to each pin as one wire across them), not a finding. The schematic fails when any error-severity violation exists; warnings are reported and do not fail it.

  • schematic: the .kicad_sch to check (any sheet of its project: the check reads the whole hierarchy).

cad.kicad_sch.editfunction

cad.kicad_sch.edit(schematic: Path | str) -> AbstractContextManager[Any]

The schematic at schematic (its project's root sheet, or any sheet) open in KiCad, for a with block: with kicad_sch.edit("design.kicad_sch") as s: hands the block KiPy's open schematic (kicode's kicode.schematic.Schematic), through kicode's headless kicad-cli api-server, its project's symbol libraries (its own sym-lib-table) loaded first; a placement from a library the project does not list is refused in one line naming it. At the block's end the schematic is saved when it was changed, so a block that changes nothing leaves the file byte for byte; when the block raises, nothing is saved and the exception goes on. A schematic not there yet is made by KiCad, with its project, and saved. A kicad_pcb.edit of the same project inside the block shares its KiCad. Needs the kicad extra (cad[kicad]; cad run gives a script that calls it the extra).

Integrations

An integration's module holds the helpers that take or answer its tool's own objects. Each loads on first use, and a script whose environment lacks the tool is told which extra brings it.

cad.build123dmodule

The build123d integration — our helpers that take build123d's objects.

build123d (and the OCCT kernel under it, OCP) is the integration model code builds with. Its extra is cad[build123d]; its code runs in the process that calls it. This namespace holds only what WE define for it, never build123d itself (import build123d as bd stays build123d's): the producers that make the document types from a build123d shape (_producers, registered in cad.registry), and the helpers a model calls with build123d objects:

  • memo: a function worth replaying on a later build (the engine's Memo functions);
  • paint(shape, faces, material): a material or colour on some faces;
  • what a part declares for a robot description, each a fact of the machine: frame(part, name, location), a named frame in its own frame (a robot description's sites), body(part, name=), a body of its own fixed to its link, limits(assembly, joint, effort=, velocity=), a joint's drive limits, mass(shape, grams), what a part or an assembly weighs in all, point_mass(part, grams, at, name=, inertia=), a lump its solids leave out, free(shape), a base not bolted to the world, and link(shape, name), the name of the link its parts make;
  • the mechanism, as ISO 10303-242 (AP242) names its entities: mechanism_state (mechanism_state_representation), configuration_sequence (interpolated_configuration_sequence), gear_pair, rack_and_pinion_pair, screw_pair, and posed(assembly, state), a copy of the assembly at a state;
  • animation(assembly, name, duration=): a glTF animation, baked into each GLB the model declares;
  • measurements of native geometry: closest_points, overlap_volume, is_sound, topology_errors, boundary_edges, self_intersections, mass_properties and their result types;
  • flat patterns, exact 2D geometry from a solid's planar faces: flat_pattern, planar_faces, flatten_face, flatten_faces, union_faces, offset_profile;
  • leaves(tree): every leaf of a tree (step.read's, xbf.read's, a model's .shape) placed where it stands, out of the tree, on the same B-rep: what located gives without copying the tree;
  • the manufacturing check of exact geometry, a CheckResult with its findings at refs (plate/face 7): dfm(shape, process=...) — what cad.step.dfm and cad.xbf.dfm run on a file's or a document's B-rep (_dfm_check; the measurements _dfm_brep and _dfm_<process>) — with cnc, sheet_metal, molding and printing its four processes by name; and unfold(shape, k_factor=), a bent sheet's flat pattern, its bends unrolled by their bend allowance;
  • materials, a submodule: named looks for what bd_materials' catalogue lacks (solder mask, ENIG, moulding compound, anodized, powder coat, ...), each a native bd_materials.FinishedMaterial.

Every name loads on first use: import cad.build123d imports no CAD kernel.

cad.build123d.ClosestPointsclass

class cad.build123d.ClosestPoints(distance: float, point_a: Vector, point_b: Vector)

cad.build123d.GeometryErrorclass

class cad.build123d.GeometryError(RuntimeError)

The kernel could not establish the requested geometric result.

cad.build123d.GeometryIssueclass

class cad.build123d.GeometryIssue(code: str, entities: tuple[Shape, ...])

cad.build123d.MassPropertiesclass

class cad.build123d.MassProperties(
    volume: float,
    mass: float,
    center_of_mass: Vector,
    inertia: Matrix3,
)

cad.build123d.animationfunction

cad.build123d.animation(assembly: Any, name: str, *, duration: Any) -> Any

Name an animation of an assembly: a GLB's own choreography, duration seconds long, returned as a builder of glTF channels; its calls chain:

show = animation(car, "showcase", duration=6)
show.channel("lid", path="translation", keys=[(0, (0, 0, 0)), (1, (0, 0, 40))])
show.rotation("wheel*", axis=(0, 1, 0), turns=3, start=1, interpolation="LINEAR")
show.translation("door", by=(0, 300, 0), start=2, end=4)
show.explode("body/*", radial=True, distance=40, end=2)       # helpers, compiled to channels
show.hide("roof", at=3)                                       # a STEP scale channel to 0
show.pose(at={0: "shut", 5: {"doors": 1}})                    # the mechanism, by its FK

.channel(parts, path=, keys=, interpolation=) is glTF's channel (path translation, rotation or scale; interpolation CUBICSPLINE, LINEAR or STEP); .translation, .rotation and .scale are channels from a start to an end. Parts are named as a ref's owner names them (a label, hand/finger.2), or by a glob (wheel*). A configuration sequence is the mechanism's and the document keeps it; an animation is the GLB's: never written into the xbf, baked into every GLB the model declares when that GLB is written. Returns the builder.

cad.build123d.bodyfunction

cad.build123d.body(part: Any, name: str | None = None) -> Any

Keep part a body of its own, rigidly fixed to the link it would have merged into, named name (the part's label where None): its mass, visuals, collision and frames go with it, not into that link's. A part that is all of its link is a body already. A part's, not an assembly's. Returns part.

cad.build123d.boundary_edgesfunction

cad.build123d.boundary_edges(shell: Shell) -> tuple[Edge, ...]

Free edges of a shell; seams are not boundaries.

An empty result establishes no free edges, not full manifold validity. Geometry is neither sewn nor repaired.

cad.build123d.closest_pointsfunction

cad.build123d.closest_points(a: Shape, b: Shape) -> ClosestPoints

Minimum set distance and one minimizing pair, in the input frame.

Solid interiors count: contact, overlap and containment have distance zero. Witnesses need not be on both boundaries or unique. This is not penetration depth. Pass faces/shells to ask about their boundaries.

Its cost grows with both shapes' faces (OCCT's exact extrema): two solids of thousands of faces each (a vendor STEP's printed parts) take seconds a pair, so a hundred pairs take minutes. Compounds are measured member by member, a member whose bounding box is farther than the best distance so far skipped. Over many pairs, rule out first those whose bounding_box(optimal=False) envelopes do not meet, and measure from a point (bd.Vertex) where a point answers the question.

cad.build123d.cncfunction

cad.build123d.cnc(
    shape: Any,
    *,
    material: str | None = None,
    axes: int | None = None,
    turning: bool = False,
    tools: Any = None,
    stock: Any = None,
    strict: bool = False,
) -> Any

CNC machining's check of shape: dfm(shape, process="cnc", ...).

cad.build123d.configuration_sequencefunction

cad.build123d.configuration_sequence(
    assembly: Any,
    name: str,
    waypoints_or_fn: Any = None,
    *,
    sweep: Any = None,
    duration: Any = None,
    ease: str = 'cubic',
    **removed: Any,
) -> Any

Name a configuration sequence of an assembly's mechanism (AP242's interpolated_configuration_sequence), by joint label: waypoints [(t, pose), ...] (t in seconds from 0, pose a mechanism state's name or {joint: value}, the rest as built), sweep={joint: (from, to)} with duration, or a function t -> {joint: value} with duration. ease is cubic (eased in and out at every waypoint: AP242's synchronous interpolation) or linear. A sequence is a finite clip; a player repeats it:

configuration_sequence(arm, "cycle", [(0, "folded"), (2, "reach"), (5, "folded")])
configuration_sequence(arm, "wave", [(0, {"wrist": -30}), (1, {"wrist": 30}), (2, {"wrist": -30})])
configuration_sequence(arm, "nod", lambda t: {"elbow": 45 + 20 * math.sin(t)}, duration=6)

The document keeps the definition, never frames (a function as its samples); a GLB export bakes it into a clip of the same name, and STEP, STL and 3MF ignore it. It never moves the build: the model is as its joints connect it. Returns assembly.

cad.build123d.dfmfunction

cad.build123d.dfm(
    shape: Any,
    *,
    process: str | None = None,
    candidates: bool = False,
    strict: bool = False,
    **options: Any,
) -> Any

The manufacturing check of a live build123d shape (a part, or an assembly's every part), as cad.step.dfm checks a file: process is cnc, sheet, molding or printing — with none, the one the parts declare (part.material = metals.aluminum(process=machined())) — and the options are that process's, by the names cad.step.dfm takes (tools=[3, 6], pull="z", technology="sla"); candidates ranks molding's pulls or printing's orientations instead, and strict fails the check on a warning too. A CheckResult: its status (ok, failed, not_checked), its findings at refs (plate/face 7), each rule's verdict with its figure and its limit, and its measurements, the report. TypeError for an option no process takes.

cad.build123d.flat_patternfunction

cad.build123d.flat_pattern(
    shape: build123d.Shape,
    *,
    normal_axis: str = 'z',
    normal_sign: float = 1.0,
    coordinate_axis: str = 'z',
    coordinate: float,
    tolerance: float = 0.02,
    kerf: float = 0.0,
) -> build123d.Shape

Select, flatten, fuse, and optionally kerf-offset — the usual whole job.

The three steps are separately available above for drawings that need them apart (a multi-plane bracket flattens each flange with its own selection before one union).

cad.build123d.flatten_facefunction

cad.build123d.flatten_face(face: build123d.Face) -> build123d.Face

Lay one planar face into the XY plane, exactly.

The face is moved by the rigid transform that takes its own plane to XY — no sampling, no projection error, and every curve survives as itself. A DXF is 2D and the engine refuses geometry off the XY plane, so this (or an explicit bd.Location((0, 0, -z)) * face) is how a derived face becomes drawable.

A face whose normal points away from +Z comes back mirrored, because that is what looking at it from its own side means. Flip the source face first if you want the other handedness.

cad.build123d.flatten_facesfunction

cad.build123d.flatten_faces(faces: Iterable[build123d.Face]) -> tuple[build123d.Face, ...]

flatten_face over a selection.

cad.build123d.framefunction

cad.build123d.frame(part: Any, name: str, location: Any) -> Any

Name a frame on part: location (a build123d Location — Pos, Rot — or a Plane) in the part's own frame, the one its geometry is in before part.location. A second frame of one name replaces the first. A frame is a part's, not an assembly's: put it on the part it stands on. Returns part.

cad.build123d.freefunction

cad.build123d.free(shape: Any) -> Any

Say that shape, a part or an assembly, is not bolted to the world: the link a robot description hangs from the world that holds a part at or below it floats (MJCF's <freejoint>; a URDF's root, which floats already). On the top assembly, the robot's base. Returns shape.

cad.build123d.gear_pairfunction

cad.build123d.gear_pair(assembly: Any, name: str, **joints: Any) -> Any

A gear train of assembly's mechanism, name: revolute joints, by label, each turning by its ratio (degrees per unit of the coupling's value) and only through it — written as AP242's gear_pair couplers, from the first-named joint to each other one. At value c each joint stands at its as-built angle plus its ratio times c: c = 0 is as built, so it never moves the build. Its range is its joints' limits: the tightest interval in which each stays within its own. Its name poses wherever a joint's does: mechanism_state(..., drive=90), a configuration sequence's waypoints and sweeps, and --pose; its joints alone are not posed. A joint that is not revolute is refused when the document is made; a label names the joint in each placement of a sub-assembly placed several times. Returns assembly.

cad.build123d.is_soundfunction

cad.build123d.is_sound(shape: Shape) -> bool

The boolean kernel's argument check (BRepAlgoAPI_Check) passes the shape: BRepCheck-valid, no self-intersections, no too-small edges, and an argument type a boolean accepts. This is what a fuse or cut demands of an operand, and it can be expensive. A null or empty shape is not sound: the kernel rejects it as an argument type (BOPAlgo_BadType), a verdict, not an error. A check the kernel could not complete raises GeometryError. Closure, solid count and signed volume are separate questions; the faulty entities are self_intersections's.

cad.build123d.leavesfunction

cad.build123d.leaves(tree: Any, *, paths: bool = False) -> list[Any]

Every leaf of tree (a node with no children), in tree order, placed in the tree's frame.

Each is a new shape of the leaf's own class, label, colour and material, detached from the tree (no parent), its location the product of its ancestors' and its own: what leaf.located(world) gives, without copying the tree. It shares its B-rep with the tree's leaf, so it costs no kernel copy however large the assembly. paths=True gives (path, leaf) pairs instead, path the labels from the root to the leaf (a label never given is ""), so a leaf is found by where it is in the assembly as well as by its name.

cad.build123d.limitsfunction

cad.build123d.limits(
    assembly: Any,
    joint: str,
    *,
    effort: float | None = None,
    velocity: float | None = None,
) -> Any

Bound the drive of every revolute or linear joint labelled joint on assembly or below it: effort in N*m for a revolute joint and N for a linear one, velocity in rad/s or m/s (URDF's <limit effort velocity>, MJCF's actuatorfrcrange; MJCF bounds no speed), each positive, each None where the model gives none. A cylindrical or a ball joint, of two and three values, is refused. A second declaration for one joint replaces the first. Declare it after the joint is made: it is kept on the part that holds it. Returns assembly.

cad.build123d.link(shape: Any, name: str) -> Any

Name name the link the parts at or below shape make in a robot description, instead of its first part's label: one link, so shape's parts must all be one link's, and no other link may take the name (both refused when the robot is described). A part declared a body is named by its body declaration. A second declaration replaces the first. Returns shape.

cad.build123d.massfunction

cad.build123d.mass(shape: Any, grams: float) -> Any

Say that shape, a part or an assembly, weighs grams in all, its point masses included: its solids keep their densities' ratios and are scaled alike to make up the rest (the module's Mass, where nested declarations are). A second declaration replaces the first. Returns shape.

cad.build123d.mass_propertiesfunction

cad.build123d.mass_properties(bodies: Iterable[tuple[Solid, float]]) -> MassProperties

Add uniform-density solids, including overlapping material as supplied.

Density must be finite and positive, in mass/input-unit³. Inertia is about the combined center of mass, expressed in the input coordinate axes. For mm and kg/mm³ the outputs are mm³, kg, mm and kg·mm².

cad.build123d.materialsmodule

cad.build123d.materials: named looks for what bd_materials' catalogue lacks.

Printed circuit boards and their parts, and the common process finishes, as scalar looks that the viewer, an OCCT still and a GLB all draw (no texture maps: a part's mesh has no UVs):

from cad.build123d import materials

board.material = materials.soldermask("green")
paint(board, pads, materials.enig())
housing.material = materials.anodized("black")
bracket.material = materials.powder_coat("RAL7016", finish="satin")

Each factory returns a fresh native bd_materials.FinishedMaterial: the physics one of bd_materials' own classes (its metals' and FR-4's tables where they have them, renamed for the look; custom_metal and custom_plastic or SolidMaterial where they do not), the look a threejs_materials.PbrProperties. No class of its own, so any release that reads an xbf reads these. A color is a preset name, an sRGB hex string, a CSS name or an sRGB (r, g, b) of 0-1 floats; zinc_plated takes its passivation instead, one of four. One finish is one material, named once whichever spelling asked for it: a preset by any of its names, or by its hex, is that preset (named by its first name in the table), and any other colour is named by its sRGB hex, so two parts of one look are one row of a BOM. substrate= takes the bd_materials metal a finish is on; its physics are kept, its look replaced.

Nothing here loads before a factory is called: import cad.build123d.materials imports neither bd_materials nor threejs_materials.

cad.build123d.materials.soldermaskfunction
cad.build123d.materials.soldermask(
    color: Color = 'green',
    finish: Finish = 'glossy',
) -> FinishedMaterial

A board in solder mask over FR-4 (its physics bd_materials' FR-4): glossy a clear-coated lacquer, matte a flat one. Presets: green, black, blue, red, white, yellow, purple.

cad.build123d.materials.soldermask_greenfunction
cad.build123d.materials.soldermask_green() -> FinishedMaterial

The common board: glossy green solder mask over FR-4.

cad.build123d.materials.soldermask_matte_blackfunction
cad.build123d.materials.soldermask_matte_black() -> FinishedMaterial

Matte black solder mask over FR-4.

cad.build123d.materials.fr4function
cad.build123d.materials.fr4() -> FinishedMaterial

Bare FR-4 laminate, unmasked: a pale yellow-green glass-epoxy (a board's edge, a slot's wall).

cad.build123d.materials.silkscreenfunction
cad.build123d.materials.silkscreen(color: Color = 'white') -> FinishedMaterial

Silkscreen ink, flat and matte, painted on a board's faces. Presets: white, black, yellow. An ink has no bulk physics: its density is unknown.

cad.build123d.materials.bare_copperfunction
cad.build123d.materials.bare_copper(oxidized: bool = False) -> FinishedMaterial

Bare copper (bd_materials' C110), bright, or oxidized to a dull brown-orange.

cad.build123d.materials.enigfunction
cad.build123d.materials.enig() -> FinishedMaterial

ENIG (electroless nickel, immersion gold) on copper pads: a pale, slightly satin gold. The physics are the pad's copper; the plating is microns thick.

cad.build123d.materials.haslfunction
cad.build123d.materials.hasl(lead_free: bool = True) -> FinishedMaterial

HASL (hot-air solder levelled) tin on copper pads: bright, the lead-free alloy a little duller. The physics are the pad's copper.

cad.build123d.materials.solderfunction
cad.build123d.materials.solder() -> FinishedMaterial

Solder (SAC305, Sn-3Ag-0.5Cu): a joint, a fillet, a ball. Its own physics (custom_metal).

cad.build123d.materials.mold_compoundfunction
cad.build123d.materials.mold_compound() -> FinishedMaterial

Black epoxy moulding compound: an IC package, a moulded module. Its own physics (custom_plastic, silica-filled epoxy).

cad.build123d.materials.ceramicfunction
cad.build123d.materials.ceramic(color: Color = 'white') -> FinishedMaterial

A ceramic body: a chip capacitor's (tan), a resistor's or a substrate's (white). Physics: 96% alumina (SolidMaterial). Presets: white, tan, beige.

cad.build123d.materials.led_lensfunction
cad.build123d.materials.led_lens(
    color: Color = 'clear',
    diffused: bool = False,
) -> FinishedMaterial

An LED's lens, clear epoxy that light passes through (transmission), tinted by color; diffused a frosted one. Presets: clear, white, red, green, blue, amber, yellow. The tint is the base colour alone, which tints the light a transmissive look passes (three.js, glTF) and is the colour a look without transmission draws: an attenuation colour as well would tint it twice, the lens far darker than its colour, and more so the thicker the part.

cad.build123d.materials.connector_housingfunction
cad.build123d.materials.connector_housing(color: Color = 'black') -> FinishedMaterial

A connector's or a switch's housing: glass-filled PBT (PBT-GF30, custom_plastic), moulded satin. Presets: black, white, natural, beige, grey.

cad.build123d.materials.anodizedfunction
cad.build123d.materials.anodized(
    color: Color = 'clear',
    substrate: FinishedMaterial | None = None,
) -> FinishedMaterial

Anodized aluminium (bd_materials' 6061-T6 unless substrate): the dyed oxide over the metal, satin. Light passes the dyed oxide to the metal and back, so a dyed part reflects its surroundings in its dye's colour: drawn as a mostly metallic surface of that colour (metalness 0.7), clear (and silver) as nearly the bare metal (0.9), black as a deep dye that reflects less (0.45), each under a light clear coat, the oxide's sheen. Presets: clear, silver, black, grey, red, blue, gold, green, purple, orange.

cad.build123d.materials.anodized_blackfunction
cad.build123d.materials.anodized_black() -> FinishedMaterial

Black anodized 6061-T6.

cad.build123d.materials.powder_coatfunction
cad.build123d.materials.powder_coat(
    color: Color = 'black',
    finish: Sheen = 'satin',
    substrate: FinishedMaterial | None = None,
) -> FinishedMaterial

Powder coat over a metal (bd_materials' mild steel unless substrate): an opaque polymer skin, matte, satin or gloss. Presets: RAL9005, RAL9010, RAL9016, RAL7016, RAL7035, RAL7024, RAL3020, RAL5010, RAL1023, RAL6005, and black, white (RAL9016) and grey (RAL7016).

cad.build123d.materials.powder_coat_blackfunction
cad.build123d.materials.powder_coat_black() -> FinishedMaterial

Satin black powder coat on mild steel.

cad.build123d.materials.bead_blastedfunction
cad.build123d.materials.bead_blasted(substrate: FinishedMaterial | None = None) -> FinishedMaterial

Bead-blasted metal (bd_materials' 6061-T6 unless substrate): an even, diffuse satin in the bare metal's own colour (bd_materials' look of its family), whatever finish the substrate wore.

cad.build123d.materials.brushedfunction
cad.build123d.materials.brushed(substrate: FinishedMaterial | None = None) -> FinishedMaterial

Brushed metal (bd_materials' 304 stainless unless substrate): satin, its highlight stretched across the grain (anisotropy), the grain around the part's Z axis.

cad.build123d.materials.zinc_platedfunction
cad.build123d.materials.zinc_plated(
    passivation: str = 'clear',
    substrate: FinishedMaterial | None = None,
) -> FinishedMaterial

Zinc-plated steel (bd_materials' mild steel unless substrate), passivated clear, blue, yellow or black. Each passivation is its own chemistry, its colour, metalness and roughness together, so it takes one of those four, not a colour.

cad.build123d.materials.black_oxidefunction
cad.build123d.materials.black_oxide(
    oiled: bool = True,
    substrate: FinishedMaterial | None = None,
) -> FinishedMaterial

Black-oxide steel (bd_materials' mild steel unless substrate): a dark, faintly metallic conversion coat, oiled a little glossier.

cad.build123d.mechanism_statefunction

cad.build123d.mechanism_state(assembly: Any, name: str, **values: Any) -> Any

Name a state of an assembly's mechanism (AP242's mechanism_state_representation): mechanism_state(arm, "raised", elbow=90) sets the joint labelled elbow to 90 degrees in the state raised (a number per joint, or for a joint of several values a sequence: a cylindrical joint's angle and position, a ball joint's three angles). The joints are build123d's, placed with connect_to; the values they were connected at are the as-built state, and a joint a mechanism state does not name stays as built. The document keeps every mechanism state; the viewer offers them as presets, --pose NAME draws a snapshot at one, and a configuration sequence's waypoint may name one. A mechanism state never changes the build: every file shows the model as built. A value outside its joint's range fails the build, in one line naming the state, the joint, the value and the range; one on a bound is within it. Returns assembly.

cad.build123d.memofunction

cad.build123d.memo(function: Any = None, /, **options: Any) -> Any

Mark a function worth replaying: @memo, bare. Its arguments are keyed by value (plain values, build123d's value types, materials, shapes the engine made); it returns geometry (a shape, or a tuple, list or dict of shapes); it writes nothing outside itself. A verifying build (Model.build(verify=True)) runs every call the engine would replay and compares what it makes with what was logged.

cad.build123d.moldingfunction

cad.build123d.molding(
    shape: Any,
    *,
    material: str | None = None,
    pull: Any = None,
    wall_limit: float | None = None,
    zero_tol: float | None = None,
    cavities: int | None = None,
    candidates: bool = False,
    strict: bool = False,
) -> Any

Injection molding's check of shape: dfm(shape, process="molding", ...).

cad.build123d.offset_profilefunction

cad.build123d.offset_profile(shape: build123d.Shape, amount: float) -> build123d.Shape

Kerf / tool-radius compensation, exactly.

Positive grows the profile (cut outside the line), negative shrinks it (cut inside). The offset is OCC's, so a filleted corner offsets to a concentric arc rather than to a fan of chords — the single biggest reason this module stopped going through shapely.

cad.build123d.overlap_volumefunction

cad.build123d.overlap_volume(a: Solid | Compound, b: Solid | Compound) -> float

Intersection volume of two finite, positively oriented solids, or of compounds of them: an assembly's leaf part is often a Compound.

A compound is its solids, each placed as the compound places it, and the answer is the sum of every pair's overlap (one solid of a, one of b): solids of one compound that overlap each other count their shared region once per solid, and are never fused. Contact has zero volume. Assembly pair selection, intentional overlaps and acceptance thresholds belong to the caller. Inputs are never fused or modified; a failed boolean is an error, never a zero-volume answer.

cad.build123d.paintfunction

cad.build123d.paint(shape: Any, faces: Any, color: Any) -> Any

Colour faces of a part, or give them a material: faces (a face, or several) of shape take color — an sRGB hex string ("#e68019", "#e68019cc"), 0-255 integers (three, or four with alpha), a build123d Color, or a bd_materials.FinishedMaterial — in the document, by their ordinal in the part. The colour is the one shape.color would give the same value (colors). A face holds one paint: a colour replaces its material, a material its colour. Returns shape, whose paints the memo keys like its label.

A part's material is set as its colour is, on the shape: part.material = bd_materials.metals.mild_steel(); on an assembly, it is every part's below it that has none. Both are attributes of the object, and travel as build123d moves them: a copy, moved and located keep them. Material assignment uses build123d's native property; set an explicit colour after assigning a material to override its PBR base colour. Paint and materials are for finished parts: set them after the last operation, so an edit of one is no kernel call (the memo keys them with the shape, and a compound does not hold its children's materials in its key).

cad.build123d.planar_facesfunction

cad.build123d.planar_faces(
    shape: build123d.Shape,
    *,
    normal_axis: str,
    normal_sign: float,
    coordinate_axis: str,
    coordinate: float,
    tolerance: float = 0.02,
    min_area: float = 1e-05,
) -> tuple[build123d.Face, ...]

The planar faces of shape facing one way at one height.

This is the selection step of a flat pattern: "every upward face of the top surface", "every outward face of the left flange". Raises rather than returning nothing — an empty selection means the plane or the sign is wrong, and a drawing generated from no faces is an empty file nobody notices.

cad.build123d.point_massfunction

cad.build123d.point_mass(
    part: Any,
    grams: float,
    at: Any,
    *,
    name: str | None = None,
    inertia: tuple[float, float, float] | None = None,
) -> Any

Add grams to part at at (a build123d Location or Plane) in its own frame, the one its geometry is in before part.location, as a frame is: a lump its solids leave out. It has no inertia of its own unless inertia gives its diagonal, (ixx, iyy, izz) in kg*m^2 about the point in at's axes. name tells several apart (point1, point2 where None); a second of one name replaces the first. A part's, not an assembly's. Returns part.

cad.build123d.posedfunction

cad.build123d.posed(assembly: Any, state: Any) -> Any

assembly with every part where state puts it: a mechanism state's name, or {joint label or coupling name: value} (the values mechanism_state takes, the rest as built). The parts move by the forward kinematics the viewer and the snapshot use (link_worlds): each link's placement at the asked values over its placement as built, applied to that link's parts. An unknown state, joint or coupling, or a value out of range, is refused by name (resolve).

assembly is what the model call returned, its document's handle, or a shape. Inside a body (return posed(arm(), "folded"): a posed file is this) the result is a copy of the shape that shares its geometry and keeps the joints, couplings, mechanism states and configuration sequences, the asked values its as-built state; a value a state or a sequence gives a coupling is said again from that state (_rebase), so each names the pose it named. From a plain script (a check) the handle's document is posed where the engine holds its mechanism (posed_structure), and the answer is the tree .shape is, at that pose: placed parts, no joints. A shape a plain script read through .shape has no joints left to pose, and is refused with what to pass instead.

cad.build123d.printingfunction

cad.build123d.printing(
    shape: Any,
    *,
    material: str | None = None,
    technology: str | None = None,
    build_volume: Any = None,
    angle_limit: float | None = None,
    layer_height: float | None = None,
    nozzle: float | None = None,
    printer: Any = None,
    candidates: bool = False,
    strict: bool = False,
) -> Any

3D printing's check of shape: dfm(shape, process="printing", ...).

cad.build123d.rack_and_pinion_pairfunction

cad.build123d.rack_and_pinion_pair(assembly: Any, name: str, **joints: Any) -> Any

A rack and pinion of assembly's mechanism, name: the first-named joint, by label, on one side — a revolute joint (the pinion) or a prismatic one (the rack) — and every other joint of the other kind, each moving by its ratio (degrees or millimetres per unit of the coupling's value) and only through it; written as AP242's rack_and_pinion_pair couplers, from the first-named joint to each other one. Its value, range and naming are a gear pair's (gear_pair). A joint of the wrong kind is refused when the document is made.

The pinion may hold no part: a RevoluteJoint on the part that carries it, connected to nothing, is a virtual pinion — a reference axis where the CAD draws no gear, so two slides couple to each other through it (rack_and_pinion_pair(gripper, "grip", pinion=1, left=0.15, right=0.15), its ratios the pitch circle's millimetres per degree). The document keeps it as a revolute pair to a link of no part; a robot description writes the racks coupled to the first of them and no pinion. Give it a range at least as wide as the racks' (build123d's default is 0 to 360): it bounds the coupling. Returns assembly.

cad.build123d.screw_pairfunction

cad.build123d.screw_pair(assembly: Any, name: str, **joints: Any) -> Any

A screw of assembly's mechanism, name: one cylindrical joint, by label, given its pitch, lead=1.5 (the millimetres it travels per 360 degrees of turn, negative for a left hand) — Part 105's SCREW_PAIR, which holds the pitch and nothing else. The coupling's value is the joint's turn from as built, in degrees; its travel follows. Its range and naming are a gear pair's (gear_pair). A joint that is not cylindrical is refused when the document is made. Returns assembly.

cad.build123d.self_intersectionsfunction

cad.build123d.self_intersections(shape: Shape) -> tuple[GeometryIssue, ...]

Explicit boolean self-intersection check in the supplied placement.

This can be expensive. Codes are OCCT's BOPAlgo_SelfIntersect; affected entities are owned copies. Inconclusive/failed checks raise an exception.

cad.build123d.sheet_metalfunction

cad.build123d.sheet_metal(
    shape: Any,
    *,
    material: str | None = None,
    thickness: float | None = None,
    k_factor: float | None = None,
    bend_radius: float | None = None,
    kerf: float | None = None,
    sheet_size: Any = None,
    strict: bool = False,
) -> Any

Sheet metal's check of shape: dfm(shape, process="sheet", ...).

cad.build123d.topology_errorsfunction

cad.build123d.topology_errors(shape: Shape) -> tuple[GeometryIssue, ...]

BRepCheck topology/geometry faults, with affected owned entities.

Codes are OCCT's BRepCheck_* status names. Open shells and reversed solids can have valid topology. Closure, signed volume and expensive boolean self-intersection testing are separate questions.

cad.build123d.unfoldfunction

cad.build123d.unfold(
    shape: Any,
    *,
    thickness: float | None = None,
    k_factor: float | None = None,
    material: str | None = None,
    bend_lines: bool = False,
) -> Any

The flat pattern of a bent sheet metal part (a build123d Shape): exact 2D geometry in the XY plane, ready to return from a @dxf model.

Each flange is rotated flat about its bend and the bend replaced by a strip as wide as its bend allowance, BA = angle * (inside radius + K * thickness); holes and arcs stay exact. thickness (mm) is checked against the part's measured one; k_factor is the neutral axis's place in the thickness (the shop's, from its bend table; default Hubs's air-bending chart by material and each bend's radius). One part gives its flat Face (or a Compound of the pieces that do not join); several parts, a Compound of each one's. With bend_lines the result is a Compound of the cut outline labelled CUT and the bends' centre lines labelled BEND (an empty one for a flat plate, which has none): a DXF writes each label as its own layer. ValueError for a shape that is not one thickness of sheet.

cad.build123d.union_facesfunction

cad.build123d.union_faces(faces: Sequence[build123d.Shape]) -> build123d.Shape

Fuse coplanar XY faces into one profile, exactly.

OCC's boolean is the primary path: overlapping faces merge, shared edges disappear, holes survive as inner wires, and arcs stay arcs. Disjoint faces come back as a multi-face result, which is a perfectly good nested cut layout.

Shapely is the fallback, and only that. OCC refuses some genuinely degenerate inputs — faces that touch along a zero-width sliver, self- intersecting projections of a fold — where a tolerant polygon union still gives a usable contour. Taking that route costs curvature (the rebuilt profile is polygonal), so it is never the default and never silent.

cad.kicadmodule

The kicad integration — our code for KiCad: kicad-cli and its IPC API, both kicode's.

KiCad's command line, kicad-cli, is an external program our code runs (kind C), with a separate process; its extra, cad[kicad], is kicode, which carries that program and KiPy, the IPC API's Python client (as kicode), one KiCad nightly's build of both. A person's own KiCad is never run. What is here:

  • _program: kicad-cli found and run, by the library's one helper for external programs (cad._internal.programs): CAD_KICAD_CLI, refused unless it names a kicad-cli, then kicode's; only kicad-cli itself is ever run, headless, in private homes (kicode.environment).
  • _command: cad run kicad-cli ARGS — KiCad's own command line, the environment's (kicode's console script), headless in a private folder, its exit code kicad-cli's.
  • _session: what kicad_pcb.edit and kicad_sch.edit run, a with block — a private kicad-cli api-server on the file (KiCad makes one not there yet), one per project, which the board's and the schematic's edits share; KiPy connected to it, the open document handed over (a schematic's project symbol libraries loaded first), saved at the block's end when it was changed and not when the block raises, the server stopped and its folder removed; _drift, the board's check at the save of the nets KiCad moved onto a pad's.
  • _check: KiCad's design rule check (cad.kicad_pcb.drc, cad kicad_pcb drc).
  • _export: the board's fabrication, assembly and 3D outputs by kicad-cli (EXPORTS: gerbers, drill, pos, bom, step, glb, odb, ipc2581, pdf, dxf), which cad.kicad_pcb.export and the server's cad kicad_pcb export are written by.
  • _schematic: a schematic's electrical rules check and its outputs (EXPORTS: pdf, svg, netlist, bom) by kicad-cli, from its project's root sheet (cad.kicad_sch.erc and export, cad kicad_sch erc and export).
  • route (_route, its search in _routing): copper for the connections an agent names, in the order it names them, written into the board a kicad_pcb.edit block has open: KiPy's board in, the copper out through it, every rule the board's own; it answers a Routed.

The board readers are the document type's (cad.kicad_pcb), our own code for the file format: viewing, reading and drawing a board need no KiCad. Importing this package starts nothing and imports no kicode.

cad.kicad.Routedclass

class cad.kicad.Routed(
    connections: tuple[Any, ...],
    tracks: int,
    vias: int,
    length: float,
    seconds: float,
    warnings: tuple[str, ...] = (),
)

What a route call did: every connection it was asked for, in the order routed (connections: each its net, its two ends, routed or not and why not, the copper it added, the plan entry it came from), and the totals. ok when every one is routed. warnings: each custom rule the router does not keep (it holds where a condition only KiCad's DRC evaluates, or is of a kind the router does not route by), and a plan whose region was narrowed to fit the router's memory, said on stderr before routing too: DRC judges the rules after.

cad.kicad.Routed.okproperty
cad.kicad.Routed.ok: bool
cad.kicad.Routed.failedproperty
cad.kicad.Routed.failed: tuple[Any, ...]
cad.kicad.Routed.human_linesmethod
cad.kicad.Routed.human_lines() -> list[str]

One line per warning, one per connection, then the totals.

cad.kicad.routefunction

cad.kicad.route(
    board: Any,
    connections: Sequence[Any] | None = None,
    *,
    layers: Any = None,
    width: float | None = None,
    clearance: float | None = None,
    vias: int | None = None,
    via_cost: float | None = None,
) -> Routed

Route connections in the board an edit has open (with kicad_pcb.edit(path) as board), in the order given; see the module's doc. Each connection is a net ("/CLK", "#net:/CLK"), a pair of pads (("U1.3", "C4.1")) or a dict of either with options; the keyword options apply to every entry that does not set its own:

  • layers (required, here or in each entry): the copper layers it may use, a list, or a mapping of each to its cost per millimetre (1 where a list names it);
  • width: the track's, mm (default: the net's netclass track width);
  • clearance: what it keeps from other nets, mm (default, and least: what DRC holds the net to);
  • vias: the most vias each entry may place, all its connections together (default: no limit; 0 for none);
  • via_cost: what a via costs, in mm of track (default 2); the search settles for a path within 1.2 times the cheapest, so it trades a via for track at about that cost, not exactly.

The board's custom rules (its .kicad_dru) are kept as cad.kicad._routing.rules says: each clearance everywhere, each size a rule holds everywhere at the entry (a track's width refused outside it, the via taken up to it, a net's via count lowering the entry's via limit), a disallow or assertion refused; every other one that can bear on new copper is a warning naming the rule, on stderr (route: warning: ...) before routing.

Answers a Routed: each connection's outcome; .ok, .failed, .warnings, .human_lines(). A connection that cannot be routed is said on stderr too. ValueError for a plan or a board it cannot route by, before anything is routed (see the module's doc); TypeError for a board no edit has open.

cad.trimeshmodule

The trimesh integration — our measurements of a triangle mesh for 3D printing, taking trimesh's Trimesh (its extra, cad[trimesh]: trimesh, with rtree for its closest points, scipy for its connected bodies and networkx for filling the face a body shares with another; the rays are the library's own, in bounded memory).

Each returns the report as plain data, every figure in millimetres, degrees and square millimetres — facts, never verdicts: nothing here compares a figure against a process's limit:

  • printing(mesh): 3D printing — the mesh, its scale, overhangs, wall thickness (ray cast, per body) and an estimate of the support volume;
  • orientations(mesh): support area and build height for six axis-aligned orientations.

A family that cannot be measured leaves {"error": ...} where its facts would be, and the report says so (partial, partial_sections). The mesh is never changed: each measures a copy, scaled by units to millimetres and cleaned as a file's mesh is (_mesh: welded, its collapsed triangles and doubled slivers and zero-area debris dropped, its tessellation's cracks closed; watertightness judged per body) and put through the same gate: a mesh with no inside to measure — no triangles, a corner that is no number, more than two million triangles, a one-sided surface, a closed one of no volume — raises cad._internal.dfm.Unmeasured (its code and message the check's one finding), and what the gate repaired is in the report's mesh.

Injection molding is judged on exact geometry alone (a mesh's chords misread its draft, undercuts and walls): check the part's STEP or model. A file is measured by its document type's check — cad.stl.dfm("part.stl"), cad.xbf.dfm(model_handle, process="printing") — which answers a CheckResult whose measurements is this report and whose findings say what it shows (cad <type> dfm --process). Everything loads on first use: import cad.trimesh imports no trimesh.

cad.trimesh.orientationsfunction

cad.trimesh.orientations(
    mesh: Any,
    *,
    units: str = 'mm',
    angle_limit: float = 45.0,
) -> dict[str, Any]

printing's support area and build height for six axis-aligned orientations of mesh.

cad.trimesh.printingfunction

cad.trimesh.printing(
    mesh: Any,
    *,
    units: str = 'mm',
    samples: int = 2000,
    angle_limit: float = 45.0,
) -> dict[str, Any]

3D printing's measurements of mesh (a trimesh.Trimesh) as it stands on the plate (its lowest point): overhangs and support counted for down-facing faces under angle_limit degrees from horizontal, wall thickness from samples rays.

cad.mujocomodule

The mujoco integration — our code that calls MuJoCo, taking its objects (its extra, cad[mujoco]: mujoco-core, the compiler and the Python bindings, numpy their one dependency, and mujoco-studio, MuJoCo Studio's web viewer; no window system).

An MJCF is MuJoCo's own file and no document type: cad writes one and asks MuJoCo about one, and never reads or shows one itself. check compiles a model with MuJoCo's own compiler and answers a check's result — what MuJoCo refused or warned of, in its words, the model-health checks, what the model collides as and its contact excludes (_check; cad mujoco check FILE is its command, the integration's one operation in cad.registry). compile_model and compile_findings are the compile alone. cad run mujoco-studio --model FILE shows the person a model in Studio's web viewer (_command: the environment's own mujoco-studio).

What it does for every document: spec makes one a mujoco.MjSpec (_spec): a model call's handle, a build123d shape, a STEP or an xbf described as a robot and written as the engine's MJCF export writes it (cad.engine.export.mjcf), for a scene to attach; an MJCF path read as it is.

What it does for a MuJoCo function — a plain function that makes a robot's spec with spec, makes the simulator's choices on it in MuJoCo's own API and returns it: parts lists the spec's parts by label path, and collisions, fit and decompose find and replace one part's collision geoms by it (_parts: fit the kernel's primitive of the part's exact solid, decompose CoACD's convex hulls of its mesh), and save writes the spec as a folder that travels, by MuJoCo's own writer (_save).

Everything loads on first use: import cad.mujoco imports no mujoco. A helper called where the extra is missing says so by name (cad[mujoco]), as every integration's does.

cad.mujoco.checkfunction

cad.mujoco.check(
    path: Path,
    *,
    strict: bool = False,
    verbose: bool = False,
) -> CheckResult

Compile one MuJoCo model with MuJoCo and check it.

MuJoCo's own compiler reads the model, so what it refuses or warns of is said in its words. Then the model-health checks of MuJoCo's modelling guide run on the compiled model, and two facts are said of it: what collides as what, body by body, and each contact exclude with how its two bodies stand at rest (every geom and exclude a row of the result's measurements). Errors always block; under strict warnings do too.

  • path: the .xml or .mjcf file to check.
  • strict: treat warnings as blocking.
  • verbose: narrate the target on stderr.

cad.mujoco.collisionsfunction

cad.mujoco.collisions(spec, part)

The collision geoms (mujoco.MjsGeom) of the part part names in spec (a spec spec made): its label path, as cad model inspect prints it, a last segment enough where only one part ends in it; a list, empty for a part that collides as nothing. A label that names no part, or two, is refused by name (cad.mujoco._parts).

cad.mujoco.compile_findingsfunction

cad.mujoco.compile_findings(path, *, mode='auto')

Compile the MJCF at path with MuJoCo and answer findings (cad._internal.findings.FindingsReport): an error with MuJoCo's words for a model it refuses, a warning for each compile warning, an info saying the compile passed or was skipped (mode auto, mujoco not installed here); required without mujoco is an error naming the extra.

cad.mujoco.compile_modelfunction

cad.mujoco.compile_model(path)

The model at path compiled by MuJoCo (mujoco.MjModel), its compile warnings beside it, as (model, warnings); MuJoCo's ValueError for a model it refuses.

cad.mujoco.decomposefunction

cad.mujoco.decompose(spec, part, *, max_hulls=16, threshold=None)

Replace the collision of the part part names in spec with the convex hulls CoACD cuts its mesh into (cad[coacd]): max_hulls at most that many (None for no limit), threshold CoACD's concavity threshold, 0.01 to 1 (its 0.05 where None). Works on a spec read from an MJCF too. Its collision geoms.

cad.mujoco.fitfunction

cad.mujoco.fit(spec, part, kind)

Replace the collision of the part part names in spec with the primitive kind (box, sphere, cylinder, capsule) the kernel fits to its exact solid (cad.engine.describe.fit); refused on a spec read from an MJCF (no solids) and for a part read from a mesh. Its collision geoms.

cad.mujoco.partsfunction

cad.mujoco.parts(spec)

The label paths of every part of spec (a spec spec made), sorted: the names collisions, fit and decompose take. A spec read from an MJCF answers its colliding meshes' names (cad.mujoco._parts).

cad.mujoco.savefunction

cad.mujoco.save(spec, path)

Write spec (a mujoco.MjSpec) to path by MuJoCo's own writer, every file it names copied into assets/ beside it, a scene.xml beside it where there is none and the spec has no floor of its own (no plane geom on its world body: a scene gets none); the spec handed in is left as it was. Prints the check's warnings, what the model collides as, its contact excludes and wrote <path>; the path written (cad.mujoco._save).

cad.mujoco.specfunction

cad.mujoco.spec(thing, *, assets=None, tolerance=None, zero=None)

thing — a model call's handle, a build123d shape, a .step/.xbf path, or an MJCF path read as it is — as a mujoco.MjSpec for a scene to attach (scene.attach(spec(arm()), prefix="arm/", frame=...)). Its meshes are written where MuJoCo will read them when the scene compiles: assets, a folder relative to the working directory where the scene is saved, else a folder of the engine's cache named by what it holds (cad.mujoco._spec). tolerance meshes them to within it, in mm. zero, a mechanism state's name, takes a document's robot there, every joint's zero at that state, as an export's --zero does (an MJCF's zero is its own, and a zero is refused).

cad.coacdmodule

The coacd integration — our code that calls CoACD, the approximate convex decomposition of a triangle mesh (its extra, cad[coacd]: the coacd wheel, numpy its one dependency, MIT).

What it does for a MuJoCo function: cad.mujoco.decompose(spec, part) makes a part collide as the convex hulls CoACD cuts its mesh into, while its visual stays whole. The decomposer (_decomposer) always runs in a process of its own, started by the engine (cad.engine.hulls, which keeps the hulls in its cache by the mesh's digest and the options): CoACD's library carries a threading runtime (TBB) of its own beside the kernel's, prints from native code and can die on a mesh it cannot repair, none of which may reach the process that holds the kernel. Nothing of the tool is re-exported, and import cad.coacd imports no coacd.

cad.netgenmodule

cad's support for netgen, the mesher a stress study runs: always in a process of its own (._mesher). What the mesh means is cad._internal.fea's. Nothing of the tool is re-exported.

cad.calculixmodule

cad's support for CalculiX, the solver a stress study runs: its ccx, the cad-ccx package's (cad[calculix]), found, checked and run headless (._program; cad run ccx, ._command), and its input and printed output (._files). What the study means is cad._internal.fea's. Nothing of the tool is re-exported.

cad.blendermodule

The blender integration — a GLB loaded into Blender's scene for a render, taking and answering Blender's own objects (its extra, cad[blender]: bpy, Blender as a Python module, which has builds for Python 3.13 alone).

from cad.blender import load

model = load("scene.glb", clip="explode", fps=24)
model.root, model.box, model.clips      # the root's object, the world box in metres, each clip
model.objects["arm/head/pin_1"]         # a node's object, by the node's name
model.play("cycle")                     # another clip; model.play(None) stands still

load imports the file with Blender's own glTF importer and answers a Model: each node's object, the clips, and the box of the pose the file was written in. It sets the scene's frame rate first (fps, with render.fps_base 1), which keys the clips' seconds. It undoes what that importer gets wrong with a file that has clips: it leaves a node a clip moves at its first clip's start, so a still shows a pose the file never held, with no error; only that first clip plays, and clearing it leaves its last pose; and it keys every clip from frame 0, wherever the scene's range starts. Here every node a clip moves stands where the file places it, and a clip plays alone (Model.play), the scene's range set to its frames, 0 to its duration.

It opens any GLB, cad's or another tool's (build123d's export_gltf, KiCad's board): a node is known by its place in the file, never by the name Blender gives its object, so a node with no name, two of one name and a name Blender cuts short are each found. A skin's joints are no objects but bones, of the armature Blender makes for the skin (the skinned mesh's parent), found there by name; load places objects, never a bone.

Everything loads on first use: import cad.blender imports no bpy, and a script whose environment lacks it is told which extra brings it. Nothing of Blender's is re-exported: import bpy stays Blender's.

cad.blender.Clipclass

class cad.blender.Clip(name: str, kind: str, duration: float)

One of the GLB's animations: kind is motion (a configuration sequence) or animation (an animation()), empty for a file cad did not write; duration in seconds.

cad.blender.Modelclass

class cad.blender.Model(
    root: bpy.types.Object,
    roots: list,
    objects: dict,
    nodes: dict,
    clips: dict,
    box: tuple,
    fps: int,
    clip: str | None = None,
)

The imported model. root is the object of the scene's first root node (roots: of each, in the file's order; for a root that is a skin's joint, the objects nearest it below). objects is each node's object by the node's name (in a GLB cad wrote, its path below the root, arm/head/pin_1); a node with no name by the name Blender gave its object (Mesh_0, Node_3); a name given twice, the last. nodes is each by its index in the file, which tells two of one name apart. Both hold every node Blender made an object of: a skin's joints are bones (the module). clips by name, box the world box (low, high corners in metres) of the pose the file was written in, fps the scene's frame rate (fps_base 1), and clip the one playing.

cad.blender.Model.centerproperty
cad.blender.Model.center: Vector
cad.blender.Model.sizeproperty
cad.blender.Model.size: Vector
cad.blender.Model.playmethod
cad.blender.Model.play(name: str | None) -> None

Play the clip name (None: no clip, every part where the file places it), the scene at its frame 0. The scene's range is the clip's, frames 0 to its duration at the model's fps.

cad.blender.Model.boundsmethod
cad.blender.Model.bounds() -> tuple

The world box (low, high corners in metres) of every mesh at the scene's current frame.

cad.blender.loadfunction

cad.blender.load(path: str | Path, clip: str | None = None, fps: int = 24) -> Model

Import the GLB at path into the current scene and play clip (None: stand still). The scene's frame rate is set to fps (render.fps, with render.fps_base 1) before the import, which keys each clip's seconds at it. ValueError for a file that is no GLB, or one with no node; Blender's own RuntimeError for one its importer cannot read, once everything the import made is removed.

cad.orcaslicermodule

The orcaslicer integration — complete OrcaSlicer presets for its command line.

OrcaSlicer stores a preset as its differences from a parent (inherits), and its command line neither fills the parent's settings in nor reads compatibility conditions: given a preset as OrcaSlicer saved it, it slices with defaults, and it refuses a process whose compatible_printers does not name the printer. That is what is missing without us, and all this integration adds:

  • presets(kind, match=...) lists the presets a person can select, of one kind (machine, process or filament), from their own OrcaSlicer folders and the app's built-in profiles: cad orcaslicer presets.
  • complete(printer=..., process=..., filament=(...), out=...) writes a printer, a process and each filament complete into a folder — every parent merged in, the process and filaments naming the printer as compatible, each saved as a user preset that inherits its system preset — as printer.json, process.json and filament-N.json, ready for OrcaSlicer's --load-settings and --load-filaments: cad orcaslicer complete.

Everything else is OrcaSlicer's own: the slice is its command line, run as it is, and its app opens a model for the person. Nothing here runs OrcaSlicer, needs the engine or the CAD kernel, or reaches the network: it reads and writes JSON files, with the standard library alone, so the integration has no extra.

cad.orcaslicer.Completedclass

class cad.orcaslicer.Completed(
    printer: Path,
    process: Path,
    filaments: tuple[Path, ...],
)

The complete presets written: the printer's, the process's and each filament's file, in order.

cad.orcaslicer.Completed.human_linesmethod
cad.orcaslicer.Completed.human_lines() -> list[str]

cad.orcaslicer.Presetsclass

class cad.orcaslicer.Presets(kind: str, names: tuple[str, ...])

The selectable presets of one kind, by name, sorted.

cad.orcaslicer.Presets.human_linesmethod
cad.orcaslicer.Presets.human_lines() -> list[str]

cad.orcaslicer.completefunction

cad.orcaslicer.complete(
    *,
    printer: str,
    process: str,
    filament: tuple[str, ...] = (),
    out: Path = Path('presets'),
    profiles: tuple[str, ...] = (),
) -> Completed

Write a printer, a process and filaments complete, for OrcaSlicer's command line.

Each is merged with every parent it inherits from, the process and each filament name the printer as compatible, and each is saved as a user preset of the system preset it comes from: printer.json, process.json and filament-N.json in the folder. Where several vendors ship a preset of one name, the one that lists the printer, else the one nearest it, is taken.

  • printer: the printer (machine) preset's name, or a preset JSON file.
  • process: the process preset's name, or a preset JSON file.
  • filament: a filament preset's name or file; once per material, in the printer's filament order.
  • out: the folder the complete presets are written into.
  • profiles: another folder of OrcaSlicer presets to search first; once per folder.

cad.orcaslicer.presetsfunction

cad.orcaslicer.presets(
    kind: Literal['machine', 'process', 'filament'],
    *,
    match: str = '',
    profiles: tuple[str, ...] = (),
) -> Presets

List the OrcaSlicer presets of one kind a person can select.

They are searched in the folders given first, then the person's own OrcaSlicer presets, then the app's built-in profiles (macOS, Windows, Linux and the Flathub build's folders). OrcaSlicer 2.5 and later ships its system presets as binary caches (.opc), which are not read: where none of the kind is found and a cache is there, the listing is refused, naming the cache, rather than empty.

  • kind: machine (a printer), process or filament.
  • match: only names containing this text, in any case.
  • profiles: another folder of OrcaSlicer presets to search first; once per folder.