@needle-tools/usd 0.0.2-next.de2e82b → 1.0.0-next.d840b4c

package/src/plugins/index.js

@@ -1,2 +1 @@
-export { addPluginForNeedleEngine } from "./needle.js";
-
+export { addPluginForNeedleEngine, getHydraHandleFromNeedleEngineAsset } from "./needle.js";

package/src/plugins/needle.js

@@ -1,6 +1,39 @@
 import { Loader, Object3D } from "three";
 import { createThreeHydra, getUsdModule } from "../index.js";
 
+const hydraHandlesByRoot = new WeakMap();
+
+/**
+ * Return the Hydra handle created by the Needle Engine USD plugin for a loaded asset.
+ * The argument can be the value returned by `NEEDLE.loadAsset(...)` or any Object3D
+ * within that loaded hierarchy.
+ *
+ * @param {unknown} asset
+ * @returns {import("..").NeedleThreeHydraHandle | null}
+ */
+export function getHydraHandleFromNeedleEngineAsset(asset) {
+    const root = findObject3D(asset);
+    if (!root) return null;
+
+    let handle = hydraHandlesByRoot.get(root) || null;
+    if (handle) return handle;
+
+    root.traverse?.((object) => {
+        handle ??= hydraHandlesByRoot.get(object) || null;
+    });
+    return handle;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Object3D | null}
+ */
+function findObject3D(value) {
+    if (!value) return null;
+    if (value instanceof Object3D || value.isObject3D === true) return value;
+    return findObject3D(value.scene) || findObject3D(value.root);
+}
+
 
 /** @type {import("../types").addPluginForNeedleEngine} */
 export async function addPluginForNeedleEngine(options) {
@@ -34,9 +67,10 @@ function onAddNeedlePlugin(NEEDLE, opts) {
         }
         onDestroy() {
             if (this.handle) {
-                this.handle.dispose();
+                void this.handle.dispose();
                 this.handle = null;
             }
+            hydraHandlesByRoot.delete(this.root);
         }
     }
 
@@ -95,8 +129,10 @@ function onAddNeedlePlugin(NEEDLE, opts) {
                 scene: this.comp.root,
                 url: url,
                 files: files,
+                waitForMaterials: opts.waitForMaterials,
             });
             this.comp.handle = handle;
+            hydraHandlesByRoot.set(this.comp.root, handle);
 
             if (debug) console.debug("Loaded", this.comp);
 
@@ -155,4 +191,4 @@ function onAddNeedlePlugin(NEEDLE, opts) {
         handlers.length = 0;
     }
 
-}
+}

package/src/types/bindings.d.ts

@@ -11,6 +11,8 @@ declare type FSNode = {
     write: boolean,
 }
 
+declare type MaybePromise<T> = T | Promise<T>
+
 declare type USD = {
     FS_createDataFile: (parent: string, filepath: string, data: Uint8Array, canRead: boolean, canWrite: boolean, canOwn: boolean) => FSNode,
     FS_createPath: (parent: string, path: string, canRead: boolean, canWrite: boolean) => FSNode,
@@ -18,6 +20,12 @@ declare type USD = {
     FS_readdir: (path: string) => string[],
     FS_rmdir: (path: string) => void,
     FS_analyzePath: (path: string) => FSNode,
+    CreateStage: (path: string) => USDStage,
+    OpenStage: (path: string) => MaybePromise<USDStage>,
+    ReleaseStage: (stage: USDStage) => boolean,
+    CreateUsdzPackage: (assetPath: string, usdzPath: string) => MaybePromise<boolean>,
+    GetBuildInfoJson: () => string,
+    ReadFile: (path: string) => Uint8Array,
     HdWebSyncDriver: new (delegate: hydraDelegate, filepath: string) => HdWebSyncDriver,
     flushPendingDeletes: () => void,
     ready: Promise<any>,
@@ -28,19 +36,292 @@ declare type USD = {
     stdout: any;
 };
 
+export type OpenUsdBuildInfo = {
+    schema: 1,
+    openusd: {
+        version: string,
+        pxrVersion: number,
+        gitSha: string,
+        gitDirty: boolean,
+    },
+    toolchain: {
+        emscripten: string,
+        cxxCompiler: string,
+        cmakeBuildType: string,
+    },
+    modules: {
+        usdImaging: boolean,
+        hydraBridge: boolean,
+        materialX: boolean,
+        openSubdiv: boolean,
+        usdGltf: boolean,
+    },
+    dependencies: {
+        openSubdiv: {
+            version: string,
+        },
+        materialX: {
+            prefix: string,
+            gitSha: string,
+            gitDirty: boolean,
+        },
+        usdGltf: {
+            prefix: string,
+            gitSha: string,
+            gitDirty: boolean,
+        },
+        emsdk: {
+            gitSha: string,
+            gitDirty: boolean,
+        },
+    },
+}
+
+// Generated in OpenUSD from pxr/usdImaging/hdEmscripten/bindgen/core-bindings.json.
+// Keep this core USD surface in sync with the generated usd-core-bindings.d.ts.
+declare type IntVector = {
+    size(): number,
+    get(index: number): number,
+    delete(): void,
+}
+
+declare type DoubleVector = {
+    size(): number,
+    get(index: number): number,
+    delete(): void,
+}
+
+declare type StringVector = {
+    size(): number,
+    get(index: number): string,
+    delete(): void,
+}
+
+declare type USDPrimVector = {
+    size(): number,
+    get(index: number): USDPrim,
+    delete(): void,
+}
+
+declare type USDAttributeVector = {
+    size(): number,
+    get(index: number): USDAttribute,
+    delete(): void,
+}
+
+declare type USDRelationshipVector = {
+    size(): number,
+    get(index: number): USDRelationship,
+    delete(): void,
+}
+
+declare type USDLayerOffset = {
+    offset: number,
+    scale: number,
+    isIdentity: boolean,
+}
+
+declare type USDLayerInfo = {
+    identifier: string,
+    displayName: string,
+    realPath: string,
+}
+
+declare type USDSpecStackEntry = {
+    path: string,
+    layer: USDLayerInfo,
+    layerOffset?: USDLayerOffset,
+    metadata: Record<string, string>,
+    specifier?: string,
+    typeName?: string,
+    name?: string,
+}
+
+declare type USDSpecStack = USDSpecStackEntry[]
+
+declare type USDResolveInfo = {
+    source: "None" | "Fallback" | "Default" | "TimeSamples" | "ValueClips" | "Spline" | "Unknown",
+    hasAuthoredValueOpinion: boolean,
+    hasAuthoredValue: boolean,
+    valueIsBlocked: boolean,
+    valueSourceMightBeTimeVarying: boolean,
+    hasNextWeakerInfo: boolean,
+}
+
+declare type USDPcpNode = {
+    arcType?: string,
+    path?: string,
+    pathAtIntroduction?: string,
+    layerStackIdentifier?: string,
+    children?: USDPcpNode[],
+}
+
+declare type USDPrimIndex = {
+    isValid: boolean,
+    rootNode?: USDPcpNode,
+}
+
+declare type USDCompositionArc = {
+    arcType: string,
+    targetLayer: USDLayerInfo,
+    targetPrimPath: string,
+    introducingLayer: USDLayerInfo,
+    introducingPrimPath: string,
+    isImplicit: boolean,
+    isAncestral: boolean,
+    hasSpecs: boolean,
+    isIntroducedInRootLayerStack: boolean,
+    isIntroducedInRootLayerPrimSpec: boolean,
+}
+
+declare type USDObjectsChangedNotice = {
+    resyncedPaths: string[],
+    changedInfoOnlyPaths: string[],
+    resolvedAssetPathsResyncedPaths: string[],
+    changedFields: Record<string, string[]>,
+}
+
+declare type USDLayer = {
+    GetIdentifier(): string,
+    GetDisplayName(): string,
+    GetRealPath(): string,
+    ExportToString(): string,
+    Export(path: string): boolean,
+    Save(): boolean,
+}
+
+declare type USDAttribute = {
+    IsValid(): boolean,
+    GetName(): string,
+    GetPath(): string,
+    GetTypeName(): string,
+    GetAllMetadata(): Record<string, string>,
+    GetMetadataString(key: string): string,
+    HasAuthoredMetadata(key: string): boolean,
+    GetValueString(): string,
+    GetValueStringAtTime(timeCode: number): string,
+    GetConnections(): StringVector,
+    GetResolveInfo(timeCode: number): USDResolveInfo,
+    HasAuthoredValue(): boolean,
+    HasAuthoredValueOpinion(): boolean,
+    GetNumTimeSamples(): number,
+    GetTimeSamples(): DoubleVector,
+    GetPropertyStack(timeCode: number): USDSpecStack,
+    GetPropertyStackWithLayerOffsets(timeCode: number): USDSpecStack,
+    SetBool(value: boolean, timeCode: number): boolean,
+    SetInt(value: number, timeCode: number): boolean,
+    SetFloat(value: number, timeCode: number): boolean,
+    SetDouble(value: number, timeCode: number): boolean,
+    SetString(value: string, timeCode: number): boolean,
+    SetToken(value: string, timeCode: number): boolean,
+    AddConnection(path: string): boolean,
+    SetColor3f(r: number, g: number, b: number, timeCode: number): boolean,
+    SetVec3f(x: number, y: number, z: number, timeCode: number): boolean,
+    SetVec3d(x: number, y: number, z: number, timeCode: number): boolean,
+    SetMatrix4d(m00: number, m01: number, m02: number, m03: number, m10: number, m11: number, m12: number, m13: number, m20: number, m21: number, m22: number, m23: number, m30: number, m31: number, m32: number, m33: number, timeCode: number): boolean,
+}
+
+declare type USDRelationship = {
+    IsValid(): boolean,
+    GetName(): string,
+    GetPath(): string,
+    GetAllMetadata(): Record<string, string>,
+    GetMetadataString(key: string): string,
+    HasAuthoredMetadata(key: string): boolean,
+    GetPropertyStack(timeCode: number): USDSpecStack,
+    GetPropertyStackWithLayerOffsets(timeCode: number): USDSpecStack,
+    GetTargets(): StringVector,
+    AddTarget(path: string): boolean,
+    ClearTargets(removeSpec: boolean): boolean,
+}
+
+declare type USDPrim = {
+    IsValid(): boolean,
+    GetName(): string,
+    GetPath(): string,
+    GetTypeName(): string,
+    GetDisplayName(): string,
+    GetAllMetadata(): Record<string, string>,
+    GetMetadataString(key: string): string,
+    HasAuthoredMetadata(key: string): boolean,
+    GetSpecifier(): string,
+    IsActive(): boolean,
+    SetActive(active: boolean): boolean,
+    ApplyAPI(schemaIdentifier: string): boolean,
+    IsDefined(): boolean,
+    IsAbstract(): boolean,
+    IsInstance(): boolean,
+    IsInPrototype(): boolean,
+    IsPrototype(): boolean,
+    IsLoaded(): boolean,
+    HasAuthoredPayloads(): boolean,
+    HasAuthoredReferences(): boolean,
+    HasAuthoredInherits(): boolean,
+    HasAuthoredSpecializes(): boolean,
+    HasAuthoredInstanceable(): boolean,
+    Load(): MaybePromise<void>,
+    Unload(): MaybePromise<void>,
+    AddPayload(assetPath: string, primPath: string): boolean,
+    GetParent(): USDPrim,
+    GetChildren(): USDPrimVector,
+    GetAttributes(): USDAttributeVector,
+    GetRelationships(): USDRelationshipVector,
+    GetPropertyNames(): StringVector,
+    GetPrimStack(): USDSpecStack,
+    GetPrimStackWithLayerOffsets(): USDSpecStack,
+    GetPrimIndex(): USDPrimIndex,
+    GetCompositionArcs(): USDCompositionArc[],
+    GetAttribute(name: string): USDAttribute,
+    CreateAttribute(name: string, typeName: string, custom: boolean): USDAttribute,
+    GetRelationship(name: string): USDRelationship,
+    CreateRelationship(name: string, custom: boolean): USDRelationship,
+    AddVariant(variantSetName: string, variantName: string): boolean,
+    SetVariantSelection(variantSetName: string, variantName: string): MaybePromise<boolean>,
+    GetVariantSelection(variantSetName: string): string,
+    ClearVariantSelection(variantSetName: string): boolean,
+    BlockVariantSelection(variantSetName: string): boolean,
+    GetVariantSetNames(): StringVector,
+    GetVariantNames(variantSetName: string): StringVector,
+    DefinePrimInVariant(variantSetName: string, variantName: string, path: string, typeName: string): USDPrim,
+}
+
 declare type USDStage = {
+    GetRootLayer(): USDLayer,
+    GetPseudoRoot(): USDPrim,
+    GetPrimAtPath(path: string): USDPrim,
+    DefinePrim(path: string, typeName: string): USDPrim,
+    Traverse(): USDPrimVector,
+    TraverseAll(): USDPrimVector,
+    GetLayerStack(includeSessionLayers: boolean): USDLayerInfo[],
+    GetUsedLayers(includeClipLayers: boolean): USDLayerInfo[],
+    GetCompositionErrors(): string[],
+    RegisterObjectsChanged(callback: (notice: USDObjectsChangedNotice) => void): number,
+    RevokeObjectsChanged(listenerId: number): boolean,
     GetStartTimeCode(): number,
     GetEndTimeCode(): number,
     GetTimeCodesPerSecond(): number,
+    SetStartTimeCode(timeCode: number): void,
+    SetEndTimeCode(timeCode: number): void,
+    SetTimeCodesPerSecond(timeCodesPerSecond: number): void,
     GetUpAxis(): number,
+    SetUpAxis(upAxis: string): boolean,
+    Export(path: string): boolean,
+    ExportToString(): string,
 }
 
 declare type HdWebSyncDriver = {
     getFile: (path: string, cb: (loadedFile: ArrayBufferLike) => void) => void,
-    GetStage: () => USDStage,
+    HasStage(): boolean,
+    GetStage(): USDStage,
+    GetStageUpAxis(): number,
+    GetStageStartTimeCode(): number,
+    GetStageEndTimeCode(): number,
+    GetStageTimeCodesPerSecond(): number,
+    SetIncludedPurposes(includedPurposes: string[]): void,
     SetTime(timecode: number): void,
     GetTime(): number,
-    Draw(): void,
+    Draw(): MaybePromise<void>,
+    Repopulate(): MaybePromise<void>,
 
     /** ??? */
     clone(): HdWebSyncDriver,
@@ -61,6 +342,16 @@ export type GetUsdModuleOptions = {
     getPreloadedPackage?: (file: string, size: number) => ArrayBuffer | null,
     setStatus?: (status: string) => void,
     onDownloadProgress?: (downloaded: number, total: number) => void,
+    onAssetFetchProgress?: (progress: {
+        url: string,
+        state: "start" | "progress" | "done" | "error" | string,
+        loaded: number,
+        total: number,
+        active: number,
+        loadedTotal: number,
+        totalBytes: number,
+        error?: string,
+    }) => void,
     /** Returns a transferable object that can be resolved to an ArrayBuffer, 
      *  or an URL that can be fetched to get an ArrayBuffer.
     */
@@ -78,5 +369,7 @@ export type GetUsdModuleOptions = {
  * ```
  */
 export function getUsdModule(opts?: GetUsdModuleOptions): Promise<USD>;
+export function getOpenUsdBuildInfo(USD: USD): OpenUsdBuildInfo;
+export function loadOpenUsdBuildInfo(opts?: GetUsdModuleOptions): Promise<OpenUsdBuildInfo>;
 
-export type USDRoot = {}
+export type USDRoot = {}

package/src/types/create.three.d.ts

@@ -1,8 +1,15 @@
-import { Scene } from "three"
-import { HdWebSyncDriver, USD } from ".."
+import { Object3D } from "three"
+import { HdWebSyncDriver, USD, USDStage } from ".."
 
 export declare type HydraFile = File & { path: string };
 
+export declare type NeedleThreeHydraStageMetadata = {
+    upAxis: string,
+    startTimeCode: number,
+    endTimeCode: number,
+    timeCodesPerSecond: number,
+}
+
 export declare type createThreeHydraConfig = {
 
     debug?: boolean,
@@ -34,7 +41,43 @@ export declare type createThreeHydraConfig = {
      * Files to be loaded into the virtual file system.
      * The first file will be loaded as the root file, others will be loaded as dependencies.
      */
-    files: Array<HydraFile>,
+    files?: Array<HydraFile>,
+
+    /**
+     * USD geometry purposes to include in the Hydra render pass.
+     * Defaults to ["default", "render"].
+     */
+    includedPurposes?: Array<"default" | "render" | "proxy" | "guide" | string>,
+
+    /**
+     * Add Three.js helper objects for USD cameras and lights.
+     * The cameras and lights themselves are created through Hydra Sprim sync either way.
+     */
+    showScenePrimitiveHelpers?: boolean,
+
+    /**
+     * Add Three.js CameraHelper objects for USD Camera prims.
+     */
+    showCameraHelpers?: boolean,
+
+    /**
+     * Add Three.js light helper objects for USD light prims.
+     */
+    showLightHelpers?: boolean,
+
+    /**
+     * Preview scale used when applying USD Lux intensity values to Three lights.
+     * Defaults to 0.01. USD intensity and exposure are still authored values; this
+     * only controls the helper/demo Three light brightness.
+     */
+    scenePrimitiveLightIntensityScale?: number,
+
+    /**
+     * Include asynchronous material generation and texture assignment in ready().
+     * Defaults to false so stage loading and first draw are not blocked by materials.
+     * Call handle.materialsReady() when you need an explicit material barrier.
+     */
+    waitForMaterials?: boolean,
 }
 
 /**
@@ -48,10 +91,47 @@ export declare type NeedleThreeHydraHandle = {
      * @param dt The delta time since the last update.
      */
     update: (dt: number) => void,
-    /** Call this to update the usd scene immediately.
-     * @param dt The delta time since the last update.
+    /** Set the current USD stage time code and redraw.
+     */
+    setTime: (timeCode: number) => Promise<void>,
+    /** Return the current USD stage time code used by Hydra.
+     */
+    getTime: () => number,
+    /** Enable or disable automatic playback in update().
+     */
+    setPlaying: (playing: boolean) => void,
+    /** Return whether update() is currently advancing stage time.
+     */
+    isPlaying: () => boolean,
+    /** Redraw the current USD stage after imperative stage edits.
+     */
+    refresh: () => Promise<void>,
+    /** Change the visible USD geometry purposes for the current Hydra view.
+     */
+    setIncludedPurposes: (includedPurposes: Array<"default" | "render" | "proxy" | "guide" | string>) => Promise<void>,
+    /** Rebuild Hydra population for the current USD stage after composition edits.
+     */
+    repopulate: () => Promise<void>,
+    /** Run an imperative USD stage edit after the current draw settles, then repopulate and redraw.
+     */
+    editStage: <T>(callback: (stage: USDStage, driver: HdWebSyncDriver) => T | Promise<T>) => Promise<T | undefined>,
+    /** Resolves after the initial Hydra draw has settled.
+     * If createThreeHydra was called with waitForMaterials, also waits for
+     * asynchronous material generation and texture assignment.
+     */
+    ready: () => Promise<void>,
+    /** Resolves when asynchronous material generation and texture assignment have settled.
+     */
+    materialsReady: () => Promise<void>,
+    /** Returns lightweight delegate diagnostics for smoke tests and debugging.
+     */
+    diagnostics: () => Record<string, unknown>,
+    /** Returns root-stage metadata captured before the first Hydra draw.
+     */
+    stageMetadata: () => NeedleThreeHydraStageMetadata,
+    /** Dispose the Three Hydra delegate.
      */
-    dispose: () => void,
+    dispose: () => Promise<void>,
 }
 
 export declare class USDLoadingManager {
@@ -62,4 +142,4 @@ export declare class USDLoadingManager {
 /**
  * Creates a new three.js hydra handle.
  */
-export function createThreeHydra(config: createThreeHydraConfig): Promise<NeedleThreeHydraHandle>
+export function createThreeHydra(config: createThreeHydraConfig): Promise<NeedleThreeHydraHandle>

package/src/types/hydra.d.ts

@@ -1,5 +1,5 @@
 import { Object3D, Texture } from 'three';
-import { HdWebSyncDriver } from './bindings';
+import { HdWebSyncDriver, USD } from './bindings';
 
 export class hydraDelegate { }
 
@@ -17,7 +17,13 @@ export const consoleRenderDelegate: hydraDelegate = {}
 
 export type threeJsRenderDelegateConfig = {
     driver: () => HdWebSyncDriver,
+    USD?: USD,
     usdRoot: Object3D,
+    scenePrimitiveRoot?: Object3D,
+    showScenePrimitiveHelpers?: boolean,
+    showCameraHelpers?: boolean,
+    showLightHelpers?: boolean,
+    scenePrimitiveLightIntensityScale?: number,
     /** Paths for resolving textures */
     paths?: string[],
     /** @deprecated */
@@ -26,7 +32,3 @@ export type threeJsRenderDelegateConfig = {
 export class threeJsRenderDelegate extends hydraDelegate {
     constructor(path: string, config: threeJsRenderDelegateConfig)
 }
-
-
-
-

package/src/types/plugins.d.ts

@@ -2,8 +2,15 @@
 
 export type PluginContext = {
     debug?: boolean,
+    /**
+     * Include asynchronous material generation and texture assignment in the
+     * Hydra handle's ready() promise. Defaults to false.
+     */
+    waitForMaterials?: boolean,
     getFiles: () => Array<import("../types").HydraFile>
 }
 
 
 export declare function addPluginForNeedleEngine(options: PluginContext): Promise<(() => void)>;
+
+export declare function getHydraHandleFromNeedleEngineAsset(asset: unknown): import("../types").NeedleThreeHydraHandle | null;