@itwin/core-geometry 4.1.0-dev.8 → 4.1.0-dev.81

package/lib/cjs/curve/internalContexts/PolygonOffsetContext.js

@@ -7,7 +7,7 @@
  * @module Curve
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CurveChainWireOffsetContext = exports.PolygonWireOffsetContext = exports.OffsetOptions = exports.JointOptions = void 0;
+exports.CurveChainWireOffsetContext = exports.PolygonWireOffsetContext = void 0;
 const Geometry_1 = require("../../Geometry");
 const AngleSweep_1 = require("../../geometry3d/AngleSweep");
 const Point3dVector3d_1 = require("../../geometry3d/Point3dVector3d");
@@ -19,11 +19,12 @@ const CurvePrimitive_1 = require("../CurvePrimitive");
 const LineSegment3d_1 = require("../LineSegment3d");
 const LineString3d_1 = require("../LineString3d");
 const Loop_1 = require("../Loop");
+const OffsetOptions_1 = require("../OffsetOptions");
 const Path_1 = require("../Path");
 const RegionOps_1 = require("../RegionOps");
-const StrokeOptions_1 = require("../StrokeOptions");
+// cspell:word CCWXY
 /**
- * Classification of contortions at a joint.
+ * Classification of how the joint is constructed.
  * @internal
  */
 var JointMode;
@@ -35,111 +36,6 @@ var JointMode;
     JointMode[JointMode["JustGeometry"] = 3] = "JustGeometry";
     JointMode[JointMode["Gap"] = 4] = "Gap";
 })(JointMode || (JointMode = {}));
-/**
- * * Control parameters for joint construction.
- * * Decision order is:
- *   * if turn angle is greater than minArcDegrees, make an arc.
- *   * if turn angle is less than or equal maxChamferTurnDegrees, extend curves along tangent to single intersection point.
- *   * if turn angle is greater than maxChamferTurnDegrees,  construct multiple lines that are tangent to the turn circle "from the outside",
- *           with each equal turn less than maxChamferTurnDegrees.
- *   * otherwise make single edge.
- * @public
- */
-class JointOptions {
-    /** Construct JointOptions.
-     * * leftOffsetDistance is required
-     * * minArcDegrees and maxChamferDegrees are optional.
-     */
-    constructor(leftOffsetDistance, minArcDegrees = 180, maxChamferDegrees = 90, preserveEllipticalArcs = false) {
-        /** smallest arc to construct.
-         * * If this control angle is large, arcs are never created.
-         */
-        this.minArcDegrees = 180.0;
-        this.maxChamferTurnDegrees = 90;
-        /** Offset distance, positive to left of base curve. */
-        this.leftOffsetDistance = 0;
-        /** Whether to offset elliptical arcs as elliptical arcs (true) or as B-spline curves (false, default). */
-        this.preserveEllipticalArcs = false;
-        this.leftOffsetDistance = leftOffsetDistance;
-        this.minArcDegrees = minArcDegrees;
-        this.maxChamferTurnDegrees = maxChamferDegrees;
-        this.preserveEllipticalArcs = preserveEllipticalArcs;
-    }
-    /** Return a deep clone. */
-    clone() {
-        return new JointOptions(this.leftOffsetDistance, this.minArcDegrees, this.maxChamferTurnDegrees, this.preserveEllipticalArcs);
-    }
-    /** Copy values of input options */
-    setFrom(other) {
-        this.leftOffsetDistance = other.leftOffsetDistance;
-        this.minArcDegrees = other.minArcDegrees;
-        this.maxChamferTurnDegrees = other.maxChamferTurnDegrees;
-        this.preserveEllipticalArcs = other.preserveEllipticalArcs;
-    }
-    /**
-     * Parse a number or JointOptions up to JointOptions:
-     * * If leftOffsetDistanceOptions is a number, create a JointOptions with other options set to default values.
-     * * If leftOffsetDistanceOrOptions is a JointOptions, return it unchanged.
-     * @param leftOffsetDistanceOrOptions
-     */
-    static create(leftOffsetDistanceOrOptions) {
-        if (leftOffsetDistanceOrOptions instanceof JointOptions)
-            return leftOffsetDistanceOrOptions;
-        // if (Number.isFinite(leftOffsetDistanceOrOptions))
-        return new JointOptions(leftOffsetDistanceOrOptions);
-    }
-    /** return true if the options indicate this amount of turn should be handled with an arc. */
-    needArc(theta) {
-        return Math.abs(theta.degrees) >= this.minArcDegrees;
-    }
-    /** Test if turn by theta should be output as single point. */
-    numChamferPoints(theta) {
-        const degrees = Math.abs(theta.degrees);
-        const stepDegrees = Geometry_1.Geometry.clamp(this.maxChamferTurnDegrees, 10, 120);
-        if (degrees <= stepDegrees)
-            return 1;
-        return Math.ceil(degrees / stepDegrees);
-    }
-}
-exports.JointOptions = JointOptions;
-/**
- * Options for offsetting a curve.
- * @public
- */
-class OffsetOptions {
-    /** Options that are provided are captured. */
-    constructor(offsetDistanceOrOptions, strokeOptions) {
-        this.jointOptions = JointOptions.create(offsetDistanceOrOptions);
-        this.strokeOptions = (strokeOptions !== undefined) ? strokeOptions : StrokeOptions_1.StrokeOptions.createForCurves();
-    }
-    get minArcDegrees() { return this.jointOptions.minArcDegrees; }
-    set minArcDegrees(value) { this.jointOptions.minArcDegrees = value; }
-    get maxChamferTurnDegrees() { return this.jointOptions.maxChamferTurnDegrees; }
-    set maxChamferTurnDegrees(value) { this.jointOptions.maxChamferTurnDegrees = value; }
-    get leftOffsetDistance() { return this.jointOptions.leftOffsetDistance; }
-    set leftOffsetDistance(value) { this.jointOptions.leftOffsetDistance = value; }
-    get preserveEllipticalArcs() { return this.jointOptions.preserveEllipticalArcs; }
-    set preserveEllipticalArcs(value) { this.jointOptions.preserveEllipticalArcs = value; }
-    /** Convert variant input into OffsetOptions.
-     * * If a JointOptions is provided, it is captured.
-     * * If an OffsetOptions is provided, a reference to it is returned. */
-    static create(offsetDistanceOrOptions) {
-        if (offsetDistanceOrOptions instanceof OffsetOptions)
-            return offsetDistanceOrOptions;
-        return new OffsetOptions(offsetDistanceOrOptions);
-    }
-    /** Convert variant input into offset distance */
-    static getOffsetDistance(offsetDistanceOrOptions) {
-        if (typeof offsetDistanceOrOptions === "number")
-            return offsetDistanceOrOptions;
-        return offsetDistanceOrOptions.leftOffsetDistance;
-    }
-    /** Return a deep clone. */
-    clone() {
-        return new OffsetOptions(this.jointOptions.clone(), this.strokeOptions.clone());
-    }
-}
-exports.OffsetOptions = OffsetOptions;
 /**
  * Description of geometry around a joint.
  * @internal
@@ -152,7 +48,9 @@ class Joint {
         this.swingPoint = swingPoint;
         this.flexure = JointMode.Unknown;
     }
-    /** try to construct an arc transition from ray0 to ray1 with given center. */
+    /**
+     * Try to construct an arc transition from ray0 to ray1 with given center.
+     */
     static constructArc(ray0, center, ray1) {
         if (center !== undefined && Geometry_1.Geometry.isSameCoordinate(ray0.origin.distance(center), ray1.origin.distance(center))) {
             const angle = ray0.direction.angleToXY(ray1.direction);
@@ -197,6 +95,7 @@ class Joint {
                 destination.packedPoints.push(point);
         }
     }
+    /** Append stroke points along the offset curve defined by the Joint chain to the destination line string. */
     static collectStrokesFromChain(start, destination, maxTest = 100) {
         let numOut = -2 * maxTest; // allow extra things to happen
         Joint.visitJointsOnChain(start, (joint) => {
@@ -208,7 +107,7 @@ class Joint {
                 if (fA === 0.0 && fB === 1.0)
                     curve1 = joint.curve1.clone();
                 else if (fA < fB)
-                    curve1 = joint.curve1.clonePartialCurve(fA, fB);
+                    curve1 = joint.curve1.clonePartialCurve(fA, fB); // trimming is done by clonePartialCurve
                 if (curve1) {
                     if (!joint.jointCurve) {
                         this.addPoint(destination, curve1.startPoint());
@@ -248,6 +147,7 @@ class Joint {
             }
         }
     }
+    /** Append CurvePrimitives along the offset curve defined by the Joint chain to the destination array. */
     static collectCurvesFromChain(start, destination, maxTest = 100) {
         if (start === undefined)
             return;
@@ -262,13 +162,13 @@ class Joint {
                 if (fA === 0.0 && fB === 1.0)
                     curve1 = joint.curve1.clone();
                 else if (fA < fB)
-                    curve1 = joint.curve1.clonePartialCurve(fA, fB);
+                    curve1 = joint.curve1.clonePartialCurve(fA, fB); // trimming is done by clonePartialCurve
                 this.collectPrimitive(destination, curve1);
             }
             return numOut++ < maxTest;
         }, maxTest);
     }
-    /** Execute `joint.annotateJointMode()` at all joints on the chain. */
+    /** Execute `joint.annotateJointMode()` at all joints on the chain to set some of the joints attributes. */
     static annotateChain(start, options, maxTest = 100) {
         if (start)
             Joint.visitJointsOnChain(start, (joint) => { joint.annotateJointMode(options); return true; }, maxTest);
@@ -276,7 +176,7 @@ class Joint {
     /**
      * Visit joints on a chain.
      * * terminate on `false` return from `callback`
-     * @param start first (and, for cyclic chain, final) Joint
+     * @param start first (and, for cyclic chain, final) joint
      * @param callback function to call with each Joint as a single parameter.
      */
     static visitJointsOnChain(start, callback, maxTest = 100) {
@@ -284,7 +184,7 @@ class Joint {
         if (joint) {
             let numTest = 0;
             while (joint !== undefined) {
-                if (numTest++ >= maxTest + 5)
+                if (numTest++ >= maxTest + 5) // allow extra things to happen
                     return true;
                 if (!callback(joint))
                     return false;
@@ -300,13 +200,13 @@ class Joint {
         if (this.curve0 && this.curve1) {
             const ray0 = this.curve0.fractionToPointAndDerivative(1.0);
             const ray1 = this.curve1.fractionToPointAndDerivative(0.0);
-            const intersection = Ray3d_1.Ray3d.closestApproachRay3dRay3d(ray0, ray1);
+            const intersection = Ray3d_1.Ray3d.closestApproachRay3dRay3d(ray0, ray1); // intersection of the 2 ray lines
             if (intersection.approachType === CurveLocationDetail_1.CurveCurveApproachType.Intersection) {
                 if (intersection.detailA.fraction >= 0.0 && intersection.detailB.fraction <= 0.0) {
                     this.fraction0 = 1.0;
                     this.fraction1 = 0.0;
                     this.flexure = JointMode.Extend;
-                    const theta = ray0.getDirectionRef().angleToXY(ray1.getDirectionRef());
+                    const theta = ray0.getDirectionRef().angleToXY(ray1.getDirectionRef()); // angle between the 2 ray lines
                     if (options.needArc(theta)) {
                         const arc = Joint.constructArc(ray0, this.curve0.baseCurveEnd, ray1);
                         if (arc) {
@@ -314,13 +214,12 @@ class Joint {
                             return;
                         }
                     }
-                    const numChamferPoints = options.numChamferPoints(theta);
-                    if (numChamferPoints <= 1) {
+                    const numChamferPoints = options.numChamferPoints(theta); // how many interior points in the linestring
+                    if (numChamferPoints <= 1) { // create sharp corner
                         this.jointCurve = LineString3d_1.LineString3d.create(ray0.origin, intersection.detailA.point, ray1.origin);
                         return;
                     }
-                    if (numChamferPoints > 1) {
-                        // A nontrivial linestring ...
+                    if (numChamferPoints > 1) { // create chamfer corner (a line string)
                         const radians0 = theta.radians;
                         const numHalfStep = 2.0 * numChamferPoints;
                         const halfStepRadians = radians0 / numHalfStep;
@@ -340,19 +239,20 @@ class Joint {
                     }
                 }
             }
-            // desperation appears ...
+            // if there is no intersection between the 2 ray lines, fill the gap by a line segment
             this.flexure = JointMode.Gap;
             this.jointCurve = LineSegment3d_1.LineSegment3d.create(this.curve0.fractionToPoint(1.0), this.curve1.fractionToPoint(0.0));
             this.fraction0 = 1.0;
             this.fraction1 = 0.0;
         }
     }
-    // Select the index at which summed fraction difference is smallest.
+    /** Select the index at which summed fraction difference is smallest */
     selectIntersectionIndexByFraction(fractionA, fractionB, intersections) {
         let index = -1;
         let aMin = Number.MAX_VALUE;
         for (let i = 0; i < intersections.length; i++) {
-            const a = Math.abs(intersections[i].detailA.fraction - fractionA) + Math.abs(intersections[i].detailB.fraction - fractionB);
+            const a = Math.abs(intersections[i].detailA.fraction - fractionA)
+                + Math.abs(intersections[i].detailB.fraction - fractionB);
             if (a < aMin) {
                 aMin = a;
                 index = i;
@@ -361,42 +261,42 @@ class Joint {
         return index;
     }
     /**
-     * Examine the adjacent geometry
-     * * set JointMode:  one of Cap Extend, or Trim
+     * Examine the adjacent geometry to set some of joint attributes:
+     * * set JointMode: one of Cap, Extend, or Trim
      * * set fraction0 and fraction1 of intersection of curve0 and curve1
+     * * set joint curve
      * * this REFERENCES curve0, curve1, fraction0, fraction1
      * * this does not reference nextJoint and previousJoint
      */
     annotateJointMode(options) {
-        if (this.curve0 && !this.curve1) {
+        if (!this.curve0 && this.curve1) { // joint at the start of the chain
             this.flexure = JointMode.Cap;
-            this.fraction0 = 1.0;
+            this.fraction1 = 0.0;
         }
-        else if (this.curve1 && !this.curve0) {
+        else if (this.curve0 && !this.curve1) { // joint at the end of the chain
             this.flexure = JointMode.Cap;
-            this.fraction1 = 0.0;
+            this.fraction0 = 1.0;
         }
-        else if (this.curve0 && this.curve1) {
-            // check for direct intersection -- occurs on offset of colinear base segments, and closed primitives
-            if (this.curve0.endPoint().isAlmostEqual(this.curve1.startPoint())) {
+        else if (this.curve0 && this.curve1) { // joints at the middle of the chain
+            if (this.curve0.endPoint().isAlmostEqual(this.curve1.startPoint())) { // joint between colinear segments
                 this.fraction0 = 1.0;
                 this.fraction1 = 0.0;
                 this.flexure = JointMode.Trim;
             }
-            else if (this.curve0 instanceof LineSegment3d_1.LineSegment3d && this.curve1 instanceof LineSegment3d_1.LineSegment3d) {
-                const ray0 = this.curve0.fractionToPointAndDerivative(0.0); // And we know that is full length ray !
-                const ray1 = this.curve1.fractionToPointAndDerivative(0.0); // ditto
-                const intersection = Ray3d_1.Ray3d.closestApproachRay3dRay3d(ray0, ray1);
+            else if (this.curve0 instanceof LineSegment3d_1.LineSegment3d && this.curve1 instanceof LineSegment3d_1.LineSegment3d) { // pair of lines
+                const ray0 = this.curve0.fractionToPointAndDerivative(0.0);
+                const ray1 = this.curve1.fractionToPointAndDerivative(0.0);
+                const intersection = Ray3d_1.Ray3d.closestApproachRay3dRay3d(ray0, ray1); // intersection of the 2 ray lines
                 if (intersection.approachType === CurveLocationDetail_1.CurveCurveApproachType.Intersection) {
                     this.fraction0 = intersection.detailA.fraction;
                     this.fraction1 = intersection.detailB.fraction;
-                    if (this.fraction0 >= 1.0 && this.fraction1 <= 0.0) {
+                    if (this.fraction0 >= 1.0 && this.fraction1 <= 0.0) { // need to extend
                         this.annotateExtension(options);
                     }
-                    else if (this.fraction0 < 1.0 && this.fraction1 > 0.0) {
+                    else if (this.fraction0 < 1.0 && this.fraction1 > 0.0) { // need to trim
                         this.flexure = JointMode.Trim;
                     }
-                    else if (this.fraction0 > 1.0 && this.fraction1 > 1.0) {
+                    else if (this.fraction0 > 1.0 && this.fraction1 > 1.0) { // need to fill gap with a single line segment
                         this.flexure = JointMode.Gap;
                         this.jointCurve = LineSegment3d_1.LineSegment3d.create(this.curve0.fractionToPoint(1.0), this.curve1.fractionToPoint(0.0));
                         this.fraction0 = 1.0;
@@ -404,15 +304,15 @@ class Joint {
                     }
                 }
             }
-            else { // generic pair of curves ...
+            else { // generic pair of curves
                 const intersections = CurveCurve_1.CurveCurve.intersectionXYPairs(this.curve0, false, this.curve1, false);
                 const intersectionIndex = this.selectIntersectionIndexByFraction(1.0, 0.0, intersections);
-                if (intersectionIndex >= 0) {
+                if (intersectionIndex >= 0) { // need to trim
                     this.flexure = JointMode.Trim;
                     this.fraction0 = intersections[intersectionIndex].detailA.fraction;
                     this.fraction1 = intersections[intersectionIndex].detailB.fraction;
                 }
-                else {
+                else { // need to extend
                     this.annotateExtension(options);
                 }
             }
@@ -420,7 +320,8 @@ class Joint {
     }
     /**
      * * Examine the primitive trim fractions between each pair of joints.
-     * * If trim fractions indicate the primitive must disappear, replace the joint pair by a new joint pointing at surrounding primitives
+     * * If trim fractions indicate the primitive must disappear, replace the joint pair by a new joint pointing at
+     * surrounding primitives
      * @param start
      */
     static removeDegeneratePrimitives(start, options, maxTest) {
@@ -455,8 +356,7 @@ class Joint {
                       }
                     */
                     const eliminateF = f0 >= f1 || f0 > 1.0;
-                    const eliminateG = (g0 !== undefined && g0 > 1.0)
-                        || (g0 !== undefined && g1 !== undefined && g0 >= g1);
+                    const eliminateG = (g0 !== undefined && g0 > 1.0) || (g0 !== undefined && g1 !== undefined && g0 >= g1);
                     if (eliminateF && eliminateG) {
                         const jointC = jointB.nextJoint;
                         const newJoint = new Joint(jointA.curve0, jointC.curve1, undefined);
@@ -512,9 +412,8 @@ class Joint {
  * @internal
  */
 class PolygonWireOffsetContext {
-    /** construct a context. */
-    constructor() {
-    }
+    /** Construct a context. */
+    constructor() { }
     // Construct a single offset from base points
     static createOffsetSegment(basePointA, basePointB, distance) {
         Point3dVector3d_1.Vector3d.createStartEnd(basePointA, basePointB, this._unitAlong);
@@ -527,14 +426,26 @@ class PolygonWireOffsetContext {
         return undefined;
     }
     /**
-     * Construct curves that are offset from a polygon.
-     * * The construction will remove "some" local effects of features smaller than the offset distance, but will not detect self intersection with far-away edges.
-     * @param points
-     * @param wrap
-     * @param offsetDistance
+     * Construct a wire (not area) that is offset from given polyline or polygon (which must be in xy-plane or in
+     *  a plane parallel to xy-plane).
+     * * This is a simple wire offset (in the form of a line string), not an area.
+     * * If offsetDistance is given as a number, default OffsetOptions are applied.
+     * * See [[JointOptions]] class doc for offset construction rules.
+     * @param points a single loop or path
+     * @param wrap true to offset the wraparound joint. Assumes first = last point.
+     * @param offsetDistanceOrOptions offset distance (positive to left of curve, negative to right) or JointOptions
+     * object.
      */
     constructPolygonWireXYOffset(points, wrap, leftOffsetDistanceOrOptions) {
-        const options = JointOptions.create(leftOffsetDistanceOrOptions);
+        /**
+         * if "wrap = true", then first and last point in the points array must be close; otherwise
+         * generated offset will be invalid.
+         */
+        if (wrap && !points[0].isAlmostEqual(points[points.length - 1])) {
+            wrap = false;
+        }
+        /** create raw offsets as a linked list (joint0) */
+        const options = OffsetOptions_1.JointOptions.create(leftOffsetDistanceOrOptions);
         const numPoints = points.length;
         let fragment0 = PolygonWireOffsetContext.createOffsetSegment(points[0], points[1], options.leftOffsetDistance);
         let joint0 = new Joint(undefined, fragment0, points[0]);
@@ -553,7 +464,9 @@ class PolygonWireOffsetContext {
             newJoint = new Joint(fragment0, undefined, points[numPoints - 1]);
             Joint.link(previousJoint, newJoint);
         }
+        /** annotateChain sets some of the joints attributes (including how to extend curves or fill the gap between curves) */
         Joint.annotateChain(joint0, options, numPoints);
+        /** make limited passes through the Joint chain until no self-intersections are removed */
         for (let pass = 0; pass++ < 5;) {
             const state = Joint.removeDegeneratePrimitives(joint0, options, numPoints);
             joint0 = state.newStart;
@@ -567,6 +480,7 @@ class PolygonWireOffsetContext {
             */
         }
         // Joint.collectPrimitivesFromChain(joint0, result, numPoints);
+        /** turn the Joint linked list into a CurveCollection (Loop or Path). trimming is done in collectStrokesFromChain */
         const chain = LineString3d_1.LineString3d.create();
         Joint.collectStrokesFromChain(joint0, chain, numPoints);
         const n = chain.packedPoints.length;
@@ -590,14 +504,13 @@ exports.PolygonWireOffsetContext = PolygonWireOffsetContext;
  */
 class CurveChainWireOffsetContext {
     /** construct a context. */
-    constructor() {
-    }
+    constructor() { }
     /**
      * Annotate a CurvePrimitive with properties `baseCurveStart` and `baseCurveEnd`.
-     * * return cp
-     * @param cp primitive to annotate
+     * @param cp curve primitive to annotate
      * @param startPoint optional start point
      * @param endPoint optional end point
+     * @return the input CurvePrimitive with annotations
      */
     static applyBasePoints(cp, startPoint, endPoint) {
         if (cp !== undefined) {
@@ -609,54 +522,49 @@ class CurveChainWireOffsetContext {
         return cp;
     }
     /**
-     * Create the offset of a single primitive.
-     * * each primitive may be labeled (as an `any` object) with start or end point of base curve:
+     * Create the offset of a single curve primitive as viewed in the xy-plane (ignoring z).
+     * * Each primitive may be labeled (as an `any` object) with start or end point of base curve:
      *   * `(primitive as any).baseCurveStart: Point3d`
      *   * `(primitive as any).baseCurveEnd: Point3d`
-     * @param g primitive to offset
-     * @param offsetDistanceOrOptions offset distance (positive to left of g), or options object
+     * @param curve primitive to offset
+     * @param offsetDistanceOrOptions offset distance (positive to left of curve, negative to right) or options object
      */
-    static createSingleOffsetPrimitiveXY(g, offsetDistanceOrOptions) {
-        const offset = g.constructOffsetXY(offsetDistanceOrOptions);
+    static createSingleOffsetPrimitiveXY(curve, offsetDistanceOrOptions) {
+        const offset = curve.constructOffsetXY(offsetDistanceOrOptions);
         if (offset === undefined)
             return undefined;
         // decorate each offset with its base curve's endpoints
         if (Array.isArray(offset)) {
-            const basePrims = g.collectCurvePrimitives(undefined, true, true);
+            const basePrims = curve.collectCurvePrimitives(undefined, true, true);
             if (basePrims.length !== offset.length)
                 return undefined; // unexpected aggregate curve type!
             for (let i = 0; i < basePrims.length; ++i)
                 this.applyBasePoints(offset[i], basePrims[i].startPoint(), basePrims[i].endPoint());
             return offset;
         }
-        return this.applyBasePoints(offset, g.startPoint(), g.endPoint());
+        return this.applyBasePoints(offset, curve.startPoint(), curve.endPoint());
     }
     /**
      * Construct curves that are offset from a Path or Loop as viewed in xy-plane (ignoring z).
-     * * The construction will remove "some" local effects of features smaller than the offset distance, but will not detect self intersection among widely separated edges.
-     * * If offsetDistance is given as a number, default OffsetOptions are applied.
-     * * When the offset needs to do an "outside" turn, the first applicable construction is applied:
-     *   * If the turn is larger than `options.minArcDegrees`, a circular arc is constructed.
-     *   * If the turn is less than or equal to `options.maxChamferTurnDegrees`, extend curves along tangent to single intersection point.
-     *   * If the turn is larger than `options.maxChamferDegrees`, the turn is constructed as a sequence of straight lines that are:
-     *      * outside the arc
-     *      * have uniform turn angle less than `options.maxChamferDegrees`
-     *      * each line segment (except first and last) touches the arc at its midpoint.
+     * * The construction will remove "some" local effects of features smaller than the offset distance, but will
+     * not detect self intersection among widely separated edges.
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/Offset
      * @param curves base curves.
      * @param offsetDistanceOrOptions offset distance (positive to left of curve, negative to right) or options object.
      */
     static constructCurveXYOffset(curves, offsetDistanceOrOptions) {
         const wrap = curves instanceof Loop_1.Loop;
-        const offsetOptions = OffsetOptions.create(offsetDistanceOrOptions);
+        const offsetOptions = OffsetOptions_1.OffsetOptions.create(offsetDistanceOrOptions);
         const simpleOffsets = [];
-        // setup pass: get simple offsets of each primitive
+        /** traverse primitives (children of curves) and create simple offsets of each primitive as an array */
         for (const c of curves.children) {
             const c1 = CurveChainWireOffsetContext.createSingleOffsetPrimitiveXY(c, offsetOptions);
             if (c1 === undefined) {
                 // bad .. maybe arc to inside?
             }
-            else if (c1 instanceof CurvePrimitive_1.CurvePrimitive)
+            else if (c1 instanceof CurvePrimitive_1.CurvePrimitive) {
                 simpleOffsets.push(c1);
+            }
             else if (Array.isArray(c1)) {
                 for (const c2 of c1) {
                     if (c2 instanceof CurvePrimitive_1.CurvePrimitive)
@@ -664,6 +572,7 @@ class CurveChainWireOffsetContext {
                 }
             }
         }
+        /** create joints between array elements to make offsets as a linked list (joint0) */
         let fragment0;
         let newJoint;
         let previousJoint;
@@ -682,8 +591,10 @@ class CurveChainWireOffsetContext {
         }
         if (joint0 && previousJoint && curves instanceof Loop_1.Loop)
             Joint.link(previousJoint, joint0);
+        /** annotateChain sets some of the joints attributes (including how to extend curves or fill the gap between curves) */
         const numOffset = simpleOffsets.length;
         Joint.annotateChain(joint0, offsetOptions.jointOptions, numOffset);
+        /** turn the Joint linked list into a CurveCollection. trimming is done in collectCurvesFromChain */
         const outputCurves = [];
         Joint.collectCurvesFromChain(joint0, outputCurves, numOffset);
         return RegionOps_1.RegionOps.createLoopPathOrBagOfCurves(outputCurves, wrap, true);