Figure

In Kontrast, a figure is the main container for each interactive visualization. A figure usually contains one or more graphs, which are positioned on a grid within the figure. Each figure is attached to a single HTML element. A figure can be exported as a PNG file.

As an example on how to create a figure and how to populate it with graphs, you can also refer to the tutorial.

The minimal JavaScript code required to create a figure is:

And the corresponding HTML code is:

Note that we use the padding-top CSS property on the figure element to maintain a constant aspect ratio of the figure. In this example the aspect ratio is 1:2.

The default CSS style for the figure HTML element used in these documentation and example pages is:

Interface

Functions

• createGraph(options: object): KontrastGraph
  Create a graph and set its properties according to the specified options.
• destroyGraph(name: string)
  Destroy the graph specified by its name.
• pause()
  Pause the rendering of the figure. This can be used to use less resources (for example when the figure is hidden) and to block user interactions.
  Example: Pause and resume the rendering of a figure
• resume()
  Resume the rendering of the figure. If the figure has been suspended due to a WebGL context loss event, this function will also try to restore the WebGL context and reactivate the figure.
  Example: Pause and resume the rendering of a figure
• renderPNG(options: object)
  Export the figure as a PNG image. Note that the PNG export works in Firefox, Chrome and Safari, but not in Edge. Moreover, due to security restriction when loading fonts, the PNG export only works when the files are served over the HTTP or HTTPS protocol (not via file://).
• renderHTML(options: object)
  Export the figure as HTML (using an image and a separate text layer).

Properties

• settled: Promise

  A promise that resolves when the figure is settled. The figure is settled when the value of all properties are synchronized with the background worker used within the Kontrast library. This becomes important when reading out properties that are determined asynchronously, i.e., the minimum and maximum of an axis when using the showEverything function or the captureView function.

• name: KontrastName

  The name of the figure. The name has to be unique within the HTML page the figure belongs to. The name must not be empty and must not contain a dot, colon, semicolon or a hash (#). The name defaults to figureN, where N is a non-negative integer. We recommend you choose a meaningful name for each figure, so that it can be easily accessed via the development console or the Kontrast menu.

• backgroundColor: KontrastColor (default value: 'white')

  The background color of the figure.

• backgroundOpacity: KontrastNumber (default value: 1)

  The opacity of the figure background.

• element: KontrastElement

  The HTML element to which the figure is attached.

• graphs: Collection of KontrastGraph

  A collection of all graphs within the figure. The object keys are the names of the graphs.

• rowStretch: KontrastNumber (default value: 0)

  The relative factor that determines how the vertical space between graphs (i.e. the rows of the layout) can be stretched.

• columnStretch: KontrastNumber (default value: 0)

  The relative factor that determines how the horizontal space between graphs (i.e. the columns of the layout) can be stretched.

• topStretch: KontrastNumber (default value: 1)

  The relative factor that determines how the space at the top of the figure can be stretched.

• bottomStretch: KontrastNumber (default value: 1)

  The relative factor that determines how the space at the bottom of the figure can be stretched.

• leftStretch: KontrastNumber (default value: 1)

  The relative factor that determines how the space at the left of the figure can be stretched.

• rightStretch: KontrastNumber (default value: 1)

  The relative factor that determines how the space at the right of the figure can be stretched.

You can see in Example: Graph layout with stretch factors how columnStretch, leftStretch and rightStretch work. (rowStretch, topStretch and bottomStretch work similarly.)

Properties of render methods

The input object for the renderHTML and renderPNG can have the following properties:

• width: positiveInteger | undefined
  The width (number of screen pixels) of the static render. If this value is not specified, the current width of the figure is used.
• height: positiveInteger | undefined
  The height (number of screen pixels) of the static render. If this value is not specified, the current height of the figure is used.
• pixelSize: positiveNumber (default value: 2)
  The size of a pixel specifies how many actual pixels in the output render correspond to a screen pixel. You can use this value to achieve a high-resolution render. A value of one results in a render that has exactly as many pixels as you specify with width and height.

The resulting PNG image has a horizontal resolution of width * pixelSize and a vertical resolution of height * pixelSize.

For more information on the usage of pixelSize we recommend the introductory paragraphs of the MDN devicePixelRatio page.

Examples

• Background color of a figure
• Export a figure as PNG
• Graph layout with stretch factors
• Pause and resume the rendering of a figure