=== added file 'docs/dhis2_gis_user_manual_en.htm' --- docs/dhis2_gis_user_manual_en.htm 1970-01-01 00:00:00 +0000 +++ docs/dhis2_gis_user_manual_en.htm 2009-09-12 09:27:37 +0000 @@ -0,0 +1,135 @@ +DHIS 2 GIS User Manual
+

DHIS 2 GIS User Manual

Jan Henrik Řverland

Pickering

Revision History
Revision 112/09/2009JPP

Initial conversion of document to DocBook format

+ +

Table of Contents

Conversion of geographical data to GeoJSON format
Production of GeoJSON files with Geoserver
Production of GeoJSON files with GDAL
Copying files to the DHIS application
Administrator panel
Registering geographical information
Assign organization units to map
Register overlays
Thematic map
Register views
Register legend sets
+

Conversion of geographical data to GeoJSON format

+ +

The DHIS2 mapping client relies on GeoJSON files in order to display + a map in the browser window. Often times, geographical data is received in + many different formats, but the ESRI shape file format is one of the most + common. Several procedures will be described below. It is important, but + not required, that the names in your geographical data match those in the + DHIS2 organizational hierarchy. If they do not, you will need to manually + match them in a later step

+

Production of GeoJSON files with Geoserver

+ +

Geoserver is capable of outputting GeoJSON formats. If you have + geoserver running someplace, you can execute the following query.

http://localhost:8080/geoserver/wfs?request=GetFeature&typename=who:zm_adm1&outputformat=json

You will need to adjust the host destination if the machine is not + your local machine as well as defining the actual layer in Geoserver + which should be output to GeoJSON (in this case + who:zm_adm1).

Upon execution of the URL, Geoserver will produce a GeoJSON file, + and you will be asked to save it. Once it has finished downloading, + rename the file following the suggested naming convention:

ISO2CountryCode followed by an underscore, followed by the layer + type (e.g. “admin” for administrative layers, “health” for health + administrative boundaries). For instance, the first administrative layer + for Zambia would be named as "zm_admin1".

+

Production of GeoJSON files with GDAL

+ +

GDAL is a multi-platform toolkit for the manipulation of + geographical data. It is freely available for a wide-range of platforms + at http://gdal.org

Production of GeoJSON files are straightforward with GDAL. Just + execute (on Windows)

ogr2ogr.exe -f "GeoJSON" dst_datasource_name src_datasource_name

or on Linux

ogr2ogr -f "GeoJSON"dst_datasource_name src_datasource_name

Replace dst_datasource_name with the path + to the destination geographical data file (following the naming + convention described above) and + src_datasource_name with the source geographical + data file.

+

Copying files to the DHIS application

+ +

Currently, your GeoJSON files should be placed in the + DHIS_HOME/geoson of your DHIS application to be accessible to the GIS + module. If the GeoJSON directory does not exist, you will need to create + it manually and copy your GeoJSON files there.

+

Administrator panel

+ +

Map source

GeoJSON: you will find your own + registered maps in the Map combo box in the Thematic map panel. + The Admin panels check box will become visible.

DHIS Database: the Map combo box will + simply be populated by the existing organisation unit levels and + GeoJSON files will be created by the application automatically + Organisation units must have coordinates stored in the database in + order to be displayed in the map. This function is mainly intended + for the facility level as it is easy to maintain and thus will + offer up-to-date shapefiles.

Admin panel

Show/hide the shapefile management panels.

+

Registering geographical information

+ +

In order to view data in the GIS module, you must import your + geographical data into your DHIS installation. Once you have produced + GeoJSON files according to the procedure above, and imported them into the + system, you will need to establish a correspondence between the + information in the DHIS database, and the GeoJSON file.

+
Organisation unit level

The level of the organization units displayed in the GeoJSON + file.

Map source file

The GeoJSON file name. These files must be placed in the + mapping/geojson folder. Use e.g. Geoserver 2.0 (currently RC1) to + easily produce GeoJSON from your shapefiles.

Display name

Represents your map in the Map combo box in the Thematic map + panel.

Name column

The shapefile data column (case sensitive!) that will be + matched against DHIS organisation unit names. If you have an + instance of Geoserver installed, you can view the layer through the + built-in OpenLayers client. Click on a particular area, and the + possible fields will be displayed.

+
+
Longitude / latitude

The longitude and latitude refer to the approximate point + where the map will be centered after rendering. If you have + Geoserver running, you can view the layer through the integrated + OpenLayers client and determine a good center point for your map. + You can also use the background map of the DHIS GIS module, and + determine an approximate location. You may need to experiment a bit + with the center point and zoom level in order to get it + correct.

+
+
Zoom

The zoom level controls the extent of the map. Some + experimentation will be required to get the correct zoom level. + Start with a value of "7" and increase or decrease the zoom level + depending on the extent of the map that should be displayed.

+

Assign organization units to map

+ +

Select a registered map and wait for it to load. The organisation + units (OU) in your database on this level will appear in the list and + colors will appear in the map. What we want to do here is creating + relations between OUs in the database and the corresponding OUs in the + shapefile. This is often necessary because of inconsistencies in the + naming in the geographical data, and what is present in the DHIS database. + First, try auto-assign at the bottom toolbar to let the application link + the OUs with a matching OU name in the shapefile. The polygons that remain + white, you will have to link manually by first selecting a white OU in the + list and then click the corresponding OU in the map.

+

The remove button at the button tool bar removes the selected OU’s + link. The remove all button removes all OU links for the selected + map.

+

Register overlays

+ +

Overlays are geographical layers that do not have any direct linkage + to data in the database. Example include roads, rivers, airports, ports, + and other geographical information that you may want to display on your + map, but that is not neccsarily linked ot data contained in the DHIS + database. The Register Overlay panel will allow you to + add new layers and determine how they will be represented visually on the + map.

  • Display name: Represents your overlay in + the layer tree in the upper right corner.

  • Map source file: The GeoJSON file + name.

  • Fill color: Decides the fill color if the + layer is a polygon layer.

  • Fill opacity: Select an opacity level + between 0 (invisible) and 1 (solid).

  • Stroke color: The stroke color over lines + and polygon borders.

  • Stroke width: Select a stroke width between + 0 and 4.

+

Thematic map

+ +

This panel should be rather self-explanatory . Calculation method + alludes to the legend interval size and set to Equal + intervals they will be “highest map value – lowest map value + / number of classes”. Choose Fixed bounds and + you may set your own legend limits, e.g. “20,40,60” using a comma to + seperate each of the class break values.

+

Register views

+ +

This panel will save the current thematic map view in order to + restore it whenever you want via the Map view + combo box in the Thematic map panel. By + adding your views to DHIS 2 Dashboard you may access them there by + inserting Map views into one of link + areas.

+

Register legend sets

+ +

A legend set may be connected to many indicators, but an indicator + may only have one legend set. Thus, you may select many indicators when + you create a legend set. When an indicator that has a legend set is + selected in the Thematic map panel, the number of + classes, low color and high color is automatically set.

\ No newline at end of file === removed file 'docs/dhis2_gis_user_manual_en.html' --- docs/dhis2_gis_user_manual_en.html 2009-09-10 06:32:34 +0000 +++ docs/dhis2_gis_user_manual_en.html 1970-01-01 00:00:00 +0000 @@ -1,79 +0,0 @@ - - - DHIS 2 GIS User Manual - Jan - HenrickŘverlandJasonPickering12009-09-09jppInitial - drafting of DocBook format
-

- - DHIS 2 GIS User Manual -

Jan - Henrick Řverland

Jason Pickering

Revision History
Revision 12009-09-09jpp
Initial - drafting of DocBook format

- -

Table of Contents

Production of of geographical data
Production of GeoJSON files with Geoserver
Production of GeoJSON files with GDAL
Copying files to the DHIS application
Administrator panel
Registering geographical information
-

Production of of geographical data

- -

The DHIS2 mapping client relies on GeoJSON files in order to - display a map in the browser window. Often times, geographical data - is received in many different formats, but the ESRI shape file - format is one of the most common. Several procedures will be - described below. It is important, but not required, that the names - in your geographical data match those in the DHIS2 organizational - hierachy. If they do not, you will need to manually match them in a - later step

-

Production of GeoJSON files with Geoserver

- -

Geoserver is capable of outputting GeoJSON formats. If you - have geoserver running someplace, you can execute the following - query.

http://localhost:8080/geoserver/wfs?request=GetFeature&typename=who:zm_adm1&outputformat=json

You will need to adjust the host destination if the machine - is not your local machine as well as defining the actual layer in - Geoserver which should be output to GeoJSON (in this case - who:zm_adm1).

Geoserver will produce a GeoJSON file, and you will be - asked to save it. Once it has finished downloading, rename the - file following the suggested naming convention:

ISO2CountryCode followed by an underscore, followed by the - layer type (e.g. “admin” for administrative layers, “health” for - health administrative boundaries)

-

Production of GeoJSON files with GDAL

- -

GDAL is a multi-platform toolkit for the manipulation of - geographical data. It is freely available for a wide-range of - platforms at http://gdal.org/.

Production of GeoJSON files are straightforward with GDAL. - Just exectue

ogr2ogr.exe -f "GeoJSON" dst_datasource_name src_datasource_name  (Windows)
-
-or
-ogr2ogr -f "GeoJSON"dst_datasource_name src_datasource_name (Linux) 

Replace dst_datasource_name with the path to the - destination geographical data file (following the naming - convention described above and src_datasource_name with the - source geographical data file.

-

Copying files to the DHIS application

- -

Currently, your GeoJSON files should be placed in the - /webapps/dhis/mapping/geojson of your DHIS application to be - accessible to the GIS application.

-

Administrator panel

- -

Map source

Shapefile: you will find your own registered maps in - the Map combo box in the Thematic map panel. The Admin - panels check box will become visibile.

DHIS Database: the Map combo box will simply be - populated by the existing organisation unit levels and - shapefiles will be created by the application on the fly. - Organisation units must have coordinates stored in the - datasbase in order to be displayed in the map. This - function is mainly intended for the facility level as it is - easy to maintain and thus will offer up-to-date - shapefiles.

Admin panel

Show/hide the shapefile management panels.

-

Registering geographical information

- -

In order to view data in the GIS module, you must import your - geographical data into your DHIS installation. Once you have - produced GeoJSON files according to the procedure above, and - imported them into the system, you will need to establish a - correspondnce between the information in the DHIS database, and the - GeoJSON file.

Organisation unit level

The level of the organization units displayed in the - GeoJSON file.

Map source file

The GeoJSON file name. These files must be placed in - the mapping/geojson folder. Use e.g. Geoserver 2.0 (currently - RC1) to easily produce GeoJSON from your shapefiles.

Display name

Represents your map in the Map combo boxe in the - Thematic map panel.

Name column

The shapefile data column (case sensitive!) that will - be matched against DHIS organisation unit names. There are - several ways to get it, eg. Geoserver:

\ No newline at end of file === modified file 'docs/dhis2_gis_user_manual_en.xml' --- docs/dhis2_gis_user_manual_en.xml 2009-09-10 06:32:34 +0000 +++ docs/dhis2_gis_user_manual_en.xml 2009-09-12 09:27:37 +0000 @@ -1,230 +1,382 @@ - - + +
- - - - - DHIS 2 GIS User Manual - <author><firstname>Jan - Henrick</firstname><surname>Øverland</surname></author> - - <author><firstname>Jason</firstname><surname>Pickering</surname></author> - - <revhistory> - - <revision><revnumber>1</revnumber><date>2009-09-09</date><authorinitials>jpp</authorinitials><revremark>Initial - drafting of DocBook format</revremark></revision> - - </revhistory> - - - + DHIS 2 GIS User Manual + + + DHIS + + GIS + + Mapping + + + + Øverland + + Jan Henrik + + + + Pickering + + Jason Paul + + + + + 1 + + 12/09/2009 + + JPP + + + Initial conversion of document to DocBook format + + + - - Production of of geographical data - - The DHIS2 mapping client relies on GeoJSON files in order to - display a map in the browser window. Often times, geographical data - is received in many different formats, but the ESRI shape file - format is one of the most common. Several procedures will be - described below. It is important, but not required, that the names - in your geographical data match those in the DHIS2 organizational - hierachy. If they do not, you will need to manually match them in a - later step + Conversion of geographical data to GeoJSON format + + The DHIS2 mapping client relies on GeoJSON files in order to display + a map in the browser window. Often times, geographical data is received in + many different formats, but the ESRI shape file format is one of the most + common. Several procedures will be described below. It is important, but + not required, that the names in your geographical data match those in the + DHIS2 organizational hierarchy. If they do not, you will need to manually + match them in a later step - Production of GeoJSON files with Geoserver - Geoserver is capable of outputting GeoJSON formats. If you - have geoserver running someplace, you can execute the following - query. - - - http://localhost:8080/geoserver/wfs?request=GetFeature&typename=who:zm_adm1&outputformat=json - - You will need to adjust the host destination if the machine - is not your local machine as well as defining the actual layer in - Geoserver which should be output to GeoJSON (in this case - who:zm_adm1). - - Geoserver will produce a GeoJSON file, and you will be - asked to save it. Once it has finished downloading, rename the - file following the suggested naming convention: - - ISO2CountryCode followed by an underscore, followed by the - layer type (e.g. “admin” for administrative layers, “health” for - health administrative boundaries) - + Geoserver is capable of outputting GeoJSON formats. If you have + geoserver running someplace, you can execute the following query. + + http://localhost:8080/geoserver/wfs?request=GetFeature&typename=who:zm_adm1&outputformat=json + + You will need to adjust the host destination if the machine is not + your local machine as well as defining the actual layer in Geoserver + which should be output to GeoJSON (in this case + who:zm_adm1). + + Upon execution of the URL, Geoserver will produce a GeoJSON file, + and you will be asked to save it. Once it has finished downloading, + rename the file following the suggested naming convention: + + ISO2CountryCode followed by an underscore, followed by the layer + type (e.g. “admin” for administrative layers, “health” for health + administrative boundaries). For instance, the first administrative layer + for Zambia would be named as "zm_admin1". - Production of GeoJSON files with GDAL - GDAL is a multi-platform toolkit for the manipulation of - geographical data. It is freely available for a wide-range of - platforms at http://gdal.org/. - - Production of GeoJSON files are straightforward with GDAL. - Just exectue - - ogr2ogr.exe -f "GeoJSON" dst_datasource_name src_datasource_name (Windows) - -or -ogr2ogr -f "GeoJSON"dst_datasource_name src_datasource_name (Linux) - Replace dst_datasource_name with the path to the - destination geographical data file (following the naming - convention described above and src_datasource_name with the - source geographical data file. - + GDAL is a multi-platform toolkit for the manipulation of + geographical data. It is freely available for a wide-range of platforms + at http://gdal.org + + Production of GeoJSON files are straightforward with GDAL. Just + execute (on Windows) + + ogr2ogr.exe -f "GeoJSON" dst_datasource_name src_datasource_name + + or on Linuxogr2ogr -f "GeoJSON"dst_datasource_name src_datasource_name + + Replace dst_datasource_name with the path + to the destination geographical data file (following the naming + convention described above) and + src_datasource_name with the source geographical + data file. - Copying files to the DHIS application - Currently, your GeoJSON files should be placed in the - /webapps/dhis/mapping/geojson of your DHIS application to be - accessible to the GIS application. - + Currently, your GeoJSON files should be placed in the + DHIS_HOME/geoson of your DHIS application to be accessible to the GIS + module. If the GeoJSON directory does not exist, you will need to create + it manually and copy your GeoJSON files there. - - Administrator panel - - - - - + + + + + - Map source - - Shapefile: you will find your own registered maps in - the Map combo box in the Thematic map panel. The Admin - panels check box will become visibile. - - DHIS Database: the Map combo box will simply be - populated by the existing organisation unit levels and - shapefiles will be created by the application on the fly. - Organisation units must have coordinates stored in the - datasbase in order to be displayed in the map. This - function is mainly intended for the facility level as it is - easy to maintain and thus will offer up-to-date - shapefiles. - + GeoJSON: you will find your own + registered maps in the Map combo box in the Thematic map panel. + The Admin panels check box will become visible. + + DHIS Database: the Map combo box will + simply be populated by the existing organisation unit levels and + GeoJSON files will be created by the application automatically + Organisation units must have coordinates stored in the database in + order to be displayed in the map. This function is mainly intended + for the facility level as it is easy to maintain and thus will + offer up-to-date shapefiles. - - - Admin panel + Admin panel - Show/hide the shapefile management panels. - - - - - - - + - Registering geographical information - In order to view data in the GIS module, you must import your - geographical data into your DHIS installation. Once you have - produced GeoJSON files according to the procedure above, and - imported them into the system, you will need to establish a - correspondnce between the information in the DHIS database, and the - GeoJSON file. - - + In order to view data in the GIS module, you must import your + geographical data into your DHIS installation. Once you have produced + GeoJSON files according to the procedure above, and imported them into the + system, you will need to establish a correspondence between the + information in the DHIS database, and the GeoJSON file. + + + Register Geodata Panel + + + + + + + + - - Organisation unit level - - The level of the organization units displayed in the - GeoJSON file. - + The level of the organization units displayed in the GeoJSON + file. - - Map source file - - The GeoJSON file name. These files must be placed in - the mapping/geojson folder. Use e.g. Geoserver 2.0 (currently - RC1) to easily produce GeoJSON from your shapefiles. - + The GeoJSON file name. These files must be placed in the + mapping/geojson folder. Use e.g. Geoserver 2.0 (currently RC1) to + easily produce GeoJSON from your shapefiles. - - Display name - - Represents your map in the Map combo boxe in the - Thematic map panel. - + Represents your map in the Map combo box in the Thematic map + panel. - - Name column - - The shapefile data column (case sensitive!) that will - be matched against DHIS organisation unit names. There are - several ways to get it, eg. Geoserver: - - - - - - - - + The shapefile data column (case sensitive!) that will be + matched against DHIS organisation unit names. If you have an + instance of Geoserver installed, you can view the layer through the + built-in OpenLayers client. Click on a particular area, and the + possible fields will be displayed. + + + Identification of the name column with Geoserver's + OpenLayers client + + + + + + + + + + Identification of the name column directly in the + GeoJSON file + + + + + + + + + + + + Longitude / latitude + + + The longitude and latitude refer to the approximate point + where the map will be centered after rendering. If you have + Geoserver running, you can view the layer through the integrated + OpenLayers client and determine a good center point for your map. + You can also use the background map of the DHIS GIS module, and + determine an approximate location. You may need to experiment a bit + with the center point and zoom level in order to get it + correct. + + + Using Geoserver OpenLayers client to get the map + center point + + + + + + + + + + Using DHIS GIS Module to get the map center + point + + + + + + + + + + + + Zoom + + + The zoom level controls the extent of the map. Some + experimentation will be required to get the correct zoom level. + Start with a value of "7" and increase or decrease the zoom level + depending on the extent of the map that should be displayed. + + - - - - - + + + + Assign organization units to map + + Select a registered map and wait for it to load. The organisation + units (OU) in your database on this level will appear in the list and + colors will appear in the map. What we want to do here is creating + relations between OUs in the database and the corresponding OUs in the + shapefile. This is often necessary because of inconsistencies in the + naming in the geographical data, and what is present in the DHIS database. + First, try auto-assign at the bottom toolbar to let the application link + the OUs with a matching OU name in the shapefile. The polygons that remain + white, you will have to link manually by first selecting a white OU in the + list and then click the corresponding OU in the map. + + + Assigning Organizational Units to the map + + + + + + + + + The remove button at the button tool bar removes the selected OU’s + link. The remove all button removes all OU links for the selected + map. + + + + Register overlays + + Overlays are geographical layers that do not have any direct linkage + to data in the database. Example include roads, rivers, airports, ports, + and other geographical information that you may want to display on your + map, but that is not neccsarily linked ot data contained in the DHIS + database. The Register Overlay panel will allow you to + add new layers and determine how they will be represented visually on the + map. + + + + Display name: Represents your overlay in + the layer tree in the upper right corner. + + + + Map source file: The GeoJSON file + name. + + + + Fill color: Decides the fill color if the + layer is a polygon layer. + + + + Fill opacity: Select an opacity level + between 0 (invisible) and 1 (solid). + + + + Stroke color: The stroke color over lines + and polygon borders. + + + + Stroke width: Select a stroke width between + 0 and 4. + + + + + + Thematic map + + This panel should be rather self-explanatory . Calculation method + alludes to the legend interval size and set to Equal + intervals they will be “highest map value – lowest map value + / number of classes”. Choose Fixed bounds and + you may set your own legend limits, e.g. “20,40,60” using a comma to + seperate each of the class break values. + + + + Register views + + This panel will save the current thematic map view in order to + restore it whenever you want via the Map view + combo box in the Thematic map panel. By + adding your views to DHIS 2 Dashboard you may access them there by + inserting Map views into one of link + areas. + + + + Register legend sets + + A legend set may be connected to many indicators, but an indicator + may only have one legend set. Thus, you may select many indicators when + you create a legend set. When an indicator that has a legend set is + selected in the Thematic map panel, the number of + classes, low color and high color is automatically set. +
- === modified file 'docs/images/admin_panel.png' Binary files docs/images/admin_panel.png 2009-09-10 06:32:34 +0000 and docs/images/admin_panel.png 2009-09-12 09:27:37 +0000 differ === added file 'docs/images/assign_org_units.png' Binary files docs/images/assign_org_units.png 1970-01-01 00:00:00 +0000 and docs/images/assign_org_units.png 2009-09-12 09:27:37 +0000 differ === added file 'docs/images/dhis_gis_center_point.png' Binary files docs/images/dhis_gis_center_point.png 1970-01-01 00:00:00 +0000 and docs/images/dhis_gis_center_point.png 2009-09-12 09:27:37 +0000 differ === added file 'docs/images/geoserver_center_point.png' Binary files docs/images/geoserver_center_point.png 1970-01-01 00:00:00 +0000 and docs/images/geoserver_center_point.png 2009-09-12 09:27:37 +0000 differ === modified file 'docs/images/register_geodata.png' Binary files docs/images/register_geodata.png 2009-09-10 06:32:34 +0000 and docs/images/register_geodata.png 2009-09-12 09:27:37 +0000 differ