README
gridviz
A JavaScript library being developed for visualizing gridded statistics from CSV files using three.js and d3.js.
Examples
Description
Gridviz is a JavaScript library which allows you to visualize large gridded datasets (or any csv file with x/y data) in the browser. Unlike traditional raster-based GIS approaches, this tool utilizes WebGL through three.js in order to render eveything client-side.
From a CSV file with x and y columns, gridviz will build a viewer capable of visualizing millions of grid cells on the fly.
For data-driven colouring and sizing, you can use d3-scale and d3-scale-chromatic.
Installation
Node.js
npm install gridviz
then
gridviz = require("gridviz")
standalone
<script src="https://unpkg.com/gridviz/build/gridviz.min.js"></script>
Usage
Create a viewer using let viewer = gridviz.viewer(); and customise it with the methods below.
Most of these methods follow the pattern viewer.myMethod([value]): If a value is specified, the method sets the parameter value and returns the viewer object itself. If no value is specified, then the method returns the current value of the parameter.
Here's a barebones example that loads a CSV containing population data for a 5 km² grid of europe:
let viz = gridviz.viewer()
.container(containerDiv)
.gridData([
{
url: "https://raw.githubusercontent.com/eurostat/gridviz/master/assets/csv/Europe/5km/3035/pop_5km_zeros_removed.csv",
cellSize: 5
}
])
.zerosRemoved(3) // To reduce file size, zeros can be removed from the cell's x and y coordinates. Just let gridviz know how many have been removed here!
.title("5km² Population Grid of Europe")
.colorField("value") // csv column that will determine cell colour
.legend({
title: "Total population per 5 km² (2011)",
ticks: 6
})
.sourcesHTML("Source: <a target='__blank' href='https://ec.europa.eu/eurostat/web/gisco/geodata/'>GISCO</a>")
.build()
API
| Method | Type | Default | Description |
|---|---|---|---|
| viewer.container([value]) | HTMLElement | document.body | The DOM element passed to the THREE.js renderer. |
| viewer.height([value]) | int | window.innerHeight | The height value used for the threejs scene, camera, zoom, labels. |
| viewer.width([value]) | int | window.innerWidth | The width value used for the threejs scene, camera, zoom, labels. |
| viewer.backgroundColor([value]) | String | "#b7b7b7" | Viewer background colour |
| viewer.lineColor([value]) | String | "#ffffff" | Colour used for line geometries |
| viewer.highlightColor([value]) | String | "#37f2d6" | Hex string which is later converted to THREE.Line2 color (hexidecimal). |
| viewer.loadingIcon([value]) | String | "ring" | CSS animation used for the loading icon, other options are: ripple | ring | ellipsis |roller. |
| viewer.title([value]) | String | null | Appends a title to the viewer |
| viewer.subtitle([value]) | String | null | Appends a subtitle to the viewer |
| viewer.cellCount([value]) | Boolean | false | Shows a count below the title of the total number of cells displayed in the viewer. |
| viewer.sourceHTML([value]) | HTML | null | Defines the innerHTML of the link to the data source shown in the bottom-right corner |
Data
| Method | Type | Default | Description |
|---|---|---|---|
| viewer.gridData([value]) | Object {url:string, cellSize: int} | null | Object containing the URL of the CSV file and its cellSize (this will determine the point size in three.js). A 1 km² grid will have a cellSize of 1000. |
| viewer.center([value]) | Array | null | [x,y] coordinates with which the viewer will center the camera. |
| viewer.addGeoJson([value]) | String | null | Loads a geojson file from the specified URL and adds it's geometries to the viewer. Currently only accepts "polygon" or "multipolygon" geometries |
| viewer.nuts([value]) | Boolean | false | Show NUTS boundaries using nuts2json |
| viewer.EPSG([value]) | int | 3035 | EPSG code of the projection to use for the geometries, placename labels and NUTS boundaries. (NUTS only available in 3035, 3857, 4258 or 4326) |
| viewer.nutsLevel([value]) | int | 0 | Nuts2json NUTS level |
| viewer.nutsSimplification([value]) | String | "20M" | Nuts2json simplification level |
| viewer.nutsCountry([value]) | String | null | Filters nuts2json geometries by country code. Used in order to only load boundaries for a single country. |
| viewer.showPlacenames([value]) | Boolean | false | Adds placenames to the viewer. Placename-scale thresholds currently defined by the user. |
| viewer.placenamesCountry([value]) | String | null | Filters placenames by country code |
| viewer.placenamesThresholds([value]) | Object | null | Defines population query parameter at certain scale thresholds e.g. {"100000":500} will show placenames with populations of over 5000 at scales up to 100 000 |
Cell colouring & sizing
| Method | Type | Default | Description |
|---|---|---|---|
| viewer.colorField([value]) | String | null | CSV field used to determine cell colour |
| viewer.sizeField([value]) | String | null | CSV field used to determine cell size |
| viewer.colorScaleName([value]) | String | "scaleSequential" | The name of d3.scale function name to use for scaling cell colours. If you would like to define your own scale you can use colorScaleFunction() |
| viewer.sizeScaleName([value]) | String | "scaleSqrt | Name of d3.scale function name to use for scaling cell sizes |
| viewer.colors([value]) | Array | null | Array of hex strings to be used in combination with viewer.thresholdValues for colouring. |
| viewer.thresholdValues([value]) | Array | null | Array of threshold values that are applied to the colour scaling function. |
| viewer.colorSchemeName([value]) | String | "interpolateTurbo" | Name of d3.scaleChromatic function to use for scaling cell colours |
| viewer.colorScaleMidpoint([value]) | Number | 0 | The midpoint value when using a diverging scale |
| viewer.reverseColorScheme([value]) | Boolean | false | Flips the current color scheme. Applies .reverse() method to the domain of the scale. |
| viewer.colorScaleFunction([value]) | Function | d3.[viewer.colorScaleName] | Define a scale function to be used for color scaling. If unspecified it will build a d3 scale using viewer.colorScaleName and the d3.extent() of the values loaded from viewer.colorField. |
| viewer.sizeScaleFunction([value]) | Function | d3.[viewer.sizeScaleName] | Define a scale function to be used for scaling cell sizes. If unspecified it will build a d3 scale using viewer.colorScaleName, the d3.extent() of the values loaded from viewer.sizeField and a range of [viewer .resolution / 3, viewer.resolution / 1.5] |
| viewer.colorFieldSelector([value]) | boolean | false | Generates a simple HTML select input showing the available fields in the csv file that can be used to drive cell colour. |
| viewer.colorSchemeSelector([value]) | boolean | false | Generates an HTML Select element for the different D3 Scale-Chromatic functions |
| viewer.sizeFieldSelector([value]) | boolean | false | Generates a simple HTML select input showing the available fields in the csv file that can be used to drive cell size. |
Legend
| Method / Object | Type | Default | Description |
|---|---|---|---|
| viewer.showLegend([value]) | boolean | true | Build d3 colour legend. |
| viewer.legend([legendConfig]) | Object | See legendConfig default values below. | |
| legendConfig.type | String | "continuous" | Type of legend to build. Accepted values are "cells" or "continuous". Cells uses d3-svg-legend and continuous uses an implementation of Mike Bostock's color legend |
| legendConfig.width | int | 140 | width of the legend in pixels |
| legendConfig.height | int | 320 for "cells" and 50 for "continuous" | height of the legend in pixels |
| legendConfig.orientation | int | For cells legends only | "vertical" or "horizontal" |
| legendConfig.title | String | "Legend" | Title text of the legend. |
| legendConfig.titleWidth | int | 50 | Width of the title text of the legend. |
| legendConfig.format | string | ".0s" | d3.format string used to format the legend values |
| legendConfig.cells | int | 5 | Number of cells (for cell legends only) |
| legendConfig.shapeWidth | int | 30 | width in pixels of legend cell (for cell legends only) |
Developer docs
For source code documentation see docs