@itwin/core-geometry 4.1.0-dev.6 → 4.1.0-dev.63

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

@@ -19,8 +19,9 @@ import { Loop } from "../Loop";
 import { Path } from "../Path";
 import { RegionOps } from "../RegionOps";
 import { StrokeOptions } from "../StrokeOptions";
+// cspell:word CCWXY
 /**
- * Classification of contortions at a joint.
+ * Classification of how the joint is constructed.
  * @internal
  */
 var JointMode;
@@ -33,26 +34,44 @@ var JointMode;
     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.
+ * Control parameters for joint construction.
+ *   * Define a "joint" as the common point between adjacent segments of the input curve.
+ *   * Define the "turn angle" at a joint to be the angle in [0,pi] between the first derivatives (tangents) of
+ * the segments at the joint.
+ *   * When creating offsets, if an offset needs to do an "outside" turn, the first applicable construction is applied:
+ *   * If the turn angle is larger than `options.minArcDegrees`, a circular arc is constructed to offset the joint.
+ *   * If the turn angle is less than or equal to `options.maxChamferTurnDegrees`, extend curves along tangent to
+ * single intersection point (to create a sharp corner).
+ *   * If the turn angle is larger than `options.maxChamferDegrees`, the joint is offset with a line string whose edges:
+ *      * lie outside the arc that would have been created by the first construction
+ *      * have uniform turn angle less than `options.maxChamferDegrees`
+ *      * touch the arc at their midpoint (except first and last edge).
  * @public
  */
 export class JointOptions {
-    /** Construct 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.
+    constructor(leftOffsetDistance, minArcDegrees = 180, maxChamferDegrees = 90, preserveEllipticalArcs = false, allowSharpestCorners = false) {
+        /**
+         * Smallest arc to construct.
+         * * If this control angle is 180 degrees or more, arcs are never created.
          */
         this.minArcDegrees = 180.0;
+        /** Largest turn angle at which to construct a sharp corner, or largest turn angle in a multi-segment chamfer. */
         this.maxChamferTurnDegrees = 90;
+        /**
+         * Whether to remove the internal turn angle upper bound for sharp corner construction.
+         * * By default, a sharp corner is not created at a joint when the turn angle is too large, so as to avoid offsets whose
+         *  ranges blow up. Internally, this is implemented by applying an upper bound of 120 degrees to `maxChamferTurnDegrees`.
+         * * When `allowSharpestCorners` is true, this internal upper bound is removed, allowing sharp corners for turn angles
+         * up to `maxChamferTurnDegrees`.
+         * * Thus, if you know your input turn angles are no greater than `maxChamferTurnDegrees`, you can create an offset
+         * with sharp corners at each joint by setting `minArcDegrees` to 180 and `allowSharpestCorners` to true.
+         */
+        this.allowSharpestCorners = false;
         /** 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). */
@@ -61,10 +80,11 @@ export class JointOptions {
         this.minArcDegrees = minArcDegrees;
         this.maxChamferTurnDegrees = maxChamferDegrees;
         this.preserveEllipticalArcs = preserveEllipticalArcs;
+        this.allowSharpestCorners = allowSharpestCorners;
     }
     /** Return a deep clone. */
     clone() {
-        return new JointOptions(this.leftOffsetDistance, this.minArcDegrees, this.maxChamferTurnDegrees, this.preserveEllipticalArcs);
+        return new JointOptions(this.leftOffsetDistance, this.minArcDegrees, this.maxChamferTurnDegrees, this.preserveEllipticalArcs, this.allowSharpestCorners);
     }
     /** Copy values of input options */
     setFrom(other) {
@@ -72,6 +92,7 @@ export class JointOptions {
         this.minArcDegrees = other.minArcDegrees;
         this.maxChamferTurnDegrees = other.maxChamferTurnDegrees;
         this.preserveEllipticalArcs = other.preserveEllipticalArcs;
+        this.allowSharpestCorners = other.allowSharpestCorners;
     }
     /**
      * Parse a number or JointOptions up to JointOptions:
@@ -82,17 +103,22 @@ export class JointOptions {
     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. */
+    /**
+     /** 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. */
+    /** Return the number of corners needed to chamfer the given turn angle. */
     numChamferPoints(theta) {
         const degrees = Math.abs(theta.degrees);
-        const stepDegrees = Geometry.clamp(this.maxChamferTurnDegrees, 10, 120);
+        const minStepDegreesClamp = 10;
+        let maxStepDegreesClamp = 120;
+        if (this.allowSharpestCorners) {
+            maxStepDegreesClamp = this.maxChamferTurnDegrees;
+        }
+        const stepDegrees = Geometry.clamp(this.maxChamferTurnDegrees, minStepDegreesClamp, maxStepDegreesClamp);
         if (degrees <= stepDegrees)
             return 1;
         return Math.ceil(degrees / stepDegrees);
@@ -108,17 +134,41 @@ export class OffsetOptions {
         this.jointOptions = JointOptions.create(offsetDistanceOrOptions);
         this.strokeOptions = (strokeOptions !== undefined) ? strokeOptions : 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.
+    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 allowSharpestCorners() {
+        return this.jointOptions.allowSharpestCorners;
+    }
+    set allowSharpestCorners(value) {
+        this.jointOptions.allowSharpestCorners = 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. */
+     * * If an OffsetOptions is provided, a reference to it is returned.
+     */
     static create(offsetDistanceOrOptions) {
         if (offsetDistanceOrOptions instanceof OffsetOptions)
             return offsetDistanceOrOptions;
@@ -147,7 +197,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.isSameCoordinate(ray0.origin.distance(center), ray1.origin.distance(center))) {
             const angle = ray0.direction.angleToXY(ray1.direction);
@@ -192,6 +244,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) => {
@@ -203,7 +256,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());
@@ -243,6 +296,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;
@@ -257,13 +311,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);
@@ -271,7 +325,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) {
@@ -279,7 +333,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;
@@ -295,13 +349,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.closestApproachRay3dRay3d(ray0, ray1);
+            const intersection = Ray3d.closestApproachRay3dRay3d(ray0, ray1); // intersection of the 2 ray lines
             if (intersection.approachType === 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) {
@@ -309,13 +363,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.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;
@@ -335,19 +388,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.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;
@@ -356,42 +410,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 && this.curve1 instanceof 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.closestApproachRay3dRay3d(ray0, ray1);
+            else if (this.curve0 instanceof LineSegment3d && this.curve1 instanceof LineSegment3d) { // pair of lines
+                const ray0 = this.curve0.fractionToPointAndDerivative(0.0);
+                const ray1 = this.curve1.fractionToPointAndDerivative(0.0);
+                const intersection = Ray3d.closestApproachRay3dRay3d(ray0, ray1); // intersection of the 2 ray lines
                 if (intersection.approachType === 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.create(this.curve0.fractionToPoint(1.0), this.curve1.fractionToPoint(0.0));
                         this.fraction0 = 1.0;
@@ -399,15 +453,15 @@ class Joint {
                     }
                 }
             }
-            else { // generic pair of curves ...
+            else { // generic pair of curves
                 const intersections = 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);
                 }
             }
@@ -415,7 +469,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) {
@@ -450,8 +505,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);
@@ -507,9 +561,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) {
         Vector3d.createStartEnd(basePointA, basePointB, this._unitAlong);
@@ -522,13 +575,25 @@ 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) {
+        /**
+         * 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 = JointOptions.create(leftOffsetDistanceOrOptions);
         const numPoints = points.length;
         let fragment0 = PolygonWireOffsetContext.createOffsetSegment(points[0], points[1], options.leftOffsetDistance);
@@ -548,7 +613,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;
@@ -562,6 +629,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.create();
         Joint.collectStrokesFromChain(joint0, chain, numPoints);
         const n = chain.packedPoints.length;
@@ -585,14 +653,13 @@ export { PolygonWireOffsetContext };
  */
 export 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) {
@@ -604,7 +671,7 @@ export class CurveChainWireOffsetContext {
         return cp;
     }
     /**
-     * Create the offset of a single primitive.
+     * Create the offset of a single 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`
@@ -628,15 +695,10 @@ export class CurveChainWireOffsetContext {
     }
     /**
      * 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.
+     * * 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.
+     * * See [[JointOptions]] class doc for offset construction rules.
      * @param curves base curves.
      * @param offsetDistanceOrOptions offset distance (positive to left of curve, negative to right) or options object.
      */
@@ -644,14 +706,15 @@ export class CurveChainWireOffsetContext {
         const wrap = curves instanceof Loop;
         const offsetOptions = 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)
+            else if (c1 instanceof CurvePrimitive) {
                 simpleOffsets.push(c1);
+            }
             else if (Array.isArray(c1)) {
                 for (const c2 of c1) {
                     if (c2 instanceof CurvePrimitive)
@@ -659,6 +722,7 @@ export class CurveChainWireOffsetContext {
                 }
             }
         }
+        /** create joints between array elements to make offsets as a linked list (joint0) */
         let fragment0;
         let newJoint;
         let previousJoint;
@@ -677,8 +741,10 @@ export class CurveChainWireOffsetContext {
         }
         if (joint0 && previousJoint && curves instanceof 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.createLoopPathOrBagOfCurves(outputCurves, wrap, true);