@itwin/core-geometry 4.1.0-dev.3 → 4.1.0-dev.5

package/lib/esm/curve/CurvePrimitive.js

@@ -19,20 +19,21 @@ import { AppendPlaneIntersectionStrokeHandler } from "./internalContexts/AppendP
 import { ClosestPointStrokeHandler } from "./internalContexts/ClosestPointStrokeHandler";
 import { CurveLengthContext } from "./internalContexts/CurveLengthContext";
 /**
- * A curve primitive is bounded
+ * A curve primitive is bounded.
  * A curve primitive maps fractions in 0..1 to points in space.
  * As the fraction proceeds from 0 towards 1, the point moves "forward" along the curve.
  * True distance along the curve is not always strictly proportional to fraction.
- * * LineSegment3d always has proportional fraction and distance
- * * an Arc3d which is true circular has proportional fraction and distance
- * *  A LineString3d is not proportional (except for special case of all segments of equal length)
- * * A Spiral3d is proportional
+ * * A LineSegment3d always has proportional fraction and distance.
+ * * An Arc3d which is true circular has proportional fraction and distance.
+ * * A LineString3d is not proportional (except for special case of all segments of equal length).
+ * * A Spiral3d is proportional.
  * * A BsplineCurve3d is only proportional for special cases.
- *
- * For fractions outside 0..1, the curve primitive class may either (a) return the near endpoint or (b) evaluate an extended curve.
+ * For fractions outside 0..1, the curve primitive class may either (a) return the near endpoint or (b) evaluate
+ * an extended curve.
  * @public
  */
 export class CurvePrimitive extends GeometryQuery {
+    /** Constructor */
     constructor() {
         super();
         /** String name for schema properties */
@@ -60,30 +61,35 @@ export class CurvePrimitive extends GeometryQuery {
         const b = data.vectorU.magnitude();
         return Geometry.conditionalDivideFraction(a, b * b * b);
     }
-    /** Construct a frenet frame:
+    /**
+     * Construct a frenet frame:
      * * origin at the point on the curve
      * * x axis is unit vector along the curve (tangent)
-     * * y axis is perpendicular and in the plane of the osculating circle.
-     * * z axis perpendicular to those.
+     * * y axis is perpendicular and in the plane of the osculating circle. y axis is called "main normal"
+     * * z axis perpendicular to those. z axis is called "bi-normal"
      */
     fractionToFrenetFrame(fraction, result) {
         const plane = this.fractionToPointAnd2Derivatives(fraction);
         if (!plane)
             return undefined;
+        // first derivative (plane.vectorU) and second derivative (plane.vectorV) are not essentially
+        // perpendicular so we use createRigidFromColumns to make 3 perpendicular vectors.
         let axes = Matrix3d.createRigidFromColumns(plane.vectorU, plane.vectorV, AxisOrder.XYZ);
         if (axes)
             return Transform.createRefs(plane.origin, axes, result);
-        // 2nd derivative not distinct -- do arbitrary headsUP ...
+        // 2nd derivative not distinct. for example if curve is linear at fraction so second derivative is 0.
+        // in this case we find perpendicular vector to plane.vectorU and pass it to createRigidFromColumns.
         const perpVector = Matrix3d.createPerpendicularVectorFavorXYPlane(plane.vectorU, plane.vectorV);
         axes = Matrix3d.createRigidFromColumns(plane.vectorU, perpVector, AxisOrder.XYZ);
         if (axes)
             return Transform.createRefs(plane.origin, axes, result);
         return undefined;
     }
-    /** Construct signed distance from a point on the curve to its center of curvature (in xy only).
-     * * Positive is to the left of the xy tangent.
-     * * negative is to the right of the xy tangent.
-     * * linear curve is 0.
+    /**
+     * Construct signed distance from a point on the planar curve to its center of curvature (in xy only).
+     * * Positive distance means the center is to the left of the curve at fraction.
+     * * Negative distance means the center is to the right of the curve at fraction.
+     * * Zero distance means curve is linear at fraction.
      */
     fractionToSignedXYRadiusOfCurvature(fraction) {
         const plane = this.fractionToPointAnd2Derivatives(fraction);
@@ -108,7 +114,7 @@ export class CurvePrimitive extends GeometryQuery {
         return ray.fractionToPoint(distance);
     }
     /**
-     * return the length of the curve.
+     * Return the length of the curve.
      * * Curve length is always positive.
      */
     curveLength() {
@@ -117,9 +123,9 @@ export class CurvePrimitive extends GeometryQuery {
         return context.getSum();
     }
     /**
-     * Returns a (high accuracy) length of the curve between fractional positions
+     * Returns a (high accuracy) length of the curve between fractional positions.
      * * Curve length is always positive.
-     * * Default implementation applies a generic gaussian integration.
+     * * Default implementation applies a generic Gaussian integration.
      * * Most curve classes (certainly LineSegment, LineString, Arc) are expected to provide efficient implementations.
      */
     curveLengthBetweenFractions(fraction0, fraction1) {
@@ -127,7 +133,7 @@ export class CurvePrimitive extends GeometryQuery {
             return 0.0;
         const scale = this.getFractionToDistanceScale();
         if (scale !== undefined) {
-            // We are in luck! simple proportions determine it all  !!!
+            // We are in luck! simple proportions determine it all !!!
             // (for example, a LineSegment3d or a circular arc)
             const totalLength = this.curveLength();
             return Math.abs((fraction1 - fraction0) * totalLength);
@@ -138,14 +144,14 @@ export class CurvePrimitive extends GeometryQuery {
     }
     /**
      * Returns a (high accuracy) range of the curve between fractional positions
-     * * Default implementation returns teh range of the curve from clonePartialCurve
+     * * Default implementation returns the range of the curve from clonePartialCurve
      */
     rangeBetweenFractions(fraction0, fraction1, transform) {
         return this.rangeBetweenFractionsByClone(fraction0, fraction1, transform);
     }
     /**
      * Returns a (high accuracy) range of the curve between fractional positions
-     * * Default implementation returns teh range of the curve from clonePartialCurve
+     * * Default implementation returns the range of the curve from clonePartialCurve
      */
     rangeBetweenFractionsByClone(fraction0, fraction1, transform) {
         if (fraction0 === fraction1)
@@ -159,12 +165,16 @@ export class CurvePrimitive extends GeometryQuery {
      * Returns an approximate range based on a fixed number of evaluations
      * * Default implementation returns a range determined by evaluating a specified number of points on the curve.
      * * Optional evaluate again at interval midpoints and extrapolate any increase
-     * * For a smooth curve, Richardson extrapolation suggests each subdivision moves 3/4 of the way to final. So extrapolationFactor
-     *            of 1/3 gets speculatively moves closer to the tight range, and larger multipliers increase confidence in being safely larger.
+     * * For a smooth curve, Richardson extrapolation suggests each subdivision moves 3/4 of the way to final. So
+     * extrapolationFactor of 1/3 gets speculatively moves closer to the tight range, and larger multipliers increase
+     * confidence in being safely larger.
+     * * This function is faster version to compute the range of a portion of a curve (because some curves can be
+     * expensive to compute the partial curve and/or to compute the partial curve's range.
      * @param fraction0 start fraction for evaluation
      * @param fraction1 end fraction for evaluation
      * @param count number of points to evaluate
-     * @param extrapolationFactor if positive, evaluate again at interval midpoints and apply this fraction multiplier to any increase in size.
+     * @param extrapolationFactor if positive, evaluate again at interval midpoints and apply this fraction multiplier
+     * to any increase in size.
      */
     rangeBetweenFractionsByCount(fraction0, fraction1, count, transform, extrapolationFactor = 0.0) {
         const range = Range3d.createNull();
@@ -189,8 +199,8 @@ export class CurvePrimitive extends GeometryQuery {
             evaluateSteps(fraction0 + globalFractionStep, globalFractionStep, interiorCount);
         }
         if (extrapolationFactor > 0.0) {
-            // Evaluate at midpoints.  Where this makes the range larger, apply extrapolationFactor to move it to safer excess value.
-            // same interior step, but shift to interval midpoints:.
+            // Evaluate at midpoints.  Where this makes the range larger, apply extrapolationFactor to move it to safer
+            // excess value. same interior step, but shift to interval midpoints.
             const baseRange = range.clone();
             const interiorCount1 = interiorCount + 1;
             const localFraction0 = 0.5 / interiorCount1; // we only evaluate at new midpoints.
@@ -201,13 +211,13 @@ export class CurvePrimitive extends GeometryQuery {
         return range;
     }
     /**
-     *
-     * * Run an integration (with a default gaussian quadrature) with a fixed fractional step
+     * Run an integration (with a default Gaussian quadrature) with a fixed fractional step
      * * This is typically called by specific curve type implementations of curveLengthBetweenFractions.
-     *   * For example, in Arc3d implementation of curveLengthBetweenFractions:
+     * * For example, in Arc3d implementation of curveLengthBetweenFractions:
      *     * If the Arc3d is true circular, it the arc is true circular, use the direct `arcLength = radius * sweepRadians`
-     *     * If the Arc3d is not true circular, call this method with an interval count appropriate to eccentricity and sweepRadians.
-     * @returns Returns an integral estimated by numerical quadrature between the fractional positions.
+     *     * If the Arc3d is not true circular, call this method with an interval count appropriate to eccentricity and
+     * sweepRadians.
+     * @returns Returns the curve length via an integral estimated by numerical quadrature between the fractional positions.
      * @param fraction0 start fraction for integration
      * @param fraction1 end fraction for integration
      * @param numInterval number of quadrature intervals
@@ -223,33 +233,39 @@ export class CurvePrimitive extends GeometryQuery {
         return Math.abs(context.getSum());
     }
     /**
-     *
-     * * (Attempt to) find a position on the curve at a signed distance from start fraction.
+     * (Attempt to) find a position on the curve at a signed distance from start fraction.
      * * Return the position as a CurveLocationDetail.
      * * In the `CurveLocationDetail`, record:
      *   * `fraction` = fractional position
      *   * `point` = coordinates of the point
-     *   * `a` = (signed!) distance moved.   If `allowExtension` is false and the move reached the start or end of the curve, this distance is smaller than the requested signedDistance.
+     *   * `a` = (signed!) distance moved.   If `allowExtension` is false and the move reached the start or end of the
+     * curve, this distance is smaller than the requested signedDistance.
      *   * `curveSearchStatus` indicates one of:
      *     * `error` (unusual) computation failed not supported for this curve.
      *     * `success` full movement completed
      *     * `stoppedAtBoundary` partial movement completed. This can be due to either
      *        * `allowExtension` parameter sent as `false`
      *        * the curve type (e.g. bspline) does not support extended range.
-     * * if `allowExtension` is true, movement may still end at the startPoint or end point for curves that do not support extended geometry (specifically bsplines)
-     * * if the curve returns a value (i.e. not `undefined`) for `curve.getFractionToDistanceScale()`, the base class carries out the computation
+     * * if `allowExtension` is true, movement may still end at the startPoint or end point for curves that do not support
+     * extended geometry (specifically bsplines)
+     * * if the curve returns a value (i.e. not `undefined`) for `curve.getFractionToDistanceScale()`, the base class
+     * carries out the computation
      *    and returns a final location.
      *   * LineSegment3d relies on this.
-     * * If the curve does not implement the computation or the curve has zero length, the returned `CurveLocationDetail` has
+     * * If the curve does not implement the computation or the curve has zero length, the returned `CurveLocationDetail`
+     * has
      *    * `fraction` = the value of `startFraction`
      *    * `point` = result of `curve.fractionToPoint(startFraction)`
      *    * `a` = 0
      *    * `curveStartState` = `CurveSearchStatus.error`
      * @param startFraction fractional position where the move starts
      * @param signedDistance distance to move.   Negative distance is backwards in the fraction space
-     * @param allowExtension if true, all the move to go beyond the startPoint or endpoint of the curve.  If false, do not allow movement beyond the startPoint or endpoint
+     * @param allowExtension if true, all the move to go beyond the startPoint or endpoint of the curve.  If false, do not
+     * allow movement beyond the startPoint or endpoint
      * @param result optional result.
-     * @returns A CurveLocationDetail annotated as above.  Note that if the curve does not support the calculation, there is still a result which contains the point at the input startFraction, with failure indicated in the `curveStartState` member
+     * @returns A CurveLocationDetail annotated as above. Note that if the curve does not support the calculation, there is
+     * still a result which contains the point at the input startFraction, with failure indicated in the `curveStartState`
+     * member
      */
     moveSignedDistanceFromFraction(startFraction, signedDistance, allowExtension, result) {
         const scale = this.getFractionToDistanceScale();
@@ -269,13 +285,14 @@ export class CurvePrimitive extends GeometryQuery {
      * Generic algorithm to search for point at signed distance from a fractional startPoint.
      * * This will work for well for smooth curves.
      * * Curves with tangent or other low-order-derivative discontinuities may need to implement specialized algorithms.
-     * * We need to find an endFraction which is the end-of-interval (usually upper) limit of integration of the tangent magnitude from startFraction to endFraction
+     * * We need to find an endFraction which is the end-of-interval (usually upper) limit of integration of the tangent
+     * magnitude from startFraction to endFraction
      * * That integral is a function of endFraction.
      * * The derivative of that integral with respect to end fraction is the tangent magnitude at end fraction.
      * * Use that function and (easily evaluated!) derivative for a Newton iteration
-     * * TO ALL WHO HAVE FUZZY MEMORIES OF CALCULUS CLASS: "The derivative of the integral wrt upper limit is the value of the integrand there" is the
-     *       fundamental theorem of integral calculus !!! The fundamental theorem is not just an abstraction !!! It is being used
-     *       here in its barest possible form !!!
+     * * TO ALL WHO HAVE FUZZY MEMORIES OF CALCULUS CLASS: "The derivative of the integral wrt upper limit is the value
+     * of the integrand there" is the fundamental theorem of integral calculus !!! The fundamental theorem is not just
+     * an abstraction !!! It is being used  here in its barest possible form !!!
      * * See https://en.wikipedia.org/wiki/Fundamental_theorem_of_calculus
      * @param startFraction
      * @param signedDistance
@@ -356,20 +373,25 @@ export class CurvePrimitive extends GeometryQuery {
         return result;
     }
     /**
-     * * Returns true if the curve's fraction queries extend beyond 0..1.
+     * * Returns true if the curve can be easily extended past its start/end point (i.e., beyond the usual
+     * fraction space [0,1]). Otherwise, returns false.
      * * Base class default implementation returns false.
-     * * These class (and perhaps others in the future) will return true:
+     * * These classes (and perhaps others in the future) will return true:
      *   * LineSegment3d
      *   * LineString3d
      *   * Arc3d
      */
-    get isExtensibleFractionSpace() { return false; }
-    /** Search for the curve point that is closest to the spacePoint.
-     *
+    get isExtensibleFractionSpace() {
+        return false;
+    }
+    /**
+     * Search for a point on the curve that is closest to the spacePoint.
      * * If the space point is exactly on the curve, this is the reverse of fractionToPoint.
-     * * Since CurvePrimitive should always have start and end available as candidate points, this method should always succeed
+     * * Since CurvePrimitive should always have start and end available as candidate points, this method should always
+     * succeed
      * @param spacePoint point in space
-     * @param extend true to extend the curve (if possible), false for no extend, single CurveExtendOptions (for both directions), or array of distinct CurveExtendOptions for start and end.
+     * @param extend true to extend the curve (if possible), false for no extend, single CurveExtendOptions (for both
+     * directions), or array of distinct CurveExtendOptions for start and end.
      * @returns Returns a CurveLocationDetail structure that holds the details of the close point.
      */
     closestPoint(spacePoint, extend) {
@@ -380,14 +402,16 @@ export class CurvePrimitive extends GeometryQuery {
     /**
      * Find intervals of this curvePrimitive that are interior to a clipper
      * @param clipper clip structure (e.g. clip planes)
-     * @param announce (optional) function to be called announcing fractional intervals"  ` announce(fraction0, fraction1, curvePrimitive)`
+     * @param announce (optional) function to be called announcing fractional intervals
+     * `announce(fraction0, fraction1, curvePrimitive)`
      * @returns true if any "in" segments are announced.
      */
     announceClipIntervals(_clipper, _announce) {
         // DEFAULT IMPLEMENTATION -- no interior parts
         return false;
     }
-    /** Return (if possible) a curve primitive which is a portion of this curve.
+    /**
+     * Return (if possible) a curve primitive which is a portion of this curve.
      * @param _fractionA [in] start fraction
      * @param _fractionB [in] end fraction
      */
@@ -395,8 +419,8 @@ export class CurvePrimitive extends GeometryQuery {
         return undefined;
     }
     /**
-     * * If the curve primitive has distance-along-curve strictly proportional to curve fraction, return the scale factor.
-     * * If distance-along-the-curve is not proportional, return undefined.
+     * If the curve primitive has distance-along-curve strictly proportional to curve fraction, return the scale factor.
+     * If distance-along-the-curve is not proportional, return undefined.
      * * When defined, the scale factor is always the length of the curve.
      * * This scale factor is typically available for these curve types:
      * * * All `LineSegment3d`
@@ -407,12 +431,14 @@ export class CurvePrimitive extends GeometryQuery {
      * * * bspline and bezier curves
      * @returns scale factor or undefined
      */
-    getFractionToDistanceScale() { return undefined; }
+    getFractionToDistanceScale() {
+        return undefined;
+    }
     /**
-     * Compute intersections with a plane.
+     * Compute intersections of the curve with a plane.
      * * The intersections are appended to the result array.
-     * * The base class implementation emits strokes to an AppendPlaneIntersectionStrokeHandler object, which uses a Newton iteration to get
-     *     high-accuracy intersection points within strokes.
+     * * The base class implementation emits strokes to an AppendPlaneIntersectionStrokeHandler object, which uses a
+     * Newton iteration to get high-accuracy intersection points within strokes.
      * * Derived classes should override this default implementation if there are easy analytic solutions.
      * * Derived classes are free to implement extended intersections (e.g. arc!!!)
      * @param plane The plane to be intersected.
@@ -429,8 +455,8 @@ export class CurvePrimitive extends GeometryQuery {
      * Examine contents of an array of CurveLocationDetail.
      * Filter the intersections according to the parameters.
      * @param allowExtend if false, remove points on the extension.
-     * @param applySnappedCoordinates if true, change the stored fractions and coordinates to exact end values.  Otherwise
-     *     use the exact values only for purpose of updating the curveIntervalRole.
+     * @param applySnappedCoordinates if true, change the stored fractions and coordinates to exact end values.
+     * Otherwise use the exact values only for purpose of updating the curveIntervalRole.
      * @param startEndFractionTolerance if nonzero, adjust fraction to 0 or 1 with this tolerance.
      * @param startEndXYZTolerance if nonzero, adjust to endpoint with this tolerance.
      * @internal
@@ -493,12 +519,16 @@ export class CurvePrimitive extends GeometryQuery {
         if (acceptIndex < n0)
             details.length = acceptIndex;
     }
-    /** return the startPoint of the primitive.  The default implementation returns fractionToPoint (0.0) */
-    startPoint(result) { return this.fractionToPoint(0.0, result); }
-    /** return the end point of the primitive. The default implementation returns fractionToPoint(1.0) */
-    endPoint(result) { return this.fractionToPoint(1.0, result); }
+    /** Return the startPoint of the primitive. The default implementation returns fractionToPoint(0.0) */
+    startPoint(result) {
+        return this.fractionToPoint(0.0, result);
+    }
+    /** Return the end point of the primitive. The default implementation returns fractionToPoint(1.0) */
+    endPoint(result) {
+        return this.fractionToPoint(1.0, result);
+    }
     /**
-     * attach StrokeCountMap structure to this primitive (and recursively to any children)
+     * Attach StrokeCountMap structure to this primitive (and recursively to any children)
      * * Base class implementation (here) gets the simple count from computeStrokeCountForOptions and attaches it.
      * * LineString3d, arc3d, BezierCurve3d, BezierCurve3dH accept that default.
      * * Subdivided primitives (linestring, bspline curve) implement themselves and attach a StrokeCountMap containing the
@@ -506,7 +536,8 @@ export class CurvePrimitive extends GeometryQuery {
      * * For CurvePrimitiveWithDistanceIndex, the top level gets (only) a total count, and each child gets
      *       its own StrokeCountMap with appropriate structure.
      * @param options StrokeOptions that determine count
-     * @param parentStrokeMap optional map from parent.  Its count, curveLength, and a1 values are increased with count and distance from this primitive.
+     * @param parentStrokeMap optional map from parent.  Its count, curveLength, and a1 values are increased with count
+     * and distance from this primitive.
      * @return sum of `a0+this.curveLength()`, for use as `a0` of successor in chain.
      */
     computeAndAttachRecursiveStrokeCounts(options, parentMap) {
@@ -515,8 +546,9 @@ export class CurvePrimitive extends GeometryQuery {
         CurvePrimitive.installStrokeCountMap(this, StrokeCountMap.createWithCurvePrimitive(this, n, a, 0, a), parentMap);
     }
     /**
-     * * evaluate strokes at fractions indicated in a StrokeCountMap.
-     *   * Base class implementation (here) gets the simple count from computeStrokeCountForOptions and strokes at uniform fractions.
+     * Evaluate strokes at fractions indicated in a StrokeCountMap.
+     *   * Base class implementation (here) gets the simple count from computeStrokeCountForOptions and strokes at
+     * uniform fractions.
      *   * LineString3d, arc3d, BezierCurve3d, BezierCurve3dH accept that default.
      *   * Subdivided primitives (linestring, bspline curve) implement themselves and evaluate within components.
      *   * CurvePrimitiveWithDistanceIndex recurses to its children.
@@ -536,7 +568,7 @@ export class CurvePrimitive extends GeometryQuery {
         return linestring.numPoints() - numPoint0;
     }
     /**
-     * final install step to save curveMap in curve.  If parentMap is given, update its length, count, and a1 fields
+     * Final install step to save curveMap in curve. If parentMap is given, update its length, count, and a1 fields
      * @param curve curve to receive the annotation
      * @param map
      * @param parentMap
@@ -550,8 +582,10 @@ export class CurvePrimitive extends GeometryQuery {
      * Return an array containing only the curve primitives.
      * * This DEFAULT implementation simply pushes `this` to the collectorArray.
      * @param collectorArray array to receive primitives (pushed -- the array is not cleared)
-     * @param smallestPossiblePrimitives if true, a [[CurvePrimitiveWithDistanceIndex]] recurses on its (otherwise hidden) children. If false, it returns only itself.
-     * @param explodeLinestrings if true, push a [[LineSegment3d]] for each segment of a [[LineString3d]]. If false, push only the [[LineString3d]].
+     * @param smallestPossiblePrimitives if true, a [[CurvePrimitiveWithDistanceIndex]] recurses on its (otherwise hidden)
+     * children. If false, it returns only itself.
+     * @param explodeLinestrings if true, push a [[LineSegment3d]] for each segment of a [[LineString3d]]. If false,
+     * push only the [[LineString3d]].
      */
     collectCurvePrimitivesGo(collectorArray, _smallestPossiblePrimitives, _explodeLinestrings = false) {
         collectorArray.push(this);
@@ -559,18 +593,23 @@ export class CurvePrimitive extends GeometryQuery {
     /**
      * Return an array containing only the curve primitives.
      * * This DEFAULT implementation captures the optional collector and calls [[collectCurvePrimitivesGo]].
-     * @param collectorArray optional array to receive primitives.   If present, new primitives are ADDED (without clearing the array.)
-     * @param smallestPossiblePrimitives if false, CurvePrimitiveWithDistanceIndex returns only itself.  If true, it recurses to its (otherwise hidden) children.
+     * @param collectorArray optional array to receive primitives.   If present, new primitives are ADDED (without
+     * clearing the array.)
+     * @param smallestPossiblePrimitives if false, CurvePrimitiveWithDistanceIndex returns only itself.  If true,
+     * it recurses to its (otherwise hidden) children.
      */
     collectCurvePrimitives(collectorArray, smallestPossiblePrimitives = false, explodeLinestrings = false) {
         const results = collectorArray === undefined ? [] : collectorArray;
         this.collectCurvePrimitivesGo(results, smallestPossiblePrimitives, explodeLinestrings);
         return results;
     }
-    /** Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of projection.
+    /**
+     * Project instance geometry (via dispatch) onto the line of the given ray, and return the extreme fractional
+     * parameters of projection.
      * @param ray ray onto which the instance is projected. A `Vector3d` is treated as a `Ray3d` with zero origin.
      * @param lowHigh optional receiver for output
-     * @returns range of fractional projection parameters onto the ray, where 0.0 is start of the ray and 1.0 is the end of the ray.
+     * @returns range of fractional projection parameters onto the ray, where 0.0 is start of the ray and 1.0 is the
+     * end of the ray.
      */
     projectedParameterRange(_ray, _lowHigh) {
         return undefined; // common implementation delegated to subclasses to avoid circular dependency