mongoid-geospatial 7.0.0 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c175628dbf99da911bb81c3c25b2665b3547506f910366a53d43eaabea99e410
-  data.tar.gz: 8e38f228cc16e9a17cbe44dd2be01bd06e989d5e91d968a9b50a1885cc12eb8e
+  metadata.gz: 4bc532f8201a1c7c0f43c63d051a073dd5658ab8ffa561ea852e14a0fcf1c243
+  data.tar.gz: 9af8f1e4e1ef5f2514e3214f5e0bc66c0f56fbb7e9a1cbdf3fd152e89b11cbad
 SHA512:
-  metadata.gz: a09b65028e7d0b27a88383dac691372e6b456ad0d72b3ef0159e8e9e33d7f6da78cb250038c6d592bbb667d9a6f6f864ac1ae8278eaed41b69277d0290a47399
-  data.tar.gz: 843567a6bbe62c5551cd962c70a927e2dd8e19968c741ea014e384cf942b99aa75fa382969fe139cc07c835249fb7d864421713cb5e324e0495615fc14b7d30e
+  metadata.gz: 154e488426770257945cd93d36138d238d5b1bf75e308b62b568ba897f9835f921faf26d50f14e71c9f3f43f0ce9be761586f228a788819a0ed7f2662274fbc3
+  data.tar.gz: 1fbd1713b7121edc2bc8f171a5cf66f63befc5668369d1f833d0be1d0783844bb41ffdf62e618172324e15bb2cfb4e905a3cd91896ec9b7d28a46142a06b6769

data/README.md

@@ -46,6 +46,14 @@ class Place
 end
 ```
 
+A pin named `geom` on a 2dsphere index is one include:
+
+```ruby
+include Mongoid::Geospatial::Geom   # field :geom, type: Point, sphere: true
+# or a named one:
+geom :pick_up
+```
+
 Generate indexes on MongoDB via rake:
 
 ```
@@ -94,6 +102,15 @@ If you need a hash
 cafe.location.to_hsh   # => { x: -74.026667, y: 40.703056 }
 ```
 
+Commonly used
+
+```ruby
+cafe.location.to_lat_lon   # => { lat: 40.703056, lon: -74.026667 }
+cafe.location.lat          # => 40.703056
+cafe.location.lng          # => -74.026667
+cafe.location.distance(other) # => km, haversine
+```
+
 If you are using GeoRuby or RGeo
 
 ```ruby
@@ -108,7 +125,7 @@ This lib uses #x and #y everywhere.
 It's shorter than lat or lng or another variation that also confuses.
 A point is a 2D mathematical notation, longitude/latitude is when you use that notation to map an sphere. In other words: all longitudes are 'xs' where not all 'xs' are longitudes.
 
-Distance and other geometrical calculations are delegated to the external library of your choice. More info about using RGeo or GeoRuby below. Some built in helpers for mongoid queries:
+Distance is `Point#distance` (haversine, km). Projections and heavier geometry still go to RGeo or GeoRuby. Some built in helpers for mongoid queries:
 
 ```ruby
 # Returns middle point + radius
@@ -176,26 +193,6 @@ field :location,  type: Point, delegate: true
 
 Now instead of `instance.location.x` you may call `instance.x`.
 
-## Nearby
-
-You can add a `spatial_scope` on your models. So you can query:
-
-```ruby
-Bar.nearby(my.location)
-```
-
-instead of
-
-```ruby
-Bar.near(location: my.location)
-```
-
-Good when you're drunk. Just add to your model:
-
-```ruby
-spatial_scope :<field>
-```
-
 ## Geometry
 
 You can also store Circle, Box, Line (LineString) and Polygons.
@@ -219,30 +216,95 @@ polygon.radius_sphere(5) # [[1.0, 1.0], 0.00048..]
 
 ## Query
 
-Before you proceed, make sure you have read this:
-
-http://mongoid.github.io/old/en/origin/docs/selection.html#standard
-
-All MongoDB queries are handled by Mongoid/Origin.
-
-http://www.rubydoc.info/github/mongoid/origin/Origin/Selectable
-
 You can use Geometry instance directly on any query:
 
-- near
+### near
 
 ```ruby
 Bar.near(location: person.house)
 Bar.where(:location.near => person.house)
 ```
 
-- near_sphere
+### near_sphere
 
 ```ruby
 Bar.near_sphere(location: person.house)
 Bar.where(:location.near_sphere => person.house)
 ```
 
+### nearby / within
+
+```ruby
+Bar.nearby(person.house)
+Bar.nearby(person.house, km: 30)
+Bar.within(person.house, 30)          # same question, km required
+City.where(:geom.near_sphere => Mongoid::Geospatial.near_query(geom, 50))
+```
+
+`within` is `$nearSphere` + `$maxDistance` in metres. Nearest first, chainable.
+
+**Don't call `#first` or `#last` on a `$near` criteria.** Mongoid sorts by
+`_id` when a criteria carries no sort of its own, and that replaces the
+distance order Mongo put there. Walk the criteria instead — `.to_a.first` —
+or use `geo_near`, which returns the distance as a field you can sort on.
+
+You can add a `spatial_scope` on your models. So you can query:
+
+```ruby
+Bar.nearby(my.location)
+```
+
+instead of
+
+```ruby
+Bar.near(location: my.location)
+```
+
+Good when you're drunk. Just add to your model:
+
+```ruby
+spatial_scope :<field>
+```
+
+### geo_near
+
+The `geo_near` class method provides a more powerful way to query for documents based on proximity,
+using MongoDB's `$geoNear` aggregation pipeline stage. This method allows for more complex
+options and returns the distance to each matched document.
+
+```ruby
+# Find places near [10, 20], using spherical calculations, up to 5km away,
+# and get the distance.
+# The :distanceField option specifies the name of the field that will contain the distance.
+# The :limit option is applied as a separate $limit stage in the aggregation.
+Place.geo_near(:location, [10, 20],
+               spherical: true,
+               maxDistance: 5000, # 5 kilometers in meters for spherical queries
+               distanceField: 'dist.calculated', # Default is 'distance'
+               query: { category: 'restaurant' }, # Optional: filter documents before geoNear
+               limit: 10)
+
+# Iterate over results
+Place.geo_near(:location, [10, 20], spherical: true).each do |place|
+  # 'place.distance' will be available if distanceField was 'distance' (the default)
+  # or 'place.dist_calculated' if distanceField was 'dist.calculated'
+  puts "#{place.name} is #{place.distance || place.dist_calculated} meters away."
+end
+```
+
+Key features and options for `geo_near`:
+
+- `:spherical` (Boolean): If `true`, calculates distances using spherical geometry. Defaults to `false`.
+- `:distanceField` (String): Name of the output field for the calculated distance. Defaults to `'distance'`.
+- `:maxDistance` (Numeric): Maximum distance from the center point. (Meters for spherical, units of coordinates for planar).
+- `:minDistance` (Numeric): Minimum distance from the center point.
+- `:query` (Hash): A query to filter documents _before_ the `$geoNear` stage.
+- `:limit` (Integer): Maximum number of documents to return (applied as a separate `$limit` stage).
+- `:distanceMultiplier` (Numeric): A factor to multiply all distances.
+- `:includeLocs` (String): Name of an output field that will contain the exact location on the document used for the distance calculation. Useful for multi-location fields or complex GeoJSON geometries.
+
+The `geo_near` method returns an array of instantiated Mongoid documents, with the `distanceField` and `includeLocs` field (if specified) available as dynamic attributes on each model instance.
+
 - within_polygon
 
 ```ruby
@@ -251,6 +313,20 @@ Bar.within_polygon(location: [[[x,y],...[x,y]]])
 Bar.within_polygon(location: street.bbox)
 ```
 
+- within_circle / within_spherical_circle
+
+Mongoid ships `within_polygon` and `within_box` and stopped there; this gem
+registers the two circle shapes, which is what `radius` and `radius_sphere`
+have been building arguments for all along.
+
+```ruby
+Bar.where(:location.within_spherical_circle => cafe.location.radius_sphere(5, :km))
+Bar.where(:location.within_circle => cafe.location.radius(0.05))  # degrees, flat
+```
+
+`$centerSphere` reads radians (`radius_sphere` hands it those); `$center`
+reads the coordinate system's own units — degrees on a legacy pair.
+
 - intersects_line
 - intersects_point
 - intersects_polygon
@@ -264,7 +340,7 @@ external library corresponding object.
 
 ### Use RGeo?
 
-https://github.com/dazuma/rgeo
+<https://github.com/dazuma/rgeo>
 
 RGeo is a Ruby wrapper for Proj/GEOS.
 It's perfect when you need to work with complex calculations and projections.
@@ -272,7 +348,7 @@ It'll require more stuff installed to compile/work.
 
 ### Use GeoRuby?
 
-https://github.com/nofxx/georuby
+<https://github.com/nofxx/georuby>
 
 GeoRuby is a pure Ruby Geometry Library.
 It's perfect if you want simple calculations and/or keep your stack in pure ruby.

data/lib/mongoid/geospatial/config/point.rb

@@ -1,17 +1,20 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     module Config
       module Point
         extend self
 
-        attr_accessor :x
-        attr_accessor :y
+        attr_accessor :x, :y
 
         def reset!
+          # Now self.x and self.y refer to the public module accessors
           self.x = Mongoid::Geospatial.lng_symbols
           self.y = Mongoid::Geospatial.lat_symbols
         end
 
+        # Initialize the configuration
         reset!
       end
     end

data/lib/mongoid/geospatial/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     module Config

data/lib/mongoid/geospatial/ext/rgeo_spherical_point_impl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RGeo
   module Geographic
     # RGeo Point

data/lib/mongoid/geospatial/fields/box.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     class Box < GeometryField

data/lib/mongoid/geospatial/fields/circle.rb

@@ -1,10 +1,10 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     # Circle
     #
     class Circle < GeometryField
-      attr_accessor :center, :radius
-
       def center
         Point.new(*self[0])
       end

data/lib/mongoid/geospatial/fields/line_string.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     class LineString < GeometryField

data/lib/mongoid/geospatial/fields/point.rb

@@ -1,15 +1,24 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     # Point
     #
-    class Point
+    class Point # rubocop:disable Metrics/ClassLength
       include Enumerable
-      attr_accessor :x, :y, :z
 
-      def initialize(x, y, z = nil)
-        @x = x
-        @y = y
-        @z = z
+      attr_accessor :x, :y, :z
+      alias lng x
+      alias lon x
+      alias lat y
+      alias lng= x=
+      alias lon= x=
+      alias lat= y=
+
+      def initialize(lon, lat, alt = nil)
+        @x = lon
+        @y = lat
+        @z = alt
       end
 
       # Object -> Database
@@ -23,6 +32,7 @@ module Mongoid
       end
       alias to_a mongoize
       alias to_xy mongoize
+      alias to_lng_lat mongoize
 
       def [](args)
         mongoize[args]
@@ -33,23 +43,13 @@ module Mongoid
         yield y
       end
 
-      #
-      # Point representation as a Hash
-      #
-      # @return [Hash] with { xl => x, yl => y }
-      #
-      def to_hsh(xl = :x, yl = :y)
-        { xl => x, yl => y }
-      end
-      alias to_hash to_hsh
-
       #
       # Helper for [self, radius]
       #
       # @return [Array] with [self, radius]
       #
-      def radius(r = 1)
-        [ mongoize, r ]
+      def radius(r = 1) # rubocop:disable Naming/MethodParameterName
+        [mongoize, r]
       end
 
       #
@@ -59,7 +59,7 @@ module Mongoid
       #
       # @return [Array] with [self, radius / earth radius]
       #
-      def radius_sphere(r = 1, unit = :km)
+      def radius_sphere(r = 1, unit = :km) # rubocop:disable Naming/MethodParameterName
         radius r.to_f / Mongoid::Geospatial.earth_radius[unit]
       end
 
@@ -85,6 +85,26 @@ module Mongoid
         "#{x}, #{y}"
       end
 
+      #
+      # Point representation as a Hash
+      # Optional param: custom keys.
+      #
+      # @return [Hash] with { lng_key => x, lat_key => y }
+      #
+      def to_hsh(xkey = :x, ykey = :y)
+        { xkey => x, ykey => y }
+      end
+      alias to_hash to_hsh
+
+      #
+      # Point representation more commonly used
+      # Latitude, Longitude
+      #
+      # @return [Hash] with { latitude: y, longitude: x }
+      def to_lat_lon
+        { latitude: y, longitude: x }
+      end
+
       #
       # Point definition as GeoJSON
       #
@@ -94,7 +114,7 @@ module Mongoid
       #
       def to_geo_json
         # Return a GeoJSON point hash that MongoDB can use
-        { type: "Point", coordinates: [x, y] }
+        { type: 'Point', coordinates: [x, y] }
       end
 
       #
@@ -110,32 +130,21 @@ module Mongoid
       end
 
       #
-      # Distance calculation methods. Thinking about not using it
-      # One needs to choose and external lib. GeoRuby or RGeo
-      #
-      # Return the distance between the 2D points (ie taking care
-      # only of the x and y coordinates), assuming the points are
-      # in projected coordinates. Euclidian distance in whatever
-      # unit the x and y ordinates are.
-      # def euclidian_distance(point)
-      #   Math.sqrt((point.x - x)**2 + (point.y - y)**2)
-      # end
-
-      # # Spherical distance in meters, using 'Haversine' formula.
-      # # with a radius of 6471000m
-      # # Assumes x is the lon and y the lat, in degrees (Changed
-      # in version 1.1).
-      # # The user has to make sure using this distance makes sense
-      # (ie she should be in latlon coordinates)
-      # def spherical_distance(point,r=6370997.0)
-      #   dlat = (point.lat - lat) * DEG2RAD / 2
-      #   dlon = (point.lon - lon) * DEG2RAD / 2
-
-      #   a = Math.sin(dlat)**2 + Math.cos(lat * DEG2RAD) *
-      #         Math.cos(point.lat * DEG2RAD) * Math.sin(dlon)**2
-      #   c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
-      #   r * c
-      # end
+      # Crow-flies distance. Haversine, Mongo's earth radius (6371 km).
+      # RGeo/GeoRuby still win for projections; this is ETA and "how far".
+      #
+      def distance(other, unit = :km) # rubocop:disable Metrics/AbcSize
+        xy = other.is_a?(Point) ? [other.x, other.y] : self.class.mongoize(other)
+        raise ArgumentError, "Invalid point: #{other.inspect}" unless xy
+
+        dlat = (xy[1] - y) * RAD_PER_DEG
+        dlon = (xy[0] - x) * RAD_PER_DEG
+        a = (Math.sin(dlat / 2)**2) +
+            (Math.cos(y * RAD_PER_DEG) * Math.cos(xy[1] * RAD_PER_DEG) *
+             (Math.sin(dlon / 2)**2))
+        c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+        Mongoid::Geospatial.earth_radius[unit] * c
+      end
 
       class << self
         #
@@ -237,7 +246,7 @@ module Mongoid
 
           raise "Hash must contain #{Mongoid::Geospatial::Config::Point.x.inspect}"
         end
-      end # << self
-    end # Point
-  end # Geospatial
-end # Mongoid
+      end
+    end
+  end
+end

data/lib/mongoid/geospatial/fields/polygon.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     class Polygon < GeometryField

data/lib/mongoid/geospatial/geometry_field.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     #
@@ -63,7 +65,7 @@ module Mongoid
       # @param [Numeric] r radius
       # @return [Array]  [point, r] point and radius in mongoid format
       #
-      def radius(r = 1)
+      def radius(r = 1) # rubocop:disable Naming/MethodParameterName
         [center, r]
       end
 
@@ -75,7 +77,7 @@ module Mongoid
       # @see Point#radius
       # @return [Array]
       #
-      def radius_sphere(r = 1, unit = :km)
+      def radius_sphere(r = 1, unit = :km) # rubocop:disable Naming/MethodParameterName
         radius r.to_f / Mongoid::Geospatial.earth_radius[unit]
       end
 

data/lib/mongoid/geospatial/helpers/delegate.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #
 # Mongoid fields extension
 #

data/lib/mongoid/geospatial/helpers/geom.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Geospatial
+    #
+    # The pin, named `geom`, on a 2dsphere index.
+    #
+    module Geom
+      extend ActiveSupport::Concern
+
+      included do
+        include Mongoid::Geospatial
+
+        geom
+      end
+
+      def located?
+        geom.present?
+      end
+    end
+  end
+end

data/lib/mongoid/geospatial/helpers/spatial.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #
 # Mongoid fields extension
 #

data/lib/mongoid/geospatial/helpers/sphere.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #
 # Mongoid fields extension
 #

data/lib/mongoid/geospatial/keys.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+#
+# `$geoWithin` with a circle. Mongoid ships `within_polygon` and `within_box`
+# and stopped there — the two circle shapes left with Origin, and `Point#radius`
+# / `#radius_sphere` have been building their argument ever since.
+#
+#   Bar.where(:location.within_circle => elvis.location.radius(0.05))
+#   Bar.where(:location.within_spherical_circle => elvis.location.radius_sphere(5, :km))
+#
+# `$center` reads its radius in the coordinate system's own units (degrees, for
+# a legacy pair); `$centerSphere` reads radians, which is what `radius_sphere`
+# returns. Guarded: if Mongoid ever registers these, its own wins.
+#
+%i[within_circle within_spherical_circle].each do |name|
+  next if Symbol.method_defined?(name)
+
+  operator = name == :within_circle ? '$center' : '$centerSphere'
+  Symbol.add_key(name, :override, '$geoWithin', operator)
+end

data/lib/mongoid/geospatial/version.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Mongoid
   # Mongoid Geospatial version
   module Geospatial
-    VERSION = '7.0.0'.freeze
+    VERSION = '7.2.0'
   end
 end

data/lib/mongoid/geospatial/wrappers/georuby.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'geo_ruby'
 
 module Mongoid

data/lib/mongoid/geospatial/wrappers/rgeo.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rgeo'
 require 'mongoid/geospatial/ext/rgeo_spherical_point_impl'