Assembly: ground the first part; drag free joint chains (#2804) (#2805)

* assembly(feat): ground first parts and drag free joint chains

Ground the first top-level part when it is created and let face dragging reposition free occurrences or any member of a floating joint chain in one undo step. Preserve exact repeated-placement frames, joint values, modifier selection and Escape cancellation. Keep the accumulated fixture, viewport layout and documentation integration fixes from the existing PR.

Signed-off-by: Karl Von Richter<karl@embeint.com>

* assembly(fix): update movable fixtures for first-part grounding

Accept the documented grounded override in component creation, explicitly free movement fixtures, and keep linked clipboard pastes movable even in an empty document. Cover first and reused linked pastes, default insertion grounding, and single-step undo in the existing link tests.

Signed-off-by: Karl Von Richter<karl@embeint.com>

* assembly(test): keep the motion-cost crank free

Unground the first component in the document-level joint-face measurement fixture so its motion samples can rotate after first-part grounding. Preserve the rotation and shared-measurement assertions that caught the Linux CI failure.

Signed-off-by: Karl Von Richter<karl@embeint.com>

* assembly(test): free the frame placement fixture

Create the frame-member placement fixture ungrounded before moving it above its root sketch. Keep its world-space member assertions while respecting first-part grounding in the frame tests added on main.

Signed-off-by: Karl Von Richter<karl@embeint.com>

---------

Signed-off-by: Karl Von Richter<karl@embeint.com>
This commit is contained in:
Karl Von Richter
2026-10-23 23:15:34 +00:00
committed by GitHub
parent 30b01e8d79
commit 0dffb206b1
75 changed files with 1094 additions and 115 deletions
+27 -3
View File
@@ -9,7 +9,31 @@ faded.
A component is placed by its **occurrences**. Paste creates another instance of the same
component, and **Paste New** creates an independent copy. Move an occurrence with the move
triad, then **Capture Position** to keep it or **Revert** to put it back. SolidCraft asks before
the next command if a move wasn't captured. **Ground** fixes an occurrence in place.
the next command if a move wasn't captured. **Ground** fixes an occurrence in place, and
**Unground** (the same row of the browser's context menu) frees it again.
The design's first part is grounded when it is made: the first occurrence placed directly in the
design by **New Component**, **Create Components from Bodies** or an import. Parts made after it,
standard parts and copies made with Paste or Paste New start free, so do parts made inside other
components. Any number of parts may be grounded, or none; opening a design never grounds
anything. A grounded part refuses Move until it is ungrounded, and `component.create` takes
`grounded: true` or `false` to choose for itself.
**Drag a part to put it somewhere else.** With the design active, press the left button on a part
and drag: the part follows the pointer, the point you grabbed moving in the plane through it that
faces the view, and stays where you let go, with its position captured. The whole drag is one
undo step, and Escape during the drag puts the part back. The drag moves the placement of the
active component that holds the part, so with the design active a part inside a subassembly
moves the whole subassembly; activate the subassembly to move the part inside it. Moving a
definition shared by several placements moves it in all of them, as Move does. A grounded part
does not move, and a part that joints hold to something grounded moves only as far as its joints
allow (below). Dragging any member of a chain joined to nothing grounded moves the whole chain,
preserving its joint values. Shared nested definitions move in every instance; the selected
instance follows the pointer even when its parent is rotated differently from the first one. A drag that starts on empty space, on a part that can't move, or
with Shift, Ctrl (Cmd) or Alt held draws a selection box instead. Other uncaptured moves stay
pending. Scripts and agents do the same with `occurrence.drag {occurrence or path, at, point}`,
which moves the placement by `point - at` in world coordinates and answers the placements it
`moved`.
Paste New copies nested component definitions, sketches, feature histories and generated
dimension parameters. Repeated child instances remain shared within the new copy. Materials,
@@ -185,8 +209,8 @@ picked in the browser, or on the first joint that moves when none is picked.
grabbed follows the pointer in the plane through it that faces the view, the joints on the
part's chain take the values that bring it nearest, within their limits, through motion links,
and with closed loops kept closed, and a four-bar's rocker stops at the end of its swing. The
whole drag is one undo step. A grounded part, or one no joint places, is not moved; a drag on
it draws a selection box as before. Each frame runs `joint.reach`, which scripts and agents use
whole drag is one undo step. A grounded part, or one its joints hold fixed, is not moved; a drag
on it draws a selection box. Each frame runs `joint.reach`, which scripts and agents use
directly to put a part's point somewhere: `joint.reach {occurrence, point}` moves the joints on
its chain from where they are to the nearest pose (the arm keeps its elbow up or down, and a
linkage stays on its branch). `at` picks the part's point (the centre of its bodies by
+1 -1
View File
@@ -229,7 +229,7 @@ One placed copy of a component inside its parent component.
A component can have several occurrences. Moving an occurrence moves only that copy; editing the
component changes every copy. The browser names occurrences with a number, such as `Bolt M20:3`.
- **In SolidCraft:** `occurrence.copy`, `occurrence.move`, `occurrence.ground`,
- **In SolidCraft:** `occurrence.copy`, `occurrence.move`, `occurrence.drag`, `occurrence.ground`,
`occurrence.properties`; the `occurrences` design-file key; the `path` of occurrence ids.
- **Don't use:** instance, placement.
- **Elsewhere:** occurrence, instance, component instance.
+16
View File
@@ -14,6 +14,14 @@ Properties accepts the leaf occurrence ID and the full path. Move can use world
{"occurrence":4,"path":[2,4],"space":"world","translate":[10,0,0],"capture":false}
```
A drag in the viewport, or `occurrence.drag`, moves one exact placement and its floating joint chain by a world translation:
```json
{"path":[2,4],"at":[0,0,10],"point":[20,0,10]}
```
It captures that placement's position (other pending positions stay pending) and is one undo step. With the design active, the viewport drags the placement on the picked body's path just inside the design; with a component placement active, the one just inside it. Grounded placements and placements that joints hold to something fixed are refused; a free chain of joints moves together, and a chain through a placement used several times is refused. The design's first top-level part is grounded when it is made (not when a design is opened); copies start free.
World movement includes pending parent and child positions. The default space remains parent-local for existing scripts. Capture Position commits pending transforms; Revert Position drops them. Copying an occurrence copies that selected occurrence's effective transform, including its pending position.
An occurrence definition inside a component is shared by every instance of that parent component. Moving, grounding, copying, or deleting that nested definition changes all its parent instances. Selecting its exact path determines the world frame used for movement and Properties; it does not create an independent child definition.
@@ -60,6 +68,14 @@ Use `sketch.redefine` with the sketch ID and a new plane to repair or convert an
Paste New remaps internal certified targets and authoring paths to the copied definitions. Timeline paste reports retained external face targets and refuses translating such attachments until an explicit fixed-plane conversion establishes independent geometry. Rename preserves certified body identity; another producer using the same body name cannot repair a lost attachment.
## Floating joint chains
Dragging any member of a floating joint chain carries the chain together without changing its
joint values. A chain joined to a grounded part still uses `joint.reach` within its joints.
Repeated nested definitions are shared: their other instances follow in their respective
parent frames. The selected exact path determines the local change, which is carried through
the solver's first-placement frame to jointed peers, including repeated peers.
## Change the size of a standard component
An inserted standard part is one component with an active catalogue configuration.