@meimu/mutracer 0.2.0 → 0.3.1

package/docs/technical/aovs.md

@@ -0,0 +1,79 @@
+# Surface color AOVs
+
+MuTracer has two pairs of surface color outputs. `diffuseAlbedo` and
+`specularAlbedo` report how much light a surface reflects. `diffuseColor` and
+`specularColor` report the material colors that produce it. Usage and the exact
+definitions are in [surface outputs](../api.md#surface-outputs); this note explains
+why both pairs exist, how they are named and how they are stored.
+
+## Reflectance and color
+
+The albedo kinds are directional-hemispherical reflectance: the fraction of
+uniform incident light that the prepared OpenPBR BSDF reflects toward the view
+direction. They integrate the BSDF by quadrature (`aovReflectance*.wgsl.ts` and
+`.glsl.ts`), so they cost more than the other outputs and support only materials
+the quadrature models. Coat, fuzz, anisotropy and similar hits are marked
+unsupported.
+
+The color kinds read resolved material inputs without integration:
+
+- diffuse: base weight × base color × (1 − metalness)
+- specular: metalness × base weight × base color + (1 − metalness) ×
+  specular weight × specular color × F0, with F0 from the specular IOR
+
+Both are multiplied by the coat color, weighted by the coat weight. Transmission,
+partial alpha, media and nonstandard materials have zero validity.
+
+EASU detail recovery needs the color kinds, not reflectance. It compares
+display-resolution colors with their average over each render pixel and scales
+the part of the upscaled radiance that follows color by that ratio. Layer factors
+that are uniform across a surface, such as coat or fuzz, cancel in the ratio, so
+the cheap estimate covers more surfaces than the quadrature does. Reflectance
+remains the right input for compositing and other uses that need reflected energy.
+
+## Names
+
+Renderers use "albedo" for both quantities:
+
+| Renderer | Integrated reflectance | Material color |
+| --- | --- | --- |
+| [MoonRay](https://docs.openmoonray.org/user-reference/how-to-guides/render-outputs/material-aovs/) | `albedo`: response to unoccluded white light from all directions | `color` |
+| [Mitsuba 3](https://mitsuba.readthedocs.io/en/stable/src/generated/plugins_integrators.html) | `albedo`: diffuse reflectance, approximate for some materials | none |
+| [Arnold](https://help.autodesk.com/cloudhelp/ENU/AR-Core/files/ac-output-aovs/arnold_user_guide_ac_output_aovs_ac_aovs_html.html) | none | `diffuse_albedo`, `specular_albedo`: colors without lighting |
+| [Cycles](https://docs.blender.org/manual/en/latest/render/layers/passes.html) | none | `Diffuse Color`, `Glossy Color`: BSDF color weights |
+| V-Ray, Redshift | none | `Diffuse Filter` |
+
+MuTracer's names match MoonRay: albedo for integrated reflectance, color for
+material inputs. Albedo for reflectance also matches Mitsuba and the
+"directional albedo" of energy compensation work. Arnold uses albedo for colors,
+so documentation always states the definition next to the name. No surveyed
+renderer names an AOV "reflectance"; the viewer uses it only in labels.
+
+These outputs are separate from the OIDN `albedo` guide, which follows its own
+path rules for denoising.
+
+## Storage
+
+The WebGPU accumulation has four `vec4f` lanes per pixel (`AOV_LAYOUT`):
+depth with roughness, position with hit count, diffuse and specular. A lobe's
+albedo and color share its lane, selected per kind by mask bits 3–4 and 7–8, so a
+render may request only one of them per lobe. Resolve, display and snapshot shaders
+see a color kind as the albedo kind of its lane (`aovLaneKind`), so they need no
+color-specific code. Separate lanes would add 32 bytes per pixel to every AOV
+render. If both are ever needed together, adding lanes lifts the restriction
+without changing the API.
+
+Display-resolution renders requesting only `depth`, `diffuseColor` and
+`specularColor` use a compact 24-byte layout: float depth and hit count, plus two
+colors in half precision. It skips the center pass, so it has no ID or motion.
+Half-precision sums lose precision as the sample count grows, which is acceptable
+only because display resolution stops at 4 samples (`DISPLAY_AOV_SAMPLE_CAP`).
+For detail recovery, 4 jittered samples matched 16 within measurement noise.
+Render resolution keeps the full layout for any request.
+
+## Native
+
+Native shares `aovTraceDisplay.wgsl.ts` but still requests display-resolution
+colors through the albedo bits with the `AOV_DISPLAY` override. The web build never
+sets that override. Native should adopt the color kinds when it is next aligned
+with web AOVs.

package/docs/technical/caustics.md

@@ -0,0 +1,109 @@
+# Caustic estimators
+
+Path tracing finds caustics only when a BSDF sample happens to hit the light
+through a smooth surface, because shadow rays treat glass as an occluder. MuTracer
+adds two WebGPU estimators for those paths: light tracing and progressive photon
+mapping. Usage, costs and limits are in the [caustics guide](../caustics.md); this
+note explains how the paths are divided and how the estimators work.
+
+## Path partition
+
+A surface is *smooth* when `isCausticSpecular` holds: no diffuse, subsurface, fuzz
+or coat weight, and specular roughness at most `CAUSTIC_ROUGHNESS_MAX` (0.1). The
+test depends only on the material, never on the lobe a sample chose, so every
+estimator classifies a vertex the same way (`src/renderer/caustics.ts`).
+
+Counting from the light, the *receiver* is the first non-smooth surface vertex, k is
+the number of smooth vertices between the light and the receiver, and the *camera
+prefix* is the path from the camera to the receiver. Surfaces skipped through alpha
+are not vertices.
+
+| Paths | Estimator |
+| --- | --- |
+| k = 0 | Path tracing, unchanged |
+| k ≥ 1, empty camera prefix (the camera sees the receiver directly), light tracing on | Light tracing |
+| Other k ≥ 1, photon mapping on | Photon mapping |
+| Anything else | Path tracing's BSDF hits |
+
+Path tracing tracks the smooth chain length and whether the receiver is the first
+visible surface. When it hits a light on a path that an enabled estimator owns, the
+contribution is zero. Each path is therefore counted by exactly one estimator.
+When an estimator is off or unsupported (WebGL 2), its rows fall back to path
+tracing, so every configuration has the same expected image and differs only in
+noise. Scenes whose smooth casters use stochastic blend coverage turn both
+estimators off, because their photon transport does not yet match path-tracing
+energy.
+
+## Casters and emission
+
+The renderer collects caster meshes and instances automatically from smooth
+materials, with one conservative world-space sphere per instance. Photons are
+emitted only toward caster spheres: a path whose first surface from the light is
+not smooth belongs to path tracing, so restricting emission loses no estimator's
+paths. Emission samples the full light surface, then accepts directions toward
+the caster mixture; the direction PDF accounts for overlapping cones
+(`casterDirectionPdf`). Lights are chosen by a separate power PMF, not the NEE
+selection table (`causticEmission.ts`). Directional and environment light emit
+from a mixture of projected caster disks.
+
+## Light tracing
+
+Light tracing is BDPT's t = 1 strategy. Photons follow smooth vertices with adjoint
+BSDF corrections. At the receiver, the pass samples a lens point, connects to the
+camera, tests visibility and splats into the pixel with float32 compare-and-swap
+atomics. It runs once per sample batch, after the last tile, in its own pass and
+bind group, because the main integrator already uses the baseline eight storage
+buffers. The result accumulates separately; resolve adds it to the path-traced
+radiance, so readback, denoising and display see the combined image. Adaptive
+sampling measures variance only on the path-traced part.
+
+## Photon mapping
+
+Photon mapping uses probabilistic progressive photon mapping (Knaus and Zwicker
+2011). Each sample batch emits a new photon map on the first tile, which later tiles
+reuse. The gather radius shrinks as r_i = r_1 · i^((α − 1)/2) with α = 2/3
+(`photonRadius`). The first radius is `initialRadius`, or 3% of the caster sphere
+radius. At the first non-smooth camera vertex the radius is further limited to
+about two projected pixels (`photonVisibleRadius`); mirror prefixes use an
+approximate footprint, and deeper vertices use the global radius. The pixel cap
+reduces blotches after denoising, at the cost of grainier raw output.
+
+Photons are stored at the first non-smooth surface after at least one smooth
+vertex, whatever camera prefix will later find them; queries at directly visible
+receivers skip them when light tracing owns those paths. Camera paths query at every non-smooth vertex within `bounces`, with a
+normal-consistent surface kernel.
+
+Each photon takes 20 bytes: float32 position and RGBE8 flux, and two octahedral
+directions (incident direction and normal). Two hash-grid layers with different
+cell sizes, one for first visible receivers and one for deeper queries, each sort
+only a 4-byte index, for 28 bytes per photon. Grids are rebuilt every batch with a
+count, a two-level parallel prefix sum and a scatter; bucket counts are powers of
+two up to 262144. Batches are reduced to fit device limits and a 128 MiB budget.
+
+Quantized flux and directions limit precision. More batches shrink the radius
+but do not remove that error, so photon mapping is consistent only up to storage
+precision.
+
+## Rejected and paused work
+
+- **MNEE and SMS** (manifold next-event estimation and specular manifold sampling)
+  are paused and excluded from builds. Behind a wavy refractive surface, each
+  receiver can have dozens of manifold roots; Newton's method finds one, and SMS
+  with its 64-trial cap covered only part of their weight, so neither converged
+  to an unbiased result. The code remains in
+  `src/research/mnee/`, registered explicitly by tests and research scripts. A
+  restart should address multiple roots, for example with manifold path guiding
+  (Fan et al. 2023).
+- **Separate photon denoising**, filtering photon contributions apart from path
+  tracing, increased error in comparisons and is not used.
+- **Photon-count radius scaling**, per-caster radii and larger shrinking screen
+  radii remain internal diagnostics (`causticDiagnostics.ts`). None improved
+  equal-error time on every test scene.
+
+## Changing this code
+
+- The partition runs in WGSL. WebGL traces plain paths and needs no zeroing; its
+  GLSL chain state exists only for the paused MNEE research path.
+- Native shares the WGSL and exposes the same two estimators.
+- Compare raw HDR, not denoised output, when judging energy; see the guide's
+  limits for denoiser artifacts.

package/docs/technical/continuous-spectrum.md

@@ -0,0 +1,122 @@
+# Continuous-wavelength dispersion
+
+MuTracer renders dispersion with continuous wavelengths inside an RGB renderer.
+Wavelength decides how light refracts and how its energy divides between RGB
+channels. Lights, materials and media stay RGB, so this is not spectral rendering.
+The implementation is in `src/renderer/spectrum.ts`, and it runs only when a material
+has `transmissionDispersionScale > 0`.
+
+## Spectral response
+
+`spectrumRgb` converts a wavelength in 400–700 nm to linear sRGB weights:
+
+1. Evaluate the CIE 1931 matching functions with the multi-lobe fit from Wyman, Sloan
+   and Shirley, "Simple Analytic Approximations to the CIE XYZ Color Matching
+   Functions", JCGT 2(2), 2013.
+2. Convert XYZ to linear sRGB and clamp negative values to zero.
+3. Scale each channel so its mean over a uniform wavelength is 1.
+
+The scale keeps white light white on average. The clamp keeps out-of-gamut colors
+saturated instead of colorimetrically exact, and it leaves red with a small violet
+lobe, which is why the short end of a rainbow looks violet instead of blue.
+
+## Sampling
+
+Both integrators sample from 5 nm inverse CDF tables. They use different estimators
+because they carry different quantities.
+
+| | Camera paths | Caustic photons |
+|---|---|---|
+| Distribution | The response of the path's RGB channel | The sum of the RGB responses |
+| Carries | One RGB channel | RGB flux |
+| Energy weight | None; the distribution is the response | `spectrumRgb(λ) / (pdf(λ) · 300)` |
+| Random number | `CAMERA_WAVELENGTH`, shared by a sample's three paths | Photon emission dimension 69 |
+
+Camera paths evaluate no response, so their effective response is a 5 nm histogram of
+the fit. Photons apply the weight exactly. Sharing one random number across a camera
+sample's channels keeps their error correlated with the other common random numbers.
+
+`dispersionWavelengths: 3` traces one path per channel in each sample. With
+`dispersionWavelengths: 1`, a dispersive primary hit selects one channel at random
+and multiplies the result by 3; other primary hits trace full RGB. This is not hero
+wavelength sampling, which carries several wavelengths along one path and combines
+them with MIS.
+
+## Channels and gathering
+
+A path stores its channel and its refracting wavelength separately:
+`spectralChannel` selects the radiance it keeps, and `wavelength` only drives
+`sampling_cauchy_ior`. A channel of 0 keeps full RGB. Red paths can sample violet, so
+the channel cannot be derived from the wavelength.
+
+Photon gathering filters photon flux by the camera path's channel. This splits RGB
+across the camera paths and applies no second spectral weight, so energy is shared
+between path tracing and caustics the same way as without dispersion.
+
+## Shared prefixes
+
+With `dispersionWavelengths: 3`, the three channel paths of a pixel sample are
+identical until the first wavelength-dependent IOR: they use the same random numbers
+and carry full RGB until then. The integrators trace that prefix once, checkpoint
+the path, material, auxiliary outputs and random-stream state at the first
+dispersive interaction, and replay only the wavelength-specific suffix for each
+channel. RGB results completed before any dispersion are reused for all three.
+WGSL replays the suffixes inside the flat, alpha, volume and guide paths; GLSL
+traces all three in one fragment invocation (`spectralPrefix.glsl.ts`). Images are
+the same as with independent paths; only the work is shared. MNEE keeps independent
+paths, because its connection solver can disperse before the camera boundary.
+
+Tracing three suffixes in one WebGL draw makes that draw about three times longer.
+See [WebGL 2 backend](./webgl.md) for the timeout risk this adds on large images.
+
+## Direct-light resampling
+
+Direct lighting selects among `directLightCandidates` light samples by resampled
+importance sampling. When the three channel paths share a prefix, they share one
+reservoir, so the target cannot depend on the channel a path carries. The target
+is the full RGB contribution with equal channel weights; only the final estimator
+keeps the path's channel (`sampleMaterial.wgsl.ts`). A luminance target would
+underweight saturated red and blue light and raise their noise. Equal weights reduce
+that, but a strongly colored region can still converge more slowly in one channel
+than with independent per-channel paths; [sampling](../sampling.md) documents this
+caveat. Single-wavelength previews and non-dispersive renders keep the luminance
+target. WebGL draws one light candidate and has no reservoir.
+
+## Short-wavelength IOR limit
+
+Cauchy IOR rises quickly at short wavelengths. At strong dispersion scales, violet
+light reaches IORs that reflect or trap much of it, and wide caustics turn yellow.
+`spectrumIorWavelength` therefore eases the refracting wavelength below 500 nm toward
+475 nm, while color keeps the sampled wavelength. The mapping is monotonic and
+continuous, so the gradient has no hard edge.
+
+This limit is an artistic choice and not physically based. It narrows the violet end
+of the spectrum, and strong dispersion scales still lose some blue.
+
+## Differences from spectral rendering
+
+| Area | Spectral rendering | MuTracer |
+|---|---|---|
+| Lights | Emission varies with wavelength | RGB, with an implicit broad spectrum; a sodium lamp still disperses into a full rainbow |
+| Materials and textures | Reflectance varies with wavelength, often upsampled from RGB | RGB, so metamerism cannot appear |
+| Media | Absorption and scattering vary with wavelength | Three RGB coefficients |
+| Thin film | Interference is integrated over wavelength | Evaluated at 620, 540 and 450 nm |
+| Refractive index | Often measured curves or Sellmeier equations | Cauchy from IOR and Abbe number, with the short-wavelength limit |
+| Wavelengths per path | Often several, combined with MIS | One per path or photon |
+| Output color | Integrated from the spectrum into the output color space | Fixed clamped sRGB weights, normalized per channel |
+
+These differences matter most for narrow-band lights, colored absorption over long
+paths, metamerism and predictive color. Clear glass and crystal under broad lights are
+closer to the spectral result, because their color comes mainly from refraction.
+
+Full spectral rendering would change the light, material, texture and medium data
+models, and requires RGB-to-spectrum upsampling in both shader backends and native.
+
+## Changing this code
+
+- Update WGSL and GLSL together. Both are generated from `spectrum.ts`; caustics are
+  WGSL only.
+- `spectralChannel` must be set wherever a path's wavelength is set.
+- `tests/unit/spectrum.test.ts` covers white balance, weight bounds, channel
+  distributions and the IOR limit. Check the image result on a real GPU in both
+  backends, as described in `AGENTS.md`.

package/docs/technical/display-upscale.md

@@ -0,0 +1,82 @@
+# Display upscale
+
+`createEasuPass` enlarges a reduced-resolution render to the canvas, and with
+`albedoDetail` it restores surface texture detail from full-resolution color AOVs.
+Usage, costs and limits are in [post-processing](../post-processing.md); the AOV
+side is in [surface color AOVs](./aovs.md). This note explains the algorithm. The
+code is `src/renderer/easu.ts` with `wgsl/easu.wgsl.ts` and
+`wgsl/easuDetail.wgsl.ts`.
+
+## Pipeline position
+
+The pass is a display post-process: it runs after composition, tone mapping and
+denoising, on display-encoded RGB. A pass can change the image size through
+`outputSize`, so the upscale is ordinary chain state and needs no special case in
+composition, export or denoising. Beauty, its denoising and the AOVs keep their own
+resolutions; only the displayed image is enlarged.
+
+An input at the output size is copied, and a larger input is area-averaged, so one
+registration serves both a reduced preview and a full-resolution final render.
+
+## EASU
+
+The enlargement is AMD FidelityFX FSR 1 EASU, without RCAS sharpening. It estimates
+a local edge direction and filters along it with a 12-tap lobe. FSR expects inputs
+in [0, 1], so extended-range output normalizes the neighborhood only for the
+direction estimate and filters the original values. EASU cannot invent detail that
+the reduced render does not contain.
+
+## Detail compensation
+
+Texture detail lost at render resolution is still present in the display-resolution
+`diffuseColor` and `specularColor` AOVs. Compensation transfers it:
+
+1. **Low guides.** The full-resolution colors are area-averaged over each render
+   pixel's exact footprint, including noninteger scales, so the low guides match
+   what beauty integrated. No second AOV allocation is needed.
+2. **Local model.** For each render pixel, a guided-filter regression over a 3×3
+   window fits scene-linear radiance as `slope × color + intercept` per channel.
+   Diffuse shading follows color (slope), while highlights and reflections do not
+   (intercept). Flat colors give a slope near zero, so they are left alone.
+3. **Upsampling.** The low guides are enlarged with exactly the same EASU taps and
+   weights as beauty, so beauty and guides share one footprint.
+4. **Ratio.** At each output pixel, the full-resolution color replaces the
+   upsampled one inside the model: `(slope × hi + intercept) / (slope × low +
+   intercept)`, clamped per channel to [0.7, 1.43]. Without a valid model it falls
+   back to the plain color ratio `hi / low`.
+5. **Display transform.** The ratio is scene-linear, but the image is tone-mapped.
+   A lookup table built from the current tone mapping and grading maps displayed
+   RGB back to scene-linear per channel, applies the ratio and maps it forward, so
+   curve shoulders and toes respond as the tone mapper would. Only the change is
+   added to the displayed value, which keeps it exact where the ratio is 1.
+
+Compensation is skipped, leaving EASU alone, where it would be wrong:
+
+- AOV validity or coverage below 0.95 (transmission, cutouts, background,
+  unsupported materials);
+- silhouettes, detected from a change in hit coverage or a break in the planarity
+  of inverse depth (which is linear in screen space on any plane, so sloped
+  surfaces are not silhouettes);
+- color below 10⁻³, treated as black.
+
+Clipped highlights cannot be recovered: the inverse tone mapping has no
+information above the display maximum.
+
+## Retained alternatives
+
+`createEasuPassImpl` keeps three internal variants for comparisons:
+
+- **Plain color ratio.** Scaling all displayed radiance by `hi / low` also scaled
+  highlights and other light that does not follow color, which limited the usable
+  ratio range. The guided model widened it to the current default.
+- **Separate lobes.** Diffuse and specular ratios weighted by lobe shares estimated
+  from the low colors; beauty has no separate lobes to weight them exactly.
+- **Silhouette reconstruction.** Front and back colors from depth-matched
+  low-resolution neighbors, mixed by full-resolution coverage. It sharpens
+  backgrounds but loses detail on thin structures, glass and reflections
+  compared with EASU alone.
+
+Ratios were first applied to encoded display RGB, which over-darkened dark decals;
+applying them in linear and then through the display transform let the clamp range
+grow. The public tuning options were removed; `EASU_DETAIL` holds the shared
+defaults, which native also uses.

package/docs/technical/openpbr.md

@@ -0,0 +1,99 @@
+# OpenPBR implementation
+
+`OpenPBRMaterial` follows the OpenPBR Surface specification with a compact GPU
+BSDF. Parameters, units and user-facing limits are in the
+[materials guide](../materials.md); this note describes how the implementation
+is organized and the rules for changing it.
+
+## Data flow
+
+- **Layout table.** `materialLayoutSchema.ts` lists every material buffer row
+  (one `vec4` each) with its source field and type. The same table generates the
+  TypeScript packing, the WGSL struct (`materialBufferWgsl`) and the GLSL row
+  constants (`materialRowsGlsl`), so the three cannot drift. Reserved rows keep
+  their legacy contents; reusing one is an intentional migration.
+- **Texture slots.** `materialTextureSlots.ts` lists every map with its target
+  parameters, channels, color space, shader define and feature bit. Slot order is
+  the atlas index contract. Public map names live in the scene layer
+  (`materialTextureNames.ts`).
+- **Feature specialization.** Features that a scene does not use, such as
+  anisotropy directions or coat normals, are compiled out by generating different
+  WGSL source, not by patching strings after generation.
+
+## BSDF
+
+The BSDF (`openPbrBsdf.wgsl.ts` and its GLSL counterpart) follows the
+prepare/eval/sample/pdf organization of Adobe's
+[openpbr-bsdf](https://github.com/adobe/openpbr-bsdf) and the
+[OpenPBR viewer](https://github.com/portsmouth/OpenPBR-viewer):
+
+- `openpbr_prepare` resolves the layered material once per path vertex. NEE, BSDF
+  sampling and MIS reuse the result, which made WebGPU samples about 11–15% faster
+  than preparing per evaluation.
+- The lobes are fuzz, coat, metal, dielectric specular, transmission, diffuse and
+  subsurface. Their weights and probabilities are stored as arrays indexed by lobe,
+  rather than one variable per lobe.
+- Metal uses the F82-tint Fresnel; specular anisotropy uses the specification's
+  roughness mapping. The coat roughens the base, changes the IOR ratio below it,
+  absorbs, and darkens through internal reflection (`coatDarkening`, default 1).
+- Fuzz uses an analytic approximation. The specification's LTC fuzz (Zeltner et al.
+  2022) is not implemented.
+
+## Energy compensation
+
+GGX loses energy to single scattering as roughness grows. The renderer uses Adobe's
+tables for opaque dielectric base coupling, ideal-metal multiple scattering and
+solid ideal-dielectric reflection and transmission (`openPbrEnergyLut.ts`). Before
+these tables, rough glass lost 5–36% and rough metal 1.5–20% of its energy in white
+furnace tests.
+
+The tables are stored as 8-bit samples normalized per row, with 16-bit row bounds,
+differences between consecutive rows and exact 16-bit averages. This keeps the
+module about 44 KB gzipped while adding the multiple-scattering tables. On the GPU
+they occupy about 280 KB.
+
+Thin-walled rough transmission has no compensation, as in the reference.
+
+## Import decisions
+
+- Three.js and glTF clearcoat import with `coatDarkening = 0`, because glTF's
+  clearcoat does not darken the base. `userData.mutracerOpenPBR` overrides it.
+- Specification names (`specularRoughnessAnisotropy`, `coatRoughnessAnisotropy`,
+  `subsurfaceScatterAnisotropy`, `geometryOpacity`, `geometryThinWalled`) are the
+  primary names; older names remain deprecated aliases.
+- glTF anisotropy is converted after texture sampling, selected by
+  `specularAnisotropyModel: 'gltf'`.
+
+## Not implemented
+
+- Statistical mixing of two materials.
+- LTC fuzz.
+- Resampled direct lighting on WebGL. It waits for the cause of a small diffuse
+  residual with 8 or 16 WebGPU light candidates; the default of 4 is unaffected.
+
+## Known accuracy limits
+
+- Rough solid glass remains slightly dark in white furnace tests, under 1% without
+  a coat and under 1.5% with one at roughness 0.3. With compensation off it is
+  about 2 percentage points darker than the reference, so the remaining loss is in
+  the transmission integration, not the tables.
+- Strongly tilted coat normals lose about 5% of their energy, because lobes are
+  clipped to the geometric hemisphere. The materials guide documents this.
+- Strong anisotropic metal can retain a small energy error, because the tables use
+  isotropic roughness.
+- A coat with a higher IOR than the base can produce spurious total internal
+  reflection in the thin film, as in the reference.
+
+## Acceptance rules
+
+These maintainer rules apply to material and BSDF changes:
+
+- A white furnace may deviate from 1 by at most 0.5%, and a coated material from
+  its uncoated control by at most 0.5%.
+- Re-encoding the tables may change any material on either backend by at most 0.1%.
+- Measure cold shader compilation with caches invalidated; increases above 10% need
+  a maintainer decision.
+- Sparse pixel differences of at most one half-float step from compiler
+  reassociation are acceptable.
+- Refactors keep default materials (base weight 1, no coat, isotropic, specular
+  color 1) pixel-identical on both backends.

package/docs/technical/pbrt-import.md

@@ -0,0 +1,168 @@
+# PBRT import mapping
+
+This contributor note describes the viewer/tool importer. Usage and limits are
+in [the tool guide](../../tools/pbrt/README.md).
+
+## Coordinates and state
+
+The reference is `mmp/pbrt-v4@b0bdf461ba5dd6504b70ebf0932acc0fe7aa744f`.
+PBRT's camera looks along local +Z. With `M = diag(1,1,-1,1)`, geometry uses
+`M * objectToWorld` and the Three camera uses `M * cameraToWorld * M`.
+The world reflection is baked into geometry so emissive triangles have consistent
+world-space winding and normals. The winding changes when the baked transform
+changes handedness, XOR `ReverseOrientation`; explicit normals only change sign
+for `ReverseOrientation`. Triangle winding is then face-forwarded to shading
+normals, matching PBRT meshes with authored N. Instances retain shared geometry
+and use `M * T * M`.
+Loop shapes refine the control mesh and push vertices to the limit surface;
+area-weighted normals approximate the reference limit-surface tangents.
+A reflection is absorbed into a geometry variant for negative instance transforms.
+
+`LookAt` sets world-to-camera, so its inverse is captured at `Camera`. `WorldBegin`
+resets the object transform. Include filenames and all asset filenames resolve
+against the main scene directory, as `SetSearchDirectory`/`ResolveFilename` do.
+`Import` inherits graphics state but restores it afterward; definitions and scene
+objects remain. Deprecated transform blocks follow PBRT-v4's attribute-block
+rewrite. Only the start transform is retained for animated scenes.
+
+## Camera and microfacets
+
+For aspect `a = width/height`, the vertical field of view is `fov` when `a >= 1`,
+otherwise `2 atan(tan(fov/2)/a)`. Lens conversion uses a 24 mm sensor height:
+`focalLength = .024/(2 tan(verticalFov/2))` metres and
+`fStop = focalLength/(2 lensRadius)` for metre scene units.
+The focus distance stays in scene units. The linear exposure multiplier is
+`ISO/100 * (shutterClose-shutterOpen)`. Film exposuretime is not a PBRT-v4
+parameter and is warned and ignored, as is whitebalance. Unsupported sensors
+produce a separate warning.
+
+The pinned `TrowbridgeReitzDistribution::RoughnessToAlpha` returns `sqrt(r)`.
+Since OpenPBR uses `alpha = roughness²`, the imported roughness is `r^(1/4)` with
+remapping and `sqrt(r)` without it. For anisotropic alphas, the scalar roughness
+is `((alphaU²+alphaV²)/2)^(1/4)` and anisotropy is
+`1-min(alphaU,alphaV)/max(alphaU,alphaV)` (zero for two zero axes). This inverts
+OpenPBR's RMS-preserving formula for both base and coat. The larger alpha is
+assigned to the tangent axis; rotation is π/2 when v is larger, so u stays dpdu.
+Anisotropic meshes also carry UV-derived tangents for the zero-rotation path.
+
+## Colors and light units
+
+RGB inputs are linear sRGB. RGB illumination preserves the RGB multiplier;
+PBRT normalizes the illuminant separately in `SpectrumToPhotometric`. The pinned
+implementation does **not** multiply this integral by 683. The Film's CIE sensor
+integrates the emitted spectrum; this cancels the illuminant normalization for
+white light. Consequently a point light's RGB intensity maps directly to the
+zero-radius SphereLight intensity, and an area light's RGB radiance maps to mesh
+emission. Spot cone angles are half angles and use cosine smoothstep on both sides.
+Distant intensity is irradiance facing the light. Sphere emitters retain meshes:
+MuTracer analytic sphere lights currently do not supply visible primary-ray
+emission, and adding a second emissive sampler would count the source twice.
+
+Power multiplies point intensity by `power/(4π)`. For a spot it multiplies by
+`power/[2π(1-(cos(inner)+cos(outer))/2)]`. Area-light power divides by
+`π * area * (twosided ? 2 : 1)`. Image emission also requires texture-average
+normalization; that case remains an approximation. Constant environment
+illuminance multiplies radiance by `illuminance/π`. Image illuminance follows
+the pinned renderer's `2π/N * sum(Y(pixel)*max(z,0))` normalization in light space.
+
+Named optical data and CIE/D65 tables come from the pinned Apache-2.0 source.
+Conductor normal and edge reflectances integrate Fresnel at cosines 1 and 1/7
+under D65, then convert XYZ to linear sRGB. OpenPBR takes an F82 **tint**,
+so the edge value is divided by `F0+(1-F0)*(6/7)^5` and limited to [0,1]. Glass uses interpolated eta at
+587.56 nm and Abbe `(etaD-1)/(etaF-etaC)`, at 486.13 and 656.27 nm.
+Blackbody emission is normalized to unit luminance before light scaling.
+An RGB renderer and PBRT's spectral renderer can retain material-dependent
+biases; comparisons report them without changing either renderer's algorithms.
+Coated conductor inputs keep `conductor.*` substrate parameters separate from
+`interface.*` coat parameters. Both roughness layers use the same remap rule;
+optical constants are read as curves from named data or SPD files before Fresnel
+integration. Coat IOR and anisotropy use the existing OpenPBR metadata fields.
+
+For coefficient-based subsurface materials, each RGB extinction mean free path is
+`1 / (scale * (sigma_a + sigma_s))`. The largest channel becomes the OpenPBR
+radius and channel ratios become radius scales. Single-scattering albedo
+`sigma_s / (sigma_a + sigma_s)` is converted to the artist-facing subsurface color
+by inverting the existing material packer's mapping. Authored diffuse reflectance
+is already an effective scattering color. These mappings preserve the RGB medium
+coefficients but do not reproduce PBRT's spectral diffusion model.
+Interior homogeneous media encode total extinction, not absorption, in
+transmission color: choose depth `d=1/max(1,max(sigma_t))`, set color
+`exp(-sigma_t*d)` and scatter color `sigma_s/sigma_t`, with scaled coefficients.
+This preserves the existing packer's coefficients without hitting its color floor.
+`MediumInterface` orders inside then outside. The geometric normal points toward
+outside, after ReverseOrientation and handedness. The importer rejects scenes
+with a camera medium. If only an outside medium remains, conversion flips
+winding and normals together and encodes it as the material interior. Two
+media cannot be represented: conversion warns and uses inside only.
+Material variants include both names to avoid sharing different boundaries.
+
+The extra medium-side reversal reciprocates thick dielectric IOR: PBRT's
+DielectricBxDF exchanges eta across its final normal. ReverseOrientation and
+coordinate handedness already affect both normals and do not independently
+reciprocate IOR. ThinDielectricBxDF uses AbsCosTheta and keeps eta unchanged.
+Base specular IOR below one survives Three conversion and material packing;
+both backends use the ratio for Fresnel, total internal reflection and refraction.
+Coat IOR is clamped to at least one and the coat is exterior-only, so reversed
+coats and coat IOR below one receive an ior-orientation warning and are excluded
+from strict comparison. Reciprocal spectral dispersion retains the original
+Abbe number, but a reciprocal Cauchy curve is not itself the same Cauchy fit;
+this receives an ior-dispersion approximation warning and comparison exclusion.
+
+Ordinary PBRT surfaces accept primary back-face hits. One-sided area emission
+uses FrontSide because MuTracer couples primary visibility and emission sidedness;
+its missing back-side surface visibility is warned about.
+
+PBRT image textures evaluate `(s,1-t)`. Decoded images use top-down rows and
+Three textures set `flipY=true`. Infinite lights use the equal-area square map,
+reprojected to world-space latitude/longitude. The direct importer uses nearest
+source lookup to match ImageInfiniteLight. Each target texel averages 4×4
+jittered samples uniform in azimuth and cos(theta), then per-channel spherical
+integrals correct residual quadrature energy error. Source texels use area 4π/N;
+target bands use exact cosine differences. This preserves small bright features'
+total energy while approximating their subpixel distribution. The existing glTF
+metadata adapter retains its previous bilinear reprojection.
+
+Material displacement uses forward UV finite differences with PBRT's `.0005`
+fallback step, including scalar texture scale and UV repeat. The image-row
+v derivative changes sign for `(s,1-t)`. The result is a tangent normal
+`normalize(-dh/du,-dh/dv,1)`, never a geometric height field. This static bake
+assumes unit tangents and omits footprint-dependent steps and curvature terms;
+it is warned and excluded from strict comparison. Only shape displacement uses
+the height-field mapping. In the pinned `interaction.cpp`, NormalMap and BumpMap
+are alternatives (`if/else`): normalmap takes precedence when both exist.
+
+## Comparison and memory
+
+Ordinary byte color maps retain their original data and declared color space;
+unmodified linear HDR maps also share decoded pixel data. Scale graphs carry
+separate multipliers. Scalar and transformed maps retain
+floating-point values. Rectangular/non-power-of-two height fields are resampled
+to the existing displacement layout, with a warning.
+
+The comparison sets PBRT's pixel filter to box with radius 0.5 to match MuTracer's
+uniform pixel jitter. It overrides spp and output resolution, removes Film crop
+windows and pixel bounds, preserves maxdepth,
+sets an opaque black background when no environment exists, removes Film sensor exposure from the reference HDR and never tone maps numerical
+inputs. AOV material IDs identify approximate surface regions. This primary-hit
+mask does not isolate indirect paths that touch approximate materials. PBRT uses
+seeds 0/1; MuTracer uses disjoint sample blocks starting at 0/N with the same Sobol
+scramble. Their difference gives a diagnostic noise estimate, not independent
+Monte Carlo replicas or statistical proof of equivalence.
+Whole-frame RMSE retains every comparable pixel and its noise margin. Regional
+material/tile tests exclude discontinuities in object, instance or material IDs,
+dilated by one pixel. Their statistic is absolute channel mean bias / standard
+error, with threshold 6. Standard error is sqrt(sum of per-pixel replica-difference
+variances) / pixel count; squaring a region-sum difference instead gives an
+unstable single observation. Whole-frame and regional statuses are separate.
+Each MuTracer run uses a fresh Chrome process to avoid retaining both scenes' caches
+and allocations during memory measurement.
+
+Text and gzip Includes are decoded by statements to avoid the single-string size
+limit. The viewer parses them and PLY data in a Worker. Inline P/N/UV/index
+arrays become
+transferable typed views before leaving the Worker; statement locations share
+the same parameter objects. Binary assets are prefetched six at a time before
+conversion; progress sums completed and in-flight bytes. The download preflight
+uses unique encoded input sizes and an 8x expansion estimate against an 8 GiB
+working budget. This estimate is deliberately conservative and cannot predict
+total process/GPU memory or prevent every browser allocation failure.