three-usd-robot 0.2.0

package/dist/core.d.ts

@@ -0,0 +1,464 @@
+import { n as UsdaFile, g as MetadataMap, m as UsdValue, P as PrimSpec, k as Specifier, j as RelationshipSpec, S as SdfPath, b as AttributeSpec, V as Variability, M as Mat4, R as RobotDescription, d as JointType, A as Axis } from './buildKinematicTree-2fg6ZN8m.js';
+export { a as AssetPath, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, J as JointDescription, c as JointDriveDescription, K as KinematicNode, e as KinematicTree, L as LinkDescription, f as ListOp, h as PropertySpec, Q as Quat, i as RAD2DEG, T as TreeEdge, U as UsdDictionary, l as UsdMatrix, o as Vec2, p as Vec3, q as Vec4, r as buildKinematicTree, s as fromUsdMatrix, t as getTranslation, u as identity4, v as invert, w as makeEuler, x as makeRotationFromQuat, y as makeRotationX, z as makeRotationY, E as makeRotationZ, F as makeScale, G as makeTranslation, H as multiply, I as multiplyAll } from './buildKinematicTree-2fg6ZN8m.js';
+
+/** Package identity. Kept in one place so every entry point can re-export it. */
+declare const PACKAGE_NAME = "three-usd-robot";
+/** Library version. Replaced by the release tooling at publish time. */
+declare const VERSION = "0.0.0";
+
+/**
+ * Recursive-descent parser for the USDA (ASCII USD) format.
+ *
+ * Scope (M1): prims (`def`/`over`/`class`), nested prims, attributes
+ * (`uniform`/`custom`/array/connections/time samples), relationships (with
+ * list-op qualifiers), and layer/prim/property metadata blocks. References,
+ * payloads and variant sets are tolerated as metadata but not resolved (M8/M10).
+ */
+
+declare function parseUsda(text: string): UsdaFile;
+
+/**
+ * Tokenizer for the USDA (ASCII USD) format.
+ *
+ * Produces a flat token stream consumed by `parseUsda`. Comments (`#...`) are
+ * stripped. Paths (`<...>`) and asset paths (`@...@` / `@@@...@@@`) are scanned
+ * as whole tokens because their interior characters are otherwise significant.
+ */
+type TokenType = "lbrace" | "rbrace" | "lparen" | "rparen" | "lbracket" | "rbracket" | "equals" | "comma" | "colon" | "dot" | "number" | "string" | "ident" | "path" | "asset" | "eof";
+type Token = {
+    type: TokenType;
+    /** Raw lexeme / decoded value. For `number` this is the original text. */
+    value: string;
+    /** Decoded numeric value for `number` tokens. */
+    num?: number;
+    /** 1-based line number where the token starts. */
+    line: number;
+    col: number;
+};
+declare class TokenizeError extends Error {
+    readonly line: number;
+    readonly col: number;
+    constructor(message: string, line: number, col: number);
+}
+declare function tokenize(src: string): Token[];
+
+declare class ParseError extends Error {
+    readonly line: number;
+    readonly col: number;
+    constructor(message: string, line: number, col: number);
+}
+
+/** A parsed USDA layer (`SdfLayer`-like, read-only). */
+declare class Layer {
+    private readonly _file;
+    constructor(_file: UsdaFile);
+    GetVersion(): string;
+    GetPseudoRootMetadata(): MetadataMap;
+    GetMetadata(key: string): UsdValue | undefined;
+    GetDefaultPrimName(): string | undefined;
+    GetRootPrimSpecs(): PrimSpec[];
+}
+
+/** OpenUSD's fallback stage linear unit when `metersPerUnit` is unauthored. */
+declare const DEFAULT_METERS_PER_UNIT = 0.01;
+type UpAxis = "Y" | "Z";
+/**
+ * A composed USD stage (`UsdStage`-like) backed by a single in-memory USDA
+ * layer. Multi-layer composition (sublayers / references / payloads) arrives in
+ * M8; for now a stage wraps exactly one parsed layer.
+ */
+declare class Stage {
+    private readonly _layer;
+    private readonly _byPath;
+    private readonly _pseudoRoot;
+    private constructor();
+    /** Parse and open a stage from USDA source text. */
+    static OpenFromString(usda: string): Stage;
+    /** Open a stage from an already-parsed layer. */
+    static OpenFromFile(file: UsdaFile): Stage;
+    private buildPrim;
+    GetRootLayer(): Layer;
+    GetPseudoRoot(): Prim;
+    /** Returns the prim at the absolute path, or `null` if none exists. */
+    GetPrimAtPath(path: string): Prim | null;
+    /** The stage's default prim (from layer `defaultPrim` metadata), if any. */
+    GetDefaultPrim(): Prim | null;
+    /** Depth-first traversal of all prims (excludes the pseudo-root). */
+    Traverse(): Prim[];
+    GetMetadata(key: string): UsdValue | undefined;
+    /** Stage up axis (`upAxis` metadata); defaults to `"Y"` per OpenUSD. */
+    GetUpAxis(): UpAxis;
+    /** Stage linear unit (`metersPerUnit` metadata); defaults to {@link DEFAULT_METERS_PER_UNIT}. */
+    GetMetersPerUnit(): number;
+}
+
+/**
+ * A composed prim on a {@link Stage} (`UsdPrim`-like).
+ *
+ * The pseudo-root (path `/`) is represented by a Prim with a `null` spec; its
+ * children are the stage's root prims.
+ */
+declare class Prim {
+    private readonly _stage;
+    private readonly _spec;
+    private readonly _path;
+    private readonly _parent;
+    private readonly _children;
+    private _attributes?;
+    private _relationships?;
+    constructor(_stage: Stage, _spec: PrimSpec | null, _path: string, _parent: Prim | null);
+    /** @internal Used by {@link Stage} while building the prim tree. */
+    _addChild(child: Prim): void;
+    GetStage(): Stage;
+    IsValid(): boolean;
+    IsPseudoRoot(): boolean;
+    GetName(): string;
+    GetPath(): string;
+    GetTypeName(): string;
+    GetSpecifier(): Specifier | null;
+    GetParent(): Prim | null;
+    GetChildren(): Prim[];
+    GetChild(name: string): Prim | null;
+    private attrMap;
+    /** Always returns an Attribute; check {@link Attribute.IsValid}. */
+    GetAttribute(name: string): Attribute;
+    HasAttribute(name: string): boolean;
+    GetAttributes(): Attribute[];
+    private relMap;
+    /** Always returns a Relationship; check {@link Relationship.IsValid}. */
+    GetRelationship(name: string): Relationship;
+    HasRelationship(name: string): boolean;
+    GetRelationships(): Relationship[];
+    GetMetadata(key: string): UsdValue | undefined;
+    GetAllMetadata(): MetadataMap;
+    /** Applied API schema names from `apiSchemas` (e.g. `PhysicsArticulationRootAPI`). */
+    GetAppliedSchemas(): string[];
+    /**
+     * Whether the given API schema is applied. Matches the bare schema name as
+     * well as multi-apply instances (e.g. `HasAPI("PhysicsDriveAPI")` is true for
+     * an applied `PhysicsDriveAPI:angular`).
+     */
+    HasAPI(schemaName: string): boolean;
+}
+
+/**
+ * A typed attribute on a prim (`UsdAttribute`-like).
+ *
+ * Mirrors the pxr USD API: `GetAttribute` always returns an `Attribute` object;
+ * call {@link Attribute.IsValid} to check whether the attribute is actually
+ * authored on the prim.
+ */
+declare class Attribute {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: AttributeSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    /** Scalar type name (without the `[]` suffix); pair with {@link IsArray}. */
+    GetTypeName(): string;
+    IsArray(): boolean;
+    GetVariability(): Variability;
+    IsCustom(): boolean;
+    /** True if a default value or any time sample is authored. */
+    HasValue(): boolean;
+    HasAuthoredValue(): boolean;
+    /**
+     * Resolve the attribute value. With no `time`, returns the default value (or
+     * the earliest time sample if only samples are authored). With a `time`,
+     * returns the exact sample if present, else the default, else the earliest
+     * sample. Returns `undefined` when nothing is authored.
+     */
+    Get(time?: number): UsdValue | undefined;
+    GetTimeSamples(): Map<number, UsdValue>;
+    GetConnections(): SdfPath[];
+}
+/** A relationship on a prim (`UsdRelationship`-like). */
+declare class Relationship {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: RelationshipSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    IsCustom(): boolean;
+    GetTargets(): SdfPath[];
+}
+
+/**
+ * Resolves USD asset paths (from references / payloads / sublayers) to URLs and
+ * fetches their text. Composition (`composition.ts`) is I/O-agnostic and goes
+ * through an {@link AssetResolver}, so the same engine works in the browser, in
+ * Node, or against an in-memory file map in tests.
+ */
+interface AssetResolver {
+    /** Resolve an authored asset path against the layer's base URL to an absolute key. */
+    resolve(assetPath: string, baseUrl: string): string;
+    /** Fetch the text of a resolved asset; rejects if it cannot be read. */
+    fetchText(url: string): Promise<string>;
+    /** Fetch the raw bytes of a resolved asset (for binary USDC / USDZ). Optional. */
+    fetchBytes?(url: string): Promise<Uint8Array>;
+}
+/** URL-based resolver using the global `fetch` (browser / Node 18+). */
+declare class DefaultAssetResolver implements AssetResolver {
+    resolve(assetPath: string, baseUrl: string): string;
+    fetchText(url: string): Promise<string>;
+    fetchBytes(url: string): Promise<Uint8Array>;
+}
+/** Resolver over an in-memory `{ path: contents }` map, with posix-style joins. */
+declare function createMemoryResolver(files: Record<string, string>): AssetResolver;
+/** Resolve `rel` against `baseUrl` using posix semantics, normalizing `.`/`..`. */
+declare function joinPosix(baseUrl: string, rel: string): string;
+
+/**
+ * Minimal USD composition: flattens references, payloads and sublayers into a
+ * single {@link UsdaFile} so the rest of the pipeline keeps working on one layer.
+ *
+ * Scope (M8): the arcs robots actually use. References and payloads pull a prim
+ * subtree from another asset (weaker than local opinions); sublayers overlay a
+ * weaker layer stack. Inherits / variants / specializes are out of scope (M10).
+ * This is not a full LIVRPS implementation — it is a pragmatic flattener.
+ */
+
+type ComposeOptions = {
+    onWarn?: (message: string) => void;
+    /** Guard against pathological recursion (default 64). */
+    maxDepth?: number;
+};
+/**
+ * Parse and fully compose a layer: resolve its sublayers and every prim's
+ * references/payloads (recursively), returning a flattened layer. Unresolvable
+ * arcs are reported via `onWarn` and skipped.
+ */
+declare function composeLayer(text: string, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>): Promise<UsdaFile>;
+
+/**
+ * USDZ (zipped USD package) support.
+ *
+ * A `.usdz` is an uncompressed zip whose entries are USD layers + textures.
+ * {@link openUsdz} unzips it (via `fflate`) and returns the root layer entry
+ * plus an {@link AssetResolver} that serves the package's other entries, so
+ * references inside the package resolve through the normal composition path.
+ * USDC (binary crate) entries are not decodable yet (M10).
+ */
+
+type UsdzPackage = {
+    /** Archive path of the root layer to open. */
+    rootEntry: string;
+    /** Resolver over the package's entries. */
+    resolver: AssetResolver;
+};
+/** Unzip a `.usdz` package and build a resolver over its entries. */
+declare function openUsdz(bytes: Uint8Array): UsdzPackage;
+
+/**
+ * Reader for the OpenUSD binary "crate" format (`.usdc` / binary `.usd`).
+ *
+ * Built incrementally (M10): bootstrap header + table of contents + the TOKENS
+ * section first; STRINGS/FIELDS/FIELDSETS/PATHS/SPECS and value reps follow.
+ * References pxr `Usd/crateFile.cpp`. This is a from-scratch TS reader — not a
+ * binding to OpenUSD.
+ */
+
+type CrateSection = {
+    name: string;
+    start: number;
+    size: number;
+};
+type CrateField = {
+    /** Field name (token index). */
+    nameIndex: number;
+    /** Packed `ValueRep` (decoded in M10c). */
+    rep: bigint;
+};
+type CrateSpec = {
+    pathIndex: number;
+    fieldSetIndex: number;
+    specType: number;
+};
+declare class CrateReader {
+    readonly version: readonly [number, number, number];
+    readonly view: DataView;
+    private readonly bytes;
+    private readonly sections;
+    private _tokens?;
+    private _strings?;
+    private _fields?;
+    private _fieldSets?;
+    private _paths?;
+    private _specs?;
+    constructor(bytes: Uint8Array);
+    /** True if `bytes` begins with the crate magic. */
+    static isCrate(bytes: Uint8Array): boolean;
+    getSection(name: string): CrateSection | undefined;
+    /** Read a little-endian uint64 as a JS number (safe for crate-sized files). */
+    u64(offset: number): number;
+    i64(offset: number): bigint;
+    private readToc;
+    getTokens(): string[];
+    getToken(index: number): string;
+    private readTokens;
+    /** String values are token indices. */
+    getStrings(): number[];
+    private readStrings;
+    /** Read a `TfFastCompression`-wrapped, delta+integer-compressed array of `count` ints. */
+    private readCompressedInts;
+    getFields(): CrateField[];
+    private readFields;
+    getFieldSets(): number[];
+    private readFieldSets;
+    /** The field indices of the field set starting at `index` (until the sentinel). */
+    getFieldSet(index: number): number[];
+    getPaths(): string[];
+    private readPaths;
+    /** Reconstruct path strings from the compressed path tree (pxr `_BuildDecompressedPathsImpl`). */
+    private buildPaths;
+    getSpecs(): CrateSpec[];
+    private readSpecs;
+    /** Decode a `ValueRep` into a {@link UsdValue} (or `undefined` if unsupported). */
+    getValue(rep: bigint): UsdValue | undefined;
+    private readInlined;
+    private readScalar;
+    private readArray;
+    private readFloat32s;
+    private readFloat64s;
+    private readVec3fArray;
+    /** Read a `[u64 count][count × uint32|int32 index]` vector → resolved strings. */
+    private readIndexVector;
+    /** Read an SdfListOp; returns the effective (explicit ∪ prepended ∪ added ∪ appended) items. */
+    private readListOp;
+}
+
+/**
+ * Bridges a parsed crate ({@link CrateReader}) into the in-memory {@link UsdaFile}
+ * AST, so the rest of the pipeline (Stage / composition / extractor / runtime)
+ * works on binary `.usd` exactly like ASCII `.usda`.
+ */
+
+declare function crateToUsdaFile(crate: CrateReader): UsdaFile;
+
+/**
+ * Resolves a prim's `xformOpOrder` into a single local transform matrix.
+ *
+ * Supports `translate`, `scale`, `orient` (quat), `transform` (matrix4d),
+ * single-axis `rotateX|Y|Z`, and the six `rotate<ORDER>` Euler ops, plus the
+ * `!invert!` op prefix and the `!resetXformStack!` sentinel. Rotation op values
+ * are in degrees and converted to radians here.
+ */
+
+type ResolvedXform = {
+    /** Local-to-parent transform (column-major {@link Mat4}). */
+    matrix: Mat4;
+    /**
+     * True if `xformOpOrder` began with `!resetXformStack!`, meaning this prim
+     * does not inherit its parent's transform. Honored by FK in M5.
+     */
+    resetsXformStack: boolean;
+};
+/**
+ * Compute a prim's local transform from its `xformOpOrder`. Returns identity
+ * when the prim authors no `xformOpOrder`.
+ */
+declare function computeLocalTransform(prim: Prim): ResolvedXform;
+/** Extract the op type token from an op attribute name (`xformOp:translate:pivot` → `translate`). */
+declare function parseOpType(opName: string): string;
+
+/**
+ * Extracts a {@link RobotDescription} from a USD {@link Stage}.
+ *
+ * Collects links (rigid bodies / joint-referenced prims) and the
+ * Fixed/Revolute/Prismatic joints connecting them, resolves `body0`/`body1` to
+ * link keys, and normalizes limits to SI. The authoritative root link and
+ * closed-loop detection come from {@link buildKinematicTree} (M4), whose result
+ * is written back into `rootLink` / `loopJoints`.
+ */
+
+type ExtractOptions = {
+    /** Override the robot name (defaults to the stage default prim or first root prim). */
+    robotName?: string;
+    /** Receives non-fatal diagnostics; also collected into `RobotDescription.warnings`. */
+    onWarn?: (message: string) => void;
+};
+declare function extractRobotDescription(stage: Stage, options?: ExtractOptions): RobotDescription;
+
+/** SI normalization for joint values. */
+
+/**
+ * Normalize raw joint limits to SI: revolute/continuous degrees → radians;
+ * prismatic kept in stage linear units (global metersPerUnit scaling is applied
+ * at the root in M9). Non-finite or unauthored limits become `undefined`.
+ */
+declare function normalizeJointLimits(type: JointType, rawLower: number | undefined, rawUpper: number | undefined): {
+    lower?: number;
+    upper?: number;
+};
+/** Convert an authored joint value to SI (angular degrees → radians). */
+declare function jointValueToSI(angular: boolean, raw: number): number;
+/**
+ * A revolute joint with no finite limits is a continuous (unbounded) joint.
+ * Returns the refined joint type.
+ */
+declare function refineJointType(base: JointType, lower: number | undefined, upper: number | undefined): JointType;
+
+/** UsdGeom schema helpers (type checks and geometry gathering). */
+
+declare function isXform(prim: Prim): boolean;
+declare function isScope(prim: Prim): boolean;
+declare function isMesh(prim: Prim): boolean;
+/** Depth-first iterator over all descendant prims (excluding `prim` itself). */
+declare function iterDescendants(prim: Prim): Generator<Prim>;
+/** Collect the prim paths of all Mesh descendants of a link prim. */
+declare function gatherMeshDescendants(prim: Prim): string[];
+
+/**
+ * UsdPhysics schema helpers for robot extraction.
+ *
+ * Reads the joint/body attributes that matter for kinematics. Values are
+ * returned as authored (degrees for revolute limits, stage units for lengths);
+ * SI normalization happens in `robot/normalize.ts`.
+ */
+
+declare const ARTICULATION_ROOT_API = "PhysicsArticulationRootAPI";
+declare const RIGID_BODY_API = "PhysicsRigidBodyAPI";
+declare const COLLISION_API = "PhysicsCollisionAPI";
+/** Base joint type from the prim's schema type, or `null` if not a joint. */
+declare function getJointType(prim: Prim): JointType | null;
+/** Resolve `physics:body0` / `physics:body1` target paths (first target each). */
+declare function getJointBodies(prim: Prim): {
+    body0?: SdfPath;
+    body1?: SdfPath;
+};
+/** Joint axis token (`physics:axis`); defaults to `"X"` per UsdPhysics. */
+declare function getJointAxis(prim: Prim): Axis;
+/** Raw joint limits as authored (degrees for revolute; `undefined` if unauthored). */
+declare function getJointLimits(prim: Prim): {
+    lower?: number;
+    upper?: number;
+};
+/**
+ * The joint frame relative to body `index` (0 or 1), as a column-major matrix
+ * `T(localPos) · R(localRot)`. Missing components default to identity.
+ */
+declare function getJointLocalFrame(prim: Prim, index: 0 | 1): Mat4;
+declare function hasArticulationRootAPI(prim: Prim): boolean;
+declare function hasRigidBodyAPI(prim: Prim): boolean;
+declare function hasCollisionAPI(prim: Prim): boolean;
+/** Drive instance name for a joint type (`angular` for revolute, `linear` otherwise). */
+declare function driveKindFor(type: JointType): "angular" | "linear";
+/** Read `UsdPhysicsDriveAPI` parameters for the given instance, as authored. */
+declare function getJointDrive(prim: Prim, kind: "angular" | "linear"): {
+    targetPosition?: number;
+    stiffness?: number;
+    damping?: number;
+    maxForce?: number;
+};
+/** Read `PhysicsJointStateAPI` position for the given instance, as authored. */
+declare function getJointStatePosition(prim: Prim, kind: "angular" | "linear"): number | undefined;
+
+export { ARTICULATION_ROOT_API, type AssetResolver, Attribute, AttributeSpec, Axis, COLLISION_API, type ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, type ExtractOptions, JointType, Layer, Mat4, MetadataMap, PACKAGE_NAME, ParseError, Prim, PrimSpec, RIGID_BODY_API, Relationship, RelationshipSpec, type ResolvedXform, RobotDescription, SdfPath, Specifier, Stage, TokenizeError, type UpAxis, UsdValue, UsdaFile, type UsdzPackage, VERSION, Variability, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize };

package/dist/core.js

@@ -0,0 +1,3 @@
+export { ARTICULATION_ROOT_API, AssetPath, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DEG2RAD, DefaultAssetResolver, Layer, PACKAGE_NAME, ParseError, Prim, Quat, RAD2DEG, RIGID_BODY_API, Relationship, Stage, TokenizeError, UsdMatrix, VERSION, buildKinematicTree, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './chunk-XCP5GZPY.js';
+//# sourceMappingURL=core.js.map
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"core.js"}

package/dist/extras.d.ts

@@ -0,0 +1,50 @@
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-lMZHW-it.js';
+import 'three';
+import './buildKinematicTree-2fg6ZN8m.js';
+
+/**
+ * `three-usd-robot/extras`
+ *
+ * Heavier convenience utilities kept out of the main bundle. Currently a
+ * `lil-gui` joint slider panel — but this module does **not** depend on
+ * `lil-gui`: the caller passes in a GUI instance (typed structurally), so no UI
+ * library leaks into the bundle.
+ */
+
+/** Minimal structural view of a `lil-gui` controller (only what we use). */
+interface GuiController {
+    name(name: string): GuiController;
+    onChange(callback: (value: number) => void): GuiController;
+    updateDisplay?(): GuiController;
+}
+/** Minimal structural view of a `lil-gui` GUI / folder. */
+interface GuiLike {
+    add(target: Record<string, number>, key: string, min?: number, max?: number, step?: number): GuiController;
+}
+type JointSliderPanelOptions = {
+    /** Half-range used when a revolute joint has no limits (radians, default π). */
+    defaultAngularRange?: number;
+    /** Half-range used when a prismatic joint has no limits (default `1`). */
+    defaultLinearRange?: number;
+    /** Slider step (default `0.01`). */
+    step?: number;
+};
+type JointSliderPanel = {
+    controllers: GuiController[];
+    /** Re-read joint values from the robot into the sliders. */
+    update(): void;
+};
+/**
+ * Add one slider per articulated joint to a `lil-gui` GUI (or folder). Moving a
+ * slider drives the robot and refreshes its kinematics.
+ *
+ * @example
+ * ```ts
+ * import GUI from "lil-gui";
+ * import { createJointSliderPanel } from "three-usd-robot/extras";
+ * createJointSliderPanel(robot, new GUI());
+ * ```
+ */
+declare function createJointSliderPanel(robot: ThreeUsdRobot, gui: GuiLike, options?: JointSliderPanelOptions): JointSliderPanel;
+
+export { type GuiController, type GuiLike, type JointSliderPanel, type JointSliderPanelOptions, createJointSliderPanel };

package/dist/extras.js

@@ -0,0 +1,35 @@
+// src/extras.ts
+function createJointSliderPanel(robot, gui, options = {}) {
+  const angular = options.defaultAngularRange ?? Math.PI;
+  const linear = options.defaultLinearRange ?? 1;
+  const step = options.step ?? 0.01;
+  const state = {};
+  const controllers = [];
+  for (const name of robot.getJointNames()) {
+    const joint = robot.getJointObject(name);
+    if (!joint?.articulated) continue;
+    const fallback = joint.jointType === "prismatic" ? linear : angular;
+    const lo = joint.lower ?? -fallback;
+    const hi = joint.upper ?? fallback;
+    state[name] = joint.value;
+    const controller = gui.add(state, name, lo, hi, step).name(name).onChange((value) => {
+      robot.setJointValue(name, value);
+      robot.updateKinematics();
+    });
+    controllers.push(controller);
+  }
+  return {
+    controllers,
+    update() {
+      for (const name of Object.keys(state)) {
+        const value = robot.getJointValue(name);
+        if (value !== void 0) state[name] = value;
+      }
+      for (const c of controllers) c.updateDisplay?.();
+    }
+  };
+}
+
+export { createJointSliderPanel };
+//# sourceMappingURL=extras.js.map
+//# sourceMappingURL=extras.js.map

package/dist/extras.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extras.ts"],"names":[],"mappings":";AAuDO,SAAS,sBAAA,CACd,KAAA,EACA,GAAA,EACA,OAAA,GAAmC,EAAC,EAClB;AAClB,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,mBAAA,IAAuB,IAAA,CAAK,EAAA;AACpD,EAAA,MAAM,MAAA,GAAS,QAAQ,kBAAA,IAAsB,CAAA;AAC7C,EAAA,MAAM,IAAA,GAAO,QAAQ,IAAA,IAAQ,IAAA;AAE7B,EAAA,MAAM,QAAgC,EAAC;AACvC,EAAA,MAAM,cAA+B,EAAC;AAEtC,EAAA,KAAA,MAAW,IAAA,IAAQ,KAAA,CAAM,aAAA,EAAc,EAAG;AACxC,IAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,cAAA,CAAe,IAAI,CAAA;AACvC,IAAA,IAAI,CAAC,OAAO,WAAA,EAAa;AAEzB,IAAA,MAAM,QAAA,GAAW,KAAA,CAAM,SAAA,KAAc,WAAA,GAAc,MAAA,GAAS,OAAA;AAC5D,IAAA,MAAM,EAAA,GAAK,KAAA,CAAM,KAAA,IAAS,CAAC,QAAA;AAC3B,IAAA,MAAM,EAAA,GAAK,MAAM,KAAA,IAAS,QAAA;AAE1B,IAAA,KAAA,CAAM,IAAI,IAAI,KAAA,CAAM,KAAA;AACpB,IAAA,MAAM,UAAA,GAAa,GAAA,CAChB,GAAA,CAAI,KAAA,EAAO,MAAM,EAAA,EAAI,EAAA,EAAI,IAAI,CAAA,CAC7B,IAAA,CAAK,IAAI,CAAA,CACT,QAAA,CAAS,CAAC,KAAA,KAAU;AACnB,MAAA,KAAA,CAAM,aAAA,CAAc,MAAM,KAAK,CAAA;AAC/B,MAAA,KAAA,CAAM,gBAAA,EAAiB;AAAA,IACzB,CAAC,CAAA;AACH,IAAA,WAAA,CAAY,KAAK,UAAU,CAAA;AAAA,EAC7B;AAEA,EAAA,OAAO;AAAA,IACL,WAAA;AAAA,IACA,MAAA,GAAS;AACP,MAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,EAAG;AACrC,QAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,aAAA,CAAc,IAAI,CAAA;AACtC,QAAA,IAAI,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,IAAI,CAAA,GAAI,KAAA;AAAA,MACzC;AACA,MAAA,KAAA,MAAW,CAAA,IAAK,WAAA,EAAa,CAAA,CAAE,aAAA,IAAgB;AAAA,IACjD;AAAA,GACF;AACF","file":"extras.js","sourcesContent":["/**\n * `three-usd-robot/extras`\n *\n * Heavier convenience utilities kept out of the main bundle. Currently a\n * `lil-gui` joint slider panel — but this module does **not** depend on\n * `lil-gui`: the caller passes in a GUI instance (typed structurally), so no UI\n * library leaks into the bundle.\n */\n\nimport type { ThreeUsdRobot } from \"./three/ThreeUsdRobot.js\";\n\n/** Minimal structural view of a `lil-gui` controller (only what we use). */\nexport interface GuiController {\n  name(name: string): GuiController;\n  onChange(callback: (value: number) => void): GuiController;\n  updateDisplay?(): GuiController;\n}\n\n/** Minimal structural view of a `lil-gui` GUI / folder. */\nexport interface GuiLike {\n  add(\n    target: Record<string, number>,\n    key: string,\n    min?: number,\n    max?: number,\n    step?: number,\n  ): GuiController;\n}\n\nexport type JointSliderPanelOptions = {\n  /** Half-range used when a revolute joint has no limits (radians, default π). */\n  defaultAngularRange?: number;\n  /** Half-range used when a prismatic joint has no limits (default `1`). */\n  defaultLinearRange?: number;\n  /** Slider step (default `0.01`). */\n  step?: number;\n};\n\nexport type JointSliderPanel = {\n  controllers: GuiController[];\n  /** Re-read joint values from the robot into the sliders. */\n  update(): void;\n};\n\n/**\n * Add one slider per articulated joint to a `lil-gui` GUI (or folder). Moving a\n * slider drives the robot and refreshes its kinematics.\n *\n * @example\n * ```ts\n * import GUI from \"lil-gui\";\n * import { createJointSliderPanel } from \"three-usd-robot/extras\";\n * createJointSliderPanel(robot, new GUI());\n * ```\n */\nexport function createJointSliderPanel(\n  robot: ThreeUsdRobot,\n  gui: GuiLike,\n  options: JointSliderPanelOptions = {},\n): JointSliderPanel {\n  const angular = options.defaultAngularRange ?? Math.PI;\n  const linear = options.defaultLinearRange ?? 1;\n  const step = options.step ?? 0.01;\n\n  const state: Record<string, number> = {};\n  const controllers: GuiController[] = [];\n\n  for (const name of robot.getJointNames()) {\n    const joint = robot.getJointObject(name);\n    if (!joint?.articulated) continue;\n\n    const fallback = joint.jointType === \"prismatic\" ? linear : angular;\n    const lo = joint.lower ?? -fallback;\n    const hi = joint.upper ?? fallback;\n\n    state[name] = joint.value;\n    const controller = gui\n      .add(state, name, lo, hi, step)\n      .name(name)\n      .onChange((value) => {\n        robot.setJointValue(name, value);\n        robot.updateKinematics();\n      });\n    controllers.push(controller);\n  }\n\n  return {\n    controllers,\n    update() {\n      for (const name of Object.keys(state)) {\n        const value = robot.getJointValue(name);\n        if (value !== undefined) state[name] = value;\n      }\n      for (const c of controllers) c.updateDisplay?.();\n    },\n  };\n}\n"]}

package/dist/helpers.d.ts

@@ -0,0 +1,39 @@
+import * as THREE from 'three';
+import { J as JointObject, T as ThreeUsdRobot } from './ThreeUsdRobot-lMZHW-it.js';
+import './buildKinematicTree-2fg6ZN8m.js';
+
+/**
+ * An arrow drawn along a joint's motion axis (the rotation axis for
+ * revolute/continuous joints, the slide direction for prismatic). Add it to the
+ * joint's motion node so it tracks the joint.
+ */
+declare class JointAxisHelper extends THREE.ArrowHelper {
+    readonly isJointAxisHelper = true;
+    constructor(joint: JointObject, length?: number, color?: THREE.ColorRepresentation);
+}
+
+/**
+ * Visualizes a joint's range of motion: an arc swept between the lower and
+ * upper limits (revolute/continuous) or a line segment between them
+ * (prismatic). A limitless revolute joint draws a full circle. Add it to the
+ * joint's motion node's parent frame (or the joint node) to anchor it.
+ */
+declare class JointLimitHelper extends THREE.Line {
+    readonly isJointLimitHelper = true;
+    constructor(joint: JointObject, radius?: number, color?: THREE.ColorRepresentation);
+}
+
+/** A small RGB axes gizmo for a link's local frame. Add it to a `LinkObject`. */
+declare class LinkFrameHelper extends THREE.AxesHelper {
+    readonly isLinkFrameHelper = true;
+    constructor(size?: number);
+}
+
+/** Attach a {@link JointAxisHelper} to every articulated joint. Returns the helpers. */
+declare function addJointAxisHelpers(robot: ThreeUsdRobot, length?: number, color?: THREE.ColorRepresentation): JointAxisHelper[];
+/** Attach a {@link JointLimitHelper} to every articulated joint. Returns the helpers. */
+declare function addJointLimitHelpers(robot: ThreeUsdRobot, radius?: number, color?: THREE.ColorRepresentation): JointLimitHelper[];
+/** Attach a {@link LinkFrameHelper} to every link. Returns the helpers. */
+declare function addLinkFrameHelpers(robot: ThreeUsdRobot, size?: number): LinkFrameHelper[];
+
+export { JointAxisHelper, JointLimitHelper, LinkFrameHelper, addJointAxisHelpers, addJointLimitHelpers, addLinkFrameHelpers };