figureone 0.15.10 → 1.0.0

package/types/js/figure/FigureCollections/Axis.d.ts

@@ -0,0 +1,517 @@
+import { Point } from '../../tools/g2';
+import type { TypeParsablePoint } from '../../tools/g2';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import type { OBJ_Font, OBJ_Font_Fixed, TypeDash, TypeColor } from '../../tools/types';
+import type { OBJ_Line } from '../FigurePrimitives/FigurePrimitiveTypes2D';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type FigureCollections from './FigureCollections';
+import type { OBJ_FormattedText } from './Text';
+import type { TypeArrowHead, OBJ_LineArrows } from '../geometries/arrow';
+import type FigureElementPrimitive2DText from '../FigurePrimitives/FigureElementPrimitive2DText';
+import type FigureElementPrimitiveGLText from '../FigurePrimitives/FigureElementPrimitiveGLText';
+/**
+ * Tick location type:
+ *
+ * `'bottom' | 'left' | 'right' | 'left' | 'center'`
+ *
+ * `'bottom'`, `'top'` and `'center'` are only for x axes.
+ *
+ * `'left'`, `'right'` and `'center'` are only for y axes.
+ * @group Misc Shapes
+ */
+export type TypeTickLocation = 'bottom' | 'left' | 'right' | 'left' | 'center';
+/**
+ * Tick location type:
+ *
+ * `'bottom' | 'left' | 'right' | 'left'`
+ *
+ * `'bottom'` and `'top'` are only for x axes.
+ *
+ * `'left'` and `'right'` are only for y axes.
+ */
+export type TypeLabelLocation = 'bottom' | 'left' | 'right' | 'left';
+/**
+ * Object passed to callback function that returns label strings for axis.
+ *
+ * @property {Array<number>} values
+ * @property {number} start start value of axis at current zoom/pan
+ * @property {number} stop stop value of axis at current zoom/pan
+ * @property {number} step step value for current zoom
+ * @property {number} mag zoom magnification
+ * @see
+ *
+ * {@link COL_Axis}
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_LabelsCallbackParams = {
+    values: Array<number>;
+    start: number;
+    stop: number;
+    step: number;
+    z: number;
+};
+/**
+ * Simple line style.
+ *
+ * @property {number} [width]
+ * @property {TypeDash} [dash]
+ * @property {TypeColor} [color]
+ * @property {OBJ_LineArrows | TypeArrowHead} [arrow]
+ * @property {number} [arrowExt] extension to line length for arrow
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_AxisLineStyle = {
+    width?: number;
+    dash?: TypeDash;
+    color?: TypeColor;
+    arrowExt?: number;
+    arrow?: OBJ_LineArrows | TypeArrowHead;
+};
+/**
+ * Axis Ticks and Grid options object for {@link COL_Axis}.
+ *
+ * @property {number} [length] length of the ticks/grid (draw space)
+ * @property {number} [offset] offset of the ticks/grid (draw space) - use this
+ * to center ticks around the axis or not (`-length / 2`)
+ * @property {number} [width] width of ticks/grid (draw space)
+ * @property {TypeDash} [dash] dash style of ticks (draw space)
+ * @property {TypeColor} [color] color of ticks/grid (defaults to plot color)
+ * @property {TypeTickLocation} [location] location of tick which if defined
+ * will overrides `offset` (`undefined`)
+ *
+ * @see
+ *
+ * {@link COL_Axis}
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_AxisTicks = {
+    length?: number;
+    offset?: number;
+    width?: number;
+    dash?: TypeDash;
+    color?: TypeColor;
+    location?: TypeTickLocation;
+};
+export type OBJ_AxisTicks_Fixed = {
+    length: number;
+    offset: number;
+    width: number;
+    dash?: TypeDash;
+    color?: TypeColor;
+};
+/**
+ * @property {Array<number>} values values to offset
+ * @property {TypeParsablePoint} offset position offset to apply to values
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_ValuesOffset = {
+    values: Array<number>;
+    offset: TypeParsablePoint;
+};
+/**
+ * Axis label options object for the {@link COL_Axis}.
+ *
+ *
+ * By default, labels are positioned with the first `ticks` defined in the
+ * axis. Labels can also be positioned at custom values with `values`.
+ *
+ * Labels will be values at the label positions, unless specified as a specific
+ * string or number in the `text` property.
+ *
+ * Different properties are defined in different spaces.
+ * - `values`, is defined in axis space, or the values along the axis.
+ * - `space` and `offset` are defined in draw space and relate
+ *   to dimensions in the space the axis is being drawn into.
+ *
+ * @property {number} [precision] Maximum number of decimal places to be shown
+ * @property {number} [precision] Fix the decimal places to the precision (all
+ * labels have the same number of decimal places)
+ * @property {'decimal' | 'exp'} [format] `'exp'` will present numbers in
+ * exponential form (`'decimal'`)
+ * @property {number} [space] space between the ticks and the label
+ * @property {TypeParsablePoint} [offset] additional offset for the labels
+ * (`[0, 0]`)
+ * @property {number} [rotation] label rotation (`0`)
+ * @property {'left' | 'right' | 'center'} [xAlign] horizontal alignment of
+ * labels (`'center'` for x axes, `'right'` for y axes)
+ * @property {'bottom' | 'baseline' | 'middle' | 'top'} [yAlign] vertical
+ * alignment of labels (`'top'` for x axes, `'middle'` for y axes)
+ * @property {OBJ_Font} [font] specific font changes for labels
+ * @property {Array<number> | number} [hide] value indexes to hide (`[]`)
+ * @property {OBJ_ValuesOffset} [valueOffset] offset the position of selected
+ * values (useful to offset values in position near axis cross over points)
+ * @property {TypeLabelLocation} [location] location of label (defaults to
+ * `'bottom'` for x axis and `'left'` for y axis)
+ * @property {Array<string>} [text] use custom labels
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ * For more examples see {@link OBJ_Axis}.
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_AxisLabels = {
+    precision?: number;
+    format?: 'decimal' | 'exp';
+    space?: number;
+    offset?: TypeParsablePoint;
+    rotation?: number;
+    xAlign?: 'left' | 'right' | 'center';
+    yAlign?: 'bottom' | 'baseline' | 'middle' | 'top';
+    font?: OBJ_Font;
+    hide?: Array<number>;
+    valueOffset?: OBJ_ValuesOffset;
+    fixed?: boolean;
+    location?: TypeLabelLocation;
+    text?: Array<string>;
+};
+export type OBJ_AxisLabels_Fixed = {
+    precision: number;
+    format: 'decimal' | 'exp';
+    space: number;
+    offset: Point;
+    rotation: number;
+    xAlign: 'left' | 'right' | 'center';
+    yAlign: 'bottom' | 'baseline' | 'middle' | 'top';
+    font: OBJ_Font_Fixed;
+    hide: Array<number>;
+    fixed: boolean;
+    valueOffset: {
+        values: Array<number>;
+        offset: Point;
+    };
+    text: Array<string>;
+};
+/**
+ * Axis title.
+ *
+ * @property {number} [rotation] title rotation
+ * @property {'bottom' | 'top' | 'left' | 'right'} [location] location of text
+ * relative to axis
+ * @property {TypeParsablePoint} [offset] title offset from default location
+ *
+ * @extends {@link OBJ_TextLines}
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_AxisTitle = OBJ_FormattedText & {
+    rotation?: number;
+    offset?: TypeParsablePoint;
+    location?: 'bottom' | 'top' | 'left' | 'right';
+};
+/**
+ * {@link CollectionsAxis} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * A zoom axis can be used to create a number line, used as an axis in
+ * {@link COL_Plot} and/or used to plot a {@link COL_Trace} against.
+ *
+ * An axis is a line that may have
+ * - tick marks
+ * - labels
+ * - grid lines
+ * - a title
+ *
+ * An axis is drawn to a `length`. It will have values along its length
+ * from `start` to `stop`. Ticks, grid lines and labels are all drawn
+ * at axis value positions. All other dimensions, such as line lengths,
+ * widths, positions, spaces and offsets are defined in draw space, or in the
+ * same space as the `length` of the axis.
+ *
+ * @property {'x' | 'y'} [axis] `'x'` axes are horizontal, `'y'` axes are
+ * vertical (`'x'`)
+ * @property {number} [length] length of the axis in draw space
+ * @property {OBJ_AxisLineStyle | boolean} [line] line style of the axis -
+ * `false` will draw no line. By default, a solid line will be drawn if not
+ * defined.
+ * @property {number} [start] start value of axis (`0`)
+ * @property {number} [stop] stop value of axis. `stop` must be larger than
+ * `start` (`start + 1`)
+ * @property {OBJ_AxisTicks | Array<OBJ_AxisTicks> | boolean} [ticks] tick
+ * options. Use an Array to setup multiple sets/styles of ticks. Use a boolean
+ * value to turn ticks on or off. Use a {@link TypeTickLocation} to only set
+ * tick location property (`false`)
+ * @property {OBJ_AxisLabels | string | () => Array<string>} [labels]
+ * label options. Use `false` to turn labels off, or a string or function as
+ * a callback to define custom labels for a set of values. Use
+ * {@link TypeLabelLocation} to only set the label location property.
+ * @property {OBJ_AxisTicks | Array<OBJ_AxisTicks> | boolean} [grid] grid
+ * options. Use an array for multiple sets of grids, and use a boolean to
+ * turn grids on and off (`false`)
+ * @property {OBJ_AxisTitle | string} [title] axis title
+ * @property {OBJ_Font} [font] default font of axis (used by title and labels)
+ * @property {boolean} [show] `false` hides the axis. Two axes are needed
+ * to plot an {@link CollectionsTrace} on a {@link CollectionsPlot}, but if either or
+ * both axes aren't to be drawn, then use `false` to hide each axis (`true`)
+ * @property {[number, number]} [auto] Will select automatic values for
+ * `start`, `stop`, and `step` that cover the range [min, max]
+ * @property {boolean | 'decimal'} [autoStep] If `true` then start, stop and
+ * step tick, grid and label values will be automatically calculated such that
+ * they land on 0 and either double/half the original step (`true`) or ensure
+ * the steps land on factors of 10 (`'decimal'`). This needs to be not `false`
+ * if panning or zooming. If `false`, then the tick, grid and label values will
+ * be from the `start`, `stop` and `step` properties. (`false`)
+ * @property {number | null} min minimum value axis can be zoomed or panned to
+ * where `null` no limit (`null`)
+ * @property {number | null} max maximum value axis can be zoomed or panned to
+ * where `null` no limit (`null`)
+ * @property {TypeParsablePoint} [position] axis position (`[0, 0]`)
+ * @property {Array<number>} [values] custom values for labels, ticks and grid.
+ * Only works for one level of ticks and grid, and doesn't not accomodate
+ * zooming or panning.
+ *
+ * @extends OBJ_Collection
+ * @interface
+ * @group 2D Shape Collections
+ */
+export type COL_Axis = {
+    axis?: 'x' | 'y';
+    length?: number;
+    line?: boolean | OBJ_AxisLineStyle;
+    start?: number;
+    stop?: number;
+    step?: number;
+    ticks?: OBJ_AxisTicks | boolean | TypeTickLocation | Array<OBJ_AxisTicks | boolean | TypeTickLocation>;
+    labels?: OBJ_AxisLabels | boolean | TypeLabelLocation | string | ((params: OBJ_LabelsCallbackParams) => Array<string>);
+    grid?: OBJ_AxisTicks | boolean | Array<OBJ_AxisTicks | boolean>;
+    title?: OBJ_AxisTitle | string;
+    font?: OBJ_Font;
+    show?: boolean;
+    min?: number | null;
+    max?: number | null;
+    auto?: [number, number];
+    autoStep?: boolean | 'decimal';
+    values?: Array<number>;
+} & OBJ_Collection;
+/**
+ * {@link FigureElementCollection} representing an Axis.
+ *
+ * ![](./apiassets/advaxis_ex1.png)
+ *
+ * ![](./apiassets/advaxis_ex2.png)
+ *
+ * ![](./apiassets/advaxis_ex3.png)
+ *
+ * ![](./apiassets/advaxis_ex4.png)
+ *
+ * ![](./apiassets/advaxis_ex5.png)
+ *
+ * This object defines an axis with an axis line, tick marks, labels,
+ * grid lines and a title.
+ *
+ * See {@link COL_Axis} for the options that can be used when creating
+ * the axis.
+ *
+ * An axis is drawn to a `length`. It will have values along its length
+ * from `start` to `stop`. Ticks, grid lines and labels are all drawn
+ * at axis value positions. All other dimensions, such as line lengths,
+ * widths, positions, spaces and offsets are defined in draw space, or in the
+ * same space as the `length` of the axis.
+ *
+ * The object contains additional methods that convert between axis values
+ * and draw space positions, as well as a convenience method to report if a
+ * value is within an axis.
+ * - <a href="#collectionsaxisvaluetodraw">valueToDraw</a>
+ * - <a href="#collectionsaxisdrawtovalue">drawToValue</a>
+ * - <a href="#collectionsaxisinaxis">inAxis</a>
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ * For more examples of axis labels and axis ticks, see {@link OBJ_AxisLabels}
+ * and {@link OBJ_AxisTicks}.
+ *
+ * @see {@link COL_Axis} for parameter descriptions
+ *
+ * @example
+ * // By default an axis is an 'x' axis
+ * figure.add({
+ *   make: 'collections.axis',
+ * });
+ *
+ * @example
+ * // An axis can also be created and then added to a figure
+ * // An axis can have specific start and stop values
+ * // An axis can be a y axis
+ * const axis = figure.collections.axis({
+ *   axis: 'y',
+ *   start: -10,
+ *   stop: 10,
+ *   step: 5,
+ * });
+ * figure.add('axis', axis);
+ *
+ *
+ * @example
+ * // An axis can have multiple sets of ticks and a title
+ * figure.add({
+ *   make: 'collections.axis',
+ *   step: [0.2, 0.05],
+ *   ticks: [
+ *     true,
+ *     { length: 0.04, location: 'bottom' },
+ *   ],
+ *   title: 'time (s)',
+ * });
+ *
+ *
+ * @example
+ * // An axis line and ticks can be customized to be dashed
+ * // and have arrows
+ * figure.add({
+ *   make: 'collections.axis',
+ *   length: 2.5,
+ *   start: -100,
+ *   stop: 100,
+ *   step: 25,
+ *   line: {
+ *     dash: [0.01, 0.01],
+ *     arrow: 'barb',
+ *   },
+ *   ticks: { dash: [0.01, 0.01] },
+ *   title: {
+ *     font: { style: 'italic', family: 'Times New Roman' },
+ *     text: 'x',
+ *     location: 'right',
+ *   },
+ * });
+ *
+ *
+ * @example
+ * // An axis can have grid lines extend from it, and
+ * // multi-line, formatted titles
+ * figure.add({
+ *   make: 'collections.axis',
+ *   stop: 2,
+ *   step: [0.5, 0.1],
+ *   grid: [
+ *     { length: 1, color: [0.5, 0.5, 0.5, 1] },
+ *     { length: 1, dash: [0.01, 0.01], color: [0.7, 0.7, 0.7, 1] },
+ *   ],
+ *   title: {
+ *     font: { color: [0.4, 0.4, 0.4, 1] },
+ *     text: [
+ *       'Total Time',
+ *       {
+ *         text: 'in seconds',
+ *         font: { size: 0.1 },
+ *         lineSpace: 0.12,
+ *       },
+ *     ],
+ *   },
+ * });
+ *
+ * @group 2D Shape Collections
+ */
+declare class CollectionsAxis extends FigureElementCollection {
+    _line: FigureElementPrimitive | null | undefined;
+    _labels: (FigureElementPrimitive2DText | FigureElementPrimitiveGLText) | null | undefined;
+    _grid: FigureElementPrimitive | null | undefined;
+    _ticks0: FigureElementPrimitive | null | undefined;
+    _grid0: FigureElementPrimitive | null | undefined;
+    length: number;
+    angle: number;
+    startValue: number;
+    stopValue: number;
+    showAxis: boolean;
+    step: Array<number>;
+    min: number | null;
+    max: number | null;
+    ticks: any;
+    grid: any;
+    labels: OBJ_AxisLabels_Fixed | null;
+    drawToValueRatio: number;
+    valueToDrawRatio: number;
+    defaultFont: OBJ_Font_Fixed;
+    axis: 'x' | 'y';
+    line: {
+        width: number;
+    } & OBJ_Line | null;
+    values: null | Array<number>;
+    labelsCallback: null | string | ((params: OBJ_LabelsCallbackParams) => Array<string>);
+    precision: number;
+    currentZoom: number;
+    initialScale: number;
+    initialStart: number;
+    autoStep: boolean | 'decimal';
+    [key: string]: any;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: COL_Axis);
+    fontUpdated(): void;
+    addTicks(type: 'grid' | 'ticks', options: OBJ_AxisTicks | boolean, index: number): any;
+    calcRatios(): void;
+    rnd(value: number): number;
+    /**
+     * Pan so an axis value is located at a draw location.
+     */
+    pan(toValue: number, atDraw: number): void;
+    _getStateProperties(options: {
+        ignoreShown?: boolean;
+    }): string[];
+    clipRange(startIn: number, stopIn: number): number[];
+    /**
+     * Pan by some delta axis value.
+     */
+    panDeltaValue(deltaValue: number): void;
+    /**
+     * Pan by some delta draw value.
+     */
+    panDeltaDraw(deltaDraw: number): void;
+    /**
+     * Zoom to some magnitude (`mag`), such that `value`
+     * is located at `drawPosition` on the axis.
+     */
+    zoom(value: number, drawPosition: number, mag: number): void;
+    /**
+     * Zoom on a value that is already shown on the axis.
+     */
+    zoomValue(value: number, mag: number): void;
+    /**
+     * Zoom by a delta magnitude on a value already shown on the axis.
+     */
+    zoomDelta(value: number, magDelta: number): void;
+    update(startValueIn?: number, stopValueIn?: number): void;
+    updateText(values: Array<number>): void;
+    updateTicks(type: 'ticks' | 'grid' | string, values: Array<number>, index: number): void;
+    addTitle(optionsIn: OBJ_FormattedText & OBJ_AxisTitle | string): void;
+    /**
+     * Convert an axis value or values to a draw space position or positions.
+     *
+     * 'x' axes have a draw space position of 0 on the left end of the axis and
+     * 'y' axes have a draw space position of 0 on the bottom end of the axis.
+     *
+     * @return {number} draw space position
+     */
+    valueToDraw(value: number): number;
+    valueToDraw(value: Array<number>): Array<number>;
+    /**
+     * Convert an axis draw space value or values to an axis value or values.
+     *
+     * 'x' axes have a draw space position of 0 on the left end of the axis and
+     * 'y' axes have a draw space position of 0 on the bottom end of the axis.
+     *
+     * @return {number} draw space position
+     */
+    drawToValue(drawValue: number): number;
+    drawToValue(drawValue: Array<number>): Array<number>;
+    /**
+     * Check if a value is within the axis.
+     *
+     * @return {boolean} `true` if value is within length of axis.
+     */
+    inAxis(value: number, precision?: number): boolean;
+    showLine(): void;
+    hideLine(): void;
+    showTicks(): void;
+    hideTicks(): void;
+    showGrid(): void;
+    hideGrid(): void;
+}
+export default CollectionsAxis;

package/types/js/figure/FigureCollections/Axis3.d.ts

@@ -0,0 +1,118 @@
+import type { OBJ_Line3Arrow } from '../../tools/d3/line3';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type { TypeColor } from '../../tools/types';
+import type FigureCollections from './FigureCollections';
+/**
+ * {@link CollectionsAxis3} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * Each option can either be singular and applied to all axes, or in a 3 element
+ * tuple where the first, second and third elements apply to the x, y, and z
+ * axes respectively.
+ *
+ * To not create an axis, use a width of exactly 0.
+ *
+ *
+ * @property {number | [number, number, number]} [width] width of axis
+ * @property {number | [number, number, number]} [start] start value of axis
+ * (`0`)
+ * @property {number | [number, number, number]} [length] length of axis
+ * @property {number | [number, number, number]} [sides] number of sides in
+ * cross section of axis (`10`)
+ * @property {number | [number, number, number]} [lines] `true` if to draw as
+ * lines instead of a solid (`false`)
+ * @property {OBJ_Line3Arrow | boolean | [OBJ_Line3Arrow | boolean, OBJ_Line3Arrow | boolean, OBJ_Line3Arrow | boolean]} [arrow] arrow options
+ * for axes
+ * @property {TypeColor | [TypeColor, TypeColor, TypeColor]} [color]
+ * axes color - default is x: red, y: green, z: blue.
+ *
+ * @extends OBJ_Collection
+ *
+ * @interface
+ * @group 3D Shape Collections
+ */
+export type COL_Axis3 = {
+    width?: number | [number, number, number];
+    length?: number | [number, number, number];
+    start?: number | [number, number, number];
+    sides?: number | [number, number, number];
+    lines?: boolean | [boolean, boolean, boolean];
+    arrow?: OBJ_Line3Arrow | boolean | [OBJ_Line3Arrow | boolean, OBJ_Line3Arrow | boolean, OBJ_Line3Arrow | boolean];
+    color?: TypeColor | [TypeColor, TypeColor, TypeColor];
+} & OBJ_Collection;
+/**
+ * {@link FigureElementCollection} representing x, y, z axes.
+ *
+ * ![](./apiassets/axis3.png)
+ *
+ * This object creates an x, y, and z axes.
+ *
+ * The axes can be created uniformly, or customized individually.
+ *
+ * See {@link COL_Axis3} for setup options.
+ *
+ * To test examples below, append them to the
+ * <a href="#shapes3d-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Create positive x, y, and z axes
+ * figure.add(
+ *   {
+ *     make: 'collections.axis3',
+ *     arrow: true,
+ *     length: 0.5,
+ *   },
+ * );
+ *
+ * @example
+ * // Create full x, y, and z axes with arrows
+ * figure.add(
+ *   {
+ *     make: 'collections.axis3',
+ *     arrow: { ends: 'all' },
+ *     start: -0.5,
+ *     length: 1,
+ *   },
+ * );
+ *
+ * @example
+ * // Customize each axis
+ * figure.add(
+ *   {
+ *     make: 'collections.axis3',
+ *     arrow: [{ ends: 'end' }, false, { ends: 'all', width: 0.02 }],
+ *     width: 0.02,
+ *     start: [0, 0, -0.5],
+ *     length: [0.5, 0.5, 1],
+ *   },
+ * );
+ *
+ * @example
+ * // Lines axes all the same color
+ * figure.add(
+ *   {
+ *     make: 'collections.axis3',
+ *     arrow: { ends: 'all' },
+ *     start: -0.5,
+ *     length: 1,
+ *     lines: true,
+ *     color: [1, 0, 0, 1],
+ *   },
+ * );
+ * @group 3D Shape Collections
+ */
+declare class CollectionsAxis3 extends FigureElementCollection {
+    _x: FigureElementPrimitive | null;
+    _y: FigureElementPrimitive | null;
+    _z: FigureElementPrimitive | null;
+    x: Record<string, any>;
+    y: Record<string, any>;
+    z: Record<string, any>;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: COL_Axis3);
+    addAxis(axisName: 'x' | 'y' | 'z'): void;
+}
+export default CollectionsAxis3;