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)

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]
'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_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_)
    • 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_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_item_ref($item_uuid_, $keys_)
    • returns a multidimensional array containing all fields specified by keys of all features with a f_module_item refrerence uuid = $item_uuid.

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

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 features and a layer.
  • shn_gis_remove_layer_features($layer_uuid_, $features_uuid_)
    • Removes tie between a number of features and a 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