@expofp/geometry 0.0.0-experimental.2632d13
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.
- package/README.md +131 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.js +42 -0
- package/dist/lib/angles.d.ts +36 -0
- package/dist/lib/angles.js +50 -0
- package/dist/lib/box.d.ts +282 -0
- package/dist/lib/box.js +362 -0
- package/dist/lib/geo.d.ts +112 -0
- package/dist/lib/geo.js +204 -0
- package/dist/lib/intersections.d.ts +30 -0
- package/dist/lib/intersections.js +70 -0
- package/dist/lib/line.d.ts +134 -0
- package/dist/lib/line.js +167 -0
- package/dist/lib/mesh.d.ts +180 -0
- package/dist/lib/mesh.js +206 -0
- package/dist/lib/point.d.ts +218 -0
- package/dist/lib/point.js +249 -0
- package/dist/lib/polygon.d.ts +186 -0
- package/dist/lib/polygon.js +296 -0
- package/dist/lib/rect.d.ts +201 -0
- package/dist/lib/rect.js +278 -0
- package/package.json +36 -0
package/dist/lib/mesh.js
ADDED
|
@@ -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
|
+
}
|