@things-factory/figure-ui 10.1.26 → 10.1.27

package/client/modeller/joint-edits.ts

@@ -0,0 +1,201 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+
+import type { FigureJoint, FigurePart, JointType, Vec3 } from '@hatiolab/figure-model'
+
+import type { FigureDraft, PartModel } from './figure-source.js'
+
+/**
+ * Editing joints and parents (ADR-0066). Pure functions over the draft and the part list, so the inspector
+ * only renders and dispatches.
+ *
+ * A joint is always created together with the parameter that drives it. Values reach a joint only through
+ * `parameters`, and the preview draws a slider per parameter, so a joint without one could be defined but
+ * never seen moving.
+ */
+
+type Parameter = NonNullable<FigureDraft['parameters']>[number]
+
+/** The limits a new joint starts with. Revolute in degrees, prismatic in millimetres. */
+const NEW_LIMITS: Record<Exclude<JointType, 'continuous'>, { min: number; max: number }> = {
+  revolute: { min: -90, max: 90 },
+  prismatic: { min: 0, max: 500 }
+}
+
+/** The span a parameter driving a continuous joint offers: one turn either way. */
+const CONTINUOUS_SPAN = { min: -360, max: 360 }
+
+/** The joint whose child is this part, if any. */
+export function jointOf(draft: FigureDraft | undefined, part: string): FigureJoint | undefined {
+  return draft?.joints?.find(joint => joint.child === part)
+}
+
+/**
+ * Parts a part may be attached to: every other part except itself and anything attached below it, since
+ * either would close a loop the format refuses (`parent-cycle`).
+ */
+export function parentChoices(parts: readonly PartModel[], part: string): string[] {
+  const below = new Set<string>([part])
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const one of parts) {
+      if (one.parent !== undefined && below.has(one.parent) && !below.has(one.name)) {
+        below.add(one.name)
+        grew = true
+      }
+    }
+  }
+  return parts.map(one => one.name).filter(name => !!name && !below.has(name))
+}
+
+function freeName(taken: Iterable<string>, stem: string): string {
+  const used = new Set(taken)
+  if (!used.has(stem)) return stem
+  for (let n = 2; ; n++) if (!used.has(`${stem}-${n}`)) return `${stem}-${n}`
+}
+
+/** The span the driving parameter offers for a joint: its limits, or one turn either way when it has none. */
+function spanOf(joint: FigureJoint): { min: number; max: number } {
+  return joint.limits ?? CONTINUOUS_SPAN
+}
+
+function drivingParameter(joint: FigureJoint): Parameter {
+  const span = spanOf(joint)
+  return {
+    name: joint.name,
+    range: { unit: joint.type === 'prismatic' ? 'mm' : 'deg', min: span.min, max: span.max },
+    default: 0,
+    clip: {
+      channels: [
+        {
+          target: joint.name,
+          keys: [
+            { at: 0, value: span.min },
+            { at: 1, value: span.max }
+          ]
+        }
+      ]
+    }
+  }
+}
+
+/**
+ * Whether a parameter is the plain one `setJointType` made for a joint: one channel on that joint, keys at
+ * 0 and 1 spanning the given limits. Only such a parameter follows the joint when its limits or type change;
+ * one the author reshaped is left as written.
+ */
+function isPlainDriver(parameter: Parameter, joint: FigureJoint, span: { min: number; max: number }): boolean {
+  const channels = parameter.clip?.channels ?? []
+  if (channels.length !== 1) return false
+  const [channel] = channels
+  if (channel!.target !== joint.name || channel!.path !== undefined) return false
+  const keys = channel!.keys as { at: number; value: number }[]
+  return (
+    keys.length === 2 &&
+    keys[0]!.at === 0 &&
+    keys[1]!.at === 1 &&
+    keys[0]!.value === span.min &&
+    keys[1]!.value === span.max &&
+    parameter.range?.min === span.min &&
+    parameter.range?.max === span.max
+  )
+}
+
+/**
+ * Sets how a part moves relative to its parent, or clears the joint with `undefined`.
+ *
+ * - From none: adds a joint whose origin is the centre of the part's bottom face, with a vertical axis and
+ *   starting limits, and a parameter that drives it over those limits.
+ * - To none: removes the joint and every channel that drove it; a parameter or clip left with no channel
+ *   is removed too, because the format refuses an empty one.
+ * - Between types: keeps the origin and axis, sets limits for the new type (none for continuous), and
+ *   moves a plain driving parameter along with them.
+ */
+export function setJointType(draft: FigureDraft, part: FigurePart, type: JointType | undefined): FigureDraft {
+  const joints = draft.joints ?? []
+  const existing = joints.find(joint => joint.child === part.name)
+
+  if (type === undefined) {
+    if (!existing) return draft
+    return withoutJoint(draft, existing.name)
+  }
+
+  if (!existing) {
+    const { position, size } = part.transform
+    const joint: FigureJoint = {
+      name: freeName([...joints.map(one => one.name)], `${part.name}-joint`),
+      child: part.name,
+      type,
+      origin: { x: position.x, y: position.y - size.y / 2, z: position.z },
+      axis: { x: 0, y: 1, z: 0 }
+    }
+    if (type !== 'continuous') joint.limits = { ...NEW_LIMITS[type] }
+
+    const parameters = draft.parameters ?? []
+    const taken = [...parameters.map(one => one.name), ...(draft.animations ?? []).map(one => one.name)]
+    const driver = drivingParameter(joint)
+    driver.name = freeName(taken, joint.name)
+
+    return { ...draft, joints: [...joints, joint], parameters: [...parameters, driver] }
+  }
+
+  if (existing.type === type) return draft
+
+  const next: FigureJoint = { ...existing, type }
+  if (type === 'continuous') delete next.limits
+  else if (existing.type === 'continuous' || (existing.type === 'prismatic') !== (type === 'prismatic')) {
+    next.limits = { ...NEW_LIMITS[type] }
+  }
+
+  return replaceJoint(draft, existing, next)
+}
+
+/** Changes a joint's origin, axis or limits. A plain driving parameter follows new limits. */
+export function patchJoint(
+  draft: FigureDraft,
+  name: string,
+  patch: { origin?: Vec3; axis?: Vec3; limits?: { min: number; max: number } }
+): FigureDraft {
+  const existing = draft.joints?.find(joint => joint.name === name)
+  if (!existing) return draft
+  const next: FigureJoint = { ...existing, ...patch }
+  if (existing.type === 'continuous') delete next.limits
+  return replaceJoint(draft, existing, next)
+}
+
+function replaceJoint(draft: FigureDraft, before: FigureJoint, after: FigureJoint): FigureDraft {
+  const joints = (draft.joints ?? []).map(joint => (joint === before ? after : joint))
+  const was = spanOf(before)
+  const unitChanged = (before.type === 'prismatic') !== (after.type === 'prismatic')
+  const spanChanged = was.min !== spanOf(after).min || was.max !== spanOf(after).max
+
+  if (!unitChanged && !spanChanged) return { ...draft, joints }
+
+  const parameters = (draft.parameters ?? []).map(parameter => {
+    if (!isPlainDriver(parameter, before, was)) return parameter
+    const driver = drivingParameter(after)
+    return { ...parameter, range: driver.range, clip: { ...parameter.clip, channels: driver.clip.channels } }
+  })
+  return { ...draft, joints, parameters }
+}
+
+function withoutJoint(draft: FigureDraft, name: string): FigureDraft {
+  const keep = <T extends { channels?: { target: string }[] }>(one: T) => (one.channels ?? []).filter(channel => channel.target !== name)
+
+  const parameters = (draft.parameters ?? [])
+    .map(parameter => ({ ...parameter, clip: { ...parameter.clip, channels: keep(parameter.clip) } }) as Parameter)
+    .filter(parameter => parameter.clip.channels.length > 0)
+  const animations = (draft.animations ?? [])
+    .map(clip => ({ ...clip, channels: keep(clip) }) as NonNullable<FigureDraft['animations']>[number])
+    .filter(clip => clip.channels.length > 0)
+  const joints = (draft.joints ?? []).filter(joint => joint.name !== name)
+
+  const next: FigureDraft = { ...draft }
+  if (joints.length > 0) next.joints = joints
+  else delete next.joints
+  if (draft.parameters !== undefined) next.parameters = parameters
+  if (draft.animations !== undefined) next.animations = animations
+  return next
+}

package/dist-client/modeller/figure-animations.d.ts

@@ -19,6 +19,8 @@ export declare class FigureAnimations extends FigureAnimations_base {
     private channelsOf;
     /** 부품 이름 — 채널이 이것을 가리킨다. */
     private get partNames();
+    /** Joints a channel can drive instead of a part (ADR-0066). */
+    private get joints();
     /**
      * 몇 부품이 움직이나 — 채널이 가리키는 **서로 다른 부품**의 수.
      *
@@ -69,6 +71,11 @@ export declare class FigureAnimations extends FigureAnimations_base {
      * 시각이 오름차순이어야 하는 것도 형식의 규칙이다. 여기서는 어긋난 줄을 붉게 내고 값을
      * 고치지는 않는다 — 저작자가 3 을 1 로 고치던 중일 수 있다.
      */
+    /**
+     * Keys of a joint channel: a position and one joint coordinate each. A value outside the joint's limits
+     * is marked and left as typed; the format refuses it on save.
+     */
+    private renderJointKeys;
     private renderKeys;
     /**
      * 움직이는 부품 예산.
@@ -111,6 +118,12 @@ export declare class FigureAnimations extends FigureAnimations_base {
     private removeClip;
     private removeParameter;
     private addChannel;
+    /**
+     * Points a channel at another part or joint. Crossing between the two changes the channel's shape: a
+     * joint channel has no path and one number per key, a part channel a path and a vector. The key positions
+     * are kept, since they are the author's timing; values restart at the rest pose.
+     */
+    private retarget;
     private setChannel;
     /**
      * 경로를 바꾼다 — **값까지 함께 옮긴다.**
@@ -123,6 +136,7 @@ export declare class FigureAnimations extends FigureAnimations_base {
     private removeChannel;
     /** 마지막 키에서 1 초 뒤. 값은 그 키를 그대로 받는다 — 붙여 놓고 고치는 것이 짜기 쉽다. */
     private addKey;
+    private setJointKey;
     private setKey;
     /** 둘 미만으로 내려가지 않는다 — 단추가 이미 죽어 있지만 밖에서 불릴 수 있다. */
     private removeKey;

package/dist-client/modeller/figure-animations.js

@@ -5,6 +5,10 @@ import { live } from 'lit/directives/live.js';
 import { i18next, localize } from '@operato/i18n';
 import { ScrollbarStyles } from '@operato/styles';
 import { AXES, CHANNEL_PATHS, INTERPOLATIONS, LIMITS } from '@hatiolab/figure-model';
+/** A channel that drives a joint names the joint and carries one number per key (ADR-0066). */
+function isJointChannel(channel) {
+    return channel.path === undefined;
+}
 /*
   레시피의 `end` 가 곧 그 범위의 끝 자세다 — 리프트가 100mm 올라가는 곡선이면 범위도
   0~100mm 다. 둘이 어긋나면 저작자가 1200 을 주고도 100 만 올라가는 것을 보게 된다.
@@ -291,6 +295,10 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
     get partNames() {
         return this.parts.map(part => part.name).filter(name => !!name);
     }
+    /** Joints a channel can drive instead of a part (ADR-0066). */
+    get joints() {
+        return this.draft?.joints ?? [];
+    }
     /**
      * 몇 부품이 움직이나 — 채널이 가리키는 **서로 다른 부품**의 수.
      *
@@ -520,23 +528,45 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
      * 검증은 저장할 때 말하고 여기서는 **그 자리에서** 보여 준다.
      */
     renderChannel(kind, channel, at, j) {
-        const orphan = !this.partNames.includes(channel.target);
+        const joint = this.joints.find(one => one.name === channel.target);
+        const orphan = !this.partNames.includes(channel.target) && !joint;
+        const target = html `
+      <div row>
+        <label>${i18next.t('figure.label.channel-target')}</label>
+        <select
+          .value=${live(channel.target ?? '')}
+          @change=${(e) => this.retarget(kind, at, j, e.target.value)}
+        >
+          ${orphan ? html `<option value=${channel.target}>${channel.target}</option>` : nothing}
+          <optgroup label=${i18next.t('figure.label.channel-target-parts')}>
+            ${this.partNames.map(name => html `<option value=${name}>${name}</option>`)}
+          </optgroup>
+          ${this.joints.length > 0
+            ? html `<optgroup label=${i18next.t('figure.label.channel-target-joints')}>
+                ${this.joints.map(one => html `<option value=${one.name}>${one.name}</option>`)}
+              </optgroup>`
+            : nothing}
+        </select>
+        <button plain @click=${() => this.removeChannel(kind, at, j)} title=${i18next.t('figure.button.remove')}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+    `;
+        /* A joint channel has no path or pivot: the joint says what moves. Each key is the joint coordinate. */
+        if (isJointChannel(channel)) {
+            const unit = joint?.type === 'prismatic' ? 'mm' : 'deg';
+            return html `
+        <div channel ?orphan=${orphan}>
+          ${target} ${orphan ? html `<p warn>${i18next.t('figure.text.channel-target-is-gone')}</p>` : nothing}
+          <p quiet>${i18next.t('figure.text.joint-channel-value-' + unit)}</p>
+          ${this.renderJointKeys(kind, channel, at, j, joint?.limits)}
+        </div>
+      `;
+        }
         const turning = channel.path === 'rotation';
         return html `
       <div channel ?orphan=${orphan}>
-        <div row>
-          <label>${i18next.t('figure.label.channel-target')}</label>
-          <select
-            .value=${live(channel.target ?? '')}
-            @change=${(e) => this.setChannel(kind, at, j, { target: e.target.value })}
-          >
-            ${orphan ? html `<option value=${channel.target}>${channel.target}</option>` : nothing}
-            ${this.partNames.map(name => html `<option value=${name}>${name}</option>`)}
-          </select>
-          <button plain @click=${() => this.removeChannel(kind, at, j)} title=${i18next.t('figure.button.remove')}>
-            <md-icon>close</md-icon>
-          </button>
-        </div>
+        ${target}
 
         ${orphan ? html `<p warn>${i18next.t('figure.text.channel-target-is-gone')}</p>` : nothing}
 
@@ -607,6 +637,66 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
      * 시각이 오름차순이어야 하는 것도 형식의 규칙이다. 여기서는 어긋난 줄을 붉게 내고 값을
      * 고치지는 않는다 — 저작자가 3 을 1 로 고치던 중일 수 있다.
      */
+    /**
+     * Keys of a joint channel: a position and one joint coordinate each. A value outside the joint's limits
+     * is marked and left as typed; the format refuses it on save.
+     */
+    renderJointKeys(kind, channel, at, j, limits) {
+        const keys = channel.keys ?? [];
+        const onValues = kind === 'parameter';
+        const beyond = (key) => !!limits && (key.value < limits.min || key.value > limits.max);
+        return html `
+      <table keys>
+        <tr>
+          <th>${i18next.t(onValues ? 'figure.label.key-at-value' : 'figure.label.key-at')}</th>
+          <th>${i18next.t('figure.label.joint-value')}</th>
+          <th></th>
+        </tr>
+        ${keys.map((key, k) => {
+            const backwards = k > 0 && key.at <= (keys[k - 1].at ?? 0);
+            return html `
+            <tr>
+              <td>
+                <input
+                  type="number"
+                  step=${onValues ? '0.05' : '0.1'}
+                  min="0"
+                  max=${onValues ? '1' : nothing}
+                  ?bad=${backwards || key.at < 0 || (onValues && key.at > 1)}
+                  .value=${live(String(key.at))}
+                  @change=${(e) => this.setJointKey(kind, at, j, k, { at: Math.max(0, Number(e.target.value) || 0) })}
+                />
+              </td>
+              <td>
+                <input
+                  type="number"
+                  step="1"
+                  ?bad=${beyond(key)}
+                  .value=${live(String(key.value))}
+                  title=${beyond(key) ? i18next.t('figure.text.joint-value-beyond-limits') : ''}
+                  @change=${(e) => this.setJointKey(kind, at, j, k, { value: Number(e.target.value) || 0 })}
+                />
+              </td>
+              <td drop>
+                <button
+                  plain
+                  ?disabled=${keys.length <= 2}
+                  title=${keys.length <= 2 ? i18next.t('figure.text.two-keys-at-least') : i18next.t('figure.button.remove')}
+                  @click=${() => this.removeKey(kind, at, j, k)}
+                >
+                  <md-icon>close</md-icon>
+                </button>
+              </td>
+            </tr>
+          `;
+        })}
+      </table>
+      ${keys.some(beyond) ? html `<p warn>${i18next.t('figure.text.joint-value-beyond-limits')}</p>` : nothing}
+      <button @click=${() => this.addKey(kind, at, j)}>
+        <md-icon>add</md-icon>${i18next.t('figure.button.add-key')}
+      </button>
+    `;
+    }
     renderKeys(kind, channel, at, j) {
         const keys = channel.keys ?? [];
         /*
@@ -836,10 +926,36 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
             { target, path: 'translation', keys: keysFor('translation') }
         ]);
     }
-    setChannel(kind, at, j, patch) {
+    /**
+     * Points a channel at another part or joint. Crossing between the two changes the channel's shape: a
+     * joint channel has no path and one number per key, a part channel a path and a vector. The key positions
+     * are kept, since they are the author's timing; values restart at the rest pose.
+     */
+    retarget(kind, at, j, target) {
         const channel = this.channelsOf(kind, at)[j];
         if (!channel)
             return;
+        const toJoint = this.joints.some(one => one.name === target);
+        if (toJoint && !isJointChannel(channel)) {
+            const next = { target, keys: channel.keys.map(key => ({ at: key.at, value: 0 })) };
+            if (channel.interpolation !== undefined)
+                next.interpolation = channel.interpolation;
+            this.patchChannel(kind, at, j, next);
+            return;
+        }
+        if (!toJoint && isJointChannel(channel)) {
+            const next = { target, path: 'translation', keys: channel.keys.map(key => ({ at: key.at, value: startValue('translation') })) };
+            if (channel.interpolation !== undefined)
+                next.interpolation = channel.interpolation;
+            this.patchChannel(kind, at, j, next);
+            return;
+        }
+        this.patchChannel(kind, at, j, { ...channel, target });
+    }
+    setChannel(kind, at, j, patch) {
+        const channel = this.channelsOf(kind, at)[j];
+        if (!channel || isJointChannel(channel))
+            return;
         const next = { ...channel, ...patch };
         /* `undefined` 를 얹는 것은 지우는 뜻이다. 남겨 두면 저장 형식에 빈 칸이 실린다. */
         if ('pivot' in patch && patch.pivot === undefined)
@@ -855,7 +971,7 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
      */
     setPath(kind, at, j, path) {
         const channel = this.channelsOf(kind, at)[j];
-        if (!channel)
+        if (!channel || isJointChannel(channel))
             return;
         const crossing = (channel.path === 'scale') !== (path === 'scale');
         const next = {
@@ -876,6 +992,18 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
         const channel = this.channelsOf(kind, at)[j];
         if (!channel)
             return;
+        if (isJointChannel(channel)) {
+            const keys = channel.keys;
+            const end = keys[keys.length - 1];
+            if (kind === 'parameter' && keys.length >= 2) {
+                const before = keys[keys.length - 2];
+                const middle = { at: (before.at + end.at) / 2, value: before.value };
+                this.patchChannel(kind, at, j, { ...channel, keys: [...keys.slice(0, -1), middle, end] });
+                return;
+            }
+            this.patchChannel(kind, at, j, { ...channel, keys: [...keys, { at: (end?.at ?? 0) + 1, value: end?.value ?? 0 }] });
+            return;
+        }
         const last = channel.keys[channel.keys.length - 1];
         /*
           A parameter curve ends at 1, so appending a key would make it unreachable. Insert it between the last two keys.
@@ -889,9 +1017,15 @@ let FigureAnimations = class FigureAnimations extends localize(i18next)(LitEleme
         const key = { at: (last?.at ?? 0) + 1, value: { ...(last?.value ?? startValue(channel.path)) } };
         this.patchChannel(kind, at, j, { ...channel, keys: [...channel.keys, key] });
     }
+    setJointKey(kind, at, j, k, patch) {
+        const channel = this.channelsOf(kind, at)[j];
+        if (!channel || !isJointChannel(channel))
+            return;
+        this.patchChannel(kind, at, j, { ...channel, keys: channel.keys.map((key, i) => (i === k ? { ...key, ...patch } : key)) });
+    }
     setKey(kind, at, j, k, patch) {
         const channel = this.channelsOf(kind, at)[j];
-        if (!channel)
+        if (!channel || isJointChannel(channel))
             return;
         this.patchChannel(kind, at, j, {
             ...channel,