Skip to content

Match Cycles' Normal Map node tangent frame (codepawl/crucible#1111) - #57

Merged
anxuanng merged 1 commit into
mainfrom
1111-normal-map
Nov 16, 2026
Merged

anxuanng merged 1 commit into
mainfrom
1111-normal-map

Conversation

@anxuanng

Copy link
Copy Markdown
Contributor

Part of codepawl/crucible#1111.

What was wrong

Cycles builds the tilted normal of a tangent-space normal map in object space and moves it to world space as a normal (inverse transpose). On an instance with a non-uniform scale the tilt shrinks along the stretched axes. Cook moved the tangent as a vector and rebuilt the bitangent from the world normal, so the same map tilted the normal more than in Cycles.

The fix

The shading point carries normal_map_tangent and normal_map_bitangent: the object-space tangent and cross(normal, tangent) * sign, moved with the inverse transpose and divided by the length of the moved normal. tangent * x + bitangent * y + normal * z then equals the Normal Map node. The base and coat normal maps read it; bump and anisotropy keep the old frame.

How I checked it

  • node tools/run-cargo-tests.mjs: 140 + 23 passed, including a new test of the kernel text.
  • Parity against Cycles 5.3 (480 x 270, 256 spp, seed 1), a plane scaled 1.8 x 1.8 x 1 with a bumpy normal map, traced as instances:
scene mean ratio relMSE tiles over 5%
plane, before (flattened or instanced) 0.956 0.0032 15 of 64
plane, after (instanced) 1.0015 4e-6 0 of 64
plane, constant tilt along the tangent, before 0.916 0.0052 31 of 64
plane, constant tilt along the tangent, after 1.0022 5e-6 0 of 64
  • A flattened scene (matrix baked into the vertices before packing) never reaches this path and is unchanged byte for byte.
  • Not fixed: a UV sphere with a normal map still shows 5 of 64 tiles over 5% (worst 1.12) against Cycles after this change. The sphere has a uniform scale, so it is a different cause (tangent generation near the poles is the suspect, not yet measured).

The Crucible side (parity scenes, Normal Map node in render-cycles.py, evidence) is in the Crucible pull request.

Cycles builds the tilted normal of a tangent-space normal map in object space
(unnormalised vertex normal, UV tangent and handedness) and moves the result to
world space as a normal. On an instance with a non-uniform scale the tilt shrinks
along the stretched axes. Cook moved the tangent as a vector and rebuilt the
bitangent from the world normal, so such a mesh was lit with the full tilt.

The shading point now carries normal_map_tangent and normal_map_bitangent: the
object-space tangent and cross(normal, tangent) * sign, moved with the inverse
transpose and divided by the length of the moved normal, so
tangent * x + bitangent * y + normal * z is the node's result. The base normal
map and the coat normal map read it; bump and anisotropy keep the old frame.

Measured against Cycles 5.3 at 480x270, 256 spp: a normal-mapped plane scaled
1.8 x 1.8 x 1 went from mean ratio 0.956, relMSE 0.0032 and 15 of 64 tiles over
5 percent to mean 1.0015, relMSE 4e-6 and 0 tiles over. Only instanced scenes
reach this path; a flattened scene has the matrix baked into the vertices.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant