plot-grid

Grid component for webgl/canvas2d with zooming, panning, polar mode etc. See demo.

Usage

const createGrid = require('plot-grid');

//cartesian grid
let grid = createGrid({
	x: {
		type: 'logarithmic',
		min: 0
	},
	y: {
		min: -100,
		max: 0
	}
});

This will create frequency response and directional diagram.

API

let grid = new Grid(options?)

Create new grid instance. It can serve both as a class or constructor function (no new). By default it displays cartesian grid, but

| Name | Default | Description | |---|---|---| | container | document.body | Container to place grid into. Can be null to render in memory. | | context | null | Can be pre-existing context. | | pixelRatio | window.devicePixelRatio | Pixel ratio of canvas. | | autostart | true | Render every frame automatically or call render method manually. Useful if plot-grid is used in cooperation with other components. | | interactions | true | Enable pan/zoom interactions, see interact event. | | x, y, r, a | Bool, String, Object | Boolean, enabling coordinates of linear type or a string, defining custom type: linear, logarithmic or time. If object is passed, it defines custom lines behaviour, see the table below. |

Each of x, y, r, a can be customized by the following options:

| Name | Type | Default | Description | |---|---|---|---| | type | String, null | null | Default type to extend, one of linear, logarithmic, time. | | color | String | rgba(0,0,0,1) | Default color for the lines, axes, ticks and labels. | | format | Function | null | Formatter for label values. Takes a value and returns a string. pretty-number can be used as such. | | lines | Bool, Array, Function, null | | Array with values, defining lines, or function returning such array, state => [values...]. Can be disabled by passing false. By default implemented by type. | | ticks | Bool, Array, Number, Function | 5 | Tick size. Can be disabled by passing false. | | labels | Bool, Array, Object , Function, null | null | Object or array with labels corresponding to lines. Can be defined as a function returning such array (state) => labels. null value will output values as is. Can be disabled by passing false. | | axis | Bool | true | Enable axis. |

Pan & zoom

Additional pan/zoom params can be set for each coordinate x, y, r, a:

| Name | Type | Default | Description | |---|---|---|---| | offset | Number | 0 | Defines start point for the visible range, in terms of values. | | origin | Number | 0.5 | Defines position of the offset on the screen, for example, .5 for center, 1 for right/top edge of the screen, 0 for left/bottom. | | scale | Number | 1 | Sets scale for the current range, number of values per pixel. | | min, max | Number | -Infinity, Infinity | Limits for panning. | | minScale, maxScale | Number | 0, Infinity | Scale limits. | | zoom | Bool | true | Enables zoom interaction. | | pan | Bool | true | Enables pan interaction. |

To change pan or zoom, use update method with the propertives above, as update({x: {offset, scale}, y: {offset, scale});.

Another time it might be useful to engage grid.on('interact', grid => {}) handler for grid interactions, like moving and zooming.

Style

Each coordinate can be customized more with additional options:

| Name | Type | Default | Description | |---|---|---|---| | lineColor | String, Number, Function, null | .3 | Color for lines. Number value will take the base color above with changed opacity. Function signature is state => [...values]. | | lineWidth | Number | 1 | Width of lines. We guess that width of sublines should not differ from the width of lines, if you have use-case requiring the opposite, please address issues. | | axisOrigin | Number | 0 | Define axis alignment by value on the opposite coordinate. | | axisColor | String, Number | 0.1 | Axis color, redefines default color. | | axisWidth | Number | 2 | Width of axis line. | | align | Number | 0.5 | The side to align ticks and labels, 0..1. | | fontSize | String, Number | 10pt | Font size for labels. Sizes with units will be automatically transformed to pixels by to-px. | | fontFamily | String | sans-serif | Font family to use for labels. | | padding WIP | Number, Array(4) | 0 | Padding inside the viewport to indent lines from axes and labels. Ordering is top, right, bottom, left, as in css. | | style WIP | String | lines | Style of rendering: lines or dots. Note that dots is available only when x and y are both enabled. | | distance | Number | 120 | Minimum distance between lines. |

grid.update(options)

Pass new options to update grid look. Note that passed options extend existing ones.

grid.update({
	x: {
		type: 'logarithmic',
		offset: 0,
		min: 0,
		scale: .01
	}
});

Note that you may need to call render in manual mode grid.update().render().

grid.render()

Redraw grid. Call whenever you need to redraw grid, like resize etc. It will not recalculate lines, just rerender existing lines. To recalculate lines, use grid.update().

grid.draw()

Directly invoke draw method, useful in case if grid needs to be drawn over other content.

Used by

• gl-spectrum
• gl-spectrogram
• gl-waveform

Thanks

To @evanw with thetamath for grid API inspiration.

Related

• grid — collection of grids for canvas2d.