figureone 0.15.10 → 1.0.0

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

@@ -0,0 +1,558 @@
+import { Point, Rect } from '../../tools/g2';
+import type { TypeParsablePoint } from '../../tools/g2';
+import { FigureElementCollection, FigureElement } from '../Element';
+import type CollectionsAxis from './Axis';
+import type { COL_Axis } from './Axis';
+import type CollectionsTrace from './Trace';
+import type { COL_Trace } from './Trace';
+import type { COL_PlotLegend } from './Legend';
+import type CollectionsRectangle from './Rectangle';
+import type { COL_Rectangle } from './Rectangle';
+import type { OBJ_Collection, OBJ_LineStyleSimple, OBJ_Texture } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type { OBJ_FormattedText } from './Text';
+import type { OBJ_Font, TypeColor, OBJ_Font_Fixed, OBJ_CurvedCorner } from '../../tools/types';
+import type FigureCollections from './FigureCollections';
+/**
+ * Gesture area extension. `left` and `bottom` should be negative numbers
+ * if extending beyond the plot area.
+ *
+ * @property {number} [left]
+ * @property {number} [right]
+ * @property {number} [top]
+ * @property {number} [bottom]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_GestureArea = {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+};
+/**
+ * Plot frame.
+ *
+ *
+ * @property {OBJ_LineStyleSimple} [line] line detail
+ * @property {TypeColor | OBJ_Texture} [fill] fill detail
+ * @property {OBJ_CurvedCorner} [corner] define if need curved corners
+ * @property {number} [space] space between plot, labels and title and frame
+ * boundary
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotFrame = {
+    line?: OBJ_LineStyleSimple;
+    fill?: TypeColor | OBJ_Texture;
+    corner?: OBJ_CurvedCorner;
+    space?: number;
+};
+/**
+  * @property {'x' | 'y' | 'xy'} [axis] which axis to zoom (`xy`)
+  * @property {number} [pinchSensitivity] pinch zoom sensitivity
+  * where >1 is more sensitive and <1 is less sensitive (`1`)
+  * @property {number} [wheelSensitivity] mouse wheel sensitivity
+  * where >1 is more sensitive and <1 is less sensitive (`1`)
+  * @property {TypeParsablePoint | number} [value] fix value to zoom on - will
+  * override pinch or mouse wheel zoom location
+  * @property {null | number} [min] minimum zoom where `null` is no limit
+  * (`null`)
+  * @property {null | number} [max] maximum zoom where `null` is no limit
+  * (`null`)
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotZoomOptions = {
+    axis?: 'x' | 'y' | 'xy';
+    wheelSensitivity?: number;
+    pinchSensitivity?: number;
+    value?: TypeParsablePoint | number;
+    min?: null | number;
+    max?: null | number;
+};
+/**
+  * @property {'x' | 'y' | 'xy'} [axis] which axis to zoom (`xy`)
+  * @property {number} [wheelSensitivity] mouse wheel sensitivity
+  * where >1 is more sensitive and <1 is less sensitive (`1`)
+  * @property {boolean} [wheel] enable mouse wheel to pan (`true`)
+  * @property {boolean} [momentum] enable panning momentum (`true`)
+  * @property {number} [maxVelocity] maximum panning velocity (`10`)
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotPanOptions = {
+    axis: 'x' | 'y' | 'xy';
+    wheelSensitivity?: number;
+    wheel?: boolean;
+    momentum?: boolean;
+    maxVelocity?: number;
+};
+/**
+ * An axis definition for a plot is the same as that for an
+ * {@link CollectionsAxis} with an additional property `location` which can be
+ * used to conveniently set the axis `position`. Note, if `position` is set in
+ * the axis definition, then it will override `location`.
+ *
+ * @extends {COL_Axis}
+ *
+ * @property {OBJ_PlotAxis} [location]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotAxis = {
+    location?: 'left' | 'right' | 'top' | 'bottom';
+} & COL_Axis;
+/**
+ * Plot area label buffer where a positive value is more buffer
+ * @property {number} [left]
+ * @property {number} [right]
+ * @property {number} [top]
+ * @property {number} [bottom]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotAreaLabelBuffer = {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+};
+export type OBJ_PlotAreaLabelBufferFixed = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+/**
+ * Plot title.
+ *
+ * {@link OBJ_TextLines}` & { offset: `{@link TypeParsablePoint}` }`
+ *
+ * Use `offset` to adjust the location of the title.
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PlotTitle = OBJ_FormattedText & {
+    offset: TypeParsablePoint;
+};
+/**
+ * {@link CollectionsPlot} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * A plot is a collection of axes and traces, and may include a title, legend
+ * and bounding frame.
+ *
+ * Use `width`, `height` and `position` to define the size of the plot area
+ * (area where the traces are drawn) and where it is in the figure.
+ *
+ * @extends OBJ_Collection
+ *
+ * @property {number} [width] width of the plot area
+ * @property {number} [height] height of the plot area
+ * @property {OBJ_PlotAxis | boolean} [x] customize the x axis, or use `false`
+ * to hide it
+ * @property {OBJ_PlotAxis | boolean} [y] customize the y axis, or use `false`
+ * to hide it
+ * @property {Array<OBJ_PlotAxis>} [axes] add axes additional to x and y
+ * @property {boolean} [grid] turn on and off the grid - use the grid options
+ * in x axis, y axis or axes for finer customization
+ * @property {OBJ_PlotTitle | string} [title] plot title can be simply a
+ * `string` or fully customized with OBJ_PlotTitle
+ * @property {Array<COL_Trace | TypeParsablePoint> | COL_Trace | Array<TypeParsablePoint>} [trace]
+ *  Use array if plotting more than one trace. Use COL_Trace to customize the
+ *  trace.
+ * @property {COL_PlotLegend | boolean} [legend] `true` to turn the legend on,
+ * or use COL_PlotLegend to customize it's location and layout
+ * @property {boolean | TypeColor | OBJ_PlotFrame} [frame] frame around the
+ * plot can be turned on with `true`, can be a simple color fill using
+ * `Array<number>` as a color, or can be fully customized with OBJ_PlotFrame
+ * @property {TypeColor | COL_Rectangle} [plotArea] plot area can be a
+ * color fill with `TypeColor` as a color, or be fully customized with
+ * COL_Rectangle
+ * @property {OBJ_Font} [font] Default font for plot (title, axes, labels, etc.)
+ * @property {TypeColor} [color] Default color
+ * @property {TypeParsablePoint} [position] Position of the plot
+ * @property {OBJ_PlotZoomOptions | 'x' | 'y' | 'xy'} [zoom] options for
+ * interactive zooming
+ * @property {OBJ_PlotPanOptions | 'x' | 'y' | 'xy'} [pan] options for
+ * interactive panning
+ * @property {TypeParsablePoint} [cross] value where the default x and y
+ * axes should cross. If defined, each `axis.position` will be overridden. If
+ * the cross point is outside of the plot area, then the axes will be drawn on
+ * the border of the plot area. (`undefined`)
+ * @property {boolean | OBJ_PlotAreaLabelBuffer} [plotAreaLabels] if `true`
+ * then axes with a cross point
+ * will be drawn such that the labels stay within the plot area. So, if the
+ * labels are on the left side of a y axis, and the cross point is out of the
+ * plot area to the left, then instead of the axis being drawn on the left edge
+ * of the plot area, it will be drawn within the plot area such that its labels
+ * are within the plot area (`false`).
+ * @property {boolean} [autoGrid] if `true` sets the grid for an axes to expand
+ * accross the entire plot area. Set to `false` if only a partial length grid
+ * is needed (`true`)
+ * @property {'box' | 'numberLine' | 'positiveNumberLine'} [styleTheme] defines
+ * default values for tick, label, axis locations and cross points. (`'box'`)
+ * @property {'light' | 'dark'} [colorTheme] defines defaul colors. `'dark'`
+ * theme is better on light backgrounds while '`light'` theme is better on dark
+ * backgrounds (`'dark'`)
+ * @property {OBJ_GestureArea} [gestureArea] the gesture area is the plot area
+ * by default. Use this property to extend the gesture area beyond the plot
+ * area. This is useful for the user to zoom in on areas on the edge of the
+ * plot area.
+ * @interface
+ * @group 2D Shape Collections
+ */
+export type COL_Plot = {
+    width?: number;
+    height?: number;
+    x?: OBJ_PlotAxis | boolean;
+    y?: OBJ_PlotAxis | boolean;
+    axes?: Array<OBJ_PlotAxis>;
+    cross?: TypeParsablePoint | null;
+    grid?: boolean;
+    title?: string | OBJ_PlotTitle;
+    trace?: Array<COL_Trace | TypeParsablePoint> | COL_Trace | Array<TypeParsablePoint>;
+    legend?: COL_PlotLegend;
+    frame?: boolean | TypeColor | OBJ_PlotFrame;
+    plotArea?: TypeColor | COL_Rectangle;
+    font?: OBJ_Font;
+    color?: TypeColor;
+    position?: TypeParsablePoint;
+    zoom?: OBJ_PlotZoomOptions | 'x' | 'y' | 'xy';
+    pan?: OBJ_PlotPanOptions | 'x' | 'y' | 'xy';
+    gestureArea?: OBJ_GestureArea;
+    autoGrid?: boolean;
+    plotAreaLabels?: boolean | OBJ_PlotAreaLabelBuffer;
+    styleTheme?: 'box' | 'numberLine' | 'positiveNumberLine';
+    colorTheme?: 'light' | 'dark';
+} & OBJ_Collection;
+/**
+ * {@link FigureElementCollection} representing a plot including axes, traces,
+ * labels and titles.
+ *
+ * ![](./apiassets/advplot_ex1.png)
+ *
+ * ![](./apiassets/advplot_ex2.png)
+ *
+ * ![](./apiassets/advplot_ex3.png)
+ *
+ * ![](./apiassets/advplot_ex4.png)
+ *
+ * ![](./apiassets/advplot_ex5.png)
+ *
+ * ![](./apiassets/advplot_ex6.png)
+ *
+ * ![](./apiassets/advplot_zoom.gif)
+ *
+ * This object provides convient and customizable plot functionality.
+ *
+ * At its simplist, just the points of the trace to be plotted need to be
+ * passed in to get a plot with automatically generated axes, tick marks,
+ * labels and grid lines.
+ *
+ * Additional options can be used to finely customize each of these, as well
+ * as add and customize plot and axis titles, a legend, and a frame around the
+ * entire plot.
+ *
+ * Plots can also be interactive, with both zoom and pan functionality from
+ * mouse, mouse wheel, touch and pinch gestures.
+ *
+ * @see
+ * See {@link COL_Axis}, {@link OBJ_AxisLabels}, {@link OBJ_AxisTicks},
+ * {@link COL_Trace} and {@link COL_PlotLegend} for more examples of customizing
+ * specific parts of the plot.
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ * All examples below also use this power function to generate the traces:
+ * ```javascript
+ * const pow = (pow = 2, start = 0, stop = 10, step = 0.05) => {
+ *   const xValues = Fig.range(start, stop, step);
+ *   return xValues.map(x => new Fig.Point(x, x ** pow));
+ * }
+ * ```
+ * @example
+ * // Plot of single trace with auto axis scaling
+ * figure.add({
+ *   make: 'collections.plot',
+ *   trace: pow(),
+ * });
+ *
+ * @example
+ * // Multiple traces with a legend
+ * // Some traces are customized beyond the default color to include dashes and
+ * // markers
+ * figure.add({
+ *   make: 'collections.plot',
+ *   width: 2,                                    // Plot width in figure
+ *   height: 2,                                   // Plot height in figure
+ *   y: { start: 0, stop: 50 },                   // Customize y axis limits
+ *   trace: [
+ *     { points: pow(1.5), name: 'Power 1.5' },   // Trace names are for legend
+ *     {                                          // Trace with only markers
+ *       points: pow(2, 0, 10, 0.5),
+ *       name: 'Power 2',
+ *       markers: { sides: 4, radius: 0.03 },
+ *     },
+ *     {                                          // Trace with markers and
+ *       points: pow(3, 0, 10, 0.5),              // dashed line
+ *       name: 'Power 3',
+ *       markers: { radius: 0.03, sides: 10, line: { width: 0.005 } },
+ *       line: { dash: [0.04, 0.01] },
+ *     },
+ *   ],
+ *   legend: true,
+ * });
+ *
+ * @example
+ * // Multiple grids and simple titles
+ * figure.add({
+ *   make: 'collections.plot',
+ *   y: {
+ *     start: -50,
+ *     stop: 50,
+ *     step: [25, 5],
+ *     grid: [
+ *       true,
+ *       { width: 0.005, dash: [0.01, 0.01], color: [1, 0.7, 0.7, 1] },
+ *     ],
+ *     title: 'velocity (m/s)',
+ *   },
+ *   x: {
+ *     start: -5,
+ *     stop: 5,
+ *     step: [2.5, 0.5, 0.1],
+ *     grid: [
+ *       true,
+ *       { width: 0.005, dash: [0.01, 0.01], color: [1, 0.7, 0.7, 1] },
+ *     ],
+ *     title: 'time (s)',
+ *   },
+ *   trace: pow(3, -10, 10),
+ *   title: 'Velocity over Time',
+ * });
+ *
+ * @example
+ * // Hide axes
+ * // Use plot frame and plot area
+ * // Title has a subtitle
+ * figure.add({
+ *   make: 'collections.plot',
+ *   trace: pow(3),
+ *   x: { show: false },
+ *   y: { show: false },
+ *   plotArea: [0.93, 0.93, 0.93, 1],
+ *   frame: {
+ *     line: { width: 0.005, color: [0.5, 0.5, 0.5, 1] },
+ *     corner: { radius: 0.1, sides: 10 },
+ *     space: 0.15,
+ *   },
+ *   title: {
+ *     text: [
+ *       'Velocity over Time',
+ *       { text: 'For object A', lineSpace: 0.13, font: { size: 0.08 } },
+ *     ],
+ *     offset: [0, 0],
+ *   },
+ * });
+ *
+ * @example
+ * // Secondary y axis
+ * figure.add({
+ *   make: 'collections.plot',
+ *   trace: pow(2),
+ *   y: {
+ *     title: {
+ *       text: 'velocity (m/s)',
+ *       rotation: 0,
+ *       xAlign: 'right',
+ *     },
+ *   },
+ *   x: { title: 'time (s)' },
+ *   axes: [
+ *     {
+ *       axis: 'y',
+ *       start: 0,
+ *       stop: 900,
+ *       step: 300,
+ *       color: [1, 0, 0, 1],
+ *       location: 'right',
+ *       title: {
+ *         offset: [0.6, 0.1],
+ *         text: 'displacment (m)',
+ *         rotation: 0,
+ *       },
+ *     },
+ *   ],
+ *   position: [-1, -1],
+ * });
+ *
+ * @example
+ * // Cartesian axes crossing at the zero point
+ * // Automatic layout doesn't support this, but axes, ticks, labels and titles
+ * // can all be customized to create it.
+ * figure.add({
+ *   make: 'collections.plot',
+ *   trace: pow(3, -10, 10),
+ *   font: { size: 0.1 },
+ *   styleTheme: 'numberLine',
+ *   x: {
+ *     title: {
+ *       text: 'x',
+ *       font: { style: 'italic', family: 'Times New Roman', size: 0.15 },
+ *     },
+ *   },
+ *   y: {
+ *     step: 500,
+ *     title: {
+ *       text: 'y',
+ *       font: { style: 'italic', family: 'Times New Roman', size: 0.15 },
+ *     },
+ *   },
+ *   grid: false,
+ * });
+ *
+ * @example
+ * // Zoomable and Pannable plot
+ *
+ * // Create the points for the plot
+ * const points = Array(3000).fill(0).map(() => {
+ *   const x = Math.random() * 8 - 4;
+ *   const y = Math.random() / Math.sqrt(2 * Math.PI) * Math.exp(-0.5 * x ** 2);
+ *   return [x, y];
+ * });
+ *
+ * // Make a zoomable and pannable plot
+ * const plot = figure.add({
+ *   make: 'collections.plot',
+ *   trace: { points, markers: { sides: 6, radius: 0.01 } },
+ *   zoom: { axis: 'xy', min: 0.5, max: 16 },
+ *   pan: true,
+ * });
+ *
+ * // Initialize by zooming in by a magnification factor of 10
+ * plot.zoomValue([1.8333, 0.06672], 10);
+ *
+ * @group 2D Shape Collections
+ */
+declare class CollectionsPlot extends FigureElementCollection {
+    _x: CollectionsAxis | null | undefined;
+    _y: CollectionsAxis | null | undefined;
+    __frame: CollectionsRectangle | null | undefined;
+    axes: Array<CollectionsAxis>;
+    traces: Array<CollectionsTrace>;
+    cross: null | Point;
+    defaultFont: OBJ_Font_Fixed;
+    width: number;
+    height: number;
+    colorTheme: string;
+    styleTheme: string;
+    grid: boolean;
+    xAxisShow: boolean;
+    yAxisShow: boolean;
+    frameSpace: number | null | undefined;
+    zoom: {
+        x: boolean;
+        y: boolean;
+        enabled: boolean;
+        min: null | number;
+        max: null | number;
+    };
+    pan: {
+        x: boolean;
+        y: boolean;
+        enabled: boolean;
+    };
+    autoGrid: boolean;
+    plotAreaLabels: boolean | OBJ_PlotAreaLabelBufferFixed;
+    forceColor: null | TypeColor;
+    zoomPoint: null | Point;
+    gestureArea: {
+        left: number;
+        bottom: number;
+        top: number;
+        right: number;
+    };
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: COL_Plot);
+    setupCross(): void;
+    setupGrid(): void;
+    showGrid(): void;
+    hideGrid(): void;
+    getNonTraceBoundingRect(): Rect;
+    addAxes(axes: Array<OBJ_PlotAxis>): void;
+    addPlotArea(plotArea: Array<number> | COL_Rectangle): void;
+    addGestureRectangle(zoomOptions: OBJ_PlotZoomOptions | 'xy' | 'x' | 'y' | false, panOptions: OBJ_PlotPanOptions | 'xy' | 'x' | 'y' | false, xAxis: OBJ_PlotAxis, yAxis: OBJ_PlotAxis): void;
+    addFrame(frameIn: OBJ_PlotFrame | true | TypeColor): void;
+    fontUpdated(): void;
+    update(): void;
+    getTraceIndex(name: string | number): number;
+    addLegend(legendOptions: COL_PlotLegend | boolean): void;
+    getAxis(name: string): CollectionsAxis | null;
+    getXAxis(): CollectionsAxis | null;
+    getYAxis(): CollectionsAxis | null;
+    /**
+     * Convert a plot point value on the axes `yAxisName` and `xAxisName` to
+     * a plot draw space position.
+     *
+     * The plot draw space is (0, 0) at the bottom
+     * left of the plot area and extends to (`width`, `height`) in the top right
+     * corner of the plot area where `width` and `height` are defined when
+     * creating the plot.
+     * @param {TypeParsablePoint} point
+     * @param {string = 'x'} xAxisName
+     * @param {string = 'y'} yAxisName
+     */
+    pointToDraw(point: TypeParsablePoint, xAxisName?: string, yAxisName?: string): Point;
+    /**
+     * Convert a plot draw space position to a plot point value on the axes
+     * `yAxisName` and `xAxisName`.
+     *
+     * The plot draw space is (0, 0) at the bottom
+     * left of the plot area and extends to (`width`, `height`) in the top right
+     * corner of the plot area where `width` and `height` are defined when
+     * creating the plot.
+     * @param {TypeParsablePoint} drawSpacePoint
+     * @param {string = 'x'} xAxisName
+     * @param {string = 'y'} yAxisName
+     */
+    drawToPoint(drawSpacePoint: TypeParsablePoint, xAxisName?: string, yAxisName?: string): Point;
+    /**
+     * Set a figure element's position to the position in the figure where some
+     * point on the plot is.
+     * @param {FigureElement} element
+     * @param {TypeParsablePoint} point
+     */
+    setElementTo(element: FigureElement, point: TypeParsablePoint): void;
+    /**
+     * Get the plot value where some element is.
+     * @param {FigureElement} element
+     */
+    getPointAtElement(element: FigureElement): Point;
+    addTraces(traces: Array<COL_Trace>): void;
+    updateTraces(): void;
+    getStyleTheme(name: string, axis?: 'x' | 'y', location?: null | 'left' | 'bottom' | 'right' | 'top' | undefined): Record<string, any>;
+    getColorTheme(name: string, defaultColor?: TypeColor | null): Record<string, any>;
+    addTitle(optionsIn: OBJ_FormattedText & {
+        offset: TypeParsablePoint;
+    } | string): void;
+    panDeltaValue(deltaValueIn: TypeParsablePoint): void;
+    panDeltaDraw(deltaDrawIn: TypeParsablePoint): void;
+    panToValue(value: TypeParsablePoint, atDraw: TypeParsablePoint): void;
+    zoomValue(valueIn: TypeParsablePoint, mag: number): void;
+    zoomDelta(valueIn: TypeParsablePoint, magDelta: number): void;
+    /**
+     * Get the current zoom.
+     * @return {number}
+     */
+    getZoom(): any;
+    /**
+     * Get the current pan.
+     * @return {Point}
+     */
+    getPan(): Point;
+}
+export default CollectionsPlot;