@operato/scene-urdf 10.0.0-beta.2 → 10.0.0-beta.24

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAA","sourcesContent":["export { default as UrdfViewer } from './urdf-viewer.js'\nexport { default as UrdfController } from './urdf-controller.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mDAAmD;AACnD,OAAO,kBAAkB,CAAA;AACzB,0CAA0C;AAC1C,OAAO,2BAA2B,CAAA;AAElC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,gDAAgD;AAChD,2EAA2E;AAC3E,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n *\n * URDF 플러그인 — things-scene의 RealObjectExternalModel 베이스를 상속받아\n * URDF(Unified Robot Description Format) 로봇을 네이티브 3D 씬 오브젝트로\n * 렌더링한다. @sceneComponent('urdf')로 등록되어 things-factory 보드에서\n * 일반 컴포넌트처럼 사용 가능.\n *\n * 기본 loader는 STL/DAE/GLB를 지원하며, GLB는 things-scene의 RealObjectGLTF\n * 캐시와 공유한다. xacro 전처리는 현재 미지원(ros-industrial 로봇 등은 사전\n * 변환된 URDF 필요).\n */\n\n// @sceneComponent decorator side-effect를 위해 import\nimport './urdf-object.js'\n// 기본 'smooth' controller 등록 (side-effect)\nimport './smoothing-controller.js'\n\nexport { RealObjectURDF } from './real-object-urdf.js'\nexport type { URDFJointState, URDFJointMeta } from './real-object-urdf.js'\nexport { URDFObject } from './urdf-object.js'\n\n// 외부 모듈이 자체 JointController를 등록할 때 사용하는 공개 API.\n// 예: @operato/scene-urdf-rapier가 `registerJointController('rapier', ...)`.\nexport {\n  registerJointController,\n  createJointController,\n  listJointControllers\n} from './joint-controller.js'\nexport type {\n  JointController,\n  JointControllerContext,\n  JointControllerFactory\n} from './joint-controller.js'\nexport { SmoothingController } from './smoothing-controller.js'\n"]}

package/dist/joint-controller.d.ts

@@ -0,0 +1,35 @@
+import type { URDFRobot, URDFJoint } from 'urdf-loader';
+import type { URDFJointMeta } from './real-object-urdf.js';
+export interface JointControllerContext {
+    robot: URDFRobot;
+    /** non-fixed + fixed 포함 모든 조인트 */
+    joints: Map<string, URDFJoint>;
+    /** non-fixed 조인트의 메타 (type, axis, limit) — fixed는 제외됨 */
+    jointMeta: Map<string, URDFJointMeta>;
+}
+export interface JointController {
+    /** 로봇 로드 직후 1회 호출. 내부 상태(current/target/velocity 등) 초기화. */
+    setup(ctx: JointControllerContext): void;
+    /**
+     * state.joints 변경 시 호출. controller가 `targets` 맵을 내부 저장하고
+     * tick에서 실제 적용을 결정한다. 각 value는 joint의 internal unit
+     * (revolute=rad, prismatic=m).
+     */
+    setTargets(targets: Record<string, number>): void;
+    /**
+     * 매 프레임 호출 (requestAnimationFrame). dt는 초 단위.
+     * 관절에 값을 적용(joint.setJointValue)하고, 값이 실제로 변경됐다면 true를
+     * 반환 (상위가 invalidate를 결정).
+     */
+    tick(dt: number): boolean;
+    /** 로봇 해제 시 호출. 내부 자원/캐시 정리. */
+    dispose(): void;
+}
+export type JointControllerFactory = () => JointController;
+/**
+ * 외부 패키지가 자신의 controller 구현을 등록한다.
+ * 예: `registerJointController('rapier', () => new RapierJointController())`.
+ */
+export declare function registerJointController(name: string, factory: JointControllerFactory): void;
+export declare function createJointController(name: string): JointController | undefined;
+export declare function listJointControllers(): string[];

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;
+}