@meimu/mutracer 0.1.4 → 0.1.5

package/docs/api.md

@@ -333,7 +333,8 @@ one. See [thin-film textures](./materials.md#textures) for range behavior.
 `undefined`. Channels and color decoding are listed in [material textures](./materials.md#textures).
 They follow the existing material/texture update mechanism.
 
-`coatNormalMap` defaults to `undefined`, retaining the shared shading normal. With a map, linear RGB supplies an independent coat normal; `coatNormalScale` defaults to `[1, 1]` and scales its decoded XY. See [coat normals](./materials.md#coat-normals) for frame, sampling and update behavior.
+`coatNormalMap` defaults to `undefined`; `coatNormalScale` defaults to `[1, 1]`.
+See [coat normals](./materials.md#coat-normals) for independent base and coat normal mapping.
 
 Raw texture sources contain exactly `width * height * 4` RGBA values, with
 rows ordered from top to bottom. `Uint8Array` and `Uint8ClampedArray` store

package/docs/materials.md

@@ -260,41 +260,32 @@ with coat, and the finite path-event budget can truncate deep glass paths.
 ## Coat normals
 
 Set `coatNormalMap` to give the coat a tangent-space normal independently of
-`normalMap`. The renderer decodes linear RGB as `2 * RGB - 1`, multiplies XY
-by `coatNormalScale`, then normalizes. The scale defaults to `[1, 1]` and can
-be negative or zero. A missing map (the default), zero coat weight or zero sampled coat coverage retains the existing shared
-shading normal, including the base normal map.
-
-The coat TBN starts from the interpolated geometry normal before base normal
-mapping. It uses the coat texture's UV0/UV1 selection and geometric
-tangent handedness; generated tangents use UV1 differentials when that set is
-selected. Degenerate frames and zero decoded vectors use stable fallbacks.
-The texture's scale, offset and `flipY` follow the ordinary atlas sampling
-rules. As with other slots, sharing an image never changes its color space.
-
-Base lobes keep their base frame. Coat reflection, its sampling PDF, directional
-albedo and passage absorption use the coat frame; the renderer combines their
-responses and densities for the same world direction. Each frame is corrected
-against the geometric/view hemisphere independently. Triangle normals still
-control reflection versus transmission, medium boundaries and ray offsets.
-A coat reflection can contribute below the base shading hemisphere when it
-remains above the coat and geometric hemispheres. As before, solid interior
-hits omit coat reflection; thin surfaces are treated as exterior hits.
+`normalMap`. Without a coat map (the default), the coat uses the interpolated
+surface normal before base normal mapping. A bumpy base can therefore have a
+smooth coat. Assign the same texture to both maps to perturb both layers.
 
-Strongly tilted shading normals lose some lobe support when clipped to the
-geometric hemisphere. A unit white environment can therefore render below
-unit radiance; the renderer does not renormalize the clipped lobes.
+The map decodes linear RGB as `2 * RGB - 1`, multiplies XY by
+`coatNormalScale`, then normalizes. The scale defaults to `[1, 1]` and can be
+negative or zero. UV0/UV1 selection, scale, offset and `flipY` follow the
+ordinary texture rules. Zero coat weight or zero sampled coat coverage
+disables the coat without changing the base normal.
 
 Replacing the map or editing its scale is detected by `engine.update()`. Call
 `texture.markUpdated()` after pixel or UV-array element edits; see [scene updates](./updates.md).
-These edits update material parameters/textures without rebuilding geometry. Normal maps do not alter
-emission's existing normal-incidence absorption or light-selection proposals.
+
+Coat reflections can remain visible where the base normal points away from
+the light. Solid interior hits omit coat reflection; thin surfaces are
+treated as exterior hits.
+
+Strongly tilted shading normals lose some lobe support when clipped to the
+geometric hemisphere. A unit white environment can therefore render below
+unit radiance; the renderer does not renormalize the clipped lobes.
 
 ## Anisotropy directions
 
 Set `specularAnisotropyRotation` or provide `anisotropyMap` to orient the base specular lobe. The map reads linear `2 * RG - 1`, normalizes the direction, multiplies strength by B, and then applies the rotation. A decoded squared length at or below `1e-4` falls back to `(1, 0)` before rotation (including the two central RGBA8 codes). Without a map the direction is `(1, 0)` and the strength multiplier is one. The rotation defaults to zero; the map defaults to undefined.
 
-`coatAnisotropyRotation` defaults to zero and uses the geometry tangent independently of the base map. Base and coat evaluation, sampling and PDF use their respective directions. The coat uses the shared shading normal unless `coatNormalMap` selects an [independent normal](#coat-normals). Zero strength ignores the new direction and retains the original isotropic path.
+`coatAnisotropyRotation` defaults to zero and uses the geometry tangent independently of the base map. Base and coat use their respective directions and [normals](#coat-normals). Zero anisotropy strength ignores the direction.
 
 Provided tangent XYZ and optional W handedness are preserved. For XYZ tangents the sign comes from triangle UV derivatives. Missing or degenerate tangents use UV derivatives and then a stable orthonormal fallback; missing tangents produce one diagnostic per geometry. The direction texture's selected UV set is used for derivative fallback, including UV1. A provided XYZW tangent remains authoritative. Directions are reorthogonalized against the final shading normal, including normal maps and back faces, and instance transforms preserve mirrored handedness. UV scale, offset and flipY affect texel lookup; they do not rotate the encoded direction.
 

package/docs/threejs.md

@@ -108,12 +108,12 @@ or a source `THREE.Texture`. `THREESync` converts parameter edits without
 rewriting texture pixels. The iridescence strength texture is not supported;
 `thinFilmMap` represents thickness only.
 
-The six layer maps reuse the texture conversion cache, source UV channel,
-scale, offset and flipY. `mutracerOpenPBR` can override them with a MuTracer
+The six layer maps preserve the source UV channel, scale, offset and `flipY`.
+`mutracerOpenPBR` can override them with a MuTracer
 `Texture` or `THREE.Texture`; explicit `null` clears an imported map, while
-unknown JSON objects are ignored. `THREESync` follows texture edits without
-copying pixels. General `KHR_texture_transform` rotation remains unsupported.
-Clearcoat normals are deferred to the independent coat-frame implementation.
+unknown JSON objects are ignored. `THREESync` follows texture edits.
+General `KHR_texture_transform` rotation remains unsupported.
+See [coat normal conversion](#coat-normal-conversion) for clearcoat normal maps.
 Anisotropy direction and source-model mapping are described [below](#anisotropy-source-conversion). The conversion preserves OpenPBR layering: glTF sheen
 layer order differs, and specular weight/color also affect metals in OpenPBR;
 these imports do not imply identical glTF BRDFs. A fully metallic material

package/docs/viewer.md

@@ -1,4 +1,37 @@
-# Sharing viewer settings
+# Using the viewer
+
+Open **Examples → MuTracer collection** for models curated for this viewer, or
+**Examples → glTF Research Scenes** for the independently maintained
+[glTF Research Scenes](https://github.com/ErfanMo77/gltf-research-scenes) collection.
+Scenes download on demand from GitHub; cards show approximate download sizes
+and link to each scene's source and license. Large scenes need more memory.
+
+glTF/GLB imports include directional, point and spot lights and emissive meshes.
+Benchmark scenes also load their sunlight and available environment maps.
+Under **Lighting → Environment**, **Scene lighting** is available only when the
+model provides lights or environment lighting. Choose it to use the imported
+lighting alone, or select an HDRI or Studio to add lighting. Emissive materials
+still work with HDRI and Studio. Environment maps add download time and are
+resampled to at most 2K width. If a source map is missing, the model still opens
+and the Lighting panel explains which map is unavailable; choose an environment
+there to replace it.
+
+When an imported glTF/GLB contains cameras, a toast offers **Apply camera** to
+use its first camera.
+Dismiss the toast to keep the Orbit view. You can select any imported camera
+in the separate camera toolbar at the bottom right; it appears only for models
+with cameras. Drag, pan or zoom after selecting a camera to continue in **Orbit**
+from that view.
+Hover over a camera in the scene tree and click its camera action to apply it
+directly. **Fit to model** in the bottom toolbar (or **F**) returns to Orbit
+and frames the model.
+Reloading the current model restores your saved camera selection without
+showing the prompt again.
+
+Picking an object in the viewport reveals it in the scene tree and scrolls it
+into view. Material rows start collapsed; expand a mesh to see its materials.
+
+## Sharing viewer settings
 
 Add settings to a viewer link to override the recipient's saved preferences.
 For example, open the viewer with HDR output enabled:
@@ -17,7 +50,7 @@ The viewer updates the URL as lighting, render and display settings change.
 Copy the address bar to share those settings and the selected example model.
 Settings also work in the hash, such as `#model=dragon&hdrOutputEnabled=true`.
 
-## Options
+### Options
 
 Parameter names match the viewer settings and are case-sensitive:
 
@@ -42,7 +75,7 @@ can override a recipient's different preference. When the viewer updates the
 address, settings move into the hash; unrelated query parameters, including
 `?webgl`, are preserved.
 
-## Caveats
+### Caveats
 
 HDR output requires WebGPU, an HDR display and a compatible browser. Unsupported
 devices fall back to SDR. `?webgl` forces WebGL 2, which does not support HDR output.

package/lib/oidn.d.ts

@@ -40,6 +40,6 @@ export declare const DEFAULT_OIDN_WEIGHTS_PACKAGE_BASE_URL = "https://cdn.jsdeli
  * Fallback for bundled standard/small weights when application assets fail.
  * Defaults to jsDelivr's `@meimu/mutracer@VERSION/oidn/weights/` directory.
  */
-export declare const DEFAULT_OIDN_WEIGHTS_BASE_URL = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.4/oidn/weights/";
+export declare const DEFAULT_OIDN_WEIGHTS_BASE_URL = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.5/oidn/weights/";
 export declare function resolveOIDNModelUrl(model: OIDNModel, weightsBaseUrl?: string | URL): string;
 export declare function resolveOIDNAuxiliaryModelUrls(weightsBaseUrl?: string | URL): OIDNAuxiliaryModelUrls;

package/lib/oidnBundledWeights.cdn.d.ts

@@ -1,2 +1,2 @@
-export declare const standardWeightsUrl = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.4/oidn/weights/rt_hdr_alb_nrm.tza";
-export declare const smallWeightsUrl = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.4/oidn/weights/rt_hdr_alb_nrm_small.tza";
+export declare const standardWeightsUrl = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.5/oidn/weights/rt_hdr_alb_nrm.tza";
+export declare const smallWeightsUrl = "https://cdn.jsdelivr.net/npm/@meimu/mutracer@0.1.5/oidn/weights/rt_hdr_alb_nrm_small.tza";

package/lib/renderer/WGPUFullQuadPass.js

@@ -282,10 +282,10 @@ ${scratchWGSLFunctions(this._reserveCapacity ? this._regionNames : inputs.filter
 ${this._fsDefine ?? ''}
 @fragment
 fn main(
-@builtin(position) fG: vec4f
+@builtin(position) fH: vec4f
 ) -> pd {
-let uv = vec2i(floor(fG.xy));
-let uv2 = fG.xy / viewportSize;
+let uv = vec2i(floor(fH.xy));
+let uv2 = fH.xy / viewportSize;
 var output: pd;
 ${this._fsMain}
 return output;

package/lib/renderer/WGPUJNLMDenoiser.js

@@ -55,13 +55,13 @@ if (id.x >= size.x || id.y >= size.y) { return; }
 let center = rawGuide[id.x + id.y * size.x];
 var lu = 0.0;
 var jc = 0.0;
-var mZ = 0.0;
+var mY = 0.0;
 var iX = 0.0;
 for (var dy = -1; dy <= 1; dy++) {
 for (var dx = -1; dx <= 1; dx++) {
 let q = clamp(vec2i(id.xy) + vec2i(dx, dy), vec2i(0), vec2i(size) - 1);
 let value = rawGuide[u32(q.x) + u32(q.y) * size.x];
-mZ += value.x;
+mY += value.x;
 iX += value.x * value.x;
 if (value.y >= 0.0) {
 lu += value.y;
@@ -73,7 +73,7 @@ var variance: f32;
 if (center.y >= 0.0) {
 variance = lu / jc;
 } else {
-let lt = mZ / 9.0;
+let lt = mY / 9.0;
 variance = max(iX / 9.0 - lt * lt, 0.0) * 9.0 / 8.0;
 }
 guide[id.x + id.y * size.x] = vec2f(center.x, variance);
@@ -122,19 +122,19 @@ const INV_NORMAL_BANDWIDTH2 = ${(1 / normalBandwidth ** 2).toFixed(6)};
 
 const CENTER_WEIGHT_MIN = 0.01;
 
-fn he(p: vec2i) -> u32 {
+fn hg(p: vec2i) -> u32 {
 let q = clamp(p, vec2i(0), vec2i(params.size) - 1);
 return u32(q.x) + u32(q.y) * params.size.x;
 }
 
-fn lA(q: vec2i, bs: vec4f, gS: vec3f) -> f32 {
+fn lw(q: vec2i, bs: vec4f, gT: vec3f) -> f32 {
 let albedo = textureLoad(albedoTex, q, 0);
 
 
 let pf = max((albedo.rgb + bs.rgb) * 0.5, vec3f(${JNLM_ALBEDO_FLOOR}));
 let ld = (albedo.rgb - bs.rgb) / pf;
 let iU = albedo.a - bs.a;
-let lp = textureLoad(normalTex, q, 0).rgb - gS;
+let lp = textureLoad(normalTex, q, 0).rgb - gT;
 return max(
 dot(ld, ld) * INV_ALBEDO_BANDWIDTH2
 + iU * iU * INV_COVERAGE_BANDWIDTH2,
@@ -153,12 +153,12 @@ let p = vec2i(id.xy);
 if (p.x >= size.x || p.y >= size.y) { return; }
 let step = i32(params.dilation);
 let bs = textureLoad(albedoTex, p, 0);
-let fC = textureLoad(normalTex, p, 0);
-let gS = fC.rgb;
-let index = he(p);
+let fD = textureLoad(normalTex, p, 0);
+let gT = fD.rgb;
+let index = hg(p);
 
 
-if (fC.a <= 0.0 && textureLoad(shadowCatcherTex, p, 0).r <= 0.0) {
+if (fD.a <= 0.0 && textureLoad(shadowCatcherTex, p, 0).r <= 0.0) {
 outColor[index] = color[index];
 outGuide[index] = guide[index];
 return;
@@ -168,20 +168,20 @@ var lf: array<vec2f, PATCH_SIZE>;
 var k = 0;
 for (var dy = -PATCH_RADIUS; dy <= PATCH_RADIUS; dy++) {
 for (var dx = -PATCH_RADIUS; dx <= PATCH_RADIUS; dx++) {
-lf[k] = guide[he(p + vec2i(dx, dy) * step)];
+lf[k] = guide[hg(p + vec2i(dx, dy) * step)];
 k++;
 }
 }
 let k2 = params.colorSensitivity * params.colorSensitivity;
 
 var sum = vec4f(0.0);
-let gV = max(bs.rgb, vec3f(${JNLM_ALBEDO_FLOOR}));
-var mq = vec3f(0.0);
-var gx = vec3f(0.0);
+let gW = max(bs.rgb, vec3f(${JNLM_ALBEDO_FLOOR}));
+var mp = vec3f(0.0);
+var gy = vec3f(0.0);
 var hs = vec3f(0.0);
 var ps = 0.0;
-var gz = 0.0;
-var nV = 0.0;
+var gA = 0.0;
+var nU = 0.0;
 var kM = 0.0;
 for (var sy = -SEARCH_RADIUS; sy <= SEARCH_RADIUS; sy++) {
 for (var sx = -SEARCH_RADIUS; sx <= SEARCH_RADIUS; sx++) {
@@ -191,38 +191,38 @@ if (
 q.x < 0 || q.y < 0 || q.x >= size.x || q.y >= size.y
 ) { continue; }
 
-let features = lA(q, bs, gS);
+let features = lw(q, bs, gT);
 if (features > 16.0) { continue; }
 
-var fX = 0.0;
+var fY = 0.0;
 k = 0;
 for (var dy = -PATCH_RADIUS; dy <= PATCH_RADIUS; dy++) {
 for (var dx = -PATCH_RADIUS; dx <= PATCH_RADIUS; dx++) {
 let a = lf[k];
-let b = guide[he(q + vec2i(dx, dy) * step)];
+let b = guide[hg(q + vec2i(dx, dy) * step)];
 let qU = a.x - b.x;
-fX += (qU * qU
+fY += (qU * qU
 - VARIANCE_CANCELLATION * (a.y + min(a.y, b.y)))
 / (1e-10 + k2 * (a.y + b.y));
 k++;
 }
 }
-fX /= f32(PATCH_SIZE);
+fY /= f32(PATCH_SIZE);
 
-let weight = exp(-max(max(fX, 0.0), features));
-let index = he(q);
+let weight = exp(-max(max(fY, 0.0), features));
+let index = hg(q);
 let c = color[index];
 let g = guide[index];
 
-let a = (textureLoad(albedoTex, q, 0).rgb - bs.rgb) / gV;
+let a = (textureLoad(albedoTex, q, 0).rgb - bs.rgb) / gW;
 let value = premultiplied(c);
 sum += value * weight;
-mq += a * weight;
-gx += a * a * weight;
+mp += a * weight;
+gy += a * a * weight;
 hs += a * value.rgb * weight;
 ps += g.x * weight;
-gz += g.y * weight * weight;
-nV += weight;
+gA += g.y * weight * weight;
+nU += weight;
 kM = max(kM, weight);
 }
 }
@@ -232,20 +232,20 @@ kM = max(kM, weight);
 let center = color[index];
 let le = guide[index];
 let dG = max(kM, CENTER_WEIGHT_MIN);
-let totalWeight = nV + dG;
+let totalWeight = nU + dG;
 let tM = premultiplied(center);
 let mean = (sum + tM * dG) / totalWeight;
 
 
-let ez = mq / totalWeight;
-let lB = max(gx / totalWeight - ez * ez, vec3f(0.0));
+let ez = mp / totalWeight;
+let lA = max(gy / totalWeight - ez * ez, vec3f(0.0));
 let qu = hs / totalWeight - ez * mean.rgb;
 
 
 
-let qE = bs.rgb + ez * gV;
-let oA = mean.rgb * gV / max(qE, vec3f(${JNLM_ALBEDO_FLOOR}));
-let vB = clamp(qu / (lB + vec3f(${JNLM_ALBEDO_REGULARIZATION})), vec3f(0.0), oA);
+let qE = bs.rgb + ez * gW;
+let oz = mean.rgb * gW / max(qE, vec3f(${JNLM_ALBEDO_FLOOR}));
+let vB = clamp(qu / (lA + vec3f(${JNLM_ALBEDO_REGULARIZATION})), vec3f(0.0), oz);
 let rD = mean.rgb - vB * ez;
 let filtered = vec4f(max(rD, vec3f(0.0)), max(mean.a, 0.0));
 let rgb = select(
@@ -256,7 +256,7 @@ filtered.a > 1e-6
 outColor[index] = vec4f(rgb, filtered.a);
 outGuide[index] = vec2f(
 (ps + le.x * dG) / totalWeight,
-(gz + le.y * dG * dG)
+(gA + le.y * dG * dG)
 / (totalWeight * totalWeight)
 );
 }

package/lib/renderer/WGPURayTraceOutput.js

@@ -23,10 +23,10 @@ ${layers ? `@location(0) foreground: vec4f,
 @location(2) albedo: vec4f${catcher ? ',\n  @location(3) shadowCatcher: vec4f' : ''}`}
 }
 @fragment
-fn main(@builtin(position) fG: vec4f) -> pd {
+fn main(@builtin(position) fH: vec4f) -> pd {
 let size = vec2u(u32(outputWidth), u32(outputHeight));
-let fP = vec2u(u32(fG.x), size.y - u32(fG.y) - 1u);
-var idx = fP.x + fP.y * size.x;
+let fQ = vec2u(u32(fH.x), size.y - u32(fH.y) - 1u);
+var idx = fQ.x + fQ.y * size.x;
 
 
 
@@ -34,7 +34,7 @@ var idx = fP.x + fP.y * size.x;
 if (sampleCount < 1.0 && normalBuffer[idx].a <= 0.0) {
 let vc = max(sampleTileGrid, vec2u(1u));
 let uM = min(
-((fP + vc / 2u) / vc) * vc,
+((fQ + vc / 2u) / vc) * vc,
 ((size - vec2u(1u)) / vc) * vc
 );
 let sH = uM.x + uM.y * size.x;

package/lib/renderer/WGPURayTracePass.js

@@ -1916,6 +1916,9 @@ ${rayTraceCompute({
         // Retain the atlas uniform capacity when a stage/material is removed.
         // Shrinking the array would rebuild every pipeline again on the next edit.
         const NUM_MAPS = Math.max(Math.ceil(+materialData.defines.NUM_MAPS / 10) * 10, Number(this._constants.NUM_MAPS ?? 0), 20);
+        // Either layer's map requires independent normals, including a smooth
+        // coat over a mapped base. Unmapped materials retain the shared path.
+        const USE_COAT_NORMAL_FRAMES = materials.some(m => m.coatWeight > 0 && (!!m.normalMap || !!m.coatNormalMap));
         Object.assign(this._constants, {
             // Match the atlas UV selector. Keep the second set when any texture
             // needs it; material/texture edits already rebuild these constants.
@@ -1924,9 +1927,8 @@ ${rayTraceCompute({
             // triangle UV differentials rather than this vertex tangent.
             USE_TANGENT: mergedGeometry.tangent != null &&
                 materials.some(material => material.specularAnisotropy > 0 || material.coatAnisotropy > 0 || (!!material.coatNormalMap && material.coatWeight > 0)),
-            USE_COAT_NORMAL_FRAMES: materials.some(m => !!m.coatNormalMap && m.coatWeight > 0),
-            USE_ANISOTROPY_DIRECTIONS: materials.some(m => (!!m.coatNormalMap && m.coatWeight > 0) ||
-                m.specularAnisotropy > 0 && (m.specularAnisotropyModel === 'gltf' || !!m.anisotropyMap || m.specularAnisotropyRotation !== 0) ||
+            USE_COAT_NORMAL_FRAMES,
+            USE_ANISOTROPY_DIRECTIONS: USE_COAT_NORMAL_FRAMES || materials.some(m => m.specularAnisotropy > 0 && (m.specularAnisotropyModel === 'gltf' || !!m.anisotropyMap || m.specularAnisotropyRotation !== 0) ||
                 m.coatAnisotropy > 0 && m.coatAnisotropyRotation !== 0),
             HAS_MEDIUM,
             HAS_SHADOW_CATCHER: this._hasShadowCatcher,