@needle-tools/materialx 1.1.1 → 1.2.0

package/src/materialx.helper.d.ts

@@ -0,0 +1,31 @@
+import * as THREE from 'three';
+
+export interface Callbacks {
+    readonly cacheKey?: string;
+    readonly getTexture: (path: string) => Promise<THREE.Texture | null | void>;
+}
+
+export interface LightData {
+    type: number;
+    position: THREE.Vector3;
+    direction: THREE.Vector3;
+    color: THREE.Color;
+    intensity: number;
+    decay_rate: number;
+    inner_angle: number;
+    outer_angle: number;
+}
+
+export function prepareEnvTexture(texture: THREE.Texture, capabilities: any): THREE.Texture;
+
+export function getLightRotation(): THREE.Matrix4;
+
+export function findLights(doc: any): Array<any>;
+
+export function registerLights(mx: any, genContext: any): Promise<void>;
+
+export function getLightData(lights: Array<THREE.Light>, genContext: any): { lightData: LightData[], lightCount: number };
+
+export function getUniformValues(shaderStage: any, loaders: Callbacks, searchPath: string): Record<string, THREE.Uniform>;
+
+export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMaterial, shaderStage: any): void;

package/src/{materialx.helper.ts → materialx.helper.js}

@@ -4,7 +4,6 @@
 //
 import * as THREE from 'three';
 import { debug, debugUpdate } from './utils.js';
-import { MaterialX } from './materialx.types.js';
 
 const IMAGE_PROPERTY_SEPARATOR = "_";
 const UADDRESS_MODE_SUFFIX = IMAGE_PROPERTY_SEPARATOR + "uaddressmode";
@@ -13,20 +12,19 @@ const FILTER_TYPE_SUFFIX = IMAGE_PROPERTY_SEPARATOR + "filtertype";
 const IMAGE_PATH_SEPARATOR = "/";
 
 /**
- * Initialized the environment texture as MaterialX expects it
+ * Initializes the environment texture as MaterialX expects it
  * @param {THREE.Texture} texture
  * @param {Object} capabilities
  * @returns {THREE.Texture}
  */
 export function prepareEnvTexture(texture, capabilities) {
-    let newTexture = new THREE.DataTexture(texture.image.data, texture.image.width, texture.image.height, texture.format, texture.type);
+    const newTexture = new THREE.DataTexture(texture.image.data, texture.image.width, texture.image.height, /** @type {any} */(texture.format), texture.type);
     newTexture.wrapS = THREE.RepeatWrapping;
     newTexture.anisotropy = capabilities.getMaxAnisotropy();
     newTexture.minFilter = THREE.LinearMipmapLinearFilter;
     newTexture.magFilter = THREE.LinearFilter;
     newTexture.generateMipmaps = true;
     newTexture.needsUpdate = true;
-
     return newTexture;
 }
 
@@ -34,7 +32,7 @@ export function prepareEnvTexture(texture, capabilities) {
  * Get Three uniform from MaterialX vector
  * @param {any} value
  * @param {any} dimension
- * @returns {THREE.Uniform}
+ * @returns {Array<number>}
  */
 function fromVector(value, dimension) {
     let outValue;
@@ -52,8 +50,11 @@ function fromVector(value, dimension) {
 
 /**
  * Get Three uniform from MaterialX matrix
+ * @param {any} matrix
+ * @param {number} dimension
+ * @returns {Array<number>}
  */
-function fromMatrix(matrix: MaterialX.Matrix, dimension: MaterialX.Matrix["size"]) {
+function fromMatrix(matrix, dimension) {
     const vec = new Array(dimension);
     if (matrix) {
         for (let i = 0; i < matrix.numRows(); ++i) {
@@ -69,19 +70,11 @@ function fromMatrix(matrix: MaterialX.Matrix, dimension: MaterialX.Matrix["size"
     return vec;
 }
 
-
-export type Loaders = {
-    /**
-     * Cache key for the loaders, used to identify and reuse textures
-     */
-    readonly cacheKey: string;
-    /**
-     * Get a texture by path
-     * @param {string} path - The path to the texture
-     * @return {Promise<THREE.Texture>} - A promise that resolves to the texture
-     */
-    readonly getTexture: (path: string) => Promise<THREE.Texture>;
-}
+/**
+ * @typedef {Object} Callbacks
+ * @property {string} [cacheKey] - Cache key for the loaders, used to identify and reuse textures
+ * @property {(path: string) => Promise<THREE.Texture | null | void>} getTexture - Get a texture by path
+ */
 
 const defaultTexture = new THREE.Texture();
 defaultTexture.needsUpdate = true;
@@ -94,21 +87,28 @@ defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAA
 // defaultTexture.magFilter = THREE.NearestFilter;
 // defaultTexture.repeat = new THREE.Vector2(100, 100);
 
-
 const defaultNormalTexture = new THREE.Texture();
 defaultNormalTexture.needsUpdate = true;
 defaultNormalTexture.image = new Image();
 defaultNormalTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIBAMAAAA2IaO4AAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAABJQTFRFgYH4gIH4gYH3gIH3gIH5gID4m94ORAAAADFJREFUeJxjZBBkfMdo9P/BB0aBj/8FGB0ufghgFGT4r8wo+P8rD2Pgo3sMjIz8jAwAMLoN0ZjS5hgAAAAASUVORK5CYII=";
 
-
-function tryGetFromCache(key: string): any {
+/**
+ * @param {string} key
+ * @returns {any}
+ */
+function tryGetFromCache(key) {
     const wasEnabled = THREE.Cache.enabled;
     THREE.Cache.enabled = true;
     const value = THREE.Cache.get(key);
     THREE.Cache.enabled = wasEnabled;
     return value;
 }
-function addToCache(key: string, value: any): void {
+
+/**
+ * @param {string} key
+ * @param {any} value
+ */
+function addToCache(key, value) {
     const wasEnabled = THREE.Cache.enabled;
     THREE.Cache.enabled = true;
     THREE.Cache.add(key, value);
@@ -118,10 +118,17 @@ function addToCache(key: string, value: any): void {
 
 /**
  * Get Three uniform from MaterialX value
+ * @param {any} uniforms
+ * @param {string} type
+ * @param {any} value
+ * @param {string} name
+ * @param {Callbacks} loaders
+ * @param {string} searchPath
+ * @returns {THREE.Uniform}
  */
-function toThreeUniform(uniforms: any, type: string, value: any, name: string, loaders: Loaders, searchPath: string): THREE.Uniform {
+function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
 
-    const uniform = new THREE.Uniform<any>(null);
+    const uniform = new THREE.Uniform(/** @type {any} */(null));
 
     switch (type) {
         case 'float':
@@ -130,21 +137,21 @@ function toThreeUniform(uniforms: any, type: string, value: any, name: string, l
             uniform.value = value;
             break;
         case 'vector2':
-            uniform.value = fromVector(value, 2);
+            uniform.value = /** @type {any} */ (fromVector(value, 2));
             break;
         case 'vector3':
         case 'color3':
-            uniform.value = fromVector(value, 3);
+            uniform.value = /** @type {any} */ (fromVector(value, 3));
             break;
         case 'vector4':
         case 'color4':
-            uniform.value = fromVector(value, 4);
+            uniform.value = /** @type {any} */ (fromVector(value, 4));
             break;
         case 'matrix33':
-            uniform.value = fromMatrix(value, 9);
+            uniform.value = /** @type {any} */ (fromMatrix(value, 9));
             break;
         case 'matrix44':
-            uniform.value = fromMatrix(value, 16);
+            uniform.value = /** @type {any} */ (fromMatrix(value, 16));
             break;
         case 'filename':
             if (value) {
@@ -165,7 +172,7 @@ function toThreeUniform(uniforms: any, type: string, value: any, name: string, l
                     checkCache = true;
                 }
 
-                const cacheKey = `${loaders.cacheKey}-${texturePath}`;
+                const cacheKey = loaders.cacheKey?.length ? `${loaders.cacheKey}-${texturePath}` : texturePath;
                 const cacheValue = checkCache ? tryGetFromCache(cacheKey) : null;
                 if (cacheValue) {
                     if (debug) console.log('[MaterialX] Use cached texture: ', cacheKey, cacheValue);
@@ -180,28 +187,30 @@ function toThreeUniform(uniforms: any, type: string, value: any, name: string, l
                     }
                 }
                 else {
-                    if (name.toLowerCase().includes("normal")) {
-                        uniform.value = defaultNormalTexture;
-                    }
-                    else {
-                        uniform.value = defaultTexture;
-                    }
-
                     if (debug) console.log('[MaterialX] Load texture:', texturePath);
+
+                    if (name.toLowerCase().includes("normal")) uniform.value = /** @type {any} */ (defaultNormalTexture);
+                    else uniform.value = /** @type {any} */ (defaultTexture);
+                    const defaultValue = uniform.value;
                     // Save the loading promise in the cache
-                    const promise = loaders.getTexture(texturePath).then(res => {
-                        if (res) {
-                            res = res.clone(); // we need to clone the texture once to avoid colorSpace issues with other materials
-                            res.colorSpace = THREE.LinearSRGBColorSpace;
-                            setTextureParameters(res, name, uniforms);
-                        }
-                        return res;
-                    });
-                    if (checkCache) {
-                        addToCache(cacheKey, promise);
-                    }
-                    promise.then(res => {
-                        if (res) uniform.value = res;
+                    const promise = loaders.getTexture(texturePath)
+                        ?.then(res => {
+                            if (res) {
+                                res = res.clone(); // we need to clone the texture once to avoid colorSpace issues with other materials
+                                res.colorSpace = THREE.LinearSRGBColorSpace;
+                                setTextureParameters(res, name, uniforms);
+                            }
+                            return res;
+                        })
+                        .catch(err => {
+                            console.error(`[MaterialX] Failed to load texture ${name} '${texturePath}'`, err);
+                            return defaultValue;
+                        });
+
+                    if (checkCache) addToCache(cacheKey, promise);
+
+                    promise?.then(res => {
+                        if (res) uniform.value = /** @type {any} */ (res);
                         else console.warn(`[MaterialX] Failed to load texture ${name} '${texturePath}'`);
                     });
                 }
@@ -222,12 +231,15 @@ function toThreeUniform(uniforms: any, type: string, value: any, name: string, l
     return uniform;
 }
 
-const valueTypeWarningMap = new Map<string, boolean>();
+/** @type {Map<string, boolean>} */
+const valueTypeWarningMap = new Map();
 
 /**
  * Get Three wrapping mode
+ * @param {number} mode
+ * @returns {THREE.Wrapping}
  */
-function getWrapping(mode: number): THREE.Wrapping {
+function getWrapping(mode) {
     let wrap;
     switch (mode) {
         case 1:
@@ -246,11 +258,14 @@ function getWrapping(mode: number): THREE.Wrapping {
     return wrap;
 }
 
-
 /**
  * Set Three texture parameters
+ * @param {THREE.Texture} texture
+ * @param {string} name
+ * @param {any} uniforms
+ * @param {boolean} [generateMipmaps=true]
  */
-function setTextureParameters(texture: THREE.Texture, name: string, uniforms: any, generateMipmaps = true) {
+function setTextureParameters(texture, name, uniforms, generateMipmaps = true) {
     const idx = name.lastIndexOf(IMAGE_PROPERTY_SEPARATOR);
     const base = name.substring(0, idx) || name;
 
@@ -265,15 +280,16 @@ function setTextureParameters(texture: THREE.Texture, name: string, uniforms: an
     }
 
     const mxFilterType = uniforms.find(base + FILTER_TYPE_SUFFIX) ? uniforms.get(base + FILTER_TYPE_SUFFIX).value : -1;
-    let minFilter: THREE.TextureFilter = generateMipmaps ? THREE.LinearMipMapLinearFilter : THREE.LinearFilter;
+    let minFilter = generateMipmaps ? THREE.LinearMipMapLinearFilter : THREE.LinearFilter;
     if (mxFilterType === 0) {
-        minFilter = generateMipmaps ? THREE.NearestMipMapNearestFilter : THREE.NearestFilter;
+        minFilter = /** @type {any} */ (generateMipmaps ? THREE.NearestMipMapNearestFilter : THREE.NearestFilter);
     }
     texture.minFilter = minFilter;
 }
 
 /**
  * Return the global light rotation matrix
+ * @returns {THREE.Matrix4}
  */
 export function getLightRotation() {
     return new THREE.Matrix4().makeRotationY(Math.PI / 2);
@@ -281,11 +297,11 @@ export function getLightRotation() {
 
 /**
  * Returns all lights nodes in a MaterialX document
- * @param {mx.Document} doc 
- * @returns {Array.<mx.Node>}
+ * @param {any} doc
+ * @returns {Array<any>}
  */
-export function findLights(doc: MaterialX.Document) {
-    let lights = new Array<any>;
+export function findLights(doc) {
+    let lights = new Array();
     for (let node of doc.getNodes()) {
         if (node.getType() === "lightshader")
             lights.push(node);
@@ -293,14 +309,16 @@ export function findLights(doc: MaterialX.Document) {
     return lights;
 }
 
+/** @type {Object<string, number>} */
 let lightTypesBound = {};
 
 /**
  * Register lights in shader generation context
- * @param {MaterialX.MODULE} mx MaterialX Module
- * @param {mx.GenContext} genContext Shader generation context
+ * @param {any} mx - MaterialX Module
+ * @param {any} genContext - Shader generation context
+ * @returns {Promise<void>}
  */
-export async function registerLights(mx: MaterialX.MODULE, genContext: any): Promise<void> {
+export async function registerLights(mx, genContext) {
     lightTypesBound = {};
     const maxLightCount = genContext.getOptions().hwMaxActiveLightSources;
     mx.HwShaderGenerator.unbindLightShaders(genContext);
@@ -353,7 +371,12 @@ export async function registerLights(mx: MaterialX.MODULE, genContext: any): Pro
     if (debug) console.log("Light types bound in MaterialX context", lightTypesBound);
 }
 
-// Converts Three.js light type to MaterialX node name
+const _lightTypeWarnings = {}
+/**
+ * Converts Three.js light type to MaterialX node name
+ * @param {string} threeLightType
+ * @returns {string|null}
+ */
 function threeLightTypeToMaterialXNodeName(threeLightType) {
     switch (threeLightType) {
         case 'PointLight':
@@ -363,26 +386,33 @@ function threeLightTypeToMaterialXNodeName(threeLightType) {
         case 'SpotLight':
             return 'ND_spot_light';
         default:
-            console.warn('MaterialX: Unsupported light type: ' + threeLightType);
-            return 'ND_point_light'; // Default to point light
+            if (!_lightTypeWarnings[threeLightType]) {
+                _lightTypeWarnings[threeLightType] = true;
+                console.warn('MaterialX: Unsupported light type: ' + threeLightType);
+            }
+            return null; // Unsupported light type
     }
-};
-
-export type LightData = {
-    type: number, // Light type ID
-    position: THREE.Vector3, // Position in world space
-    direction: THREE.Vector3, // Direction in world space
-    color: THREE.Color, // Color of the light
-    intensity: number, // Intensity of the light
-    decay_rate: number, // Decay rate for point and spot lights
-    inner_angle: number, // Inner angle for spot lights
-    outer_angle: number, // Outer angle for spot lights
 }
 
+/**
+ * @typedef {Object} LightData
+ * @property {number} type - Light type ID
+ * @property {THREE.Vector3} position - Position in world space
+ * @property {THREE.Vector3} direction - Direction in world space
+ * @property {THREE.Color} color - Color of the light
+ * @property {number} intensity - Intensity of the light
+ * @property {number} decay_rate - Decay rate for point and spot lights
+ * @property {number} inner_angle - Inner angle for spot lights
+ * @property {number} outer_angle - Outer angle for spot lights
+ */
+
 /**
  * Update light data for shader uniforms
+ * @param {Array<THREE.Light>} lights
+ * @param {any} genContext
+ * @returns {{ lightData: LightData[], lightCount: number }}
  */
-export function getLightData(lights: Array<THREE.Light>, genContext: any): { lightData: LightData[], lightCount: number } {
+export function getLightData(lights, genContext) {
     const lightData = new Array();
     const maxLightCount = genContext.getOptions().hwMaxActiveLightSources;
 
@@ -395,8 +425,12 @@ export function getLightData(lights: Array<THREE.Light>, genContext: any): { lig
 
         const lightDefinitionName = threeLightTypeToMaterialXNodeName(light.type);
 
-        if (!lightTypesBound[lightDefinitionName])
-            console.error("MaterialX: Light type not registered in context. Make sure to register light types before using them.", lightDefinitionName);
+        if(!lightDefinitionName){
+            continue; // Unsupported light type
+        }
+        if (!lightTypesBound[lightDefinitionName]) {
+            if(debug) console.error("MaterialX: Light type not registered in context. Make sure to register light types before using them.", lightDefinitionName);
+        }
 
         const wp = light.getWorldPosition(new THREE.Vector3());
         const wq = light.getWorldQuaternion(new THREE.Quaternion());
@@ -408,8 +442,8 @@ export function getLightData(lights: Array<THREE.Light>, genContext: any): { lig
         // float cosDir = dot(result.direction, -light.direction);
         // float spotAttenuation = smoothstep(low, high, cosDir);
 
-        const outerAngleRad = (light as THREE.SpotLight).angle;
-        const innerAngleRad = outerAngleRad * (1 - (light as THREE.SpotLight).penumbra);
+        const outerAngleRad = /** @type {THREE.SpotLight} */ (light).angle;
+        const innerAngleRad = outerAngleRad * (1 - /** @type {THREE.SpotLight} */ (light).penumbra);
         const inner_angle = Math.cos(innerAngleRad);
         const outer_angle = Math.cos(outerAngleRad);
 
@@ -420,7 +454,7 @@ export function getLightData(lights: Array<THREE.Light>, genContext: any): { lig
             color: new THREE.Color().fromArray(light.color.toArray()),
             // Luminous efficacy for converting radiant power in watts (W) to luminous flux in lumens (lm) at a wavelength of 555 nm.
             // Also, three.js lights don't have PI scale baked in, but MaterialX does, so we need to divide by PI for point and spot lights.
-            intensity: light.intensity * ((light as THREE.PointLight).isPointLight ? 683.0 / 3.1415 : (light as THREE.SpotLight).isSpotLight ? 683.0 / 3.1415 : 1.0),
+            intensity: light.intensity * (/** @type {THREE.PointLight} */ (light).isPointLight ? 683.0 / 3.1415 : /** @type {THREE.SpotLight} */ (light).isSpotLight ? 683.0 / 3.1415 : 1.0),
             decay_rate: 2.0,
             // Approximations for testing – the relevant light has 61.57986...129.4445 as inner/outer spot angle
             inner_angle: inner_angle,
@@ -453,8 +487,13 @@ export function getLightData(lights: Array<THREE.Light>, genContext: any): { lig
 
 /**
  * Get uniform values for a shader
+ * @param {any} shaderStage
+ * @param {Callbacks} loaders
+ * @param {string} searchPath
+ * @returns {Object<string, THREE.Uniform>}
  */
-export function getUniformValues(shaderStage: MaterialX.ShaderStage, loaders: Loaders, searchPath: string) {
+export function getUniformValues(shaderStage, loaders, searchPath) {
+    /** @type {Object<string, THREE.Uniform>} */
     const threeUniforms = {};
 
     const uniformBlocks = shaderStage.getUniformBlocks()
@@ -468,8 +507,8 @@ export function getUniformValues(shaderStage: MaterialX.ShaderStage, loaders: Lo
                 const value = variable.getValue()?.getData();
                 const uniformName = variable.getVariable();
                 const type = variable.getType().getName();
-                if (debug) console.log("Adding uniform", { path: variable.getPath(), name: uniformName, value: value, type: type });
                 threeUniforms[uniformName] = toThreeUniform(uniforms, type, value, uniformName, loaders, searchPath);
+                if (debug) console.log("Adding uniform", { path: variable.getPath(), type: type, name: uniformName, value: threeUniforms[uniformName], },);
             }
         }
     }
@@ -477,7 +516,11 @@ export function getUniformValues(shaderStage: MaterialX.ShaderStage, loaders: Lo
     return threeUniforms;
 }
 
-export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMaterial, shaderStage: MaterialX.ShaderStage) {
+/**
+ * @param {THREE.ShaderMaterial} material
+ * @param {any} shaderStage
+ */
+export function generateMaterialPropertiesForUniforms(material, shaderStage) {
 
     const uniformBlocks = shaderStage.getUniformBlocks()
     for (const [blockName, uniforms] of Object.entries(uniformBlocks)) {
@@ -501,22 +544,27 @@ export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMate
                         break;
                 }
                 if (key) {
-                    Object.defineProperty(material, key, {
-                        get: function () {
-                            return this.uniforms?.[uniformName].value
-                        },
-                        set: function (v) {
-                            const uniforms = this.uniforms;
-                            if (!uniforms || !uniforms[uniformName]) {
-                                console.warn(`[MaterialX] Uniform ${uniformName} not found in ${this.name} uniforms`);
-                                return;
+                    if (material.hasOwnProperty(key)) {
+                        if (debug) console.warn(`[MaterialX] Uniform ${uniformName} already exists in material as property ${key}, skipping.`);
+                    }
+                    else {
+                        Object.defineProperty(material, key, {
+                            get: function () {
+                                return this.uniforms?.[uniformName].value
+                            },
+                            set: function (v) {
+                                const uniforms = this.uniforms;
+                                if (!uniforms || !uniforms[uniformName]) {
+                                    console.warn(`[MaterialX] Uniform ${uniformName} not found in ${this.name} uniforms`);
+                                    return;
+                                }
+                                this.uniforms[uniformName].value = v;
+                                this.uniformsNeedUpdate = true;
                             }
-                            this.uniforms[uniformName].value = v;
-                            this.uniformsNeedUpdate = true;
-                        }
-                    });
+                        });
+                    }
                 }
             }
         }
     }
-}
+}