@expofp/geometry 3.26.0 → 3.27.1

package/dist/lib/intersections.d.ts

@@ -8,7 +8,7 @@ import { type RectLike } from './rect.js';
  * have a defined elevation and they differ by more than `elevationTolerance`.
  * @param a - first line segment, defined by `p0` and `p1`
  * @param b - second line segment, defined by `p0` and `p1`
- * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
  * @returns `{ point, onLine1, onLine2 }`, or `null` when the lines are parallel or elevation-incompatible
  */
 export declare function lineIntersection(a: LineLike, b: LineLike, elevationTolerance?: number): {
@@ -23,7 +23,7 @@ export declare function lineIntersection(a: LineLike, b: LineLike, elevationTole
  * by more than `elevationTolerance`, returns an empty array.
  * @param line - the segment, defined by `p0` and `p1`
  * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
- * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
  * @returns the intersection points (0–2 for a convex rect)
  */
 export declare function intersectLineRect(line: LineLike, rect: RectLike, elevationTolerance?: number): Point[];

package/dist/lib/intersections.js

@@ -1,7 +1,5 @@
-import { pointLerp } from './point.js';
+import { ELEVATION_TOLERANCE, pointLerp } from './point.js';
 import { rectCorners } from './rect.js';
-/** Default tolerance for elevation comparison. */
-const DEFAULT_ELEVATION_TOLERANCE = 1e-3;
 /**
  * Computes the crossing of lines `a` and `b` using the parametric form. Returns the crossing
  * point plus flags indicating whether the crossing lies within each segment's `[0, 1]` parameter
@@ -9,10 +7,10 @@ const DEFAULT_ELEVATION_TOLERANCE = 1e-3;
  * have a defined elevation and they differ by more than `elevationTolerance`.
  * @param a - first line segment, defined by `p0` and `p1`
  * @param b - second line segment, defined by `p0` and `p1`
- * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
  * @returns `{ point, onLine1, onLine2 }`, or `null` when the lines are parallel or elevation-incompatible
  */
-export function lineIntersection(a, b, elevationTolerance = DEFAULT_ELEVATION_TOLERANCE) {
+export function lineIntersection(a, b, elevationTolerance = ELEVATION_TOLERANCE) {
     if (a.elevation != null &&
         b.elevation != null &&
         Math.abs(a.elevation - b.elevation) > elevationTolerance) {
@@ -35,7 +33,7 @@ export function lineIntersection(a, b, elevationTolerance = DEFAULT_ELEVATION_TO
  * flags). See `intersectLineRect` for the higher-level helper.
  * @param a - first segment, defined by `p0` and `p1`
  * @param b - second segment, defined by `p0` and `p1`
- * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
  * @returns the intersection {@link Point}, or `null` if the segments are parallel or non-crossing
  */
 function segmentIntersection(a, b, elevationTolerance) {
@@ -49,10 +47,10 @@ function segmentIntersection(a, b, elevationTolerance) {
  * by more than `elevationTolerance`, returns an empty array.
  * @param line - the segment, defined by `p0` and `p1`
  * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
- * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
  * @returns the intersection points (0–2 for a convex rect)
  */
-export function intersectLineRect(line, rect, elevationTolerance = DEFAULT_ELEVATION_TOLERANCE) {
+export function intersectLineRect(line, rect, elevationTolerance = ELEVATION_TOLERANCE) {
     if (line.elevation != null &&
         rect.elevation != null &&
         Math.abs(line.elevation - rect.elevation) > elevationTolerance) {

package/dist/lib/line.d.ts

@@ -69,7 +69,7 @@ export declare class Line {
     /**
      * Points where this line crosses `rect`.
      * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
-     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
      * @returns the intersection points
      */
     intersectRect(rect: RectLike, elevationTolerance?: number): Point[];
@@ -87,7 +87,7 @@ export declare class Line {
     /**
      * Intersection with another segment `other` on the infinite lines.
      * @param other - the other segment
-     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
      * @returns the crossing data, or `null` when the lines are parallel or elevations are incompatible
      */
     intersect(other: LineLike, elevationTolerance?: number): {

package/dist/lib/line.js

@@ -81,7 +81,7 @@ export class Line {
     /**
      * Points where this line crosses `rect`.
      * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
-     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
      * @returns the intersection points
      */
     intersectRect(rect, elevationTolerance) {
@@ -99,7 +99,7 @@ export class Line {
     /**
      * Intersection with another segment `other` on the infinite lines.
      * @param other - the other segment
-     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to {@link ELEVATION_TOLERANCE}
      * @returns the crossing data, or `null` when the lines are parallel or elevations are incompatible
      */
     intersect(other, elevationTolerance) {

package/dist/lib/mesh.d.ts

@@ -24,6 +24,8 @@ export declare class Mesh {
     private _indices;
     /** Cached axis-aligned bounding box (xy only). */
     private _bounds;
+    /** Cached planarity: whether every vertex sits on one plane in z. */
+    private _planar;
     /**
      * Constructs a mesh from a vertex list and triangle index triplets.
      * @param vertices - source vertices; each is cloned into a {@link Point} (default `[]`)
@@ -45,6 +47,18 @@ export declare class Mesh {
      * @returns the bounding box
      */
     get bounds(): Box;
+    /**
+     * Whether this mesh is flat — every vertex sits on one plane in z, within
+     * {@link ELEVATION_TOLERANCE}, so it has no extent worth shading along that axis. An empty mesh is
+     * planar. Cached at {@link set}, so reading it is free.
+     *
+     * This is the predicate that separates a lifted-but-flat mesh from a volume: the former is placed
+     * correctly by draw order alone, while the latter needs depth testing and shading to read as solid.
+     * The comparison is deliberately approximate — see {@link meshIsPlanar} for why exact equality is
+     * the riskier choice.
+     * @returns true when the mesh has no meaningful z extent
+     */
+    get isPlanar(): boolean;
     /**
      * Mutates this mesh in place, replacing vertices/indices and refreshing the cached bounds.
      * Vertices are copied into fresh {@link Point}s — do not optimize this clone away; transform

package/dist/lib/mesh.js

@@ -1,5 +1,5 @@
 import { Box } from './box.js';
-import { Point } from './point.js';
+import { ELEVATION_TOLERANCE, Point } from './point.js';
 /**
  * A 3D triangle mesh: vertices carry an optional z coordinate, plus triangle index triplets.
  * Immutable value object: readonly getters; transforms return a new instance unless a `target`
@@ -14,6 +14,8 @@ export class Mesh {
     _indices = [];
     /** Cached axis-aligned bounding box (xy only). */
     _bounds = new Box();
+    /** Cached planarity: whether every vertex sits on one plane in z. */
+    _planar = true;
     /**
      * Constructs a mesh from a vertex list and triangle index triplets.
      * @param vertices - source vertices; each is cloned into a {@link Point} (default `[]`)
@@ -43,6 +45,20 @@ export class Mesh {
     get bounds() {
         return this._bounds;
     }
+    /**
+     * Whether this mesh is flat — every vertex sits on one plane in z, within
+     * {@link ELEVATION_TOLERANCE}, so it has no extent worth shading along that axis. An empty mesh is
+     * planar. Cached at {@link set}, so reading it is free.
+     *
+     * This is the predicate that separates a lifted-but-flat mesh from a volume: the former is placed
+     * correctly by draw order alone, while the latter needs depth testing and shading to read as solid.
+     * The comparison is deliberately approximate — see {@link meshIsPlanar} for why exact equality is
+     * the riskier choice.
+     * @returns true when the mesh has no meaningful z extent
+     */
+    get isPlanar() {
+        return this._planar;
+    }
     /**
      * Mutates this mesh in place, replacing vertices/indices and refreshing the cached bounds.
      * Vertices are copied into fresh {@link Point}s — do not optimize this clone away; transform
@@ -54,6 +70,7 @@ export class Mesh {
     set(vertices, indices) {
         this._vertices = vertices.map((v) => new Point(v.x, v.y, v.z ?? 0));
         this._indices = indices;
+        this._planar = meshIsPlanar(this._vertices);
         this._bounds = meshBounds(this);
         return this;
     }
@@ -114,6 +131,33 @@ export function meshBounds(m) {
     }
     return Box.fromMinMax({ x: minX, y: minY }, { x: maxX, y: maxY });
 }
+/**
+ * Whether every vertex sits on one plane in z, within {@link ELEVATION_TOLERANCE}.
+ *
+ * Approximate, not exact, and the asymmetry is why. Calling a flat mesh non-planar is the expensive
+ * mistake: it would be shaded and depth-tested as a volume, and a flat face whose computed normal
+ * points away from the camera renders black. Calling a mesh with sub-tolerance z extent planar costs
+ * nothing, because there is nothing there to shade. Exporters and float round-trips produce exactly
+ * that kind of noise — a `1e-17` where the author meant zero — and strict equality would take the
+ * expensive branch on it.
+ *
+ * Every vertex is compared against the *first* one rather than against its neighbor, so a mesh that
+ * ramps gently is correctly a volume even though no two adjacent vertices differ by much.
+ *
+ * Vertices have already been normalized to carry a z by {@link Mesh.set}, so no defaulting is needed.
+ * @param vertices - the mesh's vertices
+ * @returns true when the vertices have no meaningful z extent
+ */
+function meshIsPlanar(vertices) {
+    if (vertices.length === 0)
+        return true;
+    const z = vertices[0].z;
+    for (let i = 1; i < vertices.length; i++) {
+        if (Math.abs(vertices[i].z - z) > ELEVATION_TOLERANCE)
+            return false;
+    }
+    return true;
+}
 export function meshMerge(meshes, target) {
     const vertices = [];
     const indices = [];

package/dist/lib/point.d.ts

@@ -1,3 +1,15 @@
+/**
+ * How far apart two `z` values may be and still count as the same plane, in plan units.
+ *
+ * Absolute rather than relative, because the question is about the plan's own scale: a thousandth of
+ * a unit is far below anything drawable, and far above the noise an exporter or a float round-trip
+ * introduces. Deliberate thinness is *not* noise — a slab authored half a unit thick is a volume and
+ * is treated as one.
+ *
+ * Shared so the package cannot answer "same plane?" two different ways: it gates elevation in
+ * {@link lineIntersection} and planarity in {@link Mesh.isPlanar}.
+ */
+export declare const ELEVATION_TOLERANCE = 0.1;
 /** A 2D point/vector `{ x, y }`. */
 export interface Point2Like {
     /** Horizontal coordinate. */

package/dist/lib/point.js

@@ -1,4 +1,16 @@
 import { fromPolar } from './angles.js';
+/**
+ * How far apart two `z` values may be and still count as the same plane, in plan units.
+ *
+ * Absolute rather than relative, because the question is about the plan's own scale: a thousandth of
+ * a unit is far below anything drawable, and far above the noise an exporter or a float round-trip
+ * introduces. Deliberate thinness is *not* noise — a slab authored half a unit thick is a volume and
+ * is treated as one.
+ *
+ * Shared so the package cannot answer "same plane?" two different ways: it gates elevation in
+ * {@link lineIntersection} and planarity in {@link Mesh.isPlanar}.
+ */
+export const ELEVATION_TOLERANCE = 1e-1;
 /**
  * Mutable point/vector — the low-level building block other primitives and the point free functions
  * write into. `width`/`height` alias `x`/`y` so a point used as a size reads naturally.

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@expofp/geometry",
-  "version": "3.26.0",
+  "version": "3.27.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/expofp/efp-app.git",
+    "directory": "packages/geometry"
+  },
   "type": "module",
   "description": "ExpoFP SDK internal: shared geometry primitives",
   "homepage": "https://developer.expofp.com/",