@needle-tools/materialx 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.7.1] - 2026-07-01
+
+### Fixed
+- Normalized MaterialX texture request paths when combining loader search paths, `fileprefix`, and relative filename values, avoiding duplicate slashes in hosted asset URLs.
+- Preserved absolute texture URLs and filename substitution tokens while resolving relative MaterialX texture paths.
+- Added MaterialX path fixtures with reference renders for included libraries, file prefixes, relative paths, and texture-load diagnostics.
+
 ## [1.7.0] - 2026-06-30
 
 ### Added

package/README.md

@@ -136,6 +136,10 @@ globalThis.NEEDLE_MATERIALX_LOCATION = "/assets/materialx/";
 
 IMPORTANT: The value must end with a trailing slash (`/`).
 
+### Texture Path Resolution
+
+MaterialX texture filenames are resolved from the MaterialX-authored filename value, any active `fileprefix`, and the loader search path. Relative paths are normalized for web requests so hosted asset URLs do not gain duplicate slashes, while absolute URLs such as `https://`, `file://`, root-relative paths, data URIs, blob URLs, and MaterialX filename tokens such as `<UDIM>` are preserved.
+
 
 ## glTF Extension: NEEDLE_materials_mtlx
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@needle-tools/materialx",
   "description": "MaterialX material support for three.js and Needle Engine – render physically based MaterialX shaders in the browser via WebAssembly",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "type": "module",
   "license": "PolyForm-Noncommercial-1.0.0",
   "main": "index.js",

package/src/materialx.helper.js

@@ -122,6 +122,75 @@ function addToCache(key, value) {
     if (debug) console.log('[MaterialX] Added to cache:', key, value);
 }
 
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteTexturePath(value) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//") || value.startsWith("/");
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteUrl(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function withTrailingSlash(value) {
+    return value.endsWith(IMAGE_PATH_SEPARATOR) ? value : `${value}${IMAGE_PATH_SEPARATOR}`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeRelativeTexturePath(value) {
+    const suffixStart = value.search(/[?#]/);
+    const path = suffixStart >= 0 ? value.slice(0, suffixStart) : value;
+    const suffix = suffixStart >= 0 ? value.slice(suffixStart) : "";
+    const hasLeadingSlash = path.startsWith(IMAGE_PATH_SEPARATOR);
+    const parts = [];
+
+    for (const part of path.split(IMAGE_PATH_SEPARATOR)) {
+        if (!part || part === ".") continue;
+        if (part === "..") {
+            const previous = parts[parts.length - 1];
+            if (previous && previous !== "..") parts.pop();
+            else if (!hasLeadingSlash) parts.push(part);
+            continue;
+        }
+        parts.push(part);
+    }
+
+    const normalizedPath = `${hasLeadingSlash ? IMAGE_PATH_SEPARATOR : ""}${parts.join(IMAGE_PATH_SEPARATOR)}`;
+    return `${normalizedPath}${suffix}`;
+}
+
+/**
+ * @param {string} searchPath
+ * @param {string} value
+ * @returns {string}
+ */
+function resolveTexturePath(searchPath, value) {
+    if (isAbsoluteTexturePath(value)) return value;
+    if (!searchPath) return value;
+
+    const normalizedSearchPath = searchPath.replace(/\/+$/, "");
+    if (!normalizedSearchPath) return value;
+
+    if (isAbsoluteUrl(normalizedSearchPath)) {
+        return new URL(value, withTrailingSlash(normalizedSearchPath)).href;
+    }
+
+    return normalizeRelativeTexturePath(`${normalizedSearchPath}${IMAGE_PATH_SEPARATOR}${value}`);
+}
+
 /**
  * Get Three uniform from MaterialX value
  * @param {any} uniforms
@@ -165,19 +234,19 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
                 // Cache / reuse texture to avoid reload overhead.
                 // Note: that data blobs and embedded data textures are not cached as they are transient data.
                 let checkCache = true;
-                let texturePath = searchPath + IMAGE_PATH_SEPARATOR + value;
+                let texturePath = value;
                 if (value.startsWith('blob:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('data:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('http')) {
-                    texturePath = value;
                     checkCache = true;
                 }
+                else {
+                    texturePath = resolveTexturePath(searchPath, value);
+                }
 
                 const cacheKey = loaders.cacheKey?.length ? `${loaders.cacheKey}-${texturePath}` : texturePath;
                 const cacheValue = checkCache ? tryGetFromCache(cacheKey) : null;
@@ -247,7 +316,7 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
         case 'displacementshader':
         case 'volumeshader':
         case 'lightshader':
-            // MaterialX closure/shader types — not real uniforms, skip silently
+            // MaterialX closure/shader types — not emitted uniforms, skip silently
             break;
         default:
             const key = type + ':' + name;