- Gridviz API reference
Anything unclear or missing? Feel free to ask !
Here are few concepts on Gridviz to be aware of:
-
A gridviz map is composed of a stack of layers. Layers may have different types (background image, boundaries, labels, etc.). The main layer type is GridLayer, for gridded data. Background layers are usually drawn below, usually a single one. Boundaries and label layers should also be drawn as foreground, on top of grid layers.
-
Gridded datasets are defined independantly from their grid layer. Each gridded dataset may thus be reused by several layers: It is loaded and stored once, and reused several times. This reuse allows saving memory space and loading time.
-
A gridded dataset may be multi-resolution. Gridviz then takes care of selecting the most suitable resolution according to the visualisation zoom level (and a predefined minPixelsPerCell parameter). This ensures only the relevant data for the visualisation view and zoom level is loaded and displayed.
-
GridViz supports data tiling, and also Parquet format.
-
A grid layer draws a single gridded dataset using one or several styles. It is thus possible to combine styles and draw them on top of each other to show different aspects of the data.
-
A style specifies how to draw the cells within the view. The style is not defined at cell level only - it allows defining more advanced styling techniques using cell sets, based on the relations of each cell with its neigbours.
-
Gridviz comes with a library of predefined styles. These styles are customisable. Users are also offered a full flexibility to define their own style and show their cells the way they need. Predefined style may be seen only as examples and inspiration sources.
-
Predefined styles parameters are usually not static values, but functions of usually four parameters: The cell to be drawn, its resolution, the zoom level, and a viewscale object. Styling parameters (such as colors, size, etc.) may thus be computed depending on each cell, its resolution, and the zoom level. Size parameters are usually specified in the unit of measurement of the grid coordinate reference system, usually ground meters. They may also be specified in screen pixels. These functions allow adapting the cartographic styles (colors, dimensions, etc.) to the cell values, their size and the zoom level.
-
For some predefined style parameters, viewscale parameter allows defining styling parameters based on the cells within the map view only. This parameter is an object computed only once from the cells within the view. It may be used for example to compute the minimum and maximum values of these cells and adapt a color scale to this for a better contrast. It should generally be used to compute scales that are view dependant - hence the name viewscale. See this section for some examples.
-
Gridviz zoom level, usually noted z, is defined in ground UoM per pixel. The ground UoM is usually meter. z value can be used directly to transorm distances from ground distance to map screen distance, in pixels, as a division. resolution parameter is the cell size, in ground UoM. Its size in map screen pixel is thus 'resolution / z'.
-
A grid layer shows gridded data in the grid coordinate reference system. Several gridded datasets may be overlayed, as soon as they are defined in the same coordinate reference system. Other layers (background, labels, etc.) must be defined also in the grid coordinate reference system.
A gridviz dataset defines how to retrieve gridded data, as a list of grid cells. A grid cell is stored as a javascript object having a x and y property, which is usually the coordinates of the grid cell lower left corner in the grid coordinate reference system. The x and y values are usually multiples of the grid resolution value.
Gridviz proposed several types of datasets: Javascript, CSV, Parquet.
These datasets may be bundled into multi-resolution datasets, to be used for multi-scale maps:
Gridviz can also show tiled data. This ensures only the data within the viewshed are loaded and displayed. These tiled data should follow the tiled grid format.
- See this example for tiled CSV data (code).
- See this example for both tiled and multiscale CSV data (code).
For Parquet data support, see the gridviz-parquet extension.
For better efficiency, it is recommended to use multi-resolution tiled parquet data.
The gridded data may be pre-processed after loading, and filtered:
- See this example for basic pre-processing (code).
- See this example for basic filtering/selection (code).
- See this example for basic filtering/selection at style level (code).
This style is a generic style which allows to define the shape, color and size of each grid cell, independantly according to 3 different variables. Three shapes are currently available: square, circle, triangle (up, down, left or right) and donut (a disk with a hole of changing size). To show grid cells as small squares with only changing color, one of the styles based on web GL here or here should rather be used, for efficiency reasons.
- See this example with changing size (code).
- See this example with changing size and color (code).
- See this example with random shape, color and size (code).
This style displays each cell as a square, with a changing color. This style uses webGL and should thus be used to display grid cells at detailled resolutions.
- See this basic example (code).
- See this example with dark style (code).
This style displays each cell as a square, with a changing color based on a categorical variable. This style uses webGL and should thus be used to display grid cells at detailled resolutions.
- See this basic example (code).
This style shows a composition at cell level in various different ways: Flags, pie charts, rings, segments, radar, age pyramid and halftone.
- See this basic example (code).
This style displays each cell as a segment with a changeable color, length, width and orientation.
- See this basic example (code).
- See this example with random segment orientation, color, length and width (code).
This style shows the stroke of each cell with different colors, widths, shapes and sizes. This style can be used in addition to others to show the cell strokes on top of those other styles.
This style displays each cell as randomly located points, with changeable density and color.
- See this basic example (code).
- See this example with random colors (code).
This style shows the grid cells as 3D pillars or, with changeable height, width and color.
- See this basic example (code).
- See this basic example with simple style (code).
Ternary maps use color to show a composition according to three categories. Three different color hue are defined, that correspond to each of the three categories. The cells color is then selected according to the relative importance of the three categories. When two of the three categories are more important that the third, a color mix is used. A central class may be defined to show cases where the three categories are relativelly well balanced.
- See this example (code).
- See this other example (code).
Note that this style is not really a new style - it relies on a specific classifier.
This style shows the grid cells as text labels. The text, its color and font size can be set according to some cell values.
- See this basic example (code).
- See this example (code).
This style shows the grid cells as an image. The image and its size can be set according to some cell values.
- See this basic example (code).
- See this example, with Chernoff faces (code).
This style shows the grid cells as a time series chart. It is particulary suitable to show data that has high temporal granularity and low geographical granurality (variation across time rather than space). The time series charts can be colored and sized according to other variables.
- See this basic example (code).
The side styles are special:They do not display the cells, but their sides. They can be used to show discontinuities between cell values with, for example, some shadow effect.
This style displays the sides of the cells as segments with different colors and widths, depending on the values of the 2 adjacent cells.
- See this example (code).
This style displays the sides of the cells as segments with different colors depending on the categories of the 2 adjacent cells.
- See this example (code).
This style is experimental / under development. It displays the sides of the cells depending on discontinuities between the 2 adjacent cells, like contour lines.
- See this example (code).
This style shows the composition of a total quantity into categories as vertical cross-sections oriented toward North-South and East-West. It is an alternative to composition style. It may also be seen as a bi-directional joyplot style showing categories - note that when angle value is set to 90°, the style is equivalent to a joyplot. This style was inspired by the USGS geologic isometric fence diagrams (1953).
- See this example (code).
This style shows cell rows in the form of a 'joyplot' - named after Joy Division's "Unknown Pleasures" album cover. For joyplot style showing composition by categories, or for various orientations and perspective angles, see isometric fence style.
- See this basic example (code).
- See this an example of shaded joyplot (code).
- See this an example with random colors (code).
This style shows the cell as pseudo-irregular square shapes giving a mosaic effect. The cells are colored depending on a variable.
- See this basic example (code).
- See this roman style example (code).
This style shows the cell as a star polygon whose compacity depends on a variable. The higher the value, the more compact the star: Maximum values correspond to a square, and minimum values correspond to a thin star. The shapes in between correspond to 4 branches stars looking like a ninja star.
- See this basic example (code).
- See this other example (code) with stars parallel to the x/y axes.
This style shows the grid cells in a Tanaka style, that is with discrete colors and a shadow effect.
- See this example (code).
This style shows the grid cells as lego bricks with changeable colors and height based on a quantitative variable.
- See this example (code).
This style shows the grid cells as lego bricks with changeable colors based on a categorical variable.
- See this example (code).
This style allows applying a gaussian kernel smoothing to the input grid. Other styles can then be used on the smoothed grid - this style is thus more a 'filter' than a proper style.
Note that this style is available within the gridviz-smoothing extension which need to be added as: <script src="https://cdn.jsdelivr.net/npm/gridviz-smoothing"></script>.
- See this elementary example (code).
- See this example (code).
The kernel smoothing computation relies on the fast-kde library, which produces smoothing approximation very fast. Note that the approximation degrades significantly for weak smoothing (for low sigma values).
The style can be freely defined through the drawFun, which specifies how to draw the list of cells within the view on the map canvas.
- See this example (code) to define a simple style to draw each cell as an arrow symbol.
Background image layers may be defined:
- as a tiled layer: See this example (code) or this other example (code).
- or from a OGC WMS - Web Map Service: See this example (code).
- or as a single image file: See this example (code).
Foreground layers may be defined such as:
- label layers: See this example (code) or this other example (code).
- boundaries layers: See this example (code).
- points layers: See this example (code).
To handle layer and style transparency, blending modes and alpha values may be defined at layer or style level. These values may be set according to the zoom level.
- See this example (code).
A tooltip may be customised for the grid cells passed over the mouse pointer. By default, the list of properties is shown.
- See this example (code) to define the tooltip text.
To show zoom and full screen mode buttons, see this example (code).
For some predefined style parameters, viewscale parameter allows defining styling parameters based on the cells within the map view only. This parameter is an object computed only once from the cells within the view. It may be used for example to compute the minimum and maximum values of these cells and adapt a color scale to this for a better contrast. It should generally be used to compute scales that are view dependant - hence the name viewscale.
- See this basic example (code).
- See this more advanced example (code) using some predefined function.
Most of Gridviz styles rely on a continuous mapping from a statistical variable to a visual variable (color, size, etc.). The statistical distribution can be stretched with one of the stretching functions listed below can be used. These are continuous bijective functions defined from [0,1] to [0,1] intervals. They have different properties and should be chosen according to the data distribution. The amplitude of the stretching can be adjusted with a parameter.
| Stretching function | Description | Stretching parameter |
|---|---|---|
| powerScale | Polynomial function | Power exponent, from 0 to Infinity. No change: 1 |
| powerInverseScale | Polynomial inverse function | Power exponent, from 0 to Infinity. No change: 1 |
| logarithmicScale | Exponential function | Logarithmic base, from -Infinity to Infinity. No change: 0 |
| exponentialScale | Exponential | Logarithmic base, from -Infinity to Infinity. No change: 0 |
| circularScale | Circular | 0: no stretching. 1: perfect circle section |
| circularInverseScale | Circular | 0: no stretching. 1: perfect circle section |
For more information on these functions and an overview of how they differ, see:
- this basic example (code).
- this other example based on webGL style (code).
- the code
- those graphs
Gridviz offers several types of legends that are suited to different cartographic styles.
The legend elements are added within a default HTML element. To define where the legend elements should be added, see this example (code).
Each legend can be customised using the 'D3-like' style() function after constructing the legend, like so:
new gridviz.SizeLegend({
title: 'Number of inhabitants',
exaggerationFactor: 0.8,
shape: 'circle',
fillColor: '#3E5791',
}).style('padding', '0px 5px')
- See this example (code).
- See this example (code) for a view scale based style.
- See this example (code) for a legend with static text.
- See this example (code) for a legend with diverging color ramp.
- See this example (code).
- See this example (code) for a view scale based style.
- See this example (code) for a quantile view scale based style.
- See this example (code).
- See this example (code).
- See this example (code).
- See this example (code) for a discrete style.
- See this example (code) for a view scale based style.
- See this example (code) for a quantile view scale based style.
- See this example (code).
- See this example (code) for a discrete style.
- See this example (code) for a view scale based style.
- See this example (code) for a quantile view scale based style.
- See this example (code).
Gridviz can be used with leaflet by using the leaflet-gridviz plugin
See this example (code) to limit the panning and zooming to some limit values, in order to prevent the user to move toward undesired positions and zoom levels. Note that the panning limit applies to the map center, not the map borders. The panning limit is specified as an array [xMin, yMin, xMax, yMax].
A mixed-resolution grid is a grid which contains cells with different sizes.
- See this example (code).
- See this other example (code).
Note that most pre-defined styles of GridViz may not apply for mixed-resolution grids. Custom styles can be defined.
Anything unclear or missing? Feel free to ask !