geogrid.js

The library geogrid.js provides a Leaflet layer that depicts data aggregated by the ISEA3H Discrete Global Grid System. Thereby, the library renders the visualization using WebGL.

Overview

Scientific Publications

The following publication is related to this plugin and the used Discrete Global Grid System (DGGS):

FB Mocnik: A Novel Identifier Scheme for the ISEA Aperture 3 Hexagon Discrete Global Grid System. Cartography and Geographic Information Science 46(3), 2019, 227–291

Related Software

This library is compatible with the framework Measures REST, which can be used to aggregate data by a grid and then provide the data via a REST interface. Data can also be aggregated manually by using the library geogrid that computes and handles Discrete Global Grid Systems (DGGS).

Use the Library

To load the library, include the following in the header of your HTML file:

<script src="https://unpkg.com/geogrid.js"></script>

In addition, the library geogrid.js requires the following libraries to be loaded:

The library vptree.js library is included and shipped with geogrid.js under the ISC license.

In order to use the ISEA3HLayer, a Leaflet map needs to be loaded first, for example, like follows:

var map = L.map('map').setView([49.4, 8.7], 10);

Then, the ISEA3HLayer, which is provided by this library, can be added:

var isea3h = L.isea3hLayer({
  url: 'http://localhost:8080/.../{z}/{x}/{y}.json',
}).addTo(map);

As an option, a URL needs to be provided under which data aggregated by the ISEA3H grid is available. Such a URL can be provided in two different formats:

in an XYZ tile format by including the paramters {x}, {y}, and {z}, thus allowing to load the data on demand, and
as a API URI that provides the data corresponding for a given bounding box {bbox} and resolution {resolution}.

In both cases, further parameters can be encoded, as is discussed in the description of the option parameters. In all cases, the provided data should be formatted as follows:

{
    "type":"grid",
    "resolution":14,
    ...
    "data":[
        {"value":0.345, "id":"1309502766029885663"},
        {"value":null, "id":"1309502851015240491"},
        ...
    ]
}

The grid cell IDs are assumed to conform to both adaptive and non-adaptive IDs, as is described in:

F.-B. Mocnik: A Novel Identifier Scheme for the ISEA Aperture 3 Hexagon Discrete Global Grid System. Cartography and Geographic Information science 46(3), 2019, 277–291. doi:10.1080/15230406.2018.1455157

Data which is formatted in the above format is, for example, provided by the framework Measures REST.

The ISEA3HLayer can be used in combination with different base maps. A good choice is Toner lite by Stamen. The complete code of the example is as follows:

var map = L.map('map').setView([49.4, 8.7], 10);
L.stamenTileLayer('toner-lite').addTo(map);
L.isea3hLayer({
  url: 'http://localhost:8080/.../{z}/{x}/{y}.json',
}).addTo(map);

Examples

An example can be found in the subdirectory example. Observe that the example index-with-server.html presumes a local instance of Measures REST.

Examples: Options

The ISEA3HLayer accepts several options, which allow to easily adapt the layer to the data source and the visualization needs. Instead of depicting representing the value related to a grid cell by the colour, the value can also be encoded by the size of the grid cell:

L.isea3hLayer({
  url: '...',
  cellColorKey: null,
  cellSizeKey: 'value',
})

Even two different values related to a grid cell can be represented, for example, the value with key value1 encoded by the colour, and the value with key value2, by the size of the cell:

L.isea3hLayer({
  url: '...',
  cellColorKey: 'value1',
  cellSizeKey: 'value2',
})

Most options can even be updated after the ISEA3HLayer has been initialized, which makes possible to interactively adapt the display and depict different aspects of the data without the need to reload them:

isea3h = L.isea3hLayer({
  url: '...',
  cellColorKey: 'value1',
})
...
isea3h.update({
  cellColorKey: 'value2',
})

Examples: Several Data Sources

The ISEA3HLayer accepts one or more data sources. In many cases, only one data source is to be depicted. This is the case that has been discussed before – the URL that provides reference to the data and other options are provided as options:

L.isea3hLayer({
  url: '...',
  cellColorKey: 'value1',
  cellSizeKey: 'value',
  silent: false,
  renderer: 'webgl',
})

Observe that the options silent and renderer do not refer to this particular dataset but the layer in general. This is in contrast to the options url, cellColorKey, and cellSizeKey, which refer to the data source and its representation. Instead of mixing these options (which is allowed), they can be separated as follows:

L.isea3hLayer({
  sources: [{
    url: '...',
    cellColorKey: 'value1',
    cellSizeKey: 'value2',
  }],
  silent: false,
  renderer: 'webgl',
})

This way of providing the options has the advantage that it becomes obvious which options are only valid for the provided data source, and it allows to add additional data sources. For instance, several sources can be provided as follows:

L.isea3hLayer({
  sources: [{
    url: '...',
    cellColorKey: 'value1',
    cellSizeKey: 'value2',
  }, {
    url: '...',
    cellColorKey: null,
    cellSizeKey: 'value',
  }],
  silent: false,
  renderer: 'webgl',
})

It is important to note that the two ways of noting down the sources – inline with the general options in case of one source, or under sources in case of one or more sources – cannot be mixed.

The several options available are described in the following.

Options

The following options are available to describe the data sources and their handling:

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | url | String | null | URL under which data aggregated by the ISEA3H grid is available. The URL potentially contains information about the bounding box and the resolution, encoded by {bbox} and {resolution} respectively. Further parameters can be used in the url by providing corresponding values in the option parameters. The expected format of the returned data is described above. | | data | Object | null | Instead of the parameter url, the data can be provided explicitly. | | parameters | Object | {date: new Date().toLocaleDateString(), dateFrom: null} | Additional parameters that can be used in the url. | | hide | Boolean | false | Determines whether the source should be hidden. Can be useful for empty grids that are used to make incomplete data complete. | | tileZoom | Number | 7 | Zoom to be used for the tiles in case of a tile URL. | cellColorKey | String | value | The colour to be used for a grid cell can be chosen in dependence of the property cellColorKey of the cell. The colour is, accordingly, determined by computing the function cellColorScale with the property cellColorKey of the cell as argument. If the option cellColorKey is null, the colour cellColorNoKey is used instead. | | cellColorMin | Number | 0 | Minimum value to be used in cellColorScale. If null, the minimum value is determined by the data of the currently cached cells. | | cellColorMax | Number | null | Maximum value to be used in cellColorScale. If null, the maximum value is determined by the data of the currently cached cells. | | cellColorScale | Function | (min, max) => d3.scaleLinear().domain([min, max]).range(['#fff', '#f00']) | This option is used to determine the colour to be used for a grid cell, when cellColorKey is not null. This option is either (1) a function that returns, for a the property cellColorKey of the cell, the colour that should be used for the cell; or (2) a function that returns for given min and max values a function as in (1). | | cellColorNoData | String | '#eee' | Colour to be used for a grid cell, when no data is available for this particular cell. | | cellColorNoKey | String | '#f00' | Colour to be used for a grid cell, when cellColorKey is null. | | cellColorOpacity | Number | .5 | Opacity of the area of the grid cells. | | cellSizeKey | String | null | The relative size of a grid cell can be chosen in dependence of the property cellSizeKey of the cell. The relative size is, accordingly, determined by computing the function cellSizeScale with the property cellSizeKey of the cell as argument. If the option cellSizeKey is null, the relative size cellSizeNoKey is used instead. | | cellSizeMin | Number | 0 | Minimum value to be used in cellSizeScale. If null, the minimum value is determined by the data of the currently cached cells. | | cellSizeMax | Number | null | Maximum value to be used in cellSizeScale.

Geogrid.js

Install / Use

README