GIS Structure

This page details the restructuring of the GIS database to provide a scalable solution for the near future.

  • Note: This GSoC 2008 project is currently only available in the Trunk. This will be in a Stable release only for version 0.7.

GIS DB Overview

The following is an explanation of the main aspects of the new GIS database.

1. A Feature:

A feature is anything in the Sahana system that has a location associated with it (e.g. camps, inventories, house, aid etc). Whenever such an item is created in Sahana, it is registered in the GIS database (as well as the module specific table). Each Feature has coordinates, a map projection and Feature Class associated with it as well as a number of extra metadata values at the creators discretion.

For a module owner to register an item inside the GIS, they need only to include the file located in inc/lib_gis/ and call shn_gis_create_feature($keys_). For more information see the GIS API.

2. Feature Class

To give the Features in Sahana more meaning and to enhance searchability, the idea of features classes has been implemented. A feature class could be 'hospital', 'camp', 'Flood area', etc. Sahana users are able to create their own feature class as they see fit, assigning a name, icon and description to each (every existing module type has a feature class representing it pre-created on install of Sahana).

When a feature is created it will be registered to a “Feature Class”. This is specified in the $keys[f_class] attribute in shn_gis_create_feature($keys_). If this attribute is not included it will be registered as the “default class”.

Once a feature has an associated Feature Class it will be displayed on maps using the icon associated with that class. Feature classes can also be searched for when downloading files, creating feeds, and viewed inside the Situation Analysis module.

3. Layers

On top of Features and Feature Classes the new GIS has the concept of Layers.

A Layer is a collection or grouping of Feature Classes and/or individual Features. A user can create layers at will then add/remove a number of individual features or classes using the situation mapping or GIS admin modules (SM integration still to be completed).

Once a layer has been completed it can be viewed in the SA module or published as a feed.

  • Uses of the new functionality

The new functionality will allow Sahana users to easily drill down features in the mapping view. For example it would be easy to select only Hospital or Camp features on the map or even a combination. As each feature is now associated with a class and such an icon, hence maps will be much easier to understand. These features could also be published to an automatically updating feed so other non Sahana users could see say the status of all camps etc in an area.

Layers allows even more flexibility on the above - for example a ground team's daily objectives could be set out as a layer which could then be viewed in the SA module, published as a GeoRSS feed or even sent over SMS to the teams on site.

Using the new GIS

A relatively extensive api has been developed for accessing the new gis which can been seen in the second half of GIS API page.

Table Overview Diagram

Table Description


feature_uuid A UUID for each feature (specificity for the GIS).
metadata_uuid_ref A UUID referencing the metadata data related to this feature in the gis_feature_metadata table (specificity for the GIS).
feature_class_uuid_ref A UUID referencing the Feature Class this feature belongs to.
feature_type The Type of geomotory (point, line, polygon).
map_projection The projection type the coordinates are using.
coords The Coordinates in WKT(well known text format).

It contains an entry for each geographical feature in sahana. It main purpose is to provide a link to other tables and hold only the bare minimum data absolutely necessary for displaying the feature (coords, projection, type).

  • Coordinates are supported in the format of:

'x,y,z,wkt{wkt data}' This allows the system to support points, lines and polygons. The initial x,y,z represent the centroid point of any line or polygon and as such would be used as the items location in any search of x feature within a bounding box. The 'wkt{}' section encodes the actual points that make up such features examples a points, lines and polygon can be seen below:

  • point ⇒ x,y,z,wkt{POINT(x y z)}
  • line ⇒ x,y,z,wkt{LINESTRING(x y z,x y z)}
  • polygon ⇒ x,y,z,wkt{POLYGON((x y z,x y z,x y z) )}

to make life easier for module coders, functions to convert a simple array entry of long, lat, height into this format and back again are available in see the gis interface api for more details gisapi

The refrance link fields in this table are:
1. metadata_uuid_ref → A UID ref to the meta data associated with the features entry.
2. feature_class_uuid_ref → A UID reference to the appropriate feature class.


feature_class_uuid A UUID to reference the Feature Class.
module_ref The shorthand (as used by Sahanas front end) of the module used to create this feature.
name The name of this Feature Class.
description A description of this Feature Class.
icon A link to an icon that represents this Feature Class.
color A colour associated with an icon/area of this Feature Class (not currently used).

This table holds all the classes of feature we have in the system (e.g. hospitals, schools, buildings, unknown, etc). Each entry in the main “gis_feature” table has a UID linking itself to one of these types. This allows us to define inbuilt feature sets and also allows the user to add new feature sets as they see fit (something I stated in my project scope). Each feature has a name, description, icon and maybe other style data such as line colour associated with it. Whenever a new feature is added using one of the modules a feature type should be specified in the create feature call to gis_fns. Or to visually think of it as a icon pallet they can choose from in the GUI when placing markers down on the map. This table will also be useful for finding and sorting data e.g. 'find all hospital points' would be a simple query to this table to find all the point UIDs. As each feature class is relatively specialised for example we may have one for each type of camp (Government, NGO, Temp) This table also has the field 'Category' which i entered to be used as a sort of superclass that the feature belongs to eg camp, people, disaster areas etc)

  • Thoughts:


metadata_uuid The UUID to reference this meta data.
module_item_ref The UUID of an item in another module that this Feature is representing.
name The name of this Feature .
description The description of this Feature.
author The author of this Feature.
url A URL related to this Feature.
address The Address at which this feature is located.
event_date The date on which event this feature represents took place (if applicable).
placement_date The date this feature was placed in the database (done automatically).
extended_data Any Extra data for this feature.
url_view A url to view this feature (in a specific module)
url_edit A url to edit this feature (in a specific module)
url_del A url to delete this feature (in a specific module)

This contains all the extra optional pieces of data about each feature in the main table such as name, description, author, link etc. This table may expand over time if we decide to provide more functionality within the GIS. As the situation awareness/mapping module expands i hope that each feature will have the ability to be clicked on and this data shown in a bubble connected to the marker. At this point you may be thinking that there is a high chance that there is going to be data redundancy here as things like description and name are likely to be stored in the parent table associated with the feature (eg camp name, description). As each module has its own table convention and field names i decided it would be easier to store the data were the SM module would know where it was rather than having to write a specific call function to retrieve data from xyz table… i am open to discussion on this matter.

As each feature in the “gis_feature_metadata” table will have one associated entry in “gis_feature” table linked by an UID, (Although it would be possible to have the same data associated to many points (this may happen in the case the user only stores a small amount of ambiguous meta data to a number of points).

Note: The 2 most important fields in this table are likely to be 'module_item_ref' which is the place to store a uuid ref to any entry in another module specific table. And 'url' which should refrance to the modules page contaning its own extra data about the feature represented eg the url displaying data about a camp (index.php?mod=cr&act=ecmp&seq=view&cmp_id=)

 * Dates should be in the form of a sql timestamp eg. 2008-07-09 21:48:16
  • Thoughts:
    • maybe the module_item_ref field should be in gis_features insted.


layer_uuid The UUID to reference this Layer.
name The name of this Layer.
description A description of this Layer.

This table is specifically to help with OpenLayers. As you may or may not know Openlayers allows extra layers to be generated on top of the base layers. This table would store these layers. It will contain a uid, name, description for each new layer. The “gis_feature_to_layer” table contains UID references linking these features to their associated layer and visa versa. Users would be able to add and remove points to and from these layers at will and display them in the main GUI. This table will also be useful for find/sorting data.

  • Thoughts:

  • Notes:
    • Obviously this is just one idea open to much constructive criticism etc, hopefully we can come up with a good solution which i will look forward to coding as soon as possible (this weekend)

QR Code
QR Code dev:gis:gis_structure (generated for current page)