Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

feat(assembly): sub-assemblies join on their own motion path, and paths can turn parts at any waypoint

aashued717cef4772
diff --git a/apps/erp/app/modules/production/AGENTS.md b/apps/erp/app/modules/production/AGENTS.md
index 19945caa75..9e4c3dfb88 100644
--- a/apps/erp/app/modules/production/AGENTS.md
+++ b/apps/erp/app/modules/production/AGENTS.md
@@ -72,7 +72,7 @@ pnpm --filter @carbon/erp test
| `productionQuantity` | Output: type (Production/Scrap/Rework), quantity, scrapReason |
| `jobOperationBatch` | Operation batch header (`BAT` sequence): process, work center, location, status (`Planned` = pre-floor, `Active` displayed "Released"). Members are `jobOperation` rows via nullable `jobOperationBatchId`. A Released batch's coalesced schedule slot is a `capacityReservation` row tagged `jobOperationBatchId` (spared by per-job regen deletes; visible in every snapshot regardless of the anchor job's status; deleted by a `jobOperationBatch` status trigger when the batch completes or is unreleased — the sparing rules make that trigger the only retirement path; dissolve self-heals via the FK's column-list SET NULL + the anchor job's next regen) |
| `procedure` / `procedureStep` / `procedureParameter` | Versioned work instructions |
-| `assemblyInstruction` / `assemblyInstructionStep` | 3D model-based assembly instructions (Draft/Published/Archived); steps carry `componentNodeIds` + `motion`/`camera` JSON for the viewer, `hiddenComponentNodeIds` (parts hidden on THAT step only — tooling/fixtures/installed parts in the way; never the step's own `componentNodeIds`, stripped by a DB trigger on every write; applied by the shared player in the ERP editor and MES playback, authored only in the ERP), a `buildWave` INTEGER (the step's longest-path level in the planner's precedence DAG — steps sharing a wave have no ordering constraint and can be built in parallel by different people/stations; NULL for cycle-affected or hand-authored steps; informational, `sortOrder` still governs playback), and `warnings.needsSupport` (a part in the step tips once placed — center of mass outside the support polygon of the parts below it — likely needs a fixture or a second hand; shown as a hand icon with a tooltip in the step list) AND the typed-step fields mirrored from `jobOperationStep` (`type` `procedureStepType`, tiptap `description` with derived `instructionText`, `required`, UoM/min/max, `listValues`) for eventual copy into job operations. `motion`/`camera` are authored directly in the 3D viewer (drag the red waypoint path → relative `linear`/`L` motion; "Set view" captures the camera pose), autosaved via `updateAssemblyStepMotion` / the `steps/motion/$stepId` route — separate from the step form's `upsertAssemblyInstructionStep` (which rewrites `title`/typed fields). There is no numeric motion editor. **Step camera is a discriminated union**: a manual `{position,target,fov}` pose (applied verbatim), OR a planner hint `{source:"plan",direction}` — a mesh-precise view DIRECTION the Rust planner bakes per step (`crates/planner/src/view.rs` `best_view_direction`: sight lines against the real triangles of everything installed earlier, so it sees a hollow enclosure's open top where the viewer's AABB scoring can't). The viewer applies the hint with LIVE framing — target, standing distance, frustum fit at the real viewport aspect (`fitFraming`, `@carbon/viewer`). `null` = fully live AABB framing (fallback for hand-edited steps / old plans). Generated steps carry the plan hint (the TS-side camera bake was removed); re-motion refreshes it but never clobbers a manual pose. Playback visibility is presence-based (`@carbon/viewer` `visualForComponent`): a component exists on the canvas only once its step has run; components no step installs render like future-step ones (hidden during playback, future-components toggle while paused). Visibility has TWO independent axes — `futureMode` (not built yet) and `installedMode` (already built — `solid` default, so the historical rendering is unchanged; `ghost`/`hidden` let an operator see past an assembly that buries the active step's parts) — but the toolbar does NOT expose them as axes. It offers three NAMED views (`ASSEMBLY_VIEWS` / `VIEW_MODES` in `visibility.ts`): **Build** (installed solid — the historical default), **Focus** (installed ghosted, so you see past what is already fitted but keep its shape) and **Full** (everything solid). An "Isolate" view (installed hidden) was dropped: per-step `hiddenComponentNodeIds` cover removing the clutter an author chooses. The future side is hidden in all but Full: a step you are working is never helped by parts that are not on the bench yet. The same control renders in ERP and MES; nine combinations behind two icon triplets was the design that got rejected for being unreadable on a shop floor. The camera's AABB view-direction scoring honours both via `occluderWeight` — geometry the operator cannot see is never treated as an obstacle, or hiding it would clear the pixels while the framing still dodged it. AABB fallback motions for `"none"`-motion steps consider only PRIOR-step components as obstacles and fade in when no collision-free path exists or when the component interpenetrates a present component (mated parts — sliders on rails, fasteners in bores — never get fabricated paths; the planner is the only authority for those) |
+| `assemblyInstruction` / `assemblyInstructionStep` | 3D model-based assembly instructions (Draft/Published/Archived); steps carry `componentNodeIds` + `motion`/`camera` JSON for the viewer, `hiddenComponentNodeIds` (parts hidden on THAT step only — tooling/fixtures/installed parts in the way; never the step's own `componentNodeIds`, stripped by a DB trigger on every write; applied by the shared player in the ERP editor and MES playback, authored only in the ERP), a `buildWave` INTEGER (the step's longest-path level in the planner's precedence DAG — steps sharing a wave have no ordering constraint and can be built in parallel by different people/stations; NULL for cycle-affected or hand-authored steps; informational, `sortOrder` still governs playback), and `warnings.needsSupport` (a part in the step tips once placed — center of mass outside the support polygon of the parts below it — likely needs a fixture or a second hand; shown as a hand icon with a tooltip in the step list) AND the typed-step fields mirrored from `jobOperationStep` (`type` `procedureStepType`, tiptap `description` with derived `instructionText`, `required`, UoM/min/max, `listValues`) for eventual copy into job operations. `motion`/`camera` are authored directly in the 3D viewer (drag the red waypoint path → relative `linear`/`L` motion, or `waypoints` once a waypoint is turned with the rotation rings; "Set view" captures the camera pose; a sub-assembly header's `motion` is the finished unit's own joining path, edited from the using step's Playback box — or the header's own panel when nothing uses it — and saved through the same motion route with the header id), autosaved via `updateAssemblyStepMotion` / the `steps/motion/$stepId` route — separate from the step form's `upsertAssemblyInstructionStep` (which rewrites `title`/typed fields). There is no numeric motion editor. **Step camera is a discriminated union**: a manual `{position,target,fov}` pose (applied verbatim), OR a planner hint `{source:"plan",direction}` — a mesh-precise view DIRECTION the Rust planner bakes per step (`crates/planner/src/view.rs` `best_view_direction`: sight lines against the real triangles of everything installed earlier, so it sees a hollow enclosure's open top where the viewer's AABB scoring can't). The viewer applies the hint with LIVE framing — target, standing distance, frustum fit at the real viewport aspect (`fitFraming`, `@carbon/viewer`). `null` = fully live AABB framing (fallback for hand-edited steps / old plans). Generated steps carry the plan hint (the TS-side camera bake was removed); re-motion refreshes it but never clobbers a manual pose. Playback visibility is presence-based (`@carbon/viewer` `visualForComponent`): a component exists on the canvas only once its step has run; components no step installs render like future-step ones (hidden during playback, future-components toggle while paused). Visibility has TWO independent axes — `futureMode` (not built yet) and `installedMode` (already built — `solid` default, so the historical rendering is unchanged; `ghost`/`hidden` let an operator see past an assembly that buries the active step's parts) — but the toolbar does NOT expose them as axes. It offers three NAMED views (`ASSEMBLY_VIEWS` / `VIEW_MODES` in `visibility.ts`): **Build** (installed solid — the historical default), **Focus** (installed ghosted, so you see past what is already fitted but keep its shape) and **Full** (everything solid). An "Isolate" view (installed hidden) was dropped: per-step `hiddenComponentNodeIds` cover removing the clutter an author chooses. The future side is hidden in all but Full: a step you are working is never helped by parts that are not on the bench yet. The same control renders in ERP and MES; nine combinations behind two icon triplets was the design that got rejected for being unreadable on a shop floor. The camera's AABB view-direction scoring honours both via `occluderWeight` — geometry the operator cannot see is never treated as an obstacle, or hiding it would clear the pixels while the framing still dodged it. AABB fallback motions for `"none"`-motion steps consider only PRIOR-step components as obstacles and fade in when no collision-free path exists or when the component interpenetrates a present component (mated parts — sliders on rails, fasteners in bores — never get fabricated paths; the planner is the only authority for those) |
| `assemblyInstructionStepMaterial` | BOM parts consumed at a step (`stepId` → `itemId` + optional quantity; stored by itemId so links survive make-method re-versioning; picker limited to the item's make-method BOM; UNIQUE `(stepId, itemId)`). Auto-populated from `assemblyComponentMapping` via `syncAssemblyStepMaterialsFromMappings` — additive only (manual quantities/deletions survive), triggered on step generation, component add, mapping create, and "Match BOM" |
| `assemblyInstructionStepSlide` | Per-step reference slides (image XOR 3D model via `modelUploadId`, caption, `size`, `annotations` JSONB pins), mirroring `methodOperationStepSlide`; authored in the step editor's Details tab and copied to `jobOperationStepSlide` by the BOP sync / get-method. The former `assemblyInstructionStepRequirement` / `assemblyStandardNote` tables (fixtures/consumables/notes/media) were dropped — a step definition is parts + tools + slides |
| `assemblyInstructionStepTool` | Tools used at a step (`stepId` → `itemId` of a tool-type item + `quantity`, UNIQUE `(stepId, itemId)`) — `itemId` is the same target `jobOperationTool.toolId` references, so the BOP sync maps rows 1:1 |
diff --git a/apps/erp/app/modules/production/production.models.ts b/apps/erp/app/modules/production/production.models.ts
index 476fa06051..8d2c614648 100644
--- a/apps/erp/app/modules/production/production.models.ts
+++ b/apps/erp/app/modules/production/production.models.ts
@@ -1298,10 +1298,24 @@ export const assemblyStepStatuses = ["Todo", "Review", "Done"] as const;
const vector3 = z.tuple([z.number(), z.number(), z.number()]);
const quaternion = z.tuple([z.number(), z.number(), z.number(), z.number()]);
+const unitQuaternion = quaternion.refine(
+ ([x, y, z, w]) => Math.abs(Math.hypot(x, y, z, w) - 1) < 1e-3,
+ { message: "Rotation must be a unit quaternion" }
+);
+
+/** A waypoint at the seated pose: no offset and no turn (either quaternion sign). */
+function isSeatWaypoint(
+ waypoint: { offset: number[]; rotation: number[] } | undefined
+): boolean {
+ if (!waypoint) return false;
+ const [ox = 0, oy = 0, oz = 0] = waypoint.offset;
+ const w = waypoint.rotation[3] ?? 0;
+ return Math.hypot(ox, oy, oz) < 1e-3 && Math.abs(Math.abs(w) - 1) < 1e-6;
+}
/**
- * Insertion motion of a step's parts. See
- * docs/specs/animated-work-instructions-contracts.md §4.
+ * Insertion motion of a step's parts. Mirrors `Motion` in
+ * `packages/viewer/src/types.ts`, the shared contract.
*/
export const motionSchema = z.discriminatedUnion("type", [
z.object({
@@ -1342,6 +1356,17 @@ export const motionSchema = z.discriminatedUnion("type", [
)
.min(2)
}),
+ // Editor-drawn path with rotation: poses relative to the seated pose. The
+ // last waypoint is the seat itself (no offset, no turn).
+ z.object({
+ type: z.literal("waypoints"),
+ waypoints: z
+ .array(z.object({ offset: vector3, rotation: unitQuaternion }))
+ .min(2)
+ .refine((waypoints) => isSeatWaypoint(waypoints[waypoints.length - 1]), {
+ message: "The last waypoint must be the seated pose"
+ })
+ }),
z.object({ type: z.literal("none") })
]);
diff --git a/apps/erp/app/modules/production/ui/Assemblies/AssemblyInstructionProperties.tsx b/apps/erp/app/modules/production/ui/Assemblies/AssemblyInstructionProperties.tsx
index 4c8a8ee6a5..263ced9247 100644
--- a/apps/erp/app/modules/production/ui/Assemblies/AssemblyInstructionProperties.tsx
+++ b/apps/erp/app/modules/production/ui/Assemblies/AssemblyInstructionProperties.tsx
@@ -85,6 +85,7 @@ import AssemblyStepMaterials from "./AssemblyStepMaterials";
import AssemblyStepSlides from "./AssemblyStepSlides";
import { AssemblyStepStatus, normalizeStepStatus } from "./AssemblyStepStatus";
import AssemblyStepTools from "./AssemblyStepTools";
+import SubAssemblyPathRow from "./AssemblySubAssemblyPathRow";
import AssemblySubAssemblyProperties from "./AssemblySubAssemblyProperties";
type AssemblyInstructionPropertiesProps = {
@@ -110,8 +111,13 @@ type AssemblyInstructionPropertiesProps = {
onSetHiddenComponents: (nodeIds: string[]) => void;
/** The active step's motion path is open in the 3D editor */
isEditingMotion: boolean;
- onEditMotion: (stepId: string) => void;
+ /** The sub-assembly whose joining path is open in the 3D editor, if any */
+ editingUnitId: string | null;
+ /** Opens the editor on a step's motion, or on a sub-assembly it carries in */
+ onEditMotion: (stepId: string, unitHeaderId?: string) => void;
onStopEditMotion: () => void;
+ /** Clears a sub-assembly's path back to the automatic glide */
+ onResetUnitMotion: (headerId: string) => void;
onSetCamera: (stepId: string) => void;
onClearCamera: (stepId: string) => void;
/** Every step of the instruction, in play order — numbering and sub-assemblies */
@@ -138,8 +144,10 @@ const AssemblyInstructionProperties = ({
hiddenNodeIds,
onSetHiddenComponents,
isEditingMotion,
+ editingUnitId,
onEditMotion,
onStopEditMotion,
+ onResetUnitMotion,
onSetCamera,
onClearCamera,
viewerSteps,
@@ -274,6 +282,10 @@ const AssemblyInstructionProperties = ({
onSelectStep={onSelectStep}
onSetCamera={onSetCamera}
onClearCamera={onClearCamera}
+ editingUnitId={editingUnitId}
+ onEditMotion={onEditMotion}
+ onStopEditMotion={onStopEditMotion}
+ onResetUnitMotion={onResetUnitMotion}
/>
) : step ? (
<Tabs defaultValue="details" className="w-full px-4 pb-2 pt-3">
@@ -311,8 +323,10 @@ const AssemblyInstructionProperties = ({
hiddenNodeIds={hiddenNodeIds}
onSetHiddenComponents={onSetHiddenComponents}
isEditingMotion={isEditingMotion}
+ editingUnitId={editingUnitId}
onEditMotion={onEditMotion}
onStopEditMotion={onStopEditMotion}
+ onResetUnitMotion={onResetUnitMotion}
onSetCamera={onSetCamera}
onClearCamera={onClearCamera}
viewerSteps={viewerSteps}
@@ -434,8 +448,10 @@ function StepForm({
hiddenNodeIds,
onSetHiddenComponents,
isEditingMotion,
+ editingUnitId,
onEditMotion,
onStopEditMotion,
+ onResetUnitMotion,
onSetCamera,
onClearCamera,
viewerSteps,
@@ -458,8 +474,10 @@ function StepForm({
hiddenNodeIds: string[];
onSetHiddenComponents: (nodeIds: string[]) => void;
isEditingMotion: boolean;
- onEditMotion: (stepId: string) => void;
+ editingUnitId: string | null;
+ onEditMotion: (stepId: string, unitHeaderId?: string) => void;
onStopEditMotion: () => void;
+ onResetUnitMotion: (headerId: string) => void;
onSetCamera: (stepId: string) => void;
onClearCamera: (stepId: string) => void;
viewerSteps: AssemblyStep[];
@@ -523,6 +541,16 @@ function StepForm({
[step.warnings, graphIndex]
);
+ const carriedIn = useMemo(
+ () =>
+ viewerSteps.filter(
+ (viewerStep) =>
+ subPlan.get(viewerStep.id)?.isHeader &&
+ viewerStep.usedInStepId === step.id
+ ),
+ [viewerSteps, subPlan, step.id]
+ );
+
return (
<ValidatedForm
validator={assemblyInstructionStepValidator}
@@ -684,6 +712,18 @@ function StepForm({
</Button>
)}
</PlaybackRow>
+ {carriedIn.map((header) => (
+ <SubAssemblyPathRow
+ key={header.id}
+ name={titleOf(header.id)}
+ hasPath={header.motion.type !== "none"}
+ isEditing={editingUnitId === header.id}
+ isDisabled={isDisabled}
+ onEdit={() => onEditMotion(step.id, header.id)}
+ onStopEdit={onStopEditMotion}
+ onReset={() => onResetUnitMotion(header.id)}
+ />
+ ))}
<PlaybackRow
label={
<LabelWithHelp termId="assembly-step-camera" variant="inline">
diff --git a/apps/erp/app/modules/production/ui/Assemblies/AssemblyPlaybackRow.tsx b/apps/erp/app/modules/production/ui/Assemblies/AssemblyPlaybackRow.tsx
index 06ee0beefe..a99be7e748 100644
--- a/apps/erp/app/modules/production/ui/Assemblies/AssemblyPlaybackRow.tsx
+++ b/apps/erp/app/modules/production/ui/Assemblies/AssemblyPlaybackRow.tsx
@@ -17,7 +17,7 @@ export default function PlaybackRow({
return (
<div className="flex w-full items-center justify-between gap-2 px-3 py-2">
<VStack spacing={0} className="min-w-0 flex-1">
- <span className="text-xs font-medium text-muted-foreground">
+ <span className="max-w-full text-xs font-medium text-muted-foreground">
{label}
</span>
{value && (
diff --git a/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyPathRow.tsx b/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyPathRow.tsx
new file mode 100644
index 0000000000..9441c5a701
--- /dev/null
+++ b/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyPathRow.tsx
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
+// including ports, remain AGPLv3; serving them over a network requires releasing their source.
+
+import { Button, HStack, LabelWithHelp } from "@carbon/react";
+import { Trans } from "@lingui/react/macro";
+import PlaybackRow from "./AssemblyPlaybackRow";
+
+/**
+ * The path a finished sub-assembly travels when it joins the build. Edited in
+ * the 3D viewer like a step's motion; Reset returns it to the automatic glide.
+ */
+export default function SubAssemblyPathRow({
+ name,
+ hasPath,
+ isEditing,
+ isDisabled,
+ onEdit,
+ onStopEdit,
+ onReset
+}: {
+ name: string;
+ hasPath: boolean;
+ isEditing: boolean;
+ isDisabled: boolean;
+ onEdit: () => void;
+ onStopEdit: () => void;
+ onReset: () => void;
+}) {
+ return (
+ <PlaybackRow
+ label={
+ // A long sub-assembly name ends in an ellipsis instead of running
+ // under the buttons.
+ <LabelWithHelp
+ termId="assembly-sub-assembly-path"
+ variant="inline"
+ className="max-w-full [&>span:first-child]:min-w-0 [&>span:first-child]:truncate"
+ >
+ <Trans>{name} path</Trans>
+ </LabelWithHelp>
+ }
+ value={
+ isEditing ? (
+ <Trans>Drag the red waypoints in the viewer</Trans>
+ ) : hasPath ? (
+ <Trans>Custom path</Trans>
+ ) : (
+ <Trans>Automatic</Trans>
+ )
+ }
+ >
+ {!isDisabled && (
+ <HStack spacing={1} className="shrink-0">
+ {hasPath && !isEditing && (
+ <Button variant="ghost" size="sm" onClick={onReset}>
+ <Trans>Reset</Trans>
+ </Button>
+ )}
+ <Button
+ variant={isEditing ? "primary" : "secondary"}
+ size="sm"
+ onClick={isEditing ? onStopEdit : onEdit}
+ >
+ {isEditing ? (
+ <Trans>Done Editing Path</Trans>
+ ) : (
+ <Trans>Edit Path</Trans>
+ )}
+ </Button>
+ </HStack>
+ )}
+ </PlaybackRow>
+ );
+}
diff --git a/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyProperties.tsx b/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyProperties.tsx
index e633d24bf4..85f3688b9f 100644
--- a/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyProperties.tsx
+++ b/apps/erp/app/modules/production/ui/Assemblies/AssemblySubAssemblyProperties.tsx
@@ -31,6 +31,7 @@ import { assemblyInstructionStepValidator } from "../../production.models";
import type { AssemblyInstructionStepRow } from "../../types";
import PlaybackRow from "./AssemblyPlaybackRow";
import { SUB_ASSEMBLY_PARAM } from "./AssemblyStepList";
+import SubAssemblyPathRow from "./AssemblySubAssemblyPathRow";
type AssemblySubAssemblyPropertiesProps = {
step: AssemblyInstructionStepRow;
@@ -43,6 +44,10 @@ type AssemblySubAssemblyPropertiesProps = {
onSelectStep: (stepId: string) => void;
onSetCamera: (stepId: string) => void;
onClearCamera: (stepId: string) => void;
+ editingUnitId: string | null;
+ onEditMotion: (stepId: string, unitHeaderId?: string) => void;
+ onStopEditMotion: () => void;
+ onResetUnitMotion: (headerId: string) => void;
};
/**
@@ -59,7 +64,11 @@ export default function AssemblySubAssemblyProperties({
itemMentions,
onSelectStep,
onSetCamera,
- onClearCamera
+ onClearCamera,
+ editingUnitId,
+ onEditMotion,
+ onStopEditMotion,
+ onResetUnitMotion
}: AssemblySubAssemblyPropertiesProps) {
const { id: instructionId } = useParams();
if (!instructionId) throw new Error("Could not find id");
@@ -132,6 +141,10 @@ export default function AssemblySubAssemblyProperties({
);
const cannotSave = isDisabled || !permissions.can("update", "production");
+ // The checked motion the player plays (a malformed row reads as "none").
+ const hasOwnPath =
+ (viewerSteps.find((viewerStep) => viewerStep.id === step.id)?.motion.type ??
+ "none") !== "none";
const hasCamera = step.camera != null;
const name = step.title || t`Sub-Assembly`;
@@ -280,6 +293,18 @@ export default function AssemblySubAssemblyProperties({
</DropdownMenu>
)}
</PlaybackRow>
+ {/* Nothing uses it: it joins the main build here, on this path. */}
+ {!usedIn && (
+ <SubAssemblyPathRow
+ name={name}
+ hasPath={hasOwnPath}
+ isEditing={editingUnitId === step.id}
+ isDisabled={isDisabled}
+ onEdit={() => onEditMotion(step.id, step.id)}
+ onStopEdit={onStopEditMotion}
+ onReset={() => onResetUnitMotion(step.id)}
+ />
+ )}
{!usedIn && (
<PlaybackRow
label={
diff --git a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
index 6681069ba4..34858c50b1 100644
--- a/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
+++ b/apps/erp/app/routes/api+/mcp+/lib/tool-manifest.digest.json
@@ -665,7 +665,7 @@
{"name":"production_getAssemblyInstructionStepSlides","classification":"READ","paramCount":1,"schema":"0f56299d6859","response":"60aa9b57a118","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getAssemblyInstructionStepTools","classification":"READ","paramCount":1,"schema":"0f56299d6859","response":"d771814f7578","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getAssemblyInstructionVersions","classification":"READ","paramCount":2,"schema":"0c21424ecd86","response":"81c6e04c54bd","injectAuth":"companyId","permission":"production:view","paginates":false},
- {"name":"production_getAssemblyPlanJson","classification":"READ","paramCount":1,"schema":"277f7d872d8c","response":"9e6f9653f3fd","injectAuth":"companyId","permission":"production:view","paginates":false},
+ {"name":"production_getAssemblyPlanJson","classification":"READ","paramCount":1,"schema":"277f7d872d8c","response":"d73d9f72bafb","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getAssemblyUnits","classification":"READ","paramCount":1,"schema":"277f7d872d8c","response":"7224ef8546c1","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getBatchableOperations","classification":"READ","paramCount":2,"schema":"4cebb10b56d4","response":"3d084de5e690","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getBatchableProcesses","classification":"READ","paramCount":0,"schema":"efddc7bd8bbc","response":"b0ab8957f96e","injectAuth":"companyId","permission":"production:view","paginates":false},
@@ -764,7 +764,7 @@
{"name":"production_getWorkCenterRequiredAbilities","classification":"READ","paramCount":1,"schema":"de371a276a58","response":"7418ea1fc0a7","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getWorkCenterReservationsRange","classification":"READ","paramCount":2,"schema":"99ea73b8e7a1","response":"a7e9bc09d2ab","injectAuth":"companyId","permission":"production:view","paginates":false},
{"name":"production_getWorkCenterShifts","classification":"READ","paramCount":1,"schema":"e94892850934","response":"2b4835f80e6c","injectAuth":"companyId","permission":"production:view","paginates":false},
- {"name":"production_insertAssemblyInstructionStep","classification":"WRITE","paramCount":1,"schema":"432e9ed9373b","response":"00404e686415","injectAuth":"companyId+createdBy+updatedBy+userId","permission":"production:create","paginates":false},
+ {"name":"production_insertAssemblyInstructionStep","classification":"WRITE","paramCount":1,"schema":"f14d1689b7f8","response":"00404e686415","injectAuth":"companyId+createdBy+updatedBy+userId","permission":"production:create","paginates":false},
{"name":"production_insertJob","classification":"WRITE","paramCount":2,"schema":"231e1d7f0444","response":"ad63dfd9d877","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create","paginates":false},
{"name":"production_invalidateAssemblyModelCache","classification":"DESTRUCTIVE","paramCount":1,"schema":"277f7d872d8c","response":"bcde375ebd4c","injectAuth":"companyId","permission":"production:update","paginates":false},
{"name":"production_makeAssemblySubAssembly","classification":"WRITE","paramCount":2,"schema":"e39572ccf46c","response":"00404e686415","injectAuth":"companyId+userId","permission":"production:update","paginates":false},
@@ -789,7 +789,7 @@
{"name":"production_setPeopleOvertimeBulk","classification":"WRITE","paramCount":6,"schema":"8f082483561d","response":"577d7088b794","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
{"name":"production_syncAssemblyInstructionToOperation","classification":"DESTRUCTIVE","paramCount":2,"schema":"8160f8d92b1b","response":"4348d3bad80b","injectAuth":"companyId+updatedBy+userId","permission":"production:update","paginates":false},
{"name":"production_syncAssemblyStepMaterialsFromMappings","classification":"WRITE","paramCount":4,"schema":"7f7346bb3bd0","response":"5815c4dbf43d","injectAuth":"companyId+updatedBy+userId","permission":"production:update","paginates":false},
- {"name":"production_toViewerStep","classification":"WRITE","paramCount":1,"schema":"79b0e8edd0b6","response":"e3a6f6608ca6","injectAuth":"companyId","permission":"production:update","paginates":false},
+ {"name":"production_toViewerStep","classification":"WRITE","paramCount":1,"schema":"79b0e8edd0b6","response":"a15b53344e15","injectAuth":"companyId","permission":"production:update","paginates":false},
{"name":"production_unassignPeopleWeek","classification":"DESTRUCTIVE","paramCount":4,"schema":"06ead5d3d9ce","response":"9658926b2cd2","injectAuth":"companyId","permission":"production:update","paginates":false},
{"name":"production_ungroupAssemblySubAssembly","classification":"DESTRUCTIVE","paramCount":2,"schema":"4bb5885b787b","response":"none","injectAuth":"companyId+userId","permission":"production:update","paginates":false},
{"name":"production_unreleaseJobOperationBatch","classification":"WRITE","paramCount":1,"schema":"979f64cb9229","response":"9e056a59d695","injectAuth":"companyId+userId","permission":"production:update","paginates":false},
@@ -799,7 +799,7 @@
{"name":"production_updateAssemblyInstructionStepStatus","classification":"WRITE","paramCount":2,"schema":"9291eed55a4a","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
{"name":"production_updateAssemblyStepComponents","classification":"WRITE","paramCount":2,"schema":"d7ea6b1800f7","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
{"name":"production_updateAssemblyStepHiddenComponents","classification":"WRITE","paramCount":3,"schema":"3ac4e88c4df0","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
- {"name":"production_updateAssemblyStepMotion","classification":"WRITE","paramCount":3,"schema":"6665a9b53a17","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
+ {"name":"production_updateAssemblyStepMotion","classification":"WRITE","paramCount":3,"schema":"9a6ccd4d78c9","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
{"name":"production_updateAssemblySubAssembly","classification":"WRITE","paramCount":4,"schema":"0f0cbf9e32e1","response":"none","injectAuth":"companyId+updatedBy+userId","permission":"production:update","paginates":false},
{"name":"production_updateJob","classification":"WRITE","paramCount":22,"schema":"fc37d97579b2","response":"3797626bd17e","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
{"name":"production_updateJobBatchNumber","classification":"WRITE","paramCount":2,"schema":"a4c2a31bb8a6","response":"f7a40899c090","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false},
@@ -816,7 +816,7 @@
{"name":"production_updateQuoteOperationStepOrder","classification":"WRITE","paramCount":1,"schema":"d19d08f2d129","response":"646de62ab761","injectAuth":"companyId+updatedBy","permission":"production:update","paginates":false,"result":"envelopes"},
{"name":"production_upsertAssemblyComponentMapping","classification":"WRITE","paramCount":4,"schema":"9ed1f38ce764","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
{"name":"production_upsertAssemblyInstruction","classification":"WRITE","paramCount":4,"schema":"a1796f1bd347","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
- {"name":"production_upsertAssemblyInstructionStep","classification":"WRITE","paramCount":1,"schema":"224cc2443995","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
+ {"name":"production_upsertAssemblyInstructionStep","classification":"WRITE","paramCount":1,"schema":"28bd332a0905","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
{"name":"production_upsertAssemblyInstructionStepMaterial","classification":"WRITE","paramCount":5,"schema":"a21b4fac4b90","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
{"name":"production_upsertAssemblyInstructionStepSlide","classification":"WRITE","paramCount":9,"schema":"6be3bd248d68","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false,"upsert":"id"},
{"name":"production_upsertAssemblyInstructionStepTool","classification":"WRITE","paramCount":5,"schema":"d64500fd5c94","response":"3797626bd17e","injectAuth":"companyId+createdBy+updatedBy","permission":"production:create+update","paginates":false},
diff --git a/apps/erp/app/routes/x+/assembly+/$id.tsx b/apps/erp/app/routes/x+/assembly+/$id.tsx
index 4399a9ce51..4f55aaac50 100644
--- a/apps/erp/app/routes/x+/assembly+/$id.tsx
+++ b/apps/erp/app/routes/x+/assembly+/$id.tsx
@@ -424,6 +424,10 @@ export default function AssemblyInstructionRoute() {
const carriedIn = (activeInfo?.carriesIn ?? []).filter(
(headerId) => headerId !== playerStepId
);
+ const pathToolLabels = useMemo(
+ () => ({ move: t`Move`, rotate: t`Rotate` }),
+ [t]
+ );
const carryInLabel =
carriedIn.length > 0
? carriedIn
@@ -445,6 +449,7 @@ export default function AssemblyInstructionRoute() {
setIsAddingComponents(false);
// Leave any open motion-path edit session when moving to another step.
setEditingStepId(null);
+ setEditingUnitId(null);
setDraftMotion(null);
// Changing steps drops any isolate — the new step's parts should be visible.
setFocusedNodeIds([]);
@@ -618,6 +623,9 @@ export default function AssemblyInstructionRoute() {
const playerRef = useRef<AssemblyPlayerHandle>(null);
const motionFetcher = useFetcher<{ success: boolean }>();
const [editingStepId, setEditingStepId] = useState<string | null>(null);
+ // Editing the path of a sub-assembly the step carries in (saved on its
+ // header row) instead of the step's own motion.
+ const [editingUnitId, setEditingUnitId] = useState<string | null>(null);
const [draftMotion, setDraftMotion] = useState<Motion | null>(null);
const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -639,26 +647,38 @@ export default function AssemblyInstructionRoute() {
);
const onEditMotion = useCallback(
- (stepId: string) => {
- const viewerStep = viewerSteps.find((s) => s.id === stepId);
+ (stepId: string, unitHeaderId?: string) => {
+ const edited = viewerSteps.find((s) => s.id === (unitHeaderId ?? stepId));
setSelectedStepId(stepId);
setEditingStepId(stepId);
- setDraftMotion(viewerStep?.motion ?? { type: "none" });
+ setEditingUnitId(unitHeaderId ?? null);
+ setDraftMotion(edited?.motion ?? { type: "none" });
},
[viewerSteps]
);
const onStopEditMotion = useCallback(() => {
setEditingStepId(null);
+ setEditingUnitId(null);
setDraftMotion(null);
}, []);
const onMotionChange = useCallback(
(stepId: string, motion: Motion) => {
setDraftMotion(motion);
+ // A sub-assembly's path lives on its header row.
+ const targetId = editingUnitId ?? stepId;
if (saveTimer.current) clearTimeout(saveTimer.current);
- saveTimer.current = setTimeout(() => saveMotion(stepId, { motion }), 400);
+ saveTimer.current = setTimeout(
+ () => saveMotion(targetId, { motion }),
+ 400
+ );
},
+ [saveMotion, editingUnitId]
+ );
+
+ const onResetUnitMotion = useCallback(
+ (headerId: string) => saveMotion(headerId, { motion: { type: "none" } }),
[saveMotion]
);
@@ -679,8 +699,14 @@ export default function AssemblyInstructionRoute() {
[saveMotion]
);
- const isEditingSelectedMotion =
+ const isEditingSelected =
editingStepId !== null && selectedStep?.id === editingStepId;
+ const isEditingSelectedMotion = isEditingSelected && editingUnitId === null;
+ const editingUnitPartIds = useMemo(
+ () =>
+ editingUnitId ? subAssemblyPartIds(viewerSteps, editingUnitId) : null,
+ [editingUnitId, viewerSteps]
+ );
return (
<PanelProvider key={id}>
@@ -754,6 +780,7 @@ export default function AssemblyInstructionRoute() {
scopeStepIds={scopeStepIds}
isolationLabel={isolationLabel}
carryInLabel={carryInLabel}
+ pathToolLabels={pathToolLabels}
activeStepIndex={Math.max(playerStepIndex, 0)}
playFromStepIndex={playFromStepIndex}
playStepNonce={playStepNonce}
@@ -770,10 +797,14 @@ export default function AssemblyInstructionRoute() {
focusedNodeIds={focusedNodeIds}
readOnly={isDisabled}
editMotion={
- editingStepId &&
- selectedStep?.id === editingStepId &&
- draftMotion
- ? { stepId: editingStepId, motion: draftMotion }
+ editingStepId && isEditingSelected && draftMotion
+ ? {
+ stepId: editingStepId,
+ motion: draftMotion,
+ ...(editingUnitPartIds
+ ? { nodeIds: editingUnitPartIds }
+ : {})
+ }
: null
}
onMotionChange={onMotionChange}
@@ -848,8 +879,10 @@ export default function AssemblyInstructionRoute() {
hiddenNodeIds={selectedHiddenNodeIds}
onSetHiddenComponents={onSetHiddenComponents}
isEditingMotion={isEditingSelectedMotion}
+ editingUnitId={isEditingSelected ? editingUnitId : null}
onEditMotion={onEditMotion}
onStopEditMotion={onStopEditMotion}
+ onResetUnitMotion={onResetUnitMotion}
onSetCamera={onSetCamera}
onClearCamera={onClearCamera}
stepMaterials={selectedStepMaterials}
diff --git a/apps/mes/app/components/AssemblyView.tsx b/apps/mes/app/components/AssemblyView.tsx
index 876ed27f21..8b91e299cf 100644
--- a/apps/mes/app/components/AssemblyView.tsx
+++ b/apps/mes/app/components/AssemblyView.tsx
@@ -48,13 +48,12 @@ import {
useShortcutKeys
} from "@carbon/react";
import { distinctItemText, formatDurationMilliseconds } from "@carbon/utils";
-import type {
- AssemblyStep,
- CameraPose,
- Fastener,
- Motion
+import type { AssemblyStep, CameraPose, Fastener } from "@carbon/viewer";
+import {
+ AssemblyPlayer,
+ buildSubAssemblyPlan,
+ isPlayableMotion
} from "@carbon/viewer";
-import { AssemblyPlayer, buildSubAssemblyPlan } from "@carbon/viewer";
import { ModelPreview } from "@carbon/viewer/model-preview";
import { useLingui } from "@lingui/react/macro";
import { useEffect, useMemo, useRef, useState } from "react";
@@ -215,14 +214,11 @@ type AssemblyPlayback = {
}[];
};
-const playerMotionTypes = ["linear", "L", "helix", "path", "none"];
-
/** Opens a sub-assembly: the step bar and the player show only its steps. */
const SUB_ASSEMBLY_PARAM = "subAssembly";
// DB row → @carbon/viewer AssemblyStep.
function toViewerStep(step: AssemblyPlayback["steps"][number]): AssemblyStep {
- const motion = step.motion as Motion | null;
const warnings = step.warnings as { flagged?: boolean } | null;
return {
id: step.id,
@@ -233,12 +229,7 @@ function toViewerStep(step: AssemblyPlayback["steps"][number]): AssemblyStep {
parentStepId: step.parentStepId ?? null,
usedInStepId: step.usedInStepId ?? null,
isSubAssembly: step.isSubAssembly,
- motion:
- motion &&
- typeof motion === "object" &&
- playerMotionTypes.includes(motion.type)
- ? motion
- : { type: "none" },
+ motion: isPlayableMotion(step.motion) ? step.motion : { type: "none" },
camera: (step.camera as CameraPose | null) ?? null,
fastener: (step.fastener as Fastener | null) ?? null,
durationSeconds: step.durationSeconds,
diff --git a/docs/content/docs/reference/assembly-instructions.mdx b/docs/content/docs/reference/assembly-instructions.mdx
index 13322a8893..edf9b7f3c4 100644
--- a/docs/content/docs/reference/assembly-instructions.mdx
+++ b/docs/content/docs/reference/assembly-instructions.mdx
@@ -63,8 +63,9 @@ To expose obstructed work, select the eye on a row in the **Components** tab. Th
The **Playback** box sets how the step plays:
<FieldTable>
- <Field name="Motion">"Automatic" uses the path the planner found. **"Edit Path"** shows the path as red waypoints in the 3D view: drag one to reshape it, double-click the path to add one, and press Delete to remove the selected one. "No clear path" means the planner found none; hover the header note to see which parts block it.</Field>
+ <Field name="Motion">"Automatic" uses the path the planner found. **"Edit Path"** shows the path as red waypoints in the 3D view: drag one to reshape it, double-click the path to add one, and press Delete to remove the selected one. A see-through copy of the parts shows the selected waypoint's pose. Switch the viewer's **Move / Rotate** control to **Rotate** to get rotation rings on the selected waypoint: drag a ring to turn the part at that point (it snaps every 15°), so a part can be flipped on its way in. Switch back to **Move** to drag waypoints again. "No clear path" means the planner found none; hover the header note to see which parts block it.</Field>
<Field name="Camera">"Automatic" frames the step's parts on its own. **"Use Current View"** saves the angle you are looking from; **"Clear"** goes back to automatic.</Field>
+ <Field name="Sub-assembly path">One row per sub-assembly the step fits. "Automatic" slides the finished unit in from beside the build. **"Edit Path"** draws the path the whole unit travels, with the same waypoints and rotation rings; **"Reset"** goes back to automatic.</Field>
</FieldTable>
## Sub-assemblies
@@ -80,12 +81,13 @@ Selecting a sub-assembly shows its name, its steps, and **"Where it goes"**:
<FieldTable>
<Field name="Used in">The later step that fits the finished sub-assembly. Leave it on **"Main build (after its last step)"** when no step uses it, and it joins the build right after its own steps.</Field>
<Field name="Instruction">Shown only when no step uses it: what the operator reads as the finished sub-assembly joins the main build.</Field>
+ <Field name="Sub-assembly path">Shown only when no step uses it: the path the finished unit travels as it joins the main build, drawn with **"Edit Path"**.</Field>
<Field name="Camera">Shown only when no step uses it: the view for that moment, saved with **"Use Current View"**.</Field>
</FieldTable>
You can also set this from the other side: on a step, **"Use Sub-Assembly"** picks a finished sub-assembly to fit in that step. The step's row then shows **"Uses 4"**.
-During playback a sub-assembly's steps play in order on their own, and the finished unit glides in at the step that uses it. Pressing play with a sub-assembly selected builds it from its first step.
+During playback a sub-assembly's steps play in order on their own, and the finished unit arrives at the step that uses it: along its own path when it has one, otherwise gliding in from beside the build. A unit with its own path arrives before the step's other parts move; when a step fits several, they arrive one after another. Pressing play with a sub-assembly selected builds it from its first step.
**"Ungroup"** removes the sub-assembly and keeps its steps in the main list. **"Delete Sub-Assembly"** removes it together with its steps.
@@ -117,7 +119,7 @@ On the shop floor the operation opens the [guided assembly view](/docs/reference
- Routes: list `/x/production/assemblies`, editor `/x/assembly/:id`. Tables: `assemblyInstruction` (row per version, grouped by `rootInstructionId ?? id`), `assemblyInstructionStep`, `assemblyInstructionStepMaterial`, `assemblyInstructionStepSlide`, `assemblyInstructionStepTool`.
- Editing is Draft-only in the UI (`isDisabled = status !== "Draft" || !can("update","production")`). "Make Active" shows on any non-Published version, Archived included.
- Step status DB meaning: Todo = new manual step, Review = planner-generated, Done = author-validated. New steps default to Todo with `planConfidence` "manual".
-- Sub-assemblies: a header row has `assemblyInstructionStep.isSubAssembly`; its steps have `parentStepId` = the header and are stored directly before it in `sortOrder`; the header's `usedInStepId` is the step that fits it (NULL = joins the main build at the header). Rules shared by ERP, the server, and playback: `validateSubAssemblies` in `packages/viewer/src/subassembly.ts`. Header rows are never copied to job steps. The carried unit glides in over 1.2 s. The open sub-assembly is the `?subAssembly=` URL parameter.
+- Sub-assemblies: a header row has `assemblyInstructionStep.isSubAssembly`; its steps have `parentStepId` = the header and are stored directly before it in `sortOrder`; the header's `usedInStepId` is the step that fits it (NULL = joins the main build at the header). Rules shared by ERP, the server, and playback: `validateSubAssemblies` in `packages/viewer/src/subassembly.ts`. Header rows are never copied to job steps. The header's `motion` is the unit's own path (`none` = glide in over 1.2 s, then ride the using step's motion); units with a path play one after another before the step's own parts. Paths drawn with a turned waypoint save as the relative `waypoints` motion type (poses turn about the moving set's seated bounds center); unturned paths still save as `linear`/`L`. The open sub-assembly is the `?subAssembly=` URL parameter.
- Hidden parts: `assemblyInstructionStep.hiddenComponentNodeIds`; a DB trigger strips the step's own components on every write.
- Flash strings: "Step not found"; "Sub-assembly not found"; "This step is already a sub-assembly"; "This step is already in a sub-assembly"; "A sub-assembly can't be inside another sub-assembly"; "A sub-assembly's steps must come directly before it"; "A sub-assembly can only be used after it is built"; "A sub-assembly can't be used by one of its own steps"; "Only draft instructions can be edited"; "Failed to update hidden components"; "Failed to update step status"; "Failed to update assembly instruction step"; "Steps already exist — delete them before generating from the plan"; "Some steps are locked — cannot regenerate"; "The geometry service is unavailable — motion planning can't run right now."; "Motion planning is already running"; "This instruction has no processed model"; "The model must finish converting before planning"; "This job is locked — steps can't be synced to it"; "The selected item has no 3D model. Upload a STEP file on the item's Model tab first."; "Made assembly instruction active"; "Failed to make assembly instruction active".
- Planner offline: "The geometry service is offline — motion planning is unavailable right now." Generate is disabled until it is back.
diff --git a/docs/content/src/glossary/terms.ts b/docs/content/src/glossary/terms.ts
index 37fc3ebbca..136fe57840 100644
--- a/docs/content/src/glossary/terms.ts
+++ b/docs/content/src/glossary/terms.ts
@@ -97,7 +97,12 @@ export const terms = {
},
"assembly-step-motion": {
term: msg`Motion`,
- definition: msg`The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path.`,
+ definition: msg`The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint.`,
+ href: "/docs/reference/assembly-instructions#playback-settings"
+ },
+ "assembly-sub-assembly-path": {
+ term: msg`Sub-assembly path`,
+ definition: msg`The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build.`,
href: "/docs/reference/assembly-instructions#playback-settings"
},
"assembly-step-camera": {
diff --git a/packages/locale/locales/de/erp.po b/packages/locale/locales/de/erp.po
index 2d56019f6d..ab6498be36 100644
--- a/packages/locale/locales/de/erp.po
+++ b/packages/locale/locales/de/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} endet {end} (war {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} endet {end} (war unbegrenzt)"
+msgid "{name} path"
+msgstr "{name} Pfad"
+
msgid "{name} replaced"
msgstr "{name} wurde ersetzt"
@@ -6023,6 +6026,9 @@ msgstr "Benutzerdefinierte Felder"
msgid "Custom fields are not available for items yet."
msgstr "Benutzerdefinierte Felder sind für Artikel noch nicht verfügbar."
+msgid "Custom path"
+msgstr "Benutzerdefinierter Pfad"
+
msgid "Custom SOW · we manage"
msgstr "Benutzerdefiniertes SOW · wir verwalten"
@@ -17599,6 +17605,9 @@ msgstr "Rollen, die Standardberechtigungen für neue Mitarbeiter festlegen"
msgid "Room to grow without bolting on more tools"
msgstr "Platz zum Wachsen ohne zusätzliche Tools"
+msgid "Rotate"
+msgstr "Drehen"
+
msgid "Rounding Account"
msgstr "Rundungskonto"
@@ -19659,6 +19668,9 @@ msgstr "Unterbaugruppe {number}"
msgid "Sub-assembly expiries only"
msgstr "Nur Ablauf von Baugruppen"
+msgid "Sub-assembly path"
+msgstr "Baugruppen-Pfad"
+
msgid "Sub-Departments"
msgstr "Unterbereiche"
@@ -20865,8 +20877,11 @@ msgstr "Der Teil wird als eigener Auftrag hergestellt, wenn das Elternteil, das
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "Der Teil wird dem bestehenden Bestand entnommen, wenn das übergeordnete Teil hergestellt wird – kein neuer Fertigungsauftrag oder Bestellung."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Der Pfad, auf dem die Komponenten dieses Schritts während der Wiedergabe an ihren Platz fahren; aus dem Modell ermittelt oder von Hand mit Bearbeitungspfad gezeichnet."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Der Pfad, den eine fertige Baugruppe nimmt, wenn sie in den Zusammenbau eintritt. Sie kommt vor den Teilen des Schritts. Bis du mit „Pfad bearbeiten“ einen zeichnest, gleitet sie von der Seite ein."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Der Pfad, den die Komponenten dieses Schritts während der Wiedergabe an ihren Platz fahren. Er wird aus dem Modell berechnet oder mit „Pfad bearbeiten“ von Hand gezeichnet. An jedem Wegpunkt kann ein Teil auch gedreht werden."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Das Personal auf der Carbon-Seite, das Ihre Umsetzung durchführt, und wie Sie sie erreichen."
diff --git a/packages/locale/locales/en/erp.po b/packages/locale/locales/en/erp.po
index 47d70cc63c..5025b5fdac 100644
--- a/packages/locale/locales/en/erp.po
+++ b/packages/locale/locales/en/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} ends {end} (was {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} ends {end} (was open-ended)"
+msgid "{name} path"
+msgstr "{name} path"
+
msgid "{name} replaced"
msgstr "{name} replaced"
@@ -6023,6 +6026,9 @@ msgstr "Custom Fields"
msgid "Custom fields are not available for items yet."
msgstr "Custom fields are not available for items yet."
+msgid "Custom path"
+msgstr "Custom path"
+
msgid "Custom SOW · we manage"
msgstr "Custom SOW · we manage"
@@ -17599,6 +17605,9 @@ msgstr "Roles that set default permissions for new employees"
msgid "Room to grow without bolting on more tools"
msgstr "Room to grow without bolting on more tools"
+msgid "Rotate"
+msgstr "Rotate"
+
msgid "Rounding Account"
msgstr "Rounding Account"
@@ -19659,6 +19668,9 @@ msgstr "Sub-Assembly {number}"
msgid "Sub-assembly expiries only"
msgstr "Sub-assembly expiries only"
+msgid "Sub-assembly path"
+msgstr "Sub-assembly path"
+
msgid "Sub-Departments"
msgstr "Sub-Departments"
@@ -20865,8 +20877,11 @@ msgstr "The part is manufactured as its own job when the parent that needs it is
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "The part is taken from existing stock when its parent is built — no new job or purchase order."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "The people on the Carbon side who will run your implementation, and how to reach them."
diff --git a/packages/locale/locales/es/erp.po b/packages/locale/locales/es/erp.po
index d111428d81..e89a87d6a3 100644
--- a/packages/locale/locales/es/erp.po
+++ b/packages/locale/locales/es/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} termina {end} (fue {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} termina {end} (fue abierto)"
+msgid "{name} path"
+msgstr "{name} trayectoria"
+
msgid "{name} replaced"
msgstr "{name} reemplazado"
@@ -6023,6 +6026,9 @@ msgstr "Campos Personalizados"
msgid "Custom fields are not available for items yet."
msgstr "Los campos personalizados aún no están disponibles para artículos."
+msgid "Custom path"
+msgstr "Trayectoria personalizada"
+
msgid "Custom SOW · we manage"
msgstr "SOW personalizado · nosotros gestionamos"
@@ -17599,6 +17605,9 @@ msgstr "Roles que establecen permisos predeterminados para nuevos empleados"
msgid "Room to grow without bolting on more tools"
msgstr "Espacio para crecer sin añadir más herramientas"
+msgid "Rotate"
+msgstr "Girar"
+
msgid "Rounding Account"
msgstr "Cuenta de redondeo"
@@ -19659,6 +19668,9 @@ msgstr "Subensamble {number}"
msgid "Sub-assembly expiries only"
msgstr "Solo vencimientos de subensamblajes"
+msgid "Sub-assembly path"
+msgstr "Trayectoria del subensamble"
+
msgid "Sub-Departments"
msgstr "Sub-Departamentos"
@@ -20865,8 +20877,11 @@ msgstr "La parte se fabrica como su propio trabajo cuando se construye el padre
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "La parte se toma del inventario existente cuando se construye su padre - sin nuevo trabajo o orden de compra."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "La ruta que los componentes de este paso recorren hasta su lugar durante la reproducción; se calcula a partir del modelo o se dibuja manualmente con Editar ruta."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "La trayectoria que recorre el subensamble terminado como una pieza cuando se une al conjunto. Llega antes que las piezas propias del paso; hasta que dibujes una con Editar trayectoria, se desliza desde un lado del conjunto."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "La trayectoria que los componentes de este paso recorren hacia su posición durante la reproducción; calculada a partir del modelo, o dibujada manualmente con Editar trayectoria, donde una pieza también puede girarse en cualquier punto de paso."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Las personas del lado de Carbon que ejecutarán tu implementación y cómo contactarlas."
diff --git a/packages/locale/locales/fr/erp.po b/packages/locale/locales/fr/erp.po
index fce339504b..5a932a8518 100644
--- a/packages/locale/locales/fr/erp.po
+++ b/packages/locale/locales/fr/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} se termine {end} (était {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} se termine {end} (était sans terme)"
+msgid "{name} path"
+msgstr "{name} chemin"
+
msgid "{name} replaced"
msgstr "{name} remplacé"
@@ -6023,6 +6026,9 @@ msgstr "Champs personnalisés"
msgid "Custom fields are not available for items yet."
msgstr "Les champs personnalisés ne sont pas encore disponibles pour les articles."
+msgid "Custom path"
+msgstr "Chemin personnalisé"
+
msgid "Custom SOW · we manage"
msgstr "SOW personnalisé · nous gérons"
@@ -17599,6 +17605,9 @@ msgstr "Rôles qui définissent les autorisations par défaut pour les nouveaux
msgid "Room to grow without bolting on more tools"
msgstr "Espace pour croître sans ajouter d'autres outils"
+msgid "Rotate"
+msgstr "Tourner"
+
msgid "Rounding Account"
msgstr "Compte d'arrondi"
@@ -19659,6 +19668,9 @@ msgstr "Sous-assemblage {number}"
msgid "Sub-assembly expiries only"
msgstr "Expiries des sous-ensembles uniquement"
+msgid "Sub-assembly path"
+msgstr "Chemin du sous-ensemble"
+
msgid "Sub-Departments"
msgstr "Sous-départements"
@@ -20865,8 +20877,11 @@ msgstr "La pièce est fabriquée comme son propre travail quand le parent qui en
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "La pièce est prélevée du stock existant lors de la construction de son parent - aucune nouvelle tâche ou bon de commande."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Le chemin que les composants de cette étape parcourent lors de la lecture ; calculé à partir du modèle ou dessiné manuellement avec Modifier le chemin."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Le chemin qu'un sous-ensemble fini parcourt comme une seule pièce quand il se joint à la construction. Il arrive avant les pièces de cette étape ; jusqu'à ce que vous en traciez un avec Modifier le chemin, il glisse depuis le côté de la construction."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Le chemin que les pièces de cette étape parcourent pour se mettre en place pendant la lecture ; calculé à partir du modèle, ou tracé à la main avec Modifier le chemin, où une pièce peut également être tournée à n'importe quel point."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Les personnes côté Carbon qui géreront votre mise en œuvre, et comment les contacter."
diff --git a/packages/locale/locales/hi/erp.po b/packages/locale/locales/hi/erp.po
index 1bc3f1181c..825477869c 100644
--- a/packages/locale/locales/hi/erp.po
+++ b/packages/locale/locales/hi/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} {end} को समाप्त होता है (पहले
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} {end} को समाप्त होता है (पहले खुली अवधि का था)"
+msgid "{name} path"
+msgstr "{name} मार्ग"
+
msgid "{name} replaced"
msgstr "{name} प्रतिस्थापित किया गया"
@@ -6023,6 +6026,9 @@ msgstr "कस्टम फील्ड्स"
msgid "Custom fields are not available for items yet."
msgstr "कस्टम फील्ड अभी आइटम के लिए उपलब्ध नहीं हैं।"
+msgid "Custom path"
+msgstr "कस्टम मार्ग"
+
msgid "Custom SOW · we manage"
msgstr "कस्टम SOW · हम प्रबंधित करते हैं"
@@ -17599,6 +17605,9 @@ msgstr "नई कर्मचारियों के लिए डिफ़
msgid "Room to grow without bolting on more tools"
msgstr "बिना अतिरिक्त उपकरण जोड़े बढ़ने की गुंजाइश"
+msgid "Rotate"
+msgstr "घुमाएँ"
+
msgid "Rounding Account"
msgstr "राउंडिंग खाता"
@@ -19659,6 +19668,9 @@ msgstr "उप-असेंबली {number}"
msgid "Sub-assembly expiries only"
msgstr "उप-विधानसभा समाप्ति केवल"
+msgid "Sub-assembly path"
+msgstr "सब-असेंबली मार्ग"
+
msgid "Sub-Departments"
msgstr "उप-विभाग"
@@ -20865,8 +20877,11 @@ msgstr "जब माता-पिता जो इसकी आवश्यक
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "पार्ट को मौजूदा स्टॉक से लिया जाता है जब इसका मूल आइटम बनाया जाता है — कोई नया जॉब या क्रय आदेश नहीं।"
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "वह पथ जो इस चरण के घटक प्लेबैक के दौरान स्थान पर यात्रा करते हैं; मॉडल से प्राप्त, या पथ संपादित करें के साथ हाथ से खींचा गया।"
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "यह मार्ग है जो एक तैयार सब-असेंबली एक टुकड़े के रूप में तय करती है जब यह बिल्ड से जुड़ता है। यह चरण के अपने पार्ट्स से पहले आती है; जब तक आप “पथ संपादित करें” से कोई मार्ग नहीं खींचते, यह बिल्ड के बगल से आती है।"
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "यह मार्ग है जो इस चरण के घटक चलाने के समय जगह में यात्रा करते हैं; यह मॉडल से प्राप्त है, या “पथ संपादित करें” से हाथ से खींचा जाता है, जहाँ एक पार्ट किसी भी वेपॉइंट पर घुमाया जा सकता है।"
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "कार्बन की ओर से वे लोग जो आपके कार्यान्वयन को चलाएंगे, और उन तक कैसे पहुंचें।"
diff --git a/packages/locale/locales/it/erp.po b/packages/locale/locales/it/erp.po
index d390932526..1be4aa4251 100644
--- a/packages/locale/locales/it/erp.po
+++ b/packages/locale/locales/it/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} termina {end} (era {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} termina {end} (era senza data di fine)"
+msgid "{name} path"
+msgstr "{name} percorso"
+
msgid "{name} replaced"
msgstr "{name} sostituito"
@@ -6023,6 +6026,9 @@ msgstr "Campi Personalizzati"
msgid "Custom fields are not available for items yet."
msgstr "I campi personalizzati non sono ancora disponibili per gli articoli."
+msgid "Custom path"
+msgstr "Percorso personalizzato"
+
msgid "Custom SOW · we manage"
msgstr "Custom SOW · gestiamo noi"
@@ -17599,6 +17605,9 @@ msgstr "Ruoli che impostano le autorizzazioni predefinite per i nuovi dipendenti
msgid "Room to grow without bolting on more tools"
msgstr "Spazio per crescere senza aggiungere altri strumenti"
+msgid "Rotate"
+msgstr "Ruota"
+
msgid "Rounding Account"
msgstr "Conto di arrotondamento"
@@ -19659,6 +19668,9 @@ msgstr "Sotto-assemblaggio {number}"
msgid "Sub-assembly expiries only"
msgstr "Solo scadenze dei sottoassiemi"
+msgid "Sub-assembly path"
+msgstr "Percorso del sottogruppo"
+
msgid "Sub-Departments"
msgstr "Sotto-Dipartimenti"
@@ -20865,8 +20877,11 @@ msgstr "La parte viene fabbricata come suo proprio lavoro quando il genitore che
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "La parte viene presa da scorte esistenti quando il suo genitore viene costruito - nessun nuovo lavoro o ordine di acquisto."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Il percorso che i componenti di questo passo percorrono durante la riproduzione; calcolato dal modello o disegnato manualmente con Modifica percorso."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Il percorso che il sottogruppo finito percorre come un pezzo quando si unisce alla costruzione. Arriva prima dei componenti del passo; finché non ne disegni uno con Modifica Percorso, entra scivolando da accanto alla costruzione."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Il percorso che i componenti di questo passo percorrono per posizionarsi durante la riproduzione; ricavato dal modello, o disegnato a mano con Modifica Percorso, dove un componente può anche essere ruotato in qualsiasi punto di passaggio."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Le persone del team Carbon che gestiranno la tua implementazione e come contattarle."
diff --git a/packages/locale/locales/ja/erp.po b/packages/locale/locales/ja/erp.po
index e422c8ca14..2181378cb3 100644
--- a/packages/locale/locales/ja/erp.po
+++ b/packages/locale/locales/ja/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} は {end} に終了します(以前は {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} は {end} に終了します(以前は期限なし)"
+msgid "{name} path"
+msgstr "{name}パス"
+
msgid "{name} replaced"
msgstr "{name} は交換されました"
@@ -6023,6 +6026,9 @@ msgstr "カスタムフィールド"
msgid "Custom fields are not available for items yet."
msgstr "品目のカスタムフィールドはまだ利用可能ではありません。"
+msgid "Custom path"
+msgstr "カスタムパス"
+
msgid "Custom SOW · we manage"
msgstr "カスタムSOW · 当社が管理"
@@ -17599,6 +17605,9 @@ msgstr "新しい従業員のデフォルト権限を設定するロール"
msgid "Room to grow without bolting on more tools"
msgstr "さらに多くのツールを追加することなく成長する余地"
+msgid "Rotate"
+msgstr "回転"
+
msgid "Rounding Account"
msgstr "丸めアカウント"
@@ -19659,6 +19668,9 @@ msgstr "サブアセンブリ {number}"
msgid "Sub-assembly expiries only"
msgstr "サブアセンブリの有効期限のみ"
+msgid "Sub-assembly path"
+msgstr "部分組立パス"
+
msgid "Sub-Departments"
msgstr "サブ部門"
@@ -20865,8 +20877,11 @@ msgstr "必要な親が構築される場合、部品は独自のジョブとし
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "部品はその親製品が製造されるときに既存在庫から取得されます。新しい製造指図または発注書は作成されません。"
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "このステップのコンポーネントが再生中に所定の位置に移動するパス。モデルから計算されるか、パスの編集で手動で描画されます"
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "完成した部分組立がビルドに加わる際に1つのピースとして移動するパス。ステップの部品より前に到着します。編集パスで描くまでは、ビルドの脇からスライドして現れます。"
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "再生中にこのステップのコンポーネントが所定の位置に移動するパス。モデルから計算されるか、編集パスで手描きされます。各ウェイポイントで部品を回転させることもできます。"
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "実装を実施する Carbon 側の人員および連絡方法"
diff --git a/packages/locale/locales/ko/erp.po b/packages/locale/locales/ko/erp.po
index 54f06767ab..bc51597bcb 100644
--- a/packages/locale/locales/ko/erp.po
+++ b/packages/locale/locales/ko/erp.po
@@ -465,6 +465,9 @@ msgstr "{name}은 {end}에 끝남 (이전: {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name}은 {end}에 끝남 (이전: 제한 없음)"
+msgid "{name} path"
+msgstr "{name} 경로"
+
msgid "{name} replaced"
msgstr "{name} 대체됨"
@@ -6023,6 +6026,9 @@ msgstr "사용자 정의 필드"
msgid "Custom fields are not available for items yet."
msgstr "품목에 사용자 정의 필드를 아직 사용할 수 없습니다."
+msgid "Custom path"
+msgstr "사용자 정의 경로"
+
msgid "Custom SOW · we manage"
msgstr "맞춤 SOW · 저희가 관리"
@@ -17599,6 +17605,9 @@ msgstr "신규 직원의 기본 권한을 설정하는 역할"
msgid "Room to grow without bolting on more tools"
msgstr "추가 도구 없이도 성장할 수 있는 여유"
+msgid "Rotate"
+msgstr "회전"
+
msgid "Rounding Account"
msgstr "반올림 계정"
@@ -19659,6 +19668,9 @@ msgstr "소조립 {number}"
msgid "Sub-assembly expiries only"
msgstr "하위 조립품 유효기한만"
+msgid "Sub-assembly path"
+msgstr "소부조립품 경로"
+
msgid "Sub-Departments"
msgstr "하위 부서"
@@ -20865,8 +20877,11 @@ msgstr "상위 품목이 제작될 때 이 품목은 별도의 작업으로 제
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "부품은 상위 부품이 구축될 때 기존 재고에서 가져오므로, 새로운 작업 지시 또는 발주서가 없습니다."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "이 단계의 구성 요소가 재생 중에 제자리로 이동하는 경로; 모델에서 계산되거나 편집 경로를 사용하여 손으로 그려짐."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "완성된 소부조립품이 조립에 참여할 때 하나의 부분으로 이동하는 경로입니다. 단계의 자체 부품이 도착하기 전에 도착하며, 경로 편집으로 직접 그릴 때까지 조립 옆에서 들어옵니다."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "이 단계의 부품이 재생 중에 제자리로 이동하는 경로입니다. 모델에서 계산되거나 경로 편집으로 직접 그릴 수 있으며, 모든 웨이포인트에서 부품을 회전시킬 수 있습니다."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "귀사의 실행을 담당할 Carbon 팀 인원 및 연락 방법입니다."
diff --git a/packages/locale/locales/pl/erp.po b/packages/locale/locales/pl/erp.po
index 104f51c811..b052d0d25a 100644
--- a/packages/locale/locales/pl/erp.po
+++ b/packages/locale/locales/pl/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} kończy się {end} (było {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} kończy się {end} (było otwarte)"
+msgid "{name} path"
+msgstr "{name} ścieżka"
+
msgid "{name} replaced"
msgstr "{name} zastąpiono"
@@ -6023,6 +6026,9 @@ msgstr "Pola niestandardowe"
msgid "Custom fields are not available for items yet."
msgstr "Pola niestandardowe nie są jeszcze dostępne dla artykułów."
+msgid "Custom path"
+msgstr "Niestandardowa ścieżka"
+
msgid "Custom SOW · we manage"
msgstr "Niestandardowy SOW · zarządzamy"
@@ -17599,6 +17605,9 @@ msgstr "Role, które ustawiają domyślne uprawnienia dla nowych pracowników"
msgid "Room to grow without bolting on more tools"
msgstr "Miejsce do wzrostu bez dodawania kolejnych narzędzi"
+msgid "Rotate"
+msgstr "Obróć"
+
msgid "Rounding Account"
msgstr "Konto zaokrąglające"
@@ -19659,6 +19668,9 @@ msgstr "Podzespół {number}"
msgid "Sub-assembly expiries only"
msgstr "Tylko wygaśnięcia podzespołów"
+msgid "Sub-assembly path"
+msgstr "Ścieżka podzespołu"
+
msgid "Sub-Departments"
msgstr "Poddziały"
@@ -20865,8 +20877,11 @@ msgstr "Część jest wytwarzana jako swoje własne zadanie, gdy rodzic, który
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "Część jest pobierana z istniejących zapasów, gdy jego rodzic jest zbudowany - bez nowego zadania lub zamówienia zakupu."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Ścieżka, którą komponenty tego kroku przechodzą podczas odtwarzania; wyznaczona z modelu lub narysowana ręcznie za pomocą opcji Edytuj ścieżkę."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Ścieżka, jaką pokonuje gotowy podzespół jako jeden element, gdy dołącza się do budowy. Pojawia się przed własnymi częściami kroku; dopóki jej nie narysujesz za pomocą Edytuj ścieżkę, wsuwa się ze strony budowy."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Ścieżka, jaką komponenty tego kroku trafiają na miejsce podczas odtwarzania; wyznaczona na podstawie modelu lub narysowana ręcznie za pomocą Edytuj ścieżkę, gdzie część może być również obrócona w każdym punkcie."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Pracownicy po stronie Carbon, którzy będą prowadzić Twoje wdrożenie, oraz jak ich osiągnąć."
diff --git a/packages/locale/locales/pt/erp.po b/packages/locale/locales/pt/erp.po
index 6e30e40234..6f11e7d3c0 100644
--- a/packages/locale/locales/pt/erp.po
+++ b/packages/locale/locales/pt/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} termina {end} (era {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} termina {end} (era sem data de término)"
+msgid "{name} path"
+msgstr "{name} trajetória"
+
msgid "{name} replaced"
msgstr "{name} substituído"
@@ -6023,6 +6026,9 @@ msgstr "Campos Personalizados"
msgid "Custom fields are not available for items yet."
msgstr "Os campos personalizados ainda não estão disponíveis para itens."
+msgid "Custom path"
+msgstr "Trajetória personalizada"
+
msgid "Custom SOW · we manage"
msgstr "SOW personalizado · gerenciamos"
@@ -17599,6 +17605,9 @@ msgstr "Funções que definem permissões padrão para novos funcionários"
msgid "Room to grow without bolting on more tools"
msgstr "Espaço para crescer sem adicionar mais ferramentas"
+msgid "Rotate"
+msgstr "Girar"
+
msgid "Rounding Account"
msgstr "Conta de arredondamento"
@@ -19659,6 +19668,9 @@ msgstr "Sub-Montagem {number}"
msgid "Sub-assembly expiries only"
msgstr "Apenas expirações de subconjuntos"
+msgid "Sub-assembly path"
+msgstr "Trajetória de sub-montagem"
+
msgid "Sub-Departments"
msgstr "Sub-Departamentos"
@@ -20865,8 +20877,11 @@ msgstr "A peça é fabricada como seu próprio trabalho quando o pai que a neces
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "A peça é retirada do estoque existente quando seu pai é construído - nenhum novo trabalho ou pedido de compra."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "O caminho que os componentes desta etapa percorrem até sua posição durante a reprodução; calculado a partir do modelo ou desenhado manualmente com Editar Caminho."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "A trajetória que a sub-montagem acabada percorre como uma peça única quando se integra à montagem. Ela chega antes das próprias peças da etapa; até você desenhar uma com Editar Trajetória, ela desliza pela lateral da montagem."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "A trajetória que os componentes da etapa percorrem para se posicionarem durante a reprodução; calculada a partir do modelo ou desenhada manualmente com Editar Trajetória, onde uma peça também pode ser girada em qualquer ponto de passagem."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "As pessoas do lado da Carbon que executarão sua implementação e como contatá-las."
diff --git a/packages/locale/locales/ru/erp.po b/packages/locale/locales/ru/erp.po
index 83854fd9dd..3a5b865e60 100644
--- a/packages/locale/locales/ru/erp.po
+++ b/packages/locale/locales/ru/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} заканчивается {end} (было {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} заканчивается {end} (было открыто)"
+msgid "{name} path"
+msgstr "{name} траектория"
+
msgid "{name} replaced"
msgstr "{name} заменено"
@@ -6023,6 +6026,9 @@ msgstr "Пользовательские поля"
msgid "Custom fields are not available for items yet."
msgstr "Пользовательские поля еще не доступны для номенклатуры."
+msgid "Custom path"
+msgstr "Пользовательская траектория"
+
msgid "Custom SOW · we manage"
msgstr "Пользовательское SOW · мы управляем"
@@ -17599,6 +17605,9 @@ msgstr "Роли, устанавливающие права доступа по
msgid "Room to grow without bolting on more tools"
msgstr "Место для роста без добавления новых инструментов"
+msgid "Rotate"
+msgstr "Повернуть"
+
msgid "Rounding Account"
msgstr "Счет округления"
@@ -19659,6 +19668,9 @@ msgstr "Подсборка {number}"
msgid "Sub-assembly expiries only"
msgstr "Только сроки действия подсборок"
+msgid "Sub-assembly path"
+msgstr "Траектория подсборки"
+
msgid "Sub-Departments"
msgstr "Подразделения"
@@ -20865,8 +20877,11 @@ msgstr "Деталь производится как собственное за
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "Деталь берется из существующего запаса при производстве ее родительского элемента — без создания нового производственного заказа или заказа поставщику."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Путь, по которому компоненты этого шага перемещаются на место при воспроизведении; определяется на основе модели или рисуется вручную с помощью кнопки «Изменить путь»."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Траектория, по которой движется готовая подсборка как единое целое при её добавлении в сборку. Она появляется перед собственными деталями шага; пока вы не создадите её, используя функцию «Изменить траекторию», она скользит в сборку со стороны."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Траектория, по которой компоненты этого шага перемещаются на место во время воспроизведения; рассчитанная по модели или нарисованная вручную с помощью функции «Изменить траекторию», где деталь также может быть повернута в любой контрольной точке."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Сотрудники Carbon, которые будут проводить ваше внедрение, и способы связи с ними."
diff --git a/packages/locale/locales/tr/erp.po b/packages/locale/locales/tr/erp.po
index 4be6997c99..bfa68dd69e 100644
--- a/packages/locale/locales/tr/erp.po
+++ b/packages/locale/locales/tr/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} {end} tarihinde sona eriyor ({was} idi)"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} {end} tarihinde sona eriyor (daha önce açıktı)"
+msgid "{name} path"
+msgstr "{name} yolu"
+
msgid "{name} replaced"
msgstr "{name} değiştirildi"
@@ -6023,6 +6026,9 @@ msgstr "Özel Alanlar"
msgid "Custom fields are not available for items yet."
msgstr "Özel alanlar henüz öğeler için kullanılabilir değildir."
+msgid "Custom path"
+msgstr "Özel yolu"
+
msgid "Custom SOW · we manage"
msgstr "Özel SOW · biz yönetiriz"
@@ -17599,6 +17605,9 @@ msgstr "Yeni çalışanlar için varsayılan izinleri ayarlayan roller"
msgid "Room to grow without bolting on more tools"
msgstr "Daha fazla araç eklemeden büyüme için yer"
+msgid "Rotate"
+msgstr "Döndür"
+
msgid "Rounding Account"
msgstr "Yuvarlama hesabı"
@@ -19659,6 +19668,9 @@ msgstr "Alt-Montaj {number}"
msgid "Sub-assembly expiries only"
msgstr "Yalnızca alt montaj son kullanma tarihleri"
+msgid "Sub-assembly path"
+msgstr "Alt-montaj yolu"
+
msgid "Sub-Departments"
msgstr "Alt Departmanlar"
@@ -20865,8 +20877,11 @@ msgstr "Parça, ihtiyacı olan üst öğe inşa edildiğinde kendi işi olarak
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "Parça, ebeveyninin inşa edildiğinde mevcut stoktan alınır - yeni iş veya satın alma siparişi yok."
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "Bu adımın bileşenlerinin oynatma sırasında hareket ettiği yol; modelden hesaplanmış veya Yolu Düzenle ile elle çizilmiş."
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "Bitmiş bir alt-montajın montajla birleştirildiğinde tek bir parça olarak izlediği yolu. Adımın kendi parçalarından önce gelir; Yolu Düzenle ile bir yol çizemeyene kadar, yapının yanından kaymaya devam eder."
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "Bu adımın bileşenlerinin oynatma sırasında yerlerine gitmesi için izlediği yolu; modelden çıkarılan ya da Yolu Düzenle ile el ile çizilen, burada bir parçanın herhangi bir nokta üzerinde döndürülebilir."
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Carbon tarafındaki uygulamanızı yönetecek Personel ve onlara ulaşmanız için nasıl yapılır."
diff --git a/packages/locale/locales/zh/erp.po b/packages/locale/locales/zh/erp.po
index d53521dfca..6b4f1026d5 100644
--- a/packages/locale/locales/zh/erp.po
+++ b/packages/locale/locales/zh/erp.po
@@ -465,6 +465,9 @@ msgstr "{name} 在 {end} 结束(之前是 {was})"
msgid "{name} ends {end} (was open-ended)"
msgstr "{name} 在 {end} 结束(之前是开放式)"
+msgid "{name} path"
+msgstr "{name}路径"
+
msgid "{name} replaced"
msgstr "{name} 已替换"
@@ -6023,6 +6026,9 @@ msgstr "自定义字段"
msgid "Custom fields are not available for items yet."
msgstr "暂不支持物料的自定义字段。"
+msgid "Custom path"
+msgstr "自定义路径"
+
msgid "Custom SOW · we manage"
msgstr "自定义 SOW · 我们管理"
@@ -17599,6 +17605,9 @@ msgstr "为新员工设置默认权限的角色"
msgid "Room to grow without bolting on more tools"
msgstr "无需添加更多工具即可扩展"
+msgid "Rotate"
+msgstr "旋转"
+
msgid "Rounding Account"
msgstr "舍入账户"
@@ -19659,6 +19668,9 @@ msgstr "子装配体 {number}"
msgid "Sub-assembly expiries only"
msgstr "仅子组件过期日期"
+msgid "Sub-assembly path"
+msgstr "子装配体路径"
+
msgid "Sub-Departments"
msgstr "子部门"
@@ -20865,8 +20877,11 @@ msgstr "当需要该零件的父级被构造时,该零件被制造为其自己
msgid "The part is taken from existing stock when its parent is built — no new job or purchase order."
msgstr "构建其父级时,从现有库存中获取该零件 - 无新工作或采购订单。"
-msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path."
-msgstr "此步骤的组件在回放期间进入位置的路径;从模型中计算得出,或使用「编辑路径」手绘。"
+msgid "The path a finished sub-assembly travels as one piece when it joins the build. It arrives before the step's own parts; until you draw one with Edit Path, it slides in from beside the build."
+msgstr "已完成的子装配体加入构建时作为整体所走的路径。它在该步骤的零件之前到达;在您使用编辑路径绘制之前,它从构建旁边滑入。"
+
+msgid "The path this step's components travel into place during playback; worked out from the model, or drawn by hand with Edit Path, where a part can also be turned at any waypoint."
+msgstr "该步骤的零件在播放期间进入到位所走的路径;从模型计算或使用编辑路径手工绘制,其中零件也可以在任何路点处被旋转。"
msgid "The people on the Carbon side who will run your implementation, and how to reach them."
msgstr "Carbon 方面将运行您的实施的人员,以及如何联系他们。"
diff --git a/packages/viewer/AGENTS.md b/packages/viewer/AGENTS.md
index e7500fdfa0..67c5abda93 100644
--- a/packages/viewer/AGENTS.md
+++ b/packages/viewer/AGENTS.md
@@ -7,8 +7,8 @@
- **graph.json** (`AssemblyGraph`) — assembly tree written by the geometry service `/convert`; leaf nodes carry a stable `nodeId` (also baked into GLB node extras as `userData.nodeId`). All joins between steps, plans, and scene objects are by `nodeId`.
- **plan.json** (`AssemblyPlan`) — per-component insertion `Motion`, sequence, subassembly `groups`, and body-level `contacts`, written by the geometry service `/plan`. `CURRENT_PLAN_VERSION` (currently `3`) — stored plans below it are STALE and must be treated as absent so the pipeline re-plans.
- **Step** (`AssemblyStep`) — one build instruction: `componentNodeIds`, a `Motion`, optional `camera`, `fastener`, per-step `hiddenComponentNodeIds`, and the sub-assembly fields `isSubAssembly` / `parentStepId` / `usedInStepId`. Built from a plan by `buildAssemblyStepGroups`.
-- **Sub-assemblies** (`subassembly.ts`) — a header step (`isSubAssembly`) groups the steps whose `parentStepId` points at it; those steps sit directly before it in play order and are BUILT ON THEIR OWN: while one is active the player isolates its sub-assembly's parts (focus-style, ancestors kept, not cleared by playback, framed on their own bounds). A header's `usedInStepId` names the later step that carries the finished unit in (glide from beside the build, `CARRY_IN_GLIDE_SECONDS` / `buildStepClip`'s `glide.nodeIds`, then the step's insertion); without one the header itself is where the unit joins the main build, and a USED header plays nothing (0-length segment, skipped by prev/next). No nesting — a step USES a finished sub-assembly instead, so chains of any length work. `arrivalIndexByNode(steps, world)` is THE answer to "when does this part appear in the build on screen" and drives visibility; `validateSubAssemblies` is THE structural rule the ERP service and editor share. `scopeStepIds` limits the timeline to an opened sub-assembly.
-- **Motion** — discriminated union `linear | L | helix | path | none`. Insertion motion; the player derives removal (reverse) and start poses. `flagged`/`blockedBy` steps use `none` and fade in (no collision-free path exists — a synthesized path would clip through geometry).
+- **Sub-assemblies** (`subassembly.ts`) — a header step (`isSubAssembly`) groups the steps whose `parentStepId` points at it; those steps sit directly before it in play order and are BUILT ON THEIR OWN: while one is active the player isolates its sub-assembly's parts (focus-style, ancestors kept, not cleared by playback, framed on their own bounds). A header's `usedInStepId` names the later step that carries the finished unit in. A header whose `motion` is not `none` has a path of its own: the unit plays it (`buildStepClip`'s `units`, one after another in sub-assembly order) before the step's own parts move — a step with no animation of its own fades its parts in only after those units seat (`fadeProgress`). `buildCarryPlans` is THE per-step answer to which units fly, which glide, and whether an unused header joins on its own path. Otherwise it glides from beside the build (`CARRY_IN_GLIDE_SECONDS` / `buildStepClip`'s `glide.nodeIds`), then rides the step's insertion; without one the header itself is where the unit joins the main build, and a USED header plays nothing (0-length segment, skipped by prev/next). No nesting — a step USES a finished sub-assembly instead, so chains of any length work. `arrivalIndexByNode(steps, world)` is THE answer to "when does this part appear in the build on screen" and drives visibility; `validateSubAssemblies` is THE structural rule the ERP service and editor share. `scopeStepIds` limits the timeline to an opened sub-assembly.
+- **Motion** — discriminated union `linear | L | helix | path | waypoints | none`. `waypoints` is editor-authored: poses relative to the seated pose, turning about the moving set's seated bounds center (`seatedBoundsCenter`), so one motion fits a part, a rigid group or a sub-assembly. The path editor saves `linear`/`L` until a waypoint is turned (`editorWaypointsToMotion`); it has a Move / Rotate tool (`pathToolLabels` on the player, host-translated — no labels, no switch): Rotate shows drei `TransformControls` rings on the selected waypoint and stops the spheres dragging, because the rings' invisible free-rotation grip sits over the sphere. Insertion motion; the player derives removal (reverse) and start poses. `flagged`/`blockedBy` steps use `none` and fade in (no collision-free path exists — a synthesized path would clip through geometry).
- **Artifact tiers** — a model renders from best-available: LOD GLB → optimised GLB → lossless GLB → raw WASM (in-browser occt-import-js) fallback.
## Always
@@ -55,7 +55,7 @@ Key non-exported building blocks: `useAssembly` (loads meshopt GLB + graph.json,
## Cross-References
- **Consumers**: ERP `apps/erp/app/components/CadModel.tsx`, `apps/erp/app/modules/production/ui/Assemblies/*`, route `apps/erp/app/routes/x+/assembly+/$id.tsx`; MES `apps/mes/app/components/AssemblyView.tsx` + `JobOperation`; Inngest `packages/jobs/src/inngest/functions/tasks/assembly-plan.ts` (imports `@carbon/viewer/steps`).
-- **Contracts**: `docs/specs/animated-work-instructions-contracts.md` (mirrored by `types.ts`).
+- **Contracts**: `src/types.ts` is the contract itself (the `docs/specs/animated-work-instructions-contracts.md` it once mirrored no longer exists). The ERP mirrors `Motion` as zod in `motionSchema` (`apps/erp/app/modules/production/production.models.ts`); the MES checks raw rows with `isPlayableMotion`.
- **Model paths / raw limits**: `@carbon/utils` (`modelPathOptimizeFormat`, `MODEL_RAW_KEEP_MAX_BYTES`).
</content>
</invoke>
diff --git a/packages/viewer/src/AssemblyPlayer.tsx b/packages/viewer/src/AssemblyPlayer.tsx
index a7b93d9f93..96a54eae9f 100644
--- a/packages/viewer/src/AssemblyPlayer.tsx
+++ b/packages/viewer/src/AssemblyPlayer.tsx
@@ -24,6 +24,7 @@ import {
MeshStandardMaterial,
type Object3D,
PerspectiveCamera,
+ Quaternion,
Vector3
} from "three";
import {
@@ -42,13 +43,17 @@ import {
buildStepClip,
CARRY_IN_GLIDE_SECONDS,
displayMotionForStep,
+ fadeProgress,
+ motionDuration,
naturalizeMotion,
+ seatedBoundsCenter,
stepClipTiming
} from "./motion";
import {
arrivalIndexByNode,
+ buildCarryPlans,
buildSubAssemblyPlan,
- subAssemblyPartIds,
+ type PathUnit,
worldOf
} from "./subassembly";
import type {
@@ -82,6 +87,13 @@ export type {
/** Marquee rectangle in canvas-local CSS pixels while box-selecting. */
type BoxRect = { left: number; top: number; width: number; height: number };
+/**
+ * A motion open in the path editor. It always targets the ACTIVE step; with
+ * `nodeIds` it is the path of a sub-assembly that step carries in (only those
+ * parts move), otherwise the step's own insertion.
+ */
+export type EditMotion = { stepId: string; motion: Motion; nodeIds?: string[] };
+
/**
* Loop mode (MES) holds the seated pose for this long at the end of each cycle
* before replaying the insertion — a calmer cadence than a seamless repeat.
@@ -124,7 +136,7 @@ export type AssemblyPlayerProps = {
* Must reference the active step; the draft `motion` is what renders (so the
* route can hold it as controlled state). Playback is paused while set.
*/
- editMotion?: { stepId: string; motion: Motion } | null;
+ editMotion?: EditMotion | null;
/** Drag/insert/delete of a waypoint emits the new relative motion. */
onMotionChange?: (stepId: string, motion: Motion) => void;
/** Initial render mode for future-step components. Shared by step selection
@@ -185,6 +197,12 @@ export type AssemblyPlayerProps = {
isolationLabel?: string | null;
/** Shown next to the isolation label while the active step carries a finished sub-assembly in. */
carryInLabel?: string | null;
+ /**
+ * Labels for the path editor's Move / Rotate switch (shown while a path is
+ * being edited). The host translates them; without them the switch is hidden
+ * and waypoints only move.
+ */
+ pathToolLabels?: { move: string; rotate: string } | null;
mode?: "dark" | "light";
className?: string;
};
@@ -239,6 +257,7 @@ export const AssemblyPlayer = forwardRef<
playFromStepIndex,
isolationLabel,
carryInLabel,
+ pathToolLabels,
mode = "dark",
className
},
@@ -259,6 +278,16 @@ export const AssemblyPlayer = forwardRef<
// Paused orbiting doesn't change modes (per-step framing already yields to
// the framing-key guard there).
const [cameraMode, setCameraMode] = useState<"auto" | "free">("auto");
+ // Path editor tool: drag waypoints to move them, or turn the selected one
+ // with rotation rings. Each edit session starts on Move.
+ const [pathTool, setPathTool] = useState<PathTool>("move");
+ const editKey = editMotion
+ ? `${editMotion.stepId}|${editMotion.nodeIds?.[0] ?? "own"}`
+ : null;
+ // biome-ignore lint/correctness/useExhaustiveDependencies: editKey identifies the edit session; a new session resets the tool
+ useEffect(() => {
+ setPathTool("move");
+ }, [editKey]);
// Stable identity — the scene re-subscribes its controls listener otherwise.
const handleFreeCamera = useCallback(() => setCameraMode("free"), []);
// Exposed as named views, not raw axes: six icon buttons made the reader
@@ -367,17 +396,25 @@ export const AssemblyPlayer = forwardRef<
}
return byWorld;
}, [steps, stepWorlds]);
- /** Per step: the parts of the finished sub-assemblies it carries in. */
- const carriedPartIds = useMemo(
- () =>
- steps.map((step) => {
- const headers = subPlan.get(step.id)?.carriesIn ?? [];
- return [
- ...new Set(headers.flatMap((id) => subAssemblyPartIds(steps, id)))
- ];
- }),
+ // How each step's carried-in sub-assemblies arrive: on their own path
+ // (one after another, before the step's own parts) or gliding in beside
+ // the build.
+ const carryPlans = useMemo(
+ () => buildCarryPlans(steps, subPlan),
[steps, subPlan]
);
+ const carriedPartIds = useMemo(
+ () => carryPlans.map((plan) => plan.carriedPartIds),
+ [carryPlans]
+ );
+ const pathUnits = useMemo(
+ () => carryPlans.map((plan) => plan.pathUnits),
+ [carryPlans]
+ );
+ const glidingPartIds = useMemo(
+ () => carryPlans.map((plan) => plan.glidingPartIds),
+ [carryPlans]
+ );
const scopeSet = useMemo(
() => (scopeStepIds ? new Set(scopeStepIds) : null),
[scopeStepIds]
@@ -431,6 +468,21 @@ export const AssemblyPlayer = forwardRef<
// list) sees the whole moving set.
const carried = carriedPartIds[index] ?? [];
let step = original;
+ // A header whose unit joins on its own path: that path IS the header's
+ // motion, and the unit plays it — the header has no insertion of its own.
+ if (carryPlans[index]?.joinsOnOwnPath) {
+ step = { ...step, motion: { type: "none" } };
+ }
+ // The step's own insertion moves its own parts plus the gliding units.
+ const ownMoving = (glidingPartIds[index] ?? []).length
+ ? [
+ ...new Set([
+ ...step.componentNodeIds,
+ ...(glidingPartIds[index] ?? [])
+ ])
+ ]
+ : step.componentNodeIds;
+ const motionBasis = { ...step, componentNodeIds: ownMoving };
if (carried.length > 0) {
step = {
...step,
@@ -447,11 +499,11 @@ export const AssemblyPlayer = forwardRef<
}
const baseMotion = suppressFallbackMotions
? step.motion
- : displayMotionForStep(step, index, graphIndex, world);
+ : displayMotionForStep(motionBasis, index, graphIndex, world);
let minBox: [number, number, number] | null = null;
let maxBox: [number, number, number] | null = null;
- for (const nodeId of step.componentNodeIds) {
+ for (const nodeId of motionBasis.componentNodeIds) {
const node = graphIndex.nodesById.get(nodeId);
if (!node) continue;
if (!minBox || !maxBox) {
@@ -492,27 +544,32 @@ export const AssemblyPlayer = forwardRef<
graphIndex,
suppressFallbackMotions,
carriedPartIds,
+ carryPlans,
+ glidingPartIds,
arrivals,
stepWorlds
]);
// --- Continuous timeline ---------------------------------------------
- // A carry-in step also spends the glide bringing the unit in. Steps that
- // don't play (a used sub-assembly's header, or outside an opened
- // sub-assembly) take no time.
+ // A carry-in step also spends the time bringing its units in: each unit's
+ // own path, then the glide for the rest. Steps that don't play (a used
+ // sub-assembly's header, or outside an opened sub-assembly) take no time.
const segments = useMemo(
() =>
displaySteps.map((step, index) =>
playable[index]
? stepClipTiming(
step,
- (carriedPartIds[index]?.length ?? 0) > 0
+ (glidingPartIds[index]?.length ?? 0) > 0
? CARRY_IN_GLIDE_SECONDS
- : 0
+ : 0,
+ (pathUnits[index] ?? []).map((unit) =>
+ motionDuration(unit.motion)
+ )
).total
: 0
),
- [displaySteps, playable, carriedPartIds]
+ [displaySteps, playable, glidingPartIds, pathUnits]
);
const startTimes = useMemo(() => {
let elapsed = 0;
@@ -624,6 +681,8 @@ export const AssemblyPlayer = forwardRef<
const activeInfo = activeStep ? subPlan.get(activeStep.id) : undefined;
const isolatePartIds = activeInfo?.isolatePartIds ?? null;
const activeCarried = carriedPartIds[clampedIndex] ?? NO_NODE_IDS;
+ const activeGliding = glidingPartIds[clampedIndex] ?? NO_NODE_IDS;
+ const activePathUnits = pathUnits[clampedIndex] ?? NO_PATH_UNITS;
const activeArrivals = arrivals.get(stepWorlds[clampedIndex] ?? null) ?? null;
// An isolated sub-assembly frames on its own parts, not the whole model.
const frameBounds = useMemo(() => {
@@ -633,10 +692,11 @@ export const AssemblyPlayer = forwardRef<
}
return unionBounds(isolatePartIds, graphIndex.nodesById) ?? root;
}, [graphIndex, isolatePartIds]);
- // The carried unit glides in from beside the build that receives it.
+ // A carried unit with no path of its own glides in from beside the build
+ // that receives it.
const carryIn = useMemo(() => {
- if (!graphIndex || activeCarried.length === 0 || !frameBounds) return null;
- const unit = unionBounds(activeCarried, graphIndex.nodesById);
+ if (!graphIndex || activeGliding.length === 0 || !frameBounds) return null;
+ const unit = unionBounds(activeGliding, graphIndex.nodesById);
if (!unit) return null;
const diagonal = Math.hypot(
frameBounds.max[0] - frameBounds.min[0],
@@ -648,8 +708,8 @@ export const AssemblyPlayer = forwardRef<
0,
0
];
- return { nodeIds: activeCarried, offset };
- }, [graphIndex, activeCarried, frameBounds]);
+ return { nodeIds: activeGliding, offset };
+ }, [graphIndex, activeGliding, frameBounds]);
const playablePosition = playableIndices.indexOf(clampedIndex);
const prevIndex = nextPlayable(clampedIndex, -1);
const nextIndex = nextPlayable(clampedIndex, 1);
@@ -687,6 +747,7 @@ export const AssemblyPlayer = forwardRef<
readOnly={readOnly}
onSelectComponents={onSelectComponents}
editMotion={editMotion ?? null}
+ pathTool={pathToolLabels ? pathTool : "move"}
onMotionChange={onMotionChange}
assemblyDiagonal={assemblyDiagonal}
capturePoseRef={capturePoseRef}
@@ -706,9 +767,33 @@ export const AssemblyPlayer = forwardRef<
installIndexByNode={activeArrivals}
isolateNodeIds={isolatePartIds}
carryIn={carryIn}
+ pathUnits={activePathUnits}
/>
)}
</AssemblyViewer>
+ {editMotion && !readOnly && pathToolLabels && (
+ <div
+ role="group"
+ className="absolute left-3 top-3 z-10 flex items-center gap-0.5 rounded-lg border border-border bg-card p-0.5 text-xs font-medium shadow-lg"
+ >
+ {(["move", "rotate"] as const).map((tool) => (
+ <button
+ key={tool}
+ type="button"
+ aria-pressed={pathTool === tool}
+ onClick={() => setPathTool(tool)}
+ className={cn(
+ "rounded-md px-2.5 py-1 transition-colors",
+ pathTool === tool
+ ? "bg-accent text-foreground"
+ : "text-muted-foreground hover:text-foreground"
+ )}
+ >
+ {pathToolLabels[tool]}
+ </button>
+ ))}
+ </div>
+ )}
{isolationLabel && isolatePartIds && (
<div className="pointer-events-none absolute left-1/2 top-3 z-10 flex -translate-x-1/2 items-center gap-2 whitespace-nowrap rounded-full border border-border bg-card px-3 py-1.5 text-xs font-medium text-foreground shadow-lg">
<BoxesIcon />
@@ -1055,6 +1140,7 @@ function AssemblyScene({
readOnly,
onSelectComponents,
editMotion,
+ pathTool,
onMotionChange,
assemblyDiagonal,
capturePoseRef,
@@ -1073,7 +1159,8 @@ function AssemblyScene({
componentPickerActive,
installIndexByNode,
isolateNodeIds,
- carryIn
+ carryIn,
+ pathUnits
}: {
scene: Object3D;
nodesById: Map<string, Object3D>;
@@ -1089,7 +1176,8 @@ function AssemblyScene({
readOnly: boolean;
onSelectComponents?: (nodeIds: string[]) => void;
/** Active-step motion draft to edit (null = play normally) */
- editMotion: { stepId: string; motion: Motion } | null;
+ editMotion: EditMotion | null;
+ pathTool: PathTool;
onMotionChange?: (stepId: string, motion: Motion) => void;
/** Assembly diagonal (world units) for sizing the waypoint handles */
assemblyDiagonal: number;
@@ -1141,6 +1229,8 @@ function AssemblyScene({
isolateNodeIds: string[] | null;
/** A finished sub-assembly carried in at the active step, gliding from `offset`. */
carryIn: { nodeIds: string[]; offset: Vec3 } | null;
+ /** Carried sub-assemblies joining on their own path, in play order. */
+ pathUnits: PathUnit[];
}) {
const camera = useThree((state) => state.camera);
const controls = useThree(
@@ -1209,18 +1299,28 @@ function AssemblyScene({
// origins won't do: CAD exports often pivot far from the geometry, which
// would draw the locked endpoint away from the component. Components sit seated while
// editing (the clip is skipped below), so world space IS the final pose.
- const seatedCentroid = useMemo<Vec3 | null>(() => {
- if (!isEditingActive || !activeStep) return null;
- const box = new Box3();
- for (const nodeId of activeStep.componentNodeIds) {
- const node = nodesById.get(nodeId);
- if (!node) continue;
- node.updateWorldMatrix(true, false);
- box.expandByObject(node);
- }
- if (box.isEmpty()) return null;
- return box.getCenter(new Vector3()).toArray() as Vec3;
- }, [isEditingActive, activeStep, nodesById]);
+ // The parts the edited path moves: a carried sub-assembly's when editing its
+ // path, else the step's own (every part except the units on their own path).
+ const editedNodeIds = useMemo(() => {
+ if (!isEditingActive || !activeStep) return NO_NODE_IDS;
+ if (editMotion?.nodeIds) return editMotion.nodeIds;
+ const onPath = new Set(pathUnits.flatMap((unit) => unit.nodeIds));
+ return activeStep.componentNodeIds.filter((nodeId) => !onPath.has(nodeId));
+ }, [isEditingActive, activeStep, editMotion?.nodeIds, pathUnits]);
+ const seatedCentroid = useMemo<Vec3 | null>(
+ () =>
+ editedNodeIds.length > 0
+ ? seatedBoundsCenter(editedNodeIds, nodesById)
+ : null,
+ [editedNodeIds, nodesById]
+ );
+ const editedNodes = useMemo(
+ () =>
+ editedNodeIds
+ .map((nodeId) => nodesById.get(nodeId))
+ .filter((node): node is Object3D => Boolean(node)),
+ [editedNodeIds, nodesById]
+ );
const highlightedSet = useMemo(
() => new Set(highlightedNodeIds ?? []),
@@ -1319,6 +1419,8 @@ function AssemblyScene({
entries: { mesh: Mesh; fade: Material | Material[] }[];
materials: Material[];
seconds: number;
+ /** Seconds the fade waits: the step's own parts follow its sub-assemblies. */
+ delay: number;
fading: boolean;
} | null>(null);
@@ -1540,10 +1642,22 @@ function AssemblyScene({
segmentsLiveRef.current = segments;
const carryInLiveRef = useRef(carryIn);
carryInLiveRef.current = carryIn;
- // The carry-in glide is part of the signature so a change rebuilds the clip.
+ const pathUnitsLiveRef = useRef(pathUnits);
+ pathUnitsLiveRef.current = pathUnits;
+ // The carry-in glide and the units' paths are part of the signature so a
+ // change rebuilds the clip.
const carryInKey = carryIn
? JSON.stringify([carryIn.offset, carryIn.nodeIds.length])
: "";
+ const pathUnitsKey = pathUnits.length
+ ? JSON.stringify(
+ pathUnits.map((unit) => [
+ unit.headerId,
+ unit.nodeIds.length,
+ unit.motion
+ ])
+ )
+ : "";
const clipKey = activeStep
? [
activeStepIndex,
@@ -1553,7 +1667,8 @@ function AssemblyScene({
activeStep.durationSeconds ?? "",
isEditingActive,
componentPickerActive,
- carryInKey
+ carryInKey,
+ pathUnitsKey
].join("|")
: `none|${activeStepIndex}`;
@@ -1576,13 +1691,24 @@ function AssemblyScene({
// so the animation doesn't fight the drag handles.
if (isEditingActive) return;
- // A carried-in sub-assembly glides in from beside the build first. Picking
- // keeps everything seated: a click must select what the BOM tree shows.
+ // Carried-in sub-assemblies come first: each one with a path of its own
+ // flies it, then the rest glide in from beside the build. Picking keeps
+ // everything seated: a click must select what the BOM tree shows.
const carry = componentPickerActive ? null : carryInLiveRef.current;
- const timing = stepClipTiming(step, carry ? CARRY_IN_GLIDE_SECONDS : 0);
+ const units = componentPickerActive ? [] : pathUnitsLiveRef.current;
+ const timing = stepClipTiming(
+ step,
+ carry ? CARRY_IN_GLIDE_SECONDS : 0,
+ units.map((unit) => motionDuration(unit.motion))
+ );
const clip = buildStepClip(step, nodesById, {
duration: timing.motion,
holdSeconds: timing.hold,
+ units: units.map((unit, index) => ({
+ nodeIds: unit.nodeIds,
+ motion: unit.motion,
+ seconds: timing.units[index] ?? 0
+ })),
...(carry
? {
glide: {
@@ -1692,7 +1818,8 @@ function AssemblyScene({
// seated pose instead of popping: planner-flagged steps (no collision-free
// path exists) and any step whose display motion resolved to "none" (no
// stored motion and no collision-free fallback). Only the step's own parts
- // fade: a carried-in unit glides in instead.
+ // fade: a carried-in unit glides in, or flies its own path, instead — and
+ // the own parts wait until the units on their own path have seated.
useEffect(() => {
const step = steps[activeStepIndex];
// Editing this step: keep its components solid at the seated pose, no fade.
@@ -1706,9 +1833,12 @@ function AssemblyScene({
const overrides = overridesRef.current;
const entries: { mesh: Mesh; fade: Material | Material[] }[] = [];
const materials: Material[] = [];
- const gliding = new Set(carryIn?.nodeIds);
+ const carried = new Set([
+ ...(carryIn?.nodeIds ?? []),
+ ...pathUnits.flatMap((unit) => unit.nodeIds)
+ ]);
for (const nodeId of step.componentNodeIds) {
- if (gliding.has(nodeId)) continue;
+ if (carried.has(nodeId)) continue;
nodesById.get(nodeId)?.traverse((object) => {
if (!(object as Mesh).isMesh) return;
const mesh = object as Mesh;
@@ -1726,21 +1856,50 @@ function AssemblyScene({
const segment = segments[activeStepIndex] ?? 0;
const seconds =
segment > 0 ? Math.min(FADE_SECONDS, segment) : FADE_SECONDS;
- const progress = Math.min(localElapsedRef.current / seconds, 1);
+ const delay = stepClipTiming(
+ step,
+ carryIn ? CARRY_IN_GLIDE_SECONDS : 0,
+ pathUnits.map((unit) => motionDuration(unit.motion))
+ ).units.reduce((sum, unitSeconds) => sum + unitSeconds, 0);
+ const progress = fadeProgress(
+ localElapsedRef.current,
+ delay,
+ seconds,
+ finishedRef.current
+ );
for (const material of materials) material.opacity = progress;
- fadeRef.current = { entries, materials, seconds, fading: progress < 1 };
+ fadeRef.current = {
+ entries,
+ materials,
+ seconds,
+ delay,
+ fading: progress < 1
+ };
applyVisualsRef.current();
return () => {
fadeRef.current = null;
applyVisualsRef.current();
};
- }, [steps, activeStepIndex, nodesById, segments, editMotion, carryIn]);
+ }, [
+ steps,
+ activeStepIndex,
+ nodesById,
+ segments,
+ editMotion,
+ carryIn,
+ pathUnits
+ ]);
useFrame(() => {
const fade = fadeRef.current;
if (!fade) return;
- const progress = Math.min(localElapsedRef.current / fade.seconds, 1);
+ const progress = fadeProgress(
+ localElapsedRef.current,
+ fade.delay,
+ fade.seconds,
+ finishedRef.current
+ );
for (const material of fade.materials) material.opacity = progress;
// Finished (or restarted by MES loop): the pass swaps the materials.
if (fade.fading !== progress < 1) {
@@ -1951,6 +2110,7 @@ function AssemblyScene({
installedMode,
[...hiddenSet].sort().join(","),
carryInKey,
+ pathUnitsKey,
isolateNodeIds?.length ?? 0
].join("|");
if (framingKey === lastFramedKeyRef.current) return;
@@ -2005,6 +2165,25 @@ function AssemblyScene({
if (joinShift) {
assemblyBox.union(componentBox.clone().translate(joinShift));
}
+ // A unit on its own path starts wherever its path begins, turned as its
+ // first waypoint turns it.
+ for (const unit of pathUnits) {
+ const unitBox = new Box3();
+ for (const nodeId of unit.nodeIds) {
+ const seated = seatedBoundsById?.get(nodeId);
+ if (!seated) continue;
+ unitBox.expandByPoint(
+ new Vector3(...(seated.bbox.min as [number, number, number]))
+ );
+ unitBox.expandByPoint(
+ new Vector3(...(seated.bbox.max as [number, number, number]))
+ );
+ }
+ const startBox = unitBox.isEmpty()
+ ? null
+ : startPoseBounds(unitBox, unit.motion);
+ if (startBox) assemblyBox.union(startBox);
+ }
const center = assemblyBox.getCenter(new Vector3());
const radius = assemblyBox.getSize(new Vector3()).length() / 2;
const fov = camera instanceof PerspectiveCamera ? camera.fov : 45;
@@ -2189,6 +2368,8 @@ function AssemblyScene({
cameraMode,
carryIn,
carryInKey,
+ pathUnits,
+ pathUnitsKey,
isolateNodeIds
]);
@@ -2453,10 +2634,12 @@ function AssemblyScene({
/>
{isEditingActive && editMotion && onMotionChange && seatedCentroid && (
<MotionPathEditor
- key={editMotion.stepId}
+ key={`${editMotion.stepId}|${editMotion.nodeIds?.[0] ?? "own"}`}
motion={editMotion.motion}
seatedPosition={seatedCentroid}
scale={assemblyDiagonal}
+ ghostNodes={editedNodes}
+ tool={pathTool}
onMotionChange={(motion) => onMotionChange(editMotion.stepId, motion)}
/>
)}
@@ -2494,6 +2677,38 @@ function segmentIntersectsBox(
return true;
}
+/**
+ * Bounds of a set at the start of its motion: the seated box shifted by the
+ * start offset, and for a `waypoints` motion first turned about its center as
+ * the first waypoint turns it. Null when the motion has no start offset.
+ */
+function startPoseBounds(
+ seated: Box3,
+ motion: AssemblyStep["motion"]
+): Box3 | null {
+ const startOffset = insertionStartOffset(motion);
+ if (!startOffset) return null;
+ const first = motion.type === "waypoints" ? motion.waypoints[0] : undefined;
+ if (!first) return seated.clone().translate(startOffset);
+ const rotation = new Quaternion(...first.rotation).normalize();
+ const center = seated.getCenter(new Vector3());
+ const turned = new Box3();
+ for (let i = 0; i < 8; i++) {
+ turned.expandByPoint(
+ new Vector3(
+ i & 1 ? seated.max.x : seated.min.x,
+ i & 2 ? seated.max.y : seated.min.y,
+ i & 4 ? seated.max.z : seated.min.z
+ )
+ .sub(center)
+ .applyQuaternion(rotation)
+ .add(center)
+ .add(startOffset)
+ );
+ }
+ return turned;
+}
+
/**
* Where a component starts relative to its seated pose for the given insertion
* motion. Null when the motion does not translate the component.
@@ -2517,6 +2732,10 @@ function insertionStartOffset(motion: AssemblyStep["motion"]): Vector3 | null {
const travel = motion.approach + motion.pitch * motion.turns;
return axis.multiplyScalar(-travel);
}
+ case "waypoints": {
+ const first = motion.waypoints[0];
+ return first ? new Vector3(...first.offset) : null;
+ }
default:
return null;
}
@@ -2544,6 +2763,18 @@ function insertionDirection(motion: AssemblyStep["motion"]): Vector3 | null {
}
case "helix":
return new Vector3(...motion.axis).normalize();
+ case "waypoints": {
+ // The longest leg, in travel order (start → seat).
+ let longest: Vector3 | null = null;
+ for (let i = 1; i < motion.waypoints.length; i++) {
+ const from = motion.waypoints[i - 1];
+ const to = motion.waypoints[i];
+ if (!from || !to) continue;
+ const leg = new Vector3(...to.offset).sub(new Vector3(...from.offset));
+ if (leg.lengthSq() > (longest?.lengthSq() ?? 1e-12)) longest = leg;
+ }
+ return longest ? longest.normalize() : null;
+ }
default:
return null;
}
@@ -2927,6 +3158,10 @@ const CARRY_IN_GAP_FRACTION = 0.25;
/** Stable empty list, so memos keyed on "no ids" don't churn. */
const NO_NODE_IDS: string[] = [];
+type PathTool = "move" | "rotate";
+
+const NO_PATH_UNITS: PathUnit[] = [];
+
/** Seated world bounds of the given nodes, from graph.json; null when none resolve. */
function unionBounds(
nodeIds: string[],
diff --git a/packages/viewer/src/MotionPathEditor.tsx b/packages/viewer/src/MotionPathEditor.tsx
index c93d2f1c7d..ce5c5eaf9d 100644
--- a/packages/viewer/src/MotionPathEditor.tsx
+++ b/packages/viewer/src/MotionPathEditor.tsx
@@ -2,24 +2,51 @@
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
-import { Line } from "@react-three/drei";
+import { Line, TransformControls } from "@react-three/drei";
import { type ThreeEvent, useThree } from "@react-three/fiber";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Plane, Vector3 } from "three";
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useMemo,
+ useRef,
+ useState
+} from "react";
+import {
+ type Group,
+ Matrix4,
+ type Mesh,
+ MeshBasicMaterial,
+ type Object3D,
+ Plane,
+ Quaternion,
+ Vector3
+} from "three";
import type { OrbitControls as OrbitControlsImpl } from "three-stdlib";
-import { motionToWaypoints, waypointsToMotion } from "./motion";
-import type { Motion, Vec3 } from "./types";
+import { editorWaypointsToMotion, motionToEditorWaypoints } from "./motion";
+import type { Motion, Quat, Vec3 } from "./types";
+
+/** Rotation rings snap to this step, so 90° and 180° turns are easy to hit. */
+const ROTATION_SNAP = Math.PI / 12;
+
+type Waypoint = { position: Vector3; rotation: Quaternion };
/**
- * In-scene editor for a step's insertion motion, rendered as a red path with
+ * In-scene editor for an insertion motion — a step's own, or the path of a
+ * sub-assembly the step carries in — rendered as a red path with
* drag-and-drop waypoints. Grab a sphere and drag it (it moves in the plane
* facing the camera); the LAST waypoint is the seated (final) pose and is
* locked. Double-click the path to insert a waypoint; select one and press
* Delete to remove it.
*
- * Edits serialize back to a RELATIVE motion (`linear`/`L`) via
- * `waypointsToMotion`, so they apply to every component of a rigid-group step. Pure
- * translation — components keep their seated orientation (see the plan / decision #2).
+ * A see-through copy of the moving parts shows the selected waypoint's pose.
+ * With the Rotate tool, the selected waypoint gets rotation rings (snapping to
+ * 15°) and the spheres stop dragging: the rings' free-rotation grip covers the
+ * sphere, so allowing both made one drag move and spin the part at once.
+ *
+ * Edits serialize back to a RELATIVE motion via `editorWaypointsToMotion` —
+ * `linear`/`L` while nothing is turned, `waypoints` once something is — so
+ * they apply to every component of a rigid group or sub-assembly.
*
* Lives outside the AnimationMixer clip lifecycle: while editing, the player
* skips building the step clip so components stay seated and the handles are not
@@ -29,13 +56,19 @@ export function MotionPathEditor({
motion,
seatedPosition,
scale,
+ ghostNodes,
+ tool,
onMotionChange
}: {
motion: Motion;
- /** Centroid of the step's components' seated world positions (path anchor). */
+ /** Center of the moving parts' seated world bounds (path anchor and pivot). */
seatedPosition: Vec3;
/** Assembly diagonal (world units) — sizes the waypoint handles. */
scale: number;
+ /** The parts the path moves, seated — drawn see-through at a waypoint's pose. */
+ ghostNodes: Object3D[];
+ /** Move: drag waypoints. Rotate: turn the selected waypoint with rings. */
+ tool: "move" | "rotate";
onMotionChange: (motion: Motion) => void;
}) {
const camera = useThree((state) => state.camera);
@@ -43,10 +76,13 @@ export function MotionPathEditor({
(state) => state.controls
) as unknown as OrbitControlsImpl | null;
- const [points, setPoints] = useState<Vector3[]>(() =>
- motionToWaypoints(motion, seatedPosition, {
+ const [points, setPoints] = useState<Waypoint[]>(() =>
+ motionToEditorWaypoints(motion, seatedPosition, {
defaultDistance: scale > 0 ? scale * 0.25 : undefined
- }).map((point) => new Vector3(...point))
+ }).map((waypoint) => ({
+ position: new Vector3(...waypoint.position),
+ rotation: new Quaternion(...waypoint.rotation)
+ }))
);
const [selected, setSelected] = useState<number | null>(null);
const [hovered, setHovered] = useState<number | null>(null);
@@ -62,10 +98,13 @@ export function MotionPathEditor({
const handleRadius = Math.max(scale * 0.014, 0.5);
const commit = useCallback(
- (pts: Vector3[]) =>
+ (pts: Waypoint[]) =>
onMotionChange(
- waypointsToMotion(
- pts.map((point) => point.toArray() as Vec3),
+ editorWaypointsToMotion(
+ pts.map((point) => ({
+ position: point.position.toArray() as Vec3,
+ rotation: point.rotation.toArray() as Quat
+ })),
seatedPosition
)
),
@@ -76,9 +115,10 @@ export function MotionPathEditor({
(index: number, event: ThreeEvent<PointerEvent>) => {
if (index === lastIndex) return; // seated pose is locked
event.stopPropagation();
- (event.target as Element).setPointerCapture?.(event.pointerId);
setSelected(index);
- const anchor = pointsRef.current[index];
+ if (tool === "rotate") return; // rotating: a click only selects
+ (event.target as Element).setPointerCapture?.(event.pointerId);
+ const anchor = pointsRef.current[index]?.position;
if (!anchor) return;
// Slide in the plane facing the camera, through the grabbed waypoint.
const normal = camera.getWorldDirection(new Vector3());
@@ -88,7 +128,7 @@ export function MotionPathEditor({
};
if (controls) controls.enabled = false;
},
- [camera, controls, lastIndex]
+ [camera, controls, lastIndex, tool]
);
const onPointerMove = useCallback((event: ThreeEvent<PointerEvent>) => {
@@ -99,7 +139,7 @@ export function MotionPathEditor({
if (!event.ray.intersectPlane(drag.plane, hit)) return;
setPoints((previous) => {
const next = previous.map((point, index) =>
- index === drag.index ? hit.clone() : point
+ index === drag.index ? { ...point, position: hit.clone() } : point
);
pointsRef.current = next;
return next;
@@ -130,15 +170,18 @@ export function MotionPathEditor({
const from = current[i];
const to = current[i + 1];
if (!from || !to) continue;
- const distance = distanceToSegment(point, from, to);
+ const distance = distanceToSegment(point, from.position, to.position);
if (distance < bestDistance) {
bestDistance = distance;
bestSegment = i;
}
}
const insertIndex = bestSegment + 1;
+ // A new waypoint starts turned like the one the segment leaves from.
+ const rotation =
+ current[bestSegment]?.rotation.clone() ?? new Quaternion();
const next = [...current];
- next.splice(insertIndex, 0, point);
+ next.splice(insertIndex, 0, { position: point, rotation });
pointsRef.current = next;
setPoints(next);
setSelected(insertIndex);
@@ -170,11 +213,48 @@ export function MotionPathEditor({
};
}, [controls]);
+ // Rotation rings act on a handle sitting at the selected waypoint; turning
+ // the handle turns that waypoint.
+ const [ringHandle, setRingHandle] = useState<Group | null>(null);
+ // With the Rotate tool the rings sit on the selected waypoint, else the start.
+ const ringIndex =
+ tool !== "rotate" || lastIndex < 1
+ ? null
+ : selected !== null && selected !== lastIndex
+ ? selected
+ : 0;
+ const ringWaypoint = ringIndex !== null ? points[ringIndex] : undefined;
+ useEffect(() => {
+ if (!ringHandle || !ringWaypoint) return;
+ ringHandle.position.copy(ringWaypoint.position);
+ ringHandle.quaternion.copy(ringWaypoint.rotation);
+ ringHandle.updateMatrixWorld();
+ }, [ringHandle, ringWaypoint]);
+
+ const onRotate = useCallback(() => {
+ if (!ringHandle || ringIndex === null) return;
+ const rotation = ringHandle.quaternion.clone();
+ setPoints((previous) => {
+ const next = previous.map((point, index) =>
+ index === ringIndex ? { ...point, rotation } : point
+ );
+ pointsRef.current = next;
+ return next;
+ });
+ }, [ringHandle, ringIndex]);
+
const linePoints = useMemo(
- () => points.map((point) => point.toArray() as Vec3),
+ () => points.map((point) => point.position.toArray() as Vec3),
[points]
);
+ // The see-through copy shows the selected waypoint, else the start.
+ const ghostWaypoint =
+ (selected !== null && selected !== lastIndex
+ ? points[selected]
+ : undefined) ?? points[0];
+ const showGhost = Boolean(ghostWaypoint) && points.length > 1;
+
return (
<group renderOrder={10}>
<Line
@@ -191,7 +271,7 @@ export function MotionPathEditor({
return (
<mesh
key={index}
- position={point}
+ position={point.position}
renderOrder={11}
onPointerDown={(event) => onPointerDown(index, event)}
onPointerMove={onPointerMove}
@@ -218,10 +298,102 @@ export function MotionPathEditor({
</mesh>
);
})}
+ {showGhost && ghostWaypoint && (
+ <MotionGhost
+ nodes={ghostNodes}
+ pivot={seatedPosition}
+ position={ghostWaypoint.position}
+ rotation={ghostWaypoint.rotation}
+ />
+ )}
+ <group ref={setRingHandle} />
+ {ringHandle && ringWaypoint && (
+ <TransformControls
+ object={ringHandle}
+ mode="rotate"
+ space="world"
+ rotationSnap={ROTATION_SNAP}
+ size={1}
+ onObjectChange={onRotate}
+ onMouseUp={() => commit(pointsRef.current)}
+ />
+ )}
</group>
);
}
+/**
+ * The moving parts drawn see-through at one waypoint's pose: turned about the
+ * seated center (`pivot`), then moved so that center sits on the waypoint.
+ * Copies share the scene's geometry and never take part in picking.
+ */
+function MotionGhost({
+ nodes,
+ pivot,
+ position,
+ rotation
+}: {
+ nodes: Object3D[];
+ pivot: Vec3;
+ position: Vector3;
+ rotation: Quaternion;
+}) {
+ const material = useMemo(
+ () =>
+ new MeshBasicMaterial({
+ color: "#f59e0b",
+ transparent: true,
+ opacity: 0.25,
+ depthWrite: false
+ }),
+ []
+ );
+ useEffect(() => () => material.dispose(), [material]);
+
+ const copies = useMemo(
+ () =>
+ nodes.map((node) => {
+ node.updateWorldMatrix(true, false);
+ const copy = node.clone(true);
+ copy.matrixAutoUpdate = false;
+ copy.matrix.copy(node.matrixWorld);
+ copy.matrixWorldNeedsUpdate = true;
+ copy.traverse((object) => {
+ object.raycast = skipRaycast;
+ if ((object as Mesh).isMesh) (object as Mesh).material = material;
+ });
+ return copy;
+ }),
+ [nodes, material]
+ );
+
+ const groupRef = useRef<Group>(null);
+ // Before paint: the copies sit at the seated pose until this matrix lands.
+ useLayoutEffect(() => {
+ const group = groupRef.current;
+ if (!group) return;
+ const [x, y, z] = pivot;
+ group.matrix
+ .makeTranslation(position.x, position.y, position.z)
+ .multiply(new Matrix4().makeRotationFromQuaternion(rotation))
+ .multiply(new Matrix4().makeTranslation(-x, -y, -z));
+ group.matrixWorldNeedsUpdate = true;
+ }, [pivot, position, rotation]);
+
+ return (
+ <group ref={groupRef} matrixAutoUpdate={false} renderOrder={9}>
+ {copies.map((copy) => (
+ <primitive key={copy.uuid} object={copy} />
+ ))}
+ </group>
+ );
+}
+
+/** A ghost copy is never hit: clicks reach the real parts and the handles. */
+function skipRaycast() {
+ return;
+}
+
/** Shortest distance from a point to the segment [a, b]. */
function distanceToSegment(point: Vector3, a: Vector3, b: Vector3): number {
const ab = b.clone().sub(a);
diff --git a/packages/viewer/src/index.ts b/packages/viewer/src/index.ts
index 456a36651d..622680a523 100644
--- a/packages/viewer/src/index.ts
+++ b/packages/viewer/src/index.ts
@@ -28,6 +28,7 @@ export {
export {
buildStepClip,
displayMotionForStep,
+ isPlayableMotion,
type MotionKeyframeOptions,
type MotionKeyframes,
motionDuration,
diff --git a/packages/viewer/src/motion.test.ts b/packages/viewer/src/motion.test.ts
index c33dd8447a..1258e14c58 100644
--- a/packages/viewer/src/motion.test.ts
+++ b/packages/viewer/src/motion.test.ts
@@ -3,6 +3,7 @@
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
import {
+ type AnimationClip,
AnimationMixer,
Group,
Matrix4,
@@ -16,8 +17,12 @@ import {
buildStepClip,
DEFAULT_WAYPOINT_DISTANCE,
displayMotionForStep,
+ editorWaypointsToMotion,
+ fadeProgress,
+ isPlayableMotion,
type MotionKeyframes,
motionDuration,
+ motionToEditorWaypoints,
motionToKeyframes,
motionToWaypoints,
motionTravelDistance,
@@ -934,6 +939,7 @@ describe("stepClipTiming", () => {
it("plays the natural animation when no duration is authored", () => {
expect(stepClipTiming({ motion: linear })).toEqual({
total: seconds + 0.6,
+ units: [],
glide: 0,
motion: seconds,
hold: 0.6
@@ -968,3 +974,235 @@ describe("stepClipTiming", () => {
expect(timing.motion).toBe(seconds);
});
});
+
+describe("waypoints motion", () => {
+ const halfTurnZ: [number, number, number, number] = [0, 0, 1, 0];
+
+ it("turns the set about its pivot, then shifts it, and ends seated", () => {
+ const motion: Motion = {
+ type: "waypoints",
+ waypoints: [
+ { offset: [0, 0, 50], rotation: halfTurnZ },
+ { offset: [0, 0, 0], rotation: [0, 0, 0, 1] }
+ ]
+ };
+ // Part sits 10 mm along +X from the set's center at the origin.
+ const keyframes = motionToKeyframes(
+ motion,
+ { position: [10, 0, 0], quaternion: [0, 0, 0, 1] },
+ { duration: 2, pivot: [0, 0, 0] }
+ );
+ if (!keyframes) throw new Error("expected keyframes");
+ // 180° about Z swings the part to -X, then the offset lifts it.
+ expectVectorClose(positionAt(keyframes, 0), [-10, 0, 50]);
+ expectVectorClose(quaternionAt(keyframes, 0), [0, 0, 1, 0]);
+ const last = lastIndex(keyframes);
+ expectVectorClose(positionAt(keyframes, last), [10, 0, 0]);
+ expectVectorClose(quaternionAt(keyframes, last), [0, 0, 0, 1]);
+ expect(keyframes.times[last]).toBeCloseTo(2);
+ });
+
+ it("gives a turn in place readable time", () => {
+ const turnInPlace: Motion = {
+ type: "waypoints",
+ waypoints: [
+ { offset: [0, 0, 0], rotation: [0, 0, Math.SQRT1_2, Math.SQRT1_2] },
+ { offset: [0, 0, 0], rotation: [0, 0, 0, 1] }
+ ]
+ };
+ expect(motionTravelDistance(turnInPlace)).toBeGreaterThan(0);
+ expect(motionDuration(turnInPlace)).toBeGreaterThanOrEqual(1);
+ expect(motionDuration(turnInPlace)).toBeLessThanOrEqual(4);
+ });
+
+ it("round-trips through the editor and keeps unturned paths linear / L", () => {
+ const seated: Vec3 = [1, 2, 3];
+ expect(
+ editorWaypointsToMotion(
+ [
+ { position: [1, 2, 53], rotation: [0, 0, 0, 1] },
+ { position: seated, rotation: [0, 0, 0, 1] }
+ ],
+ seated
+ ).type
+ ).toBe("linear");
+ expect(
+ editorWaypointsToMotion(
+ [
+ { position: [1, 52, 53], rotation: [0, 0, 0, 1] },
+ { position: [1, 2, 53], rotation: [0, 0, 0, 1] },
+ { position: seated, rotation: [0, 0, 0, 1] }
+ ],
+ seated
+ ).type
+ ).toBe("L");
+
+ const turned = [
+ { position: [1, 2, 53] as Vec3, rotation: halfTurnZ },
+ {
+ position: seated,
+ rotation: [0, 0, 0, 1] as [number, number, number, number]
+ }
+ ];
+ const motion = editorWaypointsToMotion(turned, seated);
+ expect(motion.type).toBe("waypoints");
+ const back = motionToEditorWaypoints(motion, seated);
+ expect(back.length).toBe(2);
+ expectVectorClose(back[0]?.position ?? [], [1, 2, 53]);
+ expectVectorClose(back[0]?.rotation ?? [], halfTurnZ);
+ expectVectorClose(back[1]?.position ?? [], seated);
+ });
+});
+
+describe("buildStepClip with sub-assembly units", () => {
+ function makeParts() {
+ const root = new Group();
+ const own = new Object3D();
+ own.position.set(0, 0, 0);
+ const unitA = new Object3D();
+ unitA.position.set(100, 0, 0);
+ const unitB = new Object3D();
+ unitB.position.set(200, 0, 0);
+ root.add(own, unitA, unitB);
+ root.updateMatrixWorld(true);
+ return {
+ own,
+ unitA,
+ unitB,
+ nodesById: new Map<string, Object3D>([
+ ["own", own],
+ ["unit-a", unitA],
+ ["unit-b", unitB]
+ ])
+ };
+ }
+ const drop: Motion = { type: "linear", direction: [0, 0, -1], distance: 10 };
+ const trackFor = (clip: AnimationClip, node: Object3D) => {
+ const track = clip.tracks.find(
+ (candidate) => candidate.name === `${node.uuid}.position`
+ );
+ if (!track) throw new Error("expected a track");
+ return { times: [...track.times], values: [...track.values] };
+ };
+ const valueAt = (
+ track: { times: number[]; values: number[] },
+ time: number
+ ) => {
+ const index = track.times.findIndex((t) => Math.abs(t - time) < 1e-6);
+ expect(index).toBeGreaterThanOrEqual(0);
+ return track.values.slice(index * 3, index * 3 + 3);
+ };
+
+ it("flies the unit in first; the step's own part waits, then inserts", () => {
+ const { own, unitA, nodesById } = makeParts();
+ const clip = buildStepClip(makeStep(drop, ["own"]), nodesById, {
+ duration: 2,
+ holdSeconds: 0.5,
+ units: [{ nodeIds: ["unit-a"], motion: drop, seconds: 1 }]
+ });
+ if (!clip) throw new Error("expected clip");
+ expect(clip.duration).toBeCloseTo(1 + 2 + 0.5);
+
+ const unit = trackFor(clip, unitA);
+ expectVectorClose(unit.values.slice(0, 3), [100, 0, 10]);
+ expectVectorClose(valueAt(unit, 1), [100, 0, 0]);
+ expectVectorClose(unit.values.slice(-3), [100, 0, 0]);
+ expect(unit.times[unit.times.length - 1]).toBeCloseTo(3.5);
+
+ const part = trackFor(clip, own);
+ // Waits at its insertion start until the unit has seated…
+ expectVectorClose(part.values.slice(0, 3), [0, 0, 10]);
+ expectVectorClose(valueAt(part, 1), [0, 0, 10]);
+ // …then inserts and holds.
+ expectVectorClose(valueAt(part, 3), [0, 0, 0]);
+ });
+
+ it("plays several units one after another", () => {
+ const { unitB, nodesById } = makeParts();
+ const clip = buildStepClip(makeStep({ type: "none" }, []), nodesById, {
+ holdSeconds: 0,
+ units: [
+ { nodeIds: ["unit-a"], motion: drop, seconds: 1 },
+ { nodeIds: ["unit-b"], motion: drop, seconds: 1.5 }
+ ]
+ });
+ if (!clip) throw new Error("expected clip");
+ expect(clip.duration).toBeCloseTo(2.5);
+ const second = trackFor(clip, unitB);
+ expectVectorClose(valueAt(second, 1), [200, 0, 10]);
+ expectVectorClose(second.values.slice(-3), [200, 0, 0]);
+ });
+
+ it("builds a clip for a unit joining at a step with no parts of its own", () => {
+ const { nodesById } = makeParts();
+ expect(
+ buildStepClip(makeStep({ type: "none" }, []), nodesById, {
+ units: [{ nodeIds: ["unit-a"], motion: drop, seconds: 1 }]
+ })
+ ).not.toBeNull();
+ // A unit with no path of its own adds nothing.
+ expect(
+ buildStepClip(makeStep({ type: "none" }, []), nodesById, {
+ units: [{ nodeIds: ["unit-a"], motion: { type: "none" }, seconds: 0 }]
+ })
+ ).toBeNull();
+ });
+
+ it("scales the unit time with an authored duration", () => {
+ const natural = stepClipTiming({ motion: drop }, 0, [2]);
+ const fitted = stepClipTiming(
+ { motion: drop, durationSeconds: natural.total / 2 },
+ 0,
+ [2]
+ );
+ expect(fitted.units[0]).toBeCloseTo(1);
+ expect(fitted.total).toBeCloseTo(natural.total / 2);
+ });
+});
+
+describe("fadeProgress", () => {
+ it("waits for the units, then fades in over its own time", () => {
+ expect(fadeProgress(0.5, 2, 1.2, false)).toBe(0);
+ expect(fadeProgress(2, 2, 1.2, false)).toBe(0);
+ expect(fadeProgress(2.6, 2, 1.2, false)).toBeCloseTo(0.5);
+ expect(fadeProgress(5, 2, 1.2, false)).toBe(1);
+ });
+
+ it("is fully in once the step has finished, whatever the clock says", () => {
+ expect(fadeProgress(0, 2, 1.2, true)).toBe(1);
+ });
+
+ it("starts at once with no units", () => {
+ expect(fadeProgress(0.6, 0, 1.2, false)).toBeCloseTo(0.5);
+ });
+});
+
+describe("isPlayableMotion", () => {
+ it("accepts the motion types the player animates", () => {
+ expect(isPlayableMotion({ type: "none" })).toBe(true);
+ expect(
+ isPlayableMotion({ type: "linear", direction: [0, 0, 1], distance: 5 })
+ ).toBe(true);
+ expect(
+ isPlayableMotion({
+ type: "waypoints",
+ waypoints: [
+ { offset: [0, 0, 5], rotation: [0, 0, 0, 1] },
+ { offset: [0, 0, 0], rotation: [0, 0, 0, 1] }
+ ]
+ })
+ ).toBe(true);
+ });
+
+ it("rejects what would throw or is unknown", () => {
+ expect(isPlayableMotion(null)).toBe(false);
+ expect(isPlayableMotion({ type: "teleport" })).toBe(false);
+ expect(
+ isPlayableMotion({
+ type: "waypoints",
+ waypoints: [{ offset: [0, 0, 0], rotation: [0, 0, 0, 1] }]
+ })
+ ).toBe(false);
+ expect(isPlayableMotion({ type: "path", keyframes: [] })).toBe(false);
+ });
+});
diff --git a/packages/viewer/src/motion.ts b/packages/viewer/src/motion.ts
index 8996d6c56c..301542f060 100644
--- a/packages/viewer/src/motion.ts
+++ b/packages/viewer/src/motion.ts
@@ -4,6 +4,7 @@
import {
AnimationClip,
+ Box3,
Matrix4,
type Object3D,
Quaternion,
@@ -13,7 +14,13 @@ import {
} from "three";
import { synthesizeFallbackMotion } from "./fallback";
import type { AssemblyGraphIndex } from "./graph";
-import type { AssemblyStep, Motion, Quat, Vec3 } from "./types";
+import type {
+ AssemblyStep,
+ Motion,
+ Quat,
+ Vec3,
+ WaypointsMotion
+} from "./types";
/**
* Pure keyframe construction for step motions. No WebGL — everything here is
@@ -45,6 +52,12 @@ export type MotionKeyframeOptions = {
duration?: number;
/** Helix sampling density (quaternion slerp needs <180° between samples). */
samplesPerTurn?: number;
+ /**
+ * Seated center of the whole moving set (one part, a rigid group, or a
+ * sub-assembly). A `waypoints` motion turns the set about it. Defaults to the
+ * part's own seated position.
+ */
+ pivot?: Vec3;
};
export type StepClipOptions = MotionKeyframeOptions & {
@@ -58,6 +71,18 @@ export type StepClipOptions = MotionKeyframeOptions & {
* their insertion start until the glide ends.
*/
glide?: { offset: Vec3; seconds: number; nodeIds?: string[] };
+ /**
+ * Finished sub-assemblies that join on their own path. They play one after
+ * another before the step's own parts move (and before any `glide`); each
+ * travels as one rigid unit, turning about its own seated center.
+ */
+ units?: StepClipUnit[];
+};
+
+export type StepClipUnit = {
+ nodeIds: string[];
+ motion: Motion;
+ seconds: number;
};
/** Seconds a carried-in sub-assembly takes to glide to its insertion start. */
@@ -75,34 +100,92 @@ export const DEFAULT_WAYPOINT_DISTANCE = 50;
const NONE_STEP_SECONDS = 2;
/**
- * How a step spends its slot on the continuous timeline (`total`): a
- * carried-in sub-assembly's glide, the insertion, then the seated hold. The
- * slot is the explicit `durationSeconds` when set, otherwise the natural length
- * (a fixed slot for process-only steps). An authored duration shorter than the
- * animation speeds all three up to fit, so the step never ends mid-travel and
- * snaps its parts to their seat.
+ * How a step spends its slot on the continuous timeline (`total`): the
+ * sub-assemblies that join on their own path (`unitSeconds`, one after
+ * another), a carried-in sub-assembly's glide, the insertion, then the seated
+ * hold. The slot is the explicit `durationSeconds` when set, otherwise the
+ * natural length (a fixed slot for process-only steps). An authored duration
+ * shorter than the animation speeds everything up to fit, so the step never
+ * ends mid-travel and snaps its parts to their seat.
*/
export function stepClipTiming(
step: Pick<AssemblyStep, "motion" | "durationSeconds">,
- glideSeconds = 0
-): { total: number; glide: number; motion: number; hold: number } {
+ glideSeconds = 0,
+ unitSeconds: number[] = []
+): {
+ total: number;
+ units: number[];
+ glide: number;
+ motion: number;
+ hold: number;
+} {
+ const unitsTotal = unitSeconds.reduce((sum, seconds) => sum + seconds, 0);
const motion = step.motion.type === "none" ? 0 : motionDuration(step.motion);
- const natural = glideSeconds + motion + DEFAULT_HOLD_SECONDS;
+ const natural = unitsTotal + glideSeconds + motion + DEFAULT_HOLD_SECONDS;
const total =
step.durationSeconds && step.durationSeconds > 0
? step.durationSeconds
: step.motion.type === "none"
- ? glideSeconds + NONE_STEP_SECONDS
+ ? unitsTotal + glideSeconds + NONE_STEP_SECONDS
: natural;
const fit = Math.min(1, total / natural);
return {
total,
+ units: unitSeconds.map((seconds) => seconds * fit),
glide: glideSeconds * fit,
motion: motion * fit,
hold: DEFAULT_HOLD_SECONDS * fit
};
}
+/**
+ * Opacity of a seated fade-in at `elapsed` seconds into the step: 0 until
+ * `delay` (the step's units on their own path are still arriving), then up to
+ * 1 over `seconds`. A finished step — including one shown statically, at its
+ * end — is fully in.
+ */
+export function fadeProgress(
+ elapsed: number,
+ delay: number,
+ seconds: number,
+ finished: boolean
+): number {
+ if (finished) return 1;
+ return Math.min(Math.max((elapsed - delay) / seconds, 0), 1);
+}
+
+const PLAYABLE_MOTION_TYPES = new Set([
+ "linear",
+ "L",
+ "helix",
+ "path",
+ "waypoints",
+ "none"
+]);
+
+/**
+ * A stored motion the player can animate without throwing. Callers that read
+ * raw JSON (the MES) play anything else as `none`. Keyframed motions need at
+ * least two poses — `motionToKeyframes` throws on fewer.
+ */
+export function isPlayableMotion(value: unknown): value is Motion {
+ if (!value || typeof value !== "object") return false;
+ const motion = value as {
+ type?: unknown;
+ waypoints?: unknown;
+ keyframes?: unknown;
+ };
+ if (typeof motion.type !== "string") return false;
+ if (!PLAYABLE_MOTION_TYPES.has(motion.type)) return false;
+ if (motion.type === "waypoints") {
+ return Array.isArray(motion.waypoints) && motion.waypoints.length >= 2;
+ }
+ if (motion.type === "path") {
+ return Array.isArray(motion.keyframes) && motion.keyframes.length >= 2;
+ }
+ return true;
+}
+
/** Total travel distance (mm) implied by a motion. */
export function motionTravelDistance(motion: Motion): number {
switch (motion.type) {
@@ -127,11 +210,33 @@ export function motionTravelDistance(motion: Motion): number {
}
return total;
}
+ case "waypoints": {
+ let total = 0;
+ for (let i = 1; i < motion.waypoints.length; i++) {
+ const current = motion.waypoints[i];
+ const previous = motion.waypoints[i - 1];
+ if (!current || !previous) continue;
+ total += waypointLegTravel(previous, current);
+ }
+ return total;
+ }
case "none":
return 0;
}
}
+/** Turning counts as travel so a flip in place still takes readable time. */
+const TURN_MM_PER_RADIAN = 30;
+
+function waypointLegTravel(
+ from: WaypointsMotion["waypoints"][number],
+ to: WaypointsMotion["waypoints"][number]
+): number {
+ const distance = toVector3(from.offset).distanceTo(toVector3(to.offset));
+ const angle = toQuaternion(from.rotation).angleTo(toQuaternion(to.rotation));
+ return distance + angle * TURN_MM_PER_RADIAN;
+}
+
/** Animation duration (s) scaled to travel distance, clamped to 1–4 s. */
export function motionDuration(motion: Motion): number {
if (motion.type === "none") return 0;
@@ -479,6 +584,45 @@ export function motionToKeyframes(
}))
);
}
+
+ case "waypoints": {
+ const waypoints = motion.waypoints;
+ if (waypoints.length < 2) {
+ throw new Error("waypoints motion requires at least 2 waypoints");
+ }
+ // Each waypoint turns the whole set about its seated center, then shifts
+ // it: a part away from the center swings around it with the rest.
+ const pivot = options.pivot ? toVector3(options.pivot) : finalPosition;
+ const arm = finalPosition.clone().sub(pivot);
+ const poses = waypoints.map((waypoint, index) => {
+ if (index === waypoints.length - 1) {
+ return { position: finalPosition, quaternion: finalQuaternion };
+ }
+ const rotation = toQuaternion(waypoint.rotation);
+ return {
+ position: pivot
+ .clone()
+ .add(toVector3(waypoint.offset))
+ .add(arm.clone().applyQuaternion(rotation)),
+ quaternion: rotation.clone().multiply(finalQuaternion)
+ };
+ });
+ const legs = waypoints
+ .slice(1)
+ .map((waypoint, index) =>
+ waypointLegTravel(waypoints[index] ?? waypoint, waypoint)
+ );
+ const total = legs.reduce((sum, leg) => sum + leg, 0);
+ const times: number[] = [0];
+ let elapsed = 0;
+ for (const leg of legs) {
+ elapsed +=
+ total > 0 ? (leg / total) * duration : duration / legs.length;
+ times.push(elapsed);
+ }
+ times[times.length - 1] = duration;
+ return fromPoses(times, poses);
+ }
}
}
@@ -491,11 +635,13 @@ export function motionToKeyframes(
* final (seated) pose — or at their staging spot for a step built aside, which
* is the pose the insertion then ends at.
*
- * With `glide`, every node first glides from seat + offset to its insertion
- * start (a `none` motion glides straight to the seat).
+ * With `units`, each finished sub-assembly first travels its own path, one
+ * after another, while the step's own parts wait at their start. With `glide`,
+ * every node then glides from seat + offset to its insertion start (a `none`
+ * motion glides straight to the seat).
*
- * Returns `null` for `none` motions without a glide, or when no component
- * resolves to a node.
+ * Returns `null` when nothing moves: a `none` motion without a glide or units,
+ * or no component that resolves to a node.
*/
export function buildStepClip(
step: AssemblyStep,
@@ -503,12 +649,16 @@ export function buildStepClip(
options: StepClipOptions = {}
): AnimationClip | null {
const { glide } = options;
- if (
- (step.motion.type === "none" && !glide) ||
- step.componentNodeIds.length === 0
- ) {
- return null;
- }
+ const units = (options.units ?? []).filter(
+ (unit) => unit.nodeIds.length > 0 && unit.motion.type !== "none"
+ );
+ const unitNodeIds = new Set(units.flatMap((unit) => unit.nodeIds));
+ const ownNodeIds = step.componentNodeIds.filter(
+ (nodeId) => !unitNodeIds.has(nodeId)
+ );
+ const ownMoves =
+ ownNodeIds.length > 0 && (step.motion.type !== "none" || Boolean(glide));
+ if (!ownMoves && units.length === 0) return null;
const duration =
step.motion.type === "none"
@@ -516,107 +666,177 @@ export function buildStepClip(
: (options.duration ?? motionDuration(step.motion));
const glideSeconds = glide ? glide.seconds : 0;
const holdSeconds = options.holdSeconds ?? DEFAULT_HOLD_SECONDS;
+ const unitsSeconds = units.reduce((sum, unit) => sum + unit.seconds, 0);
+ const clipLength =
+ unitsSeconds + (ownMoves ? glideSeconds + duration : 0) + holdSeconds;
const tracks: (VectorKeyframeTrack | QuaternionKeyframeTrack)[] = [];
- for (const nodeId of step.componentNodeIds) {
- const node = nodesById.get(nodeId);
- if (!node) continue;
-
- node.updateWorldMatrix(true, false);
- const worldPosition = new Vector3();
- const worldQuaternion = new Quaternion();
- const worldScale = new Vector3();
- node.matrixWorld.decompose(worldPosition, worldQuaternion, worldScale);
+ let unitStart = 0;
+ for (const unit of units) {
+ const pivot =
+ unit.motion.type === "waypoints"
+ ? (seatedBoundsCenter(unit.nodeIds, nodesById) ?? undefined)
+ : undefined;
+ for (const nodeId of unit.nodeIds) {
+ const node = nodesById.get(nodeId);
+ if (!node) continue;
+ const { seatedPose, worldScale } = worldPoseOf(node);
+ const raw = motionToKeyframes(unit.motion, seatedPose, {
+ duration: unit.seconds,
+ pivot
+ });
+ if (!raw) continue;
+ const keyframes = delayKeyframes(
+ isEasedMotion(unit.motion) ? resampleEased(raw) : raw,
+ unitStart
+ );
+ tracks.push(...nodeTracks(node, keyframes, worldScale, clipLength));
+ }
+ unitStart += unit.seconds;
+ }
- const seatedPose: Pose = {
- position: worldPosition.toArray() as Vec3,
- quaternion: toQuat(worldQuaternion)
- };
- // A `none` motion only happens with a glide: the insertion is the seat itself.
- const rawKeyframes =
- step.motion.type === "none"
- ? {
- times: [0],
- positions: [...seatedPose.position],
- quaternions: [...seatedPose.quaternion]
- }
- : motionToKeyframes(step.motion, seatedPose, {
- ...options,
- duration
- });
- if (!rawKeyframes) continue;
- // Ease the straight insertion approaches (accelerate off the start, settle
- // into the seat). Helix threads at a constant rate (mechanically correct)
- // and paths carry their own timing, so leave those raw.
- const insertion =
- step.motion.type === "linear" || step.motion.type === "L"
+ if (ownMoves) {
+ const pivot =
+ step.motion.type === "waypoints"
+ ? (seatedBoundsCenter(ownNodeIds, nodesById) ?? undefined)
+ : undefined;
+ for (const nodeId of ownNodeIds) {
+ const node = nodesById.get(nodeId);
+ if (!node) continue;
+ const { seatedPose, worldScale } = worldPoseOf(node);
+ // A `none` motion only happens with a glide: the insertion is the seat itself.
+ const rawKeyframes =
+ step.motion.type === "none"
+ ? {
+ times: [0],
+ positions: [...seatedPose.position],
+ quaternions: [...seatedPose.quaternion]
+ }
+ : motionToKeyframes(step.motion, seatedPose, {
+ ...options,
+ duration,
+ pivot
+ });
+ if (!rawKeyframes) continue;
+ // Ease the straight and editor-drawn approaches (accelerate off the
+ // start, settle into the seat). Helix threads at a constant rate
+ // (mechanically correct) and planner paths carry their own timing.
+ const insertion = isEasedMotion(step.motion)
? resampleEased(rawKeyframes)
: rawKeyframes;
- const glides = glide && (!glide.nodeIds || glide.nodeIds.includes(nodeId));
- const keyframes = glide
- ? prependGlide(
- insertion,
- glides ? glide.offset : null,
- seatedPose,
- glide.seconds
+ const glides =
+ glide && (!glide.nodeIds || glide.nodeIds.includes(nodeId));
+ const keyframes = glide
+ ? prependGlide(
+ insertion,
+ glides ? glide.offset : null,
+ seatedPose,
+ glide.seconds
+ )
+ : insertion;
+ tracks.push(
+ ...nodeTracks(
+ node,
+ delayKeyframes(keyframes, unitsSeconds),
+ worldScale,
+ clipLength
)
- : insertion;
-
- const parentWorldInverse = node.parent
- ? node.parent.matrixWorld.clone().invert()
- : new Matrix4();
-
- const times: number[] = [];
- const positions: number[] = [];
- const quaternions: number[] = [];
- const worldMatrix = new Matrix4();
- const localMatrix = new Matrix4();
- const localPosition = new Vector3();
- const localQuaternion = new Quaternion();
- const localScale = new Vector3();
-
- const frameCount = keyframes.times.length;
- for (let i = 0; i < frameCount; i++) {
- const time = keyframes.times[i];
- if (time === undefined) continue;
- const position = new Vector3().fromArray(keyframes.positions, i * 3);
- const quaternion = new Quaternion().fromArray(
- keyframes.quaternions,
- i * 4
- );
- worldMatrix.compose(position, quaternion, worldScale);
- localMatrix.multiplyMatrices(parentWorldInverse, worldMatrix);
- localMatrix.decompose(localPosition, localQuaternion, localScale);
- times.push(time);
- positions.push(localPosition.x, localPosition.y, localPosition.z);
- quaternions.push(
- localQuaternion.x,
- localQuaternion.y,
- localQuaternion.z,
- localQuaternion.w
);
}
+ }
- // Hold the seated pose so LoopRepeat pauses before restarting.
- const lastTime = times[times.length - 1];
- if (holdSeconds > 0 && lastTime !== undefined) {
- times.push(lastTime + holdSeconds);
- positions.push(...positions.slice(-3));
- quaternions.push(...quaternions.slice(-4));
- }
+ if (tracks.length === 0) return null;
+ return new AnimationClip(`step:${step.id}`, clipLength, tracks);
+}
+
+function worldPoseOf(node: Object3D): {
+ seatedPose: Pose;
+ worldScale: Vector3;
+} {
+ node.updateWorldMatrix(true, false);
+ const worldPosition = new Vector3();
+ const worldQuaternion = new Quaternion();
+ const worldScale = new Vector3();
+ node.matrixWorld.decompose(worldPosition, worldQuaternion, worldScale);
+ return {
+ seatedPose: {
+ position: worldPosition.toArray() as Vec3,
+ quaternion: toQuat(worldQuaternion)
+ },
+ worldScale
+ };
+}
+
+/** Holds the first pose for `seconds`, then plays the keyframes. */
+function delayKeyframes(
+ keyframes: MotionKeyframes,
+ seconds: number
+): MotionKeyframes {
+ if (seconds <= 0 || keyframes.times.length === 0) return keyframes;
+ return {
+ times: [0, ...keyframes.times.map((time) => time + seconds)],
+ positions: [...keyframes.positions.slice(0, 3), ...keyframes.positions],
+ quaternions: [
+ ...keyframes.quaternions.slice(0, 4),
+ ...keyframes.quaternions
+ ]
+ };
+}
+
+/**
+ * World-space keyframes → uuid-bound tracks in the node's parent-local space,
+ * holding the last (seated) pose until `clipLength` so the loop pauses there.
+ */
+function nodeTracks(
+ node: Object3D,
+ keyframes: MotionKeyframes,
+ worldScale: Vector3,
+ clipLength: number
+): (VectorKeyframeTrack | QuaternionKeyframeTrack)[] {
+ const parentWorldInverse = node.parent
+ ? node.parent.matrixWorld.clone().invert()
+ : new Matrix4();
- tracks.push(
- new VectorKeyframeTrack(`${node.uuid}.position`, times, positions),
- new QuaternionKeyframeTrack(`${node.uuid}.quaternion`, times, quaternions)
+ const times: number[] = [];
+ const positions: number[] = [];
+ const quaternions: number[] = [];
+ const worldMatrix = new Matrix4();
+ const localMatrix = new Matrix4();
+ const localPosition = new Vector3();
+ const localQuaternion = new Quaternion();
+ const localScale = new Vector3();
+
+ const frameCount = keyframes.times.length;
+ for (let i = 0; i < frameCount; i++) {
+ const time = keyframes.times[i];
+ if (time === undefined) continue;
+ const position = new Vector3().fromArray(keyframes.positions, i * 3);
+ const quaternion = new Quaternion().fromArray(keyframes.quaternions, i * 4);
+ worldMatrix.compose(position, quaternion, worldScale);
+ localMatrix.multiplyMatrices(parentWorldInverse, worldMatrix);
+ localMatrix.decompose(localPosition, localQuaternion, localScale);
+ times.push(time);
+ positions.push(localPosition.x, localPosition.y, localPosition.z);
+ quaternions.push(
+ localQuaternion.x,
+ localQuaternion.y,
+ localQuaternion.z,
+ localQuaternion.w
);
}
- if (tracks.length === 0) return null;
- return new AnimationClip(
- `step:${step.id}`,
- glideSeconds + duration + holdSeconds,
- tracks
- );
+ // Hold the seated pose so LoopRepeat pauses before restarting.
+ const lastTime = times[times.length - 1];
+ if (lastTime !== undefined && lastTime < clipLength - 1e-9) {
+ times.push(clipLength);
+ positions.push(...positions.slice(-3));
+ quaternions.push(...quaternions.slice(-4));
+ }
+
+ return [
+ new VectorKeyframeTrack(`${node.uuid}.position`, times, positions),
+ new QuaternionKeyframeTrack(`${node.uuid}.quaternion`, times, quaternions)
+ ];
}
/**
@@ -739,6 +959,104 @@ export function waypointsToMotion(
return { type: "L", segments };
}
+/**
+ * One editable waypoint: where the moving set's seated center travels through
+ * (world space) and how it is turned there, relative to its seated pose.
+ */
+export type EditorWaypoint = { position: Vec3; rotation: Quat };
+
+const IDENTITY_QUAT: Quat = [0, 0, 0, 1];
+
+/**
+ * Editor waypoints for any motion. A `waypoints` motion keeps its rotations;
+ * every other motion goes through `motionToWaypoints` with no rotation.
+ */
+export function motionToEditorWaypoints(
+ motion: Motion,
+ seatedPosition: Vec3,
+ options: { defaultDistance?: number } = {}
+): EditorWaypoint[] {
+ if (motion.type === "waypoints" && motion.waypoints.length >= 2) {
+ const seated = toVector3(seatedPosition);
+ return motion.waypoints.map((waypoint) => ({
+ position: seated
+ .clone()
+ .add(toVector3(waypoint.offset))
+ .toArray() as Vec3,
+ rotation: waypoint.rotation
+ }));
+ }
+ return motionToWaypoints(motion, seatedPosition, options).map((position) => ({
+ position,
+ rotation: IDENTITY_QUAT
+ }));
+}
+
+/**
+ * Edited waypoints back to a motion. With no rotation anywhere it is the same
+ * `linear` / `L` / `none` the editor has always saved; any turned waypoint
+ * makes it a relative `waypoints` motion. The last waypoint is forced to the
+ * seat, unturned.
+ */
+export function editorWaypointsToMotion(
+ waypoints: EditorWaypoint[],
+ seatedPosition: Vec3
+): Motion {
+ const rotated = waypoints
+ .slice(0, -1)
+ .some((waypoint) => !isIdentityRotation(waypoint.rotation));
+ if (!rotated) {
+ return waypointsToMotion(
+ waypoints.map((waypoint) => waypoint.position),
+ seatedPosition
+ );
+ }
+ const seated = toVector3(seatedPosition);
+ return {
+ type: "waypoints",
+ waypoints: waypoints.map((waypoint, index) =>
+ index === waypoints.length - 1
+ ? { offset: [0, 0, 0], rotation: IDENTITY_QUAT }
+ : {
+ offset: toVector3(waypoint.position).sub(seated).toArray() as Vec3,
+ rotation: toQuat(toQuaternion(waypoint.rotation))
+ }
+ )
+ };
+}
+
+function isIdentityRotation(rotation: Quat): boolean {
+ return Math.abs(toQuaternion(rotation).w) >= 1 - 1e-6;
+}
+
+function isEasedMotion(motion: Motion): boolean {
+ return (
+ motion.type === "linear" ||
+ motion.type === "L" ||
+ motion.type === "waypoints"
+ );
+}
+
+/**
+ * Center of the nodes' seated world bounds — the visual middle of the set,
+ * which a `waypoints` motion turns about. Node origins won't do: CAD exports
+ * often pivot far from the geometry. The editor anchors its path here too.
+ */
+export function seatedBoundsCenter(
+ nodeIds: string[],
+ nodesById: Map<string, Object3D>
+): Vec3 | null {
+ const box = new Box3();
+ for (const nodeId of nodeIds) {
+ const node = nodesById.get(nodeId);
+ if (!node) continue;
+ node.updateWorldMatrix(true, false);
+ box.expandByObject(node);
+ }
+ if (box.isEmpty()) return null;
+ return box.getCenter(new Vector3()).toArray() as Vec3;
+}
+
/** Flat [x,y,z,…] → Vec3[], dropping consecutive coincident points. */
function dedupePositions(flat: number[]): Vec3[] {
const points: Vec3[] = [];
diff --git a/packages/viewer/src/subassembly.test.ts b/packages/viewer/src/subassembly.test.ts
index 89bbf986f1..eb34556823 100644
--- a/packages/viewer/src/subassembly.test.ts
+++ b/packages/viewer/src/subassembly.test.ts
@@ -5,6 +5,7 @@
import { describe, expect, it } from "vitest";
import {
arrivalIndexByNode,
+ buildCarryPlans,
buildSubAssemblyPlan,
displayOrder,
subAssemblyPartIds,
@@ -12,7 +13,7 @@ import {
validateSubAssemblies,
worldOf
} from "./subassembly";
-import type { AssemblyStep } from "./types";
+import type { AssemblyStep, Motion } from "./types";
type Row = Pick<
AssemblyStep,
@@ -235,3 +236,61 @@ describe("usableSubAssemblies", () => {
expect(reasons("heel")).toEqual({ drive: "header", heel: "header" });
});
});
+
+describe("buildCarryPlans", () => {
+ const drop: Motion = { type: "linear", direction: [0, 0, -1], distance: 40 };
+ const withMotion = (paths: Record<string, Motion>) =>
+ example.map((row) => ({
+ ...row,
+ motion: paths[row.id] ?? ({ type: "none" } as Motion)
+ }));
+ const plansFor = (paths: Record<string, Motion>) => {
+ const rows = withMotion(paths);
+ const plans = buildCarryPlans(rows, buildSubAssemblyPlan(rows));
+ return Object.fromEntries(rows.map((row, i) => [row.id, plans[i]]));
+ };
+
+ it("keeps the glide for a sub-assembly with no path of its own", () => {
+ const plans = plansFor({});
+ expect(plans.fit?.pathUnits).toEqual([]);
+ expect(plans.fit?.glidingPartIds.sort()).toEqual(
+ ["idler", "pinion", "plate"].sort()
+ );
+ expect(plans.heel?.joinsOnOwnPath).toBe(false);
+ });
+
+ it("flies a sub-assembly with a path instead of gliding it", () => {
+ const plans = plansFor({ drive: drop });
+ expect(plans.fit?.pathUnits).toEqual([
+ {
+ headerId: "drive",
+ nodeIds: ["plate", "pinion", "idler"],
+ motion: drop
+ }
+ ]);
+ expect(plans.fit?.glidingPartIds).toEqual([]);
+ expect(plans.fit?.carriedPartIds.sort()).toEqual(
+ ["idler", "pinion", "plate"].sort()
+ );
+ // Its header is used, so it is not where the unit joins.
+ expect(plans.drive?.joinsOnOwnPath).toBe(false);
+ });
+
+ it("an unused header with a path joins on it", () => {
+ const plans = plansFor({ heel: drop });
+ expect(plans.heel?.joinsOnOwnPath).toBe(true);
+ expect(plans.heel?.pathUnits.map((unit) => unit.headerId)).toEqual([
+ "heel"
+ ]);
+ expect(plans.heel?.glidingPartIds).toEqual([]);
+ });
+
+ it("steps that carry nothing in have an empty plan", () => {
+ expect(plansFor({ drive: drop }).sole).toEqual({
+ carriedPartIds: [],
+ pathUnits: [],
+ glidingPartIds: [],
+ joinsOnOwnPath: false
+ });
+ });
+});
diff --git a/packages/viewer/src/subassembly.ts b/packages/viewer/src/subassembly.ts
index c42f90fc77..d3ab82bf5e 100644
--- a/packages/viewer/src/subassembly.ts
+++ b/packages/viewer/src/subassembly.ts
@@ -15,7 +15,7 @@
* (step list, which actions to offer) and the ERP service (write validation),
* so all three answer the same question the same way.
*/
-import type { AssemblyStep } from "./types";
+import type { AssemblyStep, Motion } from "./types";
type StructureStep = Pick<
AssemblyStep,
@@ -199,6 +199,57 @@ export function buildSubAssemblyPlan(
return plan;
}
+/** A finished sub-assembly that joins on a path of its own (its header's motion). */
+export type PathUnit = { headerId: string; nodeIds: string[]; motion: Motion };
+
+/** How the finished sub-assemblies a step carries in arrive. */
+export type CarryPlan = {
+ carriedPartIds: string[];
+ /** The ones with a path of their own, in sub-assembly order: they fly in first. */
+ pathUnits: PathUnit[];
+ /** Carried parts with no path of their own: they glide in beside the build. */
+ glidingPartIds: string[];
+ /**
+ * The step is an unused header whose unit joins on its own path. That path
+ * IS the header's motion, so the header has no insertion of its own.
+ */
+ joinsOnOwnPath: boolean;
+};
+
+/**
+ * Per step (same order as `steps`): which finished sub-assemblies arrive and
+ * how. A header whose `motion` is not `none` has a path of its own; the rest
+ * keep the glide from beside the build.
+ */
+export function buildCarryPlans(
+ steps: (StructureStep & Pick<AssemblyStep, "motion">)[],
+ subPlan: Map<string, SubAssemblyInfo>
+): CarryPlan[] {
+ const byId = new Map(steps.map((step) => [step.id, step]));
+ return steps.map((step) => {
+ const headers = subPlan.get(step.id)?.carriesIn ?? [];
+ const carried = new Set<string>();
+ const onPath = new Set<string>();
+ const pathUnits: PathUnit[] = [];
+ for (const headerId of headers) {
+ const nodeIds = subAssemblyPartIds(steps, headerId);
+ for (const id of nodeIds) carried.add(id);
+ const header = byId.get(headerId);
+ if (header && header.motion.type !== "none") {
+ pathUnits.push({ headerId, nodeIds, motion: header.motion });
+ for (const id of nodeIds) onPath.add(id);
+ }
+ }
+ const carriedPartIds = [...carried];
+ return {
+ carriedPartIds,
+ pathUnits,
+ glidingPartIds: carriedPartIds.filter((id) => !onPath.has(id)),
+ joinsOnOwnPath: pathUnits.some((unit) => unit.headerId === step.id)
+ };
+ });
+}
+
export type SubAssemblyRule = 1 | 2 | 3;
export type SubAssemblyViolation = {
diff --git a/packages/viewer/src/types.ts b/packages/viewer/src/types.ts
index f75bad8d46..7c4a630c37 100644
--- a/packages/viewer/src/types.ts
+++ b/packages/viewer/src/types.ts
@@ -3,10 +3,12 @@
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
- * Shared contracts for animated work instructions (Phase 0).
- * These types mirror `docs/specs/animated-work-instructions-contracts.md` exactly.
- * Change them only by updating the geometry service, the ERP/Inngest layer, and
- * this package together.
+ * Shared contracts for animated work instructions. This file IS the contract:
+ * the geometry service writes these shapes into plan.json, the ERP/Inngest
+ * layer stores them on steps, and the player animates them. Change a shape the
+ * geometry service emits only by updating it, the ERP/Inngest layer, and this
+ * package together. `waypoints` is editor-only — the geometry service never
+ * reads or writes it.
*/
export type Vec3 = [number, number, number];
@@ -52,6 +54,18 @@ export type PathMotion = {
keyframes: { t: number; position: Vec3; quaternion: Quat }[];
};
+/**
+ * Editor-authored path with rotation. Poses are RELATIVE to the moving set's
+ * seated pose: each waypoint turns the set by `rotation` about its seated
+ * center, then shifts it by `offset`. So one motion applies to a single part,
+ * a rigid group, or a whole sub-assembly. First = start, last = seat
+ * (offset [0,0,0], rotation [0,0,0,1]).
+ */
+export type WaypointsMotion = {
+ type: "waypoints";
+ waypoints: { offset: Vec3; rotation: Quat }[];
+};
+
/** No geometry motion (process-only step: cure, inspect, torque pattern). */
export type NoneMotion = {
type: "none";
@@ -68,6 +82,7 @@ export type Motion =
| LMotion
| HelixMotion
| PathMotion
+ | WaypointsMotion
| NoneMotion;
/** Step camera. `null` on a step means the viewer auto-frames the active components. */