NAMGIS Core manual. September 21, 2008

Transcription

1 NAMGIS Core manual September 21, 2008 Contents 1 Overview Description License and copyright Requirements Getting started Credits Download instructions 3 3 Users Guide Deploying NAMGIS Core Creating a site Enabling context-awareness Developers Guide MAVEN instructions Installing the package and prepare the built environment Compile the code Generate the documentation Generate the source and binary packages Note on local MAVEN repository Overview NAMGIS Core is the context-aware mobile Web GIS component of NAMGIS. It exploits the map generation and manipulation services of MapServer (accessed through Java MapScript) to present the user with a mobile Web GIS interface, especially tailored for the small screen and limited CPU power of handheld devices. 1

2 NAMGIS Core screenshots. 1.1 Description NAMGIS Core is implemented as a Java Web application that can manage multiple GIS instances. Each instance is configured by specifying a MapServer mapfile, which defines the layers and the other map resources, and by providing the required fonts, symbols and resources (for normal and high contrast) as well as the data to be used to create the map. NAMGIS Core supports all the vector and the geo-referenced raster formats accepted by MapServer, and can read data both from files and databases. The GUI of NAMGIS Core is based on HTML and JavaScript and features small controls, collapsible panels and lightweight graphics and effects to maximize map surface and reduce CPU and bandwidth consumption; this GUI runs on every device equipped with a Web browser and it is stable, internationalized (Italian and English) and largely configurable by users. NAMGIS Core supports all the common GIS functionalities, including: map browsing (pan, zoom in/out, zoom by rectangle, predefined views, reference map); feature and attribute-based queries with highlight of results on the map; layer selection with dynamic legend; activable scalebar; indication of nominal scale. NAMGIS Core can be used as a standalone mobile Web GIS or it can combined with SAF to realize a context-aware GIS. When coupled with SAF, NAMGIS Core provides context-awareness features consisting in contrast adaptation and user s position tracking. Through contrast adaptation, the environmental light level affects the color theme of text, map and controls: normal contrast for low-to-medium sunlight; high contrast for bright sunlight (note that sunlight level is inferred by SAF as a pre-configured function of user s coordinates). User s position tracking consists in showing on the map the user location measured by the GPS receiver, while nearby POIs (point of interest) detected by the RFID reader are highlighted. For usability reasons, position tracking can be switched on/off by the user: if disabled, the system works in GIS Mode and all the GIS functionalities are available; if enabled, the system works in Navigator Mode, where the interface is periodically updated to reflect variations in the user position and, because of this, only a subset of GIS functionalities is available. To keep the update process fluid, a tracking algorithm is employed to decide whether to update the map, based on: the current map scale (greater than a given max value); the percentage variation of user position with respect to the map width (at least 10%); the accuracy of the GPS receiver (distance covered greater than the accuracy). 2

3 1.2 License and copyright NAMGIS Core is released under the GPLv3 license. NAMGIS Core is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 1.3 Requirements To use the software you need a JDK 1.5 or newer installed on your machine. In in order to compile the package you need MAVEN: follow the instructions at for detailed instructions to download and configure MAVEN on your machine. In order to execute NAMGIS Core you need a compliant Java servlet container, such as Apache Tomcat; please refer to the documentation of the servlet container for instructions on how to deploy NAMGIS Core. Finally, note that the binary package of NAMGIS includes and is based on the Windows version of MapScript, thus it can be used only on Windows machines. 1.4 Getting started Please refer to the user guide for information regarding the use of NAMGIS Core. If you want to compile the code or extend the application, please refer to the developer guide. 1.5 Credits The development of NAMGIS Core has been partially supported by the ArcheoMedSat research project, funded by Italian Ministry of University and Research (MIUR project, FIRB-2003) and aiming at using geomatics in archaeology to support scientific researches and excavations and to improve recreational and tourist activities; NAMGIS Core has been designed and developed by Diego Magni as part of his PhD thesis. 2 Download instructions NAMGIS Core can be downloaded together with other NAMGIS components from the Web site of Laboratorio of Geomatica at Politecnico di Milano: NAMGIS Core is distributed in two forms: a source package, intended for developers wishing to modify or compile the code. a binary package, containing the NAMGIS Core Web application packaged as a WAR and ready to be deployed to a servlet container. The source package includes also a local MAVEN repository (/mvnrepo) containing JAR files for the Java version of UMN Mapscript; as the time this package was built, binaries of this libraries are not available online, neither as standalone JAR files nor as JAR files deployed on a public MAVEN repository. 3 Users Guide NAMGIS Core is a Web application which is able to manage one or more GIS instances, each one called a site. The following sections describe how to deploy NAMGIS Core to a compliant servlet compare (we will refer to tomcat), how to create a site and how to enable context-awareness functionalities. Please note that 3

4 all the following instructions apply to the Windows platform (we do not support other operating systems at the moment). 3.1 Deploying NAMGIS Core Deployment instructions largely depends on the used servlet container. In the following, we will refer to Apache Tomcat and we will assume that a working instance of Tomcat was already installed. Using Tomcat, the first step is deploy the application WAR files located in the binary package under the Tomcat /webapps folder. There are two options: the contents of the WAR file are extracted in a subfolder of /webapps, e.g. /webapps/namgis. the WAR file is copied as is under the /webapps folder; in this case Tomcat need to be configured to automatically explode deployed WAR files, so it will autotomatically create a namgis-core-1.0 folder with the content of the deployed WAR. Please note that if you use another servlet container, then you may have to follow a different deploy procedure. Independently on how the Web application has been deployed, a required final step is to add the full path to the /mapserver folder to the PATH system variable. This is required in order to allow Java to access the included Mapscript DLLs. You can edit the PATH variable by using Control panel System Advanced Environment Variables. 3.2 Creating a site Sites in NAMGIS Core are located under the /sites folder, each one having its subfolder. A site defines a GIS instance: it defines the layers and the other map resources, and it provides the required fonts, symbols and resources (for normal and high contrast) as well as the data to be used to create the map. In order to define a new site, you have to execute the following steps: Create a subfolder under /sites using an identifying name for the new site. Create the site structure. A site is organized as depicted in the following figure. You should recreate this structure and put in place all the required files. A site template is included in the binary distribution: you have to start from this template because it includes some files that must be included in the site structure. Following is the list of all the files that you need to define (please look at the site template provided for an example of a working site): 4

5 First of all, you need to define a file map/generator.map using the MapServer syntax and defining all the layers that compose your GIS instance (please leave in place the file map/namgis.map already existing in the template). Then you have to write the two files map/symbols.sym and map/hcsymbols.sym: these files contains associations from symbolic names used in the generator file to icons placed, respectively, under the graphics/images-nc and graphics/images-hc folders. Remember to put all the images referenced in map/symbols.sym and map/hcsymbols.sym in their respective folders (note: having symbols is not mandatory). Write a file map/fontset.txt with all the mappings from font names used in map/generator.map to font files to be placed under graphics/fonts (note: having fonts is not mandatory). You can customize the use of the proj library. In this case, write your proj configuration file under /proj and reference the desired settings using metadatum namgis epsgcode inside map/generator.map (e.g. namgis epsgcode 4326 ). Place raster files used for the reference map under map/refmap folder. Using map/generator.map you can also configure NAMGIS to use vector data stored in a PostGIS database. Place data files under folder data; you can define sub-folders and include both raster and vector files. Edit the web.xml file adding a new servlet instance for the new site. Add the following lines near other servlet blocks: <servlet> <servlet-name>namgis</servlet-name> <servlet-class> it.polimi.como.geomatica.namgis.namgis </servlet-class> <param-name>site-folder</param-name> <param-value>site_folder</param-value> <param-name>site-title</param-name> <param-value>site_title</param-value> </servlet> Change SITE FOLDER and SITE TITLE respectively with the name of the folder created for the new site and with a descriptive string to be used as a part of the window title when the site is accessed using a browser. Then add the following lines: <servlet-mapping> <servlet-name>namgis</servlet-name> <url-pattern>path</url-pattern> </servlet-mapping> Choose a path and replace the placeholder PATH in the snippet above (e.g. if path /mygis is used, then the application will be reachable by browsers at the url context/mygis, where the first part until mygis depends on the way NAMGIS Core has been deployed on the servlet container). 3.3 Enabling context-awareness By default the version of NAMGIS Core shipped with this package is not integrated with SAF and runs standalone. If you wish to enable this integration, that is if you want NAMGIS Core to acquire coordinates and 5

6 context updates from SAF, all you have to do is uncomment a block of XML in file /WEB-INF/web.xml, possibly changing the URL used to connect with the context server. <web-app>... <!-- Uncomment the following lines to enable the integration with SAF. --> <!-- <filter> <filter-name>contextfilter</filter-name> <filter-class> it.cefriel.context.ext.contextfilter </filter-class> <param-name>cookiename</param-name> <param-value>contextuser</param-value> <param-name>redirecturi</param-name> <param-value>/namgis/select-context-user</param-value> <param-name>contexturl</param-name> <param-value>rmi://localhost:1099/context-service</param-value> <param-name>usersessionattributename</param-name> <param-value>user</param-value> <param-name>useragentsessionattributename</param-name> <param-value>useragent</param-value> </filter> <filter> <filter-name>coordfilter</filter-name> <filter-class> it.cefriel.context.ext.coordfilter </filter-class> </filter> <filter-mapping> <filter-name>contextfilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>coordfilter</filter-name> <url-pattern>/view</url-pattern> </filter-mapping> -->... </webapp> 6

7 4 Developers Guide Developers wishing to work with NAMGIS Core source code should download the source package of the component. NAMGIS Core is developed using MAVEN. You need a basic understanding of MAVEN in order to compile the code and generate the documentation. 4.1 MAVEN instructions In the following we gave a brief overview of the main commands to work with the source package. All the instructions refer to Windows. NAMGIS Core has been developed on the Windows platform and it is based on the Windows compiled DLLs of MapScript. While it should be possible to develop and compile the code for Linux, this will require to switch to the Linux version of MapScript libraries Installing the package and prepare the built environment Unzip the package where you prefer on your file system. Open a command prompt and enter the following command: mvn -v This should display the version of MAVEN currently installed. Please check have at least MAVEN 2.0.8, otherwise please update your installation. It would be also helpful to allocate more memory to MAVEN for its execution: to this end, define the following environment variable (go under control panel system): MAVEN_OPTS = -Xms128m -Xmx256m Now you should be ready to compile the code Compile the code From the command line, move to the root directory of the source package and execute the following command: mvn package This tells MAVEN to compile the code and generate the resulting war. If everything works you should see a BUILD SUCCESSFUL message at the end Generate the documentation Launch the following two commands from the prompt: mvn site mvn site:deploy The first generates the HTML documentation from the APT sources (a MAVEN format, used to write these pages) and generates also all the configured MAVEN reports (including Javadocs). The second deploys the generated documentation under the /docs folder under the package (you can change the pom.xml to deploy to a different location / Web site). In order to generate the PDF manual, the Doxia MAVEN plugin has been configured to translate part of the documentation into Latex. You need to create the site, then manually enter folder /target/doxia/latex/manual and edit manual.tex: change the document type from book to article; * remove also the /chapter instruction from the body; * change the definition of the \includegraphics command to; \newcommand{\pfiguregraphics}[1]{\includegraphics[scale 7

8 * instead of graphics import graphicx ; * compile the document using Latex (latex = ps = pdf) Generate the source and binary packages From the command prompt, execute the following: mvn assembly:assembly MAVEN will generate two zip files for the source and the binary packages, under the /target folder. These files are exactly the packages published on the web site. Please update the assembly.xml descriptors under /src/main/assemblies subfolders if you wish to customize the generated packages. 4.2 Note on local MAVEN repository This package includes a local MAVEN repository (/mvnrepo) containing JAR files for the Java version of UMN MapScript; as the time this package was built, binaries of this libraries are not available online, neither as standalone JAR files nor as JAR files deployed on a public MAVEN repository. 8