ppe-postgis-adapter 0.7.2

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+doc/*
+rdoc/*
+coverage/*
+spec/debug.log
+pkg/*
+*flymake.rb

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-12-10
+
+* 1 major enhancement
+
+  * Birthday!
+

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Spatial Adapter Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+PostGis Adapter Functions (c) 2008 Marcos Piccinini <nofxx>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,347 @@
+= PostgisAdapter
+
+A plugin for ActiveRecord which manages the PostGIS geometric columns
+in a transparent way (that is like the other base data type columns).
+It also provides a way to manage these columns in migrations.
+
+This fork adds handy methods to make geometrical calculations on postgis.
+Based on http://georuby.rubyforge.org Spatial Adapter
+
+RDocs - http://docs.github.com/nofxx/postgis_adapter
+Postgis Manual - http://postgis.refractions.net/documentation/manual-svn
+
+*PostGIS and Rails 2+ only*.
+
+
+== Install
+
+If you are using Spatial Adapter, *remove it first*.
+
+
+=== Dependencies
+
+- georuby
+- postgres 8.3+
+- postgis  1.3+
+
+
+=== As gem:
+
+    sudo gem install postgis-adapter
+
+Rails:
+
+    config.gem "postgis_adapter"
+
+
+Github version:
+
+
+    sudo gem install nofxx-postgis_adapter --source http://gems.github.com
+
+Rails:
+
+    config.gem "nofxx-postgis_adapter", :lib => "postgis_adapter", :source => "http://gems.github.com"
+
+
+=== As plugin:
+
+    script/plugin install git://github.com/nofxx/postgis_adapter.git
+
+
+== How to Use
+
+Geometric columns in your ActiveRecord models now appear just like
+any other column of other basic data types. They can also be dumped
+in ruby schema mode and loaded in migrations the same way as columns
+of basic types.
+
+
+=== Example App
+
+Simple rails app to demonstrate, check it out:
+
+http://github.com/nofxx/postgis_example
+
+
+=== Model
+
+    class TablePoint < ActiveRecord::Base
+    end
+
+That was easy! As you see, there is no need to declare a column as geometric.
+The plugin will get this information by itself.
+
+Here is an example of PostGIS row creation and access, using the
+model and the table defined above :
+
+        pt = TablePoint.new(:data => "Hello!",:geom => Point.from_x_y(1,2))
+        pt.save
+        pt = TablePoint.first
+        puts pt.geom.x
+        => 1
+
+
+== PostGIS Functions
+
+Here are this fork additions. To use it:
+
+    acts_as_geom [column_name] => [geom_type]
+
+
+Examples:
+
+    class POI < ActiveRecord::Base
+      acts_as_geom :geom => :point
+    end
+
+    class Street < ActiveRecord::Base
+      acts_as_geom :line => :line_string
+    end
+
+    ...
+
+
+
+== Play!
+
+    @place  =   Poi.new(    :geom  =>  Point.from_x_y(10,20)    )
+    @park   =   Park.new(   :area  =>  **Polygon**     )
+    @street =   Street.new( :line  => **LineString**   )
+
+    @place.inside?(@park)
+    => true
+
+    @place.in_bounds?(@park, 0.5) # margin
+    => false
+
+    @place.outside?(@park)
+    @street.crosses?(@park)
+    @area.contains?(@place)
+    ...
+
+
+=== Polygons:
+
+    @park.area
+    => 1345
+
+    @park.contains?(@point)
+    => true
+
+    @park.overlaps?(@other_park)
+    => false
+
+Supports transform (useful to transform SRID to UTM for area in Km^2)
+
+    @park.area(SRID)
+    => Area with new SRID
+
+
+=== LineStrings:
+
+    @street_east.intersects?(@street_west)
+    => false
+
+    @street_central.length
+    => 4508.53636
+
+    @street.length_spheroid
+    => 4.40853636
+
+
+=== Class Methods
+
+    City.close_to(@point)
+    => [Array of cities in order by distance...
+
+    Street.close_to(@point)
+    => [Array streets in order by distance...
+
+    Country.contain(@point)
+    => The Conutry that contains the point
+
+    Area.contains(@point)
+    => [Array of areas contains the point...
+
+
+=== BBox Support
+
+    @area.strictly_left_of? @point
+
+    @area.overlaps_or_above? @street
+
+    ...
+
+    completely_contained_by?
+    completely_contains?
+    overlaps_or_above?
+    overlaps_or_below?
+    overlaps_or_left_of?
+    overlaps_or_right_of?
+    strictly_above?
+    strictly_below?
+    strictly_left_of?
+    strictly_right_of?
+    interacts_with?
+    binary_equal?
+    same_as?
+
+
+Or use a (almost) PostGIS like notation:
+
+    @area.bbox "<<", @point
+
+    @area.bbox "|>>", @point
+
+    @area.bbox "@",  @park
+
+
+=== Warning
+
+*To be fixed:*
+
+This only supports one geom column per model. Still looking for the best way to
+implement a multi geom.
+
+http://nofxx.lighthouseapp.com/projects/20712/tickets/3-multiple-geoms-in-model
+
+
+=== Find_by
+
+find_by_*column* has been redefined when column is of a geometric type.
+Instead of using the Rails default '=' operator, for which I can't see
+a definition for MySql spatial datatypes and which performs a bounding
+box equality test in PostGIS, it uses a bounding box intersection:
+&& in PostGIS and MBRIntersects in MySQL, which can both make use
+of a spatial index if one is present to speed up the queries.
+You could use this query, for example, if you need to display data
+from the database: You would want only the geometries which are in
+the screen rectangle and you could use a bounding box query for that.
+Since this is a common case, it is the default. You have 2 ways to use
+the find_by_*geom_column*: Either by passing a geometric object directly,
+or passing an array with the 2 opposite corners of a bounding box
+(with 2 or 3 coordinates depending of the dimension of the data).
+
+        Park.find_by_geom(LineString.from_coordinates([[1.4,5.6],[2.7,8.9],[1.6,5.6]]))
+
+  or
+
+        Park.find_by_geom([[3,5.6],[19.98,5.9]])
+
+In PostGIS, since you can only use operations with geometries with the same SRID, you can add a third element representing the SRID of the bounding box to the array. It is by default set to -1:
+
+        Park.find_by_geom([[3,5.6],[19.98,5.9],123])
+
+
+
+== Database Tools
+
+=== Migrations
+
+Here is an example of code for the creation of a table with a
+geometric column in PostGIS, along with the addition of a spatial
+index on the column :
+
+    ActiveRecord::Schema.define do
+      create_table :places do |t|
+        t.string   :name
+        t.point    :geom, :srid => 4326, :with_z => true, :null => false
+
+        t.timestamps
+      end
+
+      add_index :places, :geom, :spatial => true
+    end
+
+
+Types:
+
+    point
+    polygon
+    line_string
+    multi_point
+    multi_polygon
+    multi_line_string
+    geometry
+    geometry_collection
+
+
+=== Fixtures
+
+If you use fixtures for your unit tests, at some point,
+you will want to input a geometry. You could transform your
+geometries to a form suitable for YAML yourself everytime but
+the spatial adapter provides a method to do it for you: +to_yaml+.
+It works for both MySQL and PostGIS (although the string returned
+is different for each database). You would use it like this, if
+the geometric column is a point:
+
+    fixture:
+          id: 1
+          data: HELLO
+          geom: <%= Point.from_x_y(123.5,321.9).to_yaml %>
+
+
+=== Annotate
+
+If you are using annotate_models, check out this fork which adds geometrical annotations for PostgisAdapter and SpatialAdapter:
+
+http://github.com/nofxx/annotate_models
+
+
+== Geometric data types
+
+Ruby geometric datatypes are currently made available only through
+the GeoRuby library (http://georuby.rubyforge.org): This is where the
+*Point.from_x_y* in the example above comes from. It is a goal
+of a future release of the Spatial Adapter to support additional
+geometric datatype libraries, such as Ruby/GEOS, as long as they
+can support reading and writing of EWKB.
+
+
+
+=== Warning
+
+- Since ActiveRecord seems to keep only the string values directly
+returned from the database, it translates from these to the correct
+types everytime an attribute is read, which is probably ok for simple
+types, but might be less than efficient for geometries, since the EWKB
+string has to be parsed everytime. Also it means you cannot modify the
+geometry object returned from an attribute directly :
+
+       place = Place.first
+       place.the_geom.y=123456.7
+
+- Since the translation to a geometry is performed everytime the_geom
+is read, the change to y will not be saved! You would have to do
+something like this :
+
+       place = Place.first
+       the_geom = place.the_geom
+       the_geom.y=123456.7
+       place.the_geom = the_geom
+
+
+== License
+
+Spatial Adapter for Rails is released under the MIT license.
+Postgis Adapter is released under the MIT license.
+
+
+== Support
+
+Tested using rails 2.2.2/2.3.3 / postgresql 8.3.7 / postgis 1.3.3 / linux / osx
+
+Any questions, enhancement proposals, bug notifications or corrections:
+
+
+=== PostgisAdapter
+
+http://github.com/nofxx/postgis_adapter/issues
+
+
+=== SpatialAdapter
+
+http://georuby.rubyforge.org
+guilhem.vellut+georuby@gmail.com.

data/Rakefile

@@ -0,0 +1,70 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "postgis_adapter"
+    gem.summary = "PostGIS Adapter for Active Record"
+    gem.description = "Execute PostGIS functions on Active Record"
+    gem.email = "x@nofxx.com"
+    gem.homepage = "http://github.com/nofxx/postgis_adapter"
+    gem.authors = ["Marcos Piccinini"]
+    gem.rubyforge_project = "postgis_adapter"
+    # TODO: better way for this.....
+    #    gem.add_dependency 'geo_ruby'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION').chomp : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "postgis_adapter #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+#
+# Reek & Roodi
+#
+begin
+  require 'reek/rake_task'
+  Reek::RakeTask.new do |t|
+    t.fail_on_error = true
+    t.verbose = false
+    t.source_files = 'lib/**/*.rb'
+  end
+rescue LoadError
+  task :reek do
+    abort "Reek is not available. In order to run reek, you must: sudo gem install reek"
+  end
+end
+
+begin
+  require 'roodi'
+  require 'roodi_task'
+  RoodiTask.new do |t|
+    t.verbose = false
+  end
+rescue LoadError
+  task :roodi do
+    abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.7.2

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/lib/postgis_adapter/acts_as_geom.rb

@@ -0,0 +1,39 @@
+#
+# PostGIS Adapter
+#
+# http://github.com/nofxx/postgis_adapter
+#
+module PostgisFunctions
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  module ClassMethods
+
+    # acts_as_geom :db_field => :geom_type
+    # Examples:
+    #
+    # acts_as_geom :data => :point
+    # acts_as_geom :geom => :line_string
+    # acts_as_geom :geom => :polygon
+    #
+    def acts_as_geom(*geom)
+      cattr_accessor :postgis_geoms
+      self.postgis_geoms = geom[0] # {:columns => column
+      send :include, case geom[0].values[0]
+        when :point       then  PointFunctions
+        when :polygon     then PolygonFunctions
+        when :line_string then  LineStringFunctions
+      end unless geom[0].kind_of? Symbol
+    end
+
+    def get_geom_type(column)
+      self.postgis_geoms.values[0] rescue nil
+    #   self.columns.select { |c| c.name == column.to_s }[0].geometry_type
+    # rescue ActiveRecord::StatementInvalid => e
+    #   nil
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, PostgisFunctions

data/lib/postgis_adapter/common_spatial_adapter.rb

@@ -0,0 +1,184 @@
+#
+# PostGIS Adapter
+#
+# Common Spatial Adapter for ActiveRecord
+#
+# Code from
+# http://georuby.rubyforge.org Spatial Adapter
+#
+
+#Addition of a flag indicating if the index is spatial
+ActiveRecord::ConnectionAdapters::IndexDefinition.class_eval do
+  attr_accessor :spatial
+
+  def initialize(table, name, unique, spatial,columns)
+    super(table,name,unique,columns)
+    @spatial = spatial
+  end
+
+end
+
+ActiveRecord::SchemaDumper.class_eval do
+  def table(table, stream)
+
+    columns = @connection.columns(table)
+    begin
+      tbl = StringIO.new
+
+      if @connection.respond_to?(:pk_and_sequence_for)
+        pk, pk_seq = @connection.pk_and_sequence_for(table)
+      end
+      pk ||= 'id'
+
+      tbl.print "  create_table #{table.inspect}"
+      if columns.detect { |c| c.name == pk }
+        if pk != 'id'
+          tbl.print %Q(, :primary_key => "#{pk}")
+        end
+      else
+        tbl.print ", :id => false"
+      end
+
+      if @connection.respond_to?(:options_for)
+        res = @connection.options_for(table)
+        tbl.print ", :options=>'#{res}'" if res
+      end
+
+      tbl.print ", :force => true"
+      tbl.puts " do |t|"
+
+      columns.each do |column|
+
+        raise StandardError, "Unknown type '#{column.sql_type}' for column '#{column.name}'" if @types[column.type].nil?
+        next if column.name == pk
+        #need to use less_simplified_type  here or have each specific geometry type be simplified to a specific simplified type in Column and each one treated separately in the Column methods
+        if column.is_a?(SpatialColumn)
+          tbl.print "    t.column #{column.name.inspect}, #{column.geometry_type.inspect}"
+          tbl.print ", :srid => #{column.srid.inspect}" if column.srid != -1
+          tbl.print ", :with_z => #{column.with_z.inspect}" if column.with_z
+          tbl.print ", :with_m => #{column.with_m.inspect}" if column.with_m
+        else
+          tbl.print "    t.column #{column.name.inspect}, #{column.type.inspect}"
+        end
+        tbl.print ", :limit => #{column.limit.inspect}" if column.limit != @types[column.type][:limit] && column.precision.blank? && column.scale.blank?
+        tbl.print ", :precision => #{column.precision.inspect}" if column.precision != @types[column.type][:precision]
+        tbl.print ", :scale => #{column.scale.inspect}" if column.scale != @types[column.type][:scale]
+        tbl.print ", :default => #{default_string(column.default)}" if !column.default.nil?
+        tbl.print ", :null => false" if !column.null
+        tbl.puts
+      end
+
+      tbl.puts "  end"
+      tbl.puts
+      indexes(table, tbl)
+      tbl.rewind
+      stream.print tbl.read
+    rescue => e
+      stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
+      stream.puts "#   #{e.message} #{e.backtrace}"
+      stream.puts
+    end
+
+    stream  end
+
+  def indexes(table, stream)
+    indexes = @connection.indexes(table)
+    indexes.each do |index|
+      stream.print "  add_index #{index.table.inspect}, #{index.columns.inspect}, :name => #{index.name.inspect}"
+      stream.print ", :unique => true" if index.unique
+      stream.print ", :spatial=> true " if index.spatial
+      stream.puts
+    end
+
+    stream.puts unless indexes.empty?
+  end
+end
+
+
+
+
+module SpatialAdapter
+  #Translation of geometric data types
+  def geometry_data_types
+    {
+      :point => { :name => "POINT" },
+      :line_string => { :name => "LINESTRING" },
+      :polygon => { :name => "POLYGON" },
+      :geometry_collection => { :name => "GEOMETRYCOLLECTION" },
+      :multi_point => { :name => "MULTIPOINT" },
+      :multi_line_string => { :name => "MULTILINESTRING" },
+      :multi_polygon => { :name => "MULTIPOLYGON" },
+      :geometry => { :name => "GEOMETRY"}
+    }
+  end
+
+end
+
+
+#using a mixin instead of subclassing Column since each adapter can have a specific subclass of Column
+module SpatialColumn
+  attr_reader  :geometry_type, :srid, :with_z, :with_m
+
+  def initialize(name, default, sql_type = nil, null = true,srid=-1,with_z=false,with_m=false)
+    super(name,default,sql_type,null)
+    @geometry_type = geometry_simplified_type(@sql_type)
+    @srid = srid
+    @with_z = with_z
+    @with_m = with_m
+  end
+
+
+  #Redefines type_cast to add support for geometries
+  def type_cast(value)
+    return nil if value.nil?
+    case type
+    when :geometry then self.class.string_to_geometry(value)
+    else super
+    end
+  end
+
+  #Redefines type_cast_code to add support for geometries.
+  #
+  #WARNING : Since ActiveRecord keeps only the string values directly returned from the database, it translates from these to the correct types everytime an attribute is read (using the code returned by this method), which is probably ok for simple types, but might be less than efficient for geometries. Also you cannot modify the geometry object returned directly or your change will not be saved.
+  def type_cast_code(var_name)
+    case type
+    when :geometry then "#{self.class.name}.string_to_geometry(#{var_name})"
+    else super
+    end
+  end
+
+
+  #Redefines klass to add support for geometries
+  def klass
+    case type
+    when :geometry then GeoRuby::SimpleFeatures::Geometry
+    else super
+    end
+  end
+
+  private
+
+  #Redefines the simplified_type method to add behaviour for when a column is of type geometry
+  def simplified_type(field_type)
+    case field_type
+    when /geometry|point|linestring|polygon|multipoint|multilinestring|multipolygon|geometrycollection/i then :geometry
+    else super
+    end
+  end
+
+  #less simlpified geometric type to be use in migrations
+  def geometry_simplified_type(field_type)
+    case field_type
+    when /^point$/i then :point
+    when /^linestring$/i then :line_string
+    when /^polygon$/i then :polygon
+    when /^geometry$/i then :geometry
+    when /multipoint/i then :multi_point
+    when /multilinestring/i then :multi_line_string
+    when /multipolygon/i then :multi_polygon
+    when /geometrycollection/i then :geometry_collection
+    end
+  end
+
+
+end