gridviz 1.2.4 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +190 -204
- package/README.md +309 -0
- package/build/gridviz.min.js +1 -1
- package/package.json +71 -65
- package/readme.md +0 -310
package/README.md
ADDED
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# gridviz
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
[Gridviz](README.md) is a JavaScript library to visualise gridded data (or any tabular dataset with x/y position) in the browser in a large variety of advanced cartographic styles. Unlike traditional raster-based web mapping tools, [Gridviz](README.md) renders everything client-side, on the fly.
|
|
8
|
+
|
|
9
|
+
<div>
|
|
10
|
+
<img src="https://raw.githubusercontent.com/eurostat/gridviz/master/docs/screenshots/cropped/color.png" alt="preview" width="200px" height="200px"/>
|
|
11
|
+
<img src="https://raw.githubusercontent.com/eurostat/gridviz/master/docs/screenshots/cropped/joyplot.png" alt="preview" width="200px" height="200px"/>
|
|
12
|
+
<img src="https://raw.githubusercontent.com/eurostat/gridviz/master/docs/screenshots/cropped/size.png" alt="preview" width="200px" height="200px"/>
|
|
13
|
+
<img src="https://raw.githubusercontent.com/eurostat/gridviz/master/docs/screenshots/cropped/nl.png" alt="preview" width="200px" height="200px"/>
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
Note: This page presents the documentation of the version 2. The version 1 documentation remains available [there](v1/readme.md).
|
|
17
|
+
|
|
18
|
+
## Examples
|
|
19
|
+
|
|
20
|
+
- [Europe](examples/EUR.html)
|
|
21
|
+
- [France](examples/FR.html)
|
|
22
|
+
- [Croatia](examples/HR.html)
|
|
23
|
+
- [Dark](examples/FR_dark.html)
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
### Node.js
|
|
28
|
+
|
|
29
|
+
```Shell
|
|
30
|
+
npm install gridviz
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
then
|
|
34
|
+
|
|
35
|
+
```javascript
|
|
36
|
+
gridviz = require("gridviz");
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### standalone
|
|
40
|
+
|
|
41
|
+
```javascript
|
|
42
|
+
<script src="https://unpkg.com/gridviz/build/gridviz.min.js"></script>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Usage
|
|
46
|
+
|
|
47
|
+
Create a [Gridviz](README.md) application using `let app = new gviz.App();` and customise it with the methods described in the documentation below.
|
|
48
|
+
|
|
49
|
+
Here's a basic example that loads a CSV file on Europe population, 5x5 km grid:
|
|
50
|
+
|
|
51
|
+
```javascript
|
|
52
|
+
new gviz.App(containerDiv)
|
|
53
|
+
//set position and zoom
|
|
54
|
+
.setGeoCenter({ x: 4500000, y: 2900000 }).setZoomFactor(3000)
|
|
55
|
+
//add CSV layer
|
|
56
|
+
.addCSVGridLayer(
|
|
57
|
+
//data URL
|
|
58
|
+
"https://raw.githubusercontent.com/eurostat/gridviz/master/assets/csv/Europe/pop_2011_5km.csv",
|
|
59
|
+
//resolution, in CRS unit
|
|
60
|
+
5000,
|
|
61
|
+
//the styles
|
|
62
|
+
[
|
|
63
|
+
new gviz.SquareColorWGLStyle({
|
|
64
|
+
colorCol: "Population",
|
|
65
|
+
tFun: (value) => Math.min(value / 50000, 1)
|
|
66
|
+
})
|
|
67
|
+
]
|
|
68
|
+
)
|
|
69
|
+
```
|
|
70
|
+
(see [online](examples/basic_CSV.html))
|
|
71
|
+
|
|
72
|
+
[Gridviz](README.md) can display several layers on top of each others. Each layer is based on a single multi-resolution dataset, which can be displayed several times based on several cartographic styles. For more information, see the [examples](#examples).
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
## App Configuration
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
| Method | Type | Default | Description |
|
|
80
|
+
| --------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| _app_.**getGeoCenter**()<br />_app_.**setGeoCenter**([value]) | { x:number, y:number } | { x:0, y:0 } | Get/set the geographical coordinates of the view center. |
|
|
82
|
+
| _app_.**getZoomFactor**()<br />_app_.**setZoomFactor**([value]) | number | 1 | Get/set the view zoom. This zoom factor is expressed as the size of a pixel in ground distance. |
|
|
83
|
+
| _app_.**getZoomFactorExtent**()<br />_app_.**setZoomFactorExtent**([value]) | Array.<number> | [0, Infinity] | Get/set the view zoom extent, in order to prevent the user to zoom in/out beyond some zoom levels. |
|
|
84
|
+
| _app_.**getBackgroundColor**()<br />_app_.**setBackgroundColor**([value]) | string | "white" | Get/set the map background color. |
|
|
85
|
+
| _app_.**getBoundaryLayer**()<br />_app_.**setBoundaryLayer**([value]) | LineLayer | undefined | A layer for boundary lines, see [here](#showing-boundaries). |
|
|
86
|
+
| _app_.**getLabelLayer**()<br />_app_.**setLabelLayer**([value]) | LabelLayer | A layer for labels (such as placenames), see [here](#showing-labels)undefined | |
|
|
87
|
+
| _app_.**setViewFromURL**() | | | Set view geo center and zoom from URL parameters _x_, _y_ and _z_. For example, using the URL _myPage.html?x=1000&y=2000&z=45_ will force the viex to center to geographical coordinates _(1000, 2000)_ and zoom _45_. |
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
## Adding data
|
|
92
|
+
|
|
93
|
+
Input data are tabular data, in CSV format. It is possible to specify different data sources for different zoom levels, so that the level of detail of the data can adapt to the zoom level. Tiled CSV data can also be specified following the [tiledCSV format](docs/tiledCSVformat.md).
|
|
94
|
+
|
|
95
|
+
Are are several examples:
|
|
96
|
+
|
|
97
|
+
### Single CSV file
|
|
98
|
+
|
|
99
|
+
See the [basic example above](#usage).
|
|
100
|
+
|
|
101
|
+
### Multi scale CSV data
|
|
102
|
+
|
|
103
|
+
TODO add example
|
|
104
|
+
|
|
105
|
+
### Tiled CSV data
|
|
106
|
+
|
|
107
|
+
```javascript
|
|
108
|
+
new gviz.App(containerDiv)
|
|
109
|
+
new gviz.App(containerDiv)
|
|
110
|
+
//set position and zoom
|
|
111
|
+
.setGeoCenter({ x: 4500000, y: 2900000 }).setZoomFactor(3000)
|
|
112
|
+
//add multi scale tiled CSV layer
|
|
113
|
+
.addTiledCSVGridLayer(
|
|
114
|
+
//data URL
|
|
115
|
+
"https://raw.githubusercontent.com/eurostat/gridviz/master/assets/csv/Europe/grid_pop_tiled/5km/",
|
|
116
|
+
//the styles
|
|
117
|
+
[
|
|
118
|
+
new gviz.SquareColorWGLStyle({
|
|
119
|
+
colorCol: "2018",
|
|
120
|
+
tFun: (value) => Math.min(value / 50000, 1)
|
|
121
|
+
})
|
|
122
|
+
]
|
|
123
|
+
)
|
|
124
|
+
```
|
|
125
|
+
(see [online](examples/basic_tiled_CSV.html))
|
|
126
|
+
|
|
127
|
+
### Multi scale tiled CSV data
|
|
128
|
+
|
|
129
|
+
```javascript
|
|
130
|
+
new gviz.App(containerDiv)
|
|
131
|
+
//set position and zoom
|
|
132
|
+
.setGeoCenter({ x: 4500000, y: 2900000 }).setZoomFactor(3000)
|
|
133
|
+
//add multi scale tiled CSV layer
|
|
134
|
+
.addMultiScaleTiledCSVGridLayer(
|
|
135
|
+
//the resolution values, ordered
|
|
136
|
+
[1000, 2000, 5000, 10000, 20000, 50000, 100000],
|
|
137
|
+
//the URL, from the resolution
|
|
138
|
+
r => "https://raw.githubusercontent.com/eurostat/gridviz/master/assets/csv/Europe/grid_pop_tiled/" + Math.round(r / 1000) + "km/",
|
|
139
|
+
//the styles
|
|
140
|
+
[
|
|
141
|
+
new gviz.SquareColorWGLStyle({
|
|
142
|
+
colorCol: "2018",
|
|
143
|
+
tFun: (value, resolution, stats) => Math.pow(value / stats.max, 0.3)
|
|
144
|
+
})
|
|
145
|
+
],
|
|
146
|
+
{
|
|
147
|
+
//the maximum pixel size
|
|
148
|
+
pixNb: 3
|
|
149
|
+
})
|
|
150
|
+
```
|
|
151
|
+
(see [online](examples/basic_multiscale_tiled_CSV.html))
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
| Method | Arguments | Description |
|
|
155
|
+
| ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------ |
|
|
156
|
+
| _app_.**addCSVGridLayer**([args]) | See [example](#single-csv-file) | Add a layer from a CSV grid dataset. |
|
|
157
|
+
| _app_.**addMultiScaleCSVGridLayer**([args]) | See [example](#multi-scale-csv-data) | Add a layer from a multi scale CSV grid dataset. |
|
|
158
|
+
| _app_.**addTiledCSVGridLayer**([args]) | See [example](#tiled-csv-data) | Add a layer from a tiled CSV grid dataset. |
|
|
159
|
+
| _app_.**addMultiScaleTiledCSVGridLayer**([args]) | See [example](#multi-scale-tiled-csv-data) | Add a layer from a multi scale tiled CSV grid dataset. |
|
|
160
|
+
|
|
161
|
+
To manage creation of datasets and their possible reuse accross different layers (so that the data is loaded and stored once), the following methods are also available:
|
|
162
|
+
|
|
163
|
+
| Method | Arguments | Description |
|
|
164
|
+
| --------------------------------------------------- | --------- | ------------------------------------------ |
|
|
165
|
+
| _app_.**addLayerFromDataset**([args]) | - | Add a layer to the app. |
|
|
166
|
+
| _app_.**makeCSVGridDataset**([args]) | - | Make a CSV grid dataset. |
|
|
167
|
+
| _app_.**makeTiledCSVGridDataset**([args]) | - | Make a tiled CSV grid dataset. |
|
|
168
|
+
| _app_.**makeMultiScaleCSVGridDataset**([args]) | - | Make a multi scale CSV grid dataset. |
|
|
169
|
+
| _app_.**makeMultiScaleTiledCSVGridDataset**([args]) | - | Make a multi scale tiled CSV grid dataset. |
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
## Data pre-processing
|
|
173
|
+
|
|
174
|
+
TODO explain preprocess.
|
|
175
|
+
|
|
176
|
+
## Styles
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
### Shape/Color/Size Style
|
|
180
|
+
|
|
181
|
+
This style allows to define the **shape**, **color** and **size** of each grid cell individually.
|
|
182
|
+
|
|
183
|
+
See [this example](examples/styles/shapecolorsize.html).
|
|
184
|
+
|
|
185
|
+
### Square color WebGL Style
|
|
186
|
+
|
|
187
|
+
This style displays each cell as a square, with a changing color. This style uses webGL and should thus be used to display at detailled resolutions.
|
|
188
|
+
|
|
189
|
+
See [this example](examples/styles/squarecolorwgl.html).
|
|
190
|
+
|
|
191
|
+
### Composition style
|
|
192
|
+
|
|
193
|
+
This style shows a composition at cell level in various different ways: Flags, pie charts, rings, segments, radar, age pyramid and halftone.
|
|
194
|
+
|
|
195
|
+
See [this example](examples/styles/composition.html).
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
### Segment style
|
|
199
|
+
|
|
200
|
+
This style displays each cell as a segment with a changeable color, length, width and orientation.
|
|
201
|
+
|
|
202
|
+
See [this example](examples/styles/segment.html).
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
### Dot density style
|
|
206
|
+
|
|
207
|
+
This style displays each cell as randomly located points, with changeable density and color.
|
|
208
|
+
|
|
209
|
+
See [this example](examples/styles/dotdensity.html).
|
|
210
|
+
|
|
211
|
+
### Stroke style
|
|
212
|
+
|
|
213
|
+
This style shows the stroke of each cell with different colors, widths, shapes and sizes.
|
|
214
|
+
|
|
215
|
+
See [this example](examples/styles/stroke.html).
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
### Side style
|
|
219
|
+
|
|
220
|
+
This style extract the sides of the cells and show each of them depending on the values of the 2 cells around.
|
|
221
|
+
|
|
222
|
+
See [this example](examples/styles/side.html).
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
### JoyPlot Style
|
|
226
|
+
|
|
227
|
+
This style shows cell rows in the form of a 'joyplot' - named after Joy Division's "Unknown Pleasures" album cover.
|
|
228
|
+
|
|
229
|
+
See [this example](examples/styles/joyplot.html).
|
|
230
|
+
|
|
231
|
+
### Mosaic style
|
|
232
|
+
|
|
233
|
+
This style is a usual cell coloring style with a slight random deformation of the squares giving a 'mosaic' like effect.
|
|
234
|
+
|
|
235
|
+
See [this example](examples/styles/mosaic.html).
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
### Tanaka style
|
|
239
|
+
|
|
240
|
+
This style shows the grid cells in a Tanaka-like style, that is with discrete colors and shadow effect.
|
|
241
|
+
|
|
242
|
+
See [this example](examples/styles/tanaka.html).
|
|
243
|
+
|
|
244
|
+
### Lego style
|
|
245
|
+
|
|
246
|
+
This style shows the grid cells as lego bricks with changeable colors and height.
|
|
247
|
+
|
|
248
|
+
See [this example](examples/styles/lego.html).
|
|
249
|
+
|
|
250
|
+
### Pillars style
|
|
251
|
+
|
|
252
|
+
This style shows the grid cells as 3D pillars, with changeable heigths and colors.
|
|
253
|
+
|
|
254
|
+
See [this example](examples/styles/pillar.html).
|
|
255
|
+
|
|
256
|
+
### Text style
|
|
257
|
+
|
|
258
|
+
This style shows the grid cells as text characters with different colors.
|
|
259
|
+
|
|
260
|
+
See [this example](examples/styles/text.html).
|
|
261
|
+
|
|
262
|
+
### Kernel smoothing style
|
|
263
|
+
|
|
264
|
+
This style allows applying gaussian kernel smoothing to the grid.
|
|
265
|
+
|
|
266
|
+
See [this example](examples/styles/kernelsmoothing.html).
|
|
267
|
+
|
|
268
|
+
## Tooltip
|
|
269
|
+
|
|
270
|
+
TODO
|
|
271
|
+
|
|
272
|
+
## Legends
|
|
273
|
+
|
|
274
|
+
TODO
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
## Foreground information
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
### Showing labels
|
|
281
|
+
|
|
282
|
+
TODO
|
|
283
|
+
From https://github.com/eurostat/euronym
|
|
284
|
+
|
|
285
|
+
### Showing boundaries
|
|
286
|
+
|
|
287
|
+
TODO
|
|
288
|
+
From https://github.com/eurostat/Nuts2json
|
|
289
|
+
|
|
290
|
+
## About
|
|
291
|
+
|
|
292
|
+
| | |
|
|
293
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
294
|
+
| _contributors_ | [<img src="https://github.com/JoeWDavies.png" height="40" />](https://github.com/JoeWDavies) [<img src="https://github.com/jgaffuri.png" height="40" />](https://github.com/jgaffuri) |
|
|
295
|
+
| _version_ | See [npm](https://www.npmjs.com/package/gridviz?activeTab=versions) |
|
|
296
|
+
| _status_ | Since 2020 |
|
|
297
|
+
| _license_ | [EUPL 1.2](https://github.com/eurostat/Nuts2json/blob/master/LICENSE) |
|
|
298
|
+
|
|
299
|
+
## Support and contribution
|
|
300
|
+
|
|
301
|
+
Feel free to [ask support](https://github.com/eurostat/eurostat.js/issues/new), fork the project or simply star it (it's always a pleasure).
|
|
302
|
+
|
|
303
|
+
## Copyright
|
|
304
|
+
|
|
305
|
+
The [Eurostat NUTS dataset](http://ec.europa.eu/eurostat/web/nuts/overview) is copyrighted. There are [specific provisions](https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units) for the usage of this dataset which must be respected. The usage of these data is subject to their acceptance. See the [Eurostat-GISCO website](http://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units/nuts) for more information.
|
|
306
|
+
|
|
307
|
+
## Disclaimer
|
|
308
|
+
|
|
309
|
+
The designations employed and the presentation of material on these maps do not imply the expression of any opinion whatsoever on the part of the European Union concerning the legal status of any country, territory, city or area or of its authorities, or concerning the delimitation of its frontiers or boundaries. Kosovo*: This designation is without prejudice to positions on status, and is in line with UNSCR 1244/1999 and the ICJ Opinion on the Kosovo declaration of independence. Palestine*: This designation shall not be construed as recognition of a State of Palestine and is without prejudice to the individual positions of the Member States on this issue.
|