This is an old revision of the document!


Sahana GIS for Sahana Module Developers

The Sahana GIS API can be used by Sahana Module Developers to add spatial functionality to their relevant modules. Module Developers can make use of the existing API calls in the gis_fns.inc file under the GIS module.

For more info, refer: GIS Architecture

Currently, the API has the following functions:

  • shn_gis_gps_from_rest
    • Creates GIS coordinates for entities via REST url
  • shn_gis_map
    • Show Generic Map
  • shn_gis_dbinsert
    • Insert GIS information into database
  • shn_gis_add_marker_map
    • Show Map with marker addition event when clicked
  • shn_gis_add_marker_map_form
    • Show above map with form elements
  • shn_gis_map_with_markers
    • Show map with markers and information as specified in array
  • shn_gis_map_with_wiki_markers
    • Show Map with Wiki Markers
  • shn_gis_map_with_wiki_markers_select
    • Show Map with Wiki Markers & update Lat/Lon form fields based on Marker selected
  • shn_gis_density_map
    • Show reporting map with custom markers
  • shn_gis_features_in_radius
    • List Features within a Radius of a location
  • shn_gis_bearing
    • Provide a Bearing when given a starting & ending set of LatLon coordinates

These functions can be called by including the gis_fns.inc file.

Example 1: Add Map with event listener
//call the GIS api file
include $global['approot']."/inc/lib_gis/gis_fns.inc";
 
//add form elements if needed, with actions
shn_form_fopen(awik,null,array('req'=>false));
//optionally, add additional form details, sequence information
shn_form_hidden(array('seq'=>'img'));
//call appropriate gis api method
shn_gis_add_marker_map_form();
shn_form_submit(_("Next"));
Example 2: Store GIS markers from previous form

A single marker's coordinates are stored in POST variables by the names of loc_x, loc_y.

The following code can be used to store the coordinates to the GIS Table.

include $global['approot']."/inc/lib_gis/gis_fns.inc";
shn_gis_dbinsert($u_id,0,null,$_POST['loc_x'],$_POST['loc_y'],null);

Where, $u_id is the uuid of your entity.

GSoC Interfaces (Under Developement)

The Following is implemented in /inc/lib_gis/gis_fns.inc (More information on each function can be seen there).

GIS key values

Key values to use when passing associative key arrays in 'shn_gis_create_*' and 'shn_gis_get_*' functions for features.

KEY TYPE EXAMPLE VALUE DESCRIPTION
== Required for create
'f_type' ⇒ [str] point [Feature type use one of ('point', 'line' 'poly')]
'f_coords' ⇒ [str] x,y,z,wkt{POINT(x y z)} [Coordinates center point then coords in wkt(x y z) format ]
== Optional for create
'f_uuid' ⇒ [str] ql5yg-1 [uuif of feature !!! IMPORTANT IT IS RECOMENDED THIS KEY IS NOT USED IN create fns !!!]
'f_class' ⇒ [str] ql5yg-2 [uuid of feature class]
'f_projection' ⇒ [str] EPSG:900913 [Mapping projection default EPSG:900913 ]
'f_module_item' ⇒ [str] ql5yg-2 [Associated module item reference uuid. USE THIS FOR REFERENCING YOUR MODULE SPECIFIC UUID]
'f_name' ⇒ [str] Toms house [Name of feature]
'f_description' ⇒ [str] Big blue house, blk door [Description of feature(can be html)]
'f_author' ⇒ [str] Tom [Name of author]
'f_url' ⇒ [str] http://www.thouse.com [url related to node]
'f_address' ⇒ [str] 10 big hill [Address at which node resides]
'f_event_date' ⇒ [str] 2008-06-15 15:05:20 [Date of event which marker represents]
'f_extended_data' ⇒ [str] blaa blaa' [Any extended data associated with point (sahana specific)]

Code for key values

      $keys_ = array(  
        'f_uuid'          => '',
        'f_class'         => '',
        'f_type'          => '',
        'f_projection'    => '',
        'f_coords'        => '',  
        'f_module_item'   => '',
        'f_name'          => '',
        'f_description'   => '',
        'f_author'        => '',
        'f_url'           => '',
        'f_address'       => '',
        'f_event_date'    => '',
        'f_extended_data' => ''
      );

Database interfaces

Feature Related

  • shn_gis_create_feature($keys_)
    • Creates GIS feature from array of associative keys see above.
  • shn_gis_remove_feature($feature_uuid_)
    • Removes a feature, associated metadata data and feature_to_layer refs.
  • shn_gis_remove_feature_module_item($f_module_item_) External modules will use this function Especially
    • Removes a feature, associated metadata data and feature_to_layer refs useing external module item uuid.
  • shn_gis_modify_feature($uuid_, $keys_)
    • Modifys a GIS feature from array of associative keys see above.
  • shn_gis_modify_feature_module_item($f_module_item_, $keys_) External modules will use this function Especially
    • Modifys a GIS feature from array of associative keys see above (uses f_module_item_ as uuid to search for entry).

Feature Gets

  • shn_gis_get_features_uuid($uuid_, $keys_)
    • returns features corresponding to the features uuid
  • shn_gis_get_features_item_ref($item_uuid_, $keys_) External modules will use this function Especially
    • returns a multidimensional array containing all fields specified by keys of all features with a f_module_item refrerence uuid = $item_uuid.
  • shn_gis_get_features_all($keys_)
    • returns a multidimensional array containing all fields specified by keys of all features.
  • shn_gis_get_features_feature_class($class_uuid_, $keys_)
    • returns a multidimensional array containing all fields specified by keys of all features in class specified by $class_uuid_.
  • shn_gis_get_features_layer($layer_uuid_, $keys_)
    • returns a multidimensional array containing all fields specified by keys of all features in layer specified by $layer_uuid_.
  • shn_gis_get_features_other($keys_, $layer_, $class_, $author_name_, $date_from_, $date_to_, $feature_name_)
    • returns a multidimensional array containing all fields specified by keys of all features using other atts as search values.

To ignore any of the attributes in the search enter $att = ''

Feature Class Related

  • shn_gis_create_feature_class($module_ref_, $category_, $name_, $description_, $icon_, $color_)
    • Creates a new feature_class.
  • shn_gis_remove_feature_class($feature_class_uuid_, $options_)
    • opt 1 - Fail if features exist with this feature class otherwise remove.
    • opt 2 - Remove feature class and set existing features with feature_class_uuid to default class.
    • opt 3 - Remove existing feature with this class then remove class.
    • default - use opt 1
  • shn_gis_modify_feature_class($uuid_, $keys_)
    • Modifys a Feature Class, Enter new values as key value.
  • shn_gis_get_feature_class_all()
    • Returns all feature classes in the system.
  • shn_gis_get_feature_class_uuid($feature_class_uuid_)
    • returns data about a feature class (see code for more details)

Layer Related

  • shn_gis_create_layer($name_, $description_)
    • Creates a new layer
  • shn_gis_remove_layer($layer_uuid_, $options_)
    • opt 1 - Fail if features exist within this layer otherwise remove.
    • opt 2 - Remove layer and references only.
    • opt 3 - Remove layer, layer references and all features that are in this layer.
    • default - use opt 1
  • shn_gis_insert_layer_features($layer_uuid_, $features_uuid_)
    • Add tie between a number of features and a layer.
  • shn_gis_remove_layer_features($layer_uuid_, $features_uuid_)
    • Removes tie between a number of features and a layer.
    • given 2 dim array of coords encodes string (see doc in code for more details).
  • shn_gis_insert_layer_feature_class($layer_uuid_, $feature_classes_uuid_)
    • Add tie between a number of feature_classes and a layer.
  • function shn_gis_remove_layer_feature_class($layer_uuid_, $feature_classes_uuid_)
    • Removes tie between a number of feature classes and a layer
  • shn_gis_get_layers_all()
    • Returns all layers as an array of arrays such:

array(array(l_uuid' ⇒ 'a uuid', 'l_name' ⇒ 'a name', 'l_description' ⇒ 'a desc'),array(l_uuid' ⇒ 'a uuid', 'l_name' ⇒ 'a name', 'l_description' ⇒ 'a desc'))

  • shn_gis_get_layers_uuid($layer_uuid_)
    • Returns a specific layer using the layers uuid a search value.
  • shn_gis_get_layers_feature_class($feature_class_uuid_)
    • Returns layers that a feature class is registered to.
  • shn_gis_get_feature_classes_layer($layer_uuid_, $options)
    • opt 1 - Returns all class uuids registered to layer
    • opt 2 - Returns all classes uuids registered to layer as well as classes of features in that layer.

Extras

  • shn_gis_coord_decode($coords)
    • given a coord string decodes values into 2 dim array (see doc in code for more details).
  • shn_gis_coord_encode($coords, $type)
    • given 2 dim array of coords encodes string (see doc in code for more details).



Navigation
  • Navigate