figureone 0.15.10 → 1.0.0

package/types/js/tools/d3/line3.d.ts

@@ -0,0 +1,55 @@
+import type { TypeParsablePoint, Point } from '../geometry/Point';
+import type { TypeParsableTransform } from '../geometry/Transform';
+/**
+ * Arrow definition object for a 3D line.
+ *
+ * @property {'start' | 'end' | 'all'} [ends] which end to put an arrow where
+ * `'start'` is `p1` and `'end'` is `p2` (`'end'`)
+ * @property {number} [width] width of arrow (line width * 2.5)
+ * @property {number} [length] length of arrow (arrow width * 3)
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_Line3Arrow = {
+    ends?: 'start' | 'end' | 'all';
+    width?: number;
+    length?: number;
+};
+/**
+ * 3D line options object.
+ *
+ * A 3D line is a cylinder with optional arrows on the end. Unlike a 2D line,
+ * the arrow profiles can only be simple triangles.
+ *
+ * @property {TypeParsablePoint} [p1] (`[0, 0, 0]`)
+ * @property {TypeParsablePoint} [p2] (default: `p1 + [1, 0, 0]`)
+ * @property {number} [width] width of line
+ * @property {OBJ_Line3Arrow | boolean} [arrow] define to use arrows at one or
+ * both ends of the line
+ * @property {number} [sides] number of sides (`10`)
+ * @property {'curve' | 'flat'} [normals] `flat` normals will make light
+ * shading across a line face constant. `curve` will gradiate the shading. Use
+ * `curve` to make a surface look more round with fewer number of sides.
+ * (`curve`)
+ * @property {number} [rotation] rotation of line around its axis - this is
+ * only noticable for small numbers of sides (`0`)
+ * @property {TypeParsableTransform} [transform] transform to apply to line
+ * @property {boolean} [lines] if `true` then points representing
+ * the edes of the faces will be returned. If `false`, then points
+ * representing two triangles per face and an
+ * associated normal for each point will be returned.
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_Line3Points = {
+    p1?: TypeParsablePoint;
+    p2?: TypeParsablePoint;
+    width?: number;
+    arrow?: OBJ_Line3Arrow | boolean | null;
+    sides?: number;
+    normals?: 'curve' | 'flat';
+    transform?: TypeParsableTransform;
+    lines?: boolean;
+    rotation?: number;
+};
+export default function line3(options: OBJ_Line3Points): [Point[]] | [Point[], Point[]];

package/types/js/tools/d3/prism.d.ts

@@ -0,0 +1,49 @@
+import { Point } from '../geometry/Point';
+import type { TypeParsablePoint } from '../geometry/Point';
+import type { TypeParsableTransform } from '../geometry/Transform';
+/**
+ * Prism options object.
+ *
+ * A prism base is defined in the XY plane, and it's length extends
+ * into +z. Use `transform` to orient it in any other way.
+ *
+ * Triangles will be created for the ends if the base is convex. If the base
+ * is not convex, use `baseTriangles` to define the triangles.
+ *
+ * @property {number} [base] base border points defined in the XY plane - the
+ * points should be defined in the counter-clock-wise direction.
+ * @property {Array<TypeParsablePoint>} baseTriangles triangles in the XY plane
+ * that create the base fill. If the base is convex, then the triangles can be
+ * auto-generated and this property left undefined.
+ * @property {number} [length] length of the prism
+ * @property {TypeParsableTransform} [transform] transform to apply to all
+ * points of prism
+ * @property {boolean} [lines] if `true` then points representing
+ * the edges of the prism will be returned. If `false`, then points
+ * representing triangle bases and associated normals will be returned.
+ * (`false`)
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_PrismPoints = {
+    base?: Array<TypeParsablePoint>;
+    baseTriangles?: Array<TypeParsablePoint>;
+    length?: number;
+    transform?: TypeParsableTransform;
+    lines?: boolean;
+};
+/**
+ * Return points of a prism.
+ *
+ * The points can either represent the triangles that make up each base, or
+ * represent the start and end points lines that are the edges of the prism.
+ *
+ * If the points represent triangles, then a second array of normal vectors
+ * for each point will be available.
+ *
+ * @property {OBJ_PrismPoints} options cube options
+ * @return {[Array<Point>, Array<Point>]} an array of points and normals. If
+ * the points represent lines, then the array of normals will be empty.
+ * @group Geometry Creation
+ */
+export default function prism(options: OBJ_PrismPoints): [Point[]] | [Point[], Point[]];

package/types/js/tools/d3/revolve.d.ts

@@ -0,0 +1,87 @@
+import { Point } from '../geometry/Point';
+import type { TypeParsablePoint } from '../geometry/Point';
+import type { Type3DMatrix } from '../m3';
+import type { TypeParsableTransform } from '../geometry/Transform';
+/**
+ * Options object for {@link revolve}.
+ *
+ * Revolve (or radially sweep) a profile in the XY plane around the x axis to
+ * form a 3D surface.
+ *
+ * @property {Array<TypeParsablePoint>} profile XY plane profile to be radially
+ * swept around the x axis
+ * @property {number} [sides] number of sides in the radial sweep
+ * @property {'flat' | 'curveRows' | 'curveRadial' | 'curve'} [normals]
+ * `flat` normals will make shading (from a light source) across a face of the
+ * object a constant color. `curveProfile` will gradiate the shading along the
+ * profile. `curveRadial` will gradiate the shading around the radial sweep.
+ * `curve` will gradiate the shading both around the radial sweep and along the
+ * profile. Use `curve`, `curveProfile`, or `curveRadial` to make a surface
+ * look more round with fewer number of sides.
+ * @property {number} [rotation] by default the profile will start in the XY
+ * plane and sweep around the x axis following the right hand rule. Use
+ * `rotation` to start the sweep at some angle where 0º is in the XY for +y and
+ * 90º is in the XZ plane for +z. initial angle of the revolve rotation
+ * @property {TypeParsablePoint} [axis] orient the shape so its axis is along
+ * this vector
+ * @property {TypeParsablePoint} [position] offset the final vertices such that
+ * the original (0, 0) point in the profile moves to position (this step
+ * happens after the rotation)
+ * @property {TypeParsableTransform} [transform] apply a final transform to
+ * shape
+ * @property {boolean} [lines] if `true` then points representing
+ * the edes of the faces will be returned. If `false`, then points
+ * representing two triangles per face and an
+ * associated normal for each point will be returned.
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_RevolvePoints = {
+    sides?: number;
+    profile?: Array<TypeParsablePoint>;
+    normals?: 'flat' | 'curveProfile' | 'curveRadial' | 'curve';
+    axis?: TypeParsablePoint;
+    rotation?: number;
+    position?: TypeParsablePoint;
+    transform?: TypeParsableTransform;
+    lines?: boolean;
+};
+export type OBJ_RevolveDefined = {
+    sides: number;
+    profile: Array<Point>;
+    normals: 'flat' | 'curveProfile' | 'curveRadial' | 'curve';
+    matrix: Type3DMatrix;
+    rotation: number;
+    position: Point;
+    transform?: TypeParsableTransform;
+};
+declare function getLathePoints(o: OBJ_RevolveDefined): Point[][];
+/**
+ * Return points of a 3D surface created by revolving (or radially sweeping) a
+ * 2D profile around an axis.
+ *
+ * The points can either represent the triangles that make up each face, or
+ * represent the start and end points lines that are the edges of each face of
+ * the cone.
+ *
+ * If the points represent triangles, then a second array of normal vectors
+ * for each point will be available.
+ *
+ * A profile is defined in the XY plane, and then revolved around the x axis.
+ *
+ * The resulting points can oriented and positioned by defining a axis and
+ * position. The axis directs the x axis (around which the profile was
+ * rotated) to any direction. The position then offsets the transformed points
+ * in 3D space, there the original (0, 0, [0]) point is translated to
+ * (position.x, position.y, position.z)
+ *
+ * All profile points must have a y value that is not 0, with the exceptions of
+ * the ends which can be 0.
+ *
+ * @param {OBJ_Revolve} options
+ * @return {[Array<Point>, Array<Point>]} an array of points and normals. If
+ * the points represent lines, then the array of normals will be empty.
+ * @group Geometry Creation
+ */
+declare function revolve(options: OBJ_RevolvePoints): [Point[]] | [Point[], Point[]];
+export { revolve, getLathePoints, };

package/types/js/tools/d3/sphere.d.ts

@@ -0,0 +1,33 @@
+import type { TypeParsableTransform } from '../geometry/Transform';
+import type { Point, TypeParsablePoint } from '../geometry/Point';
+/**
+ * Sphere options object.
+ *
+ * By default, a sphere with its base at the origin will be created.
+ *
+ * @property {number} [sides] number of sides around sphere's half great circle
+ * (`10`)
+ * @property {number} [radius] radius of sphere (`1`)
+ * @property {'curve' | 'flat'} [normals] `flat` normals will make light
+ * shading across a face cone constant. `curve` will gradiate the shading. Use
+ * `curve` to make a surface look more round with fewer number of sides.
+ * (`flat`)
+ * @property {TypeParsablePoint} [center] center position of sphere (`[0, 0]`)
+ * @property {TypeParsableTransform} [transform] transform to apply to all
+ * points of cube
+ * @property {boolean} [lines] if `true` then points representing
+ * the edes of the faces will be returned. If `false`, then points
+ * representing two triangles per face and an
+ * associated normal for each point will be returned.
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_SpherePoints = {
+    sides?: number;
+    radius?: number;
+    normals?: 'curve' | 'flat';
+    center?: TypeParsablePoint;
+    transform?: TypeParsableTransform;
+    lines?: boolean;
+};
+export default function sphere(options: OBJ_SpherePoints): [Point[]] | [Point[], Point[]];

package/types/js/tools/d3/surface.d.ts

@@ -0,0 +1,47 @@
+import { Point } from '../geometry/Point';
+import type { TypeParsablePoint } from '../geometry/Point';
+import type { TypeParsableTransform } from '../geometry/Transform';
+declare function getSurfaceNormals(surfacePoints: Array<Array<Point>>): Point[][];
+declare function getTriangles(surfacePoints: Array<Array<Point>>): Point[];
+declare function getLines(surfacePoints: Array<Array<Point>>): Point[];
+declare function getFlatNormals(surfaceNormals: Array<Array<Point>>, surfacePoints: Array<Array<Point>>): Point[];
+declare function getCurveNormals(surfaceNormals: Array<Array<Point>>, surfacePoints: Array<Array<Point>>, curve: 'curveColumns' | 'curveRows' | 'curve', closeColumns: boolean, closeRows: boolean): Point[];
+/**
+ * Options object for defining a 3D surface.
+ *
+ * @property {Array<Array<TypeParsablePoint>>} [points] A grid of points that
+ * define a 3D surface
+ * @property {'curveColumns' | 'curveRows' | 'curve' | 'flat'} [normals]
+ * `flat` normals will make shading (from a light source) across a face of the
+ * object a constant color. `curveRows` will gradiate the shading along the
+ * rows of the grid. `curveColumns` will gradiate the shading along the columns
+ * of the grid. `curve` will gradiate the shading along both rows and columns.
+ * Use `curve`, `curveRows`, or `curveColumns` to make a surface
+ * look more round with fewer number of sides.
+ * @property {boolean} [closeColumns] Set to `true` if first row and last row are
+ * the same, and normals is `'curveRows'` or `'curve'` to get correct normal
+ * calculations (`false`)
+ * @property {boolean} [closeRows] Set to `true` if first row and last
+ * column are the same, and normals is `'curveColumns'` or `'curve'` to get
+ * correct normal calculations (`false`)
+ * @property {TypeParsableTransform} [transform] apply a final transform to
+ * shape
+ * @property {boolean} [lines] if `true` then points representing
+ * the edes of the faces will be returned. If `false`, then points
+ * representing two triangles per face and an
+ * associated normal for each point will be returned.
+ * @property {boolean} [invertNormals] if `true`, all normals will be inverted
+ * @interface
+ * @group Misc Geometry Creation
+ */
+export type OBJ_SurfacePoints = {
+    points?: Array<Array<TypeParsablePoint>>;
+    normals?: 'curveColumns' | 'curveRows' | 'curve' | 'flat';
+    closeColumns?: boolean;
+    closeRows?: boolean;
+    transform?: TypeParsableTransform;
+    lines?: boolean;
+    invertNormals?: boolean;
+};
+declare function surface(options: OBJ_SurfacePoints): [Point[], Point[]];
+export { getTriangles, getFlatNormals, getCurveNormals, getSurfaceNormals, getLines, surface, };

package/types/js/tools/g2.d.ts

@@ -0,0 +1,242 @@
+import type { TypeParsablePoint } from './geometry/Point';
+import { getPoint, isParsablePoint, getPoints, getScale, parsePoint, Point } from './geometry/Point';
+import { toDelta } from './geometry/Path';
+import { Plane, getPlane, isParsablePlane, getNormal } from './geometry/Plane';
+import type { TypeParsablePlane } from './geometry/Plane';
+import type { OBJ_TranslationPath } from './geometry/Path';
+import { Line, getLine } from './geometry/Line';
+import { Transform, getTransform, isParsableTransform, angleFromVectors, directionToAxisAngle } from './geometry/Transform';
+import { decelerateValue, decelerateVector } from './geometry/deceleration';
+import type { TypeParsableLine } from './geometry/Line';
+import type { TypeParsableRect } from './geometry/Rect';
+import type { TypeTransformValue, TypeParsableTransform } from './geometry/Transform';
+import { Rect, getRect } from './geometry/Rect';
+import { rectToPolar, polarToRect } from './geometry/coordinates';
+import { RectBounds, LineBounds, Bounds, RangeBounds, getBounds } from './geometry/Bounds';
+import type { TypeParsableBounds } from './geometry/Bounds';
+import { deg, minAngleDiff, getDeltaAngle3D, getDeltaAngle, normAngleTo90, threePointAngle, threePointAngleMin, normAngle, clipAngle } from './geometry/angle';
+import type { TypeRotationDirection } from './geometry/angle';
+import { sphericalToCartesian, cartesianToSpherical } from './geometry/common';
+import sphere from './d3/sphere';
+import { revolve, getLathePoints } from './d3/revolve';
+import cone from './d3/cone';
+import line3 from './d3/line3';
+import cylinder from './d3/cylinder';
+import cube from './d3/cube';
+import prism from './d3/prism';
+import * as surface from './d3/surface';
+import { pointsToNumbers, numbersToPoints, toNumbers, toPoints } from './geometry/tools';
+import { polygon, polygonLine } from './d2/polygon';
+type Type3Components = [number, number, number];
+type Type2Components = [number, number];
+export type { TypeParsableTransform, TypeTransformValue, TypeParsablePoint, TypeParsableRect, TypeParsableLine, Type3Components, Type2Components, TypeParsablePlane, TypeRotationDirection, OBJ_TranslationPath, TypeParsableBounds, };
+declare function isTransformArrayZero(transformValue: TypeTransformValue, threshold?: number): boolean;
+declare function spaceToSpaceTransform(s1: {
+    x: {
+        min: number;
+        span: number;
+    };
+    y: {
+        min: number;
+        span: number;
+    };
+    z: {
+        min: number;
+        span: number;
+    };
+}, s2: {
+    x: {
+        min: number;
+        span: number;
+    };
+    y: {
+        min: number;
+        span: number;
+    };
+    z: {
+        min: number;
+        span: number;
+    };
+}): Transform;
+declare function spaceToSpaceScale(s1: {
+    x: {
+        bottomLeft: number;
+        width: number;
+    };
+    y: {
+        bottomLeft: number;
+        height: number;
+    };
+    z: {
+        bottomLeft: number;
+        height: number;
+    };
+}, s2: {
+    x: {
+        bottomLeft: number;
+        width: number;
+    };
+    y: {
+        bottomLeft: number;
+        height: number;
+    };
+    z: {
+        bottomLeft: number;
+        height: number;
+    };
+}): Point;
+declare function comparePoints(p: Point, currentMin: Point, currentMax: Point, firstPoint: boolean): {
+    min: Point;
+    max: Point;
+};
+/**
+ * Buffer for rectangle, where `left`, `bottom`, `right` and `top` are
+ * the buffer values for a rectangle's left, bottom, right and top sides
+ * respectively.
+ * @interface
+ * @group Misc Geometry
+ */
+export type OBJ_Buffer = {
+    left: number;
+    bottom: number;
+    right: number;
+    top: number;
+};
+/**
+ * Buffer for rectangle can be:
+ *
+ * - `number`: left, bottom, right, top buffer all the same
+ * - [`number`, `number`]: left/right and bottom/top buffer values
+ * - [`number`, `number`, `number`, `number`]: left, bottom, right,
+ *   top buffer values
+ * - `{ left? number, bottom?: number, right?: number, top?: number}`:
+ *   object definition where default values are `0`.
+ *
+ * Can use {@link getBuffer} to convert the parsable buffer into
+ * @group Misc Geometry
+ */
+export type TypeParsableBuffer = number | [number, number] | [number, number, number, number] | {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+};
+/**
+ * Convert a parsable buffer into a buffer.
+ * @return {OBJ_Buffer}
+ * @group Misc Geometry
+ */
+declare function getBuffer(buffer: TypeParsableBuffer): OBJ_Buffer;
+declare function isBuffer(input: any): boolean;
+declare function getBoundingRect(pointArrays: Array<Point> | Array<Array<Point>>, buffer?: TypeParsableBuffer): Rect;
+declare function getBoundingBorder(pointArrays: Array<Point> | Array<Array<Point>>, buffer?: TypeParsableBuffer): Point[];
+declare function randomPoint(withinRect: Rect): Point;
+declare function getMaxTimeFromVelocity(startTransform: Transform, stopTransform: Transform, velocityTransform: Transform | number, rotDirection?: 0 | 1 | -1 | 2): number;
+declare function getMoveTime(startTransform: Transform | Array<Transform>, stopTransform: Transform | Array<Transform>, rotDirection?: 0 | 1 | -1 | 2, translationVelocity?: Point, // 0.5 figure units/s
+rotationVelocity?: Point, // 60º/s
+scaleVelocity?: Point): number;
+declare function quadBezierPoints(p0: Point, p1: Point, p2: Point, sides: number): Point[];
+/**
+ * Get center of a triangle
+ *
+ * @example
+ * const getTriangleCenter = Fig.getTriangleCenter;
+ *
+ * const center = getTriangleCenter([0, 0], [1, 0], [0, 1]);
+ * console.log(center);
+ * // Point {x: 0.3333333333333333, y: 0.3333333333333333}
+ * @group 2D Geometry Tools
+ */
+declare function getTriangleCenter(p1: TypeParsablePoint, p2: TypeParsablePoint, p3: TypeParsablePoint): Point;
+/**
+ * A border is an array of points defining a contigous, closed border.
+ *
+ * `Array<TypeParsablePoint> | Array<Array<TypeParsablePoint>>`
+ *
+ * If a border is not contigous, but rather is several "islands" of contigous,
+ * closed borders, then an array of point arrays can be used, where each point
+ * array is one island.
+ * @group Misc Geometry
+ */
+export type TypeParsableBorder = Array<TypeParsablePoint> | Array<Array<TypeParsablePoint>>;
+/**
+ * A border is an array of point arrays. Each point array is a contigous, closed
+ * border. Several point arrays represent a border that is several separate
+ * borders.
+ *
+ * `TypeBorder = Array<Array<Point>>`
+ * @group Misc Geometry
+ */
+export type TypeBorder = Array<Array<Point>>;
+declare function getBorder(border: Array<TypeParsablePoint> | Array<Array<TypeParsablePoint>> | string | number | TypeParsableBuffer): Array<Array<Point>> | string | TypeParsableBuffer;
+export type TypeXAlign = 'left' | 'right' | 'center' | number | string;
+export type TypeYAlign = 'bottom' | 'top' | 'middle' | number | string;
+declare function getPositionInRect(r: TypeParsableRect, xAlign?: TypeXAlign, yAlign?: TypeYAlign): Point;
+/**
+ * Surface grid options object.
+ *
+ * Two components must be a fixed [min, max, step].
+ *
+ * One component must be a function that takes in two components
+ * (x, y), (x, z), or (y, z) and outputs the third (z, y or x repsectively).
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_SurfaceGrid = {
+    x: ((a: number, b: number) => number) | [number, number, number];
+    y: ((a: number, b: number) => number) | [number, number, number];
+    z: ((a: number, b: number) => number) | [number, number, number];
+};
+/**
+ * Create a matrix of points that define a surface.
+ *
+ * ![](./apiassets/sufacegrid.png)
+ *
+ * Start with a grid of points in two components (x, y), (x, z), or (y, z), and
+ * define the third component (z, y or x repsectively) based on the first two.
+ *
+ * Resulting matrix can be used to create a 3D surface.
+ *
+ * @see {OBJ_Surface}
+ *
+ * @param {OBJ_SurfaceGrid} [components]
+ * @return {<Array<Array<Point>>}
+ *
+ * @example
+ * const { Figure, surfaceGrid } = Fig;
+ *
+ * // Orthographic scene with camera oriented so z is up
+ * const figure = new Figure({
+ *   scene: {
+ *     style: 'orthographic',
+ *     camera: { up: [0, 0, 1], position: [1, 0.5, 0.5] },
+ *   },
+ * });
+ *
+ * // Use surfaceGrid to generate a 3D surface from an xy grid
+ * const points = surfaceGrid({
+ *   x: [-0.8, 0.8, 0.02],
+ *   y: [-0.8, 0.8, 0.02],
+ *   z: (x, y) => 1 / ((x * 5) ** 2 + (y * 5) ** 2 + 1),
+ * });
+ *
+ * figure.add([
+ *   {
+ *     make: 'surface',
+ *     points,
+ *     color: [1, 0, 0, 1],
+ *     normals: 'curve',
+ *   },
+ *   {
+ *     make: 'surface',
+ *     points,
+ *     lines: true,
+ *     color: [0, 0, 0, 1],
+ *     position: [0, 0, 0.0001],
+ *   },
+ *   { make: 'cameraControl', axis: [0, 0, 1] },
+ * ]);
+ * @group Misc Shapes
+ */
+declare function surfaceGrid(components: OBJ_SurfaceGrid): Point[][];
+export { Point, Line, minAngleDiff, deg, normAngle, Transform, Rect, spaceToSpaceTransform, getBoundingRect, polarToRect, rectToPolar, getDeltaAngle, getDeltaAngle3D, normAngleTo90, threePointAngle, threePointAngleMin, randomPoint, getMaxTimeFromVelocity, getMoveTime, parsePoint, clipAngle, spaceToSpaceScale, getPoint, getScale, getPoints, quadBezierPoints, getRect, getTransform, getLine, decelerateValue, RectBounds, LineBounds, RangeBounds, getBounds, Bounds, getTriangleCenter, getBoundingBorder, getBorder, comparePoints, isBuffer, getPositionInRect, isParsablePoint, isParsableTransform, isTransformArrayZero, Plane, getPlane, isParsablePlane, toDelta, sphericalToCartesian, cartesianToSpherical, getNormal, sphere, revolve, cylinder, cone, line3, cube, prism, surface, getLathePoints, decelerateVector, numbersToPoints, pointsToNumbers, toNumbers, toPoints, polygon, polygonLine, angleFromVectors, directionToAxisAngle, surfaceGrid, getBuffer, };