dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #13267
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 371: Revised Creating GIS document. Corrected how to create/reproject to GML
------------------------------------------------------------
revno: 371
committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Sun 2011-07-24 12:30:05 +0200
message:
Revised Creating GIS document. Corrected how to create/reproject to GML
modified:
src/docbkx/en/dhis2_documentation_guide.xml
src/docbkx/en/dhis2_user_man_creating_gis.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/docbkx/en/dhis2_documentation_guide.xml'
--- src/docbkx/en/dhis2_documentation_guide.xml 2011-06-09 08:50:51 +0000
+++ src/docbkx/en/dhis2_documentation_guide.xml 2011-07-24 10:30:05 +0000
@@ -100,7 +100,13 @@
<para>Screen shots are very useful for providing information to users on how particular actions
should be performed. DocBook has no intrinsic mechanisms to know exactly how an image should be rendered in the final document. Therefore, it is necessary to provide instructions through element attributes. The following XML code fragment demonstrates how an image can be specified to occupy 80% of the available page width. For screen shots in landscape format, this seems to be an appropriate amount. You may need to experiment a bit to obtain a proper width for your image. Alternatively, you can edit the resolution of the image itself, in order to obtain a proper size during rendering. </para>
<literallayout><screenshot>
-<screeninfo>DHIS2 Login screen</screeninfo> <mediaobject> <imageobject> <imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/> </imageobject> </mediaobject> </screenshot></literallayout>
+ <screeninfo>DHIS2 Login screen</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/>
+ </imageobject>
+ </mediaobject>
+</screenshot></literallayout>
<para>For other images, depending on their size, a different value may be necessary. If you do
not specify a width for you image, and its intrinsic size is larger than the available screen width, the image may overflow in certain document types with a fixed width, such as PDF. </para>
</section>
@@ -116,14 +122,15 @@
<para>In order to include an article into a book, an Xinclude statement must be used. The
following example shows how. </para>
<para>
-<literallayout> <chapter>
-<title>Getting started with DHIS2</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_mod2.xml" xpointer="mod2_1" encoding="UTF-8"/> </literallayout>
+<literallayout><chapter>
+<title>Getting started with DHIS2</title>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_mod2.xml" xpointer="mod2_1" encoding="UTF-8"/>
+... </literallayout>
</para>
<para>Note that the file name and id have been assigned in the parent document, referring to the
actual file (href) and particular fragment of the child document that should be referenced in the parent document (xpointer). </para>
<para>Including chapters in a book is very simple. The example below illustrates how: </para>
- <para>
-<literallayout> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_
+ <para><literallayout><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_
mod1.xml" encoding="UTF-8"/> </literallayout>
</para>
<para>In this case, there is no need to explicitly reference a part of the document, unless you
=== modified file 'src/docbkx/en/dhis2_user_man_creating_gis.xml'
--- src/docbkx/en/dhis2_user_man_creating_gis.xml 2011-06-27 09:20:19 +0000
+++ src/docbkx/en/dhis2_user_man_creating_gis.xml 2011-07-24 10:30:05 +0000
@@ -7,36 +7,40 @@
<para>
Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are distributed in shapefiles, which is the most common geospatial vector data format for desktop applications (you might find shapefiles for your country at http://www.diva-gis.org/gdata). The work that needs to be done in order to use these coordinates in DHIS 2 GIS is transfering them and storing them with the corresponding organisation units in the database.
</para>
- <para>If you go to the organisation unit module and edit one of the units, you can see a textfield called Coordinates. Here you may fill in its coordinates directly (geojson format) which is quite neat if you just want to update a couple of units. However, if you are going to e.g. add coordinates for all units at a certain level you don't want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.
+ <para>If you go to the organisation unit module and edit one of the units, you can see a textfield called Coordinates. Here you may fill in its coordinates directly (geojson format) which is quite neat if you just want to update a couple of units. However, if you are going to e.g. add coordinates for all units at a certain level you don't want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.
</para>
</section>
<section id="gisSetup">
<title>Importing coordinates</title>
<para>Step 1 - Simplify/generalize your shapefile</para>
<para>
- The boundaries in shapefiles are usually very accurate. This does not cause any trouble for hardware accelerated desktop based GIS software, but it might be too heavy for the web based GIS application in DHIS 2. Thus, we need to make the boundary lines less detailed by removing some of the line points. Go to http://mapshaper.com/test/demo.html and upload your shapefile. Then, at the center bottom you see a slider that starts at 0%. It is usually ok to drag it up to about 80%. In the left menu you can check "show original lines" to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click "export" in the top right corner. Then check the first of the four options called "Shapefile - polygons", click "create" and wait for the download buttons to appear. Now, download the two files and overwrite the existing .shp and .shx files in your shapefile set (a shapefile is actually a set that has three mandatory files called .shp, .shx and .dbf and sometimes up to 15 files in total). Move on to the next step with your new simplified shapefile.
+ The boundaries in shapefiles are usually very accurate. This does not cause any trouble for hardware accelerated desktop based GIS software, but it might be too heavy for the web based GIS application in DHIS 2. Thus, we need to make the boundary lines less detailed by removing some of the line points. Go to <ulink url="http://mapshaper.com/test/demo.html";>http://mapshaper.com/test/demo.html</ulink> and upload your shapefile. Then, at the center bottom you see a slider that starts at 0%. It is usually ok to drag it up to about 80%. In the left menu you can check "show original lines" to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click "export" in the top right corner. Then check the first of the four options called "Shapefile - polygons", click "create" and wait for the download buttons to appear. Now, download the two files and overwrite the existing .shp and .shx files in your shapefile set (a shapefile is actually a set that has three mandatory files called .shp, .shx and .dbf and sometimes up to 15 files in total). Move on to the next step with your new simplified shapefile.
</para>
- <para></para>
+ <para/>
<para>Step 2 - Convert the shapefile to GML</para>
<para>
- The recommended tool for geographical format conversions is called "ogr2ogr". This should be available for most Linux distros ("sudo apt-get install gdal-bin"). For Windows, go to http://fwtools.maptools.org/ and download "FWTools", install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with regular longitude and latitude). We can do this with the "-s_srs" flag (means "set spatial reference system"). The command syntax is: "ogr2ogr -s_srs output_projection output_file.output_format input_file.input_format". Now, if we have a shapefile called "sl_districts.shp" and want to convert it to GML, use the following command: <programlisting><userinput> ogr2ogr -s_srs EPSG:4326 -f GML sl_districts.gml sl_districts.shp </userinput></programlisting> You will find the created GML file in the same folder as the shapefile.
+ The recommended tool for geographical format conversions is called "ogr2ogr". This should be available for most Linux distros ("sudo apt-get install gdal-bin"). For Windows, go to http://fwtools.maptools.org/ and download "FWTools", install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this <ulink url="http://www.epsg-registry.org/";>site</ulink>. If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that <command>ogr2ogr</command> can determine the input spatial reference system. You can determine the spatial reference system by executing the following command.</para>
+ <para><programlisting><userinput>ogrinfo -al -so filename.shp</userinput></programlisting></para>
+ <para>Assuming that the projection is reported to be EPSG:27700 by <command>ogrinfo</command>, we can transform it to EPSG by executing the following command.<programlisting><userinput> ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp </userinput></programlisting></para>
+ <para>If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by executing the following command. </para>
+ <para><programlisting><userinput>ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp</userinput></programlisting></para>
+ <para> You will find the created GML file in the same folder as the shapefile.
</para>
- <para></para>
<para>Step 3 - Prepare the GML file</para>
<para>
- Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a <gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are just going to import their coordinates. In order to do this DHIS 2 will match the name of the feature members to the organisation unit names in the database. To get the name of the feature memebers in the GML file the importer will look for a property called "ogr:Name". Figure out what property that is holding the name of the feature members (could be "ogr:DISTRICT_NAME", "ogr:NAME_1" or whatever, this differs from shapefile to shapefile) and rename it to "ogr:Name". Ensure that both the start and the end tags are renamed properly. They are supposed to look like e.g.: <ogr:Name>Moyamba District</ogr:Name>
- </para>
- <para>
- Note that the name of the feature members in the GML file must be spelled exactly the same as the organisation units in the database. Otherwise the importer will not recognize it and thus not transfer any coordinates. E.g. "Moyamba" in the GML file migth be called "Moyamba District" in the database. Creative use of the "rename all" function in the text editor is usually of great help in these situations, as you do not want to edit numerous feature members manually. Have a brief look at the names and compare them to the names in the database. If they seem to match fairly good, it is about time to do a preview in the import-export module.
- </para>
- <para>
- Go to Services -> Import-Export, select "Preview", select the GML file and click "Import". Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the "discard all" button below the list and then the "Import all" button above the list.
+ Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a <gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are just going to import their coordinates. In order to do this DHIS 2 will match the name of the feature members to the organisation unit names in the database. To get the name of the feature memebers in the GML file the importer will look for a property called "ogr:Name". Figure out what property that is holding the name of the feature members (could be "ogr:DISTRICT_NAME", "ogr:NAME_1" or whatever, this differs from shapefile to shapefile) and rename it to "ogr:Name". Ensure that both the start and the end tags are renamed properly. They are supposed to look like e.g.: <ogr:Name>Moyamba District</ogr:Name>
+ </para>
+ <para>
+ Note that the name of the feature members in the GML file must be spelled exactly the same as the organisation units in the database. Otherwise the importer will not recognize it and thus not transfer any coordinates. E.g. "Moyamba" in the GML file migth be called "Moyamba District" in the database. Creative use of the "rename all" function in the text editor is usually of great help in these situations, as you do not want to edit numerous feature members manually. Have a brief look at the names and compare them to the names in the database. If they seem to match fairly good, it is about time to do a preview in the import-export module.
+ </para>
+ <para>
+ Go to Services -> Import-Export, select "Preview", select the GML file and click "Import". Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the "discard all" button below the list and then the "Import all" button above the list.
</para>
<para>
If the import process completes successfully, you are good to go. If not, check the log for hints and look for common errors such as:
</para>
<para>- Name duplicates in the GML file. The name column in the database is unique and does not accept two organisation units with the same name.</para>
- <para>- The "shortname" column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.</para>
+ <para>- The "shortname" column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.</para>
<para>- Special name characters in the GML file. Rename or remove.</para>
</section>
<section>
@@ -44,18 +48,18 @@
<section id="gisAdministratorSettings">
<title>Administrator settings</title>
<para>
- Administrator settings are available only to users with admin rights. The administrator settings window can be opened from the map toolbar, click on the gears symbol (tooltip says "Administrator settings").
+ Administrator settings are available only to users with admin rights. The administrator settings window can be opened from the map toolbar, click on the gears symbol (tooltip says "Administrator settings").
</para>
<para>
- - Google Maps: In order to have Google Maps as background you need to fill in an Google Maps API key created for the domain the applcation is running on. The default key works for localhost. If you want to set up GIS on an external server you have to create and fill in the key for this domain, more info here http://code.google.com/apis/maps/signup.html. You will be provided with a link such as: http://maps.google.com/maps?file=api&v=2&sensor=false&key=ABQIAAAAut6AhySExnYIXm5s2OFIkxRKNzJ-_9njnryRTbvC6CtrS4sRvRREWnxwlZUa630pLuPf3nD9i4fq9w. Note that you are supposed to fill in the key only, i.e. the encrypted string that follows after "key=", not the entire link.
+ - Google Maps: In order to have Google Maps as background you need to fill in an Google Maps API key created for the domain the applcation is running on. The default key works for localhost. If you want to set up GIS on an external server you have to create and fill in the key for this domain, more info here http://code.google.com/apis/maps/signup.html. You will be provided with a link such as: http://maps.google.com/maps?file=api&v=2&sensor=false&key=ABQIAAAAut6AhySExnYIXm5s2OFIkxRKNzJ-_9njnryRTbvC6CtrS4sRvRREWnxwlZUa630pLuPf3nD9i4fq9w. Note that you are supposed to fill in the key only, i.e. the encrypted string that follows after "key=", not the entire link.
<screenshot>
- <screeninfo>Layer options</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="50%" fileref="resources/images/gis/gis_google_key.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </screenshot>
+ <screeninfo>Layer options</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="50%" fileref="resources/images/gis/gis_google_key.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
</para>
<para>
- Date: Choose between fixed periods and start/end dates. Fixed periods refers to the periods created by the DHIS 2. Start/end dates means that you can define the period yourself by selecting the exact start date and end date of the period.
