@woosh/meep-engine 3.14.3 → 3.14.5

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.14.3",
+  "version": "3.14.5",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/mat4/m4_rigidity_defect.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How far a matrix's linear part is from a rotation — zero for a rigid motion, and growing with
+ * whatever else is in there.
+ *
+ * A rigid motion's upper 3×3 is orthonormal: three unit columns, mutually perpendicular. The defect
+ * is the largest violation of that, over the six facts it comes down to — three lengths against 1,
+ * three pairwise dot products against 0 — so it is scale-free in the sense that matters: a matrix
+ * scaled by `s` reports `|s − 1|`, and a shear reports the cosine of how far the columns have fallen
+ * out of square, whatever the scale.
+ *
+ * Not a norm and not a distance to the nearest rotation. It is a **test statistic**: one number that
+ * is zero exactly when the matrix is rigid, that grows monotonically with the thing you would want
+ * to see, and that can be compared against a tolerance without knowing what shape the matrix is. The
+ * translation is not read — a translation is rigid.
+ *
+ * ## Why this exists
+ *
+ * `dual_quat_from_m4` reads a matrix's upper 3×3 as if it were a rotation. Handed anything else it
+ * answers a rotation anyway — a wrong one, from `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms the
+ * scale has swamped — with no signal that it did. This is how a caller finds out first. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * A **reflection** reports zero: it is orthonormal, and this measures orthonormality. Callers who
+ * care about handedness want the determinant's sign, which is a different question.
+ *
+ * @param {ArrayLike<number>} mat4 column-major, 16 elements
+ * @returns {number} 0 for a rigid motion; larger the further from one
+ */
+export function m4_rigidity_defect(mat4: ArrayLike<number>): number;
+//# sourceMappingURL=m4_rigidity_defect.d.ts.map

package/src/core/geom/3d/mat4/m4_rigidity_defect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m4_rigidity_defect.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/mat4/m4_rigidity_defect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yCAHW,UAAU,MAAM,CAAC,GACf,MAAM,CA0ClB"}

package/src/core/geom/3d/mat4/m4_rigidity_defect.js

@@ -0,0 +1,71 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * How far a matrix's linear part is from a rotation — zero for a rigid motion, and growing with
+ * whatever else is in there.
+ *
+ * A rigid motion's upper 3×3 is orthonormal: three unit columns, mutually perpendicular. The defect
+ * is the largest violation of that, over the six facts it comes down to — three lengths against 1,
+ * three pairwise dot products against 0 — so it is scale-free in the sense that matters: a matrix
+ * scaled by `s` reports `|s − 1|`, and a shear reports the cosine of how far the columns have fallen
+ * out of square, whatever the scale.
+ *
+ * Not a norm and not a distance to the nearest rotation. It is a **test statistic**: one number that
+ * is zero exactly when the matrix is rigid, that grows monotonically with the thing you would want
+ * to see, and that can be compared against a tolerance without knowing what shape the matrix is. The
+ * translation is not read — a translation is rigid.
+ *
+ * ## Why this exists
+ *
+ * `dual_quat_from_m4` reads a matrix's upper 3×3 as if it were a rotation. Handed anything else it
+ * answers a rotation anyway — a wrong one, from `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms the
+ * scale has swamped — with no signal that it did. This is how a caller finds out first. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * A **reflection** reports zero: it is orthonormal, and this measures orthonormality. Callers who
+ * care about handedness want the determinant's sign, which is a different question.
+ *
+ * @param {ArrayLike<number>} mat4 column-major, 16 elements
+ * @returns {number} 0 for a rigid motion; larger the further from one
+ */
+export function m4_rigidity_defect(mat4) {
+    assert.isArrayLike(mat4, 'mat4');
+
+    const x0 = mat4[0], x1 = mat4[1], x2 = mat4[2];
+    const y0 = mat4[4], y1 = mat4[5], y2 = mat4[6];
+    const z0 = mat4[8], z1 = mat4[9], z2 = mat4[10];
+
+    const length_x = Math.sqrt(x0 * x0 + x1 * x1 + x2 * x2);
+    const length_y = Math.sqrt(y0 * y0 + y1 * y1 + y2 * y2);
+    const length_z = Math.sqrt(z0 * z0 + z1 * z1 + z2 * z2);
+
+    let defect = Math.abs(length_x - 1);
+
+    defect = Math.max(defect, Math.abs(length_y - 1));
+    defect = Math.max(defect, Math.abs(length_z - 1));
+
+    /*
+     The dot products are normalized by the column lengths so that the two halves of the answer are
+     in the same units — a cosine rather than a product of magnitudes. Without it a matrix at a large
+     scale would report its shear multiplied by that scale squared, and a tolerance chosen for one
+     model would mean something else on the next. A degenerate column has no direction to be square
+     to; its zero length has already been counted.
+    */
+    const scale_xy = length_x * length_y;
+    const scale_yz = length_y * length_z;
+    const scale_zx = length_z * length_x;
+
+    if (scale_xy > 0) {
+        defect = Math.max(defect, Math.abs(x0 * y0 + x1 * y1 + x2 * y2) / scale_xy);
+    }
+
+    if (scale_yz > 0) {
+        defect = Math.max(defect, Math.abs(y0 * z0 + y1 * z1 + y2 * z2) / scale_yz);
+    }
+
+    if (scale_zx > 0) {
+        defect = Math.max(defect, Math.abs(z0 * x0 + z1 * x1 + z2 * x2) / scale_zx);
+    }
+
+    return defect;
+}

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";AAsDA;IAoEI;;;;;;;;OAQG;IACH,8FANW,aAAa,EA4NvB;IA7QD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAmBrC;;;OAGG;IACH,yBAAwB;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,mBAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IA4BF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IAWD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAgGhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BAgCC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eA6BC;IAED;;;OAGG;IACH,sBAkEC;IAqBD;;OAEG;IACH,sBAkCC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAvrB8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;6BAFnD,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAlC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;8BAItC,wBAAwB;4BAX1B,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";AAsDA;IAoEI;;;;;;;;OAQG;IACH,8FANW,aAAa,EA4NvB;IA7QD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAmBrC;;;OAGG;IACH,yBAAwB;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,mBAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IA4BF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IAWD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAgGhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BAgCC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eA6BC;IAED;;;OAGG;IACH,sBAkEC;IAqBD;;OAEG;IACH,sBAyCC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA9rB8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;6BAFnD,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAlC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;8BAItC,wBAAwB;4BAX1B,kCAAkC;oBAH1C,yBAAyB"}