Add Interfaces

pc:add-interfaces

Add interfaces, ports, and implements: metadata to an existing PartCAD part so PartCAD can mate it to other parts by connection rather than by hand-placed coordinates. The text after the command ($ARGUMENTS) names the target part (and, optionally, how it is meant to connect). You decide the interface types and the exact port coordinates by examining the geometry, and you prove they are right twice: by drawing them on the part itself (pc render --with-all, step 4) and by mating two instances in a throwaway assembly and rendering that (step 5). Hard requirement: the enriched part passes pc test and the validation assembly renders correctly connected.

Interfaces are the reusable half of this: define the connector once, then every part that has that feature implements: it, and any two compatible parts mate. Reference: docs/source/configuration.rst (the "Interfaces" and "Parts" sections) and the feature_interface example (connect-interfaces.assy).

1. Resolve the part and how it connects

$ARGUMENTS is the object name (a part by default). Read its desc:/requirements:/summary: from partcad.yaml. Make sure PartCAD is available as /pc:init describes (pc, then partcad, then python -m partcad_cli.click.command).

Decide what connects to what: which physical feature on this part joins to a feature on another part (a bolt hole to a screw, a plug to a socket, a stud to a receptacle, a rail to a slot). Each such feature becomes a port; a named set of ports is an interface. A male feature and the female feature it enters are two different, complementary interfaces that mates: each other.

2. Understand the geometry (render and/or read the source)

You need each connection feature's position and orientation in the part's own coordinate frame, in millimeters. Get them two ways and cross-check:

• Render it to see orientation and where the origin sits:

  mkdir -p /tmp/pc-render
  pc render -t png -O /tmp/pc-render <part>        # one isometric PNG

  To see other angles, place the part at rotated locations in a throwaway .assy and render that. Run /pc:describe on the part for a written read of the shape.

  Once the part already has some ports, add --with-ports to see them drawn on that same picture — see "Look at the ports" below. That is also how you check a port you have just written before doing anything else with it.

• Read the exact coordinates from the source when you can — the CAD script, the STEP/BREP, or (for a generated/meshed part) the upstream data file. Exact numbers beat measuring off a render.

Confirm the origin and axes by reasoning about the render: where is (0,0,0), and which way is "up" for this part (it is not always +Z — a mesh-imported part can land with +Y up). Every port coordinate below is in this frame.

3. Design the interfaces and port coordinates

A port is an OCCT Location, [[x,y,z],[ax,ay,az],angle_deg]: translate to [x,y,z], then rotate angle_deg about axis [ax,ay,az]. Optionally give it a sketch: (a 2D boundary) so it is visible when rendered.

Follow the port-matching convention so mates are unambiguous:

• Use the port's Z axis as the main direction. A male port's Z points outward (out of the material); the female port it enters has Z pointing inward. When two ports mate, their origins coincide and their Z axes are opposite — PartCAD flips the incoming part 180 deg about [1,1,0], which sends +Z -> -Z.
• Orient each port's X axis toward the "next" equivalent port (right-hand rule). If several ports are interchangeable (e.g. the 4 corners of a bolt pattern, or a grid of studs), a consistent circular X orientation makes any aligned pair align all of them.

Useful consequence to place features precisely: if you orient the two ports so the 180 deg flip cancels the rotation, the mated part ends up translated by target_port_position - source_port_position with no rotation. So the mating offset is carried entirely by the two port positions — put the female (receiving) port on the part's own mating plane and the stacking/insertion depth falls out automatically, per part. Verify any non-obvious orientation cheaply, without rendering, using the pure-Python partcad.geom.Location (__mul__, .inverse(), .as_packed()) against the assembly's mate formula target_loc * target_port * turn(180@[1,1,0]) * source_port.inverse().

Declare it in partcad.yaml:

sketches:
  <port-boundary>:            # optional, for visualization
    type: basic
    circle: <radius>
interfaces:
  <male-iface>:
    desc: <what it is; note Z points outward>
    ports:
      <port>:
        sketch: <port-boundary>
    mates:
      <female-iface>:
        # freedom of movement, if any; omit or use 0 for a rigid seat
        moveZ: { min: 0, max: 0, default: 0 }
  <female-iface>:
    desc: <the complementary receptacle; Z points inward>
    ports:
      <port>:
        sketch: <port-boundary>

Interfaces can inherits: others (share ports/parameters) and declare parameters: (moveX/Y/Z, turnX/Y/Z, or a custom dir:) for parametrized mating such as a slotted hole. Reuse an existing interface if one already fits rather than inventing a new one.

4. Attach the interfaces to the part with implements:

A part implements an interface, placing that interface's ports onto the part. Place each occurrence with its own Location; use several named instances to place the same interface at several spots:

parts:
  <part>:
    # ...existing config...
    implements:
      <male-iface>:
        <instanceA>: [[x, y, z], [ax, ay, az], angle]
        <instanceB>: [[x, y, z], [ax, ay, az], angle]
      <female-iface>:
        <instanceA>: [[x, y, z], [ax, ay, az], angle]

If the part is served by an external / plugin-backed package (a dynamic catalog with no static partcad.yaml entry to edit), do not try to edit the source. Enrich it in a consuming package instead: add a type: enrich part there that points at the upstream part with source: and carries the added implements:. Enrich copies your implements: onto the resolved part:

parts:
  <local-name>:
    type: enrich
    source: //path/to/upstream/pkg:<upstream-part>
    implements:
      <fully-qualified-iface-name>:      # e.g. //my/consuming/pkg:<male-iface>
        <instance>: [[x, y, z], [ax, ay, az], angle]

Use fully-qualified interface names in an enriched part's implements: (the enriched part is instantiated in the upstream package's namespace, so a bare name would resolve there, not in your package). For the consuming package to resolve //path/to/upstream/pkg:<part>, that upstream package must be reachable from the invocation root — the simplest arrangement is to make the consuming package a sub-package of the upstream one and run pc from the upstream root. If enrich cannot carry the metadata for a given part, fall back to a local wrapper (type: alias, or a thin re-declared part) that adds the implements:.