@itwin/core-geometry 4.1.0-dev.24 → 4.1.0-dev.26

package/lib/cjs/curve/internalContexts/PolygonOffsetContext.d.ts

@@ -3,36 +3,54 @@
  */
 import { Angle } from "../../geometry3d/Angle";
 import { Point3d } from "../../geometry3d/Point3dVector3d";
-import { CurveCollection } from "../CurveCollection";
+import { CurveChain, CurveCollection } from "../CurveCollection";
 import { CurvePrimitive } from "../CurvePrimitive";
 import { Loop } from "../Loop";
 import { Path } from "../Path";
 import { StrokeOptions } from "../StrokeOptions";
 /**
- * * 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 declare class JointOptions {
-    /** smallest arc to construct.
-     * * If this control angle is large, arcs are never created.
+    /**
+     * Smallest arc to construct.
+     * * If this control angle is 180 degrees or more, arcs are never created.
      */
     minArcDegrees: number;
+    /** Largest turn angle at which to construct a sharp corner, or largest turn angle in a multi-segment chamfer. */
     maxChamferTurnDegrees: number;
+    /**
+     * 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.
+     */
+    allowSharpestCorners: boolean;
     /** Offset distance, positive to left of base curve. */
     leftOffsetDistance: number;
     /** Whether to offset elliptical arcs as elliptical arcs (true) or as B-spline curves (false, default). */
     preserveEllipticalArcs: boolean;
-    /** Construct JointOptions.
+    /**
+     * Construct JointOptions.
      * * leftOffsetDistance is required
      * * minArcDegrees and maxChamferDegrees are optional.
      */
-    constructor(leftOffsetDistance: number, minArcDegrees?: number, maxChamferDegrees?: number, preserveEllipticalArcs?: boolean);
+    constructor(leftOffsetDistance: number, minArcDegrees?: number, maxChamferDegrees?: number, preserveEllipticalArcs?: boolean, allowSharpestCorners?: boolean);
     /** Return a deep clone. */
     clone(): JointOptions;
     /** Copy values of input options */
@@ -44,9 +62,10 @@ export declare class JointOptions {
      * @param leftOffsetDistanceOrOptions
      */
     static create(leftOffsetDistanceOrOptions: number | JointOptions): JointOptions;
-    /** 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: Angle): boolean;
-    /** 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: Angle): number;
 }
 /**
@@ -64,13 +83,17 @@ export declare class OffsetOptions {
     set minArcDegrees(value: number);
     get maxChamferTurnDegrees(): number;
     set maxChamferTurnDegrees(value: number);
+    get allowSharpestCorners(): boolean;
+    set allowSharpestCorners(value: boolean);
     get leftOffsetDistance(): number;
     set leftOffsetDistance(value: number);
     get preserveEllipticalArcs(): boolean;
     set preserveEllipticalArcs(value: boolean);
-    /** Convert variant input into OffsetOptions.
+    /**
+     * 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: number | JointOptions | OffsetOptions): OffsetOptions;
     /** Convert variant input into offset distance */
     static getOffsetDistance(offsetDistanceOrOptions: number | JointOptions | OffsetOptions): number;
@@ -82,7 +105,7 @@ export declare class OffsetOptions {
  * @internal
  */
 export declare class PolygonWireOffsetContext {
-    /** construct a context. */
+    /** Construct a context. */
     constructor();
     private static _unitAlong;
     private static _unitPerp;
@@ -90,13 +113,17 @@ export declare class PolygonWireOffsetContext {
     private static _offsetB;
     private static createOffsetSegment;
     /**
-     * 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: Point3d[], wrap: boolean, leftOffsetDistanceOrOptions: number | JointOptions): CurveCollection | undefined;
+    constructPolygonWireXYOffset(points: Point3d[], wrap: boolean, leftOffsetDistanceOrOptions: number | JointOptions): CurveChain | undefined;
 }
 /**
  * Context for building a wire offset from a Path or Loop of CurvePrimitives
@@ -107,14 +134,14 @@ export declare class CurveChainWireOffsetContext {
     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: CurvePrimitive | undefined, startPoint: Point3d | undefined, endPoint: Point3d | undefined): CurvePrimitive | undefined;
     /**
-     * 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`
@@ -124,15 +151,10 @@ export declare class CurveChainWireOffsetContext {
     static createSingleOffsetPrimitiveXY(g: CurvePrimitive, offsetDistanceOrOptions: number | OffsetOptions): CurvePrimitive | CurvePrimitive[] | undefined;
     /**
      * 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.
      */

package/lib/cjs/curve/internalContexts/PolygonOffsetContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PolygonOffsetContext.d.ts","sourceRoot":"","sources":["../../../../src/curve/internalContexts/PolygonOffsetContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PolygonOffsetContext.d.ts","sourceRoot":"","sources":["../../../../src/curve/internalContexts/PolygonOffsetContext.ts"],"names":[],"mappings":"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"}