mongoid-geospatial 7.1.0 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88d807a8e7011846e353f18fc6812fb55e578f371464c202fa726976c7fec6e6
-  data.tar.gz: 32f5124231bfe558a9a591520c90dda408f76995faa2030e67c39bee1e9f7b23
+  metadata.gz: 4bc532f8201a1c7c0f43c63d051a073dd5658ab8ffa561ea852e14a0fcf1c243
+  data.tar.gz: 9af8f1e4e1ef5f2514e3214f5e0bc66c0f56fbb7e9a1cbdf3fd152e89b11cbad
 SHA512:
-  metadata.gz: f8beb1650724d7b54d7a2a35d2376597144d9290360f2571da28681ef11d3e3e0792bf562f0c904f762b0abaf09d43b9f8c8f1747cb4d7753a5f187a6c6d04c5
-  data.tar.gz: b457c28c88ab87968e76eeb00afca6e376e37cf2432df230fc88260ab44b9984c9cd11708deba53eb19fa4a19d27175d63042c5b142762707fe3bd1019107652
+  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
@@ -215,7 +232,21 @@ Bar.near_sphere(location: person.house)
 Bar.where(:location.near_sphere => person.house)
 ```
 
-### nearby
+### 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:
 
@@ -282,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
@@ -295,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.
@@ -303,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/fields/point.rb

@@ -4,9 +4,16 @@ module Mongoid
   module Geospatial
     # Point
     #
-    class Point
+    class Point # rubocop:disable Metrics/ClassLength
       include Enumerable
+
       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
@@ -25,6 +32,7 @@ module Mongoid
       end
       alias to_a mongoize
       alias to_xy mongoize
+      alias to_lng_lat mongoize
 
       def [](args)
         mongoize[args]
@@ -35,17 +43,6 @@ module Mongoid
         yield 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
-
       #
       # Helper for [self, radius]
       #
@@ -88,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
       #
@@ -113,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
         #

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/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

@@ -3,6 +3,6 @@
 module Mongoid
   # Mongoid Geospatial version
   module Geospatial
-    VERSION = '7.1.0'
+    VERSION = '7.2.0'
   end
 end

data/lib/mongoid/geospatial.rb

@@ -5,6 +5,8 @@ require 'active_support/concern' # Explicitly require for `extend ActiveSupport:
 require 'mongoid/geospatial/helpers/spatial'
 require 'mongoid/geospatial/helpers/sphere'
 require 'mongoid/geospatial/helpers/delegate'
+require 'mongoid/geospatial/helpers/geom'
+require 'mongoid/geospatial/keys'
 
 module Mongoid
   #
@@ -69,6 +71,27 @@ module Mongoid
       require 'mongoid/geospatial/wrappers/georuby'
     end
 
+    #
+    # A [lng, lat] pair, or nothing. `Point.mongoize` is lenient — it reads
+    # "nowhere" as [0.0] — and a half pair is a query Mongo cannot answer.
+    #
+    def self.mongoize_point!(geom)
+      coords = Point.mongoize(geom)
+      unless coords.is_a?(Array) && coords.size == 2 && coords.all?(Numeric)
+        raise ArgumentError, "Invalid coordinates: #{geom.inspect}"
+      end
+
+      coords
+    end
+
+    #
+    # Selector for `$nearSphere` with a km cap. Metres on the wire.
+    #
+    def self.near_query(geom, km) # rubocop:disable Naming/MethodParameterName
+      { '$geometry' => { 'type' => 'Point', 'coordinates' => mongoize_point!(geom) },
+        '$maxDistance' => km * 1_000 }
+    end
+
     # Methods applied to Document's class
     module ClassMethods
       #
@@ -92,6 +115,14 @@ module Mongoid
         spatial_fields_indexed << name
         index({ name => '2dsphere' }, options)
       end
+      alias sphere_index spherical_index
+
+      #
+      # A Point on a 2dsphere index. Default name is `geom`.
+      #
+      def geom(name = :geom)
+        field name, type: Point, sphere: true
+      end
 
       #
       # # Queries
@@ -201,15 +232,15 @@ module Mongoid
       #
       # @param coordinates [Array, Mongoid::Geospatial::Point] The coordinates (e.g., [lon, lat])
       #   or a Point object to find documents near to.
-      # @param _options [Hash] Optional hash for future extensions (currently unused).
+      # @param km [Numeric, nil] Optional cap in kilometres (`$maxDistance` in metres).
       #
       # @return [Mongoid::Criteria] A criteria object for the query.
       #
       # Example:
       #   Bar.nearby([10, 20])
-      #   Alarm.nearby(my_point_object)
+      #   Alarm.nearby(my_point_object, km: 30)
       #
-      def nearby(coordinates, _options = {})
+      def nearby(coordinates, km: nil, **_opts) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Naming/MethodParameterName
         if spatial_fields.empty?
           raise "No spatial fields defined for #{name} to use with .nearby. " \
                 "Mark a field with 'spatial: true' or 'sphere: true'."
@@ -220,9 +251,22 @@ module Mongoid
 
         raise "Could not find field definition for spatial field: #{field_name_sym}" unless field_definition
 
-        query_operator = field_definition.options[:sphere] ? :near_sphere : :near
+        if km
+          # GeoJSON `$maxDistance` is metres. `$near` on a 2d index is radians.
+          query = Mongoid::Geospatial.near_query(coordinates, km)
+          criteria.where(field_name_sym.near_sphere => query)
+        else
+          query_operator = field_definition.options[:sphere] ? :near_sphere : :near
+          criteria.where(field_name_sym.send(query_operator) => coordinates)
+        end
+      end
 
-        criteria.where(field_name_sym.send(query_operator) => coordinates)
+      #
+      # Documents within +km+ of +geom+, nearest first.
+      # `$nearSphere` + `$maxDistance` in metres.
+      #
+      def within(geom, km) # rubocop:disable Naming/MethodParameterName
+        nearby(geom, km: km)
       end
 
       # Performs a $geoNear aggregation pipeline stage to find documents near a point,
@@ -274,14 +318,20 @@ module Mongoid
       #   end
       #
       def geo_near(field_name, coordinates, options = {})
-        mongoized_coords = Mongoid::Geospatial::Point.mongoize(coordinates)
-
-        raise ArgumentError, "Invalid coordinates provided: #{coordinates.inspect}" unless mongoized_coords
+        mongoized_coords = Mongoid::Geospatial.mongoize_point!(coordinates)
 
         # User-provided options. Work with a copy.
         user_options = options.dup
         limit_value = user_options.delete(:limit) # Handled by a separate pipeline stage
 
+        # `km:` is metres on the wire, and metres only holds for a GeoJSON
+        # `near` on a sphere. A legacy pair would read `maxDistance` in radians.
+        if (km = user_options.delete(:km))
+          user_options[:maxDistance] = km.to_f * 1_000
+          user_options[:spherical] = true
+          mongoized_coords = { 'type' => 'Point', 'coordinates' => mongoized_coords }
+        end
+
         # Core $geoNear parameters derived from method arguments, these are not overrideable by user_options.
         geo_near_core_params = {
           key: field_name.to_s,
@@ -297,10 +347,8 @@ module Mongoid
         # Merge user options over defaults, then ensure core parameters are set.
         geo_near_stage_options = geo_near_defaultable_params.merge(user_options).merge(geo_near_core_params)
 
-        # Ensure :spherical is a strict boolean (true/false).
-        # If user_options provided :spherical, it's already set. If not, the default is used.
-        # This line ensures the final value is strictly true or false, not just truthy/falsy.
-        geo_near_stage_options[:spherical] = !geo_near_stage_options[:spherical].nil?
+        # $geoNear wants a strict boolean, and honours the caller's choice.
+        geo_near_stage_options[:spherical] = geo_near_stage_options[:spherical] ? true : false
 
         # Note on performance:
         # $geoNear is an aggregation pipeline stage. For simple proximity queries,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-geospatial
 version: !ruby/object:Gem::Version
-  version: 7.1.0
+  version: 7.2.0
 platform: ruby
 authors:
 - Ryan Ong
@@ -45,8 +45,10 @@ files:
 - lib/mongoid/geospatial/fields/polygon.rb
 - lib/mongoid/geospatial/geometry_field.rb
 - lib/mongoid/geospatial/helpers/delegate.rb
+- lib/mongoid/geospatial/helpers/geom.rb
 - lib/mongoid/geospatial/helpers/spatial.rb
 - lib/mongoid/geospatial/helpers/sphere.rb
+- lib/mongoid/geospatial/keys.rb
 - lib/mongoid/geospatial/version.rb
 - lib/mongoid/geospatial/wrappers/georuby.rb
 - lib/mongoid/geospatial/wrappers/rgeo.rb