@fmsim/machine 2.0.0-beta.86 → 2.0.0-beta.88

package/dist/utils/crane-position.js

@@ -0,0 +1,96 @@
+/*
+ * Crane 위치 데이터 (data.cranePosition) 변환 유틸.
+ *
+ * 명세:
+ *   {
+ *     cranePosition: {
+ *       current: { x, y, z },               // 실 좌표값
+ *       limit: { x:{min,max}, y:{min,max}, z:{min,max} }  // 각 축 한계
+ *     }
+ *   }
+ *
+ * current 를 limit 범위 안의 0~1 비율로 환산한 뒤 host(부모) footprint 에 매핑한다.
+ * x → host 긴쪽, y → 짧은쪽, z → 포크 높이(forkZ 0~100).
+ */
+/**
+ * current 값을 limit 범위 안에서 0~1 비율로 환산.
+ * limit 누락 / 0 span / 비정상 입력 시 0 반환 (안전 fallback).
+ */
+export function axisRatio(value, lim) {
+    const v = Number(value);
+    const min = Number(lim === null || lim === void 0 ? void 0 : lim.min) || 0;
+    const max = Number(lim === null || lim === void 0 ? void 0 : lim.max);
+    if (!Number.isFinite(v) || !Number.isFinite(max) || max === min)
+        return 0;
+    return Math.max(0, Math.min(1, (v - min) / (max - min)));
+}
+/**
+ * host(부모) footprint 안에서 0~1 비율 (rx,ry) → 크레인 top-left 로컬 좌표.
+ *
+ * **스토커 안쪽 오프셋**: 크레인의 폭/두께를 감안해, 크레인 *전체* 가 host 안에
+ * 머무르도록 top-left 좌표를 [0, hostLen - craneLen] 범위로 매핑한다 (= 양끝에서
+ * craneLen/2 만큼 inset 된 중심선 위를 움직임). 크레인이 host 보다 크면 span 0
+ * 으로 떨어져 host 모서리에 정렬.
+ *
+ * x(rx) 는 host 의 긴쪽, y(ry) 는 짧은쪽에 매핑 (가상 rail 은 host 긴쪽 방향).
+ */
+export function mapCraneLocalPosition(hostW, hostH, craneW, craneH, rx, ry) {
+    const longIsWidth = hostW >= hostH;
+    const longLen = longIsWidth ? hostW : hostH;
+    const shortLen = longIsWidth ? hostH : hostW;
+    const craneLongSize = longIsWidth ? craneW : craneH;
+    const craneShortSize = longIsWidth ? craneH : craneW;
+    // 크레인 크기를 뺀 inset 가용 span. top-left = ratio * span 이므로 크레인
+    // 전체가 host [0, hostLen] 안에 들어온다.
+    const longSpan = Math.max(0, longLen - craneLongSize);
+    const shortSpan = Math.max(0, shortLen - craneShortSize);
+    const longPos = rx * longSpan;
+    const shortPos = ry * shortSpan;
+    return {
+        left: longIsWidth ? longPos : shortPos,
+        top: longIsWidth ? shortPos : longPos
+    };
+}
+/**
+ * 객체에서 key 를 **대소문자 무관**으로 찾아 값 반환 (정확 매치 우선, 없으면 소문자 비교).
+ * 데이터 명세의 키 대소문자가 흔들려도(cranePosition / CRANEPOSITION / DURATION_MS …)
+ * 동일하게 읽기 위함. 매치 없으면 undefined.
+ */
+export function ciGet(obj, key) {
+    if (!obj || typeof obj !== 'object')
+        return undefined;
+    if (key in obj)
+        return obj[key];
+    const lower = key.toLowerCase();
+    for (const k of Object.keys(obj)) {
+        if (k.toLowerCase() === lower)
+            return obj[k];
+    }
+    return undefined;
+}
+/**
+ * 객체 키를 재귀적으로 소문자화한 사본 반환 (배열/원시값은 그대로, 값은 변형 안 함).
+ * 중첩 키(current/limit/x/y/z/min/max)를 대소문자 무관으로 접근하기 위한 정규화.
+ */
+export function lowerKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(v => lowerKeysDeep(v));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value)) {
+            out[k.toLowerCase()] = lowerKeysDeep(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * raw cranePosition (키 대소문자 무관) → 캐노니컬 소문자 키 구조(CranePositionData).
+ * 이후 current.x / limit.x.min 등 소문자 키로 안전하게 접근 가능. 비객체면 undefined.
+ */
+export function normalizeCranePosition(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    return lowerKeysDeep(raw);
+}
+//# sourceMappingURL=crane-position.js.map

package/dist/utils/crane-position.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crane-position.js","sourceRoot":"","sources":["../../src/utils/crane-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,GAAe;IACvD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACvB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAE,GAAG,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAE,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,CAAC,CAAA;IACzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,KAAa,EACb,MAAc,EACd,MAAc,EACd,EAAU,EACV,EAAU;IAEV,MAAM,WAAW,GAAG,KAAK,IAAI,KAAK,CAAA;IAClC,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;IAC3C,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;IAC5C,MAAM,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;IACnD,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;IAEpD,2DAA2D;IAC3D,iCAAiC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC,CAAA;IACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,CAAA;IACxD,MAAM,OAAO,GAAG,EAAE,GAAG,QAAQ,CAAA;IAC7B,MAAM,QAAQ,GAAG,EAAE,GAAG,SAAS,CAAA;IAE/B,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;QACtC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO;KACtC,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,GAAQ,EAAE,GAAW;IACzC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACrD,IAAI,GAAG,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAA;IAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAA;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAU,KAAU;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAQ,CAAA;IACxE,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,GAAG,GAAwB,EAAE,CAAA;QACnC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,GAAQ,CAAA;IACjB,CAAC;IACD,OAAO,KAAU,CAAA;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAQ;IAC7C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACrD,OAAO,aAAa,CAAoB,GAAG,CAAC,CAAA;AAC9C,CAAC","sourcesContent":["/*\n * Crane 위치 데이터 (data.cranePosition) 변환 유틸.\n *\n * 명세:\n *   {\n *     cranePosition: {\n *       current: { x, y, z },               // 실 좌표값\n *       limit: { x:{min,max}, y:{min,max}, z:{min,max} }  // 각 축 한계\n *     }\n *   }\n *\n * current 를 limit 범위 안의 0~1 비율로 환산한 뒤 host(부모) footprint 에 매핑한다.\n * x → host 긴쪽, y → 짧은쪽, z → 포크 높이(forkZ 0~100).\n */\n\n/** 축별 한계 (cranePosition.limit.{x|y|z}). */\nexport interface AxisLimit {\n  min?: number\n  max?: number\n}\n\n/** 새 데이터 명세 — data.cranePosition. */\nexport interface CranePositionData {\n  current?: { x?: number; y?: number; z?: number }\n  limit?: { x?: AxisLimit; y?: AxisLimit; z?: AxisLimit }\n}\n\n/**\n * current 값을 limit 범위 안에서 0~1 비율로 환산.\n * limit 누락 / 0 span / 비정상 입력 시 0 반환 (안전 fallback).\n */\nexport function axisRatio(value: unknown, lim?: AxisLimit): number {\n  const v = Number(value)\n  const min = Number(lim?.min) || 0\n  const max = Number(lim?.max)\n  if (!Number.isFinite(v) || !Number.isFinite(max) || max === min) return 0\n  return Math.max(0, Math.min(1, (v - min) / (max - min)))\n}\n\n/**\n * host(부모) footprint 안에서 0~1 비율 (rx,ry) → 크레인 top-left 로컬 좌표.\n *\n * **스토커 안쪽 오프셋**: 크레인의 폭/두께를 감안해, 크레인 *전체* 가 host 안에\n * 머무르도록 top-left 좌표를 [0, hostLen - craneLen] 범위로 매핑한다 (= 양끝에서\n * craneLen/2 만큼 inset 된 중심선 위를 움직임). 크레인이 host 보다 크면 span 0\n * 으로 떨어져 host 모서리에 정렬.\n *\n * x(rx) 는 host 의 긴쪽, y(ry) 는 짧은쪽에 매핑 (가상 rail 은 host 긴쪽 방향).\n */\nexport function mapCraneLocalPosition(\n  hostW: number,\n  hostH: number,\n  craneW: number,\n  craneH: number,\n  rx: number,\n  ry: number\n): { left: number; top: number } {\n  const longIsWidth = hostW >= hostH\n  const longLen = longIsWidth ? hostW : hostH\n  const shortLen = longIsWidth ? hostH : hostW\n  const craneLongSize = longIsWidth ? craneW : craneH\n  const craneShortSize = longIsWidth ? craneH : craneW\n\n  // 크레인 크기를 뺀 inset 가용 span. top-left = ratio * span 이므로 크레인\n  // 전체가 host [0, hostLen] 안에 들어온다.\n  const longSpan = Math.max(0, longLen - craneLongSize)\n  const shortSpan = Math.max(0, shortLen - craneShortSize)\n  const longPos = rx * longSpan\n  const shortPos = ry * shortSpan\n\n  return {\n    left: longIsWidth ? longPos : shortPos,\n    top: longIsWidth ? shortPos : longPos\n  }\n}\n\n/**\n * 객체에서 key 를 **대소문자 무관**으로 찾아 값 반환 (정확 매치 우선, 없으면 소문자 비교).\n * 데이터 명세의 키 대소문자가 흔들려도(cranePosition / CRANEPOSITION / DURATION_MS …)\n * 동일하게 읽기 위함. 매치 없으면 undefined.\n */\nexport function ciGet(obj: any, key: string): any {\n  if (!obj || typeof obj !== 'object') return undefined\n  if (key in obj) return obj[key]\n  const lower = key.toLowerCase()\n  for (const k of Object.keys(obj)) {\n    if (k.toLowerCase() === lower) return obj[k]\n  }\n  return undefined\n}\n\n/**\n * 객체 키를 재귀적으로 소문자화한 사본 반환 (배열/원시값은 그대로, 값은 변형 안 함).\n * 중첩 키(current/limit/x/y/z/min/max)를 대소문자 무관으로 접근하기 위한 정규화.\n */\nexport function lowerKeysDeep<T = any>(value: any): T {\n  if (Array.isArray(value)) return value.map(v => lowerKeysDeep(v)) as any\n  if (value && typeof value === 'object') {\n    const out: Record<string, any> = {}\n    for (const k of Object.keys(value)) {\n      out[k.toLowerCase()] = lowerKeysDeep(value[k])\n    }\n    return out as T\n  }\n  return value as T\n}\n\n/**\n * raw cranePosition (키 대소문자 무관) → 캐노니컬 소문자 키 구조(CranePositionData).\n * 이후 current.x / limit.x.min 등 소문자 키로 안전하게 접근 가능. 비객체면 undefined.\n */\nexport function normalizeCranePosition(raw: any): CranePositionData | undefined {\n  if (!raw || typeof raw !== 'object') return undefined\n  return lowerKeysDeep<CranePositionData>(raw)\n}\n"]}

package/dist/utils/fit-gauge-scale.js

@@ -0,0 +1,28 @@
+/**
+ * 스토커 지붕 위 용량 게이지 바의 비례 축소 계수를 계산한다.
+ *
+ * 정책:
+ *   - 게이지 바의 *최대* 크기는 maxW × maxH. 스토커가 충분히 크면 이 크기 그대로 (계수 1).
+ *   - 스토커가 그보다 작으면 지붕 footprint 안에 들어오도록 *비례* 축소 (uniform).
+ *   - *확대는 하지 않는다* (계수 상한 1) — 현재 크기가 상한이라는 요구사항.
+ *
+ * 방향 매핑: 바의 가로축(maxW)은 스토커의 *장축*에 정렬된다 (buildGauge 의
+ * `isWidthLonger ? geo.rotateY` 처리와 일치). 따라서 가용 치수도 그 기준으로 매칭한다.
+ *
+ * @param w 스토커 footprint 가로 (월드 단위)
+ * @param h 스토커 footprint 세로 (월드 단위)
+ * @param maxW 게이지 바 최대 가로
+ * @param maxH 게이지 바 최대 세로
+ * @param margin 지붕 가장자리 여백 비율 (0~1, 기본 0.85)
+ * @returns 0 < scale <= 1
+ */
+export function fitGaugeScale(w, h, maxW, maxH, margin = 0.85) {
+    const isWidthLonger = w >= h;
+    // 바 가로축(maxW)이 정렬되는 스토커 치수 = 장축, 세로축(maxH) = 단축
+    const availAlongW = isWidthLonger ? w : h;
+    const availAlongH = isWidthLonger ? h : w;
+    const scale = Math.min(1, (availAlongW * margin) / maxW, (availAlongH * margin) / maxH);
+    // 음수/NaN 방어 — 0 이하로 떨어지면 안 됨
+    return scale > 0 && Number.isFinite(scale) ? scale : 1;
+}
+//# sourceMappingURL=fit-gauge-scale.js.map

package/dist/utils/fit-gauge-scale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit-gauge-scale.js","sourceRoot":"","sources":["../../src/utils/fit-gauge-scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAC3B,CAAS,EACT,CAAS,EACT,IAAY,EACZ,IAAY,EACZ,SAAiB,IAAI;IAErB,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5B,gDAAgD;IAChD,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAA;IAEvF,6BAA6B;IAC7B,OAAO,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACxD,CAAC","sourcesContent":["/**\n * 스토커 지붕 위 용량 게이지 바의 비례 축소 계수를 계산한다.\n *\n * 정책:\n *   - 게이지 바의 *최대* 크기는 maxW × maxH. 스토커가 충분히 크면 이 크기 그대로 (계수 1).\n *   - 스토커가 그보다 작으면 지붕 footprint 안에 들어오도록 *비례* 축소 (uniform).\n *   - *확대는 하지 않는다* (계수 상한 1) — 현재 크기가 상한이라는 요구사항.\n *\n * 방향 매핑: 바의 가로축(maxW)은 스토커의 *장축*에 정렬된다 (buildGauge 의\n * `isWidthLonger ? geo.rotateY` 처리와 일치). 따라서 가용 치수도 그 기준으로 매칭한다.\n *\n * @param w 스토커 footprint 가로 (월드 단위)\n * @param h 스토커 footprint 세로 (월드 단위)\n * @param maxW 게이지 바 최대 가로\n * @param maxH 게이지 바 최대 세로\n * @param margin 지붕 가장자리 여백 비율 (0~1, 기본 0.85)\n * @returns 0 < scale <= 1\n */\nexport function fitGaugeScale(\n  w: number,\n  h: number,\n  maxW: number,\n  maxH: number,\n  margin: number = 0.85\n): number {\n  const isWidthLonger = w >= h\n  // 바 가로축(maxW)이 정렬되는 스토커 치수 = 장축, 세로축(maxH) = 단축\n  const availAlongW = isWidthLonger ? w : h\n  const availAlongH = isWidthLonger ? h : w\n\n  const scale = Math.min(1, (availAlongW * margin) / maxW, (availAlongH * margin) / maxH)\n\n  // 음수/NaN 방어 — 0 이하로 떨어지면 안 됨\n  return scale > 0 && Number.isFinite(scale) ? scale : 1\n}\n"]}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fmsim/machine",
   "description": "Layout View를 구성하는 설비(machine)들과 유닛을 구현한 모듈입니다.",
   "author": "heartyoh",
-  "version": "2.0.0-beta.86",
+  "version": "2.0.0-beta.88",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "things-scene": true,
@@ -26,7 +26,7 @@
     "migration": "things-factory-migration"
   },
   "dependencies": {
-    "@fmsim/api": "^2.0.0-beta.84",
+    "@fmsim/api": "^2.0.0-beta.88",
     "@hatiolab/things-scene": "^10.0.0-beta.1"
   },
   "devDependencies": {
@@ -55,5 +55,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "2e7fe85f5e286c28c9fb3b5c095a23c8c150b41d"
+  "gitHead": "a85bfc6794b783dd619448e2cc07cca8eafbb467"
 }

package/src/agv.ts

@@ -33,6 +33,11 @@ export default class AGV extends MCSVehicle {
     return 'black'
   }
 
+  /** AGV 의 parentObject 는 AGVLine. */
+  get parentObjectTypes(): string[] {
+    return ['AGVLine']
+  }
+
   getLegendFallback() {
     return (this.root as any).agvLegendTheme || super.getLegendFallback()
   }

package/src/crane.ts

@@ -1,6 +1,13 @@
-import { Component, ComponentNature, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, sceneComponent, frameClock } from '@hatiolab/things-scene'
 import MCSVehicle from './mcs-vehicle'
 import { LEGEND_CRANE } from './features/mcs-status-default'
+import {
+  axisRatio,
+  mapCraneLocalPosition,
+  ciGet,
+  normalizeCranePosition,
+  type CranePositionData
+} from './utils/crane-position'
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -11,6 +18,29 @@ const NATURE: ComponentNature = {
 
 const GAP = 2
 
+/** 좌표 보간 기본 duration (ms). data.DURATION_MS 가 없으면 이 값 사용. */
+const DEFAULT_DURATION_MS = 1000
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+function easeInOut(t: number): number {
+  return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2
+}
+
+interface CranePositionAnimator {
+  fromLeft: number
+  fromTop: number
+  fromForkZ: number
+  toLeft: number
+  toTop: number
+  toForkZ: number
+  startTime: number
+  duration: number
+  unsubscribe: () => void
+}
+
 @sceneComponent('Crane')
 export default class Crane extends MCSVehicle {
   static get nature() {
@@ -21,10 +51,160 @@ export default class Crane extends MCSVehicle {
     return 'black'
   }
 
+  /** Crane 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   getLegendFallback() {
     return (this.root as any).craneLegendTheme || super.getLegendFallback()
   }
 
+  private _posAnimator?: CranePositionAnimator
+
+  /**
+   * data.cranePosition = { current: {x,y,z}, limit: {x|y|z:{min,max}} } 분기.
+   * current 를 limit 범위 안의 0~1 비율로 환산한 뒤, 부모 (보통 Stocker) 기준으로
+   * 실 좌표 (state.left/top) 와 forkZ 로 변환해 lerp 시작. x→host 긴쪽, y→짧은쪽,
+   * z→포크 높이. 보간 중 새 값이 들어오면 *현재 보간 위치* 를 from 으로 잡고 새
+   * target 으로 새 lerp 시작.
+   * NODEID 경로는 super (MCSVehicle.onchangeData) 가 처리 — cranePosition 만 있는
+   * 데이터에선 NODEID 가 없어 자연스럽게 noop.
+   */
+  onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    const afterData = after?.data
+    // 데이터 명세 키 대소문자 무관: cranePosition / DURATION_MS 및 중첩 키(current/limit/x/y/z/min/max).
+    const afterCP = normalizeCranePosition(ciGet(afterData, 'cranePosition'))
+    if (afterCP) {
+      const beforeCP = normalizeCranePosition(ciGet(before?.data, 'cranePosition'))
+      if (this._cranePositionChanged(afterCP, beforeCP)) {
+        this._startPositionAnimation(afterCP, ciGet(afterData, 'DURATION_MS'))
+      }
+    }
+    super.onchangeData(after, before)
+  }
+
+  /** current 또는 limit 중 하나라도 바뀌면 재계산 필요 (limit 변화도 실 위치를 바꿈). */
+  private _cranePositionChanged(a: CranePositionData, b?: CranePositionData): boolean {
+    if (!b) return true
+    return (
+      JSON.stringify(a?.current ?? null) !== JSON.stringify(b?.current ?? null) ||
+      JSON.stringify(a?.limit ?? null) !== JSON.stringify(b?.limit ?? null)
+    )
+  }
+
+  dispose() {
+    if (this._posAnimator) {
+      this._posAnimator.unsubscribe()
+      this._posAnimator = undefined
+    }
+    super.dispose()
+  }
+
+  private _startPositionAnimation(cranePosition: CranePositionData, durationMs?: number): void {
+    const target = this._ratioToReal(cranePosition)
+    if (!target) return // 부모(host) 없거나 크기 0 이면 변환 skip
+
+    const now = frameClock.simTime
+    const duration = Math.max(1, Number(durationMs) || DEFAULT_DURATION_MS)
+
+    // 현재 위치 — 보간 중이면 그 시점 보간값을 from 으로
+    let fromLeft = Number(this.state.left) || 0
+    let fromTop = Number(this.state.top) || 0
+    let fromForkZ = Number((this.state as any).forkZ) || 0
+
+    if (this._posAnimator) {
+      const a = this._posAnimator
+      const t = Math.min(1, Math.max(0, (now - a.startTime) / a.duration))
+      const e = easeInOut(t)
+      fromLeft = lerp(a.fromLeft, a.toLeft, e)
+      fromTop = lerp(a.fromTop, a.toTop, e)
+      fromForkZ = lerp(a.fromForkZ, a.toForkZ, e)
+      a.unsubscribe()
+      this._posAnimator = undefined
+    }
+
+    const unsubscribe = frameClock.subscribe(
+      (_dt: number, simTime: number) => this._tickPositionAnimation(simTime),
+      { description: 'crane-position', component: this }
+    )
+
+    this._posAnimator = {
+      fromLeft,
+      fromTop,
+      fromForkZ,
+      toLeft: target.left,
+      toTop: target.top,
+      toForkZ: target.forkZ,
+      startTime: now,
+      duration,
+      unsubscribe
+    }
+    // 즉시 첫 frame 반영 (t=0) — set 한 번 호출. paused 환경에서도 from→target
+    // 진입 시점이 명확.
+    this._tickPositionAnimation(now)
+  }
+
+  private _tickPositionAnimation(simTime: number): void {
+    const a = this._posAnimator
+    if (!a) return
+    const t = Math.min(1, Math.max(0, (simTime - a.startTime) / a.duration))
+    const e = easeInOut(t)
+    this.set({
+      left: lerp(a.fromLeft, a.toLeft, e),
+      top: lerp(a.fromTop, a.toTop, e),
+      forkZ: lerp(a.fromForkZ, a.toForkZ, e)
+    })
+    if (t >= 1) {
+      a.unsubscribe()
+      this._posAnimator = undefined
+    }
+  }
+
+  /**
+   * cranePosition (current + limit) → state.left/top + forkZ.
+   *
+   * 부모 오브젝트 (보통은 Stocker 이지만 다른 컨테이너일 수도) 의 width/height
+   * 만 사용해 좌표 매핑 — 타입 무관 일반화. 가상 rail 은 host 의 긴쪽:
+   *   - current.x → host 의 긴쪽 (자동 판별: max(width, height))
+   *   - current.y → 짧은쪽
+   *   - current.z → forkZ (state 에 0~100 으로 저장, 3D 측에서 mast 비율로 매핑)
+   *
+   * 각 축 비율 = (current - limit.min) / (limit.max - limit.min) ∈ [0,1].
+   *
+   * **스토커 안쪽 오프셋**: 크레인의 폭/두께를 감안해, 크레인 *전체* 가 host 안에
+   * 머무르도록 top-left 좌표를 [0, hostLen - craneLen] 범위로 매핑한다 (= 양끝에서
+   * craneLen/2 만큼 inset 된 중심선 위를 움직임). 크레인이 host 보다 크면 span 0
+   * 으로 떨어져 host 모서리에 정렬.
+   *
+   * 참조는 ParentObjectMixin 이 제공하는 `parentObject` 사용 —
+   * state.parentObjectId 명시 시 그것, 미명시 시 this.parent 자동 fallback.
+   */
+  private _ratioToReal(
+    cp: CranePositionData
+  ): { left: number; top: number; forkZ: number } | undefined {
+    const host: any = (this as any).parentObject
+    if (!host) return undefined
+
+    const hw = Number(host.state?.width) || 0
+    const hh = Number(host.state?.height) || 0
+    const cw = Number(this.state.width) || 0
+    const ch = Number(this.state.height) || 0
+    if (!hw || !hh) return undefined
+
+    const rx = axisRatio(cp.current?.x, cp.limit?.x)
+    const ry = axisRatio(cp.current?.y, cp.limit?.y)
+    const rz = axisRatio(cp.current?.z, cp.limit?.z)
+
+    const { left, top } = mapCraneLocalPosition(hw, hh, cw, ch, rx, ry)
+
+    return {
+      left,
+      top,
+      forkZ: rz * 100 // forkZ 0~100, 3D 측 (crane-3d) 에서 mast 비율로 매핑
+    }
+  }
+
   render(ctx: CanvasRenderingContext2D) {
     var { left, top, width, height } = this.bounds
     const { x: cx, y: cy } = this.center

package/src/factories/crane-3d.ts

@@ -22,11 +22,29 @@ const FORK_COLOR = 0x999999
 const DEFAULT_BODY_COLOR = 0xcc8844
 
 export class Crane3D extends RealObjectGroup {
+  /** 캐리지 포크 group — Crane.state.forkZ (0~100) 가 변하면 position.y 만 lerp.
+   *  build() 시 inner 에 add 되고, *_mastBaseY 와 mastH 를 함께 보관* 해서
+   *  setForkZ 가 비율 계산에 사용. */
+  private forkGroup?: THREE.Group
+  private forkMastBaseY = 0
+  private forkMastH = 0
+
   get effectiveDepth(): number {
     const { depth } = this.component.state
     return depth || 5 * TRANSPORT_SURFACE_HEIGHT - 2
   }
 
+  /**
+   * 0~100 정규화 z (= state.forkZ) 를 mast 높이 비율로 변환해서 포크 group 의
+   * three-up y 위치 갱신. build() 가 안 끝났으면 noop — build 가 forkZ 를 다시
+   * 반영하면서 끝난다.
+   */
+  applyForkZ(z: number): void {
+    if (!this.forkGroup) return
+    const clamped = Math.max(0, Math.min(100, Number(z) || 0))
+    this.forkGroup.position.y = this.forkMastBaseY + (clamped / 100) * this.forkMastH
+  }
+
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -115,8 +133,10 @@ export class Crane3D extends RealObjectGroup {
     mastMesh.castShadow = true
     inner.add(mastMesh)
 
-    // ── 3. 캐리지 포크 (마스트 40% 높이, 양쪽으로 뻗는 포크 암) ──
-    const forkY = mastBaseY + mastH * 0.4
+    // ── 3. 캐리지 포크 (별도 group — state.forkZ 변경 시 group.position.y lerp) ──
+    // 포크 geometry 는 *_mastBaseY 기준 local 0 에 둠* — 즉 group.position.y = 0
+    // 일 때 mast 바닥 자리에. forkZ 0~100 에 따라 group.position.y 만 변경하면
+    // mast 따라 위/아래 이동. mesh 재구축 불필요.
     const forkMat = new THREE.MeshStandardMaterial({
       color: FORK_COLOR,
       roughness: 0.4,
@@ -125,15 +145,13 @@ export class Crane3D extends RealObjectGroup {
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
-    // 캐리지 중심 플레이트 (마스트에 부착, 양쪽 포크의 베이스)
     const plateW = w * 0.9
     const plateH = d * 0.08
     const plateD = pillarThick * 0.8
     const centerPlate = new THREE.BoxGeometry(plateW, plateH, plateD)
-    centerPlate.translate(0, forkY + plateH / 2, 0)
+    centerPlate.translate(0, plateH / 2, 0) // local 0 = mast 바닥
     forkGeometries.push(centerPlate)
 
-    // 양쪽 포크 암 (좌/우 선반 방향으로 뻗음)
     const armW = pillarThick * 0.6
     const armH = plateH * 0.4
     const armD = h * 0.6
@@ -142,14 +160,27 @@ export class Crane3D extends RealObjectGroup {
     for (const zSign of [-1, 1]) {
       for (const xSign of [-1, 1]) {
         const arm = new THREE.BoxGeometry(armW, armH, armD)
-        arm.translate(xSign * (armSpacing / 2), forkY + armH / 2, zSign * (plateD / 2 + armD / 2))
+        arm.translate(xSign * (armSpacing / 2), armH / 2, zSign * (plateD / 2 + armD / 2))
         forkGeometries.push(arm)
       }
     }
 
     const forkMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(forkGeometries), forkMat)
     forkMesh.castShadow = true
-    inner.add(forkMesh)
+
+    const forkGroup = new THREE.Group()
+    forkGroup.add(forkMesh)
+    inner.add(forkGroup)
+    this.forkGroup = forkGroup
+    this.forkMastBaseY = mastBaseY
+    // forkZ=100 시점에 mast 의 *_위쪽 한계*. 포크 자체 두께 (plateH) 만큼은 마스트
+    // 안에 머무르도록 limit 보정 — 그렇지 않으면 forkZ=100 일 때 포크가 상단
+    // 클램프와 충돌. mastH * 0.92 로 약간 보수적 (= 마스트 본체 92% 까지만 이동).
+    this.forkMastH = mastH * 0.92
+
+    // 초기 forkZ 반영 — state.forkZ 가 이미 set 되어 있으면 그 위치에 배치
+    const initialForkZ = Number((this.component.state as any).forkZ)
+    this.applyForkZ(Number.isFinite(initialForkZ) ? initialForkZ : 0)
 
     // ── 4. 상단 클램프 (천장 레일에 물리는 가이드부) ──
     const topClampGeo = new THREE.BoxGeometry(clampW, clampH, clampD)
@@ -162,11 +193,23 @@ export class Crane3D extends RealObjectGroup {
   updateDimension() {}
   updateAlpha() {}
 
+  /** build() 직전 호출. forkGroup 참조를 깨끗이 비워둔다 — 새 build 가 다시 set. */
+  clear() {
+    this.forkGroup = undefined
+    super.clear()
+  }
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after || 'fillStyle' in after || 'strokeStyle' in after) {
       this.update()
       return
     }
+    // forkZ 는 mesh 재구축 없이 group.position.y 만 갱신. 같은 onchange 에서
+    // left/top 도 함께 변경될 수 있으므로 super 도 반드시 호출해 본체 transform
+    // 갱신 path (state.left/top → obj3d.position.x/z) 가 동작하게 함.
+    if ('forkZ' in after) {
+      this.applyForkZ(Number(after.forkZ) || 0)
+    }
     super.onchange(after, before)
   }
 }

package/src/factories/machine-3d.ts

@@ -14,6 +14,7 @@ import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@ha
 import type { Component } from '@hatiolab/things-scene'
 import { LEGEND_CAPACITY } from '../features/mcs-status-default'
 import { getValueOnRanges } from '../utils/get-value-on-ranges'
+import { fitGaugeScale } from '../utils/fit-gauge-scale'
 import { Z_FMSIM } from './z-priority'
 
 // ── 설정 타입 ────────────────────────────────────────────
@@ -667,12 +668,20 @@ class StockerRealObject3D extends MCSRealObject3D {
     const depth = this.effectiveDepth
     const isWidthLonger = w >= h
 
-    // 게이지 캔버스 (고해상도)
-    const barW = 130
-    const barH = 26
+    // 게이지 최대 크기 (스토커가 충분히 크면 이 크기 그대로 사용).
+    const MAX_BAR_W = 130
+    const MAX_BAR_H = 26
+
+    // 스토커 지붕 footprint 에 맞춰 비례 축소 (확대는 안 함 — 현재 크기가 상한).
+    const fit = fitGaugeScale(w, h, MAX_BAR_W, MAX_BAR_H)
+
+    // PlaneGeometry 의 월드 크기는 clamp, 텍스처 캔버스 해상도는 최대 크기 기준 고정
+    // (축소되어도 선명도 유지).
+    const barW = MAX_BAR_W * fit
+    const barH = MAX_BAR_H * fit
     const scale = 4
-    const canvasW = barW * scale
-    const canvasH = barH * scale
+    const canvasW = MAX_BAR_W * scale
+    const canvasH = MAX_BAR_H * scale
     const canvas = document.createElement('canvas')
     canvas.width = canvasW
     canvas.height = canvasH

package/src/features/parent-object-mixin.ts

@@ -4,13 +4,12 @@ import { Component } from '@hatiolab/things-scene'
 import MCSMachine from '../mcs-machine'
 import MCSUnit from '../mcs-unit'
 
-export const ParentObjectMixinProperties = [
-  {
-    type: 'string',
-    label: 'parent-object-id',
-    name: 'parentObjectId'
-  }
-]
+/**
+ * parentObjectId 는 generic property builder 가 아니라 property-sidebar 의 모델 참조
+ * 룩업(ox-input-entity-id, parentObjectTypes 기준 씬 머신/유닛 선택)으로 렌더한다.
+ * 따라서 NATURE 속성 목록에서는 제외 — 빈 배열.
+ */
+export const ParentObjectMixinProperties: any[] = []
 
 export function ParentObjectMixin<TBase extends Constructor<Component>>(Base: TBase): any {
   return class extends Base {
@@ -32,5 +31,15 @@ export function ParentObjectMixin<TBase extends Constructor<Component>>(Base: TB
         return parent
       }
     }
+
+    /**
+     * parentObjectId 가 참조하는 모델 컴포넌트 타입들 — parentObject 후보를 모델(씬)에서
+     * 수집할 때 이 타입들로 거른다 (머신/유닛 무관, 복수 허용).
+     * 빈 배열(기본) 이면 모델의 모든 머신 (폴백). 참조 타입이 정해진 컴포넌트는 override:
+     *   AGV→['AGVLine'], OHT→['OHTLine'], Crane/Shelf→['STOCKER'], PortFlow→['Port'].
+     */
+    get parentObjectTypes(): string[] {
+      return []
+    }
   }
 }

package/src/mcs-machine.ts

@@ -26,6 +26,19 @@ export default class MCSMachine extends MCSStatusMixin(ContainerAbstract) {
     return false
   }
 
+  /**
+   * id 후보를 조회할 때 백엔드에 보낼 타입명. 값이 있으면 검색(lookup) 대상.
+   * 기본은 자기 타입. 자기 타입과 다른 타입으로 조회해야 하는 특수 케이스는 override.
+   */
+  get idLookupType(): string | undefined {
+    return this.state.type
+  }
+
+  /** MCS 머신 — parentObject(부모 머신) 후보 수집 시 머신으로 식별. */
+  get isMcsMachine(): boolean {
+    return true
+  }
+
   containable(component: Component) {
     return ['rect', 'ellipse'].includes(component.state.type)
   }

package/src/mcs-unit.ts

@@ -13,6 +13,18 @@ export default class MCSUnit extends MCSStatusMixin(ParentObjectMixin(ContainerA
     return [...MCSStatusMixinProperties, ...ParentObjectMixinProperties]
   }
 
+  get showMoveHandle() {
+    return false
+  }
+
+  /**
+   * id 후보를 조회할 때 백엔드에 보낼 타입명. 값이 있으면 검색(lookup) 대상.
+   * 기본은 자기 타입. 특수 케이스는 override.
+   */
+  get idLookupType(): string | undefined {
+    return this.state.type
+  }
+
   get hasTextProperty() {
     return true
   }

package/src/oht.ts

@@ -20,6 +20,11 @@ export default class OHT extends MCSVehicle {
     return 'black'
   }
 
+  /** OHT 의 parentObject 는 OHTLine. */
+  get parentObjectTypes(): string[] {
+    return ['OHTLine']
+  }
+
   getLegendFallback() {
     return (this.root as any).ohtLegendTheme || super.getLegendFallback()
   }

package/src/port-flow.ts

@@ -45,6 +45,11 @@ export default class PortFlow extends ParentObjectMixin(RectPath(Shape)) {
     return NATURE
   }
 
+  /** PortFlow 의 parentObject 는 Port (유닛). */
+  get parentObjectTypes(): string[] {
+    return ['Port']
+  }
+
   get hasTextProperty() {
     return this.getState('showText') || false
   }

package/src/port.ts

@@ -23,6 +23,11 @@ export default class Port extends MCSZoneMixin(MCSCarrierHolder) {
     return (this.root as any).portLegendTheme || super.getLegendFallback()
   }
 
+  /** Port 는 후보가 매우 많아 부모 머신 없이는 id 리스트를 조회하지 않는다 (machine 필수). */
+  get idLookupRequiresMachine() {
+    return true
+  }
+
   render(ctx: CanvasRenderingContext2D) {
     var { left, top, width, height } = this.bounds
 

package/src/shelf.ts

@@ -19,6 +19,11 @@ export default class Shelf extends MCSZoneMixin(MCSCarrierHolder) {
     return 'black'
   }
 
+  /** Shelf 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   getLegendFallback() {
     return (this.root as any).shelfLegendTheme || super.getLegendFallback()
   }