@needle-tools/gltf-progressive 3.4.0-rc → 4.0.0-alpha

package/lib/extension.model.d.ts

@@ -1,33 +0,0 @@
-type NEEDLE_progressive_model_LOD = {
-    /** path */
-    path: string;
-    hash?: string;
-};
-/** Base NEEDLE_progressive extension format. */
-export type NEEDLE_progressive_ext = {
-    /** id of the asset the lods belong to */
-    guid: string;
-    /** available lod level */
-    lods: Array<NEEDLE_progressive_model_LOD>;
-};
-/** Texture LOD extension */
-export type NEEDLE_ext_progressive_texture = NEEDLE_progressive_ext & {
-    lods: Array<NEEDLE_progressive_model_LOD & {
-        width: number;
-        height: number;
-    }>;
-};
-/** Mesh LOD extension */
-export type NEEDLE_ext_progressive_mesh = NEEDLE_progressive_ext & {
-    lods: Array<NEEDLE_progressive_model_LOD & {
-        indexCount: number;
-        vertexCount: number;
-        /** Density per primitive */
-        densities: number[] | undefined;
-        /** @deprecated Use densities with the primitive index */
-        density: number;
-    }>;
-    /** @deprecated Removed */
-    density: number;
-};
-export {};

package/lib/extension.model.js

@@ -1 +0,0 @@
-export {};

package/lib/index.d.ts

@@ -1,22 +0,0 @@
-export { version as VERSION } from "./version.js";
-export * from "./extension.js";
-export * from "./plugins/index.js";
-export { LODsManager, type LOD_Results } from "./lods.manager.js";
-export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
-export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
-import { WebGLRenderer } from "three";
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
-import { SmartLoadingHints } from "./loaders.js";
-declare type UseNeedleGLTFProgressiveOptions = {
-    /**
-     * When set to true the LODs manager will automatically be enabled
-     */
-    enableLODsManager?: boolean;
-    /**
-     * Smart loading hints can be used by needle infrastructure to deliver assets optimized for a specific usecase.
-     */
-    hints?: Omit<SmartLoadingHints, "progressive">;
-};
-/** @deprecated Use `useNeedleProgressive(loader, renderer)` - this method will be removed in gltf-progressive 4 */
-export declare function useNeedleProgressive(url: string, renderer: WebGLRenderer, loader: GLTFLoader, opts?: UseNeedleGLTFProgressiveOptions): any;
-export declare function useNeedleProgressive(loader: GLTFLoader, renderer: WebGLRenderer, opts?: UseNeedleGLTFProgressiveOptions): any;

package/lib/index.js

@@ -1,87 +0,0 @@
-export { version as VERSION } from "./version.js";
-export * from "./extension.js";
-export * from "./plugins/index.js";
-export { LODsManager } from "./lods.manager.js";
-export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
-export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
-import { addDracoAndKTX2Loaders, configureLoader, createLoaders } from "./loaders.js";
-import { NEEDLE_progressive } from "./extension.js";
-import { LODsManager } from "./lods.manager.js";
-/** Use this function to enable progressive loading of gltf models.
- * @param url The url of the gltf model.
- * @param renderer The renderer of the scene.
- * @param loader The gltf loader.
- * @param opts Options.
- * @returns The LODsManager instance.
- *
- * @example Usage with vanilla three.js:
- * ```ts
- * const url = 'https://yourdomain.com/yourmodel.glb'
- * const loader = new GLTFLoader()
- * useNeedleProgressive(url, renderer, loader)
- * ```
- *
- * @example Usage with react-three-fiber:
- * ```ts
- *  const url = 'https://yourdomain.com/yourmodel.glb'
- * const { scene } = useGLTF(url, false, false, (loader) => {
- *   useNeedleGLTFProgressive(url, gl, loader)
- * })
- * return <primitive object={scene} />
- * ```
- */
-export function useNeedleProgressive(...args) {
-    let url;
-    let renderer;
-    let loader;
-    let opts;
-    switch (args.length) {
-        case 2:
-            [loader, renderer] = args;
-            opts = {};
-            break;
-        case 3:
-            [loader, renderer, opts] = args;
-            break;
-        case 4: // legacy
-            [url, renderer, loader, opts] = args;
-            break;
-        default:
-            throw new Error("Invalid arguments");
-    }
-    createLoaders(renderer);
-    addDracoAndKTX2Loaders(loader);
-    configureLoader(loader, {
-        progressive: true,
-        ...opts?.hints,
-    });
-    loader.register(p => new NEEDLE_progressive(p));
-    const lod = LODsManager.get(renderer);
-    if (opts?.enableLODsManager !== false) {
-        lod.enable();
-    }
-    return lod;
-}
-/** Modelviewer */
-import { patchModelViewer } from "./plugins/modelviewer.js";
-patchModelViewer();
-import { getRaycastMesh, isSSR, useRaycastMeshes } from "./utils.js";
-if (!isSSR) {
-    const global = {
-        gltfProgressive: {
-            useNeedleProgressive,
-            LODsManager,
-            configureLoader,
-            getRaycastMesh,
-            useRaycastMeshes,
-        }
-    };
-    if (!globalThis["Needle"]) {
-        globalThis["Needle"] = global;
-    }
-    else {
-        for (const key in global) {
-            globalThis["Needle"][key] = global[key];
-        }
-    }
-}

package/lib/loaders.d.ts

@@ -1,48 +0,0 @@
-import { WebGLRenderer } from 'three';
-import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
-/**
- * Return the current loader configuration.
- * These paths can be changed using `setDracoDecoderLocation` and `setKTX2TranscoderLocation`.
- */
-export declare const GET_LOADER_LOCATION_CONFIG: () => {
-    dracoDecoderPath: string;
-    ktx2TranscoderPath: string;
-};
-/**
- * Set the location of the Draco decoder. If a draco loader has already been created, it will be updated.
- * @default 'https://www.gstatic.com/draco/versioned/decoders/1.5.7/'
- */
-export declare function setDracoDecoderLocation(location: string): void;
-/**
- * Set the location of the KTX2 transcoder. If a KTX2 loader has already been created, it will be updated.
- * @default 'https://www.gstatic.com/basis-universal/versioned/2021-04-15-ba1c3e4/'
- */
-export declare function setKTX2TranscoderLocation(location: string): void;
-/**
- * Create loaders/decoders for Draco, KTX2 and Meshopt to be used with GLTFLoader.
- * @param renderer - Provide a renderer to detect KTX2 support.
- * @returns The loaders/decoders.
- */
-export declare function createLoaders(renderer: WebGLRenderer | null): {
-    dracoLoader: DRACOLoader;
-    ktx2Loader: KTX2Loader;
-    meshoptDecoder: {
-        supported: boolean;
-        ready: Promise<void>;
-        decodeVertexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, filter?: string) => void;
-        decodeIndexBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeIndexSequence: (target: Uint8Array, count: number, size: number, source: Uint8Array) => void;
-        decodeGltfBuffer: (target: Uint8Array, count: number, size: number, source: Uint8Array, mode: string, filter?: string) => void;
-    };
-};
-export declare function addDracoAndKTX2Loaders(loader: GLTFLoader): void;
-/**
- * Smart loading hints can be used by needle infrastructure to deliver assets optimized for a specific usecase.
- */
-export type SmartLoadingHints = {
-    progressive?: boolean;
-    usecase?: "product";
-};
-export declare function configureLoader(loader: GLTFLoader, opts: SmartLoadingHints): void;

package/lib/loaders.js

@@ -1,161 +0,0 @@
-import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
-import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
-let DEFAULT_DRACO_DECODER_LOCATION = 'https://www.gstatic.com/draco/versioned/decoders/1.5.7/';
-let DEFAULT_KTX2_TRANSCODER_LOCATION = "https://cdn.needle.tools/static/three/0.179.1/basis2/"; // 'https://www.gstatic.com/basis-universal/versioned/2021-04-15-ba1c3e4/';
-const defaultDraco = DEFAULT_DRACO_DECODER_LOCATION;
-const defaultKTX2 = DEFAULT_KTX2_TRANSCODER_LOCATION;
-// #region Online check
-const _remoteDracoDecoderUrl = new URL(DEFAULT_DRACO_DECODER_LOCATION + "draco_decoder.js");
-// if (typeof window !== "undefined") {
-//     if (!window.navigator.onLine) {
-//         // check if the default values have been changed by the user. 
-//         // If they didnt change / the default paths are not reachable, fall back to local versions
-//         if (DEFAULT_DRACO_DECODER_LOCATION === defaultDraco)
-//             DEFAULT_DRACO_DECODER_LOCATION = "./include/draco/";
-//         if (DEFAULT_KTX2_TRANSCODER_LOCATION === defaultKTX2)
-//             DEFAULT_KTX2_TRANSCODER_LOCATION = "./include/ktx2/";
-//     }
-//     prepareLoaders();
-// }
-// Avoid cache busting - if we don't do this chrome will clear the fully cached file (potentially)
-_remoteDracoDecoderUrl.searchParams.append("range", "true");
-fetch(_remoteDracoDecoderUrl, {
-    method: "GET",
-    headers: {
-        "Range": "bytes=0-1"
-    }
-})
-    .catch(_ => {
-    console.debug(`Failed to fetch remote Draco decoder from ${DEFAULT_DRACO_DECODER_LOCATION} (offline: ${(typeof navigator !== "undefined") ? navigator.onLine : "unknown"})`);
-    // check if the default values have been changed by the user. 
-    // If they didnt change / the default paths are not reachable, fall back to local versions
-    if (DEFAULT_DRACO_DECODER_LOCATION === defaultDraco) {
-        setDracoDecoderLocation("./include/draco/");
-    }
-    if (DEFAULT_KTX2_TRANSCODER_LOCATION === defaultKTX2) {
-        setKTX2TranscoderLocation("./include/ktx2/");
-    }
-})
-    .finally(() => {
-    prepareLoaders();
-});
-// #region Loader Configuration
-/**
- * Return the current loader configuration.
- * These paths can be changed using `setDracoDecoderLocation` and `setKTX2TranscoderLocation`.
- */
-export const GET_LOADER_LOCATION_CONFIG = () => ({
-    dracoDecoderPath: DEFAULT_DRACO_DECODER_LOCATION,
-    ktx2TranscoderPath: DEFAULT_KTX2_TRANSCODER_LOCATION
-});
-/**
- * Set the location of the Draco decoder. If a draco loader has already been created, it will be updated.
- * @default 'https://www.gstatic.com/draco/versioned/decoders/1.5.7/'
- */
-export function setDracoDecoderLocation(location) {
-    DEFAULT_DRACO_DECODER_LOCATION = location;
-    if (dracoLoader && dracoLoader[$dracoDecoderPath] != DEFAULT_DRACO_DECODER_LOCATION) {
-        console.debug("Updating Draco decoder path to " + location);
-        dracoLoader[$dracoDecoderPath] = DEFAULT_DRACO_DECODER_LOCATION;
-        dracoLoader.setDecoderPath(DEFAULT_DRACO_DECODER_LOCATION);
-        dracoLoader.preload();
-    }
-    else {
-        console.debug("Setting Draco decoder path to " + location);
-    }
-}
-/**
- * Set the location of the KTX2 transcoder. If a KTX2 loader has already been created, it will be updated.
- * @default 'https://www.gstatic.com/basis-universal/versioned/2021-04-15-ba1c3e4/'
- */
-export function setKTX2TranscoderLocation(location) {
-    DEFAULT_KTX2_TRANSCODER_LOCATION = location;
-    // if set from <needle-engine> 
-    if (ktx2Loader && ktx2Loader.transcoderPath != DEFAULT_KTX2_TRANSCODER_LOCATION) {
-        console.debug("Updating KTX2 transcoder path to " + location);
-        ktx2Loader.setTranscoderPath(DEFAULT_KTX2_TRANSCODER_LOCATION);
-        ktx2Loader.init();
-    }
-    else {
-        console.debug("Setting KTX2 transcoder path to " + location);
-    }
-}
-/**
- * Create loaders/decoders for Draco, KTX2 and Meshopt to be used with GLTFLoader.
- * @param renderer - Provide a renderer to detect KTX2 support.
- * @returns The loaders/decoders.
- */
-export function createLoaders(renderer) {
-    prepareLoaders();
-    if (renderer) {
-        ktx2Loader.detectSupport(renderer);
-    }
-    else if (renderer !== null)
-        console.warn("No renderer provided to detect ktx2 support - loading KTX2 textures might fail");
-    return { dracoLoader, ktx2Loader, meshoptDecoder };
-}
-export function addDracoAndKTX2Loaders(loader) {
-    if (!loader.dracoLoader)
-        loader.setDRACOLoader(dracoLoader);
-    if (!loader.ktx2Loader)
-        loader.setKTX2Loader(ktx2Loader);
-    if (!loader.meshoptDecoder)
-        loader.setMeshoptDecoder(meshoptDecoder);
-}
-// #region internal
-const $dracoDecoderPath = Symbol("dracoDecoderPath");
-let dracoLoader;
-let meshoptDecoder;
-let ktx2Loader;
-/** Used to create and load loaders */
-function prepareLoaders() {
-    if (!dracoLoader) {
-        dracoLoader = new DRACOLoader();
-        dracoLoader[$dracoDecoderPath] = DEFAULT_DRACO_DECODER_LOCATION;
-        dracoLoader.setDecoderPath(DEFAULT_DRACO_DECODER_LOCATION);
-        dracoLoader.setDecoderConfig({ type: 'js' });
-        dracoLoader.preload();
-    }
-    if (!ktx2Loader) {
-        ktx2Loader = new KTX2Loader();
-        ktx2Loader.setTranscoderPath(DEFAULT_KTX2_TRANSCODER_LOCATION);
-        ktx2Loader.init();
-    }
-    if (!meshoptDecoder) {
-        meshoptDecoder = MeshoptDecoder;
-    }
-}
-const gltfLoaderConfigurations = new WeakMap();
-export function configureLoader(loader, opts) {
-    let config = gltfLoaderConfigurations.get(loader);
-    if (config) {
-        config = Object.assign(config, opts);
-    }
-    else {
-        config = opts;
-    }
-    gltfLoaderConfigurations.set(loader, config);
-}
-const originalLoadFunction = GLTFLoader.prototype.load;
-function onLoad(...args) {
-    const config = gltfLoaderConfigurations.get(this);
-    let url_str = args[0];
-    const url = new URL(url_str, window.location.href);
-    if (url.hostname.endsWith("needle.tools")) {
-        const progressive = config?.progressive !== undefined ? config.progressive : true;
-        const usecase = config?.usecase ? config.usecase : "default";
-        if (progressive) {
-            this.requestHeader["Accept"] = `*/*;progressive=allowed;usecase=${usecase}`;
-        }
-        else {
-            this.requestHeader["Accept"] = `*/*;usecase=${usecase}`;
-        }
-        url_str = url.toString();
-    }
-    args[0] = url_str;
-    const res = originalLoadFunction?.call(this, ...args);
-    return res;
-}
-GLTFLoader.prototype.load = onLoad;

package/lib/lods.debug.d.ts

@@ -1,4 +0,0 @@
-import { Material } from "three";
-export declare const debug: string | boolean;
-export declare let debug_OverrideLodLevel: number;
-export declare function applyDebugSettings(material: Material | Array<Material>): void;

package/lib/lods.debug.js

@@ -1,43 +0,0 @@
-import { getParam } from "./utils.internal.js";
-export const debug = getParam("debugprogressive");
-let debug_RenderWireframe = undefined;
-export let debug_OverrideLodLevel = -1; // -1 is automatic
-if (debug) {
-    let maxLevel = 6;
-    function debugToggleProgressive() {
-        debug_OverrideLodLevel += 1;
-        if (debug_OverrideLodLevel >= maxLevel) {
-            debug_OverrideLodLevel = -1;
-        }
-        console.log(`Toggle LOD level [${debug_OverrideLodLevel}]`);
-    }
-    window.addEventListener("keyup", evt => {
-        if (evt.key === "p")
-            debugToggleProgressive();
-        if (evt.key === "w") {
-            debug_RenderWireframe = !debug_RenderWireframe;
-            console.log(`Toggle wireframe [${debug_RenderWireframe}]`);
-        }
-        const pressedNumber = parseInt(evt.key);
-        if (!isNaN(pressedNumber) && pressedNumber >= 0) {
-            debug_OverrideLodLevel = pressedNumber;
-            console.log(`Set LOD level to [${debug_OverrideLodLevel}]`);
-        }
-    });
-}
-export function applyDebugSettings(material) {
-    if (!debug)
-        return;
-    if (debug_RenderWireframe !== undefined) {
-        if (Array.isArray(material)) {
-            for (const mat of material) {
-                applyDebugSettings(mat);
-            }
-        }
-        else if (material) {
-            if ("wireframe" in material) {
-                material.wireframe = debug_RenderWireframe === true;
-            }
-        }
-    }
-}

package/lib/lods.manager.d.ts

@@ -1,165 +0,0 @@
-import { Camera, Material, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
-import { NEEDLE_progressive_plugin } from "./plugins/plugin.js";
-import { PromiseGroupOptions } from "./lods.promise.js";
-export type LODManagerContext = {
-    engine: "three" | "needle-engine" | "model-viewer" | "react-three-fiber" | "unknown";
-};
-export declare type LOD_Results = {
-    mesh_lod: number;
-    texture_lod: number;
-};
-declare type LODChangedEventListener = (args: {
-    type: "mesh" | "texture";
-    level: number;
-    object: Object3D | Material | Texture;
-}) => void;
-/**
- * The LODsManager class is responsible for managing the LODs and progressive assets in the scene. It will automatically update the LODs based on the camera position, screen coverage and mesh density of the objects.
- * It must be enabled by calling the `enable` method.
- *
- * Instead of using the LODs manager directly you can also call `useNeedleProgressive` to enable progressive loading for a GLTFLoader
- *
- * ### Plugins
- * Use {@link LODsManager.addPlugin} to add a plugin to the LODsManager. A plugin can be used to hook into the LOD update process and modify the LOD levels or perform other actions.
- *
- * @example Adding a LODsManager to a Three.js scene:
- * ```ts
- * import { LODsManager } from "@needle-tools/gltf-progressive";
- * import { WebGLRenderer, Scene, Camera, Mesh } from "three";
- *
- * const renderer = new WebGLRenderer();
- * const lodsManager = LODsManager.get(renderer);
- * lodsManager.enable();
- * ```
- *
- * @example Using the LODsManager with a GLTFLoader:
- * ```ts
- * import { useNeedleProgressive } from "@needle-tools/gltf-progressive";
- * import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
- *
- * const url = 'https://yourdomain.com/yourmodel.glb';
- * const loader = new GLTFLoader();
- * const lodsManager = useNeedleProgressive(url, renderer, loader);
- * ```
- */
-export declare class LODsManager {
-    #private;
-    /**
-     * Assign a function to draw debug lines for the LODs. This function will be called with the start and end position of the line and the color of the line when the `debugprogressive` query parameter is set.
-     */
-    static debugDrawLine?: (a: Vector3, b: Vector3, color: number) => void;
-    /** @internal */
-    static getObjectLODState(object: Object3D): LOD_state | undefined;
-    static addPlugin(plugin: NEEDLE_progressive_plugin): void;
-    static removePlugin(plugin: NEEDLE_progressive_plugin): void;
-    /**
-     * Gets the LODsManager for the given renderer. If the LODsManager does not exist yet, it will be created.
-     * @param renderer The renderer to get the LODsManager for.
-     * @returns The LODsManager instance.
-     */
-    static get(renderer: WebGLRenderer, context?: LODManagerContext): LODsManager;
-    readonly renderer: WebGLRenderer;
-    private readonly context;
-    private readonly projectionScreenMatrix;
-    /** @deprecated use static `LODsManager.addPlugin()` method. This getter will be removed in later versions */
-    get plugins(): NEEDLE_progressive_plugin[];
-    /**
-     * Force override the LOD level for all objects (meshes + textures) rendered in the scene
-     * @default undefined automatically calculate LOD level
-     */
-    overrideLodLevel: undefined | number;
-    /**
-     * The target triangle density is the desired max amount of triangles on screen when the mesh is filling the screen.
-     * @default 200_000
-     */
-    targetTriangleDensity: number;
-    /**
-     * The interval in frames to automatically update the bounds of skinned meshes.
-     * Set to 0 or a negative value to disable automatic bounds updates.
-     * @default 30
-     */
-    skinnedMeshAutoUpdateBoundsInterval: number;
-    /**
-     * The update interval in frames. If set to 0, the LODs will be updated every frame. If set to 2, the LODs will be updated every second frame, etc.
-     * @default "auto"
-     */
-    updateInterval: "auto" | number;
-    /**
-     * If set to true, the LODsManager will not update the LODs.
-     * @default false
-     */
-    pause: boolean;
-    /**
-     * When set to true the LODsManager will not update the LODs. This can be used to manually update the LODs using the `update` method.
-     * Otherwise the LODs will be updated automatically when the renderer renders the scene.
-     * @default false
-     */
-    manual: boolean;
-    private readonly _newPromiseGroups;
-    private _promiseGroupIds;
-    /**
-     * Call to await LODs loading during the next render cycle.
-     */
-    awaitLoading(opts?: PromiseGroupOptions): Promise<{
-        cancelled: boolean;
-        awaited_count: number;
-        resolved_count: number;
-    }>;
-    private _postprocessPromiseGroups;
-    private readonly _lodchangedlisteners;
-    addEventListener(evt: "changed", listener: LODChangedEventListener): void;
-    removeEventListener(evt: "changed", listener: LODChangedEventListener): void;
-    private constructor();
-    private _fpsBuffer;
-    /**
-     * Enable the LODsManager. This will replace the render method of the renderer with a method that updates the LODs.
-     */
-    enable(): void;
-    disable(): void;
-    update(scene: Scene, camera: Camera): void;
-    private onAfterRender;
-    /**
-     * Update LODs in a scene
-     */
-    private internalUpdate;
-    /** Update the LOD levels for the renderer. */
-    private updateLODs;
-    /** Load progressive textures for the given material
-     * @param material the material to load the textures for
-     * @param level the LOD level to load. Level 0 is the best quality, higher levels are lower quality
-     * @returns Promise with true if the LOD was loaded, false if not
-     */
-    private loadProgressiveTextures;
-    /** Load progressive meshes for the given mesh
-     * @param mesh the mesh to load the LOD for
-     * @param index the index of the mesh if it's part of a group
-     * @param level the LOD level to load. Level 0 is the best quality, higher levels are lower quality
-     * @returns Promise with true if the LOD was loaded, false if not
-     */
-    private loadProgressiveMeshes;
-    private readonly _sphere;
-    private readonly _tempBox;
-    private readonly _tempBox2;
-    private readonly tempMatrix;
-    private readonly _tempWorldPosition;
-    private readonly _tempBoxSize;
-    private readonly _tempBox2Size;
-    private static corner0;
-    private static corner1;
-    private static corner2;
-    private static corner3;
-    private static readonly _tempPtInside;
-    private static isInside;
-    private static skinnedMeshBoundsFrameOffsetCounter;
-    private static $skinnedMeshBoundsOffset;
-    private calculateLodLevel;
-}
-declare class LOD_state {
-    frames: number;
-    lastLodLevel_Mesh: number;
-    lastLodLevel_Texture: number;
-    lastScreenCoverage: number;
-    readonly lastScreenspaceVolume: Vector3;
-    lastCentrality: number;
-}
-export {};