@flighthq/mesh 0.3.0 → 0.3.1-next.1041.35b950c

package/src/meshGeometryBuilders.test.ts

@@ -1,4 +1,4 @@
-import type { MeshGeometry } from '@flighthq/types/contract';
+import type { MeshGeometry, MeshTriangleVertexIndices } from '@flighthq/types/contract';
 
 import { getMeshGeometryIndexCount, getMeshGeometryVertexCount } from './meshGeometry';
 import {
@@ -20,6 +20,8 @@ import {
   createTorusKnotMeshGeometry,
   createTorusMeshGeometry,
 } from './meshGeometryBuilders';
+import { getMeshGeometryTriangleCount, getMeshGeometryTriangleVertexIndices } from './meshGeometryOperations';
+import { validateMeshGeometry } from './meshGeometryOperations';
 
 function expectUnitNormals(geometry: Readonly<MeshGeometry>): void {
   const count = getMeshGeometryVertexCount(geometry);
@@ -42,6 +44,10 @@ function expectUnitTangents(geometry: Readonly<MeshGeometry>): void {
   }
 }
 
+function expectFiniteCanonicalRecord(geometry: Readonly<MeshGeometry>): void {
+  for (const value of geometry.vertices) expect(Number.isFinite(value)).toBe(true);
+}
+
 // Asserts a triangle's geometric face normal agrees with its vertices' averaged shading normal, so
 // the winding (CCW front-facing) matches the outward-pointing normals the builder emits. A back-
 // facing wind would be culled and expose the interior surface instead. Scans from the first triangle
@@ -91,9 +97,23 @@ describe('createBoxMeshGeometry', () => {
 describe('createCapsuleMeshGeometry', () => {
   it('builds a capsule that spans -(height/2+radius)..(height/2+radius) on Y', () => {
     const geometry = createCapsuleMeshGeometry(0.5, 1, 8, 4);
-    expect(getMeshGeometryVertexCount(geometry)).toBeGreaterThan(0);
+    expect(getMeshGeometryVertexCount(geometry)).toBe(90);
+    expect(getMeshGeometryIndexCount(geometry)).toBe(432);
     expect(geometry.bounds!.min.y).toBeCloseTo(-1, 1);
     expect(geometry.bounds!.max.y).toBeCloseTo(1, 1);
+
+    const stride = 12;
+    const ringVertexCount = 9;
+    const topEquator = 4 * ringVertexCount * stride;
+    const bottomEquator = 5 * ringVertexCount * stride;
+    expect(geometry.vertices[topEquator]).toBeCloseTo(0.5);
+    expect(geometry.vertices[topEquator + 1]).toBeCloseTo(0.5);
+    expect(geometry.vertices[topEquator + 4]).toBeCloseTo(0);
+    expect(geometry.vertices[topEquator + 11]).toBeCloseTo(4 / 9);
+    expect(geometry.vertices[bottomEquator]).toBeCloseTo(0.5);
+    expect(geometry.vertices[bottomEquator + 1]).toBeCloseTo(-0.5);
+    expect(geometry.vertices[bottomEquator + 4]).toBeCloseTo(0);
+    expect(geometry.vertices[bottomEquator + 11]).toBeCloseTo(5 / 9);
     expectUnitNormals(geometry);
   });
 });
@@ -126,6 +146,15 @@ describe('createCylinderMeshGeometry', () => {
     expectUnitNormals(geometry);
     expectUnitTangents(geometry);
   });
+
+  it('keeps cylinder and cone records finite when height is zero', () => {
+    const cylinder = createCylinderMeshGeometry(0.5, 0.5, 0, 8);
+    const cone = createConeMeshGeometry(0.5, 0, 8);
+    expectFiniteCanonicalRecord(cylinder);
+    expectFiniteCanonicalRecord(cone);
+    expect(validateMeshGeometry(cylinder)).toBe(true);
+    expect(validateMeshGeometry(cone)).toBe(true);
+  });
 });
 
 describe('createDodecahedronMeshGeometry', () => {
@@ -182,15 +211,78 @@ describe('createPlaneMeshGeometry', () => {
 });
 
 describe('createPolyhedronMeshGeometry', () => {
-  it('accepts custom vertex/face data', () => {
-    const verts: ReadonlyArray<readonly [number, number, number]> = [
-      [0, 1, 0],
-      [-1, -1, 0],
-      [1, -1, 0],
-    ];
-    const faces: ReadonlyArray<readonly [number, number, number]> = [[0, 1, 2]];
-    const geometry = createPolyhedronMeshGeometry(verts, faces, 1, 0);
+  const TRIANGLE_VERTS: ReadonlyArray<readonly [number, number, number]> = [
+    [0, 1, 0],
+    [-1, -1, 0],
+    [1, -1, 0],
+  ];
+  const ONE_FACE: ReadonlyArray<readonly [number, number, number]> = [[0, 1, 2]];
+
+  // The name promises the custom data is USED. A vertex count alone cannot tell that from a builder
+  // that ignored both arguments and emitted any three vertices, so the seed positions are asserted
+  // through to the output — projected onto the radius sphere, which is what this builder does with them.
+  it('projects the supplied vertices onto the radius sphere', () => {
+    const geometry = createPolyhedronMeshGeometry(TRIANGLE_VERTS, ONE_FACE, 2, 0);
+
     expect(getMeshGeometryVertexCount(geometry)).toBe(3);
+    const floatsPerVertex = geometry.layout.stride / 4;
+    // The first seed is already unit length on +Y, so it lands on the sphere pole at the given radius.
+    expect(geometry.vertices[0]).toBeCloseTo(0, 6);
+    expect(geometry.vertices[1]).toBeCloseTo(2, 6);
+    expect(geometry.vertices[2]).toBeCloseTo(0, 6);
+    for (let v = 0; v < 3; v++) {
+      const base = v * floatsPerVertex;
+      expect(Math.hypot(geometry.vertices[base], geometry.vertices[base + 1], geometry.vertices[base + 2])).toBeCloseTo(
+        2,
+        6,
+      );
+      // Normals are the unit direction, independent of radius.
+      expect(
+        Math.hypot(geometry.vertices[base + 3], geometry.vertices[base + 4], geometry.vertices[base + 5]),
+      ).toBeCloseTo(1, 6);
+    }
+  });
+
+  // Different seed data must produce different geometry — the assertion the count-only version could
+  // not make, and the one that fails if the arguments are ever ignored.
+  it('produces different geometry for different seed vertices', () => {
+    const a = createPolyhedronMeshGeometry(TRIANGLE_VERTS, ONE_FACE, 1, 0);
+    const b = createPolyhedronMeshGeometry(
+      [
+        [0, 0, 1],
+        [0, 1, 0],
+        [1, 0, 0],
+      ],
+      ONE_FACE,
+      1,
+      0,
+    );
+
+    expect(Array.from(a.vertices)).not.toEqual(Array.from(b.vertices));
+  });
+
+  // Each subdivision splits every face into four, so the triangle count multiplies by four per level.
+  it.each([
+    [0, 3],
+    [1, 12],
+    [2, 48],
+  ])('subdivides to %i levels giving %i vertices', (detail, expected) => {
+    expect(getMeshGeometryVertexCount(createPolyhedronMeshGeometry(TRIANGLE_VERTS, ONE_FACE, 1, detail))).toBe(
+      expected,
+    );
+  });
+
+  it('keeps every subdivided vertex on the sphere', () => {
+    const geometry = createPolyhedronMeshGeometry(TRIANGLE_VERTS, ONE_FACE, 3, 2);
+
+    const floatsPerVertex = geometry.layout.stride / 4;
+    for (let v = 0; v < getMeshGeometryVertexCount(geometry); v++) {
+      const base = v * floatsPerVertex;
+      expect(Math.hypot(geometry.vertices[base], geometry.vertices[base + 1], geometry.vertices[base + 2])).toBeCloseTo(
+        3,
+        5,
+      );
+    }
   });
 });
 
@@ -253,3 +345,234 @@ describe('createTorusMeshGeometry', () => {
     expectWindingMatchesNormals(geometry);
   });
 });
+
+// A cone is this cylinder with a zero top radius, so its top ring collapses to the apex and one triangle
+// of every side quad had two coincident corners — a third of the mesh rasterising nothing. Removing them
+// is invisible on screen by construction, which is why the assertion below is about ZERO AREA rather
+// than about a triangle count: the count is an implementation detail, the absence of dead geometry is
+// the property.
+describe('degenerate side triangles', () => {
+  it.each([
+    ['cone', () => createConeMeshGeometry(0.7, 1.4)],
+    ['cone with a zero height', () => createConeMeshGeometry(0.5, 0, 8)],
+    ['cylinder with a zero bottom radius', () => createCylinderMeshGeometry(0.5, 0, 1, 12)],
+  ])('emits no zero-area triangle for a %s', (_name, build) => {
+    const geometry = build();
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const corner: MeshTriangleVertexIndices = { i0: 0, i1: 0, i2: 0 };
+    let triangles = 0;
+
+    for (let t = 0; t < getMeshGeometryTriangleCount(geometry); t++) {
+      if (!getMeshGeometryTriangleVertexIndices(corner, geometry, t)) continue;
+      triangles++;
+      const p = [corner.i0, corner.i1, corner.i2].map((i) => [
+        geometry.vertices[i * floatsPerVertex],
+        geometry.vertices[i * floatsPerVertex + 1],
+        geometry.vertices[i * floatsPerVertex + 2],
+      ]);
+      const e1 = [p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2]];
+      const e2 = [p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[0][2]];
+      const area = Math.hypot(
+        e1[1] * e2[2] - e1[2] * e2[1],
+        e1[2] * e2[0] - e1[0] * e2[2],
+        e1[0] * e2[1] - e1[1] * e2[0],
+      );
+      expect(area).toBeGreaterThan(1e-12);
+    }
+
+    // Without this the loop could pass by finding no triangles at all.
+    expect(triangles).toBeGreaterThan(0);
+  });
+
+  // The apex keeps one vertex per segment even though they share a position: each carries its own u,
+  // which is what lets a texture vary around the cone. Only the dead INDICES were removed.
+  it('keeps the per-segment apex vertices that carry distinct uvs', () => {
+    const geometry = createConeMeshGeometry(0.7, 1.4, 8);
+    const floatsPerVertex = geometry.layout.stride / 4;
+
+    const apexUvs = new Set<number>();
+    for (let v = 0; v < getMeshGeometryVertexCount(geometry); v++) {
+      const base = v * floatsPerVertex;
+      const isApex = Math.hypot(geometry.vertices[base], geometry.vertices[base + 2]) <= 1e-9;
+      if (isApex && geometry.vertices[base + 1] > 0) apexUvs.add(geometry.vertices[base + 10]);
+    }
+
+    expect(apexUvs.size).toBeGreaterThan(1);
+  });
+});
+
+describe('mesh builder count inputs', () => {
+  const polyhedronVertices: ReadonlyArray<readonly [number, number, number]> = [
+    [0, 1, 0],
+    [-1, -1, 0],
+    [1, -1, 0],
+  ];
+  const polyhedronFaces: ReadonlyArray<readonly [number, number, number]> = [[0, 1, 2]];
+
+  it.each([
+    ['capsule', () => createCapsuleMeshGeometry(0.5, 1, 3.5, 1.5), () => createCapsuleMeshGeometry(0.5, 1, 3, 1)],
+    ['circle', () => createCircleMeshGeometry(0.5, 3.5), () => createCircleMeshGeometry(0.5, 3)],
+    ['cone', () => createConeMeshGeometry(0.5, 1, 3.5), () => createConeMeshGeometry(0.5, 1, 3)],
+    ['cylinder', () => createCylinderMeshGeometry(0.5, 0.5, 1, 3.5), () => createCylinderMeshGeometry(0.5, 0.5, 1, 3)],
+    ['dodecahedron', () => createDodecahedronMeshGeometry(0.5, 1.5), () => createDodecahedronMeshGeometry(0.5, 1)],
+    ['icosahedron', () => createIcosahedronMeshGeometry(0.5, 1.5), () => createIcosahedronMeshGeometry(0.5, 1)],
+    ['icosphere', () => createIcosphereMeshGeometry(0.5, 1.5), () => createIcosphereMeshGeometry(0.5, 1)],
+    ['octahedron', () => createOctahedronMeshGeometry(0.5, 1.5), () => createOctahedronMeshGeometry(0.5, 1)],
+    ['plane', () => createPlaneMeshGeometry(1, 1, 1.5, 1.5), () => createPlaneMeshGeometry(1, 1, 1, 1)],
+    [
+      'polyhedron',
+      () => createPolyhedronMeshGeometry(polyhedronVertices, polyhedronFaces, 0.5, 1.5),
+      () => createPolyhedronMeshGeometry(polyhedronVertices, polyhedronFaces, 0.5, 1),
+    ],
+    ['ring', () => createRingMeshGeometry(0.25, 0.5, 3.5), () => createRingMeshGeometry(0.25, 0.5, 3)],
+    ['sphere', () => createSphereMeshGeometry(0.5, 3.5, 2.5), () => createSphereMeshGeometry(0.5, 3, 2)],
+    [
+      'torus knot',
+      () => createTorusKnotMeshGeometry(0.5, 0.15, 3.5, 3.5),
+      () => createTorusKnotMeshGeometry(0.5, 0.15, 3, 3),
+    ],
+    ['torus', () => createTorusMeshGeometry(0.5, 0.2, 3.5, 3.5), () => createTorusMeshGeometry(0.5, 0.2, 3, 3)],
+  ])('floors every fractional %s count and produces a valid mesh', (_name, fractional, floored) => {
+    const actual = fractional();
+    const expected = floored();
+    expect(validateMeshGeometry(actual)).toBe(true);
+    expect(getMeshGeometryVertexCount(actual)).toBe(getMeshGeometryVertexCount(expected));
+    expect(getMeshGeometryIndexCount(actual)).toBe(getMeshGeometryIndexCount(expected));
+  });
+
+  it.each([
+    ['capsule radialSegments', (value: number) => createCapsuleMeshGeometry(0.5, 1, value, 1)],
+    ['capsule capSegments', (value: number) => createCapsuleMeshGeometry(0.5, 1, 3, value)],
+    ['circle segments', (value: number) => createCircleMeshGeometry(0.5, value)],
+    ['cone radialSegments', (value: number) => createConeMeshGeometry(0.5, 1, value)],
+    ['cylinder radialSegments', (value: number) => createCylinderMeshGeometry(0.5, 0.5, 1, value)],
+    ['dodecahedron detail', (value: number) => createDodecahedronMeshGeometry(0.5, value)],
+    ['icosahedron detail', (value: number) => createIcosahedronMeshGeometry(0.5, value)],
+    ['icosphere subdivisions', (value: number) => createIcosphereMeshGeometry(0.5, value)],
+    ['octahedron detail', (value: number) => createOctahedronMeshGeometry(0.5, value)],
+    ['plane widthSegments', (value: number) => createPlaneMeshGeometry(1, 1, value, 1)],
+    ['plane depthSegments', (value: number) => createPlaneMeshGeometry(1, 1, 1, value)],
+    [
+      'polyhedron detail',
+      (value: number) => createPolyhedronMeshGeometry(polyhedronVertices, polyhedronFaces, 0.5, value),
+    ],
+    ['ring segments', (value: number) => createRingMeshGeometry(0.25, 0.5, value)],
+    ['sphere widthSegments', (value: number) => createSphereMeshGeometry(0.5, value, 2)],
+    ['sphere heightSegments', (value: number) => createSphereMeshGeometry(0.5, 3, value)],
+    ['tetrahedron detail', (value: number) => createTetrahedronMeshGeometry(0.5, value)],
+    ['torus knot tubularSegments', (value: number) => createTorusKnotMeshGeometry(0.5, 0.15, value, 3)],
+    ['torus knot radialSegments', (value: number) => createTorusKnotMeshGeometry(0.5, 0.15, 3, value)],
+    ['torus radialSegments', (value: number) => createTorusMeshGeometry(0.5, 0.2, value, 3)],
+    ['torus tubularSegments', (value: number) => createTorusMeshGeometry(0.5, 0.2, 3, value)],
+  ])('rejects non-finite %s', (_name, build) => {
+    expect(() => build(Number.NaN)).toThrow(RangeError);
+    expect(() => build(Number.POSITIVE_INFINITY)).toThrow(RangeError);
+  });
+});
+
+// Longitude wraps at u = 0/1, so a face straddling the seam gets corners like 0.99 and 0.01 and
+// interpolates BACKWARDS across the whole texture — the entire map crushed into one triangle. The
+// unmistakable signature is a single face holding a corner near 0 AND a corner near 1; after the
+// correction lifts the low corners past 1, no face carries both.
+//
+// Emitting per-face vertices is what makes the correction POSSIBLE (a shared vertex could only hold one
+// u) but it does not perform it, and for a long time only the first half was here.
+describe('spherical UV seam', () => {
+  it.each([
+    ['icosahedron', () => createIcosahedronMeshGeometry()],
+    ['dodecahedron', () => createDodecahedronMeshGeometry()],
+    ['octahedron', () => createOctahedronMeshGeometry()],
+    ['tetrahedron', () => createTetrahedronMeshGeometry()],
+    ['icosphere', () => createIcosphereMeshGeometry()],
+  ])('gives no %s face corners at both ends of the longitude range', (_name, build) => {
+    const geometry = build();
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const corner: MeshTriangleVertexIndices = { i0: 0, i1: 0, i2: 0 };
+
+    for (let t = 0; t < getMeshGeometryTriangleCount(geometry); t++) {
+      if (!getMeshGeometryTriangleVertexIndices(corner, geometry, t)) continue;
+      const us = [corner.i0, corner.i1, corner.i2].map((i) => geometry.vertices[i * floatsPerVertex + 10]);
+      const wrapped = Math.min(...us) < 0.1 && Math.max(...us) > 0.9;
+      expect(wrapped).toBe(false);
+    }
+  });
+
+  // A pole vertex sits on the Y axis, where every meridian meets, so atan2 hands it an arbitrary
+  // longitude unrelated to the face it belongs to — u = 0.5 while its face-mates sit near 1.0 and 1.25,
+  // stretching the face across half the texture. Having no longitude of its own to preserve, it takes
+  // the average of its face-mates and therefore must lie BETWEEN them.
+  it.each([
+    ['octahedron', () => createOctahedronMeshGeometry()],
+    ['icosphere', () => createIcosphereMeshGeometry()],
+  ])('places a %s pole vertex between its face-mates in longitude', (_name, build) => {
+    const geometry = build();
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const corner: MeshTriangleVertexIndices = { i0: 0, i1: 0, i2: 0 };
+    let polesSeen = 0;
+
+    for (let t = 0; t < getMeshGeometryTriangleCount(geometry); t++) {
+      if (!getMeshGeometryTriangleVertexIndices(corner, geometry, t)) continue;
+      const indices = [corner.i0, corner.i1, corner.i2];
+      const horizontalRadius = indices.map((i) =>
+        Math.hypot(geometry.vertices[i * floatsPerVertex], geometry.vertices[i * floatsPerVertex + 2]),
+      );
+      const poleSlot = horizontalRadius.findIndex((r) => r <= 1e-6);
+      if (poleSlot < 0) continue;
+      polesSeen++;
+      const us = indices.map((i) => geometry.vertices[i * floatsPerVertex + 10]);
+      const mates = us.filter((_, k) => k !== poleSlot);
+      expect(us[poleSlot]).toBeGreaterThanOrEqual(Math.min(...mates));
+      expect(us[poleSlot]).toBeLessThanOrEqual(Math.max(...mates));
+    }
+
+    // The fixture has to contain pole faces or the assertions above never run.
+    expect(polesSeen).toBeGreaterThan(0);
+  });
+
+  // WHAT IS ALLOWED TO REMAIN, stated as a criterion rather than a count. A handful of faces still span
+  // more than half the longitude range, and that is not a missed correction: on a 20-face solid a single
+  // face genuinely subtends that much longitude, and no UV assignment can make it narrow. What WOULD be
+  // a missed correction is such a face containing a POLE corner, because a pole has no longitude of its
+  // own and must take its face-mates'.
+  //
+  // Asserting the criterion rather than "there are exactly 4" is deliberate: a count has to be edited
+  // whenever anyone changes a segment count or subdivision level, and a check that always prints the
+  // same non-zero number teaches everyone to scroll past it — and then it cannot warn about the fifth.
+  // This phrasing stays exactly as strict when the geometry changes.
+  it.each([
+    ['dodecahedron', () => createDodecahedronMeshGeometry()],
+    ['icosahedron', () => createIcosahedronMeshGeometry()],
+    ['icosphere', () => createIcosphereMeshGeometry()],
+    ['octahedron', () => createOctahedronMeshGeometry()],
+    ['tetrahedron', () => createTetrahedronMeshGeometry()],
+  ])('leaves no %s wide face carrying a pole corner', (_name, build) => {
+    const geometry = build();
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const corner: MeshTriangleVertexIndices = { i0: 0, i1: 0, i2: 0 };
+
+    for (let t = 0; t < getMeshGeometryTriangleCount(geometry); t++) {
+      if (!getMeshGeometryTriangleVertexIndices(corner, geometry, t)) continue;
+      const indices = [corner.i0, corner.i1, corner.i2];
+      const us = indices.map((i) => geometry.vertices[i * floatsPerVertex + 10]);
+      if (Math.max(...us) - Math.min(...us) <= 0.5) continue;
+      const hasPoleCorner = indices.some(
+        (i) => Math.hypot(geometry.vertices[i * floatsPerVertex], geometry.vertices[i * floatsPerVertex + 2]) <= 1e-6,
+      );
+      expect(hasPoleCorner).toBe(false);
+    }
+  });
+
+  // A corrected face legitimately carries u above 1: no parameterisation confined to 0..1 can express
+  // a face crossing the seam continuously. Sampling wraps it, so this is the intended state, not drift.
+  it('lifts a seam face past 1 rather than clamping it into range', () => {
+    const geometry = createIcosahedronMeshGeometry();
+    const floatsPerVertex = geometry.layout.stride / 4;
+
+    let maxU = -Infinity;
+    for (let v = 0; v < getMeshGeometryVertexCount(geometry); v++) {
+      maxU = Math.max(maxU, geometry.vertices[v * floatsPerVertex + 10]);
+    }
+
+    expect(maxU).toBeGreaterThan(1);
+  });
+});