@expofp/geometry 0.0.0-experimental.cf063fc

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.
@@ -0,0 +1,206 @@
1
+ import { Box } from './box.js';
2
+ import { ELEVATION_TOLERANCE, Point } from './point.js';
3
+ /**
4
+ * A 3D triangle mesh: vertices carry an optional z coordinate, plus triangle index triplets.
5
+ * Immutable value object: readonly getters; transforms return a new instance unless a `target`
6
+ * is passed. For a planar triangulated polygon with area/containment use `Polygon` instead.
7
+ */
8
+ export class Mesh {
9
+ /** Marker so callers can narrow the type at runtime. */
10
+ isMesh = true;
11
+ /** Internal mutable vertex array (3D). */
12
+ _vertices = [];
13
+ /** Internal triangle index array. */
14
+ _indices = [];
15
+ /** Cached axis-aligned bounding box (xy only). */
16
+ _bounds = new Box();
17
+ /** Cached planarity: whether every vertex sits on one plane in z. */
18
+ _planar = true;
19
+ /**
20
+ * Constructs a mesh from a vertex list and triangle index triplets.
21
+ * @param vertices - source vertices; each is cloned into a {@link Point} (default `[]`)
22
+ * @param indices - triangle index triplets referencing positions in `vertices` (default `[]`)
23
+ */
24
+ constructor(vertices = [], indices = []) {
25
+ this.set(vertices, indices);
26
+ }
27
+ /**
28
+ * Readonly array of mesh vertices as {@link Point} instances.
29
+ * @returns the vertex array
30
+ */
31
+ get vertices() {
32
+ return this._vertices;
33
+ }
34
+ /**
35
+ * Readonly array of triangle index triplets.
36
+ * @returns the index array
37
+ */
38
+ get indices() {
39
+ return this._indices;
40
+ }
41
+ /**
42
+ * Cached axis-aligned bounding {@link Box} of this mesh (xy only, z ignored).
43
+ * @returns the bounding box
44
+ */
45
+ get bounds() {
46
+ return this._bounds;
47
+ }
48
+ /**
49
+ * Whether this mesh is flat — every vertex sits on one plane in z, within
50
+ * {@link ELEVATION_TOLERANCE}, so it has no extent worth shading along that axis. An empty mesh is
51
+ * planar. Cached at {@link set}, so reading it is free.
52
+ *
53
+ * This is the predicate that separates a lifted-but-flat mesh from a volume: the former is placed
54
+ * correctly by draw order alone, while the latter needs depth testing and shading to read as solid.
55
+ * The comparison is deliberately approximate — see {@link meshIsPlanar} for why exact equality is
56
+ * the riskier choice.
57
+ * @returns true when the mesh has no meaningful z extent
58
+ */
59
+ get isPlanar() {
60
+ return this._planar;
61
+ }
62
+ /**
63
+ * Mutates this mesh in place, replacing vertices/indices and refreshing the cached bounds.
64
+ * Vertices are copied into fresh {@link Point}s — do not optimize this clone away; transform
65
+ * free functions rely on it to avoid aliasing shared vertices. Use only for hot-path reuse.
66
+ * @param vertices - new vertex list
67
+ * @param indices - new triangle index list
68
+ * @returns `this`
69
+ */
70
+ set(vertices, indices) {
71
+ this._vertices = vertices.map((v) => new Point(v.x, v.y, v.z ?? 0));
72
+ this._indices = indices;
73
+ this._planar = meshIsPlanar(this._vertices);
74
+ this._bounds = meshBounds(this);
75
+ return this;
76
+ }
77
+ /**
78
+ * Merges two or more meshes into a single {@link Mesh}, offsetting each mesh's triangle indices
79
+ * by the cumulative vertex count so they remain valid. Forwards to {@link meshMerge}.
80
+ * @param meshes - meshes to merge
81
+ * @returns a new merged mesh
82
+ */
83
+ static merge(...meshes) {
84
+ return meshMerge(meshes);
85
+ }
86
+ /**
87
+ * Returns a new mesh translated by `offset`. Forwards to {@link meshTranslate}.
88
+ * @param offset - translation vector
89
+ * @param target - optional mesh to write into instead of allocating a new one
90
+ * @returns translated mesh
91
+ */
92
+ translate(offset, target) {
93
+ return meshTranslate(this, offset, target ?? new Mesh());
94
+ }
95
+ /**
96
+ * Returns a new mesh scaled by `factor` about `origin`. Forwards to {@link meshScale}.
97
+ * @param factor - uniform scale or per-axis `{ x, y }` scale
98
+ * @param origin - the fixed point of the scaling; defaults to the bounding-box center
99
+ * @param target - optional mesh to write into instead of allocating a new one
100
+ * @returns scaled mesh
101
+ */
102
+ scale(factor, origin = this._bounds.center, target) {
103
+ return meshScale(this, factor, origin, target ?? new Mesh());
104
+ }
105
+ /**
106
+ * Returns a new mesh rotated by `angle` radians about `origin`. Forwards to {@link meshRotate}.
107
+ * @param angle - rotation angle in radians (positive = clockwise in y-down space)
108
+ * @param origin - the pivot of the rotation; defaults to the bounding-box center
109
+ * @param target - optional mesh to write into instead of allocating a new one
110
+ * @returns rotated mesh
111
+ */
112
+ rotate(angle, origin = this._bounds.center, target) {
113
+ return meshRotate(this, angle, origin, target ?? new Mesh());
114
+ }
115
+ }
116
+ /**
117
+ * Computes the axis-aligned bounding {@link Box} of a mesh by sweeping all vertex xy coordinates.
118
+ * The z component is ignored — bounds are always in the xy plane.
119
+ * @param m - mesh or mesh-like object
120
+ * @returns the bounding box
121
+ */
122
+ export function meshBounds(m) {
123
+ if (m.vertices.length === 0)
124
+ return new Box();
125
+ let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
126
+ for (const v of m.vertices) {
127
+ minX = Math.min(minX, v.x);
128
+ minY = Math.min(minY, v.y);
129
+ maxX = Math.max(maxX, v.x);
130
+ maxY = Math.max(maxY, v.y);
131
+ }
132
+ return Box.fromMinMax({ x: minX, y: minY }, { x: maxX, y: maxY });
133
+ }
134
+ /**
135
+ * Whether every vertex sits on one plane in z, within {@link ELEVATION_TOLERANCE}.
136
+ *
137
+ * Approximate, not exact, and the asymmetry is why. Calling a flat mesh non-planar is the expensive
138
+ * mistake: it would be shaded and depth-tested as a volume, and a flat face whose computed normal
139
+ * points away from the camera renders black. Calling a mesh with sub-tolerance z extent planar costs
140
+ * nothing, because there is nothing there to shade. Exporters and float round-trips produce exactly
141
+ * that kind of noise — a `1e-17` where the author meant zero — and strict equality would take the
142
+ * expensive branch on it.
143
+ *
144
+ * Every vertex is compared against the *first* one rather than against its neighbor, so a mesh that
145
+ * ramps gently is correctly a volume even though no two adjacent vertices differ by much.
146
+ *
147
+ * Vertices have already been normalized to carry a z by {@link Mesh.set}, so no defaulting is needed.
148
+ * @param vertices - the mesh's vertices
149
+ * @returns true when the vertices have no meaningful z extent
150
+ */
151
+ function meshIsPlanar(vertices) {
152
+ if (vertices.length === 0)
153
+ return true;
154
+ const z = vertices[0].z;
155
+ for (let i = 1; i < vertices.length; i++) {
156
+ if (Math.abs(vertices[i].z - z) > ELEVATION_TOLERANCE)
157
+ return false;
158
+ }
159
+ return true;
160
+ }
161
+ export function meshMerge(meshes, target) {
162
+ const vertices = [];
163
+ const indices = [];
164
+ let offset = 0;
165
+ for (const m of meshes) {
166
+ for (const v of m.vertices)
167
+ vertices.push(v);
168
+ for (const [a, b, c] of m.indices)
169
+ indices.push([a + offset, b + offset, c + offset]);
170
+ offset += m.vertices.length;
171
+ }
172
+ return (target ?? new Mesh()).set(vertices, indices);
173
+ }
174
+ export function meshTranslate(m, offset, target) {
175
+ const dz = offset.z ?? 0;
176
+ const vertices = m.vertices.map((v) => ({
177
+ x: v.x + offset.x,
178
+ y: v.y + offset.y,
179
+ z: (v.z ?? 0) + dz,
180
+ }));
181
+ return (target ?? new Mesh()).set(vertices, m.indices);
182
+ }
183
+ export function meshScale(m, factor, origin = meshBounds(m).center, target) {
184
+ const fx = typeof factor === 'number' ? factor : factor.x;
185
+ const fy = typeof factor === 'number' ? factor : factor.y;
186
+ const vertices = m.vertices.map((v) => ({
187
+ x: origin.x + (v.x - origin.x) * fx,
188
+ y: origin.y + (v.y - origin.y) * fy,
189
+ z: v.z ?? 0,
190
+ }));
191
+ return (target ?? new Mesh()).set(vertices, m.indices);
192
+ }
193
+ export function meshRotate(m, angle, origin = meshBounds(m).center, target) {
194
+ const cos = Math.cos(angle);
195
+ const sin = Math.sin(angle);
196
+ const vertices = m.vertices.map((v) => {
197
+ const dx = v.x - origin.x;
198
+ const dy = v.y - origin.y;
199
+ return {
200
+ x: origin.x + dx * cos - dy * sin,
201
+ y: origin.y + dx * sin + dy * cos,
202
+ z: v.z ?? 0,
203
+ };
204
+ });
205
+ return (target ?? new Mesh()).set(vertices, m.indices);
206
+ }
@@ -0,0 +1,218 @@
1
+ /**
2
+ * How far apart two `z` values may be and still count as the same plane, in plan units.
3
+ *
4
+ * Absolute rather than relative, because the question is about the plan's own scale: a thousandth of
5
+ * a unit is far below anything drawable, and far above the noise an exporter or a float round-trip
6
+ * introduces. Deliberate thinness is *not* noise — a slab authored half a unit thick is a volume and
7
+ * is treated as one.
8
+ *
9
+ * Shared so the package cannot answer "same plane?" two different ways: it gates elevation in
10
+ * {@link lineIntersection} and planarity in {@link Mesh.isPlanar}.
11
+ */
12
+ export declare const ELEVATION_TOLERANCE = 0.1;
13
+ /** A 2D point/vector `{ x, y }`. */
14
+ export interface Point2Like {
15
+ /** Horizontal coordinate. */
16
+ readonly x: number;
17
+ /** Vertical coordinate. */
18
+ readonly y: number;
19
+ }
20
+ /** A 3D point/vector `{ x, y, z }`. */
21
+ export interface Point3Like {
22
+ /** Horizontal coordinate. */
23
+ readonly x: number;
24
+ /** Vertical coordinate. */
25
+ readonly y: number;
26
+ /** Depth coordinate. */
27
+ readonly z: number;
28
+ }
29
+ /** Any structural point — `z` optional. */
30
+ export interface PointLike {
31
+ /** Horizontal coordinate. */
32
+ readonly x: number;
33
+ /** Vertical coordinate. */
34
+ readonly y: number;
35
+ /** Depth coordinate (optional). */
36
+ readonly z?: number;
37
+ }
38
+ /**
39
+ * A readonly 2D vector that also exposes `width`/`height` aliases of `x`/`y` — the return type of the
40
+ * `size` getter on {@link Box} and {@link Rect}. Backed by a {@link Point} (which provides the
41
+ * aliases), so `size.x`/`size.width` and `size.y`/`size.height` both read the same value.
42
+ */
43
+ export type SizeLike = Readonly<Point2Like> & {
44
+ readonly width: number;
45
+ readonly height: number;
46
+ };
47
+ /**
48
+ * Mutable point/vector — the low-level building block other primitives and the point free functions
49
+ * write into. `width`/`height` alias `x`/`y` so a point used as a size reads naturally.
50
+ */
51
+ export declare class Point {
52
+ /** Marker so callers can narrow the type at runtime. */
53
+ readonly isPoint = true;
54
+ /** Horizontal coordinate. */
55
+ x: number;
56
+ /** Vertical coordinate. */
57
+ y: number;
58
+ /** Depth coordinate. */
59
+ z: number;
60
+ /**
61
+ * @param x - horizontal coordinate (default 0)
62
+ * @param y - vertical coordinate (default 0)
63
+ * @param z - depth coordinate (default 0)
64
+ */
65
+ constructor(x?: number, y?: number, z?: number);
66
+ /**
67
+ * Alias of {@link Point.x}.
68
+ * @returns the x coordinate
69
+ */
70
+ get width(): number;
71
+ /**
72
+ * Alias of {@link Point.y}.
73
+ * @returns the y coordinate
74
+ */
75
+ get height(): number;
76
+ /**
77
+ * Sets coordinates in place.
78
+ * @param x - horizontal coordinate
79
+ * @param y - vertical coordinate
80
+ * @param z - depth coordinate (defaults to the current z)
81
+ * @returns this
82
+ */
83
+ set(x: number, y: number, z?: number): this;
84
+ /**
85
+ * Copies from another point in place.
86
+ * @param p - source point to copy coordinates from
87
+ * @returns this
88
+ */
89
+ copy(p: PointLike): this;
90
+ /**
91
+ * Returns an independent copy, or writes into `target` if provided. See {@link pointLerp} for the
92
+ * underlying free function.
93
+ * @param target - optional point to write into; defaults to a new {@link Point}
94
+ * @returns the copy
95
+ */
96
+ clone(target?: Point): Point;
97
+ /**
98
+ * True when `p` has the same coordinates.
99
+ * @param p - point to compare against
100
+ * @returns true when all coordinates are equal
101
+ */
102
+ equals(p: PointLike): boolean;
103
+ /**
104
+ * Distance to `p`. See {@link pointDistance} for the underlying free function.
105
+ * @param p - target point
106
+ * @returns the distance
107
+ */
108
+ distanceTo(p: PointLike): number;
109
+ /**
110
+ * Interpolate toward `p` by `t`. See {@link pointLerp} for the underlying free function.
111
+ * @param p - target point
112
+ * @param t - interpolation factor (0 = this, 1 = p)
113
+ * @param target - optional point to write into; defaults to a new {@link Point}
114
+ * @returns the resulting point
115
+ */
116
+ lerp(p: PointLike, t: number, target?: Point): Point;
117
+ /**
118
+ * Rotate by `angle` radians around `origin`. See {@link pointRotate} for the underlying free
119
+ * function.
120
+ * @param angle - radians to rotate (positive = clockwise, y-down)
121
+ * @param origin - rotation pivot point
122
+ * @param target - optional point to write into; defaults to a new {@link Point}
123
+ * @returns the resulting point
124
+ */
125
+ rotate(angle: number, origin: Point2Like, target?: Point): Point;
126
+ /**
127
+ * Shift by `length` along `angle` radians. See {@link pointShift} for the underlying free function.
128
+ * @param length - distance to shift
129
+ * @param angle - direction in radians
130
+ * @param target - optional point to write into; defaults to a new {@link Point}
131
+ * @returns the resulting point
132
+ */
133
+ shift(length: number, angle: number, target?: Point): Point;
134
+ /**
135
+ * Angle (radians) at this point between rays to `a` and `b`. See {@link pointAngleBetween} for
136
+ * the underlying free function.
137
+ * @param a - first ray endpoint
138
+ * @param b - second ray endpoint
139
+ * @returns the signed angle in radians (positive = clockwise, y-down)
140
+ */
141
+ angleBetween(a: Point2Like, b: Point2Like): number;
142
+ /**
143
+ * Add a scalar (broadcast to x/y) or another point. See {@link pointAdd} for the underlying free
144
+ * function.
145
+ * @param b - scalar or point to add
146
+ * @param target - optional point to write into; defaults to a new {@link Point}
147
+ * @returns the resulting point
148
+ */
149
+ add(b: number | PointLike, target?: Point): Point;
150
+ /**
151
+ * Multiply by a scalar (x/y) or componentwise by another point. See {@link pointMultiply} for
152
+ * the underlying free function.
153
+ * @param b - scalar or point factor
154
+ * @param target - optional point to write into; defaults to a new {@link Point}
155
+ * @returns the resulting point
156
+ */
157
+ multiply(b: number | PointLike, target?: Point): Point;
158
+ }
159
+ /**
160
+ * Euclidean distance between two points (XY plane).
161
+ * @param a first point
162
+ * @param b second point
163
+ * @returns the distance
164
+ */
165
+ export declare function pointDistance(a: PointLike, b: PointLike): number;
166
+ /**
167
+ * Linear interpolation from `a` to `b` by `t`.
168
+ * @param a start point
169
+ * @param b end point
170
+ * @param t factor (0 = a, 1 = b)
171
+ * @param target optional point to write into; defaults to a new {@link Point}
172
+ * @returns the interpolated point
173
+ */
174
+ export declare function pointLerp(a: PointLike, b: PointLike, t: number, target?: Point): Point;
175
+ /**
176
+ * Adds a scalar (broadcast to x/y) or another point (componentwise) to `a`.
177
+ * @param a base point
178
+ * @param b scalar or point to add
179
+ * @param target optional point to write into; defaults to a new {@link Point}
180
+ * @returns the sum
181
+ */
182
+ export declare function pointAdd(a: PointLike, b: number | PointLike, target?: Point): Point;
183
+ /**
184
+ * Multiplies `a` by a scalar (x/y) or by another point (componentwise).
185
+ * @param a base point
186
+ * @param b scalar or point factor
187
+ * @param target optional point to write into; defaults to a new {@link Point}
188
+ * @returns the product
189
+ */
190
+ export declare function pointMultiply(a: PointLike, b: number | PointLike, target?: Point): Point;
191
+ /**
192
+ * Rotates `point` by `angle` radians around `origin` in the XY plane.
193
+ * @param point point to rotate
194
+ * @param angle radians (positive = clockwise, y-down)
195
+ * @param origin rotation pivot point
196
+ * @param target optional point to write into; defaults to a new {@link Point}
197
+ * @returns the rotated point, preserving the input depth (`z`)
198
+ */
199
+ export declare function pointRotate(point: PointLike, angle: number, origin: Point2Like, target?: Point): Point;
200
+ /**
201
+ * Shifts `point` by `length` along `angle` radians.
202
+ * @param point origin
203
+ * @param length distance
204
+ * @param angle direction in radians
205
+ * @param target optional point to write into; defaults to a new {@link Point}
206
+ * @returns the shifted point
207
+ */
208
+ export declare function pointShift(point: PointLike, length: number, angle: number, target?: Point): Point;
209
+ /**
210
+ * Angle (radians) at `center` between the rays to `a` and `b`. The result is signed — positive means
211
+ * clockwise (screen y-down convention), matching the winding used by {@link pointRotate}.
212
+ * @param center vertex
213
+ * @param a first ray endpoint
214
+ * @param b second ray endpoint
215
+ * @returns signed angle in radians (positive = clockwise, y-down)
216
+ */
217
+ export declare function pointAngleBetween(center: Point2Like, a: Point2Like, b: Point2Like): number;
218
+ //# sourceMappingURL=point.d.ts.map
@@ -0,0 +1,249 @@
1
+ import { fromPolar } from './angles.js';
2
+ /**
3
+ * How far apart two `z` values may be and still count as the same plane, in plan units.
4
+ *
5
+ * Absolute rather than relative, because the question is about the plan's own scale: a thousandth of
6
+ * a unit is far below anything drawable, and far above the noise an exporter or a float round-trip
7
+ * introduces. Deliberate thinness is *not* noise — a slab authored half a unit thick is a volume and
8
+ * is treated as one.
9
+ *
10
+ * Shared so the package cannot answer "same plane?" two different ways: it gates elevation in
11
+ * {@link lineIntersection} and planarity in {@link Mesh.isPlanar}.
12
+ */
13
+ export const ELEVATION_TOLERANCE = 1e-1;
14
+ /**
15
+ * Mutable point/vector — the low-level building block other primitives and the point free functions
16
+ * write into. `width`/`height` alias `x`/`y` so a point used as a size reads naturally.
17
+ */
18
+ export class Point {
19
+ /** Marker so callers can narrow the type at runtime. */
20
+ isPoint = true;
21
+ /** Horizontal coordinate. */
22
+ x;
23
+ /** Vertical coordinate. */
24
+ y;
25
+ /** Depth coordinate. */
26
+ z;
27
+ /**
28
+ * @param x - horizontal coordinate (default 0)
29
+ * @param y - vertical coordinate (default 0)
30
+ * @param z - depth coordinate (default 0)
31
+ */
32
+ constructor(x = 0, y = 0, z = 0) {
33
+ this.x = x;
34
+ this.y = y;
35
+ this.z = z;
36
+ }
37
+ /**
38
+ * Alias of {@link Point.x}.
39
+ * @returns the x coordinate
40
+ */
41
+ get width() {
42
+ return this.x;
43
+ }
44
+ /**
45
+ * Alias of {@link Point.y}.
46
+ * @returns the y coordinate
47
+ */
48
+ get height() {
49
+ return this.y;
50
+ }
51
+ /**
52
+ * Sets coordinates in place.
53
+ * @param x - horizontal coordinate
54
+ * @param y - vertical coordinate
55
+ * @param z - depth coordinate (defaults to the current z)
56
+ * @returns this
57
+ */
58
+ set(x, y, z = this.z) {
59
+ this.x = x;
60
+ this.y = y;
61
+ this.z = z;
62
+ return this;
63
+ }
64
+ /**
65
+ * Copies from another point in place.
66
+ * @param p - source point to copy coordinates from
67
+ * @returns this
68
+ */
69
+ copy(p) {
70
+ return this.set(p.x, p.y, p.z ?? 0);
71
+ }
72
+ /**
73
+ * Returns an independent copy, or writes into `target` if provided. See {@link pointLerp} for the
74
+ * underlying free function.
75
+ * @param target - optional point to write into; defaults to a new {@link Point}
76
+ * @returns the copy
77
+ */
78
+ clone(target) {
79
+ return (target ?? new Point()).set(this.x, this.y, this.z);
80
+ }
81
+ /**
82
+ * True when `p` has the same coordinates.
83
+ * @param p - point to compare against
84
+ * @returns true when all coordinates are equal
85
+ */
86
+ equals(p) {
87
+ return this.x === p.x && this.y === p.y && this.z === (p.z ?? 0);
88
+ }
89
+ /**
90
+ * Distance to `p`. See {@link pointDistance} for the underlying free function.
91
+ * @param p - target point
92
+ * @returns the distance
93
+ */
94
+ distanceTo(p) {
95
+ return pointDistance(this, p);
96
+ }
97
+ /**
98
+ * Interpolate toward `p` by `t`. See {@link pointLerp} for the underlying free function.
99
+ * @param p - target point
100
+ * @param t - interpolation factor (0 = this, 1 = p)
101
+ * @param target - optional point to write into; defaults to a new {@link Point}
102
+ * @returns the resulting point
103
+ */
104
+ lerp(p, t, target) {
105
+ return pointLerp(this, p, t, target);
106
+ }
107
+ /**
108
+ * Rotate by `angle` radians around `origin`. See {@link pointRotate} for the underlying free
109
+ * function.
110
+ * @param angle - radians to rotate (positive = clockwise, y-down)
111
+ * @param origin - rotation pivot point
112
+ * @param target - optional point to write into; defaults to a new {@link Point}
113
+ * @returns the resulting point
114
+ */
115
+ rotate(angle, origin, target) {
116
+ return pointRotate(this, angle, origin, target);
117
+ }
118
+ /**
119
+ * Shift by `length` along `angle` radians. See {@link pointShift} for the underlying free function.
120
+ * @param length - distance to shift
121
+ * @param angle - direction in radians
122
+ * @param target - optional point to write into; defaults to a new {@link Point}
123
+ * @returns the resulting point
124
+ */
125
+ shift(length, angle, target) {
126
+ return pointShift(this, length, angle, target);
127
+ }
128
+ /**
129
+ * Angle (radians) at this point between rays to `a` and `b`. See {@link pointAngleBetween} for
130
+ * the underlying free function.
131
+ * @param a - first ray endpoint
132
+ * @param b - second ray endpoint
133
+ * @returns the signed angle in radians (positive = clockwise, y-down)
134
+ */
135
+ angleBetween(a, b) {
136
+ return pointAngleBetween(this, a, b);
137
+ }
138
+ /**
139
+ * Add a scalar (broadcast to x/y) or another point. See {@link pointAdd} for the underlying free
140
+ * function.
141
+ * @param b - scalar or point to add
142
+ * @param target - optional point to write into; defaults to a new {@link Point}
143
+ * @returns the resulting point
144
+ */
145
+ add(b, target) {
146
+ return pointAdd(this, b, target);
147
+ }
148
+ /**
149
+ * Multiply by a scalar (x/y) or componentwise by another point. See {@link pointMultiply} for
150
+ * the underlying free function.
151
+ * @param b - scalar or point factor
152
+ * @param target - optional point to write into; defaults to a new {@link Point}
153
+ * @returns the resulting point
154
+ */
155
+ multiply(b, target) {
156
+ return pointMultiply(this, b, target);
157
+ }
158
+ }
159
+ /**
160
+ * Euclidean distance between two points (XY plane).
161
+ * @param a first point
162
+ * @param b second point
163
+ * @returns the distance
164
+ */
165
+ export function pointDistance(a, b) {
166
+ const dx = a.x - b.x;
167
+ const dy = a.y - b.y;
168
+ return Math.sqrt(dx * dx + dy * dy);
169
+ }
170
+ /**
171
+ * Linear interpolation from `a` to `b` by `t`.
172
+ * @param a start point
173
+ * @param b end point
174
+ * @param t factor (0 = a, 1 = b)
175
+ * @param target optional point to write into; defaults to a new {@link Point}
176
+ * @returns the interpolated point
177
+ */
178
+ export function pointLerp(a, b, t, target) {
179
+ const az = a.z ?? 0;
180
+ const bz = b.z ?? 0;
181
+ return (target ?? new Point()).set(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, az + (bz - az) * t);
182
+ }
183
+ /**
184
+ * Adds a scalar (broadcast to x/y) or another point (componentwise) to `a`.
185
+ * @param a base point
186
+ * @param b scalar or point to add
187
+ * @param target optional point to write into; defaults to a new {@link Point}
188
+ * @returns the sum
189
+ */
190
+ export function pointAdd(a, b, target) {
191
+ const isNum = typeof b === 'number';
192
+ const bx = isNum ? b : b.x;
193
+ const by = isNum ? b : b.y;
194
+ const bz = isNum ? 0 : (b.z ?? 0);
195
+ return (target ?? new Point()).set(a.x + bx, a.y + by, (a.z ?? 0) + bz);
196
+ }
197
+ /**
198
+ * Multiplies `a` by a scalar (x/y) or by another point (componentwise).
199
+ * @param a base point
200
+ * @param b scalar or point factor
201
+ * @param target optional point to write into; defaults to a new {@link Point}
202
+ * @returns the product
203
+ */
204
+ export function pointMultiply(a, b, target) {
205
+ const isNum = typeof b === 'number';
206
+ const bx = isNum ? b : b.x;
207
+ const by = isNum ? b : b.y;
208
+ const bz = isNum ? 1 : (b.z ?? 1);
209
+ return (target ?? new Point()).set(a.x * bx, a.y * by, (a.z ?? 0) * bz);
210
+ }
211
+ /**
212
+ * Rotates `point` by `angle` radians around `origin` in the XY plane.
213
+ * @param point point to rotate
214
+ * @param angle radians (positive = clockwise, y-down)
215
+ * @param origin rotation pivot point
216
+ * @param target optional point to write into; defaults to a new {@link Point}
217
+ * @returns the rotated point, preserving the input depth (`z`)
218
+ */
219
+ export function pointRotate(point, angle, origin, target) {
220
+ const cos = Math.cos(angle);
221
+ const sin = Math.sin(angle);
222
+ const dx = point.x - origin.x;
223
+ const dy = point.y - origin.y;
224
+ return (target ?? new Point()).set(origin.x + dx * cos - dy * sin, origin.y + dx * sin + dy * cos, point.z ?? 0);
225
+ }
226
+ /**
227
+ * Shifts `point` by `length` along `angle` radians.
228
+ * @param point origin
229
+ * @param length distance
230
+ * @param angle direction in radians
231
+ * @param target optional point to write into; defaults to a new {@link Point}
232
+ * @returns the shifted point
233
+ */
234
+ export function pointShift(point, length, angle, target) {
235
+ return pointAdd(point, fromPolar(length, angle), target);
236
+ }
237
+ /**
238
+ * Angle (radians) at `center` between the rays to `a` and `b`. The result is signed — positive means
239
+ * clockwise (screen y-down convention), matching the winding used by {@link pointRotate}.
240
+ * @param center vertex
241
+ * @param a first ray endpoint
242
+ * @param b second ray endpoint
243
+ * @returns signed angle in radians (positive = clockwise, y-down)
244
+ */
245
+ export function pointAngleBetween(center, a, b) {
246
+ const aa = Math.atan2(a.y - center.y, a.x - center.x);
247
+ const bb = Math.atan2(b.y - center.y, b.x - center.x);
248
+ return bb - aa;
249
+ }