figureone 0.15.10 → 1.0.0

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

@@ -0,0 +1,446 @@
+import { Point } from './Point';
+import { Plane } from './Plane';
+import { Line } from './Line';
+import type { TypeParsablePoint } from './Point';
+import type { OBJ_LineDefinition, TypeParsableLine } from './Line';
+/**
+ * Bounds intersect result
+ *
+ * @property {number | Point | null} [intersect] `null` means there is no
+ * intersect
+ * @property {number | Point} [reflection]
+ * @property {number} [distance] distance from value or Point and boundary in
+ * direction specified
+ * @group Misc Shapes
+ */
+export type BoundsIntersect = {
+    intersect: number | Point | null;
+    reflection: number | Point;
+    distance: number;
+};
+/**
+ * Point Bounds intersect result
+ *
+ * @property {Point | null} [intersect]
+ * @property {Point} [reflection]
+ * @property {number} [distance]
+ * @group Misc Shapes
+ */
+export type BoundsPointIntersect = {
+    intersect: Point | null;
+    reflection: Point;
+    distance: number;
+};
+/**
+ * Bounds value intersect result
+ *
+ * @property {number | null} [intersect]
+ * @property {number} [reflection]
+ * @property {number} [distance]
+ * @group Misc Shapes
+ */
+export type BoundsValueIntersect = {
+    intersect: number | null;
+    reflection: number;
+    distance: number;
+};
+/**
+ * Base class for all bounds.
+ *
+ * Either a value or a {@link Point} can be bounded.
+ *
+ * A Bounds must be able to:
+ * - store a boundary
+ * - check if a value or point is contained within the boundary
+ * - clip a value or point to within the boundary
+ * - find the intersect between the boundary and a value or point in some
+ *   direction
+ * @group Misc Shapes
+ */
+declare class Bounds {
+    boundary: any;
+    precision: number;
+    /**
+     * @param {Object} boundary
+     * @param {number} precision default precision for calculations
+     */
+    constructor(boundary?: any, precision?: number);
+    /**
+     * Duplicate the bounds object
+     */
+    _dup(): Bounds;
+    _state(options: {
+        precision: number;
+    }): {
+        f1Type: string;
+        state: any[];
+    };
+    /**
+     * Returns `true` if a value or {@link Point} is within the bounds.
+     * @param {number | TypeParsablePoint} valueOrPosition
+     * @param {boolean} [projectToPlane] optional flag used by some bounds types
+     * @return {boolean}
+     */
+    contains(valueOrPosition: number | TypeParsablePoint, projectToPlane?: boolean): boolean;
+    /**
+     * Returns `true` if a value or {@link Point} is within the bounds.
+     * @param {number | TypeParsablePoint} valueOrPosition
+     * @return {BoundsIntersect}
+     */
+    intersect(valueOrPosition: number | TypeParsablePoint, direction?: number | TypeParsablePoint): BoundsIntersect;
+    /**
+     * Clips a value or {@link Point} to be within a boundary.
+     * @param {number | TypeParsablePoint} valueOrPosition
+     * @return {number | Point}
+     */
+    clip(valueOrPosition: number | TypeParsablePoint): number | Point;
+    isDefined(): boolean;
+}
+/**
+ * Range bounds object definition.
+ *
+ * A range bounds defines a minimum and maximum value.
+ *
+ * @property {number | null} [min] minimum value boundary, null for unbounded
+ * (`null`)
+ * @property {number | null} [max] maximum value boundary, null for unbounded
+ * (`null`)
+ * @property {number} [precision] precision with which to calculate boundary
+ * `intersect` and `contains` (`8`)
+ * @interface
+ * @group Interactivity
+ */
+export type OBJ_RangeBounds = {
+    min?: number | null;
+    max?: number | null;
+    precision?: number;
+};
+/**
+ * Recorder state definition of a {@link RangeBounds} that represents the
+ * precision, min, and max bounds.
+ *
+ * ```
+ * {
+ *   f1Type: 'rangeBounds',
+ *   state: [
+ *     number, number | null, number | null,
+ * }
+ * ```
+ * @group Misc Shapes
+ */
+type TypeF1DefRangeBounds = {
+    f1Type: 'rangeBounds';
+    state: [number, number | null, number | null];
+};
+/**
+ * A RangeBounds defines a bounds for a value or {@link Point} between some
+ * minimum and maximum value.
+ *
+ * When using points, the minimum and maximum value is applied to each component
+ * of the point separately.
+ * @group Misc Shapes
+ */
+declare class RangeBounds extends Bounds {
+    boundary: {
+        min: number | null;
+        max: number | null;
+    };
+    /**
+     * @param {OBJ_RangeBounds} boundary
+     */
+    constructor(boundary: OBJ_RangeBounds);
+    isDefined(): boolean;
+    _dup(): RangeBounds;
+    _state(options: {
+        precision: number;
+    }): {
+        f1Type: string;
+        state: [number, number | null, number | null];
+    };
+    /**
+     * Returns `true` if a value or each x, y and z component of a {@link Point}
+     * is within the max and min bounds (on bounds is considered within).
+     *
+     * @param {number | TypeParsablePoint} valueOrPosition
+     * @return {boolean}
+     */
+    contains(position: number | TypeParsablePoint): boolean;
+    /**
+     * Returns the max or min bound that is met by a value moving in the positive
+     * or negative direction.
+     *
+     * The return object includes the intersect boundary, the distance to the
+     * boundary and the reflected direction.
+     *
+     * If the value lies outside the bounds, it will first be clipped to the
+     * bounds.
+     *
+     * @param {number} value
+     * @return {BoundsIntersect}
+     */
+    intersect(value: number, direction?: number): BoundsValueIntersect;
+    /**
+     * Clip a value or {@link Point} to within a range of bounds.
+     *
+     * If {@link Point}, then each x, y, and z component of the point will be
+     * independently clipped.
+     *
+     * @param {number | TypeParsablePoint} valueOrPosition
+     * @return {number | Point}
+     */
+    clip(value: number): number;
+    clip(position: TypeParsablePoint): Point;
+}
+/**
+ * Recorder state definition of a {@link RectBounds} that represents the
+ * precision, left, right, bottom, top, plane position, top direction and
+ * right direction of the rectangle
+ *
+ * ```
+ * {
+ *   f1Type: 'rectBounds',
+ *   state: [
+ *     number, number, number, number, number,
+ *     [number, number, number],
+ *     [number, number, number],
+ *     [number, number, number],
+ * }
+ * ```
+ * @group Misc Shapes
+ */
+export type TypeF1DefRectBounds = {
+    f1Type: 'rectBounds';
+    state: [
+        number,
+        number,
+        number,
+        number,
+        number,
+        [
+            number,
+            number,
+            number
+        ],
+        [number, number, number],
+        [number, number, number]
+    ];
+};
+/**
+ * A RectBounds is a rectangle bounds around a point in a plane.
+
+ * It is defined by:
+ * - a position in plane around which rectangle is formed
+ * - topDirection/rightDirection vectors that orient the rectangle
+ * - left/right magnitudes that define the width of the rectangle
+ * - bottom/top magnitudes that define the height of the rectangle
+ *
+ * ```
+----------------------------------------------     A
+|                                            |     |
+|        Top Vector                          |     |
+|             A                              |     | top
+|             |                              |     |
+|             |                              |     |
+|    position *----->                        |   ---
+|                   Right Vector             |     |
+|                                            |     | bottom
+|                                            |     |
+----------------------------------------------     V
+.             |
+.             |
+<-------------|----------------------------->
+    left                right
+```
+ * A rectangle can be defined in one of several ways:
+ * - position, plane normal, one direction vecvtor (top or right)
+ * - position, top and right direction vectors
+ *
+ * By default the rectangle will be in the XY plane (+z normal) with a
+ * rightDirection vector along the +x axis.
+ *
+ * @property {TypeParsablePoint} [position]
+ * @property {TypeParsablePoint} [normal]
+ * @property {TypeParsablePoint} [rightDirection]
+ * @property {TypeParsablePoint} [topDirection]
+ * @property {number} [left]
+ * @property {number} [right]
+ * @property {number} [top]
+ * @property {number} [bottom]
+ * @property {number} [precision] precision with which to calculate boundary
+ * `intersect` and `contains` (`8`)
+ * @interface
+ * @group Interactivity
+ */
+export type OBJ_RectBounds = {
+    position?: TypeParsablePoint;
+    normal?: TypeParsablePoint;
+    rightDirection?: TypeParsablePoint;
+    topDirection?: TypeParsablePoint;
+    left?: number;
+    right?: number;
+    bottom?: number;
+    top?: number;
+    precision?: number;
+};
+/**
+ * A RectBounds defines a rectangular bounds for a {@link Point}.
+ * @group Misc Shapes
+ */
+declare class RectBounds extends Bounds {
+    plane: Plane;
+    rightDirection: Point;
+    topDirection: Point;
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    boundary: {
+        left: Line;
+        right: Line;
+        bottom: Line;
+        top: Line;
+    };
+    /**
+    * @param {OBJ_RectBounds} boundary
+    */
+    constructor(boundary: OBJ_RectBounds);
+    isDefined(): boolean;
+    _dup(): RectBounds;
+    /**
+     * Return a bounds copy with all values rounded to a precision.
+     *
+     * @param {number} precision
+     * @return {RectBounds}
+     */
+    round(precision?: number): RectBounds;
+    _state(options: {
+        precision: number;
+    }): TypeF1DefRectBounds;
+    /**
+     * Return `true` if `position` is within the rectangular bounds.
+     *
+     * If `projectToPlane` is `false`, then position must be on plane, otherwise
+     * if `true` then point will be projected to the plane before checking if it
+     * within the rectangle.
+     *
+     * @param {TypeParsablePoint} position
+     * @param {boolean} projectToPlane
+     * @return {boolean}
+     */
+    contains(position: TypeParsablePoint, projectToPlane?: boolean): boolean;
+    /**
+     * Clip a position to the bounds rectangle. If the position is off plane, then
+     * it will first be projected to the plane.
+     *
+     *
+     * @param {TypeParsablePoint} position
+     * @return {Point}
+     */
+    clip(position: TypeParsablePoint): Point;
+    getBoundIntersect(position: Point, direction: Point, posBound: Line, negBound: Line, posDirection: Point): {
+        intersect: Point;
+        distance: number;
+        normal: Point;
+    } | null;
+    /**
+     * Return the intersect between a `position` moving in some `direction` and
+     * the four boundaries of the rectangle.
+     *
+     * @param {TypeParsablePoint} position
+     * @param {TypeParsablePoint} direction direction vector
+     * @return {BoundsIntersect}
+     */
+    intersect(position: TypeParsablePoint, direction: TypeParsablePoint): BoundsPointIntersect;
+}
+/**
+ * A line bounds defines a line boundary.
+ *
+ * @property {TypeParsableLine} [line]
+ * @property {number} [precision] precision with which to calculate boundary
+ * `intersect` and `contains` (`8`)
+ * @interface
+ * @group Interactivity
+ */
+export type OBJ_LineBounds = OBJ_LineDefinition & {
+    precision?: number;
+    line?: TypeParsableLine;
+};
+/**
+ * Recorder state definition of a {@link LineBounds} that represents the
+ * precision, first point, second point and number of ends.
+ *
+ * ```
+ * {
+ *   f1Type: 'lineBounds',
+ *   state: [
+ *     number,
+ *     [number, number, number],
+ *     [number, number, number],
+ *     2 | 1 | 0,
+ * }
+ * ```
+ * @group Misc Shapes
+ */
+export type TypeF1DefLineBounds = {
+    f1Type: 'lineBounds';
+    state: [number, [number, number, number], [number, number, number], 2 | 1 | 0];
+};
+/**
+ * A Line defines a line bounds for a {@link Point}.
+ * @group Misc Shapes
+ */
+declare class LineBounds extends Bounds {
+    boundary: Line;
+    isDefined(): boolean;
+    _dup(): LineBounds;
+    /**
+     * @param {OBJ_LineBounds} boundary
+     */
+    constructor(boundary: OBJ_LineBounds);
+    _state(options: {
+        precision: number;
+    }): TypeF1DefLineBounds;
+    /**
+     * Check if a position is within a line
+     *
+     * @param {TypeParsablePoint} position
+     * @return {boolean}
+     */
+    contains(position: TypeParsablePoint): boolean;
+    /**
+     * Clip a position to a line. The point will be projected to the line before
+     * clipping.
+     *
+     * @param {TypeParsablePoint} position
+     * @return {Point}
+     */
+    clip(position: number | TypeParsablePoint): Point;
+    /**
+     * Return the intersect between a `position` moving in some `direction` and
+     * the ends of the line boundary.
+     *
+     * The position and direction vector will first be projected onto the line
+     * before finding the intersect.
+     *
+     * @param {TypeParsablePoint} position
+     * @param {TypeParsablePoint} direction direction vector
+     * @return {BoundsIntersect}
+     */
+    intersect(position: TypeParsablePoint, direction: TypeParsablePoint): BoundsPointIntersect;
+}
+/**
+ * Parsable bounds definition.
+ *
+ * `null | `{@link Bounds}
+  | {@link RectBounds}` | `{@link LineBounds}` | `{@link RangeBounds}
+ ` | `{@link OBJ_RectBounds}` | `{@link OBJ_LineBounds}` | `{@link OBJ_RangeBounds}
+ ` | `{@link TypeF1DefRangeBounds}` | `{@link TypeF1DefRectBounds}` | `{@link TypeF1DefLineBounds}
+ * @group Interactivity
+ */
+export type TypeParsableBounds = null | Bounds | RectBounds | LineBounds | RangeBounds | OBJ_RectBounds | OBJ_LineBounds | OBJ_RangeBounds | TypeF1DefRangeBounds | TypeF1DefRectBounds | TypeF1DefLineBounds;
+/**
+ * Get bounds from a parsable bounds.
+ * @group Misc Shapes
+ */
+declare function getBounds(bounds: TypeParsableBounds): Bounds | RectBounds | LineBounds | RangeBounds;
+export { RangeBounds, Bounds, LineBounds, RectBounds, getBounds, };