@itwin/core-geometry 4.1.0-dev.7 → 4.1.0-dev.71

package/lib/esm/clipping/ClipPrimitive.js

@@ -19,6 +19,8 @@ import { UnionOfConvexClipPlaneSets } from "./UnionOfConvexClipPlaneSets";
 import { AlternatingCCTreeNode } from "./AlternatingConvexClipTree";
 import { Point3dArray } from "../geometry3d/PointHelpers";
 import { PolylineOps } from "../geometry3d/PolylineOps";
+// cspell:word zlow
+// cspell:word zhigh
 /**
  * Bit mask type for referencing subsets of 6 planes of range box.
  * @public
@@ -46,17 +48,18 @@ export var ClipMaskXYZRangePlanes;
 })(ClipMaskXYZRangePlanes || (ClipMaskXYZRangePlanes = {}));
 /**
  * * ClipPrimitive is a base class for clipping implementations that use
- *   * A UnionOfConvexClipPlaneSets designated "clipPlanes"
- *   * an "invisible" flag
- * * When constructed directly, objects of type ClipPrimitive (directly, not through a derived class) will have just planes
+ *   * A UnionOfConvexClipPlaneSets designated "clipPlanes".
+ *   * An "invisible" flag.
+ * * When constructed directly, objects of type ClipPrimitive (directly, not through a derived class) will have just planes.
  * * Derived classes (e.g. ClipShape) carry additional data such as a swept shape.
  * * ClipPrimitive can be constructed with no planes.
  *     * Derived class is responsible for filling the plane sets.
- *     * At discretion of derived classes, plane construction can be done at construction time or "on demand when" queries call `ensurePlaneSets ()`
+ *     * At discretion of derived classes, plane construction can be done at construction time or "on demand when" queries
+ * call `ensurePlaneSets ()`
  * * ClipPrimitive can be constructed directly with planes (and no derived class).
  * * That the prevailing use is via a ClipShape derived class.
  *    * The ClipShape has an "isMask" property
- *       * isMask === false means the plane sets should cover the inside of its polygon
+ *       * isMask === false means the plane sets should cover the inside of its polygon.
  *       * isMask === true means the plane sets should cover the outside of its polygon.
  *  * Note that the ClipShape's `isMask` property and the ClipPrimitive's `isInvisible` property are distinct controls.
  *     * In normal usage, callers get "outside" clip behavior using ONLY the ClipShape isMask property.
@@ -65,13 +68,19 @@ export var ClipMaskXYZRangePlanes;
  * @public
  */
 export class ClipPrimitive {
-    /** Get a reference to the `UnionOfConvexClipPlaneSets`.
-     *  * It triggers construction of the sets by `this.ensurePlaneSets()`.
-     *  * Derived class typically caches the set on the first such call.
+    /**
+     * Get a reference to the `UnionOfConvexClipPlaneSets`.
+     * * It triggers construction of the sets by `this.ensurePlaneSets()`.
+     * * Derived class typically caches the set on the first such call.
      */
-    fetchClipPlanesRef() { this.ensurePlaneSets(); return this._clipPlanes; }
+    fetchClipPlanesRef() {
+        this.ensurePlaneSets();
+        return this._clipPlanes;
+    }
     /** Ask if this primitive is a hole. */
-    get invisible() { return this._invisible; }
+    get invisible() {
+        return this._invisible;
+    }
     constructor(planeSet, isInvisible = false) {
         this._clipPlanes = planeSet;
         this._invisible = isInvisible;
@@ -100,26 +109,30 @@ export class ClipPrimitive {
     }
     /**
      * Returns true if the planes are present.
-     * * This can be false (for instance) if a ClipShape is holding a polygon but has not yet been asked to construct the planes.
+     * * This can be false (for instance) if a ClipShape is holding a polygon but has not yet been asked to construct
+     * the planes.
      */
     arePlanesDefined() {
         return this._clipPlanes !== undefined;
     }
-    /** Return a deep clone  */
+    /** Return a deep clone. */
     clone() {
         const newPlanes = this._clipPlanes ? this._clipPlanes.clone() : undefined;
         const result = new ClipPrimitive(newPlanes, this._invisible);
         return result;
     }
     /**
-     * * trigger (if needed)  computation of plane sets (if applicable) in the derived class.
+     * Trigger (if needed) computation of plane sets (if applicable) in the derived class.
      * * Base class is no op.
      * * In derived class, on first call create planes sets from defining data (e.g. swept shape).
      * * In derived class, if planes are present leave them alone.
      */
     ensurePlaneSets() { }
-    /** Return true if the point lies inside/on this polygon (or not inside/on if this polygon is a mask). Otherwise, return false.
-     * * Note that a derived class may choose to (a) implement its own test using its defining data, or (b) accept this implementation using planes that it inserted in the base class.
+    /**
+     * Return true if the point lies inside/on this polygon (or not inside/on if this polygon is a mask). Otherwise,
+     * return false.
+     * * Note that a derived class may choose to (a) implement its own test using its defining data, or (b) accept
+     * this implementation using planes that it inserted in the base class.
      */
     pointInside(point, onTolerance = Geometry.smallMetricDistanceSquared) {
         this.ensurePlaneSets();
@@ -128,7 +141,8 @@ export class ClipPrimitive {
             inside = this._clipPlanes.isPointOnOrInside(point, onTolerance);
         return inside;
     }
-    /** Method from [[Clipper]] interface.
+    /**
+     * Method from [[Clipper]] interface.
      * * Implement as dispatch to clipPlaneSets as supplied by derived class.
      */
     isPointOnOrInside(point, onTolerance = Geometry.smallMetricDistanceSquared) {
@@ -138,7 +152,8 @@ export class ClipPrimitive {
             inside = this._clipPlanes.isPointOnOrInside(point, onTolerance);
         return inside;
     }
-    /** Method from [[Clipper]] interface.
+    /**
+     * Method from [[Clipper]] interface.
      * * Implement as dispatch to clipPlaneSets as supplied by derived class.
      */
     announceClippedSegmentIntervals(f0, f1, pointA, pointB, announce) {
@@ -148,7 +163,8 @@ export class ClipPrimitive {
             hasInsideParts = this._clipPlanes.announceClippedSegmentIntervals(f0, f1, pointA, pointB, announce);
         return hasInsideParts;
     }
-    /** Method from [[Clipper]] interface.
+    /**
+     * Method from [[Clipper]] interface.
      * * Implement as dispatch to clipPlaneSets as supplied by derived class.
      */
     announceClippedArcIntervals(arc, announce) {
@@ -162,11 +178,12 @@ export class ClipPrimitive {
      * Multiply all ClipPlanes DPoint4d by matrix.
      * @param matrix matrix to apply.
      * @param invert if true, use in verse of the matrix.
-     * @param transpose if true, use the transpose of the matrix (or inverse, per invert parameter)
-     * * Note that if matrixA is applied to all of space, the matrix to send to this method to get a corresponding effect on the plane is the inverse transpose of matrixA
+     * @param transpose if true, use the transpose of the matrix (or inverse, per invert parameter).
+     * @param matrix matrix to apply.
+     * * Note that if matrixA is applied to all of space, the matrix to send to this method to get a corresponding
+     * effect on the plane is the inverse transpose of matrixA.
      * * Callers that will apply the same matrix to many planes should pre-invert the matrix for efficiency.
      * * Both params default to true to get the full effect of transforming space.
-     * @param matrix matrix to apply
      */
     multiplyPlanesByMatrix4d(matrix, invert = true, transpose = true) {
         if (invert) { // form inverse once here, reuse for all planes
@@ -179,7 +196,7 @@ export class ClipPrimitive {
             this._clipPlanes.multiplyPlanesByMatrix4d(matrix);
         return true;
     }
-    /** Apply a transform to the clipper (e.g. transform all planes) */
+    /** Apply a transform to the clipper (e.g. transform all planes). */
     transformInPlace(transform) {
         if (this._clipPlanes)
             this._clipPlanes.transformInPlace(transform);
@@ -190,7 +207,8 @@ export class ClipPrimitive {
         this._invisible = invisible;
     }
     /**
-     * Return true if any plane of the primary clipPlanes has (a) non-zero z component in its normal vector and (b) finite distance from origin.
+     * Return true if any plane of the primary clipPlanes has (a) non-zero z component in its normal vector and
+     * (b) finite distance from origin.
      */
     containsZClip() {
         if (this.fetchClipPlanesRef() !== undefined)
@@ -202,8 +220,9 @@ export class ClipPrimitive {
     }
     /**
      * Quick test of whether the given points fall completely inside or outside.
-     * @param points points to test
-     * @param ignoreInvisibleSetting if true, do the test with the clip planes and return that, ignoring the invisible setting.
+     * @param points points to test.
+     * @param ignoreInvisibleSetting if true, do the test with the clip planes and return that, ignoring the
+     * invisible setting.
      */
     classifyPointContainment(points, ignoreInvisibleSetting) {
         this.ensurePlaneSets();
@@ -222,8 +241,9 @@ export class ClipPrimitive {
             }
         return inside;
     }
-    /** Promote json object form to class instance
-     * * First try to convert to a ClipShape
+    /**
+     * Promote json object form to class instance.
+     * * First try to convert to a ClipShape.
      * * then try as a standalone instance of the base class ClipPrimitive.
      */
     static fromJSON(json) {
@@ -279,27 +299,49 @@ export class ClipShape extends ClipPrimitive {
         this.initSecondaryProps(isMask, zLow, zHigh, transform);
     }
     /** Returns true if this ClipShape is marked as invisible. */
-    get invisible() { return this._invisible; }
+    get invisible() {
+        return this._invisible;
+    }
     /** Return this transformFromClip, which may be undefined. */
-    get transformFromClip() { return this._transformFromClip; }
+    get transformFromClip() {
+        return this._transformFromClip;
+    }
     /** Return this transformToClip, which may be undefined. */
-    get transformToClip() { return this._transformToClip; }
+    get transformToClip() {
+        return this._transformToClip;
+    }
     /** Returns true if this ClipShape's transforms are currently set. */
-    get transformValid() { return this.transformFromClip !== undefined; }
+    get transformValid() {
+        return this.transformFromClip !== undefined;
+    }
     /** Returns true if this ClipShape's lower z boundary is set. */
-    get zLowValid() { return this._zLow !== undefined; }
+    get zLowValid() {
+        return this._zLow !== undefined;
+    }
     /** Returns true if this ClipShape's upper z boundary is set. */
-    get zHighValid() { return this._zHigh !== undefined; }
+    get zHighValid() {
+        return this._zHigh !== undefined;
+    }
     /** Return true if this ClipShape has a local to world transform */
-    get transformIsValid() { return this._transformFromClip !== undefined; }
+    get transformIsValid() {
+        return this._transformFromClip !== undefined;
+    }
     /** Return this zLow, which may be undefined. */
-    get zLow() { return this._zLow; }
+    get zLow() {
+        return this._zLow;
+    }
     /** Return this zHigh, which may be undefined. */
-    get zHigh() { return this._zHigh; }
+    get zHigh() {
+        return this._zHigh;
+    }
     /** Returns a reference to this ClipShape's polygon array. */
-    get polygon() { return this._polygon; }
+    get polygon() {
+        return this._polygon;
+    }
     /** Returns true if this ClipShape is a masking set. */
-    get isMask() { return this._isMask; }
+    get isMask() {
+        return this._isMask;
+    }
     /** Sets the polygon points array of this ClipShape to the array given (by reference). */
     setPolygon(polygon) {
         // Add closure point
@@ -308,8 +350,9 @@ export class ClipShape extends ClipPrimitive {
         this._polygon = polygon;
     }
     /**
-     * * If the ClipShape's associated `UnionOfConvexClipPlaneSets` is defined, do nothing.
-     * * If the ClipShape's associated `UnionOfConvexClipPlaneSets` is undefined, generate it from the `ClipShape` and transform.
+     * If the ClipShape's associated `UnionOfConvexClipPlaneSets` is defined, do nothing.
+     * If the ClipShape's associated `UnionOfConvexClipPlaneSets` is undefined, generate it from the `ClipShape`
+     * and transform.
      */
     ensurePlaneSets() {
         if (this._clipPlanes !== undefined)
@@ -321,7 +364,7 @@ export class ClipShape extends ClipPrimitive {
     }
     /**
      * Initialize the members of the ClipShape class that may at times be undefined.
-     * zLow and zHigh default to Number.MAX_VALUE, and the transform defaults to an identity transform
+     * zLow and zHigh default to Number.MAX_VALUE, and the transform defaults to an identity transform.
      */
     initSecondaryProps(isMask, zLow, zHigh, transform) {
         this._isMask = isMask;
@@ -336,7 +379,7 @@ export class ClipShape extends ClipPrimitive {
             this._transformToClip = Transform.createIdentity();
         }
     }
-    /** emit json object form */
+    /** Emit json object form */
     toJSON() {
         const shape = {
             points: this._polygon.map((pt) => pt.toJSON()),
@@ -353,7 +396,7 @@ export class ClipShape extends ClipPrimitive {
             shape.zhigh = this.zHigh;
         return { shape };
     }
-    /** parse `json` to a clip shape. */
+    /** Parse `json` to a clip shape. */
     static fromClipShapeJSON(json, result) {
         const shape = json?.shape;
         if (!shape)
@@ -415,7 +458,7 @@ export class ClipShape extends ClipPrimitive {
         blockPoints[1].x = blockPoints[2].x = high.x;
         blockPoints[0].y = blockPoints[1].y = blockPoints[4].y = low.y;
         blockPoints[2].y = blockPoints[3].y = high.y;
-        return ClipShape.createShape(blockPoints, (ClipMaskXYZRangePlanes.None !== (clipMask & ClipMaskXYZRangePlanes.ZLow)) ? low.z : undefined, ClipMaskXYZRangePlanes.None !== (clipMask & ClipMaskXYZRangePlanes.ZHigh) ? high.z : undefined, transform, isMask, invisible, result);
+        return ClipShape.createShape(blockPoints, (ClipMaskXYZRangePlanes.None !== (clipMask & ClipMaskXYZRangePlanes.ZLow)) ? low.z : undefined, (ClipMaskXYZRangePlanes.None !== (clipMask & ClipMaskXYZRangePlanes.ZHigh)) ? high.z : undefined, transform, isMask, invisible, result);
     }
     /** Creates a new ClipShape with undefined members and a polygon points array of zero length. */
     static createEmpty(isMask = false, invisible = false, transform, result) {
@@ -436,11 +479,14 @@ export class ClipShape extends ClipPrimitive {
             return false;
         return true;
     }
-    /** Returns a deep copy of this instance of ClipShape, storing in an optional result */
+    /** Returns a deep copy of this instance of ClipShape, storing in an optional result. */
     clone(result) {
         return ClipShape.createFrom(this, result);
     }
-    /** Given the current polygon data, parses clip planes that together form an object, storing the result in the set given, either clipplanes or maskplanes. */
+    /**
+     * Given the current polygon data, parses clip planes that together form an object, storing the result in
+     * the set given, either clip planes or mask planes.
+     */
     parseClipPlanes(set) {
         const points = this._polygon;
         if (points.length === 3 && !this._isMask && points[0].isExactEqual(points[points.length - 1])) {
@@ -459,7 +505,10 @@ export class ClipShape extends ClipPrimitive {
         this.parsePolygonPlanes(set, this._polygon, this.isMask);
         return true;
     }
-    /** Given a start and end point, populate the given UnionOfConvexClipPlaneSets with ConvexClipPlaneSets defining the bounded region of linear planes. Returns true if successful. */
+    /**
+     * Given a start and end point, populate the given UnionOfConvexClipPlaneSets with ConvexClipPlaneSets
+     * defining the bounded region of linear planes. Returns true if successful.
+     */
     parseLinearPlanes(set, start, end, cameraFocalLength) {
         // Handles the degenerate case of 2 distinct points (used by select by line).
         const normal = start.vectorTo(end);
@@ -491,7 +540,10 @@ export class ClipShape extends ClipPrimitive {
         set.addConvexSet(convexSet);
         return true;
     }
-    /** Given a convex polygon defined as an array of points, populate the given UnionOfConvexClipPlaneSets with ConvexClipPlaneSets defining the bounded region. Returns true if successful. */
+    /**
+     * Given a convex polygon defined as an array of points, populate the given UnionOfConvexClipPlaneSets with
+     * ConvexClipPlaneSets defining the bounded region. Returns true if successful.
+     */
     parseConvexPolygonPlanes(set, polygon, direction, buildExteriorClipper, cameraFocalLength) {
         const samePointTolerance = 1.0e-8; // This could possibly be replaced with more widely used constants
         const edges = [];
@@ -549,7 +601,10 @@ export class ClipShape extends ClipPrimitive {
         }
         return true;
     }
-    /** Given a (possibly non-convex) polygon defined as an array of points, populate the given UnionOfConvexClipPlaneSets with multiple ConvexClipPlaneSets defining the bounded region. Returns true if successful. */
+    /**
+     * Given a (possibly non-convex) polygon defined as an array of points, populate the given UnionOfConvexClipPlaneSets
+     * with multiple ConvexClipPlaneSets defining the bounded region. Returns true if successful.
+     */
     parsePolygonPlanes(set, polygon, isMask, cameraFocalLength) {
         const cleanPolygon = PolylineOps.compressDanglers(polygon, true);
         const announceFace = (_graph, edge) => {
@@ -596,17 +651,19 @@ export class ClipShape extends ClipPrimitive {
      * Multiply all ClipPlanes DPoint4d by matrix.
      * @param matrix matrix to apply.
      * @param invert if true, use in verse of the matrix.
-     * @param transpose if true, use the transpose of the matrix (or inverse, per invert parameter)
-     * * Note that if matrixA is applied to all of space, the matrix to send to this method to get a corresponding effect on the plane is the inverse transpose of matrixA
+     * @param transpose if true, use the transpose of the matrix (or inverse, per invert parameter).
+     * @param matrix matrix to apply.
+     * * Note that if matrixA is applied to all of space, the matrix to send to this method to get a corresponding effect
+     * on the plane is the inverse transpose of matrixA.
      * * Callers that will apply the same matrix to many planes should pre-invert the matrix for efficiency.
      * * Both params default to true to get the full effect of transforming space.
-     * @param matrix matrix to apply
      */
     multiplyPlanesByMatrix4d(matrix, invert = true, transpose = true) {
         this.ensurePlaneSets();
         return super.multiplyPlanesByMatrix4d(matrix, invert, transpose);
     }
-    /** Apply `transform` to the local to world (`transformFromClip`) transform.
+    /**
+     * Apply `transform` to the local to world (`transformFromClip`) transform.
      * * The world to local transform (`transformToClip` is recomputed from the (changed) `transformToClip`
      * * the transform is passed to the base class to be applied to clip plane form of the clipper.
      */
@@ -621,7 +678,8 @@ export class ClipShape extends ClipPrimitive {
         this._transformToClip = this._transformFromClip.inverse(); // could be undefined
         return true;
     }
-    /** Return true if
+    /**
+     * Return true if
      * * at least one point is defined
      * * The local to world transform (transformFromClip) either
      *   * is undefined