PleiadesGeocoder
================

Provides basic geospatial capabilities for Plone, specifically:

* Geospatial annotation of content based on emerging standards. Point, line,
and polygon annotations are possible.

* Serialization of annotated content to Atom (+GeoRSS_) or KML, which enables
content to be marshaled into Google Earth, GMaps, or OpenLayers maps. 

* A geocoding tool based on geopy.

See http://icon.stoa.org/trac/pleiades/wiki/PleiadesGeocoder for more
information.

Contact: Sean Gillies <sgillies@frii.com>


Dependencies
------------

Before installing, see DEPENDENCIES.txt


Installing Releases
-------------------

PleiadesGeocoder is installed like any other Plone product.

1. Extract the release package to your site's SOFTWARE_HOME.

2. Restart Zope and install through Plone.

3. Give the portal_geocoder a trial run via portal_geocoder/geocodeForm.


Installing from Subversion
--------------------------

1. Checkout PleiadesGeocoder::

   $ svn co http://icon.stoa.org/svn/pleiades/PleiadesGeocoder/trunk \
   PleiadesGeocoder

2. Link to Zope Products directory, restart Zope, and install through the
   Plone admin menu.


Geospatial Annotation
---------------------

Content objects that provide
Products.PleiadesGeocoder.interfaces.IGeoreferenceable and have registered
adapters to Products.PleiadesGeocoder.interfaces.IGeoItemSimple can be
annotated via the edit_geo_form. See for example:

http://pleiades.stoa.org/batlas/65/edit_geo_form

PleiadesGeocoder marks all AT content types as providers of IGeoreferenceable
and IGeoItemSimple. In Python, content objects can be geo-annotated like so:

.. code-block:: python

  >>> ob = app['plone']['batlas']['65']
  >>> coordinates = (((28.54268, 38.08102, 0.0), ...))
  >>> geoitem.setGeoInterface('Polygon', coordinates)
  >>> geoitem.geom_type
  'Polygon'
  >>> geoitem.coords
  (((28.54268, 38.08102, 0.0), ...))


KML and GeoRSS views
--------------------

Annotated objects that provide
Products.PleiadesGeocoder.interfaces.IGeoserializable have GeoRSS and KML
representations via georss and kml views. See for example:

http://pleiades.stoa.org/batlas/65/georss
http://pleiades.stoa.org/batlas/65/kml

Furthermore, folderish objects containing geo-annotated content that provide
that same interface have similiar views. See

http://pleiades.stoa.org/batlas/georss
http://pleiades.stoa.org/batlas/kml

PleiadesGeocoder marks all AT folders and topics as providers of
IGeoserializable.


Geocoding Tool
--------------

Currently, geocoding aims at one of Plone's standard metadata fields: location.
This field is for strings like::

  "Chapel Hill, NC"
  "London, England"
  
Our current functionality focuses on site members. PleiadesGeocoder adds a new
string property named 'spatialCoordinates' to your memberdata property sheet,
and overrides the default personalize.py script.  On any update of member
location, the portal_geocoder tool will attempt to find the proper coordinates
by using the Google geocoding service. The coordinates are then stored in the
member's 'spatialCoordinates' property.

Views of a site's geocoded members can be had at the URLs:

${portal_url}/Members/georss
${portal_url}/Members/kml


Support
-------

Please subscribe to the pleiades-software_ email list. The archives may be
viewed online without subscription.


About Pleiades
--------------

Pleiades is an international research network and associated web portal and
content management system devoted to the study of ancient geography. 

See http://icon.stoa.org/trac/pleiades/wiki.

Funding for the creation of this software was provided by a grant from the 
U.S. National Endowment for the Humanities (http://www.neh.gov).

.. _GeoRSS: http://georss.org
.. _pleiades-software: http://icon.stoa.org/trac/pleiades/wiki/PleiadesSoftwareList

