@itwin/core-geometry 4.9.0-dev.9 → 4.10.0-dev.1

package/lib/esm/curve/internalContexts/EllipticalArcApproximationContext.d.ts

@@ -0,0 +1,211 @@
+import { AngleSweep } from "../../geometry3d/AngleSweep";
+import { Range1d } from "../../geometry3d/Range";
+import { Transform } from "../../geometry3d/Transform";
+import { Arc3d, EllipticalArcApproximationOptions } from "../Arc3d";
+import { CurveChain } from "../CurveCollection";
+import { CurveLocationDetailPair } from "../CurveLocationDetail";
+/**
+ * Structured data carrier used by the elliptical arc sampler.
+ * @internal
+*/
+export declare class QuadrantFractions {
+    private _quadrant;
+    private _fractions;
+    private _interpolateStartTangent;
+    private _interpolateEndTangent;
+    private _averageAdded;
+    private constructor();
+    /** Constructor, captures the array. */
+    static create(quadrant: 1 | 2 | 3 | 4, fractions?: number[], interpolateStartTangent?: boolean, interpolateEndTangent?: boolean): QuadrantFractions;
+    /**
+     * Quadrant of the full ellipse containing the samples.
+     * * Quadrants are labeled proceeding in counterclockwise angular sweeps of length pi/2 starting at vector0.
+     * * For example, Quadrant 1 starts at vector0 and ends at vector90, and Quadrant 4 ends at vector0.
+     * * For purposes of angle classification, quadrants are half-open intervals, closed at their start angle,
+     * as determined by the ellipse's sweep direction.
+     */
+    get quadrant(): 1 | 2 | 3 | 4;
+    /** Sample locations in this quadrant of the elliptical arc, as fractions of its sweep. */
+    get fractions(): number[];
+    set fractions(f: number[]);
+    /**
+     * Whether to interpolate the elliptical arc tangent at the first fraction.
+     * * If true (default), the first approximating arc is computed from the first two fractions and approximates the
+     * elliptical arc between the first and second fractions, interpolating both point and tangent at the first fraction,
+     * and point at the second fraction.
+     * * If false, the first approximating arc is computed from the first three fractions and approximates the
+     * elliptical arc between the second and third fractions, where it interpolates position only.
+     */
+    get interpolateStartTangent(): boolean;
+    set interpolateStartTangent(interpolate: boolean);
+    /**
+     * Whether to interpolate the elliptical arc tangent at the last fraction.
+     * * If true (default), the last approximating arc is computed from the last two fractions and approximates the
+     * elliptical arc between the penultimate and last fractions, interpolating point at the penultimate fraction, and
+     * both point and tangent at the last fraction.
+     * * If false, the last approximating arc is computed from the last three fractions and approximates the
+     * elliptical arc between the penultimate and last fractions, where it interpolates position only.
+     */
+    get interpolateEndTangent(): boolean;
+    set interpolateEndTangent(interpolate: boolean);
+    /**
+     * Whether the average of the first and last fractions was added to satisfy a minimum fractions array length of three.
+     * * There are always at least two fractions per quadrant, but three are needed to interpolate both end tangents
+     * with circular arcs.
+     * * This flag is set if a given sample method/arc yielded only two fractions, so their average was inserted in the
+     * fractions array to meet this minimum three-sample requirement.
+    */
+    get averageAdded(): boolean;
+    set averageAdded(added: boolean);
+    /**
+     * Compute quadrant data for the given angles.
+     * @param radians0 first radian angle
+     * @param radians1 second radian angle
+     * @return quadrant number and start/end radian angles for the quadrant that contains both input angles, or
+     * undefined if no such quadrant.
+     * * The returned sweep is always counterclockwise: angle0 < angle1.
+     */
+    static getQuadrantRadians(radians0: number, radians1: number): {
+        quadrant: 1 | 2 | 3 | 4;
+        angle0: number;
+        angle1: number;
+    } | undefined;
+    /** Compute the fractional range of Quadrant 1 for the given sweep. */
+    static getQ1FractionalRange(sweep: AngleSweep): Range1d;
+    /** Reverse the fractions array and flags. */
+    reverse(): void;
+}
+/**
+ * Base class specifying callbacks for processing samples of an elliptical arc.
+ * @internal
+ */
+declare class QuadrantFractionsProcessor {
+    /**
+     * Announce the beginning of processing for quadrant `q`.
+     * @param _reversed whether `q.reverse()` was invoked before this call for symmetry reasons. If so, arcs will be
+     * announced in the opposite order and with the opposite orientation.
+     * @return whether to process `q`
+     */
+    announceQuadrantBegin(_q: QuadrantFractions, _reversed: boolean): boolean;
+    /**
+     * Retrieve the fraction preceding the input fraction in process order.
+     * * This optional callback facilitates processors like [[AdaptiveSubdivisionQ1ErrorProcessor]] whose implementation
+     * of [[announceArc]] depends upon the result of the previous invocation of [[announceArc]].
+     * @param f0 fraction to look up
+     * @return fraction preceding f0 in process order, or undefined if no such fraction
+     */
+    getPreviousFraction?(f0: number): number | undefined;
+    /**
+     * Announce a circular arc approximating the elliptical arc E between the given fractions.
+     * * The given fractions are different. If `announceQuadrantBegin` was invoked with `reversed === false` then
+     * `fPrev < f0 < f1`; otherwise, `fPrev > f0 > f1`.
+     * @param _arc circular arc that interpolates E at f0 and f1. Processor can capture `arc`; it is unused afterwards.
+     * @param _fPrev fractional parameter of E used to define the 3-point parent circle through the points at `fPrev`,
+     * `f0`, and `f1` from which `arc` was constructed. If undefined, `arc` was generated from the circle defined by
+     * the points at `f0` and `f1` and one of their tangents.
+     * @param _f0 fractional parameter of E at which point `arc` starts
+     * @param _f1 fractional parameter of E at which point `arc` ends
+     */
+    announceArc(_arc: Arc3d, _fPrev: number | undefined, _f0: number, _f1: number): void;
+    /**
+     * Announce the end of processing for quadrant `q`.
+     * @param _reversed whether `q.reverse()` was invoked before processing (see [[announceQuadrantBegin]]). If so,
+     * after this call `q.reverse()` is invoked again.
+     */
+    announceQuadrantEnd(_q: QuadrantFractions, _reversed: boolean): void;
+}
+/**
+ * Context for sampling a non-circular Arc3d and for constructing an approximation to it based on interpolation
+ * of the samples.
+ * * [[EllipticalArcApproximationContext.constructCircularArcChainApproximation]] constructs a `CurveChain`
+ * approximation consisting of circular arcs.
+ * * Various sample methods are supported, cf. [[EllipticalArcApproximationOptions]].
+ * @internal
+ */
+export declare class EllipticalArcApproximationContext {
+    private _ellipticalArc;
+    private _localToWorld;
+    private _isValidEllipticalArc;
+    private static workPt0;
+    private static workPt1;
+    private static workPt2;
+    private static workRay;
+    /** Constructor, captures input */
+    private constructor();
+    /** Constructor, clones input. */
+    static create(ellipticalArc: Arc3d): EllipticalArcApproximationContext;
+    /**
+     * The arc to be sampled.
+     * * Its axes are forced to be perpendicular.
+     * * It is stored in world coordinates.
+     */
+    get ellipticalArc(): Arc3d;
+    /**
+     * The rigid transformation that maps `ellipticalArc` from local coordinates to world coordinates.
+     * * In local coordinates, the arc center lies at the origin and its (perpendicular) axes of symmetry lie along
+     * the positive x- and y-axes.
+     */
+    get localToWorld(): Transform;
+    /**
+     * Whether the elliptical arc is amenable to sampling.
+     * * The arc is valid if it is non-circular, has nonzero sweep, and has positive radii (nonsingular matrix).
+     */
+    get isValidEllipticalArc(): boolean;
+    /**
+     * Create a clone of the context's arc in local coordinates.
+     * @param fullSweep Optionally set full sweep on the returned local arc. Start angle is preserved.
+     * @returns local arc, or undefined if the arc is invalid
+     */
+    cloneLocalArc(fullSweep?: boolean): Arc3d | undefined;
+    /**
+     * Process structured sample data for the given elliptical arc.
+     * * Circular arcs are announced to the processor for each sample interval in each quadrant.
+     * * Each quadrant is processed separately to allow the elliptical arc's axis points and tangents to be interpolated.
+     * * A 2-point plus tangent construction is used to create the first and last circular arc in each quadrant.
+     * * Symmetry of the announced circular arcs matching that of a multi-quadrant spanning elliptical arc is ensured by
+     * processing the samples consistently, starting along the elliptical arc's major axis in each quadrant.
+     * @param ellipticalArc source arc to approximate
+     * @param quadrants structured samples, may be temporarily reversed for symmetry
+     * @param processor callbacks for handling the constructed arcs
+     * @internal
+    */
+    static processQuadrantFractions(ellipticalArc: Arc3d, quadrants: QuadrantFractions[], processor: QuadrantFractionsProcessor): void;
+    /**
+     * Compute the maximum error of the circular arc chain approximation determined by the given samples.
+     * * This is measured by the longest perpendicular between the elliptical arc and its approximation.
+     * @param samples structured sample data from the instance's elliptical arc.
+     * @return details of the perpendicular measuring the max approximation error, or undefined if no such perpendicular.
+     * For each of `detailA` and `detailB`:
+     * * `point` is the end of the perpendicular on each curve
+     * * `fraction` is the curve parameter of the point
+     * * `a` is the distance between the points.
+     * @internal
+     */
+    computeApproximationError(samples: QuadrantFractions[]): CurveLocationDetailPair | undefined;
+    /**
+     * Compute samples for the elliptical arc as fraction parameters.
+     * * This method houses the sampling framework for all sampling methods, which are customized via implementations
+     * of the [[EllipticalArcSampler]] interface.
+     * * Note that the returned samples are fractions in the parameterization of the context's arc (whose axes have been
+     * forced to be perpendicular), not the input arc passed into the context's constructor.
+     * @param options options that determine how the elliptical arc is sampled.
+     * @param structuredOutput flag indicating output format as follows:
+     * * If false (default), return all fractions in one sorted (increasing), deduplicated array (a full ellipse includes
+     * both 0 and 1).
+     * * If true, fractions are assembled by quadrants:
+     *   * Each [[QuadrantFractions]] object holds at least three sorted (increasing), deduplicated fractions in a
+     * specified quadrant of the arc.
+     *   * If only two fractions would be computed for a given `QuadrantFractions`, their midpoint is inserted to enable
+     * tangent interpolation at both ends. Such a quadrant `q` is marked with `q.averageAdded = true`.
+     *   * The `QuadrantFractions` objects themselves are sorted by increasing order of the fractions they contain.
+     *   * If the arc sweep spans adjacent quadrants, the fraction bordering the quadrants appears in both `QuadrantFractions`.
+     *   * If the arc starts and ends in the same quadrant, two `QuadrantFractions` objects can be returned.
+     *   * This means there are between 1 and 5 objects in the `QuadrantFractions` array.
+     * @internal
+     */
+    computeSampleFractions(options: EllipticalArcApproximationOptions, structuredOutput?: boolean): QuadrantFractions[] | number[];
+    /** Construct a circular arc chain approximation to the elliptical arc. */
+    constructCircularArcChainApproximation(options?: EllipticalArcApproximationOptions): CurveChain | undefined;
+}
+export {};
+//# sourceMappingURL=EllipticalArcApproximationContext.d.ts.map

package/lib/esm/curve/internalContexts/EllipticalArcApproximationContext.d.ts.map

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