The Urban Toolkit: A Grammar-based Framework for Urban Visual Analytics
Project description
The Urban Toolkit (UTK)
The Urban Toolkit is a flexible and extensible visualization framework that enables the easy authoring of web-based visualizations through a new high-level grammar specifically built with common urban use cases in mind.
For a quick getting starter document and tutorials, visit: urbantk.org
UTK was first presented in the paper:
The Urban Toolkit: A Grammar-based Framework for Urban Visual Analytics
Gustavo Moreira, Maryam Hosseini, Md Nafiul Alam Nipu, Marcos Lage, Nivan Ferreira, Fabio Miranda
IEEE Transactions on Visualization and Computer Graphics (Accepted, to appear)
Features
- Easy integration of physical and thematic layers.
- Rapid iteration over the visualization design space.
- Data transformation to support visualization tasks.
- Support for 2D and 3D maps.
- Support for juxtaposed and embedded plots.
- Integration with OpenStreetMap.
Road map
- Aug 21: Python API description.
- Sep 15: Better support for macOS.
- Sep 15: Support for WRF data.
- Sep 30: Support for point cloud data.
Installation & quick start
UTK leverages several spatial packages, such as Geopandas, OSMnx, Shapely. To facilite the installation of UTK, we have made it available through pip, only requiring the following commands in a terminal / command prompt:
pip install utk
A detailed description of UTK's capabilities can be found in our paper, but generally speaking UTK is divided into two components: a backend component, accessible through UTK's Python library, and a frontend component, accessible through a web interface.
UTK backend
UTK's backend is available through our Python library. For example, using a Jupyter Notebook, it can be imported with:
import utk
To download data for Manhattan, NY, you only need to then:
uc = utk.OSM.load('Manhattan, NY', layers=['surface', 'parks', 'water', 'roads'])
uc.save('./manhattan')
This will create a new folder (manhattan
) with the downloaded and parsed OSM data. On top of that, UTK also offers functionalities to load data from shapefiles (utk.data.layer_from_shapefile
), csv files (utk.data.layer_from_csv
), dataframes (utk.data.layer_from_dataframe
), and also accumulate sunlight access values (utk.data.shadow
). A detailed description of UTK's Python API is coming soon.
UTK frontend
UTK's frontend is available through the utk
command. After the pip installation is complete, you can check a toy example with the following commands:
utk example
UTK's toy example will then be accessible through localhost:5001
. Starting and stopping UTK's server can be done using the following command:
utk start
utk stop
The utk
command takes the following arguments:
usage: utk [-h] [-d [DATA]] [-b [BUNDLE]] [-g [GRAMMAR]] [-a [ADDRESS]]
[-p PORT]
{start,list,stop,example}
The Urban Toolkit
positional arguments:
{start,list,stop,example}
Start, list or stop utk servers, or start server with
a simple example.
optional arguments:
-h, --help show this help message and exit
-d [DATA], --data [DATA]
Path to data folder.
-b [BUNDLE], --bundle [BUNDLE]
Path to app bundle (defaults to installed utk bundle).
-g [GRAMMAR], --grammar [GRAMMAR]
Path to grammar JSON file, if different from
[DATA]/grammar.json (default: [DATA]/grammar.json).
-a [ADDRESS], --address [ADDRESS]
Server address (default: localhost).
-p PORT, --port PORT Server port (default: 5001).
Even though we offer support for a variety of arguments, most users will simply need to run the following to use data stored in a folder called ./data/
:
utk start --data ./data
After starting UTK's server and opening localhost:5001
on a browser, you will see UTK's main interface, composed of a grammar editor (left) and map viewer (right). Adding new elements to the grammar specification on the right (e.g., new plots, new data) will automatically update the map viewer:
Tutorials
Step-by-step tutorials are available on our website. These tutorials highlight how UTK can be used to create sophisticated urban visualizations.
A detailed description of UTK's grammar can be found here.
Team
- Gustavo Moreira (UIC)
- Maryam Hosseini (MIT)
- Md Nafiul Alam Nipu (UIC)
- Marcos Lage (UFF)
- Nivan Ferreira (UFPE)
- Fabio Miranda (UIC)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.