mongoid-geospatial 5.1.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c947554ea1c07198ca1c8b7c649ed93464fd1a08c6c71a2b2752e826344f049
-  data.tar.gz: 49d2636d235a0b91671564db6807241a4600d40070089e3d2729dd598151b2d2
+  metadata.gz: 88d807a8e7011846e353f18fc6812fb55e578f371464c202fa726976c7fec6e6
+  data.tar.gz: 32f5124231bfe558a9a591520c90dda408f76995faa2030e67c39bee1e9f7b23
 SHA512:
-  metadata.gz: 8da975f59a71106fc991043f1438f5c7c910e1e7c2cc78f7e112062bee9fc34a966ecf80a39ec423230805aa6756f0c01e5882085fb5e701618b0ec7d4d6b6f5
-  data.tar.gz: 8c8c89eec0397d1a0e3bcae04ca972ef5b3aa82094d76b4b060c53c2bb6dbc4eb058bc80cfb0d9c5b5fbb7b217aaed973212b98193247c3cfe079fb5de67a489
+  metadata.gz: f8beb1650724d7b54d7a2a35d2376597144d9290360f2571da28681ef11d3e3e0792bf562f0c904f762b0abaf09d43b9f8c8f1747cb4d7753a5f187a6c6d04c5
+  data.tar.gz: b457c28c88ab87968e76eeb00afca6e376e37cf2432df230fc88260ab44b9984c9cd11708deba53eb19fa4a19d27175d63042c5b142762707fe3bd1019107652

data/README.md

@@ -1,5 +1,4 @@
-Mongoid Geospatial
-==================
+# Mongoid Geospatial
 
 A Mongoid Extension that simplifies the use of MongoDB spatial features.
 
@@ -8,8 +7,7 @@ A Mongoid Extension that simplifies the use of MongoDB spatial features.
 [![Coverage Status](https://coveralls.io/repos/github/mongoid/mongoid-geospatial/badge.svg?branch=master)](https://coveralls.io/github/mongoid/mongoid-geospatial?branch=master)
 [![Build Status](https://travis-ci.org/mongoid/mongoid-geospatial.svg?branch=master)](https://travis-ci.org/mongoid/mongoid-geospatial)
 
-Quick Start
------------
+## Quick Start
 
 This gem focuses on (making helpers for) MongoDB's spatial features using Mongoid 5, 6 and 7.
 
@@ -60,17 +58,16 @@ Or programatically:
 Place.create_indexes
 ```
 
-Points
-------
+## Points
 
 This gem defines a specific `Point` class under the Mongoid::Geospatial namespace. Make sure to use `type: ::Mongoid::Geospatial::Point` to avoid name errors or collisions with other `Point` classes you might already have defined `NameError`s.
 
 Currently, MongoDB supports query operations on 2D points only, so that's what this lib does. All geometries apart from points are just arrays in the database. Here's is how you can input a point as:
 
-* longitude latitude array in that order - [long,lat] ([x, y])
-* an unordered hash with latitude key(:lat, :latitude) and a longitude key(:lon, :long, :lng, :longitude)
-* an ordered hash with longitude as the first item and latitude as the second item; this hash does not have include the latitude and longitude keys
-* anything with the a method #to_xy or #to_lng_lat that converts itself to  [long, lat] array
+- longitude latitude array in that order - [long,lat] ([x, y])
+- an unordered hash with latitude key(:lat, :latitude) and a longitude key(:lon, :long, :lng, :longitude)
+- an ordered hash with longitude as the first item and latitude as the second item; this hash does not have include the latitude and longitude keys
+- anything with the a method #to_xy or #to_lng_lat that converts itself to [long, lat] array
 
 _Note: the convention of having longitude as the first coordinate may vary for other libraries. For instance, Google Maps often refer to "LatLng". Make sure you keep those differences in mind. See below for how to configure this library for LatLng._
 
@@ -131,8 +128,7 @@ house.area.bbox    # Returns polygon bounding_box (envelope)
 house.area.center  # Returns calculate middle point
 ```
 
-Model Setup
------------
+## Model Setup
 
 You can create Point, Line, Circle, Box and Polygon on your models:
 
@@ -157,8 +153,7 @@ class CrazyGeom
 end
 ```
 
-Helpers
--------
+## Helpers
 
 You can use `spatial: true` to add a '2d' index automatically,
 No need for `spatial_index :location`:
@@ -181,29 +176,7 @@ 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
---------
+## Geometry
 
 You can also store Circle, Box, Line (LineString) and Polygons.
 Some helper methods are available to them:
@@ -224,34 +197,84 @@ polygon.radius(5)        # [[1.0, 1.0], 5]
 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
+## Query
 
 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)
 ```
 
-* within_polygon
+### 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>
+```
+
+### 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
 Bar.within_polygon(location: [[[x,y],...[x,y]]])
@@ -259,13 +282,11 @@ Bar.within_polygon(location: [[[x,y],...[x,y]]])
 Bar.within_polygon(location: street.bbox)
 ```
 
-* intersects_line
-* intersects_point
-* intersects_polygon
-
+- intersects_line
+- intersects_point
+- intersects_polygon
 
-External Libraries
-------------------
+## External Libraries
 
 We currently support GeoRuby and RGeo.
 If you require one of those, a #to_geo and #to_rgeo, respectivelly,
@@ -338,8 +359,7 @@ end
 
 You will need to manually migrate any existing `Point` data if you change configuration in an existing system.
 
-This Fork
----------
+## This Fork
 
 This fork is not backwards compatible with 'mongoid_spacial'.
 This fork delegates calculations to external libs.
@@ -370,8 +390,7 @@ field :source,  type: Point,    spatial: true # or sphere: true
 
 Beware the 't' and 'c' issue. It's spaTial.
 
-Troubleshooting
----------------
+## Troubleshooting
 
 **Mongo::OperationFailure: can't find special index: 2d**
 
@@ -387,15 +406,12 @@ Programatically
 Model.create_indexes
 ```
 
-Contributing
-------------
+## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
-License
--------
+## License
 
 Copyright (c) 2009-2017 Mongoid Geospatial Authors
 
 MIT License, see [MIT-LICENSE](MIT-LICENSE).
-

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,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Geospatial
     # Point
@@ -6,10 +8,10 @@ module Mongoid
       include Enumerable
       attr_accessor :x, :y, :z
 
-      def initialize(x, y, z = nil)
-        @x = x
-        @y = y
-        @z = z
+      def initialize(lon, lat, alt = nil)
+        @x = lon
+        @y = lat
+        @z = alt
       end
 
       # Object -> Database
@@ -35,11 +37,12 @@ module Mongoid
 
       #
       # Point representation as a Hash
+      # Optional param: custom keys.
       #
-      # @return [Hash] with { xl => x, yl => y }
+      # @return [Hash] with { lng_key => x, lat_key => y }
       #
-      def to_hsh(xl = :x, yl = :y)
-        { xl => x, yl => y }
+      def to_hsh(xkey = :x, ykey = :y)
+        { xkey => x, ykey => y }
       end
       alias to_hash to_hsh
 
@@ -48,7 +51,7 @@ module Mongoid
       #
       # @return [Array] with [self, radius]
       #
-      def radius(r = 1)
+      def radius(r = 1) # rubocop:disable Naming/MethodParameterName
         [mongoize, r]
       end
 
@@ -59,7 +62,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 +88,18 @@ module Mongoid
         "#{x}, #{y}"
       end
 
+      #
+      # Point definition as GeoJSON
+      #
+      # "x, y"
+      #
+      # @return [String] Point as comma separated String
+      #
+      def to_geo_json
+        # Return a GeoJSON point hash that MongoDB can use
+        { type: 'Point', coordinates: [x, y] }
+      end
+
       #
       # Point inverse/reverse
       #
@@ -225,7 +240,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/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
 #
@@ -11,6 +13,6 @@ Mongoid::Fields.option :sphere do |model, field, _options|
     spatial_fields_indexed << field.name.to_sym
 
     # Create 2Dsphere index
-    sphere_index field.name
+    spherical_index field.name
   end
 end

data/lib/mongoid/geospatial/version.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Mongoid
   # Mongoid Geospatial version
   module Geospatial
-    VERSION = '5.1.0'.freeze
+    VERSION = '7.1.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'