function-curve-viewer

An interactive function curve and waveform viewer for the web browser. It plots mathematical functions and sampled data (e.g. audio waveforms) in a HTML canvas, with mouse, touch and keyboard support for zooming and panning. It can be used as a plain widget (with a HTML canvas element) or as a web component (HTML custom element).

Online demo  |  NPM package  |  Examples

Features

• Plots any JavaScript function of the form y = f(x).
• Displays sampled data (arrays), e.g. audio waveforms, with automatic min/max envelope rendering when zoomed out and linear or nearest-neighbor interpolation when zoomed in.
• Zooming and panning with mouse, touch gestures or keyboard.
• Multiple channels (multiple curves in the same viewer).
• Auto-scaled coordinate grid with axis labels and optional units.
• X-axis segment selection.
• Custom paint hook for drawing additional content on the canvas.
• Clipboard copy support.
• Styling via CSS custom properties.
• Written in TypeScript, type declarations included, no dependencies.

Usage as a web component

Register the custom element once, place it in the HTML and pass it a viewer state:

<function-curve-viewer id="viewer1" style="width: 800px; height: 300px;"></function-curve-viewer>

import {registerCustomElement, FunctionCurveViewerElement} from "function-curve-viewer";

registerCustomElement();
const viewer = <FunctionCurveViewerElement>document.getElementById("viewer1");
viewer.setViewerState({
   viewerFunction: (x: number) => Math.sin(x) / x,
   xMin: -20, xMax: 20,
   yMin: -1.2, yMax: 1.2 });

Usage as a widget

In widget mode, the viewer is attached to an existing canvas element:

<canvas id="functionCurveViewer" style="width: 800px; height: 300px;" tabindex="-1"></canvas>

import {Widget} from "function-curve-viewer";

const canvas = <HTMLCanvasElement>document.getElementById("functionCurveViewer");
const widget = new Widget(canvas);
widget.setViewerState({
   viewerFunction: (x: number) => Math.sin(x) / x,
   xMin: -20, xMax: 20,
   yMin: -1.2, yMax: 1.2 });

Displaying sampled data (e.g. audio waveforms)

createViewerFunctionForArray() converts an array of sample values into a viewer function. When zoomed out, the min/max envelope of the curve is displayed.

import {Widget, createViewerFunctionForArray, ZoomMode} from "function-curve-viewer";

const viewerFunction = createViewerFunctionForArray(samples, {scalingFactor: sampleRate});
widget.setViewerState({
   viewerFunction,
   xMin: 0, xMax: samples.length / sampleRate,
   yMin: -1.2, yMax: 1.2,
   primaryZoomMode: ZoomMode.x });

The widget example shows how to load and display an audio file.

Viewer function

The curve to be plotted is defined by a viewer function:

type ViewerFunction = (x: number, sampleWidth: number, channel: number) =>
   number | number[] | undefined;

It is called once per canvas pixel column and may return a single y value, an array [yMin, yMax] to draw a vertical envelope range, or undefined where the function is not defined.

Mouse, touch and keyboard controls

| Input | Action | | ---------------------------- | --------------------------------- | | drag with mouse or touch | move the coordinate plane | | mouse wheel | zoom (primary zoom mode) | | Shift + mouse wheel | zoom y-axis | | Alt + mouse wheel | zoom x-axis | | Ctrl + mouse wheel | zoom both axes | | touch pinch gesture | zoom x, y or both axes | | Shift + drag | select x-axis segment | | Shift + click | clear x-axis segment selection | | Alt + click / Alt + drag | modify x-axis segment | | + / - | zoom both axes in/out | | X / x, Y / y | zoom single axis in/out | | g | toggle coordinate grid | | i | reset to the initial state |

The widget provides this list at runtime via getRawHelpText() and getFormattedHelpText().

Styling

Colors and line widths can be configured with CSS custom properties on the viewer element (or on the canvas in widget mode):

| CSS property | Description | | ------------------------------- | ---------------------------------------------- | | --background-color | canvas background color | | --curve-color | curve color of the first channel | | --curve-color0, --curve-color1, ... | per-channel curve colors | | --curve-width | curve line width of the first channel | | --curve-width0, --curve-width1, ... | per-channel curve line widths | | --grid-color, --grid-color-0, --grid-color-10 | grid line colors | | --label-text-color | axis label text color | | --selection-color | background color of the selected segment |

For touch devices, touch-action: none should be set on the viewer element so that drag and pinch gestures are handled by the viewer instead of the browser.

Events

The viewer fires the following events:

• viewportchange — after the user has changed the viewport by zooming or panning.
• segmentchange — after the user has changed the x-axis segment selection.

viewer.addEventListener("viewportchange", () => { ... });

Examples

The examples directory contains complete example applications:

• widgetExample — widget mode: plots a user-entered function expression and displays the waveform of an audio file.
• webComponentExample — the viewer used as a web component.
• spectrumViewer — a <spectrum-viewer> web component for audio frequency spectra (dB over Hz), built by subclassing the function curve viewer element. Demonstrates the custom paint hook (bar plot mode) and loading spectrum data from JSON, element attributes or a URL.