plotboilerplate 1.28.0 → 1.29.0

package/src/_esm/src/ts/BezierPath.d.ts

@@ -1,610 +0,0 @@
-/**
- * @author Ikaros Kappler
- * @date 2013-08-19
- * @modified 2018-08-16 Added closure. Removed the 'IKRS' wrapper.
- * @modified 2018-11-20 Added circular auto-adjustment.
- * @modified 2018-11-25 Added the point constants to the BezierPath class itself.
- * @modified 2018-11-28 Added the locateCurveByStartPoint() function.
- * @modified 2018-12-04 Added the toSVGString() function.
- * @modified 2019-03-23 Added JSDoc tags.
- * @modified 2019-03-23 Changed the fuctions getPoint and getPointAt to match semantics in the Line class.
- * @modified 2019-11-18 Fixed the clone function: adjustCircular attribute was not cloned.
- * @modified 2019-12-02 Removed some excessive comments.
- * @modified 2019-12-04 Fixed the missing obtainHandleLengths behavior in the adjustNeightbourControlPoint function.
- * @modified 2020-02-06 Added function locateCurveByEndPoint( Vertex ).
- * @modified 2020-02-11 Added 'return this' to the scale(Vertex,number) and to the translate(Vertex) function.
- * @modified 2020-03-24 Ported this class from vanilla-JS to Typescript.
- * @modified 2020-06-03 Made the private helper function _locateUIndex to a private function.
- * @modified 2020-06-03 Added the getBounds() function.
- * @modified 2020-07-14 Changed the moveCurvePoint(...,Vertex) to moveCurvePoint(...,XYCoords).
- * @modified 2020-07-24 Added the getClosestT(Vertex) function.
- * @modified 2020-12-29 Constructor is now private (no explicit use intended).
- * @modified 2021-05-25 Added BezierPath.fromReducedList( Array<number> ).
- * @modified 2022-01-31 Added `BezierPath.getEvenDistributionVertices(number)`.
- * @modified 2022-02-02 Added the `destroy` method.
- * @modified 2022-02-02 Cleared the `toSVGString` function (deprecated). Use `drawutilssvg` instead.
- * @modified 2023-10-06 Adding the `BezierPath.toPathPoints()` method.
- * @modified 2023-10-07 Adding the `BezierPath.fromCurve(CubicBezierCurve)` static function.
- * @modified 2025-04-09 Added the `BezierPath.move` method to match the convention – which just calls `translate`.
- * @modified 2025-04-09 Modified the `BezierPath.translate` method: chaning parameter `Vertex` to more generalized `XYCoords`.
- * @modified 2025-04-14 Class `BezierPath` is now implementing interface `Intersectable`.
- * @version 2.7.0
- *
- * @file BezierPath
- * @public
- **/
-import { Bounds } from "./Bounds";
-import { CubicBezierCurve } from "./CubicBezierCurve";
-import { Vector } from "./Vector";
-import { VertTuple } from "./VertTuple";
-import { Vertex } from "./Vertex";
-import { XYCoords, SVGSerializable, UID, Intersectable, IBounded } from "./interfaces";
-/**
- * @classdesc A BezierPath class.
- *
- * This was refactored from an older project.
- *
- * @requires Bounds
- * @requires Vertex
- * @requires CubicBezierCurve
- * @requires XYCoords
- * @requires SVGSerializable
- * @requires UID
- * @requires UIDGenerator
- **/
-export declare class BezierPath implements IBounded, Intersectable, SVGSerializable {
-    /**
-     * Required to generate proper CSS classes and other class related IDs.
-     **/
-    readonly className: string;
-    /**
-     * The UID of this drawable object.
-     *
-     * @member {UID}
-     * @memberof BezierCurve
-     * @instance
-     * @readonly
-     */
-    readonly uid: UID;
-    /**
-     * @member {Array<Vertex>}
-     * @memberof BezierPath
-     * @type {Array<Vertex>}
-     * @instance
-     */
-    pathPoints: Array<Vertex>;
-    /**
-     * @member {number}
-     * @memberof BezierPath
-     * @type {number}
-     * @instance
-     */
-    totalArcLength: number;
-    /**
-     * Set this flag to true if you want the first point and
-     * last point of the path to be auto adjusted, too.
-     *
-     * @member {number}
-     * @memberof BezierPath
-     * @type {number}
-     * @instance
-     */
-    adjustCircular: boolean;
-    /**
-     * @member {Array<CubicBezierCurve>}
-     * @memberof BezierPath
-     * @type {Array<CubicBezierCurve>}
-     * @instance
-     */
-    bezierCurves: Array<CubicBezierCurve>;
-    /**
-     * @member {boolean}
-     * @memberof BezierPath
-     * @type {boolean}
-     * @instance
-     */
-    isDestroyed: boolean;
-    /** @constant {number} */
-    static START_POINT: number;
-    /** @constant {number} */
-    static START_CONTROL_POINT: number;
-    /** @constant {number} */
-    static END_CONTROL_POINT: number;
-    /** @constant {number} */
-    static END_POINT: number;
-    /** @constant {number} */
-    START_POINT: number;
-    /** @constant {number} */
-    START_CONTROL_POINT: number;
-    /** @constant {number} */
-    END_CONTROL_POINT: number;
-    /** @constant {number} */
-    END_POINT: number;
-    /**
-     * The constructor.<br>
-     * <br>
-     * This constructor expects a sequence of path points and will approximate
-     * the location of control points by picking some between the points.<br>
-     * You should consider just constructing empty paths and then add more curves later using
-     * the addCurve() function.
-     *
-     * @constructor
-     * @name BezierPath
-     * @param {Vertex[]} pathPoints - An array of path vertices (no control points).
-     **/
-    private constructor();
-    /**
-     * Add a cubic bezier curve to the end of this path.
-     *
-     * @method addCurve
-     * @param {CubicBezierCurve} curve - The curve to be added to the end of the path.
-     * @instance
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    addCurve(curve: CubicBezierCurve): void;
-    /**
-     * Locate the curve with the given start point (function returns the index).
-     *
-     * @method locateCurveByStartPoint
-     * @param {Vertex} point - The (curve start-) point to look for.
-     * @instance
-     * @memberof BezierPath
-     * @return {number} The curve index or -1 if curve (start-) point not found
-     **/
-    locateCurveByStartPoint(point: Vertex): number;
-    /**
-     * Locate the curve with the given end point (function returns the index).
-     *
-     * @method locateCurveByEndPoint
-     * @param {Vertex} point - The (curve end-) point to look for.
-     * @instance
-     * @memberof BezierPath
-     * @return {number} The curve index or -1 if curve (end-) point not found
-     **/
-    locateCurveByEndPoint(point: Vertex): number;
-    /**
-     * Locate the curve with the given start point (function returns the index).
-     *
-     * @method locateCurveByStartControlPoint
-     * @param {Vertex} point - The (curve endt-) point to look for.
-     * @instance
-     * @memberof BezierPath
-     * @return {number} The curve index or -1 if curve (end-) point not found
-     **/
-    locateCurveByStartControlPoint(point: Vertex): number;
-    locateCurveByEndControlPoint(point: Vertex): number;
-    /**
-     * Get the total length of this path.<br>
-     * <br>
-     * Note that the returned value comes from the curve buffer. Unregistered changes
-     * to the curve points will result in invalid path length values.
-     *
-     * @method getLength
-     * @instance
-     * @memberof BezierPath
-     * @return {number} The (buffered) length of the path.
-     **/
-    getLength(): number;
-    /**
-     * This function is internally called whenever the curve or path configuration
-     * changed. It updates the attribute that stores the path length information.<br>
-     * <br>
-     * If you perform any unregistered changes to the curve points you should call
-     * this function afterwards to update the curve buffer. Not updating may
-     * result in unexpected behavior.
-     *
-     * @method updateArcLengths
-     * @instance
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    updateArcLengths(): void;
-    /**
-     * Get the number of curves in this path.
-     *
-     * @method getCurveCount
-     * @instance
-     * @memberof BezierPath
-     * @return {number} The number of curves in this path.
-     **/
-    getCurveCount(): number;
-    /**
-     * Get the cubic bezier curve at the given index.
-     *
-     * @method getCurveAt
-     * @param {number} index - The curve index from 0 to getCurveCount()-1.
-     * @instance
-     * @memberof BezierPath
-     * @return {CubicBezierCurve} The curve at the specified index.
-     **/
-    getCurveAt(curveIndex: number): CubicBezierCurve;
-    /**
-     * Move the whole bezier path by the given (x,y)-amount.
-     *
-     * @method translate
-     * @param {XYCoords} amount - The amount to be added (amount.x and amount.y)
-     *                          to each vertex of the curve.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} this for chaining
-     **/
-    translate(amount: XYCoords): BezierPath;
-    /**
-     * Move the whole bezier path by the given (x,y)-amount.
-     *
-     * @method move
-     * @param {XYCoords} amount - The amount to be added (amount.x and amount.y)
-     *                          to each vertex of the curve.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} this for chaining
-     **/
-    move(amount: XYCoords): BezierPath;
-    /**
-     * Scale the whole bezier path by the given uniform factor.
-     *
-     * @method scale
-     * @param {Vertex} anchor - The scale origin to scale from.
-     * @param {number} scaleFactor - The scalar to be multiplied with.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} this for chaining.
-     **/
-    scale(anchor: Vertex, scaleFactor: number): BezierPath;
-    /**
-     * Scale the whole bezier path by the given (x,y)-factors.
-     *
-     * @method scale
-     * @param {Vertex} anchor - The scale origin to scale from.
-     * @param {number} amount - The scalar to be multiplied with.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} this for chaining.
-     **/
-    scaleXY(scaleFactors: XYCoords, anchor?: XYCoords): BezierPath;
-    /**
-     * Rotate the whole bezier path around a point..
-     *
-     * @method rotate
-     * @param {Vertex} angle  - The angle to rotate this path by.
-     * @param {Vertex} center - The rotation center.
-     * @instance
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    rotate(angle: number, center: Vertex): void;
-    /**
-     * Get the 't' position on this curve with the minimal distance to point p.
-     *
-     * @param {Vertex} p - The point to find the closest curve point for.
-     * @return {number} A value t with 0.0 <= t <= 1.0.
-     **/
-    getClosestT(p: Vertex): number;
-    /**
-     * Get the point on the bézier path at the given relative path location.
-     *
-     * @method getPoint
-     * @param {number} u - The relative path position: <pre>0 <= u <= this.getLength()</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The point at the relative path position.
-     **/
-    getPoint(u: number): Vertex;
-    /**
-     * Get the point on the bézier path at the given path fraction.
-     *
-     * @method getPointAt
-     * @param {number} t - The absolute path position: <pre>0.0 <= t <= 1.0</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The point at the absolute path position.
-     **/
-    getPointAt(t: number): Vertex;
-    /**
-     * Get the tangent of the bézier path at the given path fraction.<br>
-     * <br>
-     * Note that the returned vector is not normalized.
-     *
-     * @method getTangentAt
-     * @param {number} t - The absolute path position: <pre>0.0 <= t <= 1.0</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The tangent vector at the absolute path position.
-     **/
-    getTangentAt(t: number): Vertex;
-    /**
-     *  Get the tangent of the bézier path at the given path location.<br>
-     * <br>
-     * Note that the returned vector is not normalized.
-     *
-     * @method getTangent
-     * @param {number} u - The relative path position: <pre>0 <= u <= getLength()</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The tangent vector at the relative path position.
-     **/
-    getTangent(u: number): Vertex;
-    /**
-     * Get the perpendicular of the bézier path at the given absolute path location (fraction).<br>
-     * <br>
-     * Note that the returned vector is not normalized.
-     *
-     * @method getPerpendicularAt
-     * @param {number} t - The absolute path position: <pre>0.0 <= t <= 1.0</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The perpendicluar vector at the absolute path position.
-     **/
-    getPerpendicularAt(t: number): Vertex;
-    /**
-     * Get the perpendicular of the bézier path at the given relative path location.<br>
-     * <br>
-     * Note that the returned vector is not normalized.
-     *
-     * @method getPerpendicular
-     * @param {number} u - The relative path position: <pre>0 <= u <= getLength()</pre>
-     * @instance
-     * @memberof BezierPath
-     * @return {Vertex} The perpendicluar vector at the relative path position.
-     **/
-    getPerpendicular(u: number): Vertex;
-    /**
-     * Get all line intersections with this shape.
-     *
-     * This method returns all intersections (as vertices) with this shape. The returned array of vertices is in no specific order.
-     *
-     * @param {VertTuple} line - The line to find intersections with.
-     * @param {boolean} inVectorBoundsOnly - If set to true only intersecion points on the passed vector are returned (located strictly between start and end vertex).
-     * @returns {Array<Vertex>} - An array of all intersections with the shape's outline.
-     */
-    lineIntersections(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vertex>;
-    /**
-     * Get all line intersections of this polygon and their tangents along the shape.
-     *
-     * This method returns all intersection tangents (as vectors) with this shape. The returned array of vectors is in no specific order.
-     *
-     * @param line
-     * @param lineIntersectionTangents
-     * @returns
-     */
-    lineIntersectionTangents(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vector>;
-    /**
-     * This is a helper function to locate the curve index for a given
-     * absolute path position u.
-     *
-     * I decided to put this into privat scope as it is really specific. Maybe
-     * put this into a utils wrapper.
-     *
-     * Returns:
-     * - {number} i - the index of the containing curve.
-     * - {number} uPart - the absolute curve length sum (length from the beginning to u, should equal u itself).
-     * - {number} uBefore - the absolute curve length for all segments _before_ the matched curve (usually uBefore <= uPart).
-     **/
-    private static _locateUIndex;
-    /**
-     * Get a specific sub path from this path. The start and end position are specified by
-     * ratio number in [0..1].
-     *
-     * 0.0 is at the beginning of the path.
-     * 1.0 is at the end of the path.
-     *
-     * Values below 0 or beyond 1 are cropped down to the [0..1] interval.
-     *
-     * startT > endT is allowed, the returned sub path will have inverse direction then.
-     *
-     * @method getSubPathAt
-     * @param {number} startT - The start position of the sub path.
-     * @param {number} endT - The end position of the sub path.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} The desired sub path in the bounds [startT..endT].
-     **/
-    getSubPathAt(startT: number, endT: number): BezierPath;
-    /**
-     * This function moves the addressed curve point (or control point) with
-     * keeping up the path's curve integrity.<br>
-     * <br>
-     * Thus is done by moving neighbour- and control- points as needed.
-     *
-     * @method moveCurvePoint
-     * @param {number} curveIndex - The curve index to move a point from.
-     * @param {number} pointID - One of the curve's four point IDs (START_POINT,
-     *                           START_CONTROL_POINT, END_CONTRO_POINT or END_POINT).
-     * @param {XYCoords} moveAmount - The amount to move the addressed vertex by.
-     * @instance
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    moveCurvePoint(curveIndex: number, pointID: number, moveAmount: XYCoords): void;
-    /**
-     * This helper function adjusts the given point's predecessor's control point.
-     *
-     * @method adjustPredecessorControlPoint
-     * @param {number} curveIndex - The curve index to move a point from.
-     * @param {boolean} obtainHandleLength - Moves the point with keeping the original handle length.
-     * @param {boolean} updateArcLength - The amount to move the addressed vertex by.
-     * @instance
-     * @private
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    adjustPredecessorControlPoint(curveIndex: number, obtainHandleLength: boolean, updateArcLengths: boolean): void;
-    /**
-     * This helper function adjusts the given point's successor's control point.
-     *
-     * @method adjustSuccessorControlPoint
-     * @param {number} curveIndex - The curve index to move a point from.
-     * @param {boolean} obtainHandleLength - Moves the point with keeping the original handle length.
-     * @param {boolean} updateArcLength - The amount to move the addressed vertex by.
-     * @instance
-     * @private
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    adjustSuccessorControlPoint(curveIndex: number, obtainHandleLength: boolean, updateArcLengths: boolean): void;
-    /**
-     * This helper function adjusts the given point's successor's control point.
-     *
-     * @method adjustNeighbourControlPoint
-     * @param {CubicBezierCurve} mainCurve
-     * @param {CubicBezierCurve} neighbourCurve
-     * @param {Vertex} mainPoint
-     * @param {Vertex} mainControlPoint
-     * @param {Vertex} neighbourPoint
-     * @param {Vertex} neighbourControlPoint
-     * @param {boolean} obtainHandleLengths
-     * @param {boolean} updateArcLengths
-     * @instance
-     * @private
-     * @memberof BezierPath
-     * @return {void}
-     **/
-    private static adjustNeighbourControlPoint;
-    /**
-     * Get the bounds of this Bézier path.
-     *
-     * Note the the curves' underlyung segment buffers are used to determine the bounds. The more
-     * elements the segment buffers have, the more precise the returned bounds will be.
-     *
-     * @return {Bounds} The bounds of this Bézier path.
-     **/
-    getBounds(): Bounds;
-    /**
-     * Get n 'equally' distributed vertices along this Bézier path.
-     *
-     * As the changing curvature of the B slines makes prediction of distances difficult, the
-     * returned vertices' distances are only relatively equal:
-     *  - the distance grows where curvature is large.
-     *  - the distance shrinks where curvature is small.
-     *
-     * Only the distance mean of all consecutive is 1/n-th of the total arc length.
-     *
-     * Usually this approximation is good enough for most use cases.
-     *
-     * @param {number} pointCount - (must be at least 2) The number of desired points (start and end point included).
-     * @return {Array<Vertex>}
-     */
-    getEvenDistributionVertices(pointCount: number): Array<Vertex>;
-    /**
-     * Clone this BezierPath (deep clone).
-     *
-     * @method clone
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath}
-     **/
-    clone(): BezierPath;
-    /**
-     * Compare this and the passed Bézier path.
-     *
-     * @method equals
-     * @param {BezierPath} path - The pass to compare with.
-     * @instance
-     * @memberof BezierPath
-     * @return {boolean}
-     **/
-    equals(path: BezierPath): boolean;
-    /**
-     * This function should invalidate any installed listeners and invalidate this object.
-     * After calling this function the object might not hold valid data any more and
-     * should not be used.
-     *
-     * @method destroy
-     * @instance
-     * @memberof BezierPath
-     */
-    destroy(): void;
-    /**
-     * Convert this path to an array of path points that can be drawn by the default DrawLib
-     * implementations.
-     *
-     * @method toPathPoints
-     * @instance
-     * @memberof BezierPath
-     * @return {Array<XYCoords>}
-     */
-    toPathPoints(): Array<XYCoords>;
-    /**
-     * Create a JSON string representation of this bézier curve.
-     *
-     * @method toJSON
-     * @param {boolean} prettyFormat - If true then the function will add line breaks.
-     * @instance
-     * @memberof BezierPath
-     * @return {string} The JSON string.
-     **/
-    toJSON(prettyFormat: boolean): string;
-    /**
-     * Parse a BezierPath from the given JSON string.
-     *
-     * @method fromJSON
-     * @param {string} jsonString - The string with the JSON data.
-     * @throw An error if the string is not JSON or does not contain a bezier path object.
-     * @static
-     * @memberof BezierPath
-     * @return {BezierPath} The parsed bezier path instance.
-     **/
-    static fromJSON(jsonString: string): BezierPath;
-    /**
-     * Construct a new path with a single curve. Adding more curves is always possible.
-     *
-     * @method fromCurve
-     * @param {CubicBezierCurve} curve - The curve to construct a new path from.
-     * @static
-     * @memberof BezierPath
-     * @return {BezierPath} The constructed bezier path instance.
-     */
-    static fromCurve(curve: CubicBezierCurve): BezierPath;
-    /**
-     * Create a BezierPath instance from the given array.
-     *
-     * @method fromArray
-     * @param {Vertex[][]} arr - A two-dimensional array containing the bezier path vertices.
-     * @throw An error if the array does not contain proper bezier path data.
-     * @static
-     * @memberof BezierPath
-     * @return {BezierPath} The bezier path instance retrieved from the array data.
-     **/
-    static fromArray(obj: any): BezierPath;
-    /**
-     * This function converts the bezier path into a string containing
-     * integer values only.
-     * The points' float values are rounded to 1 digit after the comma.
-     *
-     * The returned string represents a JSON array (with leading '[' and
-     * trailing ']', the separator is ',').
-     *
-     * @method toReducedListRepresentation
-     * @param {number} digits - The number of digits to be used after the comma '.'.
-     * @instance
-     * @memberof BezierPath
-     * @return {string} The reduced list representation of this path.
-     **/
-    toReducedListRepresentation(digits: number): string;
-    /**
-     * Parse a BezierPath instance from the reduced list representation.<br>
-     * <br>
-     * The passed string must represent a JSON array containing numbers only.
-     *
-     * @method fromReducedListRepresentation
-     * @param {string} listJSON - The number of digits to be used after the floating point.
-     * @throw An error if the string is malformed.
-     * @instance
-     * @memberof BezierPath
-     * @return {BezierPath} The bezier path instance retrieved from the string.
-     **/
-    static fromReducedListRepresentation(listJSON: string, adjustCircular?: boolean): BezierPath;
-    /**
-     * Convert a reduced list representation (array of numeric coordinates) to a BezierPath instance.
-     *
-     * The array's length must be 6*n + 2:
-     *  - [sx, sy,  scx, scy,  ecx, ecy, ... , ex,  ey ]
-     *     |                               |   |     |
-     *     +--- sequence of curves --------+   +-end-+
-     *
-     * @param {number[]} pointArray
-     * @returns BezierPath
-     */
-    static fromReducedList(pointArray: Array<number>, adjustCircular?: boolean): BezierPath;
-}