Publish

Publishing Geospatial Data

Pedro R. Andrade, Heitor Carneiro

This tutorial works with TerraME 2.0-RC-5 or grater and publish version 0.4.1 or greater.

Summary

• Introduction
• Application and View
• Report
• Other examples
• Making Application Available
• Editing the Final Application

Introduction

Communicating geospatial data produced by scientific projects is a difficult task. Solutions usually involve publishing the data using standard formats such as shapefiles or geotiff. Any more elaborate solution requires some programming knowledge in languages such as Javascript and HTML. This tutorial presents a simple way to publish geospatial data as a Google Maps applications.

Every application is built using a Project, stored as a tview file. It defines a set of Layers that indicate the location where each data is stored. The idea is that, once the project is created, the user only manages the layer name when creating an Application. The code below shows a project stored in file brazil.tview. Layer biomes is stored in the same directory where the script is saved (and where brazil.tview will be created after running the script), while states is stored in directory c:/mydata. It is usually recommended to store the data in the same directory of the script to facilitate describing the layers.

import("gis")

project = Project{
	file = "brazil.tview",
	clean = true,
	biomes = "br_biomes.shp",
	states = "c:/mydata/br_states.shp"
}

In this tutorial, we are going to use two layers, biomes and states, that use data stored in publish package. It is possible to use filePath() to refer to this data instead of describing its location in the computer. See the code below.

import("gis")

project = Project{
	file = "brazil.tview",
	clean = true,
	biomes = filePath("br_biomes.shp", "publish"),
	states = filePath("br_states.shp", "publish")
}

Application and View

The main concept of publish package is Application. An Application represents a Google Maps instance with additional data provided by the selected project. The code below shows a very simple Application using project brazil.tview defined above. It uses the following arguments:

• A title to be displayed in the top of the application.
• A description to be shown when the application is initialised (the user has to press Ok after the description to start using the application).
• An output indicates where the final application will be stored in the computer.
• Two Views describe which data will be used and how the data will be displayed. The name of each View must match the name of a Layer in the Project. View biomes will be painted according to the values of attribute name, using colors described by Set2. All states will be all drawn with yellow. Each of them also has a description to be shown in the left panel.

import("publish")

Application{
    project = "brazil.tview",
    title = "Brazil Application",
    description = "Small application with some data related to Brazil.",
    clean = true,
    output = "BrazilWebMap",
    biomes = View{
        select = "name",
        color = "Set2",
        description = "Brazilian Biomes, from IBGE."
    },
    states = View{
        color = "yellow",
        description = "Brazilian states, from IBGE"
    }
}

When this script is executed in TerraME, it creates a directory named BrazilWebMap in the same directory where the script is stored. The files created within this directory have no Lua code and do not depend on TerraME to be executed. Is it even possible to update the code of the created application manually, taking care not to run the script again to avoid overwriting it. See the last section of this tutorial for a description of the created files. By opening index.html within this directory, the browser will display an application as below after pressing Ok. You can also run the application by clicking here.

When the application is on the Web, it can be opened with different web browsers. However, opening index.html directly might not work depending on the default browser. If you use Firefox, it is possible to open index.html directly. If you use Chrome, it is necessary to install 200 OK! Web Server for Chrome and also set you Google Developer Key using the argument Application:key in the source code before creating the application. Other browsers were not tested for local applications.

This webpage has all features of a Google Maps application, such as pane, zoom, and select a base map. Additionally, it is possible to configure which data of the application will be visualized using the left panel.

Publish automatically reprojects all the input data to projection EPSG:4326 (i.e. GCS_WGS_1984). If the final visualization does not work properly, please reproject the input data to this projection before creating the application. This is usually the main problem in the data.

Report

In the final application, each geospatial entity, be it a point, line, or polygon, can have a Report associated to it. Reports are more interesting than showing data in a table format, as usually displayed in a desktop GIS. They can link metadata with attribute values by merging both into a single and more readable format that can be used to communicate geospatial data to the end user. For example, it is possible to use the description of attributes instead of only their names, convert numeric categorical values to their real meanings, as well as add units of measurements and temporal aspects to the description of attribute values. Package publish supposes all the relevant attributes for the application were already created. In this sense, the script only uses such attributes to feed the final application, without executing any geospatial operation. Every View can be associated to a Report through a user-defined function called report that gets a geospatial object and returns a Report. There are two basic functions to add information to the Report: addImage and addText. See the example below a Report that is implemented within definition of View biomes. When TerraME creates an application from a script that contains a Report, it creates a report for each geospatial object of the Layer by calling calling this function with each of them as argument.

        report = function(cell)
            local mreport = Report{
                title = cell.name,  -- "name" is an attribute of object
                author = "IBGE"
            }

            mreport:addImage(filePath("biomes/"..cell.name..".jpg", "publish"))
            mreport:addText("For more information, please visit "..link(links[cell.name], "here")..".")

            return mreport
        end

Note that this code uses a variable named links, with the web addresses of each biome. It must be declared before the application and, in this case, it has the content shown below. The attribute "Mata Atlantica" is declared using brackets as it has a space in its name. This way, each report will have a link to a Wikipedia page of its biome. These values could be stored in the shapefile as attributes of the biomes, but the intention here is to keep the original data from IBGE as is.

links = {
    Amazonia           = "en.wikipedia.org/wiki/Amazon_biome",
    Caatinga           = "en.wikipedia.org/wiki/Caatinga",
    Cerrado            = "en.wikipedia.org/wiki/Cerrado",
    Pampa              = "en.wikipedia.org/wiki/Pampas",
    Pantanal           = "en.wikipedia.org/wiki/Pantanal",
    ["Mata Atlantica"] = "en.wikipedia.org/wiki/Atlantic_Forest"
}

The report above produces the application available here. Now it is possible to click in each biome to see a report like the one shown below.

Other examples

Additional examples can be found at publish GitHub page. Other online applications are:

• Communities of BR-230, in Para state
• Social classes scenarios for Caragua municipality, in Sao Paulo state
• Sanitary landfills of Sao Paulo state (in portuguese)

Making Application Available

After creating an application, it is possible to make it available in the Internet by copying it to a web server. This section shows how to make it freely available using GitHub. The following steps make the application available. Some of them might be unnecessary if you already have used the necessary tools.

1. Create a GitHub account here if you do not have one.
2. Once you have logged in, click in the green button to create a New repository.
3. Choose a name for your repository, click in Initialize this repository with a README and then click in Create repository. Your repository will look like as follows:

4. Click in Upload files. Drag and drop all the files within the directory of the created application to GitHub and then click in the green button Commit changes.
5. You can visualize your application in the following address: https://rawgit.com/YOUR-USER-NAME/YOUR-REPOSITORY-NAME/master/index.html
6. It is also possible to create a short url using services like bit.ly.

Editing the Final Application

The applications created by publish do not depend on TerraME and can be edited afterwards. This session contains information about the internal content of the created files. All the files with .min.js are minified versions. It is possible to find their original versions within publish package.

The created directory has the following content:

• index.html: The file that executes the Application in a web browser. It comes with Bootstrap library. Opening this file in a web browser executes the application.
• default.gif: A gif file shown when the application is being loaded. It is possible to use another gif by setting the argument loading while defining the Application.
• config.js: Javascript code with a set of configuration variables for the application, describing each View. It has properties such as the names of each view, their description, if they are visible in the beginning of the application, and colors for their legends.
• jquery-3.1.1.min.js: Minified version of JQuery library.
• publish.min.js: Minified JavaScript file that defines the main functionalities of the application. It controls all events of an application, such as loading the data to be added to Google Maps API, changing displayed layers, mouse events, besides updating the menu.
• publish.min.css: File that describes the application's layout, with positions, margins, alignments, etc.
• *.geojson: Files with geospatial data exported in a way that the web browser can understand (json file format). Each View is exported as a single geojson file. These files will be downloaded to the computer of the final user when the application is initialized.
• Other files: Image files shown in the report are copied to the application directory to make it self contained.