== PostGIS \ActiveRecord Adapter

The PostGIS \ActiveRecord Adapter is an \ActiveRecord connection adapter
based on the standard postgresql adapter. It extends the standard adapter
to provide support for the spatial extensions provided by PostGIS, using
the {RGeo}[http://github.com/dazuma/rgeo] library to represent spatial
data in Ruby. Like the standard postgresql adapter, this adapter requires
the pg gem.

=== Usage

To use this adapter, add this gem, "activerecord-postgis-adapter", to
your Gemfile, and then request the adapter name "postgis" in your
database connection configuration (which, for a Rails application, is in
the config/database.yml file). The other database connection configuration
parameters are the same as for the stock postgresql adapter.

First, this adapter extends the migration syntax to support creating 
spatial columns and indexes. To create a spatial column, use the
<tt>:geometry</tt> type, or any of the OGC spatial types such as
<tt>:point</tt> or <tt>:line_string</tt>. To create a geography column,
set the <tt>:geographic</tt> option to true when creating the column.
To create a spatial index, set the <tt>:spatial</tt> option to true when
creating the index.

Examples:

 create_table :spatial_table do |t|
   t.column :shape, :geometry  # or t.geometry :shape
   t.line_string :path
   t.column :latlon, :point, :geographic => true
 end
 change_table :spatial_table do |t|
   t.index :latlon, :spatial => true
 end

When this adapter is in use, spatial attributes in your \ActiveRecord
objects will have RGeo geometry values. You can set spatial attributes
either to RGeo geometry objects, or to strings in WKT (well-known text)
format, which the adapter will automatically convert to geometry objects.

To specify the RGeo geometry factory, you can either set an explicit
factory for a column, or provide a factory generator that will yield the
appropriate factory for the table's spatial columns based on their types.
For the former, call the set_rgeo_factory_for_column class method on your
\ActiveRecord class. For the latter, set the rgeo_factory_generator class
attribute. This generator should understand the usual <tt>:srid</tt>,
<tt>:has_z_coordinate</tt>, and <tt>:has_m_coordinate</tt> options. It
will also be passed a <tt>:geographic</tt> option indicating whether the
column is a geography column. The set_rgeo_factory_for_column and 
rgeo_factory_generator methods are actually implemented and documented in
the "rgeo-activerecord" gem.

Examples, given the spatial table defined above:

 class SpatialTable < ActiveRecord::Base
   
   # By default, use the GEOS implementation for spatial columns.
   self.rgeo_factory_generator = RGeo::Geos.method(:factory)
   
   # But use a geographic implementation for the :latlon column.
   set_rgeo_factory_for_column(:latlon, RGeo::Geographic.spherical_factory)
   
 end

Now you can interact with the data using the RGeo types:

 rec = SpatialTable.new
 rec.latlon = 'POINT(-122 47)'   # You can set by feature object or WKT.
 loc = rec.latlon                # Accessing always returns a feature object, in
                                 # this case, a geographic that understands latitude.
 loc.latitude                    # => 47
 rec.shape = loc                 # the factory for the :shape column is GEOS, so the
                                 # value will be cast from geographic to GEOS.
 RGeo::Geos.is_geos?(rec.shape)  # => true

You can create simple queries based on spatial equality in the same way
you would on a scalar column:

 rec = SpatialTable.where(:latlon => RGeo::Geos.factory.point(-122, 47)).first

You can also use WKT:

 rec = SpatialTable.where(:latlon => 'POINT(-122 47)').first

Other types of queries currently must be written in SQL. However, we are
investigating writing a set of Arel extensions for constructing arbitrary
spatial queries.

=== Installation

This adapter has the following requirements:

* Ruby 1.8.7 or later. Ruby 1.9.2 or later preferred.
* PostGIS 1.5 or later.
* \ActiveRecord 3.0.3 or later. Earlier versions will not work.
* rgeo gem 0.2.3 or later.
* rgeo-activerecord gem 0.2.1 or later.
* pg gem 0.10 or later.

Install this adapter as a gem:

 gem install activerecord-postgis-adapter

See the README for the "rgeo" gem, a required dependency, for further
installation information.

=== Known bugs and limitations

A few minor holes still exist in this adapter. Notably, using \ActiveRecord
to list indexes doesn't properly identify GiST (spatial) indexes as such.
This adapter is also not yet well tested.

=== Development and support

Documentation is available at http://virtuoso.rubyforge.org/activerecord-postgis-adapter/README_rdoc.html

Source code is hosted on Github at http://github.com/dazuma/activerecord-postgis-adapter

Contributions are welcome. Fork the project on Github.

Report bugs on Github issues at http://github.org/dazuma/activerecord-postgis-adapter/issues

Contact the author at dazuma at gmail dot com.

=== Acknowledgments

RGeo is written by Daniel Azuma (http://www.daniel-azuma.com).

Development of RGeo is sponsored by GeoPage, Inc. (http://www.geopage.com).

This adapter implementation owes some debt to the spatial_adapter plugin
(http://github.com/fragility/spatial_adapter). Although we made some
different design decisions for this adapter, studying the spatial_adapter
source gave us a head start on the implementation.

=== License

Copyright 2010 Daniel Azuma

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
* Neither the name of the copyright holder, nor the names of any other
  contributors to this software, may be used to endorse or promote products
  derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.