ka-Map Workshop

Paul Spencer

DM Solutions Group

Lorenzo Becchi

Ominiverdi.org

Presentation Overview

  • Project Overview
  • Introduction
    • Installation and Configuration
    • Map File Configuration
    • Exploring ka-Explorer
  • Using the API in Your Own Interface
  • Mashups with ka-Map
  • ka-Map extras
    • Adding Objects
    • Tooltips
    • XML Overlay
    • WFS points
    • ka-Routing
    • GRASS integration (Embrio)
  • Q & A

Project Overview

Project Overview

  • ka-Map is ...
    • a javascript API for rendering fast, tiled maps
    • a set of tools for navigating and basic application needs
    • a dynamically generated tile caching server
  • Its good for ...
    • Static base map data with dynamic point overlays
    • fixed set of scales
    • large maps (full screen)
    • dynamically resizeable maps
  • Its not good for ...
    • dynamically changing base data
    • Many separately controllable layers

Supported Browsers

Browser Windows Linux Mac OS X
Internet Explorer yes (6, 7) - -
Mozilla/Firefox yes (1.0+) yes (1.0+) yes (1.0+)
Netscape yes (7+) yes (7+) yes (7+)
Epiphany - yes -
Opera yes (7+) yes (7+) yes (7+)
Konqueror - no -
Safari ? - yes

Project Overview

  • DM Solutions Group
    • javascript API for a tiled client
    • PHP/MapScript implementation of a tile caching system
    • basic tools for navigation
  • Ominiverdi
    • kaExplorer interface (among others)
    • core improvements and bug fixes
    • new tools (search, query, ...)
    • LiveCD
  • Other contributions ...
    • Scalebar and bug fixes (Tim Schaub)
    • XML Overlays (Pg)
    • Graphics (Alexandra Herzog)
    • Testing, support (many)

Installation and Configuration

  • Prerequisites
    • web server with PHP support
    • functional MapServer installation with PHP/MapScript
  • Basic Installation
    • extract archive
    • configure web server to access htdocs directory
  • MS4W installation is simple!

Main Configuration

/var/www/localhost/htdocs/ka-map/include/config.php
  • edit include/config.php
  • set name of mapscript module
  • set name of GD module
  • modify default tile settings (if desired)
  • set cache directory location

Adding Maps

  • duplicate /home/kamap/mapfile/gmap75-2.map
  • create new array to describe the map
    $aszGMap2 = array ( 'title' => 'GMap 75 Modified', 'path' => '/home/kamap/mapfile/gmap75-2.map', 'scales' => array( 40000000, 25000000, 12000000, 7500000, 3000000 ), 'format' =>'PNG' );
  • add it to the global array of maps
    $aszMapFiles = array( 'gmap75-2' => $aszGMap2, ... );

Troubleshooting

  • ka-Map normally fails if ...
    • syntax error in config.php
    • invalid path to map file in config.php
    • invalid map file syntax
  • Loading init.php directly usually reveals the problem in the PHP error log

Troubleshooting

  • browser versions ...
  • check web server configuration
  • test your map file (shp2img)
  • check cache directory to see if images are created (permissions?)

Map File Configuration

  • ka-Map-specific options
    • how GROUPs are used
    • MAP level metadata
    • LAYER level metadata

Map File GROUPs

  • GROUPS create separately controllable 'layers' in the client
  • all layers in a GROUP are rendered into a single set of tiles
  • LAYERs without a GROUP are in the Base GROUP automatically
  • LAYER ordering can be changed by by using GROUPs
  • more GROUPs = less performance & bigger cache

Edit gmap75 GROUPs

  • open /home/kamap/mapfile/gmap75.map
  • change SHAPEPATH to ../data/gmap/data/
  • add GROUP "Parks" to the park layer
    • refresh ka-Map, toggle new Park layer on/off
    • notice parks are still 'burned' into the Base layer
    • delete contents of kacache and try again
      • open terminal, cd /home/kamap/cache/
      • rm -rf gmap75
  • add GROUP "Transportation" to road and rail layer
    • clear cache
    • refresh ka-Map

MAP level Metadata

  • "max_extents" ["minx, miny, maxx, maxy" | "auto"]
    • add 
      METADATA 
    "max_extents" "auto"
END
      to WEB gmap75.map
    • refresh kaMap and try panning the map
  • "version" "any string"
    • remove GROUP "Transportation" from rail and road layers
    • refresh ka-Map ... no roads or rail in base
    • add "version" "1" to WEB METADATA in gmap75.map
    • refresh ka-Map

LAYER level Metadata

  • "opacity" [integer]
  • "imageformat" "[DITHERED|PNG24|PNG|JPEG|GIF]"
  • "queryable" ["true" | "false"]
  • "searchfield" "layer_field_name"
  • "fields" "fieldname1:alias1,fieldname2:alias2,fiendname3:alias3"
  • "tile_source" ["auto" | "cache" | "redraw" | "nocache"]
  • "redraw_interval" "n"
  • "refresh_interval" "n"

LAYER level Metadata experiments

  • add "opacity" "50" to the parks layer and refresh ka-Map
  • Point queries ...
    • add "queryable" "true" to the parks layer and refresh ka-Map, then query a park
    • add "fields" "NAME_E:Name,AREA:Area" to parks layer and query again
  • Searches ...
    • add "searchfield" "NAME_E" to parks layer
    • Click the search tool (binoculars) and type in "wood" and click search

"tile_source" ["auto" | "cache" | "redraw" | "nocache"]

auto (default if not set)
let tile.php decide whether or not to render a new tile
cache
If you have pre-rendered all your tiles, you can specify "cache" to have tiles requested from the cache directly - this requires that you also specify a web accessible path to your cache in config.php
redraw
Causes tiles to be re-requested by the client based on redraw_interval. Currency of data is affected by refresh_interval

"tile_source" ["auto" | "cache" | "redraw" | "nocache"]

nocache
The "nocache" option has two effects: it redraws tiles without using the cache and without creating larger metatiles, and it uses MapServer CGI style replacement variables. To specify values for variable replacement on the client side, add a replacementVariables object to your JavaScript _layer object (e.g. myLayer.replacementVariables = {key1: 'value1', key2: 'value2'}). Variable replacement currently works for layer->data, layer->connection, layer->filter, and for class->expression.

"refresh_interval" and "redraw_interval"

redraw_interval
the interval, in seconds, at which the data in the cache is considered to be stale. When the ka-Map client requests tiles and the tile source is set to redraw, it will pass the current timestamp for the entire layer/group and the redraw interval.
refresh_interval
the interval at which the layer/group should be automatically refreshed by the client. If not specified or <=0, the layer/group will not be automatically refreshed. This is most effective when combined with tile_source "redraw" or tile_source "nocache" for periodically changing data.

Exploring ka-Explorer

  • An advanced pre-cooked interface to use ka-Map API out of the box.
  • features:
    • Windows application look and feel
    • Integrated tools for Query, Search, Print and Permalink
    • Basic customization just editing a CSS file:
      ka-map/htdocs/tools/kaExplorer/screen.css
    • Developed for a FAO project
  • live example:

Using the API

  • embed your map in any web page
  • can be very simple or very complex

Getting Started ...

  • you can make your own web page or use this one ...

Add scripts ...

  • Add the following script tags to your page: 
    <script type="text/javascript" 
    src="/ka-map/htdocs/xhr.js">
</script>
<script type="text/javascript" 
    src="/ka-map/htdocs/kaMap.js">
</script>
<script type="text/javascript" 
   src="/ka-map/htdocs/kaTool.js">
</script>

Add a map to the page

  • Place a div somewhere in the page: 
    <div id="mapDiv"></div>
  • The id is used to tell kaMap where to put the map

Mandatory and optional styles for the map

<style type="text/css">
#mapDiv {
    position: relative; //or absolute
    height: 200px;
    background-color:  white;
    border: 1px solid black;
}
</style>

Initialize the map

<script type="text/javascript">
var myKaMap;

window.onload=function() {
    myKaMap = new kaMap('mapDiv');
    myKaMap.server = 'http://localhost/ka-map/htdocs/';
    myKaMap.initialize();
}
</script>

Try it out

Add navigation controls ...

<script type="text/javascript">
var myKaMap;
var myNav;

window.onload=function() {
    myKaMap = new kaMap('mapDiv');
    myKaMap.server = 'http://localhost/ka-map/htdocs/';
    myKaMap.initialize();

    myNav = new kaNavigator(myKaMap);
    myNav.activate();
}
</script>

Try it out

Adding a Point

  • Add a point to the map when the user clicks a link
  • add a link to your page: 
    show DMSG Office

Add a canvas to draw the point on

<script type="text/javascript">
var myKaMap;
var myNav;
var myCanvas;

window.onload=function() {
    myKaMap = new kaMap('mapDiv');
    myKaMap.server = 'http://www.ominiverdi.org/ka-map/ka-map/htdocs/';
    myKaMap.initialize();
    
    myNav = new kaNavigator(myKaMap);
    myNav.activate();
    myCanvas = myKaMap.createDrawingCanvas(1000);
}
</script>

Add zoomToDMSG function

function zoomToDMSG() {
    var lon = -75.726061;//1509106.04; 
    var lat = 45.401306;//-172671.12;

    var img = document.createElement('img');
    img.src = 'http://www.ominiverdi.org/ka-map/ka-map/htdocs/images/kamap.gif';
    img.width = 36;
    img.height = 42;

    myKaMap.addObjectGeo(myCanvas, lon, lat, img);
    myKaMap.zoomTo(lon, lat, 10000000);
}

Try it out

Mashups with ka-Map

Extras

  • Adding Objects
  • Tooltips
  • XML Overlay
  • WFS points
  • ka-Routing
  • GRASS integration (Embrio)

Adding Objects 1/2

An Object can be whatever HTML element we want to add to the map, ex: image, textbox, ecc.

  • Sample application (needs a World Map)
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/object_add_example.html
  • Code sample
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/object_add_code.html

Adding Objects 2/2

  • create the object array (line 54): 
    
//my points array
var aPoints = new Array();
...
  • create your function to populate the map (line 66)
    createDrawingCanvas(idx) and addObjectGeo(canvas,lat,lon,div) 
    
	function printMyTips () {
		...
	}
  • Add action when objects are clicked (line 91) 
    
function myTipClicked(){
	...
}

Tooltips 1/2

The tooltip is a common graphical user interface element. The user hovers the cursor over an item and a small box appears with supplementary information regarding the item being hovered over (extract from Wikipedia)

  • Sample appication (needs a World Map)
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/tooltip_example.html
  • Code Sample
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/tooltip_code.html

Tooltips 2/2

  • Include tooltip code in HTML header (line 14) 
    
<script type="text/javascript" src="tools/kaToolTip.js"></script>
  • add the function to draw tips (line 73) 
    
	function printMyTips ()
  • show infos when Tip is cliced (line 110) 
    
	function myTipClicked ()

XML Overlays

  • written by Piergiorgio Navone (PG)
  • What's good
    • Client side vectorial drawing (cross Browser, FFOX and IE)
    • Point, Line, Polygon drawing supported
    • almost independant API
    • objects can be added by JS script or XML file
  • What's not good
    • poor Browser support to vectorial drawings
    • Heavy traffic on big drawings

XML Overlays drawing points

  • Sample application (needs a World Map)
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_point_example.html
  • Code sample
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_point_code.html

XML Overlays drawing lines

  • Sample application (needs a World Map)
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_line_example.html
  • Code sample
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_line_code.html

XML Overlays drawing polygons

  • Sample application (needs a World Map)
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_polygon_example.html
  • Code sample
    • LiveCD path: 
      
		/var/www/localhost/htdocs/ka-map/presentations/foss4g2007/xml_overlay_polygon_code.html

WFS POINTS 1/2

  • Sample application (external link)
  • How does this work?
    • Server List -> you can add your own servers
    • Feature -> step by step choosing the feature your are looking for
    • EPSG -> has your map a default projection?
    • Messages -> helping process

WFS POINTS 2/2

  • What's good
    • projection conversion on the fly (server side)
    • server side filtering GML (less code to parse on the client and move on the net)
  • What's not good
    • PHP5 needed (DOM)
    • no WFS LINES and POLYGONS support (could be implemented with XMLOverlay)

ka-Routing

GRASS integration: PyWPS

GRASS integration: Embrio

Embrio is web interface to access GRASS commands. It uses php/mapscript to manage maps, data and WPS connections.

Q & A

  • Any question?

Creative Commons License

Creative Commons Deed

Attribution-NonCommercial-ShareAlike 2.5

You are free:

  • to copy, distribute, display, and perform the work
  • to make derivative works

Under the following conditions:

by
Attribution. You must attribute the work in the manner specified by the author or licensor.
nc
Noncommercial. You may not use this work for commercial purposes.
sa
Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under a license identical to this one.
  • For any reuse or distribution, you must make clear to others the license terms of this work.
  • Any of these conditions can be waived if you get permission from the copyright holder.

Your fair use and other rights are in no way affected by the above.

This is a human-readable summary of the Legal Code (the full license).

 

Learn how to distribute your work using this license