figureone 0.15.10 → 1.0.0

package/types/js/tools/geometry/Line.d.ts

@@ -0,0 +1,314 @@
+import { Point } from './Point';
+import type { TypeParsablePoint } from './Point';
+/**
+ * Line definition object.
+ *
+ * Combinations that can be used are:
+ * - p1, p2, ends
+ * - p1, length, angle, ends (for 2D lines)
+ * - p1, length, phi, theta, ends (for 3D lines)
+ * - p1, length, direction, ends
+ *
+ * @property {TypeParsablePoint} [p1] first point of line
+ * @property {TypeParsablePoint} [p2] second point of line
+ * @property {number} [length] length of line
+ * @property {number} [theta] theta (elevation) angle of line in spherical
+ * coordinates
+ * @property {number} [phi] phi (azimuth) angle of line in spherical coordinates
+ * @property {number} [angle] angle of line in 2D definition
+ * @property {TypeParsablePoint | number} [direction] direction vector of line
+ * from p1
+ * @property {0 | 1 | 2} [ends]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_LineDefinition = {
+    p1?: TypeParsablePoint;
+    p2?: TypeParsablePoint;
+    length?: number;
+    theta?: number;
+    angle?: number;
+    phi?: number;
+    direction?: TypeParsablePoint | number;
+    ends?: 0 | 1 | 2;
+};
+/**
+ * Recorder state definition of a {@link Line} that represents the two end
+ * points of the line and the number of finite ends.
+ *
+ * `{ f1Type: 'l', state: [[number, number, number], [number, number, number], 2 | 1 | 0] }`
+ * @group Misc Geometry
+ */
+type TypeF1DefLine = {
+    f1Type: 'l';
+    state: [[number, number, number], [number, number, number], 2 | 1 | 0];
+};
+/**
+ * Line intersect result.
+ *
+ * @property {Point} [intersect] the intersection point. Will be undefined if
+ * there is no intersection
+ * @property {boolean} collinear `true` if the lines are collinear
+ * @property {boolean} onLines `true` if the intersection point is on both lines
+ * @interface
+ * @group Misc Geometry
+ */
+export type OBJ_LineIntersect = {
+    intersect?: Point;
+    collinear: boolean;
+    onLines: boolean;
+};
+/**
+ * A {@link Line} is defined with either:
+ * - an instantiated {@link Line}
+ * - two points [{@link TypeParsablePoint}, {@link TypeParsablePoint}]
+ * - two points and the number of ends
+ *   [{@link TypeParsablePoint}, {@link TypeParsablePoint}, `1 | 2 | 0`]
+ * - a line definition object {@link OBJ_LineDefinition}
+ * - A recorder state definition {@link TypeF1DefLine}
+ * - A string representation of all options except the first
+ *
+ * The `ends` defines whether a line is finite (a line segment between two
+ * points - `ends = 2`), a ray (a line extending to infinity in one direction
+ * from a point - `ends = 1`), or a infinite line (a line extending to infinity
+ * in both directions - `ends = 0`).
+ *
+ * @example
+ * // l1, l2, l3, l4, l5, and l6 are all the same
+ * l1 = new Fig.Line([0, 0], [2, 0]);
+ * l2 = Fig.getLine([[0, 0], [2, 0]]);
+ * l3 = Fig.getLine({ p1: [0, 0], length: 2, direction: [1, 0] });
+ * l4 = Fig.getLine({ p1: [0, 0], length: 2, angle: 0 });
+ * l5 = Fig.getLine({ p1: [0, 0], length: 2, theta: Math.PI / 2, phi: 0 });
+ * l6 = Fig.getLine({ p1: [0, 0], p2: [2, 0] });
+ * @group Geometry
+ */
+export type TypeParsableLine = [TypeParsablePoint, TypeParsablePoint, 2 | 1 | 0] | [TypeParsablePoint, TypeParsablePoint] | OBJ_LineDefinition | TypeF1DefLine | Line;
+/**
+ * Convert a parsable line definition to a {@link Line}.
+ * @param {TypeParsableLine} l parsable line definition
+ * @return {Line} `Line` object
+ * @group Misc Geometry
+ */
+declare function getLine(l: TypeParsableLine): Line;
+/**
+ * Object representing a Line.
+ *
+ * Contains methods that makes it conventient to use lines in calculations.
+ *
+ * @example
+ * // get Line from Fig
+ * const { Line } = Fig;
+ *
+ * // define a line from [0, 0] to [1, 0]
+ * const l = new Line([0, 0], [1, 0]);
+ *
+ * // find the length of the line
+ * const len = l.length();
+ *
+ * // get the point at length 0.2 along the line
+ * const p = l.pointAtLength(0.2);
+ *
+ * // find the intersect with another line
+ * const i = l.intersectsWith([[0.5, 0.5], [0.5, -0.5]]);
+ * @group Geometry
+ */
+declare class Line {
+    p1: Point;
+    p2: Point;
+    ends: 2 | 1 | 0;
+    /**
+     * @param {0 | 1 | 2} ends number of ends the line has. `2` ends is a finite
+     * line. `1` end is an infinite line that terminates at the first point, and
+     * goes through the second point to infinity. `0` ends is an infinite line
+     * that goes through both first and second points to infinity.
+     */
+    constructor(p1OrOptions: TypeParsablePoint | OBJ_LineDefinition, p2?: TypeParsablePoint, ends?: 2 | 1 | 0);
+    _state(options: {
+        precision: number;
+    }): TypeF1DefLine;
+    /**
+     * Return the spherical theta angle of p2 relative to p1.
+     */
+    theta(): number;
+    /**
+     * Return the spherical phi angle of p2 relative to p1.
+     */
+    phi(): number;
+    _dup(): Line;
+    /**
+     * Change p1 of the line
+     */
+    setP1(p1: TypeParsablePoint): void;
+    /**
+   * Change p2 of the line
+   */
+    setP2(p2: TypeParsablePoint): void;
+    /**
+     * Get the unit vector of the line ((p2 - p1) / length).
+     */
+    unitVector(): Point;
+    /**
+     * Get the vector of the line (p2 - p1).
+     */
+    vector(): Point;
+    /**
+     * Get p1 or p2
+     * @return {Point}
+     */
+    getPoint(index?: 1 | 2): Point;
+    /**
+     * Return a line with swapped p1 and p2.
+     */
+    reverse(): Line;
+    /**
+     * Get the 2D angle of the line from p1 to p2
+     * @return {number}
+     */
+    angle(): number;
+    /**
+     * Return a duplicate line with values rounded to `precision`
+     * @return {Line}
+     */
+    round(precision?: number): Line;
+    /**
+     * Return the distance between p1 and p2. Note, for infinite lines
+     * this will still return the distance between p1 and p2 that defines
+     * the line.
+     * @return {number}
+     */
+    length(): number;
+    /**
+     * Return the midpoint between p1 and p2.
+     * @return {Point}
+     */
+    midPoint(): Point;
+    /**
+     * Return the point along some percent of the distance between p1 and p2.
+     * @return {Point}
+     */
+    pointAtPercent(percent: number): Point;
+    /**
+     * Return the point along the line at some length from p1
+     * @return {Point}
+     */
+    pointAtLength(length: number): Point;
+    /**
+     * `true` if `point` is along the line extended to infinity on both ends
+     * @return {boolean}
+     */
+    hasPointAlong(point: TypeParsablePoint, precision?: number): boolean;
+    /**
+     * `true` if `point` is on the line.
+     * If the line has 2 or 1 finite ends, point must be on or between the
+     * defined ends.
+     * @return {boolean}
+     */
+    hasPointOn(point: TypeParsablePoint, precision?: number): boolean;
+    /**
+     * Perpendicular distance from `point` to line
+     * @return {number}
+     */
+    distanceToPoint(point: TypeParsablePoint): number;
+    /**
+     * `true` if `line` is parrallel to this line.
+     * @return {boolean}
+     */
+    isParallelTo(line: TypeParsableLine, precision?: number): boolean;
+    /**
+     * `true` if two lines are equal to within some rounding `precision`.
+     * @return {boolean}
+     */
+    isEqualTo(line2: TypeParsableLine, precision?: number, delta?: boolean): boolean;
+    /**
+     * `true` if this line is within `line2`
+     * @return {boolean}
+     */
+    hasLineWithin(line: TypeParsableLine, precision?: number): boolean;
+    /**
+     * `true` if this line is along the infinite length of `line2`
+     * @return {boolean}
+     */
+    isAlongLine(line: TypeParsableLine, precision?: number): boolean;
+    isCollinearTo(line: TypeParsableLine, precision?: number): boolean;
+    isWithinLine(line: TypeParsableLine, precision?: number): boolean;
+    /**
+     * Create a line that is offset by some distance from this line.
+     *
+     * `'left'`, `'right'`, `'top'` and `'bottom'` are relative to cartesian
+     * coordinates.
+     *
+     * `'positive'` to the right of a vertical line defined from bottom to top and
+     * above a horizontal line defined from right to left. Another way to think of
+     * it is if lines are used to create a polygon in the positive rotation
+     * direction (CCW), the the `'positive'` side will be on the outside of the
+     * polygon.
+     *
+     * `'negative'` is then the inside of the same polygon.
+     * @return  {Line}
+     */
+    offset(direction: TypeParsablePoint | 'left' | 'right' | 'top' | 'bottom' | 'positive' | 'negative', dist?: number | null, perpendicular?: boolean): Line;
+    /**
+     * Create a line that is offset by some distance from this line.
+     *
+     * `'left'`, `'right'`, `'top'` and `'bottom'` are relative to cartesian
+     * coordinates.
+     *
+     * `'positive'` to the right of a vertical line defined from bottom to top and
+     * above a horizontal line defined from right to left. Another way to think of
+     * it is if lines are used to create a polygon in the positive rotation
+     * direction (CCW), the the `'positive'` side will be on the outside of the
+     * polygon.
+     *
+     * `'negative'` is then the inside of the same polygon.
+     * @return  {Line}
+     */
+    offset2D(direction: 'left' | 'right' | 'top' | 'bottom' | 'positive' | 'negative', dist: number): Line;
+    /**
+     * Perpendicular distance between two lines extended to infinity
+     */
+    distanceToLine(line: TypeParsableLine, precision?: number): number;
+    /**
+     * Return the point projected onto the line by some point off the line.
+     * The line from the projected point to the offline point will be
+     * perpendicular to the line.
+     */
+    pointProjection(p: TypeParsablePoint): Point;
+    /**
+     * The intersection between this line and `line2`.
+     *
+     * The returned result is an {@link Intersect} object with the keys
+     * `intersect`, `offLine` and `colinear`.
+     *
+     * If no intersect exists, then `intersect` will be undefined.
+     *
+     * If an intersect exists, and the intersect is within both lines, then
+     * `offLine` will be `true`. If at least one of the lines needs to be extended
+     * to reach the intersect point, then `offLine` will be `false`.
+     *
+     * If the lines are collinear but do not overlap, then the intersect point
+     * will be the midpoint between the two closest ends. `offLine` will be `true`
+     * and `collinear` will be `true`.
+     *
+     * If the lines are collinear and overlap fully (or are equal), then the
+     * intersect will be p1 of the calling line, `offLine` will be `false` and
+     * `collinear` will be `true`.
+     *
+     * If either line has zero length, then an exception will be thrown.
+     * @return {Intersect}
+     */
+    intersectsWith(line: TypeParsableLine, precision?: number): OBJ_LineIntersect;
+    /**
+     * Clip a point to be on a line.
+     *
+     * If point is not along line, then it will be projected onto it.
+     *
+     * If point is not on line, then the closest line end will be returned.
+     *
+     * @param {TypeParsablePoint} point point to clip
+     * @param {number} precision precision to clip to (`8`)
+     * @return {Point} clipped point
+     */
+    clipPoint(point: TypeParsablePoint, precision?: number): Point;
+}
+export { Line, getLine, };

package/types/js/tools/geometry/Path.d.ts

@@ -0,0 +1,67 @@
+import { Point } from './Point';
+import type { TypeParsablePoint } from './Point';
+declare function linearPath(start: Point, delta: Point, percent: number): Point;
+/**
+ * Curved translation path options, that defineds the control
+ * point of a quadratic bezier curve.
+ *
+ * Use `controlPoint` to define the control point directly. This
+ * will override all other properties.
+ *
+ * Otherwise `direction`, `magnitude` and `offset` can be used
+ * to calculate the control point based on the start and end
+ * points of the curve.
+ *
+ * The control point is calculated by:
+ * - Define a line from start to target - it will have length `d`
+ * - Define a point `P` on the line
+ * - Define a control line from point `P` with length `d` and some
+ *   angle delta from the original line.
+ *
+ * The properties then customize this calculation:
+ * - `magnitude` will scale the distance d
+ * - `offset` will define where on the line point `P` is where `0.5` is
+ *   the midpoint and `0.1` is 10% along the line from the start location
+ * - `direction` will define which side of the line the control line should be
+ *   drawn
+ * - `angle` defines the angle delta between the line and the control line - by
+ *    default this a right angle (Math.PI / 2)
+ *
+ * The directions `'up'`, `'down'`, `'left'`, `'right'` all reference the side
+ * of the line. The `'positive'`
+ * direction is the side of the line that the line would move toward when
+ * rotated in the positive direction around the start point. The
+ * '`negative`' side of the line is then the opposite side.
+ *
+ * These directions only work when the `angle` is between `0` and `Math.PI`.
+ *
+ * @property {TypeParsablePoint | null} controlPoint
+ * @property {number} magnitude
+ * @property {number} offset
+ * @property {number} angle (`Math.PI / 2`)
+ * @property {'positive' | 'negative' | 'up' | 'left' | 'down' | 'right'} direction
+ * @interface
+ * @group Misc Geometry
+ */
+export type OBJ_QuadraticBezier = {
+    controlPoint: TypeParsablePoint | null;
+    angle: number;
+    magnitude: number;
+    offset: number;
+    direction: 'up' | 'left' | 'down' | 'right' | 'positive' | 'negative';
+};
+/**
+ * Translation path options object
+ */
+export type OBJ_TranslationPath = {
+    style?: 'curve' | 'linear' | 'curved';
+    angle?: number;
+    magnitude?: number;
+    offset?: number;
+    controlPoint?: TypeParsablePoint | null;
+    direction?: 'positive' | 'negative' | 'up' | 'down' | 'left' | 'right';
+};
+declare function curvedPath(start: Point, delta: Point, percent: number, options: OBJ_TranslationPath): Point;
+declare function translationPath(pathType: "linear" | "curved" | "curve" | undefined, start: Point, delta: Point, percent: number, options: OBJ_TranslationPath): Point;
+declare function toDelta(start: Point, delta: Point, percent: number, translationStyle?: 'linear' | 'curved' | 'curve', translationOptions?: OBJ_TranslationPath): Point;
+export { curvedPath, linearPath, translationPath, toDelta, };

package/types/js/tools/geometry/Plane.d.ts

@@ -0,0 +1,201 @@
+import { Line } from './Line';
+import { Point } from './Point';
+import type { TypeParsablePoint } from './Point';
+import type { TypeParsableLine } from './Line';
+/**
+ * Recorder state definition of a {@link Plane} that represents a position
+ * and normal vector
+ *
+ * ```
+ * {
+ *   f1Type: 'pl',
+ *   state: [[number, number, number], [number, number, number]],
+ * }
+ * ```
+ * @group Misc Geometry
+ */
+export type TypeF1DefPlane = {
+    f1Type: 'pl';
+    state: [[number, number, number], [number, number, number]];
+};
+/**
+ * A {@link Plane} is defined with either:
+ * - an instantiated {@link Plane}
+ * - a position and normal vector
+ *   [{@link TypeParsablePoint}, {@link TypeParsablePoint}]
+ * - three points [{@link TypeParsablePoint}, {@link TypeParsablePoint},
+ *   {@link TypeParsablePoint}]
+ * - A recorder state definition {@link TypeF1DefPlane}
+ * - A string representation of all options except the first
+ *
+ * When defining 3 points p1, p2 and p3, the normal will be in the direction of
+ * the cross product of p12 with p13.
+ *
+ *
+ * @example
+ * // p1, p2, and p3 are all equal planes
+ * p1 = new Fig.Plane([0, 0, 0], [0, 1, 0]);
+ * p2 = Fig.getPlane([[0, 0, 0], [0, 1, 0]]);
+ * p3 = Fig.getPlane([[0, 0, 0], [1, 0, 0], [0, 0, 1]]);
+ * @group Geometry
+ */
+export type TypeParsablePlane = [TypeParsablePoint, TypeParsablePoint] | [TypeParsablePoint, TypeParsablePoint, TypeParsablePoint] | Plane | string;
+/**
+ * Chech if input parameter can be parsed as a {@link Plane}.
+ * @return {boolean}
+ * @group Misc Geometry
+ */
+declare function isParsablePlane(pIn: any): boolean;
+/**
+ * Parse a {@link TypeParsablePoint} and return a {@link Point}.
+ * @return {Point}
+ * @group Misc Geometry
+ */
+declare function getPlane(p: TypeParsablePlane): Plane;
+/**
+ * Object representing a plane.
+ *
+ * Contains methods that makes it convenient to operate on planes,
+ * points and lines.
+ *
+ * A plane can either be created with:
+ * - a point on the plane and a normal
+ * - 3 points on the plane
+ *
+ * If defined with 3 points P1, P2, and P3, then the normal will be in the
+ * direction of the cross product of vectors P1P2 and P1P3.
+ *
+ * @example
+ * // define a plane at the origin in the XZ plane
+ * const p = new Plane([0, 0, 0], [0, 1, 0]);
+ *
+ * // see if a point is on the plane
+ * const result = p.hasPointOn([1, 0, 1]);
+ *
+ * // find the intersect with a line
+ * const i = lineIntersect([[0, -0.5, 0], [0, 0.5, 0]])
+ * @group Geometry
+ */
+declare class Plane {
+    p: Point;
+    n: Point;
+    /**
+     * @return {Plane} a XY plane through the origin
+     */
+    static xy(): Plane;
+    /**
+     * @return {Plane} a XZ plane through the origin
+     */
+    static xz(): Plane;
+    /**
+     * @return {Plane} a YZ plane through the origin
+     */
+    static yz(): Plane;
+    /**
+     * @param {TypeParsablePlane | TypeParsablePoint} p1OrDef position of plane
+     * or parsable plane definition
+     * @param {TypeParsablePoint | null} normalOrP2 if `p1OrDef` is a point and
+     * `p3` is `null`, then
+     * this parameter will define the plane normal (`null`)
+     * @param {TypeParsablePoint | null} p3 if defined, then `p1OrDef` and
+     * `normalOrP2` will define the first two points of a three point plane
+     * definition
+     */
+    constructor(p1OrDef?: TypeParsablePlane | TypeParsablePoint, normalOrP2?: null | TypeParsablePoint, p3?: null | TypeParsablePoint);
+    _dup(): Plane;
+    _state(options: {
+        precision: number;
+    }): {
+        f1Type: string;
+        state: number[][];
+    };
+    /**
+     * Return a plane with all values rounded to a precision.
+     * @param {number} precision
+     * @return {Plane}
+     */
+    round(precision?: number): Plane;
+    /**
+     * `true` if point p lies on plane
+     * @param {TypeParsablePoint} p
+     * @param {number} precision
+     * @return {boolean}
+     */
+    hasPointOn(p: TypeParsablePoint, precision?: number): boolean;
+    /**
+     * Two planes are considered equal if they are parallel, and the same
+     * point exists on both planes.
+     *
+     * If the plane normal direction also needs to be compared, then use `includeNormal = true`.
+     *
+     * @param {TypeParsablePlane} plane
+     * @param {boolean} includeNormal
+     * @param {number} precision
+     * @return {boolean}
+     */
+    isEqualTo(plane: TypeParsablePlane, includeNormal?: boolean, precision?: number): boolean;
+    /**
+     * `true` if two planes are parallel to each other.
+     * @param {TypeParsablePlane} plane
+     * @param {number} precision
+     * @return {boolean}
+     */
+    isParallelTo(plane: TypeParsablePlane, precision?: number): boolean;
+    /**
+     * Returns intersect line of two planes. Returns `null` if planes are parallel
+     * and have no intersect.
+     *
+     * @param {TypeParsablePlane} plane
+     * @param {number} precision
+     * @return {null | Line} intersect line
+     */
+    intersectsWith(plane: TypeParsablePlane, precision?: number): Line | null;
+    /**
+     * `true` if line is parallel to plane.
+     *
+     * @param {TypeParsableLine} line
+     * @param {number} precision
+     * @return {boolean}
+     */
+    isParallelToLine(line: TypeParsableLine, precision?: number): boolean;
+    /**
+     * Returns the intersect point for a line (extended to infinity) with a plane.
+     * @param {TypeParsableLine} line
+     * @param {number} precision
+     * @return {Point | null} intersect point. `null` if the line does not
+     * intersect
+     */
+    lineIntersect(line: TypeParsableLine, precision?: number): Point | null;
+    /**
+     * `true` if a line lies within the plane
+     * @param {TypeParsableLine} line
+     * @param {number} precision
+     * @return {Point | null} intersect point. `null` if the line does not
+     * intersect
+     */
+    hasLineOn(line: TypeParsableLine, precision?: number): boolean;
+    /**
+     * Project a point onto the plane
+     * @param {TypeParsablePoint} p
+     * @return {Point}
+     */
+    pointProjection(p: TypeParsablePoint): Point;
+    /**
+     * Distance between plane and point
+     * @param {TypeParsablePoint} p
+     * @return {number}
+     */
+    distanceToPoint(p: TypeParsablePoint): number;
+    reflect(vector: TypeParsablePoint): Point;
+}
+/**
+ * Get plane created with three points.
+ *
+ * Normal is in the direction of the cross product of p12 and p13
+ * @param {TypeParsablePoint | [TypeParsablePoint, TypeParsablePoint, TypeParsablePoint]} p1OrPoints
+ * @param {TypeParsablePoint} p2
+ * @param {TypeParsablePoint} p3
+ * @group Misc Geometry
+ */
+declare function getNormal(p1OrPoints: TypeParsablePoint | [TypeParsablePoint, TypeParsablePoint, TypeParsablePoint], p2?: null | TypeParsablePoint, p3?: null | TypeParsablePoint): Point;
+export { isParsablePlane, Plane, getPlane, getNormal, };