Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Parts and assemblies

An assembly is a part whose features insert other parts as components and constrain them with mates. This chapter covers insertPart, the placement of a component, the mate constraints and their kinds, the degrees-of-freedom report, and how a component pattern copies components.

An assembly document is an ordinary part; the top-level field "kind": "assembly" marks it for editors but the kernel does not need it.

insertPart

Puts a copy of another part in the assembly.

FieldTypeDefaultMeaning
partpart documentrequiredThe part, embedded in full: a document with format, features and the other top-level fields. If it is missing or cannot be read (it fails the format check) the feature is insertPartMissing.
place{o, x, y, z}noneThe placement frame: four vectors of three plain numbers. The component’s world origin maps to o and its axes to x, y, z.
dx, dy, dznumber0A translation, used when there is no place. Plain numbers; expressions are not evaluated here.
axis{"kind": "axis", "axis": "x"}noneRotation axis for the angle form: a world axis through the origin.
anglenumber or expression0Degrees about axis. The rotation is applied first, then the translation dx, dy, dz.
fixedbooleanfalseA fixed component never moves: its degrees of freedom are 0, and mates move the other component.
sourcestringnoneA label for where the part came from. Read and kept, not used by the kernel.

The embedded part is regenerated on its own, with its own rollback ignored, and its body becomes the component. Two inserts of the same part document regenerate it once. Components are appended to the body as separate bodies; they are never united, so components may overlap.

Every face of a component is renamed with the id of the insert feature: E1.C0 in the part becomes E1.C0@F1.1 for the insert F1. Names the part already had after @ stay in front (F8.S.h1@F9.1@F1.1). These are the names mates and later features use.

The regen reply lists the components in components, sorted by id: {id, dof, place}, where dof is 6 for a free component and 0 for a fixed one (mates lower it) and place is the frame the component now has.

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 50, "dy": 0, "dz": 0, "axis": {"kind": "axis", "axis": "y"}, "angle": 90
    }
  ]
}

Run result: no errors; 6 faces, volume 3141.5927 mm³. Components in the reply: F1 dof 0, origin [0,0,0]; F2 dof 6, origin [50,0,0]. The faces of the body are E1.C0@F1.1, E1.C1@F1.1, E1.S.e1@F1.1, E1.C0@F2.1, E1.C1@F2.1, E1.S.e1@F2.1. The volume is the sum of the two pins (3141.5927); nothing is united.

A placement frame instead of dx, dy, dz:

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "place": {"o": [0, 0, 50], "x": [1, 0, 0], "y": [0, 1, 0], "z": [0, 0, 1]}
    }
  ]
}

Run result: no errors; 3 faces, volume 1570.7963 mm³. Component: F1 dof 6, origin [0,0,50].

Errors and edge cases:

SituationResult
No part, or an unreadable oneinsertPartMissing.
The part reports errors when regeneratedinsertPartErrors with params.detail set to "<feature id>: <code>" of the first error (by feature id). The part is not inserted.
The part has no features, or builds no solid bodyNo error and no component.
{"format": "ck-part", "version": 1, "features": [{"type": "insertPart", "id": "F1"}]}

Run result: errors F1: insertPartMissing; no solid body.

{
  "format": "ck-part", "version": 1,
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S9", "end": "blind", "depth": 5}
        ]
      }
    }
  ]
}

Run result: errors F1: insertPartErrors {"detail":"E1: missingSketch"}; no solid body.

mate

A mate constrains two components by one face on each. The mate moves the component of a onto the component of b; when that component is fixed, the other one moves instead. Mates are solved in order and each later mate keeps the earlier ones satisfied where it can. The solution is iterative (a damped Gauss-Newton on the placement of the moving component), so positions are accurate to about 1e-9 rather than exact.

FieldTypeDefaultMeaning
kindstring"coincident"See the table of kinds.
aface namerequiredA face of the moving component, in its component name (E1.C0@F2.1).
bface namerequiredA face of the other component.
distancenumber or expression0Offset for distance, the stop offset of hinge.
flipbooleanfalseReverses the contact side or the direction, depending on the kind.
a2, b2face namesnoneSecond faces (width, hinge stop, slot wall).
cface namenoneThe mirror face of symmetric.
anglenumber or expressionkind dependentDegrees: the angle of an angle mate, or the drive of gear, rackPinion and screw.
ratio, pitch, radiusnumber or expression1, 1, noneGear ratio, screw pitch (length per turn), pinion pitch radius.
min, max, oflimits: the range, and of: "distance" (default) or "angle".
dir[x, y, z]noneTravel direction of a planar rack.

Kinds. “Leaves” is the freedom a free component keeps when mated once to a fixed one (an observed value for the examples run; a second mate removes more):

kindFacesConstraintLeaves
coincidentplane, planeNormals opposed (or aligned with flip), the planes touch.3
distanceplane, planeAs coincident, at distance.3
parallelplane or axis pairsDirections parallel.4
concentriccylinder, cylinderAxes on one line.2
angleplane, cylinder or coneThe angle between the two directions equals angle.5
perpendicularplane or axis pairsDirections at 90 degrees.5
tangentcylinder or sphere against plane; cylinder or sphere pairsContact. flip takes the other side of a plane, or internal contact between round faces.4 for a cylinder on a plane
lockany face of eachThe relative pose at the time of the mate is kept.0
symmetricplane/plane, cylinder/cylinder, sphere/sphere, and ca is the mirror image of b about c (the component of c is treated as fixed).3 for a plane pair
widtha, a2 parallel planes of a tab; b, b2 of a slotThe tab centred in the slot.3
hingecylinders or cones; optional a2, b2 stop planesConcentric axes, and the stop faces in contact at distance.1 turn (2 without the stop)
slota a pin (cylinder); b (and b2) planar slot wallsPin parallel to the walls and centred between them.4
screwcylinders (screw, nut)Concentric, advance = pitch x turns; with angle the nut is placed that far along the thread.1; 0 with angle
gearcylindersThe follower turns by -angle / ratio about its axis for a drive angle of a, measured from the pose at the time of the mate.one coupling
rackPinionpinion cylinder, rack cylinder or plane with dirRack travel = radius x pinion angle.one coupling
limitstwo planes, or two directions with of: "angle"The measured value is clamped into [min, max]; inside the range the mate removes no freedom.6 inside the range

Couplings (gear, rackPinion, screw) are measured from the placements the components have when the mate is made (after earlier mates were solved), so a later mate that moves the driver drags the follower. The follower is the component of b; if that one is fixed, gear and screw swap the roles, and rackPinion is refused with mateFixed. Not supported (mateGeometry): symmetric with c on a moving component, tangent with a cylinder in a and a sphere in b, a rack that is neither a cylinder nor a plane with dir. An unknown kind is mateGeometry.

A cap against a cap. F2 slides on the cap of F1 (it keeps three freedoms: two translations along the plane and one rotation about the normal):

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 100
    },
    {"type": "mate", "id": "F3", "kind": "coincident", "a": "E1.C0@F2.1", "b": "E1.C1@F1.1"}
  ]
}

Run result: no errors; 6 faces, volume 3141.5927 mm³. The cap of F2 lies on the cap of F1: F1 dof 0, origin [0,0,0]; F2 dof 3, origin [100,0,19.999999998] (z = 20). It can still slide in x and y and turn about z, so it keeps 3 of its 6 freedoms. The position is converged to about 1e-9, not exact.

Axis on axis, leaving a slide and a turn along the axis:

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 100
    },
    {"type": "mate", "id": "F3", "kind": "concentric", "a": "E1.S.e1@F2.1", "b": "E1.S.e1@F1.1"}
  ]
}

Run result: no errors; 6 faces, volume 3141.5927 mm³. The axis of F2 is on the axis of F1: F1 dof 0, origin [0,0,0]; F2 dof 2, origin [0,0,0].

A hinge with a stop face leaves one turn:

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 100
    },
    {
      "type": "mate", "id": "F3", "kind": "hinge", "a": "E1.S.e1@F2.1", "b": "E1.S.e1@F1.1",
      "a2": "E1.C0@F2.1", "b2": "E1.C1@F1.1"
    }
  ]
}

Run result: no errors; 6 faces, volume 3141.5927 mm³. F2 sits on top of F1 on the same axis and can only turn: the assembly object says {“total”:1,“translational”:0,“rotational”:1}.

Errors

CodeWhen
missingReferenceA face name does not exist (or b is empty).
mateSameBodyBoth faces belong to one component.
mateFixedBoth components are fixed (and for rackPinion a fixed rack).
mateGeometry {detail}The kind cannot use the geometry of these faces, or the kind is unknown.
mateConflictThe solver cannot satisfy this mate together with the earlier ones.
nothingToCutThe document has no body yet.

A rejected mate leaves every component where the earlier mates put it, and the other mates still run.

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true, "dx": 100
    },
    {"type": "mate", "id": "F3", "kind": "coincident", "a": "E1.C0@F2.1", "b": "E1.C1@F1.1"}
  ]
}

Run result: errors F3: mateFixed; 6 faces, volume 3141.5927 mm³.

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "fixed": true
    },
    {
      "type": "insertPart", "id": "F2",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 100
    },
    {
      "type": "mate", "id": "F3", "kind": "distance", "a": "E1.C0@F2.1", "b": "E1.C1@F1.1",
      "distance": 5
    },
    {
      "type": "mate", "id": "F4", "kind": "distance", "a": "E1.C0@F2.1", "b": "E1.C1@F1.1",
      "distance": 9
    }
  ]
}

Run result: errors F4: mateConflict; 6 faces, volume 3141.5927 mm³. The second mate is rejected and F2 stays where the first put it (z = 25): F1 dof 0, origin [0,0,0]; F2 dof 3, origin [100,0,24.999999998].

The degrees-of-freedom report

When the document uses a mate kind beyond coincident, concentric, distance and parallel, or the regen request has opts.dofReport: true, the reply carries an assembly object next to components. This is the report of the hinge example above:

{"assembly": {
  "dof": {"total": 1, "translational": 0, "rotational": 1},
  "components": [{"id": "F1", "fixed": true, "dof": 0, "translational": 0, "rotational": 0},
                 {"id": "F2", "fixed": false, "dof": 1, "translational": 0, "rotational": 1}],
  "overConstrained": false,
  "redundant": [],
  "conflicts": []
}}
  • dof.total is the dimension of the motion space of all floating components left by all mates together. rotational is the rank of the rotation part, translational the rest. Each component’s own numbers are the motions it can still make; fixed components report 0.
  • redundant lists mates that add no constraint (their rows depend on the earlier mates). They are harmless and make overConstrained true.
  • conflicts lists each rejected mate as {"mate": id, "with": [earlier mates on the same components]}, with the matching mateConflict error.
  • The rank comes from a numeric Jacobian of the mate residuals at the solved pose, so a nearly singular pose can be misreported. With more than 30 floating components the null-space part is skipped and the object carries "truncated": true.

The same number appears as components[].dof once an added kind is present.

Component patterns

A cpattern with an empty seeds list and bodies set copies whole components around an axis (see patterns and transforms). bodies is a list of {"face": "<component face>"}: every component that owns one of the faces is copied.

FieldMeaning
bodies[{"face": "E1.C0@F1.1"}]: a face of each component to copy.
axis, count, angle, equal, reverseAs for a circular pattern.

The copies are new bodies named with the pattern id after the component suffix (E1.C0@F1.1@F2.1); they are not listed in components.

{
  "format": "ck-part", "version": 1, "kind": "assembly",
  "features": [
    {
      "type": "insertPart", "id": "F1",
      "part": {
        "format": "ck-part", "version": 1,
        "features": [
          {
            "type": "sketch", "id": "S1", "plane": {"kind": "std", "id": "front"},
            "points": [{"id": "c", "x": 0, "y": 0}],
            "entities": [{"type": "circle", "id": "e1", "c": "c", "r": 5}], "constraints": []
          },
          {"type": "extrude", "id": "E1", "op": "add", "sketch": "S1", "end": "blind", "depth": 20}
        ]
      },
      "dx": 30
    },
    {
      "type": "cpattern", "id": "F2", "seeds": [], "bodies": [{"face": "E1.C0@F1.1"}],
      "axis": {"kind": "axis", "axis": "z"}, "count": 3, "angle": 360
    }
  ]
}

Run result: no errors; 9 faces, volume 4712.389 mm³. Three pins around the z axis. The copies are named E1.C0@F1.1@F2.1, E1.C1@F1.1@F2.1, … and are not listed in components (1 component).

importStep

Holds a body that came from a STEP file, so that sketches, cuts and fillets later in the history can work on it. The STEP text is kept inside the part, so the part does not depend on a file next to it.

FieldTypeDefaultMeaning
blobstringnoneKey of an entry in the part’s top-level blobs table. The entry is the STEP text and the key is the SHA-256 of that text in lower-case hex (of its UTF-8 bytes).
stepstringnoneThe STEP text written in the feature itself. Meant for small files; use blob for anything large. blob wins when both are given.
bodystringnoneName for the body. When the file holds several solids they are named <body>, <body> 2, <body> 3, in file order.
{
  "format": "ck-part", "version": 1,
  "blobs": {"9f2c...e1": "ISO-10303-21;\nHEADER;\n..."},
  "features": [{"type": "importStep", "id": "F1", "blob": "9f2c...e1", "body": "Case"}]
}

How it behaves:

  • The kernel reads the file with its STEP reader. Lengths are converted to millimetres using the units the file declares (millimetre, centimetre, metre, inch and so on).
  • Every solid in the file becomes its own body. Following the rule for new bodies, the solids are added beside any bodies that already exist and are not joined to them.
  • Faces are named <feature id>.I<solid>F<n>, for example F1.I1F7. The solid number and the face number follow the order in the file, so the names are the same on every run and after the part is saved and opened again. Later features refer to these faces like any other face (see identifiers and references).
  • The key is checked against the text every time the feature runs. Because the regeneration cache only sees the key and not the text, a large file adds a few bytes to a cache key, and the same file used by two features is stored once.
  • Keep the blobs entry as long as a feature uses it. Editors should remove entries that no feature names.

Errors and edge cases:

SituationResult
No blob and no stepimportStepInvalid with params.detail.
The key is missing from blobs, or does not match the textimportStepInvalid with params.detail.
The text is not a STEP file, is cut short or uses something the reader cannot buildimportStepInvalid; params.detail is the reader’s message, params.reason its code and params.entity the STEP entity number when it names one.
The file holds no solidimportStepInvalid.
A body name already used by another bodybodyNameConflict.

See also