Tutorial: The first visualization with Kontrast

In this document we want to show you step-by-step how you can create your own interactive visualization with Kontrast.

We assume that you have basic knowledge about JavaScript, HTML and LaTeX. Don’t worry, you don’t have to be a professional programmer and we show you how to create a figure step by step.

If you have little knowledge about JavaScript, we suggest tutorials (or books) on JavaScript, such as JavaScript basics (MDN) (see also: Notes on web development).

Preparation

We use the following HTML file as a template:

Please write (or copy-and-paste) the above content as a .html file. The filename is arbitrary. We recommend that you place the file inside the folder user within the Kontrast distribution to facilitate later updates of Kontrast.

Some things to note about the above file are:

You need to include some .js files and .css files using the script and link tags inside the head tag.
Of course, you also must include your code somehow. You can also choose to add your code inside the HTML file directly, but in this tutorial we assume that you write your code in a separate .js file that will be included from the HTML file.

The first figure

Drawing axes

As a first step, let’s draw a figure with a single graph that simply shows a coordinate system consisting of two axes. Write the following code and save as a .js file. Of course the name of this file must be the same as the filename which you specified in the .html file. If you just copy-and-pasted the HTML code above, the filename of this JavaScript code is tutorial.js and has to be placed in the same folder.

The specified range (min and max) of each axis is used as the initial range. You (and viewers of your page) can change the range using the mouse or touch gestures.

You can use arbitrary (but unique) strings as axis names ('x' and 'y' in this example). We refer to these names later.

Now open your .html file in your browser. You can enter the path of your .html file as file:///SOME/DIRECTORY/tutorial.html (on Unix-like systems such as Linux and MacOS) or file:///C:/SOME/FOLDER/tutorial.html (Windows) in the address bar of your browser.

Do you see a graph like the one below?

If you don’t see this, have a look at the console log to check for possible reason(s) of the problem. See Notes on web development for more details on how to open the console.

The most likely mistake is specifying the wrong path(s) for the external resources. In this case, you’ll see a message like ReferenceError: kontrast is not defined or Resource not found in the console log.

Adding labels

You may want to create a label for each axis. To do this, modify your .js file as follows:

If you wish to adjust the position of the axis label, you can use horizontalAnchor and verticalAnchor. In addition, you may want to modify the labels to allow for mathematical notation. To realize these, modify the label as follows (i.e. change the text-entry and add horizontalAnchor and verticalAnchor).

Kontrast is distributed with a helper utility for typesetting math formulas with the library KaTeX. As you see, you can specify the label text using LaTeX syntax. Unfortunately, each backslash must be escaped with another backslash, i. e. you need to write \\ for a single backslash. The label text in the above example corresponds to x\,/\,\textrm{m} in the normal LaTeX notation. (The sequence \, results in a small horizontal space.)

Now you can write mathematical notation like $a^2$ (a^2), $\theta$ (\theta), $\int\mathrm dx x^2$ (\int\mathrm dx x^2) etc.

Draw a graph

A single line

It’s time to draw a graph!

A line (more precisely, a line segment) can be drawn as follows:

This code creates a line from (0, 0.1) to (1, 0.9).

To specify the coordinates of the line, we used the axis names in data:. If you use, e. g., time as the internal name for the abscissa, you need to change the corresponding name in data:, too:

Multiple lines

You just need to repeat graph0.createLines() to draw two or more lines.

As you see, you can specify a color of the line using color . If you want to specify it as RGB color, use an array like this:

color: [1, 0.5, 0], // R, G, B. (0-1)

or use an HTML color expression such as '#ff0000'.

A curve

In Kontrast you can draw a curve from contiguous data using a line plot (consisting of a set of line segments).

A good starting point to explore all mathematical functions available in JavaScript is the MDN page on the Math object.

Points

To draw the point(s), use createPoints() instead of createLines().

Interaction

We show you here how to write an interactive graph using a slider.

For this, you need to change your HTML file as follows:

Again, the actual slider will be generated by the JavaScript code inside Kontrast. In the HTML file, you can simply place an empty <div> (with a unique ID).

The new JavaScript code will be like this:

'use strict'

kontrast.addEventListener('load', function () {
  let figure = kontrast.createFigure({ element: 'tutorial' })
  let graph0 = figure.createGraph({
    abscissae: {
      x: {
        min: 0,
        max: 1,
        yOrigin: -1,
        label: {
          text: katex.renderToString('x\\,/\\,\\textrm{m}'),
          horizontalAnchor: -1,
          verticalAnchor: -1,
        },
      },
    },
    ordinates: {
      y: {
        min: 0,
        max: 1,
        xOrigin: -1,
        label: {
          text: katex.renderToString('y\\,/\\,\\textrm{m}'),
          horizontalAnchor: 0,
          verticalAnchor: -1.5,
        },
      },
    },
  })

let linePlot = graph0.createLines({
    thickness: 3,

// Compare with your previous JavaScript code.
    // data: (a set of line segments) will be specified below
  })

let y1 = 0.1 // initial value

// create slider
  let ySlider = kontrast.createSlider({
    element: 'yslider', // The ID of the slider HTML element
    min: 0,
    max: 1,
    value: y1, // initial value
    quantity: katex.renderToString('y'),
    unit: katex.renderToString('\\mathrm{m}'), // optional
  })

// The function is invoked when the slider is moved or a (valid)
  // value is entered into the textbox.
  ySlider.addEventListener('numericInput', function (value) {
    // 'value' is the new value (= user input)
    y1 = value

// redraw graph
    update()
  })

// redraw (precisely: update the set of line segments)
  function update() {
    linePlot.data = {
      x: [0, 1],
      y: [0, y1],
    }
  }

// invoke update() once (before using the slider)
  // to draw the initial figure
  update()
})

Unfortunately, there is a lot happening at once in the above example. If you want to write the function separately, you can also write as follows:

The above code means:

If the slider is changed, the function changeY() should be called.
Inside the function changeY() we can describe what should be done, when the event (change of slider) occurs. In this case, the value is updated explicitly and the update() function is called.

In general, a function for such purpose is called an event handler. To tell the system which handler will be invoked for which event, you need to connect the event and event handler. This is done by addEventListener().

Enjoy!

That’s the end of the tutorial! We hope this document helps you to write your own interactive visualizations using Kontrast. Please refer to the documentation for more information.

We appreciate your feedback, in case you have any comments about this page and/or Kontrast itself.