GEOPAN ATL@S APP TECHNICAL MANUALgeoserver.atlas.polimi.it/examples/servlets/Geopan/... · GeoPAN Atl@s APP GeoPAN Atl@s APP – Technical Manual Last modification 15 November 2016

Politecnico di Milano Dipartimento di architettura, ingegneria delle costruzioni e ambiente costruito (DABC)

GeoPAN Atl@s APP – User Manual

Last modification 20 septembre 2016

Author POLIMI –DABC - GIcarus Lab Version : 1.0 Page 1 / 13

GEOPAN ATL@S APP

TECHNICAL MANUAL

Technical Manual GeoPAN Atl@s APP

GeoPAN Atl@s APP – Technical Manual

Last modification 15 November 2016


Table of Contents

LIST OF ILLUSTRATIONS 3

NAMING CONVENTIONS 4

1. INTRODUCTION 5

2. INFORMATION FOR USE OF THE DOCUMENTATION 5

3. SYSTEM CHARACTERISTICS 6

4. SYSTEM ARCHITECTURE 7

5. DESIGN METHODS AND STANDARDS 8

6. PROGRAMMING STANDARDS 9

7. DEVELOPMENT TOOLS 11

8. RELATED INFORMATION - SOURCES 13





List of illustrations

Figure 1. GeoPAN Atl@s homepage 5

Figure 2: GeoPan Atl@s multi layered architecture 7

Figure 3: GeoPan Atl@s communication interfaces 8

Figure 4: GeoPan Atl@s general structure 9

Figure 5: GeoPan Atl@s structure 9





Naming conventions

Naming Description

APK Android application package

API Application programming interface

APP Application

CSS Cascading Style Sheets

ENERGIC OD European NEtwork for Redistributing Geospatial Information to user

Communities- Open Data

GUI Graphic User Interface

HTML HyperText Markup Language

JS JavaScript

KML Keyhole Markup Language

OGC Open Geospatial Consortium

OSM OpenStreetMap

VH Virtual Hub

WCS Web Coverage Service

WFS Web Feature Service

WMS Web Map Service

WMTS Web Map Tile Service





1. INTRODUCTION

The purpose of this document is to provide a technical description of the GeoPan Atl@s APP (Figure 1). This document provides information about characteristics, architecture, tools and programming standard of the GeoPan Atl@s APP for its future maintenance and further updates. In particular, this document covers the following contents:

• Characteristics of the developed application: major features of the APP and their relationship with user requirements;

• System architecture: components (software and hardware) and interfaces of the developed application;

• Design methods and standards: the development strategy adopted to implement the APP and its general structure;

• Programming standards: standards and libraries adopted in the implementation of the GeoPan Atl@s APP;

• Development tools: software tools and the development framework used for the GeoPAN Atl@s APP.

Figure 1. GeoPAN Atl@s homepage

2. INFORMATION FOR USE OF THE DOCUMENTATION

This documentation is primarily prepared for technical stuff in charge of maintaining and updating the GeoPAN Atl@s APP. Indeed, even if the GeoPan Atl@s APP was designed so that a minimum effort is needed to guaran-tee its maintenance, to guarantee its operational status in the case of external libraries and/or VH updates, some update activities can be foreseen. In those cases the current document can be used as a reference. In particular, this document provides information about the version of external libraries (e.g., jQuey, jQuery Mobile, etc.) that are used in the GeoPAN Atl@s allowing an easy update to new releases.





The GeoPAN Atl@s APP was designed to be easily extended both in terms of geographical cover-age. For example, the APP is currently focusing on the Lombardy region but it can be extended to other regions or possibly to the whole Italy. The expansion could also be considered in terms of pro-vided services such as new functionalities that can be added to fulfill requirements of new users in domain of land change monitoring and management. This document can give a clear understanding of the application architecture and facilitate its update identifying the way in which new features can be integrated in the current framework. This document can also be of a certain interest for application developers. Indeed, the developing criteria used for the GeoPAN Atl@s APP can be easily extended to develop a new application based on the Italian Virtual Hub developed in the framework of ENERGIC OD.

3. SYSTEM CHARACTERISTICS

This section is focusing on the major features implemented in the GeoPAN Atl@s app and their rela-tionship with the technical and non-technical requirements identified in D6.1 (ENERGIC OD Consorti-um, 2015). Some basic requirements such as map navigation, zooming and data visualization are here skipped while an higher attention is paid to major features specific of the APP. Table 1 summa-rizes the major features of the APP and their link with the User requirements. Some more details about the features are presented in section 5 (Design methods and standards).

User Requirement APP features • Display publicly available information on

territorial development (e.g. land use/land cover changes)

• The user is provided with a tool to find the past and the current riverbeds in Lombardy Re-gion along with other datasets like river flooding protection areas and seismic areas (Ricerca Fiume)

• Configurable for various target groups and use cases

• The user is provided with a tool to access specific datasets for geologists (Ricerca Fiume) and a wider range thematic datasets (Ricerca libera)

• Change layer transparencies in order to compare specific land/landscape features

• The user is provided with a tool for manag-ing the transparency of dataset by using a slider tool (Lista layer)

• The user is provided with a tool that offers the capability to change freely the base layer. The base layers available are Bing Maps (satellite, roads or hybrid) and OSM (Lista layer).

• Geolocation of positions and itineraries • Geolocation and display of photos taken by

the user

• The user is provided with a a tool for geolo-cating his/her position and tracking a path (Geolocalizzazione)

• Calculate distances and areas • The user is provided with a tool for calculat-ing distances and areas (Disegna)

• Drawing (point, polygons and polylines) and annotation functions

• Export of data in commonly known format (eg. KML files)

• The user is provided with a tool for drawing points, lines and polygons and with a tool to export these features as KML as well as GeoJson files (Disegna)

• Add, visualise and interact with datasets in different formats and services

• Datasets are accessed using specific queries to the Italian VH that allows the access of dif-ferent data formats and services (e.g., shp, WMS, etc.)

Table 1: User requirements and related APP feature





4. SYSTEM ARCHITECTURE

The app GeoPan Atl@s solution is designed to have a multilayer architecture. This layered architec-ture is shown in the following Figure 2.

Figure 2: GeoPan Atl@s multi layered architecture

The presentation layer contains the GeoPan Atl@s web application with the HTML user interfaces, which are accessed from clients (smartphones, tablets, laptops, PCs) via http. This tier is warped also in .apk files to be used on Android devices.

The Virtual Hub layer provides the homogeneous access to a set of various data sources. These can be classified as “POLIMI Open Data” and External Open Data Sources. “POLIMI Open Data” are a set of layers that are made available as Open Data by POLIMI for purposes of GeoPan APP (further details are given in the description of the publishing tier). External Open Data sources are open ser-vices (mainly OGC’s) and data sets (mainly Esri Shapefiles) provided by third parties (e.g., Public Administration, research centres, etc.) that are accessed through the Italian VH.

The publishing layer provides the necessary business-logic functions in the form of a service-oriented infrastructure (SOA) that can be addressed by the Virtual Hub layer through web-based OGC stand-ard interfaces. In particular, of major interest are the services provided by POLIMI for publishing POLIMI Open Data:

• Geoserver (http://geoserver.org/): Provides OGC map services (WMS, WMTS, WFS,





WCS);

• Geonetwork Opensource (http://geonetwork-opensource.org/): provides a CSW service for the published datasets.

The data layer contains all data of the system (configuration and business data).

GeoPan ATl@s communicates with the Italian VH by means of the exposed JavaScript web APIs, while connection with data providers is performed according to OGC standards. Interaction between user and GeoPAN solution is an HTML-based GUI of the Web App in browser while interaction be-tween the user browser and GeoPAn Atl@s APP is based on HTTP. The GeoPan ATl@s can also be accessed as .apk for Android devices. Communication interfaces between the GeoPAN application and external systems are summarized in Figure 3.

Figure 3: GeoPan Atl@s communication interfaces

The different layers require specific hardware. In particular, server services require a dedicated com-puter running with high availability. Basically there are two servers:

1) The Web Server contains the web application and the web services of the solution.

2) The data server contains the used database with the needed data. If needed, database specific load balancing features can be used to distribute data on multiple servers and thus re-spond to high usage.

Currently these production web servers are provided by POLIMI- ASICT service which is character-ized by 520 GB of hard drive and 16 GB RAM. In order to run the application, users will need a regu-lar computer, with no particular hardware restrictions. For mobile visualization with .apk file an An-droid smartphone or tablet is needed.

5. DESIGN METHODS AND STANDARDS

GeoPAN Atl@s APP client is developed as a classic HTML/CSS/JS by using the Apache Cordova

technology (Phonegap). All source codes are available in those formats.

GeoPan ATl@s is designed to be close in contact with the Italian VH, in particular it communicate

with the Italian VH by means of JavaScript web APIs, while connection with data providers is per-

formed according to standard OGC standards. Figure 4 gives an overview of the different tier and

their connection.





Figure 4: GeoPan Atl@s general structure

6. PROGRAMMING STANDARDS

The application client is developed as a classic HTML/CSS/JS. The overall structure of the APP is Summarized in Figure 5.

Figure 5: GeoPan Atl@s structure





The APP consist of two main components: the first one is the Map canvas that uses OpenLayers li-brary (see also section 7) to display maps and allows user interaction with the displayed maps; the second one are the interaction panels that allows user to retrieve layers, interact with them, create new contents and save them, geolocate and provide feedbacks. Interaction panels are ajax loaded after the JavaScript inclusion is completed. Here a brief description of the different panels is given: Ricerca fiume (Search River) This panels allows users to select the river they want to analyse (the river can be selected from a list), the datasets they are interested in (that can be chosen from a dropdown list) and the reference year (that can be selected from a dropdown list). All these information are combined to perform a request trough the Italian VH to retrieve the desired layers. In particular a request with the keywords #lay-er_name+#reference_year+#dataset_type is performed. The results on the search are loaded in the panel named “Visulizza risultati” show results. Source files “searchRiverPanel.html”, “GeopanLayer-Manager.js”, “GeopanSearchManager.js” and “Geopan.js” are specifically involved in these opera-tions. Search results are stored in mySearchresults object. Ricerca libera (Free Search) This panels allows users to perform a free query trough the Virtual Hub. The user can select a set of keywords, temporal and spatial constraints (that can be also imported from the Map Canvas). These constraints, all of them or a subset, are used to perform a query trough the Italian VH. The results on the search are loaded in the panel named “Visulizza risultati” show results. Source files “search-Panel.html”, “GeopanLayerManager.js”, “GeopanSearchManager.js” and “Geopan.js” are specifically involved in these operations. Search results are stored in mySearchResults object. Visualizza risultati (Show results) Results coming from a specific query are loaded in this panel. Results loaded in the results panel can came from a river search, a free search or a search in the historic catalogue. The user can select the layer they are interested in and the layer is loaded in the panel “Lista layer” (layer list). Selected files are also passed as layers to OpenLayers to be dispayed in the Map Canvas. Source files “searchResultsPanel.html”, “GeopanLayerManager.js” and “Geopan.js” are specifically involved in these operations. Selected layers are passed to myLayerManager object. Lista layer (Layer list) The layer list panel allows the interaction with layers in the Map Canvas trough OpenLayers. The user can select from a dropdown list a base layer. The base layer can be selected from OpenStreetMap or Bing Maps. Thematic layers can be selected from a dropdown list and the following features can be changed: layer opacity, layer order and layer visibility. Layer opacity and layer visibility are handled directly with OpenLayers while the layer order is handled firstly by “GeopanLayerManager.js”, and the myLayer-Manager object is then passed to Openlayers to handle the visualization. Source files “layerPanel.html”, “GeopanBaseLayerManager.js”,“GeopanLayerManager.js” and “Ge-opan.js” are specifically involved in these operations. Catalogo storico (Layer list) This panel allows for the selection of an historic map from an historic catalogue. The historic cata-logue is loaded with the JavaScript “geopancataloge.js”. The user can perform a query of the map they are interested in by perming these three steps:

• Choose area of interest (city, region, etc.); • Choose map container; and • Select a historic map.

The user can select the layer they are interested in and the layer is loaded in the panel “Lista layer” (layer list). Selected files are also passed as layers to OpenLayers to be dispayed in the Map Canvas. Selected layers are passed to myLayerManager object.





Source files “cataloguePanel.html”, “catalogueitem.js”, “geopancataloge.js”, “GeopanLayerManag-er.js” and “Geopan.js” are specifically involved in these operations. Strumenti (Tools) This panel allows redirection to:

• Ricerca posizione (Find Address); • Geolocalizzazione (Geolocate); • Inizia disegno (Edit/Draw); and • Impostazioni (Settings).

Ricerca Posizione (Find address) This panel allows for searching a specific address. This function use Google Map Geocoding API. These APIs allows for converting addresses into geographic coordinates that can be used to place a marker of the map canvas. In particular, the marker used as output of this search is loaded in the “vectorLayer” directly in the Openlayer map object. Source files “toolPanel.html” is specifically involved in this operation. Geolocalizzazione (Geolocate) This panel allows to geo-locate positions and to record itineraries. This function uses the Cordova plugin for geolocation. The location is added in the layer “drawingGroup” and it is shown in the map canvas. The position and the path can be downloaded both as .geojson and .kml files. Source files “geolocationPanel.html” and “geolocation.js” are specifically involved in these operations. Disegno (Edit) This panel allows for drawing features on the map (points, lines and polygons). The object can be selected from a dropdown list and it is drawn in the map Canvas. The drawing is added in the layer “drawingGroup” can be downloaded both as .geojson and .kml files. A switch button allows the visual-ization of the dimensions of the drawn elements. Source files “drawinfPanel.html”, “featuredrawing.js”, “measurePanel.html” and “measureUtils.js” are specifically involved in these operations. Feedback (Feedback) This panel allows for reporting user feedbacks. This panel incorporates a Google form that the user can fill in and send to developers. Source file for this panel are “creditsPanel.html” and “creditsPan-el.js”. Credits (Credits) This panel shows credits to the project and development team. Source file for this panel is “cred-itsPanel.html”.

7. DEVELOPMENT TOOLS

GeoPan Atl@s is developed using the Apache Cordova technology (Phonegap). The application cli-ent is system independent since frontend/interface is developed as a classic HTML/CSS/JS approach by using the well-known library (see the following paragraph for a comprehensive list of the used frameworks and libraries) while the VirtualHUB library itself is wrapped in specific classes. The appli-cation is currently tested and deployed only on Android devices. However, by using the Phonegap package the possibility exists to bring the same application to other ecosystems such as iOS or Win-dows Phone with relative ease. The GeoPan ATl@s is also provided as a web APP, also in this case only a modern browser with HTML5 support and enabled JavaScript is needed to run the application. The following browsers have tested during the development:

• Chrome version >= 48.0

• Firefox version >= 44.0





• Microsoft Internet Explorer11and Edge (Partially)

• Safari version >= 9

• Opera version >= 40

For the development of the GeoPAN At@s APP client side the following software, libraries and frameworks have been used:

giapi-1.2.x

VH javascript library. The application interface with the Italian VH is performed trough the web API provided to simplify interaction with the VH and to facilitate the development of applications. Docu-mentation of this library as well as usage examples and license terms can be found at http://api.eurogeoss-broker.eu/

Phonegap (Apache Cordova)

PhoneGap is a free and open source framework that allows to create mobile apps using standardized web APIs for a very wide range of mobile platforms. License information can be found at http://phonegap.com/.

jQuery

The jQuery 1.10.X library is used in order to develop the frontend (UI and application behaviour). Some jQuery plugins are added such as blockUI, numeric, and zebra datepicker in order to enhance the user experience. Further information about this library and license information, as well as javas-cript files, can be found at http://jquery.com/.

jQuery Mobile

jQuery Mobile is a HTML5-based user interface system designed to make responsive web sites and apps that are accessible on all smartphone, tablet and desktop devices.

jQuery Mobile is a touch-optimized web framework, more specifically a JavaScript library. jQuery Mo-bile is a HTML5-based user interface system that focuses to make responsive web sites and on creat-ing a framework compatible with a wide variety of smartphones and tablet computers. The jQuery Mobile framework is compatible with other mobile app frameworks and platforms such as PhoneGap.

Documentation of this library as well as usage examples and license terms can be found at https://jquerymobile.com/

OpenLayers

OpenLayers 3.x is used as support to the giapi library in order to manage layers returned from que-ries. OpenLayers 3.x is an open source JavaScript library for displaying map data in web browsers. It provides an API for building rich web-based geographic applications it is also used to manage maps allowing for user interaction (e.g., navigation, zoom, pan).

Documentation of this library as well as usage examples and license terms can be found at http://openlayers.org/

Geopan library

In order to develop this application, a specific library is developed that both handles the raw data from





the VH and the application user experience. In particular, an OpenLayer layer is wrapped as a Ge-opanLayer, which in turn is managed by the GeopanLayerManager – this allows for easy manage-ment via javascript for both the raw data and the visualization. Additional custom application behav-iour is also defined in the Geopan.js, geolocation.js and GeopanSearchManager.js files.

Technologies for the implementation of server and database components include:

Apache Tomcat

Apache Tomcat 8.x is an open-source Java Servlet Container implementing several Java EE specifi-cations including Java Servlet, JavaServer Pages (JSP), Java EL, and WebSocket, and provides an HTTP web server environment in which Java code can run. In the case of GeoPAN Atl@s solution Apache Tomcat is used as servlet to host the map server (GeoServer) and the web APP.

Geoserver

GeoServer v2.8X is an open-source server written in Java that allows users to share, process and edit geospatial data. Geoserver publishes geospatial data from any major spatial data source using open standards (mainly OGC standards). GeoServer functions as the reference implementation of the Open Geospatial Consortium Web Feature Service standard, and also implements the Web Map Ser-vice, Web Coverage Service, Web Processing Service specifications and Web Map Tile Service. Ge-oserver is used to publish POLIMI Open Datasets.

Java Runtime Environment (JRE)

JRE 8.x is a software package that contains what is required to run a Java program. It is used to run Geoserver.

8. RELATED INFORMATION - SOURCES

ENERGIC OD Consortium (2015). D6.1 Application based requirements and standards catalogue.

Websites:

http://api.eurogeoss-broker.eu/

http://geonetwork-opensource.org/

http://geoserver.org/

http://jquery.com/

https://jquerymobile.com/

http://phonegap.com

http://tomcat.apache.org/

Documents

GEOPAN ATL@S APP TECHNICAL MANUALgeoserver.atlas.polimi.it/examples/servlets/Geopan/... · GeoPAN Atl@s APP GeoPAN Atl@s APP – Technical Manual Last modification 15 November 2016