figureone
    Preparing search index...

    Class default

    Primary Figure class.

    A figure will attach a WebGL canvas and 2D canvas to the html div element with id "figureOneContainer".

    The figure creates and manages all drawing elements, renders the drawing elements on a browser's animation frames and listens for guestures from the user.

    The figure also has a recorder, allowing it to record and playback states, and gestures.

    To attach to a different div, use the htmlId property in the class constructor.

    If a figure is paused, then all drawing element animations will also be paused.

    Figure has a number of convenience methods for creating drawing elements and useful transforms for converting between the different spaces (e.g. pixel, GL, figure).

    Notifications - The notification manager property notifications will publish the following events:

    • beforeDraw: published before a frame is drawn
    • afterDraw: published after a frame is drawn
    • resize: published after a resize event, but before frame drawing
    // Simple html and javascript example to create a figure, and add a
    // hexagon.
    //
    // For additional examples, see https://github.com/airladon/FigureOne
    //
    // Two files `index.html` and `index.js` in the same directory

    // index.html
    <!doctype html>
    <html>
    <body>
        <div id="figureOneContainer" style="width: 800px; height: 800px; background-color: white;">
        </div>
        <script type="text/javascript" src='https://cdn.jsdelivr.net/npm figureone@0.15.10/figureone.min.js'></script>
        <script type="text/javascript" src='./index.js'></script>
    </body>
    </html>

    // index.js
    const figure = new Fig.Figure({ scene: [-1, -1, 1, 1 ]});
    figure.add(
      {
        name: 'p',
        make: 'polygon',
        radius: 0.5,
        sides: 6,
      },
    );

    // Alternately, an element can be added programatically
    // index.js
    const figure = new Fig.Figure({ scene: [-1, -1, 1, 1 ]});
    const hex = figure.shapes.polygon({
      radius: 0.5,
      sides: 6,
    });
    figure.add('hexagon', hex);
    Index

    Methods

    addSlideNavigator getSlideNavigator addCursor getCursor add getElement getElements get recreateAtlases spaceTransformMatrix transformPoint getRemainingAnimationTime show hide showOnly setScenarios stop showTouchable showTouchBorders showBorders animateNextFrame isAnimating setManualFrames endManualFrames frame addFrameRate

    Methods

    • Get the CollectionsSlideNavigator for the figure (will only return if the navigator was added with figure.addSlideNavigator).

      Returns any

    • Add cursor for recording interactive videos. Cursor will be hidden when first added.

      Parameters

      Returns any

      cursor element

    • Add a figure element to the root collection of the figure.

      If adding an array of elements, then the added elements will be returned in an array (even if only one element is added). If not adding an array, then that single element will be returned.

      Parameters

      Returns any

      added element, or array of added elements

      // Add name and element
      const element = figure.primitives.polygon({ radius: 1 });
      figure.add('name', element);

      // Element only (name will be autogenerated)
      const element = figure.primitives.polygon({ radius: 1 });
      figure.add(element);

      // Element definition (if no name is provided, then name will
      // be auto generated)
      figure.add({
        make: 'polygon',
        radius: 1,
      });

      // Array of elements
      const element = figure.primitives.polygon({ radius: 1 });
      figure.add([
        element,
        {
          make: 'polygon',
          radius: 0.2,
          color: [0, 0, 1, 1],
        },
      ]);

    • Get element from an element path with '.' separators.

      For instance, if a collection has a child collection 'a', which has a child primitive 'b', then the path would be: 'a.b'.

      Parameters

      • elementName: string

      Returns any

      element at path. If elementPath is null, then the figure's base collection is returned. If elementPath is invalid then null is returned.

      element.getElement

      // Get all the elements from a figure
      figure.add(
        {
          name: 'c',
          make: 'collection',
          elements: [
            {
              name: 'tri',
              make: 'triangle',
              height: 0.4,
              width: 0.4,
            },
            {
              name: 'text',
              make: 'text',
              text: 'triangle',
              position: [0, -0.4],
              xAlign: 'center',
            },
          ],
        },
      );

      const c = figure.getElement('c');
      // Elements within collections can be found with dot notation
      const tri = figure.getElement('c.tri');
      // Or the collection can be queried directly
      const text = c.getElement('text');

    • Recreate all automatically generated atlases.

      This would be typically used after loading custom fonts.

      Returns void

    • Return matrix that can convert between 'pixel', 'figure' and 'gl' spaces.

      These matrices would be generally used to transform points between spaces. transformPoint can be used to do this for individual points, but if converting many points, then generating the transform matrix once and applying it to each point can be more efficient.

      Depending on the type of figure scene, not all space combinations are possible.

      For 2D scenes, all combinations are possible.

      For 3D scenes:

      • 'pixel' to 'gl' will transform a point in pixel space to a point on the XY plane at Z = 0 in GL space.
      • 'pixel' to 'figure' is not valid. Use transformPoint instead where a plane can be defined to intersect with.
      • Conversions between 'gl' and 'figure' are only valid for 'orthographic' projections. For perspective projections, the transform matrix is not general and depends coordinates of the point to be transformed. Use transformPoint for each point to be transformed.

      Parameters

      • from: "figure" | "pixel" | "gl"
      • to: "figure" | "pixel" | "gl"

      Returns Type3DMatrix

    • Transform a point between 'figure', 'gl' and 'pixel' spaces.

      plane is only needed when converting from pixel space (a 2D space) to 'figure' space or 'gl' space (a 3D space). A ray from the pixel is drawn into the screen and the intersection with the defined plane is returned.

      Parameters

      • point: TypeParsablePoint
      • fromSpace: "figure" | "pixel" | "gl"

        space to convert point from

      • toSpace: "figure" | "pixel" | "gl"

        space to convert point to

      • plane: TypeParsablePlane = ...

        figure space intersection plane for 'pixel' to 'figure' conversion (default: xy plane at z = 0)

      Returns Point

    • Get remaining animation durations of running animations

      Parameters

      • nowIn: number = ...

      Returns number | null

    • Set scenarios of all elements with scenarioName defined

      Parameters

      • scenarioName: string
      • onlyIfVisible: boolean = false

      Returns void

    • Stop all animations, movement and pulses in figure.

      Parameters

      • how: "cancel" | "complete" | "freeze" | "animateToComplete" | "dissolveToComplete" = 'cancel'

      Returns void

    • Debug - 3D Shapes

      Show touchable 3D shapes in figure. This will only last for one animation frame, so it will not work if an animation is ongoing.

      Note, the shown borders will be for the instant this method is called only. If animation is ongoing, the shown borders will not move with the animation. To update the borders, call this method again.

      Returns void

    • Debug - 2D Shapes

      Show the touchBorders of selected elements in the figure or all elements in the figure.

      Note, the shown borders will be for the instant this method is called only. If animation is ongoing, the shown borders will not move with the animation. To update the borders, call this method again.

      Parameters

      • element: TypeElementPath | null = 'touchable'

        use null for all elements, touchable for all touchable elements or define specific elements to show ('touchable')

      • colors: TypeColor[] = ...

        array of colors to cycle through for each shape ([blue, cyan, purple, green, red, yellow, black])

      Returns void

    • Debug - 2D Shapes

      Show the borders or touchBorders of selected elements in the figure or all elements in the figure.

      Parameters

      • border: "border" | "touchBorder" = 'border'

        ('border')

      • element: TypeElementPath | null = null

        use null for all elements, touchable for all touchable elements or define specific elements to show (null)

      • colors: TypeColor[] = ...

        array of colors to cycle through for each shape ([blue, cyan, purple, green, red, yellow, black])

      Returns void

    • Force figure to draw on next available animation frame.

      Parameters

      • draw: boolean = true
      • fromWhere: string = ''

      Returns void

    • Sets manual frames.

      Normally, when a browser is ready to refresh the screen it will call FigureOne to do a draw. The time between frames is not fixed and depends on a number of factors. This is the most performant way to handle drawing.

      However, when debugging it can be useful to manually trigger a draw frame with a defined delta time from the last frame.

      This method turns on manual frames. Use frame to trigger a draw.

      Returns void

    • Manually trigger a draw frame with a specified time step (in seconds) from the last draw frame. Can only be used when setManualFrames() has been called.

      Parameters

      • timeStep: number

        in seconds

      Returns void

    • Add a frame rate annotation to the figure.

      Each time the browser requests FigureOne to paint the screen, FigureOne performs two main tasks:

      • setup the figure for a draw (setupDraw) - all visible figure elements are iterated through and if they are animating or moving then their next animation or movement frame is calculated
      • draw the figure elements (draw)

      Frame rate is determined by FigureOne's total frame processing time (setupDraw time + draw time), and how frequently a browser requests FigureOne to draw a frame.

      The frame rate will not be faster than the browser wants, but it can be slower if the total frame processing time is too long.

      The frame rate and time durations are reported as both an average, and worst case (max). The averaging is done over numFrames number of frames.

      The screen output is then:

      • Ave: F fsp, T ms (S, D)
      • Max: F fsp, T ms (S, D)

      Where:

      • F: Frames per second
      • T: Total frame processing time
      • S: setupDraw processing time
      • D: draw processing time

      Note: FigureOne only requests animation frame notifications from the browser when an element is animating or moving. If everything is still, then the frame rate will be 0.

      Parameters

      Returns any

    Settings

    Member Visibility

    On This Page

    Methods