Update README

README.rst

@@ -0,0 +1,163 @@
+==============================================
+ckanext-spatial - Geo related plugins for CKAN
+==============================================
+
+This extension contains plugins that add geospatial capabilities to CKAN.
+Currently, there are a WMS previewer (`wms_preview`) and a spatial query
+API call (`spatial_query`) available.
+
+Dependencies
+============
+
+You will need CKAN installed. The present module should be installed at least 
+with `setup.py develop` if not installed in the normal way with
+`setup.py install` or using pip or easy_install.
+ 
+If you want to use the spatial search API, you will need PostGIS installed
+and enable the spatial features of your PostgreSQL database. See the
+"Setting up PostGIS" section for details.
+
+Configuration
+=============
+
+Plugins are configured as follows in the CKAN ini file::
+
+    ckan.plugins = wms_preview spatial_query
+
+If you are using the spatial search feature, you can define the projection
+in which extents are stored in the database with the following option. Use 
+the EPSG code as an integer (e.g 4326, 4258, 27700, etc). It defaults to 
+4258::
+    
+    ckan.spatial.srid = 4258
+
+
+Command line interface
+======================
+
+The following operations can be run from the command line using the 
+``paster extents`` command::
+
+      extents update 
+         - creates or updates the extent geometry column for packages with
+          a bounding box defined in extras
+       
+The commands should be run from the ckanext-spatial directory and expect
+a development.ini file to be present. Most of the time you will specify 
+the config explicitly though::
+
+        paster extents update --config=../ckan/development.ini
+
+
+API
+===
+
+The extension adds the following call to the CKAN search API, which returns
+packages with an extent that intersects with the bounding box provided::
+
+    /api/2/search/package/geo?bbox={minx,miny,maxx,maxy}[&crs={srid}]
+
+If the bounding box coordinates are not in the same projection as the one
+defined in the database, a CRS must be provided, in one of the following
+forms:
+
+- urn:ogc:def:crs:EPSG::4258
+- EPSG:4258
+- 4258
+
+
+Setting up PostGIS
+==================
+
+Configuration
+-------------
+
+*   Install PostGIS::
+
+        sudo apt-get install postgresql-8.4-postgis
+    
+*   Create a new PostgreSQL database::
+    
+        sudo -u postgres createdb [database]
+        
+    (If you just want to spatially enable an exisiting database, you can
+    ignore this point, but it's a good idea to create a template to
+    make easier to create new databases)
+
+*   Many of the PostGIS functions are written in the PL/pgSQL language,
+    so we need to enable it in our database::
+    
+        sudo -u postgres createlang plpgsql [database]
+
+*   Run the following commands. The first one will create the necessary
+    tables and functions in the database, and the second will populate
+    the spatial reference table::
+    
+        sudo -u postgres psql -d [database] -f /usr/share/postgresql/8.4/contrib/postgis-1.5/postgis.sql
+        sudo -u postgres psql -d [database] -f /usr/share/postgresql/8.4/contrib/postgis-1.5/spatial_ref_sys.sql    
+
+*   Execute the following command to see if PostGIS was properly
+    installed::
+    
+        sudo -u postgres psql -d [database] -c "SELECT postgis_full_version()"
+    
+    You should get something like::
+    
+                                             postgis_full_version                                          
+        ------------------------------------------------------------------------------------------------------
+        POSTGIS="1.5.2" GEOS="3.2.2-CAPI-1.6.2" PROJ="Rel. 4.7.1, 23 September 2009" LIBXML="2.7.7" USE_STATS
+        (1 row)
+    
+    Also, if you log into the database, you should see two tables,
+    ``geometry_columns`` and ``spatial_ref_sys`` (and probably a view
+    called ``geography_columns``).
+
+    Note: This commands will create the two tables owned by the postgres
+    user. You probably should make owner the user that will access the
+    database from ckan::
+    
+        ALTER TABLE spatial_ref_sys OWNER TO [your_user];
+        ALTER TABLE geometry_columns OWNER TO [your_user];
+
+More information on PostGIS installation can be found here:
+
+http://postgis.refractions.net/docs/ch02.html#PGInstall
+
+
+
+Setting up a spatial table
+--------------------------
+
+To be able to store geometries and perform spatial operations, PostGIS
+needs to work with geometry fields. Geometry fields should always be
+added via the ``AddGeometryColumn`` function::
+
+    CREATE TABLE package_extent(
+        package_id text PRIMARY KEY
+    );
+    
+    ALTER TABLE package_extent OWNER TO [your_user];
+    
+    SELECT AddGeometryColumn('package_extent','the_geom', 4258, 'POLYGON', 2);
+    
+This will add a geometry column in the ``package_extent`` table called
+``the_geom``, with the spatial reference system EPSG:4258. The stored 
+geometries will be polygons, with 2 dimensions.
+
+Have a look a the table definition, and see how PostGIS has created
+three constraints to ensure that the geometries follow the parameters
+defined in the geometry column creation::
+
+    # \d package_extent
+
+       Table "public.package_extent"
+       Column   |   Type   | Modifiers 
+    ------------+----------+-----------
+     package_id | text     | not null
+     the_geom   | geometry | 
+    Indexes:
+        "package_extent_pkey" PRIMARY KEY, btree (package_id)
+    Check constraints:
+        "enforce_dims_the_geom" CHECK (st_ndims(the_geom) = 2)
+        "enforce_geotype_the_geom" CHECK (geometrytype(the_geom) = 'POLYGON'::text OR the_geom IS NULL)
+        "enforce_srid_the_geom" CHECK (st_srid(the_geom) = 4258)