figureone 0.15.10 → 1.0.0

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

@@ -0,0 +1,359 @@
+import type { Type2Components, Type3Components } from './types';
+import type { Type3DMatrix } from '../m3';
+type TypeF1DefPoint = {
+    f1Type: 'p';
+    state: [number, number, number];
+};
+/**
+ * A {@link Point} can be defined in several ways
+ * - As an instantiated {@link Point}
+ * - As an x, y tuple: [number, number]
+ * - As an x, y, z tuple: [number, number, number]
+ * - As an x, y string: '[number, number]'
+ * - As an x, y, z string: '[number, number, number]'
+ * - As a recorder state definition: { f1Type: 'p', state: [number, number, number] }
+ * }
+ * - A string representation of all options except the first
+ *
+ * If points are defined with only a `x` and `y` component, then `z` will be
+ * set to 0 automatically.
+ *
+ * @example
+ * // p1, p2, p3 and p4 are all the same when parsed by `getPoint`
+ * p1 = new Fig.Point(2, 3);
+ * p2 = [2, 3];
+ * p3 = '[2, 3]';
+ * p4 = { f1Type: 'p', state: [2, 3] };
+ * p5 = [2, 3, 0];
+ * @group Geometry
+ */
+export type TypeParsablePoint = Type2Components | Type3Components | Point | string | TypeF1DefPoint;
+declare function parsePoint(pIn: TypeParsablePoint): Point;
+/**
+ * Test is a point is parsable
+ * @group Misc Geometry
+ */
+declare function isParsablePoint(pIn: any): boolean;
+/**
+ * Parse a {@link TypeParsablePoint} and return a {@link Point}.
+ * @return {Point}
+ * @group Misc Geometry
+ */
+declare function getPoint(p: TypeParsablePoint): Point;
+/**
+ * Parse an array of parsable point definitions ({@link TypeParsablePoint})
+ * returning an array of points.
+ * @return {Array<Point>}
+ * @group Misc Geometry
+ */
+declare function getPoints(points: TypeParsablePoint | Array<TypeParsablePoint>): Array<Point>;
+/**
+ * Parse a scale definition and return a {@link Point} representing the scale
+ * in x and y.
+ * Scale can either be defined as a {@link TypeParsablePoint} or a `number` if
+ * the x and y scale is equal.
+ * @return {Point} x and y scale
+ * @group Misc Geometry
+ */
+declare function getScale(s: TypeParsablePoint | number): Point;
+/**
+ * Object representing a point or vector.
+ *
+ * Contains methods that makes it convenient to work with points and vectors.
+ *
+ * @see {@link TypeParsablePoint}, {@link isParsablePoint}
+ *
+ * @example
+ * // get Point from Fig
+ * const { Point } = Fig;
+ *
+ * // define a point at (0, 2)
+ * const p = new Point(0, 2);
+ *
+ * // find the distance to another point (0, 1) which will be 1
+ * const d = p.distance([0, 1]);
+ *
+ * // add to another point (3, 1) which will result in (3, 3)
+ * const q = p.add(3, 1);
+ * @group Geometry
+ */
+declare class Point {
+    x: number;
+    y: number;
+    z: number;
+    _type: 'point';
+    constructor(xOrArray: Type3Components | Type2Components | number, y?: number, z?: number);
+    /**
+     * Return x, y, z components as a length 3 tuple.
+     * @return {[number, number, number]}
+     */
+    toArray(dimension?: 2 | 3): [number, number, number] | [number, number];
+    /**
+     * Convert a cartesian point to polar coordiantes (will use x and y
+     * components of point only).
+     * @return {{ mag: number, angle: number }}
+     */
+    toPolar(): {
+        mag: number;
+        angle: number;
+    };
+    /**
+     * Convert the cartesian point to spherical coordinates.
+     * @return {{ mag: number, theta: number, phi: number }}
+     */
+    toSpherical(): {
+        mag: number;
+        theta: number;
+        phi: number;
+    };
+    _state(options?: {
+        precision: number;
+    }): {
+        f1Type: "p";
+        state: [number, number, number];
+    };
+    /**
+     * Return a duplicate of the {@link Point} object
+     * @return {Point}
+     */
+    _dup(): Point;
+    /**
+     * Multiply values of point by scalar
+     * @return {Point}
+     * @example
+     * p = new Point(1, 1, 1);
+     * s = p.scale(3);
+     * // s = Point{x: 3, y: 3, z: 3}
+     */
+    scale(scalar: number): Point;
+    /**
+     * Return a point with the negative of each component.
+     *
+     * @return {Point}
+     *
+     * @example
+     * p = new Point(1, 2, 3);
+     * q = p.neg();
+     * // q = Point{x: -1, y: -2, z: -3}
+     */
+    neg(): Point;
+    /**
+     * Multiply each corresponding component of two points.
+     *
+     * @return {Point}
+     *
+     * @example
+     * p = new Point(2, 3, 4);
+     * q = new Point(3, 4, 5);
+     * m = p.mul(q);
+     * // m = Point{x: 6, y: 12, z: 20}
+     */
+    mul(p: TypeParsablePoint): Point;
+    /**
+     * Complex multiplication.
+     *
+     * Multiply two 2D points such that x is the real value and
+     * y is the imaginary value of a complex number. z is ignored.
+     * @return {Point}
+     * @example
+     * p = new Point(1, 2); // represents 1 + 2i
+     * q = new Point(2, 3); // represents 2 + 3i
+     * m = p.cmul(q);
+     * // m = Point{x: -4, y: 7, z: 0}
+     * // which represents the complex value -4 + 7i
+     */
+    cmul(complexPoint: TypeParsablePoint): Point;
+    /**
+     * Complex division.
+     *
+     * Divide this point by `complexPoint`. Each point represents a complex
+     * number where x is the real value and y is the imaginary value.
+     * z is ignored.
+     * @return {Point}
+     * @example
+     * p = new Point(-4, 7); // represents -4 + 7i
+     * q = new Point(1, 2); // represents 1 + 2i
+     * m = p.cdiv(q);
+     * // m = Point{x: 2, y: 3, z: 0}
+     * // which represents the complex value 2 + 3i
+     */
+    cdiv(complexPoint: TypeParsablePoint): Point;
+    /**
+     * Subtract (x, y, z) values or a {@link Point} and return the difference as a new {@link Point}
+     * @return {Point}
+     * @example
+     * p = new Point(3, 3, 3);
+     * d = p.sub(1, 1, 1)
+     * // d = Point{x: 2, y: 2, z: 2}
+     *
+     * p = new Point(3, 3, 3);
+     * q = new Point(1, 1, 1);
+     * d = p.sub(q)
+     * // d = Point{x: 2, y: 2, z: 2}
+     */
+    sub(pointOrX: Point | number, y?: number, z?: number): Point;
+    /**
+     * Add (x, y, z) values or a {@link Point} and return the sum as a new {@link Point}
+     * @return {Point}
+     * @example
+     * p = new Point(3, 3, 3);
+     * d = p.add(1, 1, 1)
+     * // d = Point{x: 4, y: 4, z: 4}
+     *
+     * p = new Point(3, 3, 3);
+     * q = new Point(1, 1, 1);
+     * d = p.add(q)
+     * // d = Point{x: 4, y: 4, z: 4}
+     */
+    add(pointOrX: Point | number, y?: number, z?: number): Point;
+    /**
+     * Return the distance between two points (or point and origin if no input
+     * supplied)
+     * @return {number}
+     * @example
+     * p = new Point(1, 1, 1);
+     * q = new Point(0, 0, 0);
+     * d = q.distance(p);
+     * // d = 1.7320508075688772
+     *
+     */
+    distance(toPointIn?: TypeParsablePoint | null): number;
+    /**
+     * Return the distance between (0, 0, 0) and the point. If the point
+     * represents a vector, then it is the length of the vector.
+     * @return {number}
+     */
+    length(): number;
+    /**
+     * Dot product this point (vector) with another.
+     * @return {number}
+     */
+    dotProduct(v: TypeParsablePoint): number;
+    /**
+     * Cross product of two points (vectors).
+     * @return {Point}
+     */
+    crossProduct(v: TypeParsablePoint): Point;
+    /**
+     * Angle between this vector and vector v.
+     * @return {number}
+     */
+    angleTo(v: TypeParsablePoint): number;
+    /**
+     * Scalar projection of this vector in direction of vector v.
+     * @return {number}
+     */
+    projectOn(v: TypeParsablePoint): number;
+    /**
+     * Return a vector with magnitude of the scalar projection of this vector on
+     * v and direction +/- v (depending on the sign of the scalar projection).
+     * @return {Point}
+     */
+    componentAlong(v: TypeParsablePoint): Point;
+    /**
+     * Returns `true` if the x, y, z components of the point when rounded
+     * with `precision` are zero.
+     * @return {boolean}
+     */
+    isZero(precision?: number): boolean;
+    /**
+     * Return a new point with (x, y, z) values rounded to some precision
+     * @return {Point}
+     * @example
+     * p = new Point(1.234, 1.234, 1.234);
+     * q = p.round(2);
+     * // q = Point{x: 1.23, y: 1.23, z: 1.23}
+     */
+    round(precision?: number): Point;
+    /**
+     * Return a new point that is clipped to min and max values from the origin.
+     *
+     * Use a point as a parameter to define different (x, y) min/max values,
+     * a number to define the same (x, y) min/max values, or null to have no
+     * min/max values.
+     * @return {Point}
+     * @example
+     * p = new Point(2, 2);
+     * q = p.clip(1, 1);
+     * // q = Point{x: 1, y: 1}
+     *
+     * p = new Point(2, 2);
+     * q = p.clip(1, null);
+     * // q = Point{x: 1, y: 2}
+     *
+     * p = new Point(-2, -2);
+     * minClip = new Point(-1, -1.5);
+     * q = p.clip(minClip, null);
+     * // q = Point{x: -1, y: -1.5}
+     */
+    clip(min: Point | number | null, max: Point | number | null): Point;
+    /**
+     * Transform the point with a 4x4 matrix (3 dimensional transform in
+     * homogenous coordinates)
+     * @return {Point}
+     * @example
+     * // Transform a point with a (2, 2, 0) translation then 90º z rotation
+     * p = new Point(1, 1);
+     * m = new Transform3().translate(2, 2, 0).rotate(0, 0, Math.PI / 2).matrix();
+     * // m = [0, -1, 0, -2, 1, 0, 0, 2, 0, 0, 0, 1]
+     * q = p.transformBy(m)
+     * // q = Point{x: -3, y: 3, 0}
+     */
+    transformBy(matrix: Type3DMatrix): Point;
+    quadraticBezier(p1: Point, p2: Point, t: number): Point;
+    /**
+     * Rotate a point some angle around a point
+     * @param {number} angle - in radians
+     * @param center - in radians
+     * @return {Point}
+     * @example
+     * // Rotate a point around the origin
+     * p = new Point(1, 0);
+     * q = p.rotate(Math.PI)
+     * // q = Point{x: -1, y: 0}
+     *
+     * // Rotate a point around (1, 1)
+     * p = new Point(2, 1);
+     * q = p.rotate(Math.PI, new Point(1, 1))
+     * // q = Point{x: 0, y: 1}
+     */
+    rotate(angle: number, center?: TypeParsablePoint, axis?: TypeParsablePoint): Point;
+    /**
+     * Return the unit vector of the point (the direction vector of length 1
+     * from the origin to the point).
+     * @return {Point}
+     */
+    normalize(): Point;
+    /**
+     * Compare two points for equality to some precision or delta
+     * @param {TypeParsablePoint} p point to compare
+     * @param {number} precision precision to compare (`8`)
+     * @param {boolean} delta if `true` then precision is the delta value the two
+     * points must be within to be equal
+     * @return {boolean}
+     * @example
+     * p = new Point(1.123, 1.123);
+     * q = new Point(1.124, 1.124);
+     * p.isEqualTo(q)
+     * // false
+     *
+     * p.isEqualTo(q, 2)
+     * // true
+     */
+    isEqualTo(p: TypeParsablePoint, precision?: number, delta?: boolean): boolean;
+    isWithinDelta(p: Point, delta?: number): boolean;
+    /**
+     * Compare two points for unequality to some precision
+     * @example
+     * p = new Point(1.123, 1.123);
+     * q = new Point(1.124, 1.124);
+     * p.isNotEqualTo(q)
+     * // true
+     *
+     * p.isNotEqualTo(q, 2)
+     * // false
+     */
+    isNotEqualTo(p: Point, precision?: number, delta?: boolean): boolean;
+    isNotWithinDelta(p: Point, delta?: number): boolean;
+}
+export { isParsablePoint, getPoint, getScale, getPoints, parsePoint, Point, };

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

@@ -0,0 +1,115 @@
+import { Point } from './Point';
+import type { TypeParsablePoint } from './Point';
+import type { TypeParsableLine } from './Line';
+/**
+ * An object representing a rectangle.
+ *
+ * @example
+ * // get Rect from Fig
+ * const { Rect } = Fig;
+ *
+ * // define a rect centered at origin with width 4 and height 2
+ * const r = new Rect(-2, -1, 4, 2);
+ * @group Geometry
+ */
+declare class Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    bottom: number;
+    right: number;
+    /**
+     * Constructor
+     * @constructor
+     * @param {number} left - left location
+     * @param {number} bottom - bottom location
+     * @param {number} width - rectangle width
+     * @param {number} height - rectangle height
+     */
+    constructor(left: number, bottom: number, width: number, height: number);
+    /**
+     * Return a duplicate rectangle object
+     */
+    _dup(): Rect;
+    _state(options: {
+        precision: number;
+    }): TypeF1DefRect;
+    /**
+     * Returns `true` if `point` is within or on the border of the rectangle
+     * @param {TypeParsablePoint} point point to test
+     * @param {number} precision precision to test
+     * @return {boolean}
+     * @example
+     * const r = new Rect(-2, -1, 4, 2);
+     *
+     * // check if point is within the rectangle (will return `true`)
+     * const result = r.isPointInside([0, 1]);
+     */
+    isPointInside(point: TypeParsablePoint, precision?: number): boolean;
+    /**
+     * Returns a rectangle with coordinates rounded to `precision`
+     * @param {number} precision precision to test
+     * @return {Rect}
+     */
+    round(precision?: number): Rect;
+    /**
+     * Find the intersect of the line from the center of the rectangle to the
+     * point, with the rectangle border.
+     * @param {TypeParsablePoint} point
+     * @return {Point | null} intersect
+     */
+    intersectsWith(point: TypeParsablePoint): Point | null;
+    /**
+     * Find the intersect(s) between a line and rectangle
+     * @param {TypeParsableLine} line
+     * @return {Array<Point>}
+     */
+    intersectsWithLine(line: TypeParsableLine): Array<Point | undefined>;
+    /**
+     * The center point of the rectangle
+     * @return {Point}
+     */
+    center(): Point;
+}
+/**
+ * Recorder state definition of a {@link Rect} that represents the left,
+ * bottom, width and height of the rectangle.
+ *
+ * ```
+ * {
+ *   f1Type: 'rect',
+ *   state: [number, number, number, number],
+ * }
+ * ```
+ * @group Misc Geometry
+ */
+type TypeF1DefRect = {
+    f1Type: 'rect';
+    state: [number, number, number, number];
+};
+/**
+ * A {@link Rect} can be defined with either
+ * - an instantiated {@link Rect}
+ * - an array of left, bottom, width, height values
+ *  `[number, number, number, number]`
+ * - a recorder state definition {@link TypeF1DefRect}
+ * - a string representation of all options except the first
+ *
+ * @example
+ * // All rectangles are the same when parsed by `getRect` and have a lower
+ * left corner of `(-2, -1)`, a width of `4`, and a height of `2`
+ * const r1 = Fig.getRect([-2, -1, 4, 2]);
+ * const r2 = new Fig.Rect(-2, -1, 4, 2);
+ * const r3 = Fig.getRect('[-2, -1, 4, 2]');
+ * @group Geometry
+ */
+export type TypeParsableRect = [number, number, number, number] | Rect | TypeF1DefRect | string;
+/**
+ * Convert a parsable rectangle definition to a {@link Rect}.
+ * @param {TypeParsableRect} r parsable rectangle definition
+ * @return {Rect} rectangle object
+ * @group Misc Geometry
+ */
+declare function getRect(r: TypeParsableRect): Rect;
+export { getRect, Rect, };