Geo and Geocode Modules Documentation Wiki

Here's my initial take on an outline for documentation for the Geo module. For the most part, I broke up the docs into three main areas. The "What is the Geo module?" section is meant to be a primer that provides a base level of knowledge for users new to GIS terminology. The "Module Requirements" section is pretty self-explanatory, but since it took me more than a few minutes to realize I needed to install the php_zip extension in order to use the Geo Data module I thought it might be good to document it. The "Functionality" section will obviously be the main part of the docs. I imagine it as a walk-through of each major aspect of the module.
In addition to this documentation, there's also some great documentation over at GeoJune.org including some technical documentation as well as several recipe-style examples.

Eventually, this will have to be split up into several pages, but for now, I thought it would be best to have everything in one place until we have the outline complete.

Since this is a wiki page, feel free to help me fill in all the details. If you can provide an example of a particular functionality, even better!

The Geo project actually contains three modules:

1. Geo - provides an API for storing/retriving spatial data for PostgreSQL and MySQL spatial fields
2. Geo Field - provides CCK integration for storage and display of native spatial data, using the Geo API
3. Geo Data - provides the ability to import and query ESRI shape files

What are the advantages of the Geo module over other Drupal GIS solutions?

• stores GIS data in native form using spatial extensions on MySql and PostgreSQL (Oracle and SQLLite also have spatial extensions, but are not yet implemented in the Geo module)
  • the spatial extensions allow you to do math on GIS data
    • is a point within a polygon?
    • do two linestrings intersect?
    • find the area of a polygon
  • PostgreSQL has a much fuller set of GIS functions than MySql.
    • If you're doing anything "serious", use PostgreSQL.
      • examples?
  • can store points, linestrings, and polygons

Here's a link to an diagram of how some of the various Geo modules fit together - the diagram focuses on the input side of things.

Related Modules

As the Geo module is predominantly an API, you probably want to download additional modules for more usable and attractive input and output of your Geo data. The following modules are designed to work with Geo:

• The Gmap Geo module provides CCK input widgets and output formatters for fields provided by the Geo Field module.
• Geocode allows you to derive geospatial information for Geo Field module storage from other sources. For example, you can gather GPX track data from a file field, EXIF coordinates from Image Fields, or geocode a postal address.
• The OpenLayers module provides a click and drawing interface to gather point, line and polygon information from an openlayers interface.

The Geocode module gets GIS data from other sources

• provides an API for discovering GIS data from multiple sources
• provides a CCK widget for Geo fields

• examples

  • take an address and send it to 3rd party service to get GIS data
  • take an image and extract any GIS data from exif
  • take a track file and extract the points from it
  • extract GIS data from a .gpx file

• What is Geo module?

  • CCK and Views required for most cases
  • terminology
    • shape files
    • point
    • linestring
    • polygon
    • WKT (well known text) - http://en.wikipedia.org/wiki/Well_Known_Text
      • POINT(x y)
        • format is POINT(lon lat)
        • sample point (Washington, D.C.): POINT(-95.677068 37.0625)
      • LINESTRING(point1, point2, point3, ...)
        • format is LINESTRING(lon lat, lon lat, lon lat, ...)
        • sample linestring (track from Washington D.C. to N.Y.): LINESTRING(-77.003 38.925, -76.5855 39.300,-75.102 39.968,-73.981 40.755 )
      • POLYGON((point1, point2, point3, point1), (point4, point5, point6, point4)) (outer boundry, inner boundry, ...)
        • format is POLYGON((lon lat, lon lat, ...))
        • sample polygon (portion of the Washington D.C. beltway): POLYGON((-77.106 39.020,-76.971 39.021,-76.890 39.002,-76.865 38.950,-76.847 38.900,-76.861 38.847,-77.106 39.020))
    • WKB (well known binary)
  • GIS resource links
    • http://www.opengeospatial.org - organization for setting up GIS standards
  • sample use cases
    • examples...
  • Module Requirements
    • The Geo Data module requires that the php_zip extension is enabled. With some common all-in-one Apache-MySql-PHP stacks, this is often not the case. For example, neither the current versions of MAMP or XAMPP come with the zip extension installed (MAMP instructions, XAMPP instructions). In WAMP however, it is a trivial process. Simply right-click the WAMP icon in the system tray, then navigate to "PHP Settings", then "PHP Extensions" and select "php_zip". The server will briefly restart, then the extension will be ready to go. For other PHP packages, you might need to use PEAR or PECL to assist you in getting it enabled.
    • PostgreSQL with spatial extensions
    • MySql with spatial extensions (it would be interesant to complete this part with some info like : How do I know if my version of MySQL is complient ?)
  • Functionality
    • Importing Shapefiles
      • Geospatial shapefiles can be imported into Drupal's database via the Geo Data module (included with the main Geo module). The required shapefile must be a .zip file that includes, at a minimum, a .shp, .dbf and .shx file.(what about .prj files as an alternative to SRID?) Once imported, the data can be integrated with the site through CCK and/or Views.
      • Shapefiles are imported via the "Site building|Geospatial data" menu item. As of March, 2009, the user interface is still under development, things are a bit wonky on the input page, but the basic functionality works. The input fields are described as follows:
        • Table label - this field only shows up once a shapefile has been imported. As of March, 2009, it doesn't really do anything.
        • Shapefile - a file input field used to select the shapefile for import. The shapefile must be a .zip file. This field is required.
        • Table name - The name of the table you'd like the import date into. If the table already exists, the imported data will be appeneded. This name must contain only lowercase letters, numbers, and underscores. The table name entered will be prepended with "geo_data_". This field is required.
        • SRID - the Spatial Reference IDentifier indicates the projection system of the imported shapefile. Knowing shapefile's reference system is imperative in knowing exactly how the data is plotted on the surface of the earth. Various spatial vendors use different reference systems, so the SRID provides a way to translate data between different reference systems. In PostgreSQL, or in any other "real" GIS system, it's necessary to store the SRID of each entity, so that when you do comparisons between objects, it knows whether those two objects are speaking the same language. If one side of the equation is using a different SRID than the other side, you must do an on-the-fly transformation to synch them up (example). When using PostgreSQL as the backend database, the value is required, while MySQL will just store it in case you want to do something responsible with it later. The most common projection, the lat/lon system you've encountered on Google Maps and elsewhere, is WGS 84, or 4326 (the default value for this field).
        • Create a new table - should be self-explanatory, if this box isn't checked, the imported data will go into an existing "geo_data_" table, potentially overwriting previous data. Need better documentation here.
    • geospatial CCK fields
      • data
        • input
          • direct text entry (WKT)
          • lat/long
          • gmap picker (via gmap_geo module - http://drupal.org/project/gmap_geo)
          • See the Geo GUI module (http://drupal.org/project/geo_gui) for inputting using a interactive map for WKT
        • display
          • WKT
          • latitude - working?
          • longitude - working?
          • GeoRSS - working?
          • GMap (via gmap_geo module - http://drupal.org/project/gmap_geo)
            • works for points entered via gmap picker
            • works for other user-entered points/lines/polygons, as well as geodata imported from shapefiles
            • Linestrings and polygons are gently simplified and displayed using the Google Maps API's "encoded polylines", allowing more detail to be shown as you zoom in
      • data reference
    • geospatial views output
      • GeoXML display
        • KML - working? I exported a polygon and it ended up in Antarctica
        • SVG - bounding box issues?
        • Simple XML - buggy?