activerecord-spatial 0.0.1

data/lib/activerecord-spatial/active_record/models/geography_column.rb

@@ -0,0 +1,17 @@
+
+module ActiveRecordSpatial
+  class GeographyColumn < ActiveRecord::Base
+    include SpatialColumn
+
+    self.table_name = 'geography_columns'
+
+    def spatial_type
+      :geography
+    end
+
+    def spatial_column
+      self.f_geography_column
+    end
+  end
+end
+

data/lib/activerecord-spatial/active_record/models/geometry_column.rb

@@ -0,0 +1,17 @@
+
+module ActiveRecordSpatial
+  class GeometryColumn < ActiveRecord::Base
+    include SpatialColumn
+
+    self.table_name = 'geometry_columns'
+
+    def spatial_type
+      :geometry
+    end
+
+    def spatial_column
+      self.f_geometry_column
+    end
+  end
+end
+

data/lib/activerecord-spatial/active_record/models/spatial_column.rb

@@ -0,0 +1,22 @@
+
+module ActiveRecordSpatial
+  module SpatialColumn #:nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      self.primary_key = nil
+
+      # PostGIS inserts a "type" column into these tables/views that can
+      # really mess things up good.
+      self.inheritance_column = 'nonexistent_column_name_type'
+
+      belongs_to :spatial_ref_sys,
+        :foreign_key => :srid
+    end
+
+    def readonly?
+      true
+    end
+  end
+end
+

data/lib/activerecord-spatial/active_record/models/spatial_ref_sys.rb

@@ -0,0 +1,20 @@
+
+module ActiveRecordSpatial
+  class SpatialRefSys < ::ActiveRecord::Base
+    self.table_name = 'spatial_ref_sys'
+    self.primary_key = 'srid'
+
+    has_many :geometry_columns,
+      :foreign_key => :srid,
+      :inverse_of => :spatial_ref_sys
+
+    has_many :geography_columns,
+      :foreign_key => :srid,
+      :inverse_of => :spatial_ref_sys
+
+    def spatial_columns
+      self.geometry_columns + self.geography_columns
+    end
+  end
+end
+

data/lib/activerecord-spatial/associations.rb

@@ -0,0 +1,292 @@
+
+module ActiveRecord
+  module Associations #:nodoc:
+    class SpatialAssociation < HasManyAssociation
+      attr_reader :geom, :foreign_geom, :relationship, :scope_options
+
+      def initialize(*args)
+        super
+
+        @geom = self.options[:geom]
+        @foreign_geom = self.options[:foreign_geom]
+        @relationship = self.options[:relationship].to_s
+        @scope_options = (self.options[:scope_options] || {}).merge({
+          :column => @foreign_geom
+        })
+      end
+    end
+
+    class Builder::Spatial < Builder::HasMany #:nodoc:
+      self.macro = :has_many
+
+      self.valid_options += [
+        :geom, :foreign_geom, :relationship, :scope_options
+      ]
+
+      self.valid_options -= [
+        :through, :source, :source_type, :dependent, :finder_sql, :counter_sql,
+        :inverse_of
+      ]
+
+      private
+        def dependency_method_name
+          "spatially_#{self.relationship}_dependent_for_#{name}"
+        end
+    end
+
+    class Preloader #:nodoc:
+      class SpatialAssociation < HasMany #:nodoc:
+        SPATIAL_FIELD_ALIAS = '__spatial_ids__'
+        SPATIAL_JOIN_NAME = '__spatial_ids_join__'
+        SPATIAL_JOIN_QUOTED_NAME = %{"#{SPATIAL_JOIN_NAME}"}
+
+        def records_for(ids)
+          table_name = reflection.quoted_table_name
+          join_name = model.quoted_table_name
+          column = %{#{SPATIAL_JOIN_QUOTED_NAME}.#{model.quoted_primary_key}}
+          geom = {
+            :class => model,
+            :table_alias => SPATIAL_JOIN_NAME
+          }
+
+          if reflection.options[:geom].is_a?(Hash)
+            geom.merge!(reflection.options[:geom])
+          else
+            geom[:column] = reflection.options[:geom]
+          end
+
+          scoped.
+            select(%{array_to_string(array_agg(#{column}), ',') AS "#{SPATIAL_FIELD_ALIAS}"}).
+            joins(
+              "INNER JOIN #{join_name} AS #{SPATIAL_JOIN_QUOTED_NAME} ON (" <<
+                klass.send("st_#{reflection.options[:relationship]}",
+                  geom,
+                  (reflection.options[:scope_options] || {}).merge(
+                    :column => reflection.options[:foreign_geom]
+                  )
+                ).where_values.join(' AND ') <<
+              ")"
+            ).
+            where(model.arel_table.alias(SPATIAL_JOIN_NAME)[model.primary_key].in(ids)).
+            group(table[klass.primary_key])
+        end
+
+        private
+
+        def associated_records_by_owner
+          owners_map = owners_by_key
+          owner_keys = owners_map.keys.compact
+
+          if klass.nil? || owner_keys.empty?
+            records = []
+          else
+            sliced  = owner_keys.each_slice(model.connection.in_clause_length || owner_keys.size)
+            records = sliced.map { |slice| records_for(slice) }.flatten
+          end
+
+          records_by_owner = Hash[owners.map { |owner| [owner, []] }]
+
+          records.each do |record|
+            record[SPATIAL_FIELD_ALIAS].split(',').each do |owner_key|
+              owners_map[owner_key].each do |owner|
+                records_by_owner[owner] << record
+              end
+            end
+          end
+
+          records_by_owner
+        end
+      end
+
+      def preloader_for_with_spatial(reflection)
+        if reflection.options[:relationship]
+          SpatialAssociation
+        else
+          preloader_for_without_spatial(reflection)
+        end
+      end
+      alias_method_chain :preloader_for, :spatial
+    end
+
+    class AssociationScope #:nodoc:
+      def add_constraints_with_spatial(scope)
+        return add_constraints_without_spatial(scope) if !self.association.is_a?(SpatialAssociation)
+
+        tables = construct_tables
+
+        chain.each_with_index do |reflection, i|
+          table, foreign_table = tables.shift, tables.first
+
+          conditions = self.conditions[i]
+          geom_options = {
+            :class => self.association.klass
+          }
+
+          if self.association.geom.is_a?(Hash)
+            geom_options.merge!(
+              :value => owner[self.association.geom[:name]]
+            )
+            geom_options.merge!(self.association.geom)
+          else
+            geom_options.merge!(
+              :value => owner[self.association.geom],
+              :name => self.association.geom
+            )
+          end
+
+          if reflection == chain.last
+            scope = scope.send("st_#{self.association.relationship}", geom_options, self.association.scope_options)
+
+            if reflection.type
+              scope = scope.where(table[reflection.type].eq(owner.class.base_class.name))
+            end
+
+            conditions.each do |condition|
+              scope = scope.where(interpolate(condition))
+            end
+          else
+            constraint = scope.where(
+              scope.send(
+                "st_#{self.association.relationship}",
+                owner[self.association.foreign_geom],
+                self.association.scope_options
+              ).where_values
+            ).join(' AND ')
+
+            if reflection.type
+              type = chain[i + 1].klass.base_class.name
+              constraint = table[reflection.type].eq(type).and(constraint)
+            end
+
+            scope = scope.joins(join(foreign_table, constraint))
+
+            unless conditions.empty?
+              scope = scope.where(sanitize(conditions, table))
+            end
+          end
+        end
+
+        scope
+      end
+      alias_method_chain :add_constraints, :spatial
+    end
+  end
+
+  module Reflection #:nodoc:
+    class AssociationReflection < MacroReflection #:nodoc:
+      def association_class_with_spatial
+        if self.options[:relationship]
+           Associations::SpatialAssociation
+        else
+          association_class_without_spatial
+        end
+      end
+      alias_method_chain :association_class, :spatial
+    end
+  end
+end
+
+# ActiveRecord Spatial associations allow for +has_many+-style associations
+# using spatial relationships.
+#
+# == Example
+#
+#   class Neighbourhood < ActiveRecord::Base
+#     has_many_spatially :cities,
+#       :relationship => :contains
+#   end
+#
+#   class City < ActiveRecord::Base
+#     has_many_spatially :neighbourhoods,
+#       :relationship => :within
+#   end
+#
+#   Neighbourhood.first.cities
+#   #=> All cities that the neighbourhood is within
+#
+#   City.first.neighbourhoods
+#   #=> All neighbourhoods contained by the city
+#
+#   City.includes(:neighbourhoods).first.neighbourhoods
+#   #=> Eager loading works too
+#
+# Spatial associations can be set up using any of the relationships found in
+# ActiveRecordSpatial::SpatialScopes::RELATIONSHIPS.
+#
+# == Options
+#
+# Many of the options available with standard +has_many+ associations will work
+# with the exceptions of +:through+, +:source+, +:source_type+, +:dependent+,
+# +:finder_sql+, +:counter_sql+, and +:inverse_of+.
+#
+# Polymorphic relationships can be used via the +:as+ option as in standard
+# +:has_many+ relationships. Note that the default field for the geometry
+# in these cases is "#{association_name}_geom" and can be overridden using
+# the +:foreign_geom+ option.
+#
+# * +:relationship+ - sets the spatial relationship for the association.
+#   Valid options can be found in ActiveRecordSpatial::SpatialScopes::RELATIONSHIPS.
+#   The default value is +:intersects+.
+# * +:geom+ - sets the geometry field for the association in the calling model.
+#   The default value is +:the_geom+ as is often seen in PostGIS documentation.
+# * +:foreign_geom+ - sets the geometry field for the association's foreign
+#   table. The default here is again +:the_geom+.
+# * +:scope_options+ - these are options passed directly to the SpatialScopes
+#   module and as such the options are the same as are available there. The
+#   default value here is <tt>{ :invert => true }</tt>, as we want our
+#   spatial relationships to say "Foo spatially contains many Bars" and
+#   therefore the relationship in SQL becomes
+#   <tt>ST_contains("foos"."the_geom", "bars"."the_geom")</tt>.
+#
+# Note that you can modify the default geometry column name for all of
+# ActiveRecordSpatial by setting it via ActiveRecordSpatia.default_column_name.
+#
+# == Caveats
+#
+# * You should consider spatial associations to be essentially readonly. Since
+#   we're not dealing with unique IDs here but rather 2D and 3D geometries,
+#   the relationships between rows don't really map well to the traditional
+#   foreign key-style ActiveRecord associations.
+module ActiveRecordSpatial::Associations
+  extend ActiveSupport::Concern
+
+  DEFAULT_OPTIONS = {
+    :relationship => :intersects,
+    :geom => ActiveRecordSpatial.default_column_name,
+    :foreign_geom => ActiveRecordSpatial.default_column_name,
+    :scope_options => {
+      :invert => true
+    }
+  }.freeze
+
+  module ClassMethods #:nodoc:
+    def has_many_spatially(name, options = {}, &extension)
+      options = build_options(options)
+
+      if !ActiveRecordSpatial::SpatialScopeConstants::RELATIONSHIPS.include?(options[:relationship].to_s)
+        raise ArgumentError.new(%{Invalid spatial relationship "#{options[:relationship]}", expected one of #{ActiveRecordSpatial::SpatialScopeConstants::RELATIONSHIPS.inspect}})
+      end
+
+      ActiveRecord::Associations::Builder::Spatial.build(self, name, options, &extension)
+    end
+
+    def build_options(options)
+      if !options[:foreign_geom] && options[:as]
+        options[:foreign_geom] = "#{options[:as]}_geom"
+      end
+
+      if options[:geom].is_a?(Hash)
+        options[:geom][:name] ||= ActiveRecordSpatial.default_column_name
+      end
+
+      DEFAULT_OPTIONS.deep_merge(options)
+    end
+    private :build_options
+  end
+end
+
+module ActiveRecord
+  class Base #:nodoc:
+    include ActiveRecordSpatial::Associations
+  end
+end

data/lib/activerecord-spatial/spatial_columns.rb

@@ -0,0 +1,345 @@
+
+module ActiveRecordSpatial
+  # This little module helps us out with geometry columns. At least, in
+  # PostgreSQL it does.
+  #
+  # This module will add a method called spatial_columns to your model
+  # which will contain information that can be gleaned from the
+  # geometry_columns and geography_columns tables/views that PostGIS creates.
+  #
+  # You can also have the module automagically create some accessor
+  # methods for you to make your life easier. These accessor methods will
+  # override the ActiveRecord defaults and allow you to set geometry
+  # column values using Geos geometry objects directly or with
+  # PostGIS-style extended WKT and such. See
+  # create_spatial_column_accessors! for details.
+  module SpatialColumns
+    extend ActiveSupport::Concern
+
+    SPATIAL_COLUMN_OUTPUT_FORMATS = %w{ geos wkt wkb ewkt ewkb wkb_bin ewkb_bin }.freeze
+
+    class InvalidGeometry < ::ActiveRecord::ActiveRecordError
+      def initialize(geom)
+        super("Invalid geometry: #{geom}")
+      end
+    end
+
+    class SRIDNotFound < ::ActiveRecord::ActiveRecordError
+      def initialize(table_name, column)
+        super("Couldn't find SRID for #{table_name}.#{column}")
+      end
+    end
+
+    class CantConvertSRID < ::ActiveRecord::ActiveRecordError
+      def initialize(table_name, column, from_srid, to_srid)
+        super("Couldn't convert SRID for #{table_name}.#{column} from #{from_srid} to #{to_srid}")
+      end
+    end
+
+    module ClassMethods
+      protected
+        @geometry_columns = nil
+        @geography_columns = nil
+
+      public
+        # Build call to ActiveRecordSpatial::SpatialFunction.build! that helps
+        # you create spatial function calls.
+        def spatial_function(*args)
+          SpatialFunction.build!(self, *args)
+        end
+
+        # Stubs for documentation purposes:
+
+        # Returns an Array of available geometry columns in the
+        # table. These are PostgreSQLColumns with values set for
+        # the srid and coord_dimensions properties.
+        def geometry_columns; end
+
+        # Returns an Array of available geography columns in the
+        # table. These are PostgreSQLColumns with values set for
+        # the srid and coord_dimensions properties.
+        def geography_columns; end
+
+        # Force a reload of available geometry columns.
+        def geometry_columns!; end
+
+        # Force a reload of available geography columns.
+        def geography_columns!; end
+
+        # Grabs a geometry column based on name.
+        def geometry_column_by_name(name); end
+
+        # Grabs a geography column based on name.
+        def geography_column_by_name(name); end
+
+        # Returns both the geometry and geography columns for a table.
+        def spatial_columns
+          self.geometry_columns + self.geography_columns
+        end
+
+        # Reloads both the geometry and geography columns for a table.
+        def spatial_columns!
+          self.geometry_columns! + self.geography_columns!
+        end
+
+        # Grabs a spatial column based on name.
+        def spatial_column_by_name(name)
+          self.geometry_column_by_name(name) || self.geography_column_by_name(name)
+        end
+
+        %w{ geometry geography }.each do |m|
+          src, line = <<-EOF, __LINE__ + 1
+            undef :#{m}_columns
+            def #{m}_columns
+              if !defined?(@#{m}_columns) || @#{m}_columns.nil?
+                @#{m}_columns = ActiveRecordSpatial::#{m.capitalize}Column.where(
+                  :f_table_name => self.table_name
+                ).all
+                @#{m}_columns.freeze
+              end
+              @#{m}_columns
+            end
+
+            undef :#{m}_columns!
+            def #{m}_columns!
+              @#{m}_columns = nil
+              #{m}_columns
+            end
+
+            undef :#{m}_column_by_name
+            def #{m}_column_by_name(name)
+              @#{m}_column_by_name ||= self.#{m}_columns.inject(HashWithIndifferentAccess.new) do |memo, obj|
+                memo[obj.spatial_column] = obj
+                memo
+              end
+              @#{m}_column_by_name[name]
+            end
+          EOF
+          self.class_eval(src, __FILE__, line)
+        end
+
+        # Quickly grab the SRID for a geometry column.
+        def srid_for(column_name)
+          column = self.spatial_column_by_name(column_name)
+          column.try(:srid) || ActiveRecordSpatial::UNKNOWN_SRID
+        end
+
+        # Quickly grab the number of dimensions for a geometry column.
+        def coord_dimension_for(column_name)
+          self.spatial_column_by_name(column_name).coord_dimension
+        end
+
+      protected
+        # Sets up nifty setters and getters for spatial columns.
+        # The methods created look like this:
+        #
+        # * spatial_column_name_geos
+        # * spatial_column_name_wkb
+        # * spatial_column_name_wkb_bin
+        # * spatial_column_name_wkt
+        # * spatial_column_name_ewkb
+        # * spatial_column_name_ewkb_bin
+        # * spatial_column_name_ewkt
+        # * spatial_column_name=(geom)
+        # * spatial_column_name(options = {})
+        #
+        # Where "spatial_column_name" is the name of the actual
+        # column.
+        #
+        # You can specify which spatial columns you want to apply
+        # these accessors using the :only and :except options.
+        def create_spatial_column_accessors!(options = nil)
+          create_these = []
+
+          if options.nil?
+            create_these.concat(self.spatial_columns)
+          else
+            if options[:geometry_columns]
+              create_these.concat(self.geometry_columns)
+            end
+
+            if options[:geography_columns]
+              create_these.concat(self.geography_columns)
+            end
+
+            if options[:except] && options[:only]
+              raise ArgumentError, "You can only specify either :except or :only (#{options.keys.inspect})"
+            elsif options[:except]
+              except = Array.wrap(options[:except]).collect(&:to_s)
+              create_these.reject! { |c| except.include?(c) }
+            elsif options[:only]
+              only = Array.wrap(options[:only]).collect(&:to_s)
+              create_these.select! { |c| only.include?(c) }
+            end
+          end
+
+          create_these.each do |k|
+            src, line = <<-EOF, __LINE__ + 1
+              def #{k.spatial_column}=(geom)
+                if !geom
+                  self['#{k.spatial_column}'] = nil
+                else
+                  column = self.class.spatial_column_by_name(#{k.spatial_column.inspect})
+
+                  if geom =~ /^SRID=default;/i
+                    geom = geom.sub(/default/i, column.srid.to_s)
+                  end
+
+                  geos = Geos.read(geom)
+
+                  if column.spatial_type != :geography
+                    geom_srid = if geos.srid == 0 || geos.srid == -1
+                      ActiveRecordSpatial::UNKNOWN_SRIDS[column.spatial_type]
+                    else
+                      geos.srid
+                    end
+
+                    if column.srid != geom_srid
+                      if column.srid == ActiveRecordSpatial::UNKNOWN_SRIDS[column.spatial_type] || geom_srid == ActiveRecordSpatial::UNKNOWN_SRIDS[column.spatial_type]
+                        geos.srid = column.srid
+                      else
+                        raise CantConvertSRID.new(self.class.table_name, #{k.spatial_column.inspect}, geom_srid, column.srid)
+                      end
+                    end
+
+                    self['#{k.spatial_column}'] = geos.to_ewkb
+                  else
+                    self['#{k.spatial_column}'] = geos.to_wkb
+                  end
+                end
+
+                SPATIAL_COLUMN_OUTPUT_FORMATS.each do |f|
+                  instance_variable_set("@#{k.spatial_column}_\#{f}", nil)
+                end
+              end
+
+              def #{k.spatial_column}_geos
+                @#{k.spatial_column}_geos ||= Geos.from_wkb(self['#{k.spatial_column}'])
+              end
+
+              def #{k.spatial_column}(options = {})
+                format = case options
+                  when String, Symbol
+                    options
+                  when Hash
+                    options = options.stringify_keys
+                    options['format'] if options['format']
+                end
+
+                if format
+                  if SPATIAL_COLUMN_OUTPUT_FORMATS.include?(format)
+                    return self.send(:"#{k.spatial_column}_\#{format}")
+                  else
+                    raise ArgumentError, "Invalid option: \#{options[:format]}"
+                  end
+                end
+
+                self['#{k.spatial_column}']
+              end
+            EOF
+            self.class_eval(src, __FILE__, line)
+
+            SPATIAL_COLUMN_OUTPUT_FORMATS.reject { |f| f == 'geos' }.each do |f|
+              src, line = <<-EOF, __LINE__ + 1
+                def #{k.spatial_column}_#{f}(*args)
+                  @#{k.spatial_column}_#{f} ||= self.#{k.spatial_column}_geos.to_#{f}(*args) rescue nil
+                end
+              EOF
+              self.class_eval(src, __FILE__, line)
+            end
+          end
+        end
+
+        # Creates column accessors for geometry columns only.
+        def create_geometry_column_accessors!(options = {})
+          options = {
+            :geometry_columns => true
+          }.merge(options)
+
+          create_spatial_column_accessors!(options)
+        end
+
+        # Creates column accessors for geometry columns only.
+        def create_geography_column_accessors!(options = {})
+          options = {
+            :geography_columns => true
+          }.merge(options)
+
+          create_spatial_column_accessors!(options)
+        end
+
+        # Stubs for documentation purposes:
+
+        # Returns a Geos::Geometry object.
+        def __spatial_column_name_geos; end
+
+        # Returns a hex-encoded WKB String.
+        def __spatial_column_name_wkb; end
+
+        # Returns a WKB String in binary.
+        def __spatial_column_name_wkb_bin; end
+
+        # Returns a WKT String.
+        def __spatial_column_name_wkt; end
+
+        # Returns a hex-encoded EWKB String.
+        def __spatial_column_name_ewkb; end
+
+        # Returns an EWKB String in binary.
+        def __spatial_column_name_ewkb_bin; end
+
+        # Returns an EWKT String.
+        def __spatial_column_name_ewkt; end
+
+        # An enhanced setter that tries to deduce how you're
+        # setting the value. The setter can handle Geos::Geometry
+        # objects, WKT, EWKT and WKB and EWKB in both hex and
+        # binary.
+        #
+        # When dealing with SRIDs, you can have the SRID set
+        # automatically on WKT by setting the value as
+        # "SRID=default;GEOMETRY(...)", i.e.:
+        #
+        #  spatial_column_name = "SRID=default;POINT(1.0 1.0)"
+        #
+        # The SRID will be filled in automatically if available.
+        # Note that we're only setting the SRID on the geometry,
+        # but we're not doing any sort of re-projection or anything
+        # of the sort. If you need to convert from one SRID to
+        # another, you're stuck for the moment, but we'll be adding
+        # support for reprojections/transoformations via proj4rb
+        # soon.
+        #
+        # For WKB, you're better off manipulating the WKB directly
+        # or using proper Geos geometry objects.
+        def __spatial_column_name=(geom); end
+
+        # An enhanced getter that accepts an options Hash or
+        # String/Symbol that can be used to determine the output
+        # format. In the options Hash, use :format, or set the
+        # format directly as a String or Symbol.
+        #
+        # This basically allows you to do the following, which
+        # are equivalent:
+        #
+        #  spatial_column_name(:wkt)
+        #  spatial_column_name(:format => :wkt)
+        #  spatial_column_name_wkt
+        def __spatial_column_name(options = {}); end
+
+        undef __spatial_column_name_geos
+        undef __spatial_column_name_wkb
+        undef __spatial_column_name_wkb_bin
+        undef __spatial_column_name_wkt
+        undef __spatial_column_name_ewkb
+        undef __spatial_column_name_ewkb_bin
+        undef __spatial_column_name_ewkt
+
+        undef __spatial_column_name=
+        undef __spatial_column_name
+    end
+  end
+
+  # Alias for backwards compatibility.
+  GeometryColumns = SpatialColumns
+end