{"id":46034856,"url":"https://github.com/tgve/tgvejs","last_synced_at":"2026-03-01T04:43:38.746Z","repository":{"id":37953230,"uuid":"185968373","full_name":"tgve/tgvejs","owner":"tgve","description":"Turing Geo-Visualisation Engine","archived":false,"fork":false,"pushed_at":"2025-04-24T23:27:38.000Z","size":18384,"stargazers_count":35,"open_issues_count":6,"forks_count":7,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-10-25T08:18:39.688Z","etag":null,"topics":["geospatial-analytics","geospatial-visualization","visualization"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgve.png","metadata":{"files":{"readme":"README.md","changelog":"change-log.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-10T10:23:09.000Z","updated_at":"2025-10-18T01:54:18.000Z","dependencies_parsed_at":"2023-02-18T15:15:58.076Z","dependency_job_id":"e4c83416-b205-418d-b9cc-c36610b2a69d","html_url":"https://github.com/tgve/tgvejs","commit_stats":{"total_commits":863,"total_committers":8,"mean_commits":107.875,"dds":"0.21320973348783312","last_synced_commit":"15baee95c4296c9b7055251a8c5b1a95476f87b5"},"previous_names":["layik/eatlas"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/tgve/tgvejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgve%2Ftgvejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgve%2Ftgvejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgve%2Ftgvejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgve%2Ftgvejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgve","download_url":"https://codeload.github.com/tgve/tgvejs/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgve%2Ftgvejs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29960253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geospatial-analytics","geospatial-visualization","visualization"],"created_at":"2026-03-01T04:43:38.224Z","updated_at":"2026-03-01T04:43:38.730Z","avatar_url":"https://github.com/tgve.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Node CI](https://github.com/tgve/tgvejs/workflows/Node%20CI/badge.svg?branch=release)](https://github.com/tgve/tgve/actions?query=workflow%3A%22Node+CI%22)\n[![npm version](https://badge.fury.io/js/@tgve%2Ftgvejs.svg)](https://badge.fury.io/js/@tgve%2Ftgvejs) ![GitHub package.json version](https://img.shields.io/github/package-json/v/tgve/tgvejs?label=gh%3Aversion) [![codecov](https://codecov.io/gh/tgve/tgvejs/branch/develop/graph/badge.svg?token=FnXegSkNXD)](https://codecov.io/gh/tgve/tgvejs)\n\nThe Turing Geovisualisation Engine (TGVE) is a web-based,\ninteractive 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\nvisualization design and techniques from Geographic Information Science (GIScience). Additionally, techniques from geographic information science (GIScience) and related domains are used\nto implement automatic aggregation of temporal and\nspatial data.\n\n\u003c!-- https://user-images.githubusercontent.com/408568/76419738-c46edc80-6398-11ea-8bbe-496394f90adc.png --\u003e\n\u003cimg width=90% alt=\"TGVE screen shot\" src=\"https://user-images.githubusercontent.com/408568/195129362-92b9fc70-e5b7-4895-9331-162324e53e76.png\"\u003e\n\n\n## npm package\n\n\u003e note: the older versions released under https://www.npmjs.com/package/eatlas is deprecated.\n\nThis is a React Component ES Module that can be embedded in your React applications. To install in your project:\n\n```sh\nnpm install @tgve/tgvejs\n# or\nyarn add @tgve/tgvejs\n```\nThen, 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:\n\n``` javascript\nimport React from 'react';\nimport Tgve from '@tgve/tgvejs';\n\nfunction App() {\n  return (\n    \u003cTgve defaultURL={process.env.REACT_APP_DEFAULT_URL}/\u003e\n  );\n}\n```\n\n### Configuration settings\n\nTGVE supports separately-provided geography (in GeoJSON or Shapefile) and point data sources (in CSV). Other formats are not supported.\n\nThe following parameters can be passed to the TGVE app. Each parameter can be passed as an environment variable, with the exception of:\n- leftSidebarContent\n- data\n\nFor example: `REACT_APP_GEOGRAPHY_URL` or when using TGVE as a component\n`\u003cTgve geographyURL=\"https://geo.com\"\u003e`. For more on passing variables to a React app and\nthe `REACT_APP_` prefix please see [React docs](https://create-react-app.dev/docs/adding-custom-environment-variables).\n\nThey can also be passed to the TGVE as URL query parameters. For instance\n`localhost:3000?dark=false`.\n\n-   `data`: valid geojson object. This can be a component prop value, a URL query parameter or `\u003cscript id=\"tgve-data\" type=\"application/json\"\u003e{geojson:object}\u003c/script\u003e` 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.\n\n-   `defaultURL`: which returns a valid geojson object when `fetched`.\n    It can be used to fetch CSVs which is converted to `geojson` by\n    TGVE after fetching.\n\n-   `geographyURL`: which returns a valid `geojson` dataset. If this\n    variable is provided, data is fetched separately along with\n    `defaultURL`, TGVE uses the `geographyColumn` to join them. TGVE\n    does this on initialization and when `reset` button is pressed.\n\n-   `geographyColumn`: a column name which is shared between data within\n    the `defaultURL` and `geographyURL` or a mapping between the two. If\n    a mapping is provided it must be in this format:\n    `defaultURLColumnName:geographyURLColumnName`. This is the joining\n    column that will result in dynamically generating `geojson` data for\n    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.\n\n-   `column`: if provided, and if the geometry is of particular type\n    which would need a column, it would be used. Defaults on to the\n    second column as often first column is assumed to be an ID of sort.\n\n-   `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`.\n\n-   `layerName`: if provided, and if the given name is in the list of\n    DeckGL layers supported by TGVE, will be passed to generate the\n    layer with the name given.\n\n-   `dark`: by default `baseui/baseweb` is set to dark, you can change\n    the theme to other (e.g. light)\n\n-   `leftSidebarContent`: is based on React standard children. This is\n    where users can add their own UI and more, though this requires\n    competent React concepts. A simple use would be to pass plain text\n    description of data/project etc.\n\n-   `viewport`: TGVE’s main functionality is to auto-adjust the viewport\n    (see DeckGL docs). However, the initial viewport can be set using\n    this JSON parameter. The default values are:\n    `{longitude: -1.6362, latitude: 53.8321, zoom: 10, pitch: 55, bearing: 0}`.\n    Feel free to provide as little as you like, if any of these are missing, TGVE will draw them from these\n    default values.\n\n-   `hideChartGenerator` boolean value which would hide the sidebar\n    component which generates charts from the data.\n\n-   `hideCharts` boolean value which would hide all charts. This takes\n    priority over `hideChartGenerator` parameter.\n\n-   `hideSidebar` boolean value which would hide the left sidebar.\n\nNone of the above values is necessary and in the current release “Add data” button allows loading data into eAtlas.\n\n#### Callbacks\nThe TGVE supports these callbacks since v1.5.1:\n* `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\".\n\n* `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]}}`\n\n\u003e 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.\n\n### Shapefiles\nFor 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 `\u003cscript src=\"https://unpkg.com/shpjs@latest/dist/shp.js\"\u003e\u003c/script\u003e` in your React app's `index.html` file. Then, just add the source as `defaultURL=www.domain/shape.zip`.\n\n### Data and settings\n\nAs 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:\n\n```html\n\u003c!--notice the ID names--\u003e\n\u003cscript id=\"tgve-data\" type=\"application/json\"\u003e{'valid':'geojson'}\u003c/script\u003e\n\u003cscript id=\"tgve-settings\" type=\"application/json\"\u003e{'defaultURL':'https://raw.githubusercontent.com/layik/eatlas-data/main/casualties_100.geojson','dark':'false'}\u003c/script\u003e\n\n```\n\n## External dependenices\nThe 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:\n\n```html\n\u003cscript src=\"https://cdn.plot.ly/plotly-2.6.3.min.js\"\u003e\u003c/script\u003e\n```\nIf you are not sure, please see the [`app`](https://github.com/tgve/app) repository.\n\n\n### Testing\n\nThe package follows `create-react-app` testing kits and uses mainly\n`@testing-library/react` and `jest`.\nRun `npm run test`.\n\n## Contributing\n\nSee:\n- [Contributor Code of Conduct](https://github.com/tgve/tgver/blob/master/CODE_OF_CONDUCT.md)\n- [developer setup instructions](notes/dev-setup.md)\n\n## Package Status\n\nThis 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.\n\n## Citing TGVE\n\nYou can cit TGVE like:\n```bib\n@inproceedings {10.2312:evs.20231045,\nbooktitle = {EuroVis 2023 - Short Papers},\neditor = {Hoellt, Thomas and Aigner, Wolfgang and Wang, Bei},\ntitle = {{TGVE: a Tool for Analysis and Visualization of Geospatial Data}},\nauthor = {Hama, Layik and Beecham, Roger and Lomax, Nik},\nyear = {2023},\npublisher = {The Eurographics Association},\nISBN = {978-3-03868-219-6},\nDOI = {10.2312/evs.20231045}\n}\n```\n\n## Funding\n\nThe project is led by Dr [Nik\nLomax](https://environment.leeds.ac.uk/geography/staff/1064/dr-nik-lomax)\nand Dr [Roger\nBeecham](https://environment.leeds.ac.uk/geography/staff/1003/dr-roger-beecham)\nand funded by the EPSRC via The Alan Turing Institute's AI for Science and\nGovernment Programme, grant number EP/T001569/1.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgve%2Ftgvejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgve%2Ftgvejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgve%2Ftgvejs/lists"}