@needle-tools/gltf-progressive 1.2.14 → 2.0.0-alpha

package/CHANGELOG.md

@@ -1,164 +1,170 @@
-# Changelog
-All notable changes to this package will be documented in this file.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
-
-## [1.2.14] - 2024-10-06
-- Update README
-
-## [1.2.12] - 2024-09-23
-- Add: `assignTextureLOD` now also accepts mesh as parameter
-- Change: improved `assignTextureLOD` typing
-
-## [1.2.11] - 2024-09-11
-- Fix: draco and KTX decoder path handling when gstatic can not be reached and user set path
-
-## [1.2.10] - 2024-09-10
-- Fix: loading and assigning texture LOD for ShaderMaterial and RawShaderMaterial
-
-## [1.2.9] - 2024-07-29
-- Fix: server side rendering fixes
-
-## [1.2.8] - 2023-07-19
-- Add: repository url
-
-## [1.2.7] - 2023-07-18
-- Fix: include `type: module`
-
-## [1.2.5] - 2023-07-16
-- Remove: Frustum cull check because we're already operating on the latest renderlist
-
-## [1.2.5-beta] - 2023-07-09
-- Change: Update skinned mesh bounding box every 30 frames using the lowres mesh version
-
-## [1.2.4-beta.1] - 2023-07-09
-- Add: LODsManager `manual` property which can be used to manually update the LODs in the scene by calling `LODsManager.update(scene, camera)`
-- Fix: updating LODs in WebXR
-
-## [1.2.4-beta] - 2023-07-05
-- Change: `createLoaders` now returns created loaders and decoders to be re-used
-
-## [1.2.3-beta] - 2023-07-04
-- Add: support for transmissive objects
-
-## [1.2.3-alpha.3] - 2023-07-01
-- Add: prevent loading highres textures when user has enabled data-save mode
-
-## [1.2.3-alpha.2] - 2023-06-27
-- Fix: error caused by parser associations containing `undefined` value
-
-## [1.2.3-alpha.1] - 2023-06-25
-- Internal: rename `setRaycastMesh` to `registerRaycastMesh`
-
-## [1.2.3-alpha] - 2023-06-24
-- Change: automatically change LOD update interval based on framerate
-
-## [1.2.2-alpha.4] - 2023-06-20
-- Add: Register version in global "GLTF_PROGRESSIVE_VERSION" variable
-- Add: `<model-viewer>` elements added document at any time are now properly registered 
-- Fix: LOD updates for multiple `<model-viewer>` elements
-- Fix: Initial render tick for a few frames for `<model-viewer>` to trigger LOD updates when the model-viewer element is not animated or interacted with
-- Change: `<model-viewer>` elements will fetch a slightly higher texture LOD
-
-## [1.2.1-alpha.4] - 2023-06-19
-- Fix: SkinnedMesh bounds calculation
-
-## [1.2.1-alpha.3] - 2023-06-15
-- update the README
-
-## [1.2.1-alpha.2] - 2023-06-15
-- fix: Ortographic camera causing LODs being falsely updated
-- fix: regression introduced in 1.2.1-alpha
-- fix: error when trying to load a LOD glTF directly 
-- fix: issues caused by instanceof in local development environments
-
-## [1.2.0-alpha.9] - 2023-06-13
-- fix: issue where skinned mesh matrix was falsely applied to calculate screen size
-- fix: use bounding box from SkinnedMesh object
-
-## [1.2.0-alpha.6] - 2023-06-12
-- fix: minor bug where opened glTF has `NEEDLE_progressive` extension but no lods array because the glTF is a LOD variant
-
-## [1.2.0-alpha.5] - 2023-06-10
-- fix: safeguard when `registerMesh` or `registerTexture` are being called with invalid data
-- examples: update vanilla threejs example
-
-## [1.2.0-alpha.4] - 2023-06-07
-- add: `useRaycastMeshes` method:
-  ```ts
-    // call to enable raycasting with low poly raycast meshes
-    // this can be done once in your project
-    useRaycastMeshes(true);
-    
-    // then use the raycaster as usual
-    const raycaster = new Raycaster();
-    raycaster.setFromCamera(mouse, camera);
-    const intersects = raycaster.intersectObjects(scene.children, true);
-    
-    // call to disable raycasting with low polwy meshes
-    useRaycastMeshes(false);
-  ```
-
-## [1.2.0-alpha.3] - 2023-06-06
-- add: automatically load the highest LOD first to show a slightly better quality level as soon as possible
-- fix: improve Texture LOD selection by taking LOD level height into account
-- fix: correctly assign LOD level information to initially loaded texture
-
-## [1.1.0-alpha.2] - 2023-06-05
-- fix: register LOD information for meshes that don't have associations
-
-## [1.1.0-alpha] - 2023-06-03
-- add: loading of multiple texture LOD levels
-- fix: issue where material LODs where not updated when the material was cloned
-- change: clamp screen coverage when near plane intersects with the object bounds
-- change: skip CubeCamera setup
-- change: handle cases where an object has only texture LODs
-
-## [1.0.0-alpha.19] - 2023-05-31
-- add `LODsManager.plugins` getter 
-
-## [1.0.0-alpha.18] - 2023-05-30
-- update README
-
-## [1.0.0-alpha.16] - 2023-05-29
-- fix: LODs manager now clamps to LOD 0 if the near plane is inside the bounds
-- change: Ignore certain material in lods update loop 
-
-## [1.0.0-alpha.15] - 2023-05-25
-- add: `getRaycastMesh` method
-- add: LODsManager does now expose `targetTriangleDensity`. The target triangle density is the desired max amount of triangles on screen when the mesh is filling the screen. 
-- change: create LODsManager via `LODsManager.get(renderer)`
-
-## [1.0.0-alpha.13] - 2023-05-24
-- fix: modelviewer error when trying to access undefined texture extensions
-
-## [1.0.0-alpha.13] - 2023-05-24
-- add: vanilla three.js example
-- fix: texture LODs losing filter setting
-
-## [1.0.0-alpha.12] - 2023-05-19
-- fix: update LODs when using postprocessing
-
-## [1.0.0-alpha.11] - 2023-05-17
-- add: expose `setDracoDecoderLocation` and `setKTX2TranscoderLocation`
-- fix: allow using draco decoder and ktx2 transcoder from local filepath
-
-## [1.0.0-alpha.10] - 2023-05-07
-- fix: progressive assets are now only updated during the main canvas render call and not e.g. when rendering to a texture
-
-## [1.0.0-alpha.9] - 2023-05-03
-- fix: handle loading of ShaderMaterial for VRM progressive textures
-
-## [1.0.0-alpha.8] - 2023-05-03
-- fix: handle transparent materials
-
-## [1.0.0-alpha.7] - 2023-05-01
-- fix: Handle modelviewer `src` set as property but not as attribute
-- change: Remove sourcemap
-
-## [1.0.0-alpha.6] - 2023-05-01
-- fix: LOD mesh assignment for multi-material meshes (meshes with multiple primitives)
-
-## [1.0.0-alpha.5] - 2023-04-30
+# Changelog
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [2.0.0-alpha] - 2024-12-09
+- Add: `Accept` header options for Needle Cloud requests
+
+## [1.2.15] - 2024-10-21
+- Fix: internal window parameter access causing issue with SSR
+
+## [1.2.13] - 2024-10-06
+- Update README
+
+## [1.2.12] - 2024-09-23
+- Add: `assignTextureLOD` now also accepts mesh as parameter
+- Change: improved `assignTextureLOD` typing
+
+## [1.2.11] - 2024-09-11
+- Fix: draco and KTX decoder path handling when gstatic can not be reached and user set path
+
+## [1.2.10] - 2024-09-10
+- Fix: loading and assigning texture LOD for ShaderMaterial and RawShaderMaterial
+
+## [1.2.9] - 2024-07-29
+- Fix: server side rendering fixes
+
+## [1.2.8] - 2023-07-19
+- Add: repository url
+
+## [1.2.7] - 2023-07-18
+- Fix: include `type: module`
+
+## [1.2.5] - 2023-07-16
+- Remove: Frustum cull check because we're already operating on the latest renderlist
+
+## [1.2.5-beta] - 2023-07-09
+- Change: Update skinned mesh bounding box every 30 frames using the lowres mesh version
+
+## [1.2.4-beta.1] - 2023-07-09
+- Add: LODsManager `manual` property which can be used to manually update the LODs in the scene by calling `LODsManager.update(scene, camera)`
+- Fix: updating LODs in WebXR
+
+## [1.2.4-beta] - 2023-07-05
+- Change: `createLoaders` now returns created loaders and decoders to be re-used
+
+## [1.2.3-beta] - 2023-07-04
+- Add: support for transmissive objects
+
+## [1.2.3-alpha.3] - 2023-07-01
+- Add: prevent loading highres textures when user has enabled data-save mode
+
+## [1.2.3-alpha.2] - 2023-06-27
+- Fix: error caused by parser associations containing `undefined` value
+
+## [1.2.3-alpha.1] - 2023-06-25
+- Internal: rename `setRaycastMesh` to `registerRaycastMesh`
+
+## [1.2.3-alpha] - 2023-06-24
+- Change: automatically change LOD update interval based on framerate
+
+## [1.2.2-alpha.4] - 2023-06-20
+- Add: Register version in global "GLTF_PROGRESSIVE_VERSION" variable
+- Add: `<model-viewer>` elements added document at any time are now properly registered 
+- Fix: LOD updates for multiple `<model-viewer>` elements
+- Fix: Initial render tick for a few frames for `<model-viewer>` to trigger LOD updates when the model-viewer element is not animated or interacted with
+- Change: `<model-viewer>` elements will fetch a slightly higher texture LOD
+
+## [1.2.1-alpha.4] - 2023-06-19
+- Fix: SkinnedMesh bounds calculation
+
+## [1.2.1-alpha.3] - 2023-06-15
+- update the README
+
+## [1.2.1-alpha.2] - 2023-06-15
+- fix: Ortographic camera causing LODs being falsely updated
+- fix: regression introduced in 1.2.1-alpha
+- fix: error when trying to load a LOD glTF directly 
+- fix: issues caused by instanceof in local development environments
+
+## [1.2.0-alpha.9] - 2023-06-13
+- fix: issue where skinned mesh matrix was falsely applied to calculate screen size
+- fix: use bounding box from SkinnedMesh object
+
+## [1.2.0-alpha.6] - 2023-06-12
+- fix: minor bug where opened glTF has `NEEDLE_progressive` extension but no lods array because the glTF is a LOD variant
+
+## [1.2.0-alpha.5] - 2023-06-10
+- fix: safeguard when `registerMesh` or `registerTexture` are being called with invalid data
+- examples: update vanilla threejs example
+
+## [1.2.0-alpha.4] - 2023-06-07
+- add: `useRaycastMeshes` method:
+  ```ts
+    // call to enable raycasting with low poly raycast meshes
+    // this can be done once in your project
+    useRaycastMeshes(true);
+    
+    // then use the raycaster as usual
+    const raycaster = new Raycaster();
+    raycaster.setFromCamera(mouse, camera);
+    const intersects = raycaster.intersectObjects(scene.children, true);
+    
+    // call to disable raycasting with low polwy meshes
+    useRaycastMeshes(false);
+  ```
+
+## [1.2.0-alpha.3] - 2023-06-06
+- add: automatically load the highest LOD first to show a slightly better quality level as soon as possible
+- fix: improve Texture LOD selection by taking LOD level height into account
+- fix: correctly assign LOD level information to initially loaded texture
+
+## [1.1.0-alpha.2] - 2023-06-05
+- fix: register LOD information for meshes that don't have associations
+
+## [1.1.0-alpha] - 2023-06-03
+- add: loading of multiple texture LOD levels
+- fix: issue where material LODs where not updated when the material was cloned
+- change: clamp screen coverage when near plane intersects with the object bounds
+- change: skip CubeCamera setup
+- change: handle cases where an object has only texture LODs
+
+## [1.0.0-alpha.19] - 2023-05-31
+- add `LODsManager.plugins` getter 
+
+## [1.0.0-alpha.18] - 2023-05-30
+- update README
+
+## [1.0.0-alpha.16] - 2023-05-29
+- fix: LODs manager now clamps to LOD 0 if the near plane is inside the bounds
+- change: Ignore certain material in lods update loop 
+
+## [1.0.0-alpha.15] - 2023-05-25
+- add: `getRaycastMesh` method
+- add: LODsManager does now expose `targetTriangleDensity`. The target triangle density is the desired max amount of triangles on screen when the mesh is filling the screen. 
+- change: create LODsManager via `LODsManager.get(renderer)`
+
+## [1.0.0-alpha.13] - 2023-05-24
+- fix: modelviewer error when trying to access undefined texture extensions
+
+## [1.0.0-alpha.13] - 2023-05-24
+- add: vanilla three.js example
+- fix: texture LODs losing filter setting
+
+## [1.0.0-alpha.12] - 2023-05-19
+- fix: update LODs when using postprocessing
+
+## [1.0.0-alpha.11] - 2023-05-17
+- add: expose `setDracoDecoderLocation` and `setKTX2TranscoderLocation`
+- fix: allow using draco decoder and ktx2 transcoder from local filepath
+
+## [1.0.0-alpha.10] - 2023-05-07
+- fix: progressive assets are now only updated during the main canvas render call and not e.g. when rendering to a texture
+
+## [1.0.0-alpha.9] - 2023-05-03
+- fix: handle loading of ShaderMaterial for VRM progressive textures
+
+## [1.0.0-alpha.8] - 2023-05-03
+- fix: handle transparent materials
+
+## [1.0.0-alpha.7] - 2023-05-01
+- fix: Handle modelviewer `src` set as property but not as attribute
+- change: Remove sourcemap
+
+## [1.0.0-alpha.6] - 2023-05-01
+- fix: LOD mesh assignment for multi-material meshes (meshes with multiple primitives)
+
+## [1.0.0-alpha.5] - 2023-04-30
 - initial version

package/README.md

@@ -1,133 +1,131 @@
-# glTF progressive
-
-LOD support on steroids for three.js with one-line integration: Load glTF, GLB or VRM files and get smart and automatic LOD selection loading for meshes and texture. Reduce initial load time and increase performance at the same time.
-
-## Features
-- One line integration in any three.js based engine/project e.g. react-three-fiber, model-viewer, vanilla threejs... (see examples below)
-- Mesh LOD support (works for both regular meshes and skinned meshes)
-- Texture LOD support
-- Smart LOD selection: LOD levels are switched automatically based on a pre-calculated mesh density for deterministic and consistent quality in any situation (VR is also supported)
-- On demand loading: higher qualities are streamed in on demand when objects become visible. This reduces the loading time of websites significantly
-- Low poly LOD meshes can be used for raycasting for smooth interactions with high-poly meshes (see examples below)
-- Tiny dependency-free package (< 10KB gzipped)
-- Cloud generation and loading support via [cloud.needle.tools](https://cloud.needle.tools) for glTF, GLB & VRM assets or use [Needle Engine with Unity or Blender](https://docs.needle.tools/getting-started).
-
-## Examples
-
-Examples are in the `/examples` directory. Live versions can be found in the links below.  
-
-- [Vanilla three.js](https://engine.needle.tools/demos/gltf-progressive/threejs/) - multiple models and animations
-- [React Three Fiber](https://engine.needle.tools/demos/gltf-progressive/r3f/)
-- \<model-viewer\> 
-  - [single \<model-viewer> element](https://engine.needle.tools/demos/gltf-progressive/modelviewer) 
-  - [multiple \<model-viewer> elements](https://engine.needle.tools/demos/gltf-progressive/modelviewer-multiple)
-- [Needle Engine](https://stackblitz.com/edit/needle-engine-gltf-progressive?file=src%2Fmain.ts)
-- [Progressive VRM - 14 MB to 1 MB](https://cloud.needle.tools/view/91b4450/262927895)
-
-**Interactive Examples**:
-- [Stackblitz](https://stackblitz.com/@marwie/collections/gltf-progressive)
-- [Codesandbox](https://codesandbox.io/dashboard/sandboxes/gltf-progressive)
-
-
-<br/>
-<video width="320" controls autoplay src="https://engine.needle.tools/demos/gltf-progressive/video.mp4">
-    <source src="https://engine.needle.tools/demos/gltf-progressive/video.mp4" type="video/mp4">
-</video>
-
-
-## Usage
-
-### react three fiber
-
-Full example in `examples/react-three-fiber`
-
-```ts
-function ChurchModel() {
-  const { gl } = useThree()
-  const url = 'https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb'
-  const { scene } = useGLTF(url, false, false, (loader) => {
-    useNeedleProgressive(url, gl, loader as any)
-  })
-  return <primitive object={scene} />
-}
-```
-
-### threejs (CDN, no bundler)
-
-The full example can be found at `examples/threejs`
-
-```html
-<head>
-    <!-- Add the threejs import map to your HTML head section -->
-    <script type="importmap">
-    {
-        "imports": {
-            "three": "https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js",
-            "three/addons/": "https://cdn.jsdelivr.net/npm/three@latest/examples/jsm/",
-            "three/examples/": "https://cdn.jsdelivr.net/npm/three@latest/examples/",
-            "@needle-engine/gltf-progressive": "https://www.unpkg.com/@needle-tools/gltf-progressive@latest"
-        }
-    }
-    </script>
-</head>
-```
-
-In your script:
-```ts
-const gltfLoader = new GLTFLoader();
-
-const url = "https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb";
-
-// register the progressive loader
-useNeedleProgressive(url, renderer, gltfLoader)
-
-// just call the load method as usual
-gltfLoader.load(url, gltf => {
-    console.log(gltf)
-    scene.add(gltf.scene)
-    gltf.scene.position.y += .95;
-})
-```
-
-
-### \<model-viewer\>
-
-The example can be found in `examples/modelviewer.html`
-
-```html
-<head>
-    <!-- Include threejs import map -->
-    <script type="importmap">
-        {
-            "imports": {
-                "three": "https://unpkg.com/three/build/three.module.js",
-                "three/": "https://unpkg.com/three/"
-            }
-        }
-    </script>
-    <!-- Include gltf-progressive -->
-    <script type="module" src="https://www.unpkg.com/@needle-tools/gltf-progressive@latest"></script>
-    <!-- Include model-viewer -->
-    <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.4.0/model-viewer.min.js"></script>
-</head>
-<body>
-
-    <model-viewer src="https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb" camera-controls auto-rotate></model-viewer>
-    
-</body>
-```
-
-### Needle Engine
-
-[Needle Engine](https://needle.tools) natively supports progressive loading of these glTF files! See [docs.needle.tools](https://docs.needle.tools) for more information. 
-
-
-Use [cloud.needle.tools](https://cloud.needle.tools) to generate LODs for your assets now.
-
-
-# Contact ✒️
-<b>[🌵 needle — tools for creators](https://needle.tools)</b> • 
-[Twitter](https://twitter.com/NeedleTools) • 
-[Discord](https://discord.needle.tools) • 
-[Forum](https://forum.needle.tools)
-
+# glTF progressive
+
+LODs on steroids for glTF, GLB or VRM files with density based loading for meshes or texture for any three.js based project.
+
+## Features
+- One line integration in any three.js based engine/project
+- Mesh LOD support
+- Texture LOD support
+- LOD levels are loaded on demand based on mesh screen density
+- Low poly LOD meshes can easily be used for raycasting for smooth interactions with high-poly meshes
+- Cloud generation and loading support via [cloud.needle.tools](https://cloud.needle.tools) for glTF, GLB & VRM assets
+
+## Examples
+
+Examples are in the `/examples` directory. Live versions can be found in the links below.  
+
+- [Vanilla three.js](https://engine.needle.tools/demos/gltf-progressive/threejs/) - multiple models and animations
+- [React Three Fiber](https://engine.needle.tools/demos/gltf-progressive/r3f/)
+- \<model-viewer\> 
+  - [single \<model-viewer> element](https://engine.needle.tools/demos/gltf-progressive/modelviewer) 
+  - [multiple \<model-viewer> elements](https://engine.needle.tools/demos/gltf-progressive/modelviewer-multiple)
+- [Needle Engine](https://stackblitz.com/edit/needle-engine-gltf-progressive?file=src%2Fmain.ts)
+- [Progressive VRM 14 MB to 1 MB](https://cloud.needle.tools/view/91b4450/262927895)
+
+**Interactive Examples**:
+- [Stackblitz](https://stackblitz.com/@marwie/collections/gltf-progressive)
+- [Codesandbox](https://codesandbox.io/dashboard/sandboxes/gltf-progressive)
+
+
+<br/>
+<video width="320" controls autoplay src="https://engine.needle.tools/demos/gltf-progressive/video.mp4">
+    <source src="https://engine.needle.tools/demos/gltf-progressive/video.mp4" type="video/mp4">
+</video>
+
+
+## Usage
+
+### react three fiber
+
+Full example in `examples/react-three-fiber`
+
+```ts
+function ChurchModel() {
+  const { gl } = useThree()
+  const url = 'https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb'
+  const { scene } = useGLTF(url, false, false, (loader) => {
+    useNeedleProgressive(url, gl, loader as any)
+  })
+  return <primitive object={scene} />
+}
+```
+
+### threejs (CDN, no bundler)
+
+The full example can be found at `examples/threejs`
+
+```html
+<head>
+    <!-- Add the threejs import map to your HTML head section -->
+    <script type="importmap">
+    {
+        "imports": {
+            "three": "https://cdn.jsdelivr.net/npm/three@latest/build/three.module.js",
+            "three/addons/": "https://cdn.jsdelivr.net/npm/three@latest/examples/jsm/",
+            "three/examples/": "https://cdn.jsdelivr.net/npm/three@latest/examples/",
+            "@needle-engine/gltf-progressive": "https://www.unpkg.com/@needle-tools/gltf-progressive@latest"
+        }
+    }
+    </script>
+</head>
+```
+
+In your script:
+```ts
+const gltfLoader = new GLTFLoader();
+
+const url = "https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb";
+
+// register the progressive loader
+useNeedleProgressive(url, renderer, gltfLoader)
+
+// just call the load method as usual
+gltfLoader.load(url, gltf => {
+    console.log(gltf)
+    scene.add(gltf.scene)
+    gltf.scene.position.y += .95;
+})
+```
+
+
+### \<model-viewer\>
+
+The example can be found in `examples/modelviewer.html`
+
+```html
+<head>
+    <!-- Include threejs import map -->
+    <script type="importmap">
+        {
+            "imports": {
+                "three": "https://unpkg.com/three/build/three.module.js",
+                "three/": "https://unpkg.com/three/"
+            }
+        }
+    </script>
+    <!-- Include gltf-progressive -->
+    <script type="module" src="https://www.unpkg.com/@needle-tools/gltf-progressive@latest"></script>
+    <!-- Include model-viewer -->
+    <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.4.0/model-viewer.min.js"></script>
+</head>
+<body>
+
+    <model-viewer src="https://engine.needle.tools/demos/gltf-progressive/assets/church/model.glb" camera-controls auto-rotate></model-viewer>
+    
+</body>
+```
+
+### Needle Engine
+
+[Needle Engine](https://needle.tools) natively supports progressive loading of these glTF files! See [docs.needle.tools](https://docs.needle.tools) for more information. 
+
+
+Use [cloud.needle.tools](https://cloud.needle.tools) to generate LODs for your assets now.
+
+
+# Contact ✒️
+<b>[🌵 needle — tools for creators](https://needle.tools)</b> • 
+[Twitter](https://twitter.com/NeedleTools) • 
+[Discord](https://discord.needle.tools) • 
+[Forum](https://forum.needle.tools)
+