mongoid_geospatial 2.3.0 → 2.5.0

data/README.md

@@ -3,7 +3,6 @@ Mongoid Geospatial
 
 A Mongoid Extension that simplifies the use of MongoDB spatial features.
 
-
 ** On beta again **
 
 Removing some trash, improving and adding support for RGeo and GeoRuby.
@@ -25,98 +24,26 @@ You can also use an external Geometric/Spatial alongside.
     # Gemfile
     gem 'mongoid_geospatial'
 
-
     # A place to illustrate Point, Line and Polygon
     class Place
       include Mongoid::Document
+
+      # Include the module
       include Mongoid::Geospatial
 
+	  # Just like mongoid,
       field :name,     type: String
+	  # define your field, but choose a geometry type:
       field :location, type: Point, :spatial => true
       field :route,    type: Linestring
       field :area,     type: Polygon
+	  
+	  # If your are going to query on your points, don't forget to index:
+	  spatial_index :location
+	  
     end
 
 
-Geometry Helpers
-----------------
-
-We currently support GeoRuby and RGeo.
-If you require one of those, a #to_geo method will be available to all
-spatial fields, returning the external library corresponding object.
-To illustrate:
-
-    class Person
-      include Mongoid::Document
-      include Mongoid::Geospatial
-
-      field :location, type: Point
-    end
-
-    me = Person.new(location: [8, 8])
-
-    # Example with GeoRuby
-    point.class # Mongoid::Geospatial::Point
-    point.to_geo.class # GeoRuby::SimpleFeatures::Point
-
-    # Example with RGeo
-    point.class # Mongoid::Geospatial::Point
-    point.to_geo.class # RGeo::Geographic::SphericalPointImpl
-
-
-Configure
-----------------
-
-Assemble it as you need (use a initializer file):
-
-With RGeo
-
-    Mongoid::Geospatial.use_rgeo
-    # Optional
-    # Mongoid::Geospatial.factory = RGeo::Geographic.spherical_factory
-
-With GeoRuby
-
-    Mongoid::Geospatial.use_georuby
-
-Defaults (change if you know what you're doing)
-
-    Mongoid::Geospatial.lng_symbol = :x
-    Mongoid::Geospatial.lat_symbol = :y
-    Mongoid::Geospatial.earth_radius = EARTH_RADIUS
-
-
-
-Model Setup
------------
-
-You can create Point, Line, Circle, Box and Polygon on your models:
-
-
-    class River
-      include Mongoid::Document
-      include Mongoid::Geospatial
-
-      field :name,              type: String
-      field :length,            type: Integer
-      field :discharge,         type: Integer
-
-      field :source,            type: Point,    spatial: true
-      field :mouth,             type: Point,    spatial: true
-      field :course,            type: Line
-      field :boundings,         type: Box
-
-      # spatial indexing
-      spatial_index :mouth
-
-      # default mongodb options
-      spatial_index :mouth, {bit: 24, min: -180, max: 180}
-    end
-
-
-Use
----
-
 Generate indexes on MongoDB:
 
 
@@ -126,6 +53,10 @@ Generate indexes on MongoDB:
 Points
 ------
 
+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:
+
 * an unordered hash with the lat long string keys defined when setting the field (only applies for setting the field)
 * 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)
@@ -150,10 +81,18 @@ We store data in the DB as a [lng,lat] array then reformat when it is returned t
 Now to access this spatial information we can do this
 
     hudson.mouth  # => [-74.026667, 40.703056]
+	
+If you need a hash
+
+    hudson.mouth.to_hsh  # => { x: -74.026667, y: 40.703056 }
+	
+If you are using GeoRuby or RGeo
+
+    hudson.mouth.to_geo  # => NiceGeolib::Point
 
 Distance and other geometrical calculations are delegated to the external
 library you choosed. More info about using RGeo or GeoRuby below.
-Some built in helpers:
+Some built in helpers for mongoid queries:
 
     # Returns middle point + radius
     # Useful to search #within_circle
@@ -165,6 +104,12 @@ Some built in helpers:
     hudson.mounth.to_hsh(:lon, :lat)  # {:lon => -74.., :lat => 40..}
 
 
+And for polygons and lines:
+
+	house.area.bbox    # Returns polygon bounding_box (envelope)
+	house.area.center  # Returns calculate middle point
+	
+
 Query
 --------
 
@@ -178,30 +123,150 @@ All MongoDB queries are handled by Mongoid.
 You can use Geometry instance directly on any query:
 
 * near
+  * Bar.near(location: person.house)
   * Bar.where(:location.near => person.house)
+  
 
 * near_sphere
+  * Bar.near_sphere(location: person.house)
   * Bar.where(:location.near_sphere => person.house)
 
+
 * within_box
-  * Bar.where(:location.within_box => hood.area)
+  * Bar.within_box(location: hood.area)
+  
 
 * within_circle
-  * Bar.where(:location.within_box => hood.area)
+  * Bar.within_circle(location: hood.area)
+  
 
 * within_circle_sphere
-  * Bar.where(:location.within_circle_sphere => hood.area)
+  * Bar.within_circle_sphere(location: hood.area)
+  
 
 * within_polygon
-  * Bar.where(:location.within_polygon => city.area)
+  * Bar.within_polygon(location: city.area)
+
+
+External Libraries
+------------------
+
+Use 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.
+It'll require more stuff installed to compile/work.
+
+
+Use GeoRuby?
+https://github.com/nofxx/geo_ruby
+
+GeoRuby is a pure Ruby Geometry Library.
+It's perfect if you want simple calculations and/or keep your stack in pure ruby.
+Albeit not full featured in maths it has a handful of methods and good import/export helpers.
+
+Use Nothing?
+
+This lib won't stand in your way.
+Write your own wrapper if you want.
+
+
+Geometry Helpers
+----------------
+
+We currently support GeoRuby and RGeo.
+If you require one of those, a #to_geo method will be available to all
+spatial fields, returning the external library corresponding object.
+To illustrate:
+
+    class Person
+      include Mongoid::Document
+      include Mongoid::Geospatial
+
+      field :location, type: Point
+    end
+
+    me = Person.new(location: [8, 8])
+
+    # Example with GeoRuby
+    point.class # Mongoid::Geospatial::Point
+    point.to_geo.class # GeoRuby::SimpleFeatures::Point
+
+    # Example with RGeo
+    point.class # Mongoid::Geospatial::Point
+    point.to_geo.class # RGeo::Geographic::SphericalPointImpl
+
+
+Configure
+----------------
+
+Assemble it as you need (use a initializer file):
+
+With RGeo
+
+    Mongoid::Geospatial.use_rgeo
+    # Optional
+    # Mongoid::Geospatial.factory = RGeo::Geographic.spherical_factory
+
+
+With GeoRuby
+
+    Mongoid::Geospatial.use_georuby
+	
+
+Defaults (change if you know what you're doing)
+
+    Mongoid::Geospatial.lng_symbol = :x
+    Mongoid::Geospatial.lat_symbol = :y
+    Mongoid::Geospatial.earth_radius = EARTH_RADIUS
+
+
+
+Model Setup
+-----------
+
+You can create Point, Line, Circle, Box and Polygon on your models:
+
+
+    class CrazyGeom
+      include Mongoid::Document
+      include Mongoid::Geospatial
+
+      field :location,     type: Point
+
+      field :route,        type: Line
+      field :area,         type: Polygon
+     
+	  field :square,       type: Box
+	  field :around,       type: Circle
+    
+      # spatial indexing
+      spatial_index :mouth
+
+      # default mongodb options
+      spatial_index :mouth, {bit: 24, min: -180, max: 180}
+	  
+	  # query by location
+	  spatial_scope :location	  
+    end
+
+
+
+Nearby
+------
 
+You can add a `spatial_scope` on your models. So you can query:
 
-Class Methods
--------------
+    Bar.nearby(my.location)
+	
+instead of
 
-Some method are added to your class when you define a field as spatial.
+    Bar.near(location: my.location)
+	
+Good when you're drunk. Just add to your model:
 
-    field :location, type: Point, spatial: true
+    spatial_scope :<field>
 
 
 

data/lib/mongoid_geospatial/fields/geometry_field.rb

@@ -25,8 +25,8 @@ module Mongoid
         [center, r]
       end
 
-      def radius_sphere r = 1
-        [center, r.to_f/Mongoid::Geospatial.earth_radius[:km]]
+      def radius_sphere r = 1, unit = :km
+        radius r.to_f/Mongoid::Geospatial.earth_radius[unit]
       end
 
 

data/lib/mongoid_geospatial/fields/point.rb

@@ -1,6 +1,7 @@
 module Mongoid
   module Geospatial
     class Point
+      include Enumerable
       attr_accessor :x, :y
 
       def initialize(x=nil, y=nil)
@@ -18,6 +19,11 @@ module Mongoid
         mongoize[args]
       end
 
+      def each
+        yield x
+        yield y
+      end
+
       def to_hsh xl = :x, yl = :y
         {xl => x, yl => y}
       end
@@ -58,7 +64,7 @@ module Mongoid
 
         # Database -> Object
         def demongoize(object)
-          # return unless object && !object.empty?
+          return unless object
           Point.new(*object)
         end
 

data/lib/mongoid_geospatial/geospatial.rb

@@ -26,7 +26,7 @@ module Mongoid
     @@earth_radius = EARTH_RADIUS.dup
 
     included do
-      attr_accessor :geo
+      # attr_accessor :geo
       cattr_accessor :spatial_fields, :spatial_fields_indexed
       @@spatial_fields = []
       @@spatial_fields_indexed = []
@@ -51,6 +51,15 @@ module Mongoid
         index({name => '2d'}, options)
       end
 
+      def spatial_scope field, opts = {}
+        self.singleton_class.class_eval do
+          # define_method(:close) do |args|
+          define_method(:nearby) do |args|
+            queryable.where(field.near_sphere => args)
+          end
+        end
+      end
+
     end
 
   end

data/lib/mongoid_geospatial/version.rb

@@ -1,5 +1,5 @@
 module Mongoid
   module Geospatial
-    VERSION = "2.3.0"
+    VERSION = "2.5.0"
   end
 end

data/spec/models/bar.rb

@@ -8,4 +8,6 @@ class Bar
   has_one :rating, :as => :ratable
 
   spatial_index :location
+  spatial_scope :location
+
 end

data/spec/mongoid_geospatial/field_option_spec.rb

@@ -3,9 +3,14 @@ require "spec_helper"
 describe Mongoid::Fields do
 
   context "spatial" do
+    before do
+      Bar.create_indexes
+    end
 
     it "should set some class methods" do
-      Bar.near_location([1,1]).should eq([])
+      far  = Bar.create!(name: "Far", location: [7,7])
+      near = Bar.create!(name: "Near", location: [2,2])
+      Bar.nearby([1,1]).should eq([near, far])
     end
 
   end

data/spec/mongoid_geospatial/fields/box_spec.rb

@@ -0,0 +1,11 @@
+require "spec_helper"
+
+describe Mongoid::Geospatial::Box do
+
+  it "should work" do
+    alarm = Alarm.new(area: [[1,2], [3,4]])
+    alarm.area.should be_a Mongoid::Geospatial::Box
+  end
+
+
+end

data/spec/mongoid_geospatial/fields/point_spec.rb

@@ -9,7 +9,14 @@ describe Mongoid::Geospatial::Point do
 
   it "should not fail if point is nil" do
     bar = Bar.create!(name: "Moe's")
-    bar.location.x.should be_nil
+    bar.location.should be_nil
+  end
+
+  it "should set point to nil" do
+    bar = Bar.create!(name: "Moe's", location: [1, 1])
+    bar.location = nil
+    bar.location.should be_nil
+    bar.save.should be_true
   end
 
   describe "methods" do
@@ -36,6 +43,14 @@ describe Mongoid::Geospatial::Point do
       bar.location.radius_sphere[1].should be_within(0.0001).of(0.00015)
     end
 
+    it "should have a radius sphere helper in meters" do
+      bar.location.radius_sphere(1000, :m)[1].should be_within(0.0001).of(0.00015)
+    end
+
+    it "should have a radius sphere helper in miles" do
+      bar.location.radius_sphere(1, :mi)[1].should be_within(0.0001).of(0.00025)
+    end
+
   end
 
   describe "queryable" do
@@ -66,6 +81,15 @@ describe Mongoid::Geospatial::Point do
         Bar.where(:location.near => jim.location).should == [ paris, prague, berlin ]
       end
 
+      it "returns the documents sorted closest to furthest" do
+        Bar.near(location: jim.location).should == [ paris, prague, berlin ]
+      end
+
+      it "returns the documents sorted closest to furthest sphere" do
+        person = Person.new(:location => [ 41.23, 2.9 ])
+        Bar.near_sphere(location: jim.location).should == [ paris, prague, berlin ]
+      end
+
       it "returns the documents sorted closest to furthest sphere" do
         person = Person.new(:location => [ 41.23, 2.9 ])
         Bar.where(:location.near_sphere => jim.location).should == [ paris, prague, berlin ]
@@ -113,6 +137,11 @@ describe Mongoid::Geospatial::Point do
       it "returns the documents within a center_sphere" do
         Bar.where(:location.within_spherical_circle => [elvis.location, 0.5]).to_a.should include(mile9)
       end
+
+      it "returns the documents within a box" do
+        Bar.within_box(location: [elvis.location, elvis.location.map(&:ceil)]).to_a.should == [ mile3 ]
+      end
+
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid_geospatial
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-13 00:00:00.000000000 Z
+date: 2012-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rgeo
@@ -181,6 +181,7 @@ files:
 - spec/models/river.rb
 - spec/mongoid_geospatial/extensions/core_ext_spec.rb
 - spec/mongoid_geospatial/field_option_spec.rb
+- spec/mongoid_geospatial/fields/box_spec.rb
 - spec/mongoid_geospatial/fields/circle_spec.rb
 - spec/mongoid_geospatial/fields/line_spec.rb
 - spec/mongoid_geospatial/fields/point_spec.rb
@@ -227,6 +228,7 @@ test_files:
 - spec/models/river.rb
 - spec/mongoid_geospatial/extensions/core_ext_spec.rb
 - spec/mongoid_geospatial/field_option_spec.rb
+- spec/mongoid_geospatial/fields/box_spec.rb
 - spec/mongoid_geospatial/fields/circle_spec.rb
 - spec/mongoid_geospatial/fields/line_spec.rb
 - spec/mongoid_geospatial/fields/point_spec.rb