BufferGeometryUtils: Add MikkTSpace version of .computeTangents()

[donmccurdy]

Summary: Adds a computeTangents( geometry ) function to BufferGeometryUtils, implementing the MikkTSpace standard for vertex tangents used with tangent space normal maps.

Background: Vertex tangents are used when baking normal maps, but often those original tangents are not included in the model itself. While a different method of computing tangents will usually look "close" to the right result, in some cases (particularly with mirrored UVs) you may see seams or other visual problems. The only way to completely avoid those problems is to use exactly the same vertex tangents as the normal map baker. For that purpose, MikkTSpace is the de facto standard — it is open source, widely used, and is designed to return the same tangents even when certain changes (like reordering vertices) have been made to the underlying geometry.

Currently this PR does not remove the existing geometry.computeTangents() method. The new function is added to BufferGeometryUtils instead, because the size of the MikkTSpace WASM module (from mikktspace-wasm) is about 21 KB gzipped.

Note that calculating vertex tangents is somewhat costly — on my machine it takes 75ms for the DamagedHelmet.glb sample. Any existing geometry index must be removed, although the index can be recomputed after generating tangents. For those reasons, most users probably should not blindly compute vertex tangents in the hope it will make their normal maps look better — where possible, compute tangents offline with tools like gltf-transform tangents or Blender, and omit tangents when there's no benefit.

This PR also borrows a denormalize() function from #22874.

Usage:

import { computeTangents } from 'three/examples/jsm/utils/BufferGeometryUtils.js';

geometry = computeTangents( geometry );

Related:

• BufferGeometry: Allow computeTangents to be called without an Index attribute #22816
• Seams with normal map and mirrored uvs #18565
• Models appear washed out/metallic on certain android devices #20997
• Normals flipped on some parts of the mesh that have double sided materials #17804
• Rendering issue with normals and DoubleSided materials on some Adreno GPU series #15850
• Allow GLTFLoader to import tangents or make BufferGeometryUtils.computeTangents use the Mikktspace algorithm #15428
• GLTFLoader: Normal-Tangent Test model result is incorrect #11438

[donmccurdy]

One other note – the build script will skip mikktspace.module.js, leaving examples/js/utils/BufferGeometryUtils.js depending on an undefined global generateTangents function when used from the examples/js/* directory. So users not importing ES Modules would need to define that with a modified build of the mikktspace npm package. The mikktspace package only publishes CJS (for Node.js) and ES Module builds currently.

[gkjohnson]

This would be nice to get merged. I'd like to use it for my path tracing work for meshes with normal maps that don't already have tangents generated. I'm looking at other ways to generate them as-needed in the shader but this would be a good start.

Would like to see it in the next release 😁 🙏

[mrdoob]

Thanks!

[gkjohnson]

Looks like this doesn't work with bundlers that don't support top level await at the moment... which Parcel doesn't, at least (argh!)

parcel-bundler/parcel#4028

[gkjohnson]

Oh... which actually means that BufferGeometryUtils can't be imported into a project at all without breaking it in one of these bundlers.

[donmccurdy]

Oh... which actually means that BufferGeometryUtils can't be imported into a project at all without breaking it in one of these bundlers...

Hm, BufferGeometryUtils is all individual exports now — is access to methods other than computeTangents broken in Parcel with v139 as well?

import { mergeBufferGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';

Looks like this doesn't work with bundlers that don't support top level await at the moment...

Ugh, I thought top-level await was just part of the ES Modules spec. 🤦‍♂️ I don't suppose dynamic imports or .wasm imports are better supported? Would rather not do the Base64 decode and WASM instantiation synchronously on the main thread... I guess our other option would be to make the MikkTSpace dependency explicit:

import { MikkTSpace } from 'three/examples/jsm/libs/mikktspace.module.js';
import { computeTangents } from 'three/examples/jsm/utils/BufferGeometryUtils.js';

async function someUserCode() {

  await MikkTSpace.ready;
 
  // ...

  geometry = computeTangents( geometry, MikkTSpace );

}

Also note — there's currently a bug with non-indexed geometry, #23795.

[LeviPesin]

Ugh, I thought top-level await was just part of the ES Modules spec. 🤦‍♂️ I don't suppose dynamic imports or .wasm imports are better supported?

I think that dynamic imports (if you are talking about import()) are supported pretty much everywhere.

[donmccurdy]

In browsers, yes — but like top-level await it will also depend on your bundler to rewrite URLs correctly. I guess in this case it doesn't matter, we probably want computeTangents itself to be synchronous, so we couldn't put in a dynamic import. Unless/until importing .wasm files directly is widely supported, let's do the userland await MikkTSpace.ready; option?

[gkjohnson]

I'm okay with MikkTSpace.ready.

is access to methods other than computeTangents broken in Parcel with v139 as well?

Yup -- just importing the file causes the issue.

Ugh, I thought top-level await was just part of the ES Modules spec.

Heh, we can dream 😁 Some day new enabling JS features will just work.