diff --git a/docs/mutation-testing.md b/docs/mutation-testing.md index ea1f67d2..8db67be5 100644 --- a/docs/mutation-testing.md +++ b/docs/mutation-testing.md @@ -35,6 +35,18 @@ project: dotnet stryker -t mtp --since: ``` +Use a full commit SHA for `--since`, not an abbreviation: `git rev-parse +` first, then pass the full result. Stryker resolves `--since` +through the same git plumbing a short SHA can resolve ambiguously (or fail to +resolve at all) depending on the checkout's object database, and a +misresolved base silently changes what "since" means instead of erroring. + +In a container, also set `git config --global --add safe.directory '*'` +before running Stryker (or any other command that shells out to `git` +against this checkout) - git refuses to operate on a repository owned by a +different user by default, which is the common case for a bind-mounted +checkout in a container. + Reports land in `StrykerOutput/` next to the test project (git-ignored). Open the `reports/mutation-report.html` file for a browsable view, or read `reports/mutation-report.json` for a scriptable one. @@ -75,12 +87,73 @@ inside a `static readonly` field initializer as unproven until confirmed with a direct `dotnet test` run against the same mutation; do not triage it as a missing test without that check. +A survivor that looks like it must be covered is unproven until confirmed +with a direct `dotnet test` run against the same hand-applied mutation - but +confirm what the mutant actually is before drawing a tooling conclusion from +it. An earlier pass here reported three survivors in +`CultGeometrySurfaceNets.TryGetOtherEndpoint`'s per-axis `if (x + 1 >= +sizeX) return false;` guards and initially triaged them as a `vstest` +coverage false-survivor (the same shape as the `mtp`/`static readonly` +caveat above). That triage was wrong: the actual mutant Stryker reports +there is `return false` -> `return true` inside the guard, which is +equivalent, not a coverage miss. Returning `true` from +`TryGetOtherEndpoint` still leaves the out `other` coordinate equal to the +current coordinate (see the method: `other` is cloned from `coord` and only +one component is incremented when the method returns `true`), so the caller +compares a sample against itself, the inside/outside flags always match, +and the crossing is skipped exactly as it would have been had the method +correctly returned `false`. No test can distinguish the two branches because +there is nothing to distinguish - it is a legitimate equivalent mutant, not +evidence of a `vstest` false survivor. + +`CultGeometrySurfaceNets.Extract`'s `if (inside == (OrientationSign[axis] < +0))` (the sole authority for quad winding after the geometric cross-product +fallback was deleted) has three mutants on that line: `==` -> `!=`, and `< 0` +negated to `> 0` or widened to `<= 0`. The first two, `inside != (OrientationSign[axis] +< 0)` and `OrientationSign[axis] > 0`, are both reported `Killed`. The third, +`OrientationSign[axis] <= 0`, survives, but it is an equivalent mutant, not a +coverage gap: `OrientationSign` is the fixed table `{ 1, -1, 1 }` and never +holds `0`, so `< 0` and `<= 0` agree on every value the table can actually +produce. There is nothing for a test to distinguish, the same shape as the +`TryGetOtherEndpoint` equivalent mutant above. + +No `vstest` coverage-based false survivor has actually been confirmed for +GameCult.Geometry. Every survivor triaged here so far has turned out to be a +genuine equivalent mutant once hand-mutated and checked directly against +`dotnet test`; treat any survivor that looks like it must obviously be +covered as unproven until confirmed the same way, but do not cite this +project as precedent for the `vstest` caveat itself - that caveat is +`mtp`-runner-specific and documented above for `static readonly` field +initializers, and GameCult.Geometry has never actually hit it. + ## Follow-ups -CultMath.Tests is the only project currently scoped. `GameCult.Caching`, -`GameCult.Geometry`, `GameCult.Mesh` (+ `.Quic`, `.Quic.Native`), +CultMath.Tests and GameCult.Geometry.Tests are the only projects currently +scoped. GameCult.Geometry's `stryker-config.json` has no `test-runner` +entry: the project is NUnit 4 with `NUnit3TestAdapter` and +`Microsoft.NET.Test.Sdk`, so Stryker's default `vstest` runner applies +directly (no `mtp` workaround needed, unlike CultMath.Tests's xunit.v3 +suite). + +GameCult.Geometry has only ever been run `--since:`-scoped to the cut that +added surface nets; a full-project baseline (running mutation against all of +`CultGeometryIsoSurface`, `CultGeometryDocuments`, and +`CultGeometryPrimitives`, not just the diff) is a recorded follow-up, not +something either cut did. + +That first `--since` pass did not actually stay diff-scoped: adding +`stryker-config.json` itself in the same cut that first used it made Stryker +log "391 mutants will be tested because: Non-CSharp files in test project +were changed" and mutate the whole `mutate` glob (all four existing +GameCult.Geometry source files), not just the new surface-nets files. A cut +that changes a non-C# file inside the test project (a fixture, this config +file, anything under `Fixtures/`) loses `--since` line-level scoping for that +run; a future cut whose diff is C#-only, against a base commit that already +has `stryker-config.json`, should scope correctly. + +`GameCult.Caching`, `GameCult.Mesh` (+ `.Quic`, `.Quic.Native`), `GameCult.Networking` (+ `.WebSockets`), and the non-.NET runtimes -(`cultcache-rs/py/ts`, `cultmesh-*`, `cultnet-*`) each need their own +(`cultcache-rs/py/ts`, `cultmesh-*`, `cultnet-*`) each still need their own `stryker-config.json` (or ecosystem-equivalent tool: `cargo-mutants` for Rust, `StrykerJS` for TypeScript, `mutmut` for Python) and a baseline pass. None of that is wired into CI yet. diff --git a/src/GameCult.Geometry/CultGeometryQuadMesh.cs b/src/GameCult.Geometry/CultGeometryQuadMesh.cs new file mode 100644 index 00000000..f849782c --- /dev/null +++ b/src/GameCult.Geometry/CultGeometryQuadMesh.cs @@ -0,0 +1,89 @@ +using System; + +namespace GameCult.Geometry +{ + /// + /// The grid edge from sample (X, Y, Z) to (X, Y, Z) + e_Axis, where Axis 0/1/2 is X/Y/Z. + /// + public readonly struct CultGeometryGridEdge : IEquatable, IComparable + { + /// Creates a grid edge. + public CultGeometryGridEdge(int x, int y, int z, byte axis) + { + X = x; + Y = y; + Z = z; + Axis = axis; + } + + /// Gets the starting sample's x coordinate. + public int X { get; } + + /// Gets the starting sample's y coordinate. + public int Y { get; } + + /// Gets the starting sample's z coordinate. + public int Z { get; } + + /// Gets the axis the edge runs along: 0 for x, 1 for y, 2 for z. + public byte Axis { get; } + + /// Returns whether this edge is equal to another edge. + public bool Equals(CultGeometryGridEdge other) => + X == other.X && Y == other.Y && Z == other.Z && Axis == other.Axis; + + /// + public override bool Equals(object? obj) => obj is CultGeometryGridEdge other && Equals(other); + + /// + public override int GetHashCode() => HashCode.Combine(X, Y, Z, Axis); + + /// Compares edges by (X, Y, Z, Axis) in that order. + public int CompareTo(CultGeometryGridEdge other) + { + var byX = X.CompareTo(other.X); + if (byX != 0) return byX; + + var byY = Y.CompareTo(other.Y); + if (byY != 0) return byY; + + var byZ = Z.CompareTo(other.Z); + if (byZ != 0) return byZ; + + return Axis.CompareTo(other.Axis); + } + + /// + public override string ToString() => $"({X}, {Y}, {Z})+e{Axis}"; + + // The relational operators (<, >, <=, >=) had no caller and no test anywhere in the repo: + // ordering goes through CompareTo (see + // Extraction_is_deterministic_and_quad_edges_are_strictly_ascending), so they were deleted + // rather than carried as untested surface. != is kept only because C# requires it whenever + // == is defined (CS0216); it is exercised directly by a test. + public static bool operator ==(CultGeometryGridEdge left, CultGeometryGridEdge right) => left.Equals(right); + public static bool operator !=(CultGeometryGridEdge left, CultGeometryGridEdge right) => !left.Equals(right); + } + + /// + /// An engine-neutral quad mesh with welded vertices, produced by surface nets extraction. + /// Not a CultCache document: this is an in-process algorithm result, not a persisted artifact. + /// + public sealed class CultGeometryQuadMesh + { + /// Gets or sets the welded vertex positions, xyz per vertex. + public float[] Positions { get; set; } = Array.Empty(); + + /// Gets or sets the quad vertex indices, 4 per quad. + public uint[] Quads { get; set; } = Array.Empty(); + + /// Gets or sets the grid edge each quad was emitted for, one per quad, strictly ascending. + public CultGeometryGridEdge[] QuadEdges { get; set; } = Array.Empty(); + + /// Gets the number of quads. + public int QuadCount => Quads.Length / 4; + + /// Gets the number of welded vertices. + public int VertexCount => Positions.Length / 3; + } +} diff --git a/src/GameCult.Geometry/CultGeometryQuadNormals.cs b/src/GameCult.Geometry/CultGeometryQuadNormals.cs new file mode 100644 index 00000000..a8121ca7 --- /dev/null +++ b/src/GameCult.Geometry/CultGeometryQuadNormals.cs @@ -0,0 +1,65 @@ +using System; +using CultMath; + +namespace GameCult.Geometry +{ + /// + /// Derives per-vertex normals for a welded quad mesh by face-weighted averaging. + /// + public static class CultGeometryQuadNormals + { + /// + /// Computes a per-vertex normal for as the sum, over every quad + /// touching that vertex, of the quad's diagonal cross product (which points along the + /// quad's normal and whose length is twice a non-planar quad's area), then normalized. + /// A vertex touched only by zero-area quads gets a zero normal. + /// + public static float[] FaceWeighted(CultGeometryQuadMesh mesh) + { + if (mesh == null) throw new ArgumentNullException(nameof(mesh)); + + var sums = new float3[mesh.VertexCount]; + for (var quad = 0; quad < mesh.QuadCount; quad++) + { + var baseIndex = quad * 4; + var i0 = mesh.Quads[baseIndex]; + var i1 = mesh.Quads[baseIndex + 1]; + var i2 = mesh.Quads[baseIndex + 2]; + var i3 = mesh.Quads[baseIndex + 3]; + + var p0 = Position(mesh.Positions, i0); + var p1 = Position(mesh.Positions, i1); + var p2 = Position(mesh.Positions, i2); + var p3 = Position(mesh.Positions, i3); + + var faceVector = math.cross(p2 - p0, p3 - p1); + + sums[i0] += faceVector; + sums[i1] += faceVector; + sums[i2] += faceVector; + sums[i3] += faceVector; + } + + var normals = new float[mesh.VertexCount * 3]; + for (var vertex = 0; vertex < sums.Length; vertex++) + { + var sum = sums[vertex]; + + // A vertex whose contributions cancel or were all zero-area gets a zero normal; + // normalize follows HLSL and would return NaN for it (matches Extract's degenerate rule). + var normal = math.dot(sum, sum) > 0f ? math.normalize(sum) : float3.zero; + normals[vertex * 3] = normal.x; + normals[vertex * 3 + 1] = normal.y; + normals[vertex * 3 + 2] = normal.z; + } + + return normals; + } + + private static float3 Position(float[] positions, uint index) + { + var offset = (int)index * 3; + return new float3(positions[offset], positions[offset + 1], positions[offset + 2]); + } + } +} diff --git a/src/GameCult.Geometry/CultGeometrySurfaceNets.cs b/src/GameCult.Geometry/CultGeometrySurfaceNets.cs new file mode 100644 index 00000000..45c3f1ec --- /dev/null +++ b/src/GameCult.Geometry/CultGeometrySurfaceNets.cs @@ -0,0 +1,257 @@ +using System; +using System.Collections.Generic; +using CultMath; + +namespace GameCult.Geometry +{ + /// + /// Extracts engine-neutral welded quad meshes from sampled scalar fields with surface nets. + /// + public static class CultGeometrySurfaceNets + { + // For axis A, the two perpendicular axes in (u, v) order. Axis 0 (X) pairs (Y, Z) and axis + // 2 (Z) pairs (X, Y): both right-handed, u x v == +A_hat. Axis 1 (Y) pairs (X, Z), which is + // left-handed (X x Z == -Y). OrientationSign below records that mirroring explicitly so + // quad winding can be derived from it instead of a per-quad geometric test. + private static readonly (int U, int V)[] PerpAxes = { (1, 2), (0, 2), (0, 1) }; + + // +1 when (PerpAxes[axis].U, .V) is right-handed, -1 when it is mirrored (axis 1 only). + private static readonly int[] OrientationSign = { 1, -1, 1 }; + + // The perimeter loop around a crossing edge, in perpendicular (u, v) space: a proper square + // loop (0,0) -> (1,0) -> (1,1) -> (0,1), not a diagonal cross. Added to a cell's own + // coordinate it gives the axis's four parallel edges inside that cell (for vertex + // placement); shifted by -1 it gives the four cells that share a crossing edge (for quad + // assembly). One table, two uses, instead of three axis-specific copies of each. + private static readonly (int U, int V)[] PerimeterLoop = { (0, 0), (1, 0), (1, 1), (0, 1) }; + + /// + /// Extracts the surface with surface nets. + /// Values less than or equal to the isovalue are treated as inside. + /// + /// is null. + /// + /// is too small or has a non-finite sample, or + /// or a component of is non-finite. + /// + /// is non-positive or infinite. + /// + /// Non-finite results from otherwise-finite inputs (for example an extreme + /// or samples near float's magnitude limit producing an + /// infinite vertex position) are a float-domain overflow, not a validated input error; + /// this method does not range-check magnitudes for that case. + /// + public static CultGeometryQuadMesh Extract( + float[,,] samples, + float isoValue = 0f, + CultVec3 origin = default, + float cellSize = 1f) + { + if (samples == null) throw new ArgumentNullException(nameof(samples)); + if (samples.GetLength(0) < 2 || samples.GetLength(1) < 2 || samples.GetLength(2) < 2) + { + throw new ArgumentException("A surface nets field requires at least two samples on every axis.", nameof(samples)); + } + + foreach (var sample in samples) + { + if (!float.IsFinite(sample)) + { + throw new ArgumentException("A surface nets field requires every sample to be finite.", nameof(samples)); + } + } + + if (!float.IsFinite(isoValue)) + { + throw new ArgumentException("The isovalue must be finite.", nameof(isoValue)); + } + + if (!float.IsFinite(origin.X) || !float.IsFinite(origin.Y) || !float.IsFinite(origin.Z)) + { + throw new ArgumentException("The origin must be finite.", nameof(origin)); + } + + if (!(cellSize > 0f) || float.IsInfinity(cellSize)) + { + throw new ArgumentOutOfRangeException(nameof(cellSize), "Cell size must be finite and positive."); + } + + var sizeX = samples.GetLength(0); + var sizeY = samples.GetLength(1); + var sizeZ = samples.GetLength(2); + var cellCounts = new[] { sizeX - 1, sizeY - 1, sizeZ - 1 }; + var originValue = new float3(origin.X, origin.Y, origin.Z); + + var vertexIndex = new Dictionary<(int, int, int), uint>(); + var positions = new List(); + + for (var cx = 0; cx < cellCounts[0]; cx++) + for (var cy = 0; cy < cellCounts[1]; cy++) + for (var cz = 0; cz < cellCounts[2]; cz++) + { + var cellCoord = new[] { cx, cy, cz }; + var vertex = CellVertex(samples, cellCoord, isoValue, originValue, cellSize); + if (vertex == null) continue; + + vertexIndex[(cx, cy, cz)] = (uint)(positions.Count / 3); + Append(vertex.Value, positions); + } + + var quads = new List(); + var quadEdges = new List(); + + for (var x = 0; x < sizeX; x++) + for (var y = 0; y < sizeY; y++) + for (var z = 0; z < sizeZ; z++) + { + var coord = new[] { x, y, z }; + + for (byte axis = 0; axis < 3; axis++) + { + // Only an edge whose far endpoint is still inside the grid can cross into a + // quad. Bounding the loop with this one condition, instead of a helper that + // returned a bool for the caller to branch on, leaves one path through the + // rest of the body instead of two that happened to produce the same result. + if (coord[axis] < cellCounts[axis]) + { + var other = (int[])coord.Clone(); + other[axis] += 1; + + var inside = IsInside(samples[x, y, z], isoValue); + var otherInside = IsInside(samples[other[0], other[1], other[2]], isoValue); + if (inside != otherInside && TryGetQuadCells(cellCounts, coord, axis, out var cells)) + { + // The four cells around a crossing edge each contain that same crossing + // edge among their own twelve, so each of them is mixed and has a + // vertex: this indexer cannot miss without the extraction invariant + // already being broken. + var v = new uint[4]; + for (var i = 0; i < 4; i++) v[i] = vertexIndex[cells[i]]; + + // Orientation comes only from which endpoint is inside and the axis's + // fixed handedness (OrientationSign) - never from the quad's own + // geometry, so degenerate (zero-area) quads still orient consistently + // with their neighbours. + if (inside == (OrientationSign[axis] < 0)) + { + (v[1], v[3]) = (v[3], v[1]); + } + + quads.Add(v[0]); + quads.Add(v[1]); + quads.Add(v[2]); + quads.Add(v[3]); + quadEdges.Add(new CultGeometryGridEdge(x, y, z, axis)); + } + } + } + } + + return new CultGeometryQuadMesh + { + Positions = positions.ToArray(), + Quads = quads.ToArray(), + QuadEdges = quadEdges.ToArray(), + }; + } + + private static bool IsInside(float sample, float isoValue) => sample <= isoValue; + + private static float3? CellVertex( + float[,,] samples, + int[] cellCoord, + float isoValue, + float3 origin, + float cellSize) + { + var sum = float3.zero; + var count = 0; + + for (byte axis = 0; axis < 3; axis++) + { + AccumulateAxisEdges(samples, cellCoord, axis, isoValue, origin, cellSize, ref sum, ref count); + } + + return count == 0 ? null : sum / count; + } + + private static void AccumulateAxisEdges( + float[,,] samples, + int[] cellCoord, + byte axis, + float isoValue, + float3 origin, + float cellSize, + ref float3 sum, + ref int count) + { + var (u, v) = PerpAxes[axis]; + + for (var i = 0; i < 4; i++) + { + var start = (int[])cellCoord.Clone(); + start[u] += PerimeterLoop[i].U; + start[v] += PerimeterLoop[i].V; + + var end = (int[])start.Clone(); + end[axis] += 1; + + var startValue = samples[start[0], start[1], start[2]]; + var endValue = samples[end[0], end[1], end[2]]; + if (IsInside(startValue, isoValue) == IsInside(endValue, isoValue)) continue; + + var startPosition = origin + new float3(start[0], start[1], start[2]) * cellSize; + var endPosition = origin + new float3(end[0], end[1], end[2]) * cellSize; + sum += Interpolate(startPosition, startValue, endPosition, endValue, isoValue); + count++; + } + } + + private static float3 Interpolate(float3 first, float firstValue, float3 second, float secondValue, float isoValue) + { + // A straddling edge has exactly one endpoint <= isoValue and the other > isoValue, so + // delta is always non-zero (.NET preserves subnormals; there is no value of delta for + // which a fallback produces a better answer than the exact interpolation). + var amount = (isoValue - firstValue) / (secondValue - firstValue); + return math.lerp(first, second, amount); + } + + // The four cells that share the grid edge from (x, y, z) to (x, y, z) + e_axis, listed as a + // perimeter loop around the edge (not crossed diagonally) so the caller can build a quad + // directly from them. The edge's own coordinate is unchanged for all four cells: it is + // guaranteed to already index a valid cell there because the caller's own loop bound + // already verified coord[axis] < cellCounts[axis]. + private static bool TryGetQuadCells(int[] cellCounts, int[] coord, byte axis, out (int, int, int)[] cells) + { + cells = Array.Empty<(int, int, int)>(); + var (u, v) = PerpAxes[axis]; + + if (!InRange(coord[u] - 1, cellCounts[u]) || !InRange(coord[u], cellCounts[u]) || + !InRange(coord[v] - 1, cellCounts[v]) || !InRange(coord[v], cellCounts[v])) + { + return false; + } + + var result = new (int, int, int)[4]; + for (var i = 0; i < 4; i++) + { + var cell = (int[])coord.Clone(); + cell[u] += PerimeterLoop[i].U - 1; + cell[v] += PerimeterLoop[i].V - 1; + result[i] = (cell[0], cell[1], cell[2]); + } + + cells = result; + return true; + } + + private static bool InRange(int value, int count) => value >= 0 && value < count; + + private static void Append(float3 value, List destination) + { + destination.Add(value.x); + destination.Add(value.y); + destination.Add(value.z); + } + } +} diff --git a/src/GameCult.Geometry/GameCult.Geometry.csproj b/src/GameCult.Geometry/GameCult.Geometry.csproj index a3ad9457..c10c2ecf 100644 --- a/src/GameCult.Geometry/GameCult.Geometry.csproj +++ b/src/GameCult.Geometry/GameCult.Geometry.csproj @@ -17,5 +17,6 @@ + diff --git a/src/GameCult.Geometry/SURFACE-NETS-PROVENANCE.md b/src/GameCult.Geometry/SURFACE-NETS-PROVENANCE.md new file mode 100644 index 00000000..d161ede3 --- /dev/null +++ b/src/GameCult.Geometry/SURFACE-NETS-PROVENANCE.md @@ -0,0 +1,49 @@ +# Surface nets extraction provenance + +`CultGeometrySurfaceNets` is a clean implementation of surface nets over a +regular scalar grid. It is implemented fresh from the published algorithm +description; no code or lookup tables were copied from any source. `CultGeometryQuadNormals` +is likewise a fresh implementation of face-weighted vertex normal averaging. + +Cited literature: + +- S. F. F. Gibson, "Constrained Elastic Surface Nets: Generating Smooth + Surfaces from Binary Segmented Data," MICCAI 1998 (MERL Technical Report + TR99-24). +- M. Lysenko, "Smooth Voxel Terrain (Part 2)," 0fps.net, 2012. +- N. Max, "Weights for Computing Vertex Normals from Facet Normals," Journal + of Graphics Tools 4(2), 1999. + +Deliberate behavior: + +- a scalar sample less than or equal to the isovalue is inside, matching + `CultGeometryIsoSurface`'s sign convention; +- a cell's vertex is the mean of the linearly interpolated crossings of its + own twelve edges; +- Gibson's elastic relaxation of the vertex toward its neighbors is omitted; + the vertex stays at the unrelaxed dual-cell mean; +- one quad is emitted per crossing interior grid edge, from the (up to) four + cells that share it; an edge whose four surrounding cells do not all exist + emits no quad, leaving the mesh open at the field boundary; +- quad winding is decided by which of the crossing edge's two endpoints is + inside, times the per-axis handedness table (`OrientationSign`: `+1, -1, + +1`), never by a per-quad geometric test: axis 1's perpendicular pair (X, + Z) is left-handed, so its sign is mirrored relative to axes 0 and 2. On a + non-degenerate (non-zero-area) quad this decision has the outward-facing + property as a corollary: the diagonal cross product of the quad has a + positive dot product with the direction from the edge's inside endpoint to + its outside endpoint. A degenerate quad carries no such geometric property + to check, but still orients consistently with its neighbors because the + rule never looks at its geometry; +- non-finite `isoValue` or `origin` components are rejected, matching the + existing rejection of non-finite samples and cell size; +- an extreme but finite input (a `cellSize` near float's magnitude limit, or + finite samples whose interpolated position overflows to infinity) is a + float-domain overflow, not a validated input error, and is deliberately not + range-checked; +- vertices are welded: one vertex per active cell, shared by every quad + touching that cell; +- face-weighted normals sum each quad's diagonal cross product (unnormalized, + so a bigger quad outweighs a sliver) per touched vertex, then normalize; a + vertex touched only by zero-area quads gets a zero normal rather than NaN, + matching `CultGeometryIsoSurface`'s degenerate-normal rule. diff --git a/tests/GameCult.Geometry.Tests/QuadNormalsTests.cs b/tests/GameCult.Geometry.Tests/QuadNormalsTests.cs new file mode 100644 index 00000000..448c699d --- /dev/null +++ b/tests/GameCult.Geometry.Tests/QuadNormalsTests.cs @@ -0,0 +1,158 @@ +using System; +using FluentAssertions; +using NUnit.Framework; + +namespace GameCult.Geometry.Tests +{ + [TestFixture] + public sealed class QuadNormalsTests + { + [Test] + public void A_sliver_sharing_a_vertex_does_not_move_the_large_quads_normal() + { + // A 10x10 quad in the XY plane (facing +Z) sharing vertex 0 with a near-degenerate + // sliver tilted into the XZ plane. The sliver's area is ~1e6 times smaller. Offset away + // from the origin so a diagonal computed as (p2 + p0) instead of (p2 - p0) is not + // coincidentally the same value (p0 = 0 would erase that distinction). + var mesh = new CultGeometryQuadMesh + { + Positions = new[] + { + // Large quad: 0,1,2,3 + 5f, 7f, 9f, + 15f, 7f, 9f, + 15f, 17f, 9f, + 5f, 17f, 9f, + // Sliver quad: 0 (shared), 4, 5, 6 + 5.001f, 7f, 9f, + 5.001f, 7f, 9.001f, + 5f, 7f, 9.001f, + }, + Quads = new[] + { + 0u, 1u, 2u, 3u, + 0u, 4u, 5u, 6u, + }, + QuadEdges = new[] + { + new CultGeometryGridEdge(0, 0, 0, 2), + new CultGeometryGridEdge(0, 0, 0, 1), + }, + }; + + var normals = CultGeometryQuadNormals.FaceWeighted(mesh); + + normals[0].Should().BeApproximately(0f, 1e-4f); + normals[1].Should().BeApproximately(0f, 1e-4f); + normals[2].Should().BeApproximately(1f, 1e-4f); + } + + [Test] + public void A_closed_cube_gets_unit_length_normals_pointing_away_from_center() + { + var mesh = Cube(); + + var normals = CultGeometryQuadNormals.FaceWeighted(mesh); + + // Each vertex's normal must point away from the cube's center (0.5,0.5,0.5) along every + // axis, i.e. its sign must match the vertex's own offset from the center. Checking the + // exact direction (not just the length) catches a mutant that flips the sign of one of a + // vertex's three contributing faces: three orthogonal +-2-length vectors summed have the + // same length no matter which one is negated, so a length-only check cannot tell them apart. + var oneOverRoot3 = 1f / MathF.Sqrt(3f); + for (var vertex = 0; vertex < mesh.VertexCount; vertex++) + { + var px = mesh.Positions[vertex * 3]; + var py = mesh.Positions[(vertex * 3) + 1]; + var pz = mesh.Positions[(vertex * 3) + 2]; + var expected = new[] + { + px > 0.5f ? oneOverRoot3 : -oneOverRoot3, + py > 0.5f ? oneOverRoot3 : -oneOverRoot3, + pz > 0.5f ? oneOverRoot3 : -oneOverRoot3, + }; + + normals[vertex * 3].Should().BeApproximately(expected[0], 1e-5f); + normals[(vertex * 3) + 1].Should().BeApproximately(expected[1], 1e-5f); + normals[(vertex * 3) + 2].Should().BeApproximately(expected[2], 1e-5f); + } + } + + [Test] + public void A_zero_area_quad_contributes_nothing_and_an_untouched_vertex_is_a_finite_zero() + { + var mesh = new CultGeometryQuadMesh + { + // Vertex 4 is never referenced by any quad. + Positions = new[] + { + 0f, 0f, 0f, + 1f, 0f, 0f, + 2f, 0f, 0f, + 3f, 0f, 0f, + 9f, 9f, 9f, + }, + Quads = new[] { 0u, 1u, 2u, 3u }, + QuadEdges = new[] { new CultGeometryGridEdge(0, 0, 0, 0) }, + }; + + var normals = CultGeometryQuadNormals.FaceWeighted(mesh); + + normals.Should().HaveCount(15); + normals.Should().OnlyContain(value => value == 0f); + normals.Should().OnlyContain(value => float.IsFinite(value)); + } + + [Test] + public void Null_mesh_is_rejected() + { + Action act = () => CultGeometryQuadNormals.FaceWeighted(null!); + + act.Should().Throw(); + } + + private static CultGeometryQuadMesh Cube() + { + // 0..7: (0,0,0) (1,0,0) (1,1,0) (0,1,0) (0,0,1) (1,0,1) (1,1,1) (0,1,1) + var positions = new[] + { + 0f, 0f, 0f, + 1f, 0f, 0f, + 1f, 1f, 0f, + 0f, 1f, 0f, + 0f, 0f, 1f, + 1f, 0f, 1f, + 1f, 1f, 1f, + 0f, 1f, 1f, + }; + + // Each face ordered so d1 x d2 points outward. + var quads = new[] + { + 0u, 3u, 2u, 1u, // -Z + 4u, 5u, 6u, 7u, // +Z + 0u, 1u, 5u, 4u, // -Y + 3u, 7u, 6u, 2u, // +Y + 0u, 4u, 7u, 3u, // -X + 1u, 2u, 6u, 5u, // +X + }; + + var quadEdges = new[] + { + new CultGeometryGridEdge(0, 0, 0, 0), + new CultGeometryGridEdge(0, 0, 0, 1), + new CultGeometryGridEdge(0, 0, 0, 2), + new CultGeometryGridEdge(0, 1, 0, 0), + new CultGeometryGridEdge(1, 0, 0, 1), + new CultGeometryGridEdge(0, 0, 1, 2), + }; + + return new CultGeometryQuadMesh + { + Positions = positions, + Quads = quads, + QuadEdges = quadEdges, + }; + } + } +} diff --git a/tests/GameCult.Geometry.Tests/SurfaceNetsTests.cs b/tests/GameCult.Geometry.Tests/SurfaceNetsTests.cs new file mode 100644 index 00000000..3e3b3892 --- /dev/null +++ b/tests/GameCult.Geometry.Tests/SurfaceNetsTests.cs @@ -0,0 +1,811 @@ +using System; +using System.Collections.Generic; +using FluentAssertions; +using NUnit.Framework; + +namespace GameCult.Geometry.Tests +{ + [TestFixture] + public sealed class SurfaceNetsTests + { + [Test] + public void A_sample_exactly_on_the_isovalue_is_inside_like_a_sample_below_it() + { + var atIso = SingleInsideSample(3, 3, 3, 1, 1, 1, 0f); + var belowIso = SingleInsideSample(3, 3, 3, 1, 1, 1, -1e-4f); + var aboveIso = SingleInsideSample(3, 3, 3, 1, 1, 1, 1e-4f); + + var meshAtIso = CultGeometrySurfaceNets.Extract(atIso); + var meshBelowIso = CultGeometrySurfaceNets.Extract(belowIso); + var meshAboveIso = CultGeometrySurfaceNets.Extract(aboveIso); + + meshAtIso.QuadEdges.Should().Equal(meshBelowIso.QuadEdges); + meshAtIso.QuadCount.Should().Be(6); + meshAboveIso.QuadCount.Should().Be(0); + } + + [Test] + public void A_single_interior_inside_sample_names_its_six_quads_by_their_crossing_edge() + { + var samples = SingleInsideSample(3, 3, 3, 1, 1, 1, -1f); + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(6); + mesh.QuadEdges.Should().BeEquivalentTo(new[] + { + new CultGeometryGridEdge(1, 1, 1, 0), + new CultGeometryGridEdge(1, 1, 1, 1), + new CultGeometryGridEdge(1, 1, 1, 2), + new CultGeometryGridEdge(0, 1, 1, 0), + new CultGeometryGridEdge(1, 0, 1, 1), + new CultGeometryGridEdge(1, 1, 0, 2), + }); + } + + [Test] + public void A_non_cubic_grid_names_quads_by_edge_without_swapping_axes() + { + var samples = SingleInsideSample(4, 3, 5, 2, 1, 2, -1f); + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(6); + mesh.QuadEdges.Should().BeEquivalentTo(new[] + { + new CultGeometryGridEdge(2, 1, 2, 0), + new CultGeometryGridEdge(2, 1, 2, 1), + new CultGeometryGridEdge(2, 1, 2, 2), + new CultGeometryGridEdge(1, 1, 2, 0), + new CultGeometryGridEdge(2, 0, 2, 1), + new CultGeometryGridEdge(2, 1, 1, 2), + }); + } + + [Test] + public void Every_quad_winds_outward_from_inside_to_outside() + { + var samples = SingleInsideSample(3, 3, 3, 1, 1, 1, -1f); + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(6); + for (var quad = 0; quad < mesh.QuadCount; quad++) + { + var edge = mesh.QuadEdges[quad]; + var insideCoord = new CultVec3(1f, 1f, 1f); + var edgeStart = new CultVec3(edge.X, edge.Y, edge.Z); + var edgeEnd = OtherEndpoint(edge); + + // The single inside sample is (1,1,1); the edge's other endpoint is outside. + var outsideCoord = edgeStart.Equals(insideCoord) ? edgeEnd : edgeStart; + var outward = Subtract(outsideCoord, insideCoord); + + var baseIndex = quad * 4; + var v0 = Position(mesh.Positions, mesh.Quads[baseIndex]); + var v1 = Position(mesh.Positions, mesh.Quads[baseIndex + 1]); + var v2 = Position(mesh.Positions, mesh.Quads[baseIndex + 2]); + var v3 = Position(mesh.Positions, mesh.Quads[baseIndex + 3]); + var cross = Cross(Subtract(v2, v0), Subtract(v3, v1)); + + // Restricted to non-degenerate (non-zero-area) quads: the spec's geometric + // winding rule is only meaningful there. Degenerate/collapsed quads are covered + // separately by AssertEdgeDirectionsBalance, since a zero cross product carries + // no orientation information to check here. + if (cross.X == 0f && cross.Y == 0f && cross.Z == 0f) continue; + + Dot(cross, outward).Should().BePositive($"quad for edge {edge} should wind outward"); + } + } + + [Test] + public void A_cells_vertex_is_the_mean_of_its_symmetric_edge_crossing_midpoints() + { + // A single cell with one inside corner cut symmetrically by +-1 values: each of the + // three crossing edges interpolates to its own midpoint. + var samples = new float[2, 2, 2]; + samples[0, 0, 0] = -1f; + samples[1, 0, 0] = 1f; + samples[0, 1, 0] = 1f; + samples[0, 0, 1] = 1f; + samples[1, 1, 0] = 5f; + samples[1, 0, 1] = 5f; + samples[0, 1, 1] = 5f; + samples[1, 1, 1] = 5f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(1f / 6f, 1e-6f); + mesh.Positions[1].Should().BeApproximately(1f / 6f, 1e-6f); + mesh.Positions[2].Should().BeApproximately(1f / 6f, 1e-6f); + } + + [Test] + public void A_cells_vertex_is_the_mean_of_unequal_edge_crossings() + { + var samples = new float[2, 2, 2]; + samples[0, 0, 0] = -1f; + samples[1, 0, 0] = 3f; // crossing at 0.25 along x + samples[0, 1, 0] = 1f; // crossing at 0.5 along y + samples[0, 0, 1] = 4f; // crossing at 0.2 along z + samples[1, 1, 0] = 5f; + samples[1, 0, 1] = 6f; + samples[0, 1, 1] = 7f; + samples[1, 1, 1] = 8f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(0.25f / 3f, 1e-6f); + mesh.Positions[1].Should().BeApproximately(0.5f / 3f, 1e-6f); + mesh.Positions[2].Should().BeApproximately(0.2f / 3f, 1e-6f); + } + + // A single cell's 12 edges form a cube graph (3-regular, 8 vertices): the number of edges + // with differently-signed endpoints (a graph cut) is provably never 1 or 2 for any corner + // sign pattern - the minimum nonzero cut is 3 (one corner opposite the other seven), which + // the two fixtures above already exercise. 4 and 6 below are the next cuts a single cell + // can actually produce; both distinguish sum/count from the sum/3 mutant just as well. + [Test] + public void A_cells_vertex_with_four_crossings_is_their_mean_not_a_third() + { + // One face (x=0) inside, the opposite face (x=1) outside: only the 4 x-axis edges + // cross, each at the same amount since every inside/outside value is uniform. + var samples = new float[2, 2, 2]; + for (var y = 0; y < 2; y++) + for (var z = 0; z < 2; z++) + { + samples[0, y, z] = -1f; + samples[1, y, z] = 3f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + // amount = (0 - -1) / (3 - -1) = 0.25 for all four x-edges, at (y, z) in {0,1}x{0,1}. + // mean = ((0.25,0,0)+(0.25,1,0)+(0.25,0,1)+(0.25,1,1)) / 4 = (0.25, 0.5, 0.5). + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(0.25f, 1e-6f); + mesh.Positions[1].Should().BeApproximately(0.5f, 1e-6f); + mesh.Positions[2].Should().BeApproximately(0.5f, 1e-6f); + } + + [Test] + public void A_cells_vertex_with_six_crossings_is_their_mean_not_a_third() + { + // Two face-diagonal (non-adjacent) corners inside, the other six outside: a cut of 6 + // (3 edges from each inside corner; the two inside corners share no edge). + var samples = new float[2, 2, 2]; + for (var x = 0; x < 2; x++) + for (var y = 0; y < 2; y++) + for (var z = 0; z < 2; z++) samples[x, y, z] = 3f; + + samples[0, 0, 0] = -1f; + samples[1, 1, 0] = -1f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + // amount = (0 - -1) / (3 - -1) = 0.25 for all six crossings (uniform inside/outside + // values). From (0,0,0): (0.25,0,0), (0,0.25,0), (0,0,0.25). + // From (1,1,0): (0.75,1,0), (1,0.75,0), (1,1,0.25). + // mean = (3.0, 3.0, 0.5) / 6 = (0.5, 0.5, 1/12). + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(0.5f, 1e-6f); + mesh.Positions[1].Should().BeApproximately(0.5f, 1e-6f); + mesh.Positions[2].Should().BeApproximately(1f / 12f, 1e-6f); + } + + [Test] + public void Vertex_placement_applies_origin_and_cell_size() + { + // The inside corner is (1,1,1), not (0,0,0): every crossing edge's start sample has at + // least one non-zero coordinate, so a cellSize applied by division instead of + // multiplication (or dropped altogether) changes the result instead of coincidentally + // matching it (a zero component erases that distinction either way). + var samples = new float[2, 2, 2]; + for (var x = 0; x < 2; x++) + for (var y = 0; y < 2; y++) + for (var z = 0; z < 2; z++) samples[x, y, z] = 9f; + + samples[1, 1, 1] = -1f; + + var mesh = CultGeometrySurfaceNets.Extract(samples, origin: new CultVec3(10f, 20f, 30f), cellSize: 2f); + + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(10f + (2.9f / 3f * 2f), 1e-5f); + mesh.Positions[1].Should().BeApproximately(20f + (2.9f / 3f * 2f), 1e-5f); + mesh.Positions[2].Should().BeApproximately(30f + (2.9f / 3f * 2f), 1e-5f); + } + + [TestCase(6)] + [TestCase(8)] + [TestCase(10)] + public void A_closed_sphere_field_welds_into_a_genus_zero_manifold(int size) + { + var samples = Sphere(size); + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().BeGreaterThan(0); + var usage = EdgeUsage(mesh); + usage.Values.Should().OnlyContain(count => count == 2); + (mesh.VertexCount - mesh.QuadCount).Should().Be(2); + } + + [Test] + public void An_ambiguous_checkerboard_field_has_even_but_not_necessarily_manifold_edge_usage() + { + // A checkerboard pattern with a one-sample uniform-outside margin, so every crossing + // edge this exercises has all four surrounding cells in range: any odd usage would be + // a real non-manifold artifact of the ambiguity, not an open-boundary side effect. + var samples = new float[5, 5, 5]; + for (var x = 0; x < 5; x++) + for (var y = 0; y < 5; y++) + for (var z = 0; z < 5; z++) + { + var interior = x is >= 1 and <= 3 && y is >= 1 and <= 3 && z is >= 1 and <= 3; + samples[x, y, z] = interior ? (((x + y + z) % 2 == 0) ? -1f : 1f) : 5f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().BeGreaterThan(0); + var usage = EdgeUsage(mesh); + usage.Values.Should().OnlyContain(count => count % 2 == 0); + } + + [Test] + public void An_open_plane_emits_quads_only_where_all_four_surrounding_cells_exist() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) + { + samples[x, y, z] = x - 1.5f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + // The plane crosses 16 grid edges (all y,z at the x=1|2 boundary), but only the + // interior y,z in {1,2} have all four surrounding cells, so only 4 quads are emitted. + mesh.QuadCount.Should().Be(4); + mesh.QuadEdges.Should().OnlyContain(edge => + edge.X == 1 && edge.Axis == 0 && + (edge.Y == 1 || edge.Y == 2) && + (edge.Z == 1 || edge.Z == 2)); + } + + [Test] + public void An_open_plane_along_y_emits_quads_only_where_all_four_surrounding_cells_exist() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) + { + samples[x, y, z] = y - 1.5f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(4); + mesh.QuadEdges.Should().OnlyContain(edge => + edge.Y == 1 && edge.Axis == 1 && + (edge.X == 1 || edge.X == 2) && + (edge.Z == 1 || edge.Z == 2)); + } + + [Test] + public void An_open_plane_along_z_emits_quads_only_where_all_four_surrounding_cells_exist() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) + { + samples[x, y, z] = z - 1.5f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(4); + mesh.QuadEdges.Should().OnlyContain(edge => + edge.Z == 1 && edge.Axis == 2 && + (edge.X == 1 || edge.X == 2) && + (edge.Y == 1 || edge.Y == 2)); + } + + [Test] + public void A_tiny_but_normal_edge_delta_interpolates_exactly_instead_of_falling_back_to_the_midpoint() + { + // Every crossing edge from the inside corner has firstValue -1e-30f and secondValue + // 3e-21f: a delta of ~3e-21, comfortably inside float's normal range (well above the + // ~1.18e-38 normal floor) but far under the old 1e-20 guard that used to fall back to + // the 0.5 midpoint. The exact amount, computed independently in double precision + // below (not by calling Interpolate), is ~3.33e-10 - nowhere near 0.5. + var samples = new float[2, 2, 2]; + for (var x = 0; x < 2; x++) + for (var y = 0; y < 2; y++) + for (var z = 0; z < 2; z++) samples[x, y, z] = 3e-21f; + + samples[0, 0, 0] = -1e-30f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + var expected = HandDerivedSingleCornerVertex(-1e-30f, 3e-21f); + + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(expected, 1e-12f); + mesh.Positions[1].Should().BeApproximately(expected, 1e-12f); + mesh.Positions[2].Should().BeApproximately(expected, 1e-12f); + } + + [Test] + public void A_subnormal_edge_delta_interpolates_exactly_instead_of_falling_back_to_the_midpoint() + { + // Both endpoints of every crossing edge from the inside corner are themselves + // subnormal floats (|value| well under the ~1.1755e-38 normal floor), so the delta + // between them is subnormal too. .NET keeps subnormal precision, so this must + // interpolate exactly rather than fall back to 0.5, same as the tiny-but-normal case. + var samples = new float[2, 2, 2]; + for (var x = 0; x < 2; x++) + for (var y = 0; y < 2; y++) + for (var z = 0; z < 2; z++) samples[x, y, z] = 3e-40f; + + samples[0, 0, 0] = -1e-40f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + var expected = HandDerivedSingleCornerVertex(-1e-40f, 3e-40f); + + mesh.VertexCount.Should().Be(1); + mesh.Positions[0].Should().BeApproximately(expected, 1e-6f); + mesh.Positions[1].Should().BeApproximately(expected, 1e-6f); + mesh.Positions[2].Should().BeApproximately(expected, 1e-6f); + } + + // The four cells around a crossing edge are documented as a perimeter loop in a specific + // cyclic order per axis (see TryGetQuadCells). Each of the three tests below pins that + // exact order end to end (which welded vertex position lands in Quads[0..3]) for one axis, + // using an open-plane fixture whose four relevant cells have distinct, hand-computable + // vertex positions, so swapping or mirroring any of the four is directly observable. + [Test] + public void An_axis_0_quads_corners_follow_the_documented_perimeter_order() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) samples[x, y, z] = x - 1.5f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + var edge = new CultGeometryGridEdge(1, 1, 1, 0); + + // Cells (x, y-1, z-1), (x, y, z-1), (x, y, z), (x, y-1, z) each have their vertex at + // the cell's own (y, z) center, since the field only varies with x: (1.5, cy+0.5, + // cz+0.5). The edge's low end (x=1) is inside and axis 0 is not mirrored, so the + // documented c0..c3 order is not swapped. + var expected = new[] + { + new CultVec3(1.5f, 0.5f, 0.5f), // c0 = (1, 0, 0) + new CultVec3(1.5f, 1.5f, 0.5f), // c1 = (1, 1, 0) + new CultVec3(1.5f, 1.5f, 1.5f), // c2 = (1, 1, 1) + new CultVec3(1.5f, 0.5f, 1.5f), // c3 = (1, 0, 1) + }; + + AssertQuadCorners(mesh, edge, expected); + } + + [Test] + public void An_axis_1_quads_corners_follow_the_documented_perimeter_order() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) samples[x, y, z] = y - 1.5f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + var edge = new CultGeometryGridEdge(1, 1, 1, 1); + + // Cells (x-1, y, z-1), (x, y, z-1), (x, y, z), (x-1, y, z) each have their vertex at + // (cx+0.5, 1.5, cz+0.5). The edge's low end (y=1) is inside, but axis 1 is the + // mirrored one (OrientationSign[1] < 0), so the documented order is swapped: v1 and + // v3 trade places relative to the raw c0..c3 listing. + var expected = new[] + { + new CultVec3(0.5f, 1.5f, 0.5f), // c0 = (0, 1, 0) + new CultVec3(0.5f, 1.5f, 1.5f), // c3 = (0, 1, 1), swapped into v1 + new CultVec3(1.5f, 1.5f, 1.5f), // c2 = (1, 1, 1) + new CultVec3(1.5f, 1.5f, 0.5f), // c1 = (1, 1, 0), swapped into v3 + }; + + AssertQuadCorners(mesh, edge, expected); + } + + [Test] + public void An_axis_2_quads_corners_follow_the_documented_perimeter_order() + { + var samples = new float[4, 4, 4]; + for (var x = 0; x < 4; x++) + for (var y = 0; y < 4; y++) + for (var z = 0; z < 4; z++) samples[x, y, z] = z - 1.5f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + var edge = new CultGeometryGridEdge(1, 1, 1, 2); + + // Cells (x-1, y-1, z), (x, y-1, z), (x, y, z), (x-1, y, z) each have their vertex at + // (cx+0.5, cy+0.5, 1.5). The edge's low end (z=1) is inside and axis 2 is not + // mirrored, so the documented c0..c3 order is not swapped. + var expected = new[] + { + new CultVec3(0.5f, 0.5f, 1.5f), // c0 = (0, 0, 1) + new CultVec3(1.5f, 0.5f, 1.5f), // c1 = (1, 0, 1) + new CultVec3(1.5f, 1.5f, 1.5f), // c2 = (1, 1, 1) + new CultVec3(0.5f, 1.5f, 1.5f), // c3 = (0, 1, 1) + }; + + AssertQuadCorners(mesh, edge, expected); + } + + // The spec's orientation rule "(d1 x d2).(outside - inside) > 0" still holds on + // non-degenerate quads (Every_quad_winds_outward_from_inside_to_outside above pins that + // directly). These fixtures target the cases the old per-quad geometric fallback got + // wrong: quads that collapse to zero area, where orientation must still come from + // topology alone and every shared undirected edge must still be traversed in opposite + // directions by its two (or four) quads. + [Test] + public void A_sample_exactly_at_the_isovalue_collapses_every_quad_but_edges_still_balance() + { + // The inside sample equals isoValue exactly, so every crossing edge from it + // interpolates to amount 0: all six quads around it collapse onto the same point. + var samples = SingleInsideSample(3, 3, 3, 1, 1, 1, 0f); + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().Be(6); + AssertEdgeDirectionsBalance(mesh); + } + + [Test] + public void A_sphere_at_a_huge_origin_with_a_tiny_cell_size_collapses_quads_but_edges_still_balance() + { + // A large origin combined with a tiny cell size used to erase the float32 precision + // the old geometric fallback needed: vertex positions could round to the same value + // even for non-degenerate quads, making the per-quad cross product an unreliable + // orientation source. Orientation no longer reads positions at all, so this must + // balance regardless. + var samples = Sphere(64); + + var mesh = CultGeometrySurfaceNets.Extract(samples, origin: new CultVec3(1e4f, 1e4f, 1e4f), cellSize: 0.001f); + + mesh.QuadCount.Should().BeGreaterThan(0); + AssertEdgeDirectionsBalance(mesh); + } + + [Test] + public void An_octahedron_field_sampled_exactly_at_the_isovalue_collapses_quads_but_edges_still_balance() + { + // An L1-distance ("octahedron") field with the radius chosen to land exactly on + // several lattice points: those quads collapse just like the single-sample case. A + // one-sample uniform-outside margin (same as the checkerboard fixture elsewhere in + // this file) keeps every crossing edge's four surrounding cells in range, so an + // open-boundary artifact can't masquerade as an orientation imbalance. + var samples = new float[5, 5, 5]; + for (var x = 0; x < 5; x++) + for (var y = 0; y < 5; y++) + for (var z = 0; z < 5; z++) + { + var interior = x is >= 1 and <= 3 && y is >= 1 and <= 3 && z is >= 1 and <= 3; + samples[x, y, z] = interior ? Math.Abs(x - 2) + Math.Abs(y - 2) + Math.Abs(z - 2) - 1f : 5f; + } + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().BeGreaterThan(0); + AssertEdgeDirectionsBalance(mesh); + } + + [Test] + public void A_field_within_a_tiny_tolerance_of_the_isovalue_collapses_quads_but_edges_still_balance() + { + // A sphere field scaled down by 1e-9 so most non-boundary values sit within 1e-8 of + // the isovalue without changing which side of it they are on (scaling preserves sign). + var samples = Sphere(10); + for (var x = 0; x < 10; x++) + for (var y = 0; y < 10; y++) + for (var z = 0; z < 10; z++) samples[x, y, z] *= 1e-9f; + + var mesh = CultGeometrySurfaceNets.Extract(samples); + + mesh.QuadCount.Should().BeGreaterThan(0); + AssertEdgeDirectionsBalance(mesh); + } + + [Test] + public void Extraction_is_deterministic_and_quad_edges_are_strictly_ascending() + { + var samples = Sphere(8); + + var first = CultGeometrySurfaceNets.Extract(samples); + var second = CultGeometrySurfaceNets.Extract(samples); + + second.Positions.Should().Equal(first.Positions); + second.Quads.Should().Equal(first.Quads); + second.QuadEdges.Should().Equal(first.QuadEdges); + + for (var index = 1; index < first.QuadEdges.Length; index++) + { + first.QuadEdges[index].CompareTo(first.QuadEdges[index - 1]).Should().BePositive(); + } + } + + [Test] + public void Grid_edge_equality_requires_every_component_to_match() + { + var edge = new CultGeometryGridEdge(1, 2, 3, 0); + + (edge == new CultGeometryGridEdge(1, 2, 3, 0)).Should().BeTrue(); + (edge == new CultGeometryGridEdge(9, 2, 3, 0)).Should().BeFalse(); + (edge == new CultGeometryGridEdge(1, 9, 3, 0)).Should().BeFalse(); + (edge == new CultGeometryGridEdge(1, 2, 9, 0)).Should().BeFalse(); + (edge == new CultGeometryGridEdge(1, 2, 3, 1)).Should().BeFalse(); + } + + [Test] + public void Grid_edge_object_equals_distinguishes_every_component_and_rejects_null_and_other_types() + { + var edge = new CultGeometryGridEdge(1, 2, 3, 0); + object same = new CultGeometryGridEdge(1, 2, 3, 0); + object diffX = new CultGeometryGridEdge(9, 2, 3, 0); + object diffY = new CultGeometryGridEdge(1, 9, 3, 0); + object diffZ = new CultGeometryGridEdge(1, 2, 9, 0); + object diffAxis = new CultGeometryGridEdge(1, 2, 3, 1); + + edge.Equals(same).Should().BeTrue(); + edge.Equals(diffX).Should().BeFalse(); + edge.Equals(diffY).Should().BeFalse(); + edge.Equals(diffZ).Should().BeFalse(); + edge.Equals(diffAxis).Should().BeFalse(); + edge.Equals(null).Should().BeFalse(); + edge.Equals("not an edge").Should().BeFalse(); + edge.Equals((object)42).Should().BeFalse(); + + // object.Equals must agree with the typed Equals(CultGeometryGridEdge) it delegates to, + // and with GetHashCode wherever the two report equal, so the type is safe as a + // dictionary/set key (Extract uses it as one via vertexIndex's cell-coordinate tuples' + // sibling role, and tests key EdgeUsage dictionaries by it directly). + edge.Equals(same).Should().Be(edge.Equals((CultGeometryGridEdge)same)); + edge.GetHashCode().Should().Be(((CultGeometryGridEdge)same).GetHashCode()); + } + + [Test] + public void Grid_edge_inequality_is_the_negation_of_equality() + { + // != has no caller of its own; it exists only because C# requires it whenever == is + // defined (CS0216). This is its only direct test. + var edge = new CultGeometryGridEdge(1, 2, 3, 0); + + (edge != new CultGeometryGridEdge(1, 2, 3, 0)).Should().BeFalse(); + (edge != new CultGeometryGridEdge(9, 2, 3, 0)).Should().BeTrue(); + } + + [Test] + public void Grid_edge_to_string_names_its_coordinates_and_axis() + { + var edge = new CultGeometryGridEdge(1, 2, 3, 2); + + edge.ToString().Should().Be("(1, 2, 3)+e2"); + } + + [Test] + public void Null_field_is_rejected() + { + Action act = () => CultGeometrySurfaceNets.Extract(null!); + + act.Should().Throw(); + } + + [Test] + public void Invalid_field_shape_is_rejected() + { + Action act = () => CultGeometrySurfaceNets.Extract(new float[1, 2, 2]); + + act.Should().Throw(); + } + + [TestCase(0f)] + [TestCase(-1f)] + [TestCase(float.NaN)] + [TestCase(float.PositiveInfinity)] + public void Invalid_cell_size_is_rejected(float cellSize) + { + var samples = new float[2, 2, 2]; + + Action act = () => CultGeometrySurfaceNets.Extract(samples, cellSize: cellSize); + + act.Should().Throw(); + } + + [TestCase(float.NegativeInfinity)] + [TestCase(float.PositiveInfinity)] + [TestCase(float.NaN)] + public void A_non_finite_isoValue_is_rejected(float nonFiniteValue) + { + var samples = new float[2, 2, 2]; + + Action act = () => CultGeometrySurfaceNets.Extract(samples, isoValue: nonFiniteValue); + + act.Should().Throw(); + } + + [TestCase(float.NegativeInfinity, 0f, 0f)] + [TestCase(float.PositiveInfinity, 0f, 0f)] + [TestCase(float.NaN, 0f, 0f)] + [TestCase(0f, float.NegativeInfinity, 0f)] + [TestCase(0f, float.PositiveInfinity, 0f)] + [TestCase(0f, float.NaN, 0f)] + [TestCase(0f, 0f, float.NegativeInfinity)] + [TestCase(0f, 0f, float.PositiveInfinity)] + [TestCase(0f, 0f, float.NaN)] + public void A_non_finite_origin_component_is_rejected(float x, float y, float z) + { + var samples = new float[2, 2, 2]; + + Action act = () => CultGeometrySurfaceNets.Extract(samples, origin: new CultVec3(x, y, z)); + + act.Should().Throw(); + } + + [TestCase(float.NegativeInfinity)] + [TestCase(float.PositiveInfinity)] + [TestCase(float.NaN)] + public void A_non_finite_sample_is_rejected(float nonFiniteValue) + { + var samples = new float[2, 2, 2]; + samples[0, 0, 0] = nonFiniteValue; + + Action act = () => CultGeometrySurfaceNets.Extract(samples); + + act.Should().Throw(); + } + + private static float[,,] SingleInsideSample(int sizeX, int sizeY, int sizeZ, int ix, int iy, int iz, float insideValue) + { + var samples = new float[sizeX, sizeY, sizeZ]; + for (var x = 0; x < sizeX; x++) + for (var y = 0; y < sizeY; y++) + for (var z = 0; z < sizeZ; z++) samples[x, y, z] = 1f; + + samples[ix, iy, iz] = insideValue; + return samples; + } + + private static float[,,] Sphere(int size) + { + var samples = new float[size, size, size]; + var center = (size - 1) / 2f; + var radius = center - 1f; + for (var x = 0; x < size; x++) + for (var y = 0; y < size; y++) + for (var z = 0; z < size; z++) + { + var dx = x - center; + var dy = y - center; + var dz = z - center; + var distance = MathF.Sqrt(dx * dx + dy * dy + dz * dz); + samples[x, y, z] = distance - radius; + } + + return samples; + } + + private static Dictionary<(uint, uint), int> EdgeUsage(CultGeometryQuadMesh mesh) + { + var usage = new Dictionary<(uint, uint), int>(); + for (var quad = 0; quad < mesh.QuadCount; quad++) + { + var baseIndex = quad * 4; + var indices = new[] + { + mesh.Quads[baseIndex], + mesh.Quads[baseIndex + 1], + mesh.Quads[baseIndex + 2], + mesh.Quads[baseIndex + 3], + }; + + for (var edge = 0; edge < 4; edge++) + { + var a = indices[edge]; + var b = indices[(edge + 1) % 4]; + var key = a < b ? (a, b) : (b, a); + usage[key] = usage.GetValueOrDefault(key) + 1; + } + } + + return usage; + } + + private static CultVec3 OtherEndpoint(CultGeometryGridEdge edge) => edge.Axis switch + { + 0 => new CultVec3(edge.X + 1, edge.Y, edge.Z), + 1 => new CultVec3(edge.X, edge.Y + 1, edge.Z), + _ => new CultVec3(edge.X, edge.Y, edge.Z + 1), + }; + + private static CultVec3 Subtract(CultVec3 left, CultVec3 right) => + new(left.X - right.X, left.Y - right.Y, left.Z - right.Z); + + private static CultVec3 Cross(CultVec3 left, CultVec3 right) => new( + (left.Y * right.Z) - (left.Z * right.Y), + (left.Z * right.X) - (left.X * right.Z), + (left.X * right.Y) - (left.Y * right.X)); + + private static float Dot(CultVec3 left, CultVec3 right) => + (left.X * right.X) + (left.Y * right.Y) + (left.Z * right.Z); + + private static CultVec3 Position(float[] positions, uint index) + { + var offset = (int)index * 3; + return new CultVec3(positions[offset], positions[offset + 1], positions[offset + 2]); + } + + // Hand-derived (double precision, independent of Interpolate) expected position for a + // single-inside-corner-at-origin fixture where every one of the three crossing edges has + // the same firstValue/secondValue pair. + private static float HandDerivedSingleCornerVertex(float insideValue, float outsideValue) + { + double first = insideValue; + double second = outsideValue; + var amount = (0d - first) / (second - first); + return (float)(amount / 3d); + } + + private static void AssertQuadCorners(CultGeometryQuadMesh mesh, CultGeometryGridEdge edge, CultVec3[] expected) + { + var quadIndex = Array.IndexOf(mesh.QuadEdges, edge); + quadIndex.Should().BeGreaterThanOrEqualTo(0, $"a quad for edge {edge} should exist"); + + var baseIndex = quadIndex * 4; + for (var i = 0; i < 4; i++) + { + Position(mesh.Positions, mesh.Quads[baseIndex + i]).Should().Be(expected[i], + $"corner {i} of the quad for edge {edge} should be {expected[i]}"); + } + } + + // Every shared undirected edge of a welded quad mesh must be traversed in opposite + // directions by the quads that share it (net zero over a(); + for (var quad = 0; quad < mesh.QuadCount; quad++) + { + var baseIndex = quad * 4; + var indices = new[] + { + mesh.Quads[baseIndex], + mesh.Quads[baseIndex + 1], + mesh.Quads[baseIndex + 2], + mesh.Quads[baseIndex + 3], + }; + + for (var edge = 0; edge < 4; edge++) + { + var a = indices[edge]; + var b = indices[(edge + 1) % 4]; + if (a == b) continue; + + var key = a < b ? (a, b) : (b, a); + var sign = a < b ? 1 : -1; + net[key] = net.GetValueOrDefault(key) + sign; + } + } + + net.Values.Should().OnlyContain(value => value == 0, + "every shared undirected edge should be traversed in opposite directions by its quads"); + } + } +} diff --git a/tests/GameCult.Geometry.Tests/stryker-config.json b/tests/GameCult.Geometry.Tests/stryker-config.json new file mode 100644 index 00000000..f86bc1ba --- /dev/null +++ b/tests/GameCult.Geometry.Tests/stryker-config.json @@ -0,0 +1,11 @@ +{ + "stryker-config": { + "project": "GameCult.Geometry.csproj", + "mutate": [ + "**/src/GameCult.Geometry/**/*.cs" + ], + "mutation-level": "Standard", + "reporters": [ "progress", "html", "json" ], + "thresholds": { "high": 80, "low": 60, "break": 0 } + } +}