figureone 0.15.10 → 1.0.0

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

@@ -0,0 +1,237 @@
+import { Point } from '../../tools/g2';
+import type { TypeParsablePoint } from '../../tools/g2';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import type CollectionsAxis from './Axis';
+import type { COL_Axis } from './Axis';
+import type { OBJ_Line, OBJ_Polygon, OBJ_Star } from '../FigurePrimitives/FigurePrimitiveTypes2D';
+import type { OBJ_LineStyleSimple, OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type { TypeColor, OBJ_Font_Fixed } from '../../tools/types';
+import type { CPY_Steps } from '../geometries/copy/copy';
+import type FigureCollections from './FigureCollections';
+/**
+ * {@link CollectionsTrace} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * A plot trace is a set of (x, y) points associated with an
+ * x and y axis.
+ *
+ * The trace and can be drawn with either a set of
+ * `markers` at each point, or a `line` between each pair of adjacent points.
+ *
+ * The axes are used to plot the trace - the trace
+ * can only appear within the bounds of the axes, and the axes
+ * provide the mapping from axis value to draw space so the trace
+ * can be drawn. Points that lie outside the axis will not be draw,
+ * and lines between pairs of points where one is outside will be interpolated.
+ *
+ * While FigureOne isn't designed to process very large numbers of points,
+ * some steps can be taken to improve performance when large numbers of points
+ * are being used (tens of thousands or more):
+ * - Turn off corner interpolation between line segments in `line`:
+ *   `{ line: { corner: 'none` } }`
+ * - Use `xSampleDistance` and `ySampleDistance` to not draw points that are
+ *   too close to each other
+ * - If using markers, use polygons with smaller numbers of sides, and use fills
+ *   instead of outlines
+ *
+ * Even using these methods, it can take up to a second to render a trace with
+ * hundreds of thousands of points (depending on the client device).
+ *
+ * @extends OBJ_Collection
+ *
+ * @property {Array<TypeParsablePoint>} points the x points of the trace
+ * @property {COL_Axis | string} [xAxis] The x axis associated with the trace,
+ * if this is a string, the trace must be part of a plot with an axis with the
+ * same name. In plots, this will default to the string `'x'`.
+ * @property {COL_Axis | string} [yAxis] The y axis associated with the trace,
+ * if this is a string, the trace must be part of a plot with an axis with the
+ * same name. In plots, this will default to the string `'y'`.
+ * @property {OBJ_LineStyleSimple} [line] line style of the trace - if neither `line` nor
+ * `markers` is defined, then `line` will default to a solid line. If `line`
+ * is not defined, but `markers` is, then only markers will be used to represent
+ * the line
+ * @property {OBJ_Polygon | OBJ_Star} [markers] marker style of the trace
+ * @property {TypeColor} [color] color of the trace
+ * @property {string} [name] name of the trace used in plot legends
+ * @property {number} [xSampleDistance] If x distance between points is less
+ * than this value, then the later point will not be plotted. By default this is
+ * 1/4000th the range of the x axis
+ * @property {number} [ySampleDistance] If y distance between points is less
+ * than this value, then the later point will not be plotted. By default this is
+ * 1/4000th the range of the y axis
+ *
+ * @see
+ * For more examples on using traces, see {@link CollectionsPlot}
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ * @interface
+ * @group Misc Shapes
+ */
+export type COL_Trace = {
+    points: Array<TypeParsablePoint>;
+    xAxis?: COL_Axis | string;
+    yAxis?: COL_Axis | string;
+    x?: Array<TypeParsablePoint>;
+    y?: Array<TypeParsablePoint>;
+    line?: OBJ_LineStyleSimple;
+    markers?: OBJ_Polygon | OBJ_Star;
+    color?: TypeColor;
+    name?: string;
+    xSampleDistance?: number;
+    ySampleDistance?: number;
+} & OBJ_Collection;
+/**
+ * {@link FigureElementCollection} representing a trace.
+ *
+ * ![](./apiassets/advtrace_ex1.png)
+ * ![](./apiassets/advtrace_ex2.png)
+ *
+ * ![](./apiassets/advtrace_ex3.png)
+ * ![](./apiassets/advtrace_ex4.png)
+ *
+ * ![](./apiassets/advtrace_ex5.png)
+ * ![](./apiassets/advtrace_ex6.png)
+ *
+ * This object defines a trace in an {@link CollectionsPlot}.
+ *
+ * The trace includes all the points of the trace, and the axes that it
+ * should be drawn against and is defined using the {@link COL_PlotTrace}
+ * options object.
+ *
+ * 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
+ * // When plotting a single trace, just the points are required. By default
+ * // the line will be solid, and it will be plotted against the 'x' and 'y' axes.
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: pow(),
+ * });
+ *
+ * @example
+ * // Change the thickness and color of the line
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: {
+ *     points: pow(),
+ *     line: {
+ *       width: 0.03,
+ *       color: [0, 0.8, 0.4, 1],
+ *     }
+ *   },
+ * });
+ *
+ * @example
+ * // Default Markers
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: {
+ *     points: pow(2, 0, 10, 1),
+ *     markers: true,
+ *   },
+ * });
+ *
+ * @example
+ * // Custom Markers
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: {
+ *     points: pow(2, 0, 10, 1),
+ *     markers: {
+ *       radius: 0.035,
+ *       sides: 20,
+ *       line: { width: 0.01 },
+ *     },
+ *   },
+ * });
+ *
+ * @example
+ * // Line and markers
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: {
+ *     points: pow(2, 0, 10, 1),
+ *     line: { width: 0.01, dash: [0.02, 0.01] },
+ *     markers: {
+ *       radius: 0.035,
+ *       sides: 20,
+ *     },
+ *   },
+ * });
+ *
+ * @example
+ * // Use names in trace definitions to customize legend
+ * figure.add({
+ *   name: 'plot',
+ *   make: 'collections.plot',
+ *   trace: [
+ *     pow(2),
+ *     { points: pow(2.5), name: 'Power 2.5' },
+ *     {
+ *       points: pow(3, 0, 10, 1),
+ *       name: 'Power 3',
+ *       markers: { radius: 0.03 },
+ *       line: { width: 0.01 },
+ *     },
+ *   ],
+ *   legend: true,
+ * });
+ * @group Misc Shapes
+ */
+declare class CollectionsTrace extends FigureElementCollection {
+    _line: FigureElementPrimitive | null | undefined;
+    points: Array<Point>;
+    drawPoints: Array<Point>;
+    polylines: Array<Array<Point>>;
+    xAxis: CollectionsAxis;
+    yAxis: CollectionsAxis;
+    line: OBJ_Line;
+    defaultFont: OBJ_Font_Fixed;
+    xSampleDistance: number;
+    ySampleDistance: number;
+    markers: (OBJ_Polygon | OBJ_Star) & {
+        copy: CPY_Steps;
+    };
+    name: string;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: COL_Trace);
+    /**
+     * Update the trace with a new set of points.
+     * @param {Array<TypeParsablePoint>} points
+     */
+    update(points: Array<TypeParsablePoint>): void;
+    updateAxes(): void;
+    getY(xValue: number, precision?: number): number[];
+    getX(yValue: number, precision?: number): number[];
+    pointToDraw(p: Point): Point;
+    inAxes(p: Point): boolean;
+    intersect(p1: Point, p2: Point): {
+        result: boolean;
+        intersect?: Array<Point>;
+    };
+    updatePoints(): void;
+    addLine(options: OBJ_LineStyleSimple): void;
+    removeLine(): void;
+    removeMarkers(): void;
+    addMarkers(options: OBJ_Polygon | OBJ_Star): void;
+    _getStateProperties(options: Record<string, any>): string[];
+}
+export default CollectionsTrace;

package/types/js/figure/FigurePrimitives/FigureElementPrimitive2DText.d.ts

@@ -0,0 +1,119 @@
+import { FigureElementPrimitive } from '../Element';
+import type { FigureElement } from '../Element';
+import { Point, Rect } from '../../tools/g2';
+import type { Transform } from '../../tools/g2';
+import type Scene from '../../tools/geometry/scene';
+import type { Type3DMatrix } from '../../tools/m3';
+import DrawingObject from '../DrawingObjects/DrawingObject';
+import { FigureFont } from '../DrawingObjects/TextObject/TextObject';
+import type { OBJ_Font, TypeColor } from '../../tools/types';
+import type { OBJ_Text, OBJ_SetText } from './FigurePrimitiveTypes';
+import type DrawContext2D from '../DrawContext2D';
+declare class TextObject extends DrawingObject {
+    drawContext2D: DrawContext2D;
+    scalingFactor: number;
+    lastDrawTransform: Array<number>;
+    bounds: Rect;
+    textBorder: Array<Array<Point>>;
+    text: Array<string>;
+    location: any;
+    alignedLocation: Array<Point>;
+    font: FigureFont;
+    xAlign: 'left' | 'center' | 'right';
+    yAlign: 'top' | 'bottom' | 'middle' | 'alphabetic' | 'baseline';
+    measure: {
+        ascent: number;
+        descent: number;
+        width: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        border: Array<Array<Point>>;
+    };
+    measurements: Array<{
+        left: number;
+        right: number;
+        bottom: number;
+        top: number;
+    }>;
+    lastDraw: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    adjustments: {
+        ascent: number;
+        descent: number;
+        width: number;
+    };
+    constructor(drawContext2D: DrawContext2D, options: OBJ_Text);
+    watch(callback: string | (() => void)): void;
+    getCanvas(): HTMLCanvasElement;
+    calcScalingFactor(): void;
+    setText(text: Array<string> | string | OBJ_SetText): void;
+    setFont(font: OBJ_Font): void;
+    measureText(ctx?: CanvasRenderingContext2D, scalingFactor?: number): {
+        ascent: number;
+        descent: number;
+        width: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        border: Array<Array<Point>>;
+    };
+    calcBorder(): void;
+    drawWithTransformMatrix(scene: Scene, worldMatrix: Type3DMatrix, color?: TypeColor): void;
+    clear(): void;
+    _state(): Record<string, any>;
+}
+/**
+ * FigureElementPrimitive that handles drawing text on a 2D canvas.
+ * @group Misc Text
+ */
+export default class FigureElementPrimitive2DText extends FigureElementPrimitive {
+    drawingObject: TextObject;
+    constructor(drawContext2D: DrawContext2D, options: OBJ_Text & {
+        parent: null | FigureElement;
+        transform: Transform;
+        color: TypeColor;
+        name: string;
+    });
+    /**
+     * Change the text in the primitive.
+     *
+     * @param {string | OBJ_SetText} text
+     */
+    setText(text: string | OBJ_SetText): void;
+    calcBorderAndBounds(): void;
+    calcBorder(): void;
+    calcTouchBorder(): void;
+    /**
+     * Change only the font of the text.
+     *
+     * @param {OBJ_Font} font
+     */
+    setFont(font: OBJ_Font): void;
+    /**
+     * Get the text shown by the primitive.
+     *
+     * @return {string}
+     */
+    getText(): string;
+    /**
+     * Get the font of the text.
+     *
+     * @return {FigureFont}
+     */
+    getFont(): FigureFont;
+    setColor(color: TypeColor, setDefault?: boolean): void;
+    stateSet(): void;
+    measureAndAlignText(): void;
+    _getStateProperties(options: {
+        ignoreShown?: boolean;
+    }): string[];
+    getFonts(): (string | boolean | FigureFont)[][];
+}
+export {};

package/types/js/figure/FigurePrimitives/FigureElementPrimitiveGLText.d.ts

@@ -0,0 +1,94 @@
+import { FigureElementPrimitive } from '../Element';
+import { Point } from '../../tools/g2';
+import type GLObject from '../DrawingObjects/GLObject/GLObject';
+import { FigureFont } from '../DrawingObjects/TextObject/TextObject';
+import type { OBJ_Font, TypeColor } from '../../tools/types';
+import Scene from '../../tools/geometry/scene';
+import type { OBJ_Text_Fixed, OBJ_SetText } from './FigurePrimitiveTypes';
+/**
+ * FigureElementPrimitive that handles drawing text in WebGL.
+ *
+ * WebGL text is rendered using a texture atlas of fonts - an image
+ * with all the glyphs, and a map of the locations, ascent, descent and width
+ * of each glyph.
+ * @group Misc Text
+ */
+export default class FigureElementPrimitiveGLText extends FigureElementPrimitive {
+    text: Array<string>;
+    font: FigureFont;
+    atlas: Record<string, any>;
+    adjustments: {
+        width: number;
+        descent: number;
+        ascent: number;
+    };
+    measure: {
+        ascent: number;
+        descent: number;
+        width: number;
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+        border: Array<Array<Point>>;
+    };
+    location: Array<Point>;
+    fontSize: number;
+    xAlign: 'left' | 'center' | 'right';
+    yAlign: 'top' | 'bottom' | 'middle' | 'alphabetic' | 'baseline';
+    drawingObject: GLObject;
+    atlasNotificationsID: number;
+    setup(options: OBJ_Text_Fixed): void;
+    createAtlas(sceneIn?: Scene): void;
+    /**
+     * Debug method - will replace the drawn text with the texture atlas so it
+     * can be reviewed.
+     *
+     * @param {number} dimension size of the texture atlas to draw (`1`)
+     */
+    showMap(dimension?: number): void;
+    /**
+     * Recreate texture atlas.
+     *
+     * This is useful if a font has changed after an atlas has been
+     * auto-generated. Recreating the atlas will use the new version of the
+     * font.
+     */
+    recreateAtlas(): void;
+    loaded(): void;
+    measureAndAlignText(): void;
+    /**
+     * Change the text in the primitive.
+     *
+     * @param {string | OBJ_SetText} text
+     */
+    setText(text: string | Array<string> | OBJ_SetText): void;
+    /**
+     * Get the text shown by the primitive.
+     *
+     * @return {string}
+     */
+    getText(): string;
+    /**
+     * Get the font of the text.
+     *
+     * @return {FigureFont}
+     */
+    getFont(): FigureFont;
+    /**
+     * Change only the font of the text.
+     *
+     * @param {OBJ_Font} font
+     */
+    setFont(font: OBJ_Font): void;
+    setColor(color: TypeColor, setDefault?: boolean): void;
+    calcBorderAndBounds(): void;
+    calcBorder(): void;
+    stateSet(): void;
+    cleanup(): void;
+    calcTouchBorder(): void;
+    _getStateProperties(options: {
+        ignoreShown?: boolean;
+    }): string[];
+    getFonts(): (string | boolean | FigureFont)[][];
+}