Gen Assembly

pc:gen-assembly

Generate a PartCAD assembly: an .assy file that composes parts (and sub-assemblies) into one product. The text after the command ($ARGUMENTS) is the assembly description. You author both the ASSY and its component parts and prove the whole thing passes pc test. There is no legacy ai assembly pipeline — this capability is new.

1. Decompose

$ARGUMENTS is the description. Break it into components and the spatial/mechanical relationships between them: which parts, how many of each, and how they attach to or move relative to one another. Clarify only load-bearing ambiguities.

2. Inventory or generate the parts

pc --no-ansi list parts          # what already exists to reuse

Reuse existing parts; generate any missing component with the /pc:gen-part flow. Each part must pass pc test on its own before you compose it.

3. Author the ASSY

Scaffold (this creates the empty file and the assemblies: entry), then write <name>.assy:

pc --no-ansi add assembly assy <name>.assy

An ASSY file is a tree of nodes under links: (reference: PartCAD "Assembly YAML" docs, docs/source/assy.rst).

Container — the top level, and any grouping node:

name: <optional>
description: <the description>
location: <optional [[x,y,z], [ax,ay,az], angle_deg]>
links:
  - <node>
  - <node>

Part node — places a part; use exactly one placement method:

# explicit placement (translation, then rotation of angle_deg about the axis):
- part: <part-in-this-package  or  //package:part>
  name: <optional instance name>
  location: [[x, y, z], [ax, ay, az], angle_deg]

# OR connect by ports (no interface mating):
- part: <...>
  connectPorts:
    with: <this part's port, if it has more than one>
    name: <target instance already in the assembly>
    to: <target port, if the target has more than one>

# OR connect by interfaces (universal mating):
- part: <...>
  connect:
    with: <this part's interface, if more than one>
    name: <target instance already in the assembly>
    to: <target interface, if more than one compatible>
    # optional disambiguation: withInstance / withPort / toInstance / toPort

location, connectPorts, and connect are mutually exclusive — pick one per node. with names the interface/port on the part being added; to names it on the part already in the assembly.

Both connectPorts and connect also take two optional sections that describe the connection rather than place it:

- part: <...>
  connect:
    name: <target instance already in the assembly>
    comment: <free form context for a human or an LLM; never parsed>
    how:
      stage: <label; consecutive nodes sharing it are connected at the same time>
      pushForceMax: <force in N, default 5>
      pushDistance: <staging distance in mm; default 1.5x the part's length along the interface Z>
      turnDirection: <cw (default) or ccw>
      turnTorqueMax: <torque in N*m, default 0>
      threadStep: <lead in mm per full turn, default 0.00>
      holdWith: <interface(s) to hold the part being added by>
      holdWithInstance: <instance(s) of holdWith>
      holdWithForceMin/Max: <force in N to hold it with, default 3/7; holdWithForce sets both>
      holdTo: <interface(s) to hold the target by>
      holdToInstance: <instance(s) of holdTo>
      holdToForceMin/Max: <force in N to hold the target with, default 3/7; holdToForce sets both>

pushDirection is not a field: it is deduced from the interfaces (an interface's +Z points into the object it belongs to, which is the way an incoming part travels) and reported with the rest.

Everything that is required to perform the assembly must be codified in how and the other fields — never only in comment, which no tool reads. The hold* fields default to the connect: section of the part or assembly definition in partcad.yaml:

parts:
  <name>:
    type: step
    connect: # (optional) what this part contributes to every connection
      hold: <interface(s) to hold it by>
      holdInstance: <instance(s) of hold>
      holdForceMin/Max: <force in N; holdForce sets both>

threadStep defaults to the thread of the interfaces being connected, declared once on the interface that introduces it:

interfaces:
  m3:
    threadStep: 0.5   # inherited by every interface that inherits m3
    selfScrew: false  # true when it cuts its own thread instead of matching one

Two connected interfaces must agree on threadStep unless one declares selfScrew. Run pc test -a <name> to check that: it fails an assembly whose instructions contradict themselves — a mismatched thread, or a *Min above its *Max — and passes one that takes every default.

Sub-assembly node — identical to a part node but with assembly: instead of part:, and it may carry its own nested links:.

Prefer connect/connectPorts when the parts define interfaces/ports; otherwise use explicit location. Work in millimeters and degrees.

Do not guess the names with:, to:, withInstance:, toInstance:, withPort: and toPort: take. Ask each part what it has, and read the exact spelling out of the log:

mkdir -p /tmp/pc-render                                  # -O needs the directory to exist
pc render -t png -O /tmp/pc-render --with-all <part>

That draws every port of the part with its name, and every interface instance with a line out to the ports that belong to it — and lists all of them in the log, under the N port(s) drawn on the projection: line, which is the list to copy from. pc info <part> reports the same names as text.

Then mark the assembly not manufacturable in partcad.yaml (it is generated, not a catalog item) so pc test passes:

assemblies:
  <name>:
    type: assy
    path: <name>.assy
    manufacturable: false

Do not add a manufacturing: section: assy is the only method an assembly has and it comes with the type. (additive/subtractive/forming/sheet_metal are ways of making a part and mean nothing here.) Marking it manufacturable instead makes pc test require that every part in it can be bought or made from a declared supplier — only do that when that is true.

4. Group what repeats into sub-assemblies

An assembly of any size repeats itself, and a flat file hides that: a reader cannot see that four of those brackets are the same bracket, PartCAD builds each one from nothing, and the instruction book walks through the same six steps four times.

So once the parts are in the right places, look at what recurs and give each recurring group a name of its own. Name them <product>/<piece> — an object whose name has a / in it is written into that sub-directory, so the pieces sit together beside the thing they belong to.

assemblies:
  gearbox/idler-stage:
    type: assy
    desc: One idler on its shaft, with the bearing either side

Three things follow from it, and they are the reason to do it rather than a tidiness argument:

• It is built once. Every further use is a cache hit, and a change inside one piece rebuilds that piece rather than the product.
• It is an object in its own right, so it can be rendered, tested and inspected alone — which matters most when the whole product is too big or too slow to render at all.
• The instruction book documents it once, and says how many to make.

Judge the split by what the design actually repeats, not by carving the model into even parts. A group that occurs once is not a piece; a group that occurs eight times is, even if it is three parts.

Check the arithmetic: the parts in each piece, multiplied by how many times the piece is used, plus whatever is left loose, has to come to what you started with. It is the cheapest test there is and it catches a piece that quietly gained or lost a part.

5. Replace the coordinates with connections

A part placed by location: is a part nothing holds up. The file says where it ended up, not what puts it there — so nothing can check it, an instruction book can only say "at (144, 9.6, 0)", and moving anything means recomputing everything downstream by hand. A part joined through its ports says the thing that is true: this feature of it meets that feature of what it sits on, and PartCAD works out the coordinates.

Convert in this order, and verify after each step (§6).

Find the pairs by where the ports are

Two ports are a joint when they are at the same point. That is the whole test, and it is the same test whatever the parts are:

• Compute every port of the part in the pose it is already in.
• Compute every port of the parts already placed.
• A pair at the same point, within a tolerance that reflects how the coordinates were written, is a joint.

Do not derive port names from a part's name or its nominal grid. A part whose name says it is 2 by 2 may carry four ports on one face and one on the other; a part with a hollow middle has ports round its rim and none inside. Naming conventions are a convenience, not a contract — ask the part where its ports are (pc info <part>, or read implements: out of its configuration) and match on position.

Grow the order; do not follow the construction order

A joint may only name a node placed before it, so the order the nodes are written in decides how many of them can be joined at all. Written in the order the thing is physically built, a whole first layer has nothing beneath it and all of it stays on coordinates.

It does not have to be written that way. A part joins to what is under it or to what is over it, and the second breaks the deadlock: place one part of the first layer, add the part above that bridges it to its neighbour, and the neighbour then joins upward into that bridge. So grow the order — take whatever can be joined to what is already down, and only when nothing can, place another part by coordinates and carry on. Break ties by the original order, so a piece that needs no help still reads the way it was written.

The first node needs no location at all

Neither coordinates nor a joint: it is the assembly's origin, and where that goes is for whatever places the assembly to decide. Saying it twice is how the two come to disagree.

That moves the assembly's frame onto that node, so whatever places the assembly has to take up the difference — by the offset the node used to sit at, turned the way the assembly is turned. An assembly whose parts are all placed against one shared grid is the exception: leaving its first node's coordinates out moves that node and nothing else.

A turn is a difference, not an orientation

When a part is joined to one that lies a different way, the joint carries the difference between the two — not how either of them lies on its own. A part turned a quarter turn, sitting on another turned the same quarter turn, is not turned relative to what it sits on and the joint needs no turn at all.

Getting this backwards is the most expensive mistake in the conversion, because the result still builds: the part lands one feature away, which looks like a near miss rather than a wrong rule.

Where a joint does need a turn, prefer a port pair that does not: parts usually meet over several features, and a pair that lies square avoids the question entirely. Take the turned pair only when it is the only one.

Let sub-assemblies join each other

A port inside a sub-assembly is the sub-assembly's own business until it says otherwise. map: is how it says otherwise — a name of its choosing against the node inside it, the interface that node implements, and the instance:

assemblies:
  gearbox/idler-stage:
    type: assy
    map:
      shaft-out: [bearing-b, //pub/std/bearing:bore, outer]

The interface is not renamed — it is a contract — but the instance name is the piece's to pick. The parent then connects to shaft-out like any other port. The map does not reach inside a sub-assembly of a sub-assembly: that one externalizes what it wants seen, and this one maps that. A boundary is crossed one object at a time, which is what keeps a piece free to be rearranged inside without breaking what connects to it.

Note that a sub-assembly is joined through a port of a part inside it, and that part may lie differently from the sub-assembly itself — in which case the joint turns the whole piece by the difference. The rule above applies unchanged; it is just easier to miss one level up.

When a part has no port where the joint is

Leave it on coordinates and say why. A joint through an interface a part has not got is not a joint, and one through a port in the wrong place is a joint that lies — it will place something silently wrong, which is worse than coordinates that are merely silent.

Then fix it where it belongs: a part missing a mating feature it really has is a gap in the package that serves the part, not something to work around in the assembly. Report it or fix it there, and the assembly gets shorter for free.

A part that is a standard part under a name of its own (an enrich, such as a leg cut from a post) has the standard part's ports. Where the joint is near one of them rather than on it, give it a name of the leg's own with map: instead of declaring a new port by coordinates: {port: <its port>, moveX: ..., turnZ: ...}, in the frame of that port, written in terms of the enrich's with values where it depends on them ("%length * 25.4%"). See "New names for what an object has" in the configuration docs.