@math.gl/geometry 5.0.0-beta.1 → 5.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/culling/index.cjs +40 -7
  2. package/dist/culling/index.cjs.map +3 -3
  3. package/dist/culling/index.d.ts +2 -0
  4. package/dist/culling/index.d.ts.map +1 -1
  5. package/dist/culling/index.js +1 -0
  6. package/dist/culling/index.js.map +1 -1
  7. package/dist/culling/screen-ray.d.ts +22 -0
  8. package/dist/culling/screen-ray.d.ts.map +1 -0
  9. package/dist/culling/screen-ray.js +55 -0
  10. package/dist/culling/screen-ray.js.map +1 -0
  11. package/dist/index.cjs +272 -34
  12. package/dist/index.cjs.map +3 -3
  13. package/dist/index.d.ts +3 -0
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +2 -0
  16. package/dist/index.js.map +1 -1
  17. package/dist/polygon/earcut.d.ts.map +1 -1
  18. package/dist/polygon/earcut.js +100 -34
  19. package/dist/polygon/earcut.js.map +1 -1
  20. package/dist/polygon/subdivide-triangle-mesh.d.ts +10 -0
  21. package/dist/polygon/subdivide-triangle-mesh.d.ts.map +1 -1
  22. package/dist/polygon/subdivide-triangle-mesh.js +13 -3
  23. package/dist/polygon/subdivide-triangle-mesh.js.map +1 -1
  24. package/dist/utils/compose-attribute-provenance.d.ts +13 -0
  25. package/dist/utils/compose-attribute-provenance.d.ts.map +1 -0
  26. package/dist/utils/compose-attribute-provenance.js +63 -0
  27. package/dist/utils/compose-attribute-provenance.js.map +1 -0
  28. package/dist/utils/qualify-surface-transition.d.ts +21 -0
  29. package/dist/utils/qualify-surface-transition.d.ts.map +1 -0
  30. package/dist/utils/qualify-surface-transition.js +140 -0
  31. package/dist/utils/qualify-surface-transition.js.map +1 -0
  32. package/package.json +3 -3
  33. package/src/culling/index.ts +2 -0
  34. package/src/culling/screen-ray.ts +75 -0
  35. package/src/index.ts +4 -0
  36. package/src/polygon/earcut.ts +98 -37
  37. package/src/polygon/subdivide-triangle-mesh.ts +22 -2
  38. package/src/utils/compose-attribute-provenance.ts +74 -0
  39. package/src/utils/qualify-surface-transition.ts +169 -0
@@ -36,6 +36,15 @@ export type SubdivideTriangleMeshOptions = SubdivisionOptions &
36
36
  refinement?: 'transform-error';
37
37
  /** Positive, finite sampled error tolerance across target components, in target units. */
38
38
  tolerance: number;
39
+ /** Optional application metric in tolerance units. Receives fresh sample arrays.
40
+ * Must return a finite nonnegative value. Exceptions propagate.
41
+ * Does not change output coordinates or provide a continuous error guarantee.
42
+ */
43
+ errorMetric?: (sample: {
44
+ source: readonly number[];
45
+ exact: readonly number[];
46
+ interpolated: readonly number[];
47
+ }) => number;
39
48
  /** Positive maximum Euclidean source-edge length. Default Infinity. */
40
49
  maxEdgeLength?: number;
41
50
  }
@@ -44,6 +53,7 @@ export type SubdivideTriangleMeshOptions = SubdivisionOptions &
44
53
  refinement: 'source-edge';
45
54
  /** No target-space tolerance is evaluated in source-edge mode. */
46
55
  tolerance?: never;
56
+ errorMetric?: never;
47
57
  /** Positive, finite maximum Euclidean edge length across all source components. */
48
58
  maxEdgeLength: number;
49
59
  }
@@ -93,6 +103,7 @@ export function subdivideTriangleMesh(
93
103
  const {
94
104
  transform,
95
105
  tolerance,
106
+ errorMetric,
96
107
  refinement = 'transform-error',
97
108
  size = 2,
98
109
  targetSize = size,
@@ -148,11 +159,14 @@ export function subdivideTriangleMesh(
148
159
  function validateOptions(): void {
149
160
  if (
150
161
  typeof transform !== 'function' ||
162
+ (errorMetric !== undefined && typeof errorMetric !== 'function') ||
151
163
  (refinement !== 'transform-error' && refinement !== 'source-edge') ||
152
164
  (refinement === 'transform-error' &&
153
165
  (tolerance === undefined || !Number.isFinite(tolerance) || tolerance <= 0)) ||
154
166
  (refinement === 'source-edge' &&
155
- (tolerance !== undefined || !Number.isFinite(maxEdgeLength))) ||
167
+ (tolerance !== undefined ||
168
+ errorMetric !== undefined ||
169
+ !Number.isFinite(maxEdgeLength))) ||
156
170
  (size !== 2 && size !== 3) ||
157
171
  (targetSize !== 2 && targetSize !== 3) ||
158
172
  !(maxEdgeLength > 0) ||
@@ -195,7 +209,13 @@ export function subdivideTriangleMesh(
195
209
  points.map(p => p.target),
196
210
  weights
197
211
  );
198
- return Math.hypot(...project(source).map((value, i) => value - linearTarget[i]));
212
+ const exact = project(source);
213
+ if (!errorMetric) return Math.hypot(...exact.map((value, i) => value - linearTarget[i]));
214
+ const value = errorMetric({source, exact, interpolated: linearTarget});
215
+ if (!Number.isFinite(value) || value < 0) {
216
+ throw new RangeError('errorMetric must return a finite nonnegative value');
217
+ }
218
+ return value;
199
219
  }
200
220
 
201
221
  function needsRefinement(face: Face): boolean {
@@ -0,0 +1,74 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ import type {AttributeInterpolationProvenance} from './interpolate-packed-attributes';
5
+
6
+ /** Compose child→intermediate and intermediate→original barycentric provenance.
7
+ * Interpolate attributes only after composition, avoiding repeated integer rounding.
8
+ * More than three distinct contributors rejects: this contract describes source
9
+ * triangles, not arbitrary sparse blending. Zero-weight indices are ignored.
10
+ */
11
+ export function composeAttributeProvenance(
12
+ parent: AttributeInterpolationProvenance,
13
+ child: AttributeInterpolationProvenance,
14
+ options: {maxVertices?: number} = {}
15
+ ): {sourceVertexIndices: Uint32Array; sourceVertexWeights: Float64Array} {
16
+ const limit = options.maxVertices ?? 65536;
17
+ if (!Number.isSafeInteger(limit) || limit < 0 || limit > 0xffffffff)
18
+ throw new RangeError('Invalid provenance vertex limit');
19
+ validate(parent);
20
+ validate(child, parent.sourceVertexIndices.length / 3);
21
+ if (child.sourceVertexIndices.length / 3 > limit)
22
+ throw new RangeError('Provenance composition exceeded maxVertices');
23
+ const indices = new Uint32Array(child.sourceVertexIndices.length);
24
+ const weights = new Float64Array(indices.length);
25
+ for (let vertex = 0; vertex < indices.length / 3; vertex++) {
26
+ const contributors = new Map<number, number>();
27
+ for (let j = 0; j < 3; j++) {
28
+ const weight = child.sourceVertexWeights[3 * vertex + j];
29
+ if (!weight) continue;
30
+ const intermediate = child.sourceVertexIndices[3 * vertex + j];
31
+ for (let k = 0; k < 3; k++) {
32
+ const w = weight * parent.sourceVertexWeights[3 * intermediate + k];
33
+ if (!w) continue;
34
+ const index = parent.sourceVertexIndices[3 * intermediate + k];
35
+ contributors.set(index, (contributors.get(index) ?? 0) + w);
36
+ }
37
+ }
38
+ if (contributors.size > 3)
39
+ throw new RangeError('Composed vertex spans multiple source triangles');
40
+ const sum = Array.from(contributors.values()).reduce((a, b) => a + b, 0);
41
+ let slot = 3 * vertex;
42
+ for (const [index, weight] of contributors) {
43
+ indices[slot] = index;
44
+ weights[slot++] = weight / sum;
45
+ }
46
+ }
47
+ return {sourceVertexIndices: indices, sourceVertexWeights: weights};
48
+ }
49
+
50
+ function validate(p: AttributeInterpolationProvenance, count = 0x100000000) {
51
+ if (
52
+ !Number.isSafeInteger(p.sourceVertexIndices.length) ||
53
+ p.sourceVertexIndices.length < 0 ||
54
+ p.sourceVertexIndices.length % 3 ||
55
+ p.sourceVertexIndices.length !== p.sourceVertexWeights.length
56
+ )
57
+ throw new RangeError('Invalid provenance lengths');
58
+ for (let i = 0; i < p.sourceVertexIndices.length; i += 3) {
59
+ let sum = 0;
60
+ for (let j = 0; j < 3; j++) {
61
+ const w = p.sourceVertexWeights[i + j],
62
+ index = p.sourceVertexIndices[i + j];
63
+ if (
64
+ !Number.isFinite(w) ||
65
+ w < 0 ||
66
+ w > 1 ||
67
+ (w > 0 && (!Number.isSafeInteger(index) || index < 0 || index >= count))
68
+ )
69
+ throw new RangeError('Invalid provenance contributor');
70
+ sum += w;
71
+ }
72
+ if (Math.abs(sum - 1) > 1e-10) throw new RangeError('Provenance weights must sum to one');
73
+ }
74
+ }
@@ -0,0 +1,169 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ import type {TriangleMesh} from '../polygon/subdivide-triangle-mesh';
5
+
6
+ export type SurfaceTransitionQualification = {
7
+ /** A fixed indexed disk stays a graph over XY throughout linear vertex interpolation. */
8
+ scope: 'convex-xy-disk-linear';
9
+ minimumProjectedDoubleArea: number;
10
+ boundary: Uint32Array;
11
+ };
12
+
13
+ /** Qualify a conservative subset of 3D mesh morphs, without time sampling.
14
+ * Input is an oriented, connected triangulated disk. Both endpoints share indices.
15
+ * Every triangle must retain positive XY orientation and the boundary must stay
16
+ * convex throughout linear vertex motion. Quadratic extrema test the full [0,1].
17
+ * This excludes holes, folded surfaces, most global globe meshes and curved vertex
18
+ * trajectories. It qualifies the piecewise-linear mesh, not its underlying smooth
19
+ * projection or a camera's approximation error. Floating-point margins reject
20
+ * near-degeneracy; this is not a formal interval-arithmetic certificate.
21
+ */
22
+ export function qualifySurfaceTransition(
23
+ mesh: TriangleMesh,
24
+ targetPositions: ArrayLike<number>,
25
+ options: {minimumDoubleArea?: number; maxChecks?: number} = {}
26
+ ): SurfaceTransitionQualification {
27
+ const from = Array.from(mesh.positions),
28
+ to = Array.from(targetPositions),
29
+ indices = Array.from(mesh.indices),
30
+ count = from.length / 3,
31
+ maxChecks = options.maxChecks ?? 1000000;
32
+ if (
33
+ !from.length ||
34
+ from.length % 3 ||
35
+ to.length !== from.length ||
36
+ !indices.length ||
37
+ indices.length % 3 ||
38
+ !from.every(Number.isFinite) ||
39
+ !to.every(Number.isFinite) ||
40
+ !indices.every(i => Number.isSafeInteger(i) && i >= 0 && i < count) ||
41
+ !Number.isSafeInteger(maxChecks) ||
42
+ maxChecks < 0
43
+ )
44
+ throw new RangeError('Invalid surface transition mesh or budget');
45
+ let scale = 0;
46
+ for (const positions of [from, to])
47
+ for (let i = 0; i < indices.length; i += 3)
48
+ for (let j = 0; j < 3; j++) {
49
+ const a = indices[i + j] * 3,
50
+ b = indices[i + ((j + 1) % 3)] * 3;
51
+ scale = Math.max(
52
+ scale,
53
+ Math.hypot(positions[b] - positions[a], positions[b + 1] - positions[a + 1])
54
+ );
55
+ }
56
+ const margin = options.minimumDoubleArea ?? scale * scale * 1e-12;
57
+ if (!Number.isFinite(margin) || margin <= 0)
58
+ throw new RangeError('Expected positive finite area margin');
59
+ let checks = 0;
60
+ const tick = () => {
61
+ if (++checks > maxChecks) throw new RangeError('Surface qualification exceeded maxChecks');
62
+ };
63
+ const edges = new Map<string, {a: number; b: number; faces: number}>(),
64
+ used = new Set(indices);
65
+ let minimum = Infinity;
66
+ const orientation = (a: number, b: number, c: number, t: number) => {
67
+ // Interpolate relative edges, avoiding cancellation from translating a patch
68
+ // across large world-coordinate origins before subtracting vertex positions.
69
+ const edge = (v: number, k: number) =>
70
+ (from[3 * v + k] - from[3 * a + k]) * (1 - t) + (to[3 * v + k] - to[3 * a + k]) * t;
71
+ return edge(b, 0) * edge(c, 1) - edge(b, 1) * edge(c, 0);
72
+ };
73
+ const minimumOrientation = (a: number, b: number, c: number) => {
74
+ tick();
75
+ return quadraticMinimum(t => orientation(a, b, c, t));
76
+ };
77
+ for (let i = 0; i < indices.length; i += 3) {
78
+ const tri = indices.slice(i, i + 3);
79
+ const area = minimumOrientation(tri[0], tri[1], tri[2]);
80
+ if (area < margin) throw new RangeError('Triangle collapses or reverses during transition');
81
+ minimum = Math.min(minimum, area);
82
+ for (let j = 0; j < 3; j++) {
83
+ const a = tri[j],
84
+ b = tri[(j + 1) % 3],
85
+ key = a < b ? `${a}:${b}` : `${b}:${a}`,
86
+ edge = edges.get(key);
87
+ if (edge) {
88
+ if (edge.faces !== 1 || edge.a !== b || edge.b !== a)
89
+ throw new RangeError('Expected oriented manifold edges');
90
+ edge.faces++;
91
+ } else edges.set(key, {a, b, faces: 1});
92
+ }
93
+ }
94
+ const next = new Map<number, number>();
95
+ for (const edge of edges.values())
96
+ if (edge.faces === 1) {
97
+ if (next.has(edge.a)) throw new RangeError('Nonmanifold boundary');
98
+ next.set(edge.a, edge.b);
99
+ }
100
+ if (!next.size || used.size !== count || used.size - edges.size + indices.length / 3 !== 1)
101
+ throw new RangeError('Expected a triangulated disk without unused vertices');
102
+ const start = next.keys().next().value!,
103
+ boundary: number[] = [];
104
+ const visitedBoundary = new Set<number>();
105
+ let v = start;
106
+ do {
107
+ if (visitedBoundary.has(v) || !next.has(v)) throw new RangeError('Expected one boundary cycle');
108
+ visitedBoundary.add(v);
109
+ boundary.push(v);
110
+ v = next.get(v)!;
111
+ } while (v !== start);
112
+ if (boundary.length !== next.size) throw new RangeError('Multiple boundary cycles');
113
+ // Every boundary vertex stays left of each directed support edge. This allows
114
+ // collinear refinement vertices while rejecting a nonconvex or crossing outline.
115
+ for (let i = 0; i < boundary.length; i++) {
116
+ const a = boundary[i],
117
+ b = boundary[(i + 1) % boundary.length];
118
+ // Distinct boundary vertices rule out multiple winding of a convex outline
119
+ // (a locally positive double-cover fan would otherwise pass support tests).
120
+ for (let j = i + 1; j < boundary.length; j++) {
121
+ tick();
122
+ const c = boundary[j];
123
+ const separation = quadraticMinimum(t => {
124
+ const dx = (from[3 * c] - from[3 * a]) * (1 - t) + (to[3 * c] - to[3 * a]) * t,
125
+ dy = (from[3 * c + 1] - from[3 * a + 1]) * (1 - t) + (to[3 * c + 1] - to[3 * a + 1]) * t;
126
+ return dx * dx + dy * dy;
127
+ });
128
+ if (separation < margin) throw new RangeError('Boundary vertices meet during transition');
129
+ }
130
+ for (const c of boundary)
131
+ if (c !== a && c !== b && minimumOrientation(a, b, c) < -margin * 1e-3)
132
+ throw new RangeError('Boundary is not convex throughout transition');
133
+ }
134
+ // Euler characteristic plus one boundary is insufficient if a closed component
135
+ // is present. Explicitly require connectivity of the vertex graph.
136
+ const neighbors = Array.from({length: count}, () => [] as number[]);
137
+ for (const {a, b} of edges.values()) {
138
+ neighbors[a].push(b);
139
+ neighbors[b].push(a);
140
+ }
141
+ const seen = new Set<number>([start]),
142
+ queue = [start];
143
+ for (let i = 0; i < queue.length; i++)
144
+ for (const n of neighbors[queue[i]])
145
+ if (!seen.has(n)) {
146
+ seen.add(n);
147
+ queue.push(n);
148
+ }
149
+ if (seen.size !== count) throw new RangeError('Disconnected surface mesh');
150
+ return {
151
+ scope: 'convex-xy-disk-linear',
152
+ minimumProjectedDoubleArea: minimum,
153
+ boundary: new Uint32Array(boundary)
154
+ };
155
+ }
156
+
157
+ function quadraticMinimum(value: (t: number) => number): number {
158
+ const f = value(0),
159
+ g = value(1),
160
+ h = value(0.5),
161
+ a = 2 * (f + g - 2 * h),
162
+ b = g - f - a;
163
+ if (![f, g, h, a, b].every(Number.isFinite))
164
+ throw new RangeError('Nonfinite surface orientation polynomial');
165
+ const t = a > 0 ? -b / (2 * a) : -1;
166
+ const result = Math.min(f, g, t > 0 && t < 1 ? value(t) : Infinity);
167
+ if (!Number.isFinite(result)) throw new RangeError('Nonfinite surface orientation');
168
+ return result;
169
+ }