https://github.com/tgve/tgvejs
Turing Geo-Visualisation Engine
https://github.com/tgve/tgvejs
geospatial-analytics geospatial-visualization visualization
Last synced: 4 months ago
JSON representation
Turing Geo-Visualisation Engine
- Host: GitHub
- URL: https://github.com/tgve/tgvejs
- Owner: tgve
- License: mit
- Created: 2019-05-10T10:23:09.000Z (about 7 years ago)
- Default Branch: develop
- Last Pushed: 2025-04-24T23:27:38.000Z (about 1 year ago)
- Last Synced: 2025-10-25T08:18:39.688Z (8 months ago)
- Topics: geospatial-analytics, geospatial-visualization, visualization
- Language: JavaScript
- Homepage:
- Size: 17.5 MB
- Stars: 35
- Watchers: 6
- Forks: 7
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: change-log.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/tgve/tgve/actions?query=workflow%3A%22Node+CI%22)
[](https://badge.fury.io/js/@tgve%2Ftgvejs)  [](https://codecov.io/gh/tgve/tgvejs)
The Turing Geovisualisation Engine (TGVE) is a web-based,
interactive visual analytics tool for geospatial data analysis, built using R and JavaScript/React, that can be used as a complete server-client application or just as a front-end stand-alone application. The visual views and interaction mechanisms designed into the tool is underpinned by empirically-informed guidelines around
visualization design and techniques from Geographic Information Science (GIScience). Additionally, techniques from geographic information science (GIScience) and related domains are used
to implement automatic aggregation of temporal and
spatial data.
## npm package
> note: the older versions released under https://www.npmjs.com/package/eatlas is deprecated.
This is a React Component ES Module that can be embedded in your React applications. To install in your project:
```sh
npm install @tgve/tgvejs
# or
yarn add @tgve/tgvejs
```
Then, for an example to import the TGVE package and use it as the main component in a React app, see the [`tgve/app`](https://github.com/tgve/app) repo. Following is a snippet of ReactJS from that repo:
``` javascript
import React from 'react';
import Tgve from '@tgve/tgvejs';
function App() {
return (
);
}
```
### Configuration settings
TGVE supports separately-provided geography (in GeoJSON or Shapefile) and point data sources (in CSV). Other formats are not supported.
The following parameters can be passed to the TGVE app. Each parameter can be passed as an environment variable, with the exception of:
- leftSidebarContent
- data
For example: `REACT_APP_GEOGRAPHY_URL` or when using TGVE as a component
``. For more on passing variables to a React app and
the `REACT_APP_` prefix please see [React docs](https://create-react-app.dev/docs/adding-custom-environment-variables).
They can also be passed to the TGVE as URL query parameters. For instance
`localhost:3000?dark=false`.
- `data`: valid geojson object. This can be a component prop value, a URL query parameter or `{geojson:object}` as per standard [`script`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#embedding_data_in_html) tag use. If a valid GeoJSON object is provided both `defaultURL` and `geographyURL` will be ignored, which also means `geographyColumn` would be ignored, too.
- `defaultURL`: which returns a valid geojson object when `fetched`.
It can be used to fetch CSVs which is converted to `geojson` by
TGVE after fetching.
- `geographyURL`: which returns a valid `geojson` dataset. If this
variable is provided, data is fetched separately along with
`defaultURL`, TGVE uses the `geographyColumn` to join them. TGVE
does this on initialization and when `reset` button is pressed.
- `geographyColumn`: a column name which is shared between data within
the `defaultURL` and `geographyURL` or a mapping between the two. If
a mapping is provided it must be in this format:
`defaultURLColumnName:geographyURLColumnName`. This is the joining
column that will result in dynamically generating `geojson` data for
TGVE to consume. If a valid column name is not provided TGVE will attempt using the first matching column between the two files. If there is none, TGVE will load the geography data without the data.
- `column`: if provided, and if the geometry is of particular type
which would need a column, it would be used. Defaults on to the
second column as often first column is assumed to be an ID of sort.
- `select`: if provided, either as a string or a JSON object, it will be passed to the `tgvejs` subsetting workflow. For now, only when the application is started. The format could be one of `select={"key1": ["val1", "val2"]}` or `select=key1:val1,val2:key2:val3,val4`. For example: `https://tgve.github.io/app/?select=ranking:45` in a dataset with a column named `ranking` and its value being `45`.
- `layerName`: if provided, and if the given name is in the list of
DeckGL layers supported by TGVE, will be passed to generate the
layer with the name given.
- `dark`: by default `baseui/baseweb` is set to dark, you can change
the theme to other (e.g. light)
- `leftSidebarContent`: is based on React standard children. This is
where users can add their own UI and more, though this requires
competent React concepts. A simple use would be to pass plain text
description of data/project etc.
- `viewport`: TGVE’s main functionality is to auto-adjust the viewport
(see DeckGL docs). However, the initial viewport can be set using
this JSON parameter. The default values are:
`{longitude: -1.6362, latitude: 53.8321, zoom: 10, pitch: 55, bearing: 0}`.
Feel free to provide as little as you like, if any of these are missing, TGVE will draw them from these
default values.
- `hideChartGenerator` boolean value which would hide the sidebar
component which generates charts from the data.
- `hideCharts` boolean value which would hide all charts. This takes
priority over `hideChartGenerator` parameter.
- `hideSidebar` boolean value which would hide the left sidebar.
None of the above values is necessary and in the current release “Add data” button allows loading data into eAtlas.
#### Callbacks
The TGVE supports these callbacks since v1.5.1:
* `onViewStateChange`: a `function` to get the `viewport` of the TGVE which is passed from DeckGL. The returned object is described in DeckGL's documentations [here](https://deck.gl/docs/developer-guide/view-state-transitions). It contains zoom level, location information (longitude, latitude etc), current camera view (bearing and pitch) and transition details like "transitionDuration".
* `onStateChange`: a `function` to get a `JSON` object which contains the select (filter) state of the TGVE. As the state of the app changes the provided function is called. The returned object contains an object called `select` which contains columns selected (filtered) with values in an array like `{select:{columnName: [value1, value2]}}`
> In light of the above callbacks, when data is loaded in TGVE via "Add data" button from the local machine (i.e via FileReader API), the TGVE will disable other data sources until "reset" button is pressed.
### Shapefiles
For more about shapefiles please refer to [this](https://en.wikipedia.org/wiki/Shapefile) Wikipedia entry. The TGVE can read shapefiles if provided as a zip file using [`shapefile.js`](https://github.com/calvinmetcalf/shapefile-js). The package is used as external dependency, therefore, if you do use it make sure you have `` in your React app's `index.html` file. Then, just add the source as `defaultURL=www.domain/shape.zip`.
### Data and settings
As stated above, you can create a `script` tag to pass data and above configurations as `JSON` to where TGVE is being rendered; for example in an `index.html` where the component is rendered like:
```html
{'valid':'geojson'}
{'defaultURL':'https://raw.githubusercontent.com/layik/eatlas-data/main/casualties_100.geojson','dark':'false'}
```
## External dependenices
The package relies on Plotly to be available as `window.Plotly`. You can satisify this dependency by adding Plotly in your HTML build where the package is used. For instance version `2.6.3` minifed:
```html
```
If you are not sure, please see the [`app`](https://github.com/tgve/app) repository.
### Testing
The package follows `create-react-app` testing kits and uses mainly
`@testing-library/react` and `jest`.
Run `npm run test`.
## Contributing
See:
- [Contributor Code of Conduct](https://github.com/tgve/tgver/blob/master/CODE_OF_CONDUCT.md)
- [developer setup instructions](notes/dev-setup.md)
## Package Status
This package is part of ongoing research at the University of Leeds, is provided “as is” and is likely to be changed without warning to meet the research needs of the University.
## Citing TGVE
You can cit TGVE like:
```bib
@inproceedings {10.2312:evs.20231045,
booktitle = {EuroVis 2023 - Short Papers},
editor = {Hoellt, Thomas and Aigner, Wolfgang and Wang, Bei},
title = {{TGVE: a Tool for Analysis and Visualization of Geospatial Data}},
author = {Hama, Layik and Beecham, Roger and Lomax, Nik},
year = {2023},
publisher = {The Eurographics Association},
ISBN = {978-3-03868-219-6},
DOI = {10.2312/evs.20231045}
}
```
## Funding
The project is led by Dr [Nik
Lomax](https://environment.leeds.ac.uk/geography/staff/1064/dr-nik-lomax)
and Dr [Roger
Beecham](https://environment.leeds.ac.uk/geography/staff/1003/dr-roger-beecham)
and funded by the EPSRC via The Alan Turing Institute's AI for Science and
Government Programme, grant number EP/T001569/1.