-
Notifications
You must be signed in to change notification settings - Fork 9
Home
The Open City Toolkit (OCT) was developed in cooperation between the CityScienceLab of the HafenCity University Hamburg (HCU) and Deutsche Gesellschaft für Internationale Zusammenarbeit GmbH (GIZ) in India and Ecuador. It is an open source tool and the software for this project is based entirely on open source components. The Open City Toolkit is a web-based geographic information system (GIS) for multi-touch tables that is optimised for the use by non-GIS-experts. It supports integrated and participatory urban planning processes, fostering dialogue between governments and citizens and exchange of knowledge and data between government departments. The main functionality of the Open City Toolkit is to visualise and analyse complex urban data, jointly among local practitioners and with citizens. This manual is targeted to technical administrators of local OCT installations. It provides a high-level overview of the system’s design and guides administrators in the setup of the tool, including hardware and software installation, data preparation and maintenance.
The OCT is capable of running on a variety of devices ranging from tablet-sized mobile devices and desktop PCs to large touchscreens. This chapter focuses on the installation of a touchscreen device, similar to the one illustrated in Fig. 1.
For the best user experience, install the table indoors and protect it from extreme temperature and humidity conditions. Place it in such a way that no direct sunlight is cast on the screen; ideally keep any natural light out of the room.
Attach the screen and PC to a power source according to the devices’ specifications. Make sure the power source is free of interruptions and the cords are out of the way of users standing anywhere around the table.
Connect the computer to the local network, preferably using a wired connection. Internet access is required for background maps and, depending on the server configuration, it may also be required to access the tool itself and the geodata it works on.
Administrators of the OCT server(s) are required to have a basic understanding of:
- Linux server and command-line tools
The OCT is a web application, i.e. it can run either on the user’s computer or on a remote server. In any case, the machine the tool is installed on is referred to as the server.
Choosing the right server for the OCT will depend on a variety of factors, which are evaluated in this section.
On the one hand, there are certain hardware requirements that have to be met, depending on the usage profile (dataset size, number of users, desired speed etc.). On the other hand, there will be limits to the amount of money and time that can be spent on the hosting. Last but not least, there may be individual requirements regarding stability, security, or compliance.
The easiest way to get the tool running is to install it on the user’s machine. This could be an average PC or laptop, or the touchscreen’s integrated computer. The disadvantage of this approach will most likely be the limited processing power, memory, and storage capacity of the machine. Therefore this kind of setup is recommended only for testing purposes, not for production.
Technical parameters:
- OCT backend and GeoServer running on “localhost”
- Geodata stored on “localhost”
Pros:
- Easy installation
- No security or privacy concerns (only physical access to the machine needs to be regulated)
- Low cost
Cons:
- Hard limits for CPU units, memory and storage
- Not available to remote users
- Maintenance and backup require manual intervention
- Additional efforts will be needed if the computer does not run a Linux operating system
Installing the OCT on a remote server allows for better availability and scalability. However, it requires knowledge of server-side tools such as secure shell, web server, firewall etc. There is a wide range of service providers offering remote servers for a monthly fee, often with additional services such as 24/7 support.
Technical parameters:
- OCT backend and GeoServer running on remote server
- GeoServer running on the same server
Pros:
- Flexibility regarding the hardware configuration
- Remote access for both administrators and users
- Easy backup solutions are available
Cons:
- Some knowledge in Linux server administration is required
- Market research is required
- Security concerns need to be addressed
- More or less expensive
Installing OCT in the cloud basically means the same as installing it on a remote server, except that the service is provided by one of the leading cloud service providers, who offer highly configurable virtual machines, storage, and network services.
Technical parameters:
- OCT backend and GeoServer running in a dedicated instance or container
- Geodata stored in dedicated storage
Pros:
- Remote access for both administrators and users
- Maximum flexibility and scalability
- All-in-one solution for virtual machines, containers, storage, and DNS
- Automatic backup
- High availability setup is possible
Cons:
- Great deal of knowledge both in Linux server administration and cloud configuration is required
- Very expensive
The OCT source files can be obtained from the Github repository. Choose the right branch depending on the deployment location:
- For Bhubaneswar, India, use the “bhubaneshwar” branch.
- For Latacunga, Ecuador, use the “latacunga” branch.
- For all other locations, use the “master” branch (it is a generic version not tailored to a specific deployment location)
Please refer to the “README” file for detailed installation instructions. A video tutorial explaining the installation process is available, too. (Tutorial 2, Deployment)
Administrators of OCT datasets are required to have a basic understanding of:
- Geopackage, GeoJSON, OSM XML, GeoTIFF
- WMS, WFS
- GeoServer
- at least one desktop GIS (e.g. QGIS, GrassGIS, ESRI ArcMap)
OCT requires a base dataset, or base map, to be imported before any further analysis operations can be carried out (not to be confused with the background map, which is always available). This is achieved by selecting “Set basemap” in settings and uploading a downloaded extract of OpenStreetMap (OSM) data that covers the region users are interested in. The download can be obtained from OSM in several ways:
-
Using the OpenStreetMap Export page. It allows you to download the OSM data of the map shown in the browser, or from a custom bounding box. However, this works only for small regions. If it does not work, try the “Overpass API” link on the same page.
-
Using Geofabrik downloads. It provides ready-to-use OSM extracts covering whole countries or smaller administrative areas.
-
For more download options, please refer to the OpenStreetMap documentation.
After you have downloaded an OSM extract, use the “Set basemap” function in OCT to import it.
For a detailed description of this function please refer to the OCT user manual or the corresponding video tutorial describing the general overview, user interface and settings.
While some relevant map layers such as roads, waterways, and buildings are generated automatically, it is often necessary to import custom thematic maps and datasets into OCT as well. Depending on the type of geodata and the intended use, there are different ways to import them.
- If you want to add a new layer to the map, proceed to the section “Managing maps in GeoServer”.
- If you want to use a dataset for querying, proceed to the section “Managing maps in OCT”.
GeoServer is not only a geodata warehouse, but also a provider of map services. It is capable of handling a wide variety of geographic datasets in both raster and vector format. In order to add a map to OCT through GeoServer, follow the steps below.
See also: video tutorial to create thematic maps.
The data source (in GeoServer terminology it is called store) has to be prepared to meet the requirements of OCT. For this, it is best to use a desktop GIS of choice. Process the dataset so that it conforms to the following expectations:
-
EPSG 4326 projection is expected, to avoid long projection transformation processing time during the layer import into OCT.
-
UTF-8 character encoding is expected, to avoid incorrectly displayed characters.
-
Ambiguities and misspellings in the data shall be avoided.
-
Data topology shall be checked in order to avoid polygon overlaps or dangling nodes within the geometry. See QGIS Topology
-
Detailed metadata are required:
-
When abbreviations are used, explain their meaning
-
Define attribute field definitions
-
Indicate units used for numeric attributes
-
Indicate data source
-
Indicate licence
-
Indicate time of creation/last modification
-
When the data source is validated and ready to use, create a GeoServer data store for it.
Then, create a GeoServer layer for the data store you have added by publishing it. The layer configuration allows you to set its projection, boundaries, and other metadata. Additionally, it is suggested to set the layer’s style (with SLD or CSS) and its legend.
In order for the OCT to recognize the new layer, it is necessary to adjust its layer configuration. Currently this is only possible through modifying the JavaScript source code; the relevant code for the modification of map layers is found in webapp/views/map/script.js.
-
Add a Leaflet layer using the layer name you have used in GeoServer. Example:
-
Add the layer to the layer control. Example:
-
For the changes to take effect, you need to rebuild and restart the OCT Docker container.
Besides the rather complicated process of configuring layers in GeoServer, OCT offers an easy way to import maps, however, some limitations apply. Only files in GeoPackage, GeoJSON, OSM and GeoTIFF format are supported, and the imported datasets can be used by the “query” and “volcanic threat scenarios” only. They will not be added to the map. In order to upload a map file, use the “Add layer” function from the “Settings” panel in OCT. For a detailed description of this function please refer to the OCT user manual.
The Docker image is configured in a way that the chance of errors is reduced to a minimum. However, various issues may occur.
If building the image (“docker build” command) fails, there may be several reasons for it.
You must run the build command from the same directory that contains the Dockerfile, or provide the correct path in the command, e.g.:
`docker build -t oct <directory/containing/Dockerfile>
`