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)]
'f_url_view' ⇒ [str] [A Link to view a feature/item in the owners module]
'f_url_edit' ⇒ [str] [A Link to edit a feature/item in the owners module]
'f_url_delete' ⇒ [str] [A Link to delete a feature/item in the owners module]

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' => '',
   'f_url_view'      => '',
   'f_url_edit'      => '',
   'f_url_delete'    => ''
);

Alternately when asking for keys you can just use

$keys_ = array('all' => '1');

To retrieve all the fields eg:

$keys_ = array('all' => '1');
shn_gis_get_features_uuid('somefeatureuuid', $keys_)

Database interfaces

Feature Related

Creating a Feature

...
shn_gis_create_feature($keys_)
...

Creates GIS feature from array of associative keys see above.

Removing a Feature

...
shn_gis_remove_feature($feature_uuid_)
...

Removes a feature, associated metadata data and feature_to_layer refs.

Removing a Feature using an external module item as a refrence [External modules are especially likely to use this function]

...
shn_gis_remove_feature_module_item($f_module_item_) 
...

Removes a feature, associated metadata data and feature_to_layer refs useing external module item uuid.

Modifying A Feature

...
shn_gis_modify_feature($uuid_, $keys_) 
...

Modifys a GIS feature from array of associative keys see above.

Modifying A Feature using an external module item as a refrence [External modules are especially likely to use this function]

...
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

By Feature UUID

...
shn_gis_get_features_uuid($uuid_, $keys_)
...

returns features corresponding to the features uuid

By External Module Item UUID [External modules are especially likely to use this function]

...
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.

Get All Features

...
shn_gis_get_features_all($keys_)
...

returns a multidimensional array containing all fields specified by keys of all features.

Get Features Belonging To A Particular Feature Class

...
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_.

Get Features Belonging To A Particular Layer

...
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_.

Specific Search useng a number of values

...
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

Create a New Feature Class

...
shn_gis_create_feature_class($module_ref_, $category_, $name_, $description_, $icon_, $color_)
...

Creates a new feature_class.

NOTE: This function will be recoded in the near future to take a key entry of values such :

...
$keys = array(
             'c_module_ref' => 'mod item uuid',
             'c_name' => 'a name',
             'c_description' => 'a desc',
             'c_icon' => 'a hard link to an icon',
             'c_color' => 'the color of line/poly',
        ); 

shn_gis_create_feature_class($keys)
...


Remove a 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

If you are building this into a module be carfull not to remove any feature classes that are registored to another module (they will have $module_ref_ set).

Modify A Feature Class

...
shn_gis_modify_feature_class($uuid_, $keys_)
...

Modifys a Feature Class, Enter new values as key value.

Return All The Feature Classes

...
shn_gis_get_feature_class_all()
...

Returns all feature classes in the system.

Return A Feature Class by its UUID

...
shn_gis_get_feature_class_uuid($feature_class_uuid_)
...

Returns data about a feature class (see code for more details).

Layer Related

Create A New Layer

...
shn_gis_create_layer($name_, $description_)
...

Creates a new layer

NOTE: This function will be recoded in the near future to take a key entry of values such :

...
$keys = array(
             'l_name' => 'a name',
             'l_description' => 'a desc'
        ); 

shn_gis_create_layer($keys)
...


Remove A 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


Add Features To A Layer

...
shn_gis_insert_layer_features($layer_uuid_, $features_uuid_)
...

Add tie between a number of features and a layer.

Remove Features From A Layer

...
shn_gis_remove_layer_features($layer_uuid_, $features_uuid_)
...

Removes tie between a number of features and a layer.

Add A Feature Class To A Layer

...
shn_gis_insert_layer_feature_class($layer_uuid_, $feature_classes_uuid_)
...

Add tie between a number of feature_classes and a layer.

Remove A Feature Class From A Layer

...
shn_gis_remove_layer_feature_class($layer_uuid_, $feature_classes_uuid_)
...

Removes tie between a number of feature classes and a layer

Get All Layers

...
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'
      )
)


Get A Layer By Its UUID

...
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.

Return All Feature Classes In A Layer

...
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

Decode A Coordinate String To Array

...
shn_gis_coord_decode($coords)
...

given a coord string decodes values into 2 dim array (see doc in code for more details).

Encode A Coordinate Array To String

...
shn_gis_coord_encode($coords, $type)
...

given 2 dim array of coords encodes string (see doc in code for more details).


Navigation
  • Navigate