@operato/scene-urdf 10.0.0-beta.1 → 10.0.0-beta.19

package/dist/joint-controller.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * URDF 조인트 제어기 추상화.
+ *
+ * 배경:
+ *   state.joints는 조인트의 "목표값"을 표현하고, 실제 URDFJoint에 적용되는 값은
+ *   어떤 정책을 따를지에 따라 달라질 수 있다.
+ *     - Direct: 목표값을 즉시 적용 (현재 기본 동작)
+ *     - Smooth: 스프링-댐퍼로 부드럽게 수렴
+ *     - Rapier 등 물리: rigid body 시뮬레이션의 결과를 관절에 반영
+ *
+ *   이들은 모두 "목표값 → 실제 적용값" 매핑이라는 공통 추상으로 묶을 수 있다.
+ *
+ * 확장:
+ *   외부 패키지가 `registerJointController('rapier', ...)` 형태로 구현을 등록해
+ *   urdf 컴포넌트의 state.physics 값을 통해 선택 가능. 예를 들어 미래의
+ *   `@operato/scene-urdf-rapier` 패키지가 Rapier 기반 controller를 register.
+ */
+const registry = new Map();
+/**
+ * 외부 패키지가 자신의 controller 구현을 등록한다.
+ * 예: `registerJointController('rapier', () => new RapierJointController())`.
+ */
+export function registerJointController(name, factory) {
+    registry.set(name, factory);
+}
+export function createJointController(name) {
+    return registry.get(name)?.();
+}
+export function listJointControllers() {
+    return [...registry.keys()];
+}
+//# sourceMappingURL=joint-controller.js.map

package/dist/joint-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joint-controller.js","sourceRoot":"","sources":["../src/joint-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqCH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAA;AAE1D;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,OAA+B;IACnF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;AAC/B,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;AAC7B,CAAC","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n *\n * URDF 조인트 제어기 추상화.\n *\n * 배경:\n *   state.joints는 조인트의 \"목표값\"을 표현하고, 실제 URDFJoint에 적용되는 값은\n *   어떤 정책을 따를지에 따라 달라질 수 있다.\n *     - Direct: 목표값을 즉시 적용 (현재 기본 동작)\n *     - Smooth: 스프링-댐퍼로 부드럽게 수렴\n *     - Rapier 등 물리: rigid body 시뮬레이션의 결과를 관절에 반영\n *\n *   이들은 모두 \"목표값 → 실제 적용값\" 매핑이라는 공통 추상으로 묶을 수 있다.\n *\n * 확장:\n *   외부 패키지가 `registerJointController('rapier', ...)` 형태로 구현을 등록해\n *   urdf 컴포넌트의 state.physics 값을 통해 선택 가능. 예를 들어 미래의\n *   `@operato/scene-urdf-rapier` 패키지가 Rapier 기반 controller를 register.\n */\n\nimport type { URDFRobot, URDFJoint } from 'urdf-loader'\nimport type { URDFJointMeta } from './real-object-urdf.js'\n\nexport interface JointControllerContext {\n  robot: URDFRobot\n  /** non-fixed + fixed 포함 모든 조인트 */\n  joints: Map<string, URDFJoint>\n  /** non-fixed 조인트의 메타 (type, axis, limit) — fixed는 제외됨 */\n  jointMeta: Map<string, URDFJointMeta>\n}\n\nexport interface JointController {\n  /** 로봇 로드 직후 1회 호출. 내부 상태(current/target/velocity 등) 초기화. */\n  setup(ctx: JointControllerContext): void\n\n  /**\n   * state.joints 변경 시 호출. controller가 `targets` 맵을 내부 저장하고\n   * tick에서 실제 적용을 결정한다. 각 value는 joint의 internal unit\n   * (revolute=rad, prismatic=m).\n   */\n  setTargets(targets: Record<string, number>): void\n\n  /**\n   * 매 프레임 호출 (requestAnimationFrame). dt는 초 단위.\n   * 관절에 값을 적용(joint.setJointValue)하고, 값이 실제로 변경됐다면 true를\n   * 반환 (상위가 invalidate를 결정).\n   */\n  tick(dt: number): boolean\n\n  /** 로봇 해제 시 호출. 내부 자원/캐시 정리. */\n  dispose(): void\n}\n\nexport type JointControllerFactory = () => JointController\n\nconst registry = new Map<string, JointControllerFactory>()\n\n/**\n * 외부 패키지가 자신의 controller 구현을 등록한다.\n * 예: `registerJointController('rapier', () => new RapierJointController())`.\n */\nexport function registerJointController(name: string, factory: JointControllerFactory): void {\n  registry.set(name, factory)\n}\n\nexport function createJointController(name: string): JointController | undefined {\n  return registry.get(name)?.()\n}\n\nexport function listJointControllers(): string[] {\n  return [...registry.keys()]\n}\n"]}

package/dist/real-object-urdf.d.ts

@@ -0,0 +1,106 @@
+import * as THREE from 'three';
+import type { URDFRobot } from 'urdf-loader';
+import type { Properties } from '@hatiolab/things-scene';
+import { RealObjectExternalModel } from '@hatiolab/things-scene';
+export interface URDFJointState {
+    /** revolute/continuous: 라디안. prismatic: 거리(URDF 단위). */
+    value?: number;
+}
+export interface URDFJointMeta {
+    name: string;
+    type: 'fixed' | 'continuous' | 'revolute' | 'planar' | 'prismatic' | 'floating';
+    axis: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    limit: {
+        lower: number;
+        upper: number;
+        effort: number;
+        velocity: number;
+    };
+}
+export declare class RealObjectURDF extends RealObjectExternalModel<URDFRobot> {
+    protected get _formatLabel(): string;
+    protected get _placeholderColor(): number;
+    private static _urdfCache;
+    private static _topViewCache;
+    /**
+     * URDF를 로드한다 (동일 URL 캐시).
+     * mesh 로더는 STL/DAE(내장) + OBJ(MTL 연동) + GLB(확장)를 지원한다.
+     *
+     * URDFLoader.loadAsync는 URDF XML 파싱 직후 resolve하지만 mesh(STL/DAE/GLB)는
+     * 비동기로 뒤늦게 attach된다. robot.clone() 시점에 mesh가 아직 없으면 클론된
+     * 트리엔 visual이 비게 되고 원본에만 mesh가 붙는다. 전용 LoadingManager의
+     * onLoad를 사용해 URDF + 모든 mesh가 완료된 후 resolve한다.
+     *
+     * `packages` 옵션을 통해 ROS `package://<pkg>/<rel>` prefix 해석을 설정할 수
+     * 있다 (예: `{ a1_description: 'https://.../robots/a1_description' }`).
+     */
+    static loadURDF(url: string, packages?: Record<string, string>): Promise<URDFRobot>;
+    /** 모든 캐시 비움 (보드 전환 시 호출) */
+    static flushCache(): void;
+    static getTopViewCache(source: string): HTMLCanvasElement | undefined;
+    static setTopViewCache(source: string, canvas: HTMLCanvasElement): void;
+    private _robot?;
+    private _jointIndex;
+    private _jointMeta;
+    private _jointOriginals;
+    private _animRaf?;
+    private _animStartTime;
+    private _controller?;
+    private _ctrlRaf?;
+    private _ctrlLastTime;
+    get robot(): URDFRobot | undefined;
+    /** 로드된 조인트 메타 리스트 (property panel 등이 참조) */
+    get jointMeta(): URDFJointMeta[];
+    get jointNames(): string[];
+    protected _loadExternal(url: string): Promise<URDFRobot>;
+    protected _onLoaded(robot: URDFRobot): void;
+    private _resolveUnitScale;
+    /**
+     * 조인트 트리를 순회하며 인덱스와 메타를 구축한다.
+     * fixed 조인트는 조작 대상이 아니므로 메타에서 제외하되 인덱스에는 남긴다.
+     */
+    private _buildJointIndex;
+    /**
+     * state.joints 변경을 적절한 경로로 디스패치한다.
+     *   - controller가 활성이면 setTargets (controller가 스무딩/물리 적용)
+     *   - 없으면 즉시 적용 (direct 모드, 기본)
+     */
+    private _dispatchJointStates;
+    /**
+     * Controller를 인스턴스화하고 setup + tick 루프 시작.
+     * 이미 활성 중이면 먼저 해제.
+     */
+    private _setupController;
+    private _disposeController;
+    /**
+     * state.joints 맵을 순회하며 각 조인트 값을 적용한다 (direct 모드).
+     * 값은 숫자 또는 { value: number } 형식 모두 허용 (유연성).
+     *
+     * joint transform 변경 후 component.invalidate()로 재렌더를 요청한다.
+     * 표준 경로: invalidate → Layer.throttle_render → rAF __draw__ → trigger('redraw')
+     * → ThreeCapability.animate → renderThreeD.
+     */
+    private _applyJointStates;
+    /**
+     * 자동 sine 애니메이션 시작.
+     * 각 non-fixed 조인트를 limit 범위 내에서 sine 스윙. 조인트 순서에 따라
+     * frequency와 phase를 약간씩 다르게 해 동기화를 피하고 유기적 움직임을 만든다.
+     *
+     * state.joints를 건드리지 않고 joint.setJointValue만 직접 호출 — state 변경
+     * cascade를 피해 성능을 유지하고, 슬라이더가 있는 경우에도 state와 시각이
+     * 분리되어 표시됨 (활성 시 state는 의미 없음).
+     */
+    private _startAutoAnimate;
+    private _stopAutoAnimate;
+    /**
+     * 모든 조인트를 원본 값으로 복원한다.
+     */
+    private _resetAllJoints;
+    clear(): THREE.Object3D<THREE.Object3DEventMap>;
+    updateDimension(): void;
+    onchange(after: Properties, before: Properties): void;
+}

package/dist/real-object-urdf.js

@@ -0,0 +1,527 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * URDF (Unified Robot Description Format) 지원 RealObject.
+ * RealObjectGLTF와 동일한 캐시/레이스/placeholder 패턴을 따른다.
+ *
+ * 차이점: GLTF는 노드/애니메이션이 주된 바인딩 대상이지만, URDF는 "joint"가
+ * 1급 시민이다. state.joints에 이름→라디안(또는 prismatic의 경우 거리) 맵을
+ * 두어 외부 센서값 등을 연결할 수 있도록 한다.
+ *
+ * 좌표계: URDF는 Z-up, things-scene의 3D는 Y-up. 로드 후 루트 그룹에 1회만
+ * -PI/2 X축 회전을 적용하여 변환한다. 내부 조인트 축은 원본 그대로 유지.
+ */
+import * as THREE from 'three';
+import URDFLoader from 'urdf-loader';
+import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
+import { MTLLoader } from 'three/examples/jsm/loaders/MTLLoader.js';
+import { warn } from '@hatiolab/things-scene';
+import { RealObjectExternalModel } from '@hatiolab/things-scene';
+import { RealObjectGLTF } from '@hatiolab/things-scene';
+import { createJointController } from './joint-controller.js';
+const X_NEG_PI_HALF = -Math.PI / 2;
+export class RealObjectURDF extends RealObjectExternalModel {
+    get _formatLabel() { return 'urdf'; }
+    get _placeholderColor() { return 0x1976d2; }
+    // URDF 파싱 결과 캐시 — 동일 URL 재파싱 방지. clone()으로 복제 사용.
+    static _urdfCache = new Map();
+    // 탑뷰 스냅샷 캐시 (2D 렌더 폴백)
+    static _topViewCache = new Map();
+    /**
+     * URDF를 로드한다 (동일 URL 캐시).
+     * mesh 로더는 STL/DAE(내장) + OBJ(MTL 연동) + GLB(확장)를 지원한다.
+     *
+     * URDFLoader.loadAsync는 URDF XML 파싱 직후 resolve하지만 mesh(STL/DAE/GLB)는
+     * 비동기로 뒤늦게 attach된다. robot.clone() 시점에 mesh가 아직 없으면 클론된
+     * 트리엔 visual이 비게 되고 원본에만 mesh가 붙는다. 전용 LoadingManager의
+     * onLoad를 사용해 URDF + 모든 mesh가 완료된 후 resolve한다.
+     *
+     * `packages` 옵션을 통해 ROS `package://<pkg>/<rel>` prefix 해석을 설정할 수
+     * 있다 (예: `{ a1_description: 'https://.../robots/a1_description' }`).
+     */
+    static loadURDF(url, packages) {
+        // 동일 URL이라도 packages 설정이 다르면 다른 캐시 엔트리.
+        const cacheKey = packages && Object.keys(packages).length > 0
+            ? `${url}|${JSON.stringify(packages)}`
+            : url;
+        let cached = RealObjectURDF._urdfCache.get(cacheKey);
+        if (!cached) {
+            cached = new Promise((resolve, reject) => {
+                const manager = new THREE.LoadingManager();
+                const loader = new URDFLoader(manager);
+                if (packages) {
+                    loader.packages = packages;
+                }
+                loader.loadMeshCb = ((path, mgr, done) => {
+                    if (/\.(glb|gltf)$/i.test(path)) {
+                        // GLB는 별도 시스템 — manager 추적에서 벗어나므로 명시적으로 track.
+                        mgr.itemStart(path);
+                        RealObjectGLTF.loadGLTF(path).then(gltf => { done(gltf.scene.clone()); mgr.itemEnd(path); }, err => { done(null, err); mgr.itemError(path); mgr.itemEnd(path); });
+                    }
+                    else if (/\.obj$/i.test(path)) {
+                        // OBJ는 urdf-loader 내장 defaultMeshLoader가 지원하지 않음.
+                        // 연관된 .mtl(재질) 파일이 있으면 MTLLoader로 먼저 로드하여 색상/텍스처
+                        // 적용, 없으면 OBJLoader만 폴백.
+                        //
+                        // LoadingManager 정합성: 외부 path로만 itemStart/itemEnd를 1회씩
+                        // 기록한다. 내부 MTLLoader/OBJLoader는 manager 주입 없이 생성하여
+                        // 서브-아이템으로 카운트되지 않게 함 — 그렇지 않으면 MTL 404 직후
+                        // 일시적으로 pending=0이 되어 manager.onLoad가 조기 발화하고
+                        // 최종 로봇이 빈 상태로 resolve되는 레이스가 발생.
+                        mgr.itemStart(path);
+                        const finishOk = (mesh) => { done(mesh); mgr.itemEnd(path); };
+                        const finishErr = (err) => { done(null, err); mgr.itemError(path); mgr.itemEnd(path); };
+                        const lastSlash = path.lastIndexOf('/');
+                        const baseUrl = lastSlash >= 0 ? path.substring(0, lastSlash + 1) : '';
+                        const mtlName = path.substring(lastSlash + 1).replace(/\.obj$/i, '.mtl');
+                        const loadObjOnly = () => {
+                            new OBJLoader().load(path, group => finishOk(group), undefined, err => finishErr(err));
+                        };
+                        new MTLLoader().setResourcePath(baseUrl).setPath(baseUrl).load(mtlName, materials => {
+                            materials.preload();
+                            new OBJLoader().setMaterials(materials).load(path, group => finishOk(group), undefined, err => finishErr(err));
+                        }, undefined, () => {
+                            // MTL 로드 실패 시 OBJ만 로드 (정상 시나리오 — MTL 없는 OBJ도 있음)
+                            loadObjOnly();
+                        });
+                    }
+                    else {
+                        // STL/DAE는 urdf-loader 내장 디폴트로 폴백 (manager 자동 추적)
+                        ;
+                        loader.defaultMeshLoader(path, mgr, done);
+                    }
+                });
+                let robotResult;
+                manager.onLoad = () => {
+                    if (robotResult)
+                        resolve(robotResult);
+                    else
+                        reject(new Error('URDF load completed but no robot result'));
+                };
+                manager.onError = (failedUrl) => {
+                    // 개별 에러는 로그로만 남김 — 전체 로드는 그래도 완료되도록
+                    // (일부 mesh 실패 시 나머지라도 보이게)
+                    warn('URDFLoader: resource load error', failedUrl);
+                };
+                loader.load(url, robot => { robotResult = robot; }, undefined, err => reject(err));
+            }).catch(err => {
+                RealObjectURDF._urdfCache.delete(cacheKey);
+                throw err;
+            });
+            RealObjectURDF._urdfCache.set(cacheKey, cached);
+        }
+        return cached;
+    }
+    /** 모든 캐시 비움 (보드 전환 시 호출) */
+    static flushCache() {
+        RealObjectURDF._urdfCache.clear();
+        RealObjectURDF._topViewCache.clear();
+    }
+    static getTopViewCache(source) {
+        return RealObjectURDF._topViewCache.get(source);
+    }
+    static setTopViewCache(source, canvas) {
+        RealObjectURDF._topViewCache.set(source, canvas);
+    }
+    // --- 인스턴스 상태 ---
+    _robot;
+    // 조인트 인덱스 + 메타 (로드 후 외부에서 구독 가능)
+    _jointIndex = new Map();
+    _jointMeta = new Map();
+    // 원본 조인트 값 — reset을 위해 보존
+    _jointOriginals = new Map();
+    // 자동 애니메이션 (sine 모드) 상태
+    _animRaf;
+    _animStartTime = 0;
+    // Joint controller (physics mode) 상태
+    _controller;
+    _ctrlRaf;
+    _ctrlLastTime = 0;
+    get robot() {
+        return this._robot;
+    }
+    /** 로드된 조인트 메타 리스트 (property panel 등이 참조) */
+    get jointMeta() {
+        return Array.from(this._jointMeta.values());
+    }
+    get jointNames() {
+        return Array.from(this._jointIndex.keys());
+    }
+    _loadExternal(url) {
+        const packages = this.component.state.packages;
+        return RealObjectURDF.loadURDF(url, packages);
+    }
+    _onLoaded(robot) {
+        if (this.component.state.loadError) {
+            this.component.setState({ loadError: undefined });
+        }
+        // 캐시의 robot은 공유 참조이므로 clone하여 독립 인스턴스 구성.
+        // urdf-loader의 URDFRobot는 Object3D를 상속하므로 Object3D.clone()이 안전하게 동작.
+        const cloned = robot.clone();
+        // 섀도우 캐스팅
+        cloned.traverse(child => {
+            if (child.isMesh) {
+                child.castShadow = true;
+            }
+        });
+        // clear()는 object3d.userData를 리셋하므로 pending 후 재설정.
+        this.clear();
+        this.object3d.userData.context = this;
+        this._robot = cloned;
+        // 좌표계 변환: URDF(Z-up) → three(Y-up).
+        // 사용자가 state.upAxis = 'y' 로 지정하면 변환 생략.
+        this.pivot = new THREE.Object3D();
+        const upAxis = this.component.state.upAxis;
+        if (upAxis !== 'y') {
+            this.pivot.rotation.x = X_NEG_PI_HALF;
+        }
+        // URDF는 기본 meter 단위. state.unitScale로 에디터 단위로 환산.
+        const unitScale = this._resolveUnitScale();
+        if (unitScale !== 1) {
+            this.pivot.scale.setScalar(unitScale);
+        }
+        this.pivot.add(cloned);
+        // URDF의 base_link는 관행상 z=0이 바닥(floor origin). things-scene는 center
+        // origin이므로, components3D 그룹(= -geometricOffsetY만큼 shift된 바닥 기준
+        // subgroup)에 pivot을 넣어 로봇이 컴포넌트 바닥면에 서도록 한다.
+        this.components3D.add(this.pivot);
+        // 조인트 인덱스/메타 구축
+        this._buildJointIndex(cloned);
+        // bounding box 계산 후 updateDimension으로 크기 반영
+        const box = new THREE.Box3().setFromObject(this.pivot);
+        this._objectSize = box.getSize(new THREE.Vector3());
+        this.updateDimension();
+        // 자동 placement 정렬: URDF의 base_link 원점이 로봇 기하의 최저점이 아닐 때
+        // (Nao/minitaur/quadrotor는 torso/중심 기준) 로봇 일부가 컴포넌트 범위를
+        // 벗어나는 것을 방지. 씬의 placement 모드에 따라 정렬 기준이 다르다.
+        //   - floor:    로봇 최저점 → 컴포넌트 바닥면
+        //   - inverted: 로봇 최상점 → 컴포넌트 천장면 (매달림)
+        //   - space:    정렬 없음 (중심 원점 유지)
+        // state.floorAlign === false 로 비활성화 가능.
+        if (this.component.state.floorAlign !== false) {
+            const placement = this.scenePlacement;
+            if (placement !== 'space') {
+                this.components3D.updateMatrixWorld(true);
+                const worldBox = new THREE.Box3().setFromObject(this.pivot);
+                if (isFinite(worldBox.min.y) && isFinite(worldBox.max.y)) {
+                    if (placement === 'inverted') {
+                        const localMax = this.components3D.worldToLocal(worldBox.max.clone());
+                        if (localMax.y > 0) {
+                            this.pivot.position.y -= localMax.y;
+                        }
+                    }
+                    else {
+                        // floor (기본)
+                        const localMin = this.components3D.worldToLocal(worldBox.min.clone());
+                        if (localMin.y < 0) {
+                            this.pivot.position.y -= localMin.y;
+                        }
+                    }
+                }
+            }
+        }
+        // 컨트롤러 초기화 (state.physics 설정된 경우)
+        const physicsMode = this.component.state.physics;
+        if (physicsMode && physicsMode !== 'none') {
+            this._setupController(physicsMode);
+        }
+        // 초기 joint 상태 적용
+        const jointStates = this.component.state.joints;
+        if (jointStates) {
+            this._dispatchJointStates(jointStates);
+        }
+        // 자동 애니메이션 시작 (state.autoAnimate === 'sine'인 경우)
+        if (this.component.state.autoAnimate === 'sine') {
+            this._startAutoAnimate();
+        }
+        // 탑뷰 스냅샷
+        const source = this.component.state.src;
+        if (source && !RealObjectURDF._topViewCache.has(source)) {
+            try {
+                const canvas = RealObjectGLTF.renderTopView(this.pivot);
+                RealObjectURDF._topViewCache.set(source, canvas);
+                this.component._topViewSnapshot = canvas;
+            }
+            catch {
+                // 스냅샷 실패는 치명적이지 않음
+            }
+        }
+        else if (source) {
+            ;
+            this.component._topViewSnapshot = RealObjectURDF._topViewCache.get(source);
+        }
+    }
+    _resolveUnitScale() {
+        const s = this.component.state.unitScale;
+        if (typeof s === 'number' && s > 0)
+            return s;
+        // 기본: URDF meter → 에디터 mm 스케일 1000
+        return 1000;
+    }
+    /**
+     * 조인트 트리를 순회하며 인덱스와 메타를 구축한다.
+     * fixed 조인트는 조작 대상이 아니므로 메타에서 제외하되 인덱스에는 남긴다.
+     */
+    _buildJointIndex(robot) {
+        this._jointIndex.clear();
+        this._jointMeta.clear();
+        this._jointOriginals.clear();
+        const joints = robot.joints || {};
+        for (const [name, joint] of Object.entries(joints)) {
+            this._jointIndex.set(name, joint);
+            this._jointOriginals.set(name, joint.angle || 0);
+            if (joint.jointType === 'fixed')
+                continue;
+            this._jointMeta.set(name, {
+                name,
+                type: joint.jointType,
+                axis: { x: joint.axis.x, y: joint.axis.y, z: joint.axis.z },
+                limit: { ...joint.limit }
+            });
+        }
+    }
+    /**
+     * state.joints 변경을 적절한 경로로 디스패치한다.
+     *   - controller가 활성이면 setTargets (controller가 스무딩/물리 적용)
+     *   - 없으면 즉시 적용 (direct 모드, 기본)
+     */
+    _dispatchJointStates(states) {
+        if (this._controller) {
+            const targets = {};
+            for (const [name, raw] of Object.entries(states)) {
+                const v = typeof raw === 'number' ? raw : Number(raw?.value);
+                if (Number.isFinite(v))
+                    targets[name] = v;
+            }
+            this._controller.setTargets(targets);
+            return;
+        }
+        this._applyJointStates(states);
+    }
+    /**
+     * Controller를 인스턴스화하고 setup + tick 루프 시작.
+     * 이미 활성 중이면 먼저 해제.
+     */
+    _setupController(mode) {
+        this._disposeController();
+        const ctrl = createJointController(mode);
+        if (!ctrl) {
+            warn(`URDFObject: unknown physics mode '${mode}'`);
+            return;
+        }
+        if (!this._robot)
+            return;
+        ctrl.setup({ robot: this._robot, joints: this._jointIndex, jointMeta: this._jointMeta });
+        this._controller = ctrl;
+        // 현재 state.joints를 초기 타겟으로 설정
+        const s = this.component.state.joints;
+        if (s) {
+            const targets = {};
+            for (const [name, raw] of Object.entries(s)) {
+                const v = typeof raw === 'number' ? raw : Number(raw?.value);
+                if (Number.isFinite(v))
+                    targets[name] = v;
+            }
+            ctrl.setTargets(targets);
+        }
+        this._ctrlLastTime = performance.now();
+        const tick = () => {
+            if (!this._controller) {
+                this._ctrlRaf = undefined;
+                return;
+            }
+            const now = performance.now();
+            const dt = (now - this._ctrlLastTime) / 1000;
+            this._ctrlLastTime = now;
+            const changed = this._controller.tick(dt);
+            if (changed) {
+                this.component?.invalidate?.();
+            }
+            this._ctrlRaf = requestAnimationFrame(tick);
+        };
+        this._ctrlRaf = requestAnimationFrame(tick);
+    }
+    _disposeController() {
+        if (this._ctrlRaf != null) {
+            cancelAnimationFrame(this._ctrlRaf);
+            this._ctrlRaf = undefined;
+        }
+        if (this._controller) {
+            this._controller.dispose();
+            this._controller = undefined;
+        }
+    }
+    /**
+     * state.joints 맵을 순회하며 각 조인트 값을 적용한다 (direct 모드).
+     * 값은 숫자 또는 { value: number } 형식 모두 허용 (유연성).
+     *
+     * joint transform 변경 후 component.invalidate()로 재렌더를 요청한다.
+     * 표준 경로: invalidate → Layer.throttle_render → rAF __draw__ → trigger('redraw')
+     * → ThreeCapability.animate → renderThreeD.
+     */
+    _applyJointStates(states) {
+        if (!this._robot)
+            return;
+        let changed = false;
+        for (const [name, raw] of Object.entries(states)) {
+            const joint = this._jointIndex.get(name);
+            if (!joint || joint.jointType === 'fixed')
+                continue;
+            const value = typeof raw === 'number' ? raw : raw?.value;
+            if (typeof value !== 'number' || !isFinite(value))
+                continue;
+            joint.setJointValue(value);
+            changed = true;
+        }
+        if (changed) {
+            this.component?.invalidate?.();
+        }
+    }
+    /**
+     * 자동 sine 애니메이션 시작.
+     * 각 non-fixed 조인트를 limit 범위 내에서 sine 스윙. 조인트 순서에 따라
+     * frequency와 phase를 약간씩 다르게 해 동기화를 피하고 유기적 움직임을 만든다.
+     *
+     * state.joints를 건드리지 않고 joint.setJointValue만 직접 호출 — state 변경
+     * cascade를 피해 성능을 유지하고, 슬라이더가 있는 경우에도 state와 시각이
+     * 분리되어 표시됨 (활성 시 state는 의미 없음).
+     */
+    _startAutoAnimate() {
+        if (this._animRaf != null)
+            return;
+        if (!this._robot || this._jointMeta.size === 0)
+            return;
+        this._animStartTime = performance.now();
+        const TWO_PI = Math.PI * 2;
+        const tick = () => {
+            if (!this._robot) {
+                this._animRaf = undefined;
+                return;
+            }
+            const t = (performance.now() - this._animStartTime) / 1000;
+            let i = 0;
+            let changed = false;
+            for (const [name, meta] of this._jointMeta) {
+                const joint = this._jointIndex.get(name);
+                if (!joint)
+                    continue;
+                const mid = (meta.limit.upper + meta.limit.lower) / 2;
+                const amp = (meta.limit.upper - meta.limit.lower) / 2;
+                // 조인트별로 frequency와 phase 약간씩 다르게 (0.15 ~ 0.4 Hz 범위)
+                const freq = 0.15 + (i % 6) * 0.05;
+                const phase = i * 0.73;
+                const value = mid + amp * Math.sin(t * freq * TWO_PI + phase);
+                joint.setJointValue(value);
+                changed = true;
+                i++;
+            }
+            if (changed) {
+                this.component?.invalidate?.();
+            }
+            this._animRaf = requestAnimationFrame(tick);
+        };
+        this._animRaf = requestAnimationFrame(tick);
+    }
+    _stopAutoAnimate() {
+        if (this._animRaf != null) {
+            cancelAnimationFrame(this._animRaf);
+            this._animRaf = undefined;
+        }
+    }
+    /**
+     * 모든 조인트를 원본 값으로 복원한다.
+     */
+    _resetAllJoints() {
+        if (!this._robot)
+            return;
+        for (const [name, orig] of this._jointOriginals) {
+            const joint = this._jointIndex.get(name);
+            if (joint && joint.jointType !== 'fixed') {
+                joint.setJointValue(orig);
+            }
+        }
+    }
+    // --- 라이프사이클 ---
+    clear() {
+        this._stopAutoAnimate();
+        this._disposeController();
+        this._jointIndex.clear();
+        this._jointMeta.clear();
+        this._jointOriginals.clear();
+        this._robot = undefined;
+        return super.clear();
+    }
+    updateDimension() {
+        if (!this.pivot)
+            return;
+        const { width = 1, height = 1, depth = 1 } = this.component.state;
+        const { x = 1, y = 1, z = 1 } = this._objectSize || {};
+        // URDF는 관절 기반 로봇의 비율을 유지해야 하므로 uniform scale을 적용한다.
+        // 세 축 각각의 비율 중 가장 작은 값(best-fit)을 사용해 로봇이 컴포넌트의
+        // bounding box 안에 왜곡 없이 맞춰지도록 한다.
+        const unit = this._resolveUnitScale();
+        const baseX = x || 1;
+        const baseY = y || 1;
+        const baseZ = z || 1;
+        const upAxis = this.component.state.upAxis;
+        const rotated = upAxis !== 'y';
+        const rX = width / baseX;
+        const rY = (rotated ? depth : height) / baseY;
+        const rZ = (rotated ? height : depth) / baseZ;
+        const ratio = Math.min(rX, rY, rZ);
+        this.pivot.scale.setScalar(ratio * unit);
+        this.component.invalidate();
+    }
+    onchange(after, before) {
+        super.onchange(after, before);
+        if ('src' in after) {
+            this.updateSource();
+            return;
+        }
+        if ('joints' in after) {
+            // 사용자가 joint를 직접 조작하면 자동 애니메이션이 이를 즉시 덮어써
+            // 의도를 상쇄하므로, 자동 애니메이션을 우선 중지한다.
+            if (this._animRaf != null) {
+                this._stopAutoAnimate();
+                this._component.setState({ autoAnimate: 'none' });
+            }
+            const jointStates = after.joints;
+            if (this._controller) {
+                // controller 모드: 타겟만 갱신. 이전 값 리셋은 controller가 연속 감쇠로
+                // 알아서 수렴하므로 불필요.
+                if (jointStates && Object.keys(jointStates).length > 0) {
+                    this._dispatchJointStates(jointStates);
+                }
+            }
+            else {
+                // direct 모드: 전체 reset 후 명시된 값만 재적용 (sparse state 지원).
+                this._resetAllJoints();
+                if (jointStates && Object.keys(jointStates).length > 0) {
+                    this._applyJointStates(jointStates);
+                }
+            }
+        }
+        if ('autoAnimate' in after) {
+            if (after.autoAnimate === 'sine') {
+                this._startAutoAnimate();
+            }
+            else {
+                this._stopAutoAnimate();
+            }
+        }
+        if ('physics' in after) {
+            const mode = after.physics;
+            if (mode && mode !== 'none') {
+                this._setupController(mode);
+            }
+            else {
+                this._disposeController();
+            }
+        }
+        if ('upAxis' in after || 'unitScale' in after || 'packages' in after) {
+            // 좌표/스케일/패키지 매핑 변경은 pivot 재구성이 필요하므로 전체 재빌드
+            this.build();
+        }
+    }
+}
+//# sourceMappingURL=real-object-urdf.js.map