@gltf-transform/functions - npm Package Compare versions

Comparing version 3.4.8 to 3.5.0

dist/weld.d.ts

 import { Document, Primitive, Transform } from '@gltf-transform/core';
 /** Options for the {@link weld} function. */
 export interface WeldOptions {
-    /** Tolerance, as a fraction of primitive AABB, used when merging similar vertices. */
+    /** Tolerance for vertex positions, as a fraction of primitive AABB. */
     tolerance?: number;
+    /** Tolerance for vertex normals, in radians. */
+    toleranceNormal?: number;
     /** Whether to overwrite existing indices. */
@@ -21,5 +23,9 @@ overwrite?: boolean;
  * of the AABB's longest dimension. Other vertex attributes are also compared
- * during welding, with attribute-specific thresholds. For --tolerance=0, geometry
+ * during welding, with attribute-specific thresholds. For `tolerance=0`, geometry
  * is indexed in place, without merging.
  *
+ * To preserve visual appearance consistently, use low `toleranceNormal` thresholds
+ * around 0.1 (±3º). To pre-processing a scene before simplification or LOD creation,
+ * use higher thresholds around 0.5 (±30º).
+ *
  * Example:
@@ -31,3 +37,3 @@ *
  * await document.transform(
- * 	weld({ tolerance: 0.001 })
+ * 	weld({ tolerance: 0.001, toleranceNormal: 0.5 })
  * );
@@ -34,0 +40,0 @@ * ```

package.json

 {
 	"name": "@gltf-transform/functions",
-	"version": "3.4.8",
+	"version": "3.5.0",
 	"repository": "github:donmccurdy/glTF-Transform",
@@ -38,5 +38,5 @@ "homepage": "https://gltf-transform.dev/functions.html",
 	"dependencies": {
-		"@gltf-transform/core": "^3.4.8",
-		"@gltf-transform/extensions": "^3.4.8",
-		"ktx-parse": "^0.5.0",
+		"@gltf-transform/core": "^3.5.0",
+		"@gltf-transform/extensions": "^3.5.0",
+		"ktx-parse": "^0.6.0",
 		"ndarray": "^1.0.19",
@@ -56,3 +56,3 @@ "ndarray-lanczos": "^0.3.0",
 	},
-	"gitHead": "7f2f55fa5073ccc57926b293fa99e2bde998cc11"
+	"gitHead": "8fcc53cfd29649aa3174997fe17138b47897db4a"
 }

src/weld.ts

@@ -51,3 +51,3 @@ import {
 	COLOR: 0.01, // [0, 1]
-	NORMAL: 0.5, // [-1, 1]
+	NORMAL: 0.05, // [-1, 1], ±3º
 	JOINTS: 0.0, // [0, ∞]
@@ -59,4 +59,6 @@ WEIGHTS: 0.01, // [0, ∞]
 export interface WeldOptions {
-	/** Tolerance, as a fraction of primitive AABB, used when merging similar vertices. */
+	/** Tolerance for vertex positions, as a fraction of primitive AABB. */
 	tolerance?: number;
+	/** Tolerance for vertex normals, in radians. */
+	toleranceNormal?: number;
 	/** Whether to overwrite existing indices. */
@@ -70,2 +72,3 @@ overwrite?: boolean;
 	tolerance: Tolerance.DEFAULT,
+	toleranceNormal: Tolerance.NORMAL,
 	overwrite: true,
@@ -84,5 +87,9 @@ exhaustive: false, // donmccurdy/glTF-Transform#886
  * of the AABB's longest dimension. Other vertex attributes are also compared
- * during welding, with attribute-specific thresholds. For --tolerance=0, geometry
+ * during welding, with attribute-specific thresholds. For `tolerance=0`, geometry
  * is indexed in place, without merging.
  *
+ * To preserve visual appearance consistently, use low `toleranceNormal` thresholds
+ * around 0.1 (±3º). To pre-processing a scene before simplification or LOD creation,
+ * use higher thresholds around 0.5 (±30º).
+ *
  * Example:
@@ -94,3 +101,3 @@ *
  * await document.transform(
- * 	weld({ tolerance: 0.001 })
+ * 	weld({ tolerance: 0.001, toleranceNormal: 0.5 })
  * );
@@ -104,6 +111,15 @@ * ```
 
-	if (options.tolerance > 0.1 || options.tolerance < 0) {
+	if (options.tolerance < 0 || options.tolerance > 0.1) {
 		throw new Error(`${NAME}: Requires 0 ≤ tolerance ≤ 0.1`);
 	}
 
+	if (options.toleranceNormal < 0 || options.toleranceNormal > Math.PI / 2) {
+		throw new Error(`${NAME}: Requires 0 ≤ toleranceNormal ≤ ${(Math.PI / 2).toFixed(2)}`);
+	}
+
+	if (options.tolerance > 0) {
+		options.tolerance = Math.max(options.tolerance, Number.EPSILON);
+		options.toleranceNormal = Math.max(options.toleranceNormal, Number.EPSILON);
+	}
+
 	return createTransform(NAME, async (doc: Document): Promise<void> => {
@@ -190,7 +206,6 @@ const logger = doc.getLogger();
 
-	const baseTolerance = Math.max(options.tolerance, Number.EPSILON);
 	const attributeTolerance: Record<string, number> = {};
 	for (const semantic of prim.listSemantics()) {
 		const attribute = prim.getAttribute(semantic)!;
-		attributeTolerance[semantic] = getAttributeTolerance(semantic, attribute, baseTolerance);
+		attributeTolerance[semantic] = getAttributeTolerance(semantic, attribute, options);
 	}
@@ -334,6 +349,6 @@
 /** Computes a per-attribute tolerance, based on domain and usage of the attribute. */
-function getAttributeTolerance(semantic: string, attribute: Accessor, tolerance: number): number {
+function getAttributeTolerance(semantic: string, attribute: Accessor, options: Required<WeldOptions>): number {
 	// Attributes like NORMAL and COLOR_# do not vary in range like POSITION,
 	// so do not apply the given tolerance factor to these attributes.
-	if (semantic === 'NORMAL' || semantic === 'TANGENT') return Tolerance.NORMAL;
+	if (semantic === 'NORMAL' || semantic === 'TANGENT') return options.toleranceNormal;
 	if (semantic.startsWith('COLOR_')) return Tolerance.COLOR;
@@ -347,4 +362,5 @@ if (semantic.startsWith('TEXCOORD_')) return Tolerance.TEXCOORD;
 	attribute.getMaxNormalized(_b);
-	const range = Math.max(..._b) - Math.min(..._a) || 1;
-	return tolerance * range;
+	const diff = _b.map((bi, i) => bi - _a[i]);
+	const range = Math.max(...diff);
+	return options.tolerance * range;
 }
@@ -351,0 +367,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1351308

increased by0.31%

Lines of code

7378

increased by0.33%

Dependency changes

• - Removedktx-parse@0.5.0(transitive)

• Updated@gltf-transform/core@^3.5.0

• Updated@gltf-transform/extensions@^3.5.0

• Updatedktx-parse@^0.6.0