README.md in mongoid_geospatial-2.2.0 vs README.md in mongoid_geospatial-2.3.0
- old
+ new
@@ -24,11 +24,11 @@
# Gemfile
gem 'mongoid_geospatial'
- # A place to illustrate Point, LineString and Polygon
+ # A place to illustrate Point, Line and Polygon
class Place
include Mongoid::Document
include Mongoid::Geospatial
field :name, type: String
@@ -65,11 +65,11 @@
Configure
----------------
-Assemble it as you need:
+Assemble it as you need (use a initializer file):
With RGeo
Mongoid::Geospatial.use_rgeo
# Optional
@@ -88,111 +88,149 @@
Model Setup
-----------
-You can create Point, LineString and Polygon on your models:
+You can create Point, Line, Circle, Box and Polygon on your models:
-```ruby
-class River
- include Mongoid::Document
- include Mongoid::Geospatial
+ class River
+ include Mongoid::Document
+ include Mongoid::Geospatial
- field :name, type: String
- field :length, type: Integer
- field :average_discharge, type: Integer
- field :source, type: Point, spatial: true
+ field :name, type: String
+ field :length, type: Integer
+ field :discharge, type: Integer
- # set return_array to true if you do not want a hash returned all the time
- field :mouth, type: Point, spatial: {lat: :latitude, lng: :longitude, return_array: true }
- field :course, type: Polygon
+ field :source, type: Point, spatial: true
+ field :mouth, type: Point, spatial: true
+ field :course, type: Line
+ field :boundings, type: Box
- # simplified spatial indexing
- # you can only index one point in mongodb version below 1.9
- # if you want something besides the defaults {bit: 24, min: -180, max: 180} just set index to the options on the index
- spatial_index :source
+ # spatial indexing
+ spatial_index :mouth
-end
-```
+ # default mongodb options
+ spatial_index :mouth, {bit: 24, min: -180, max: 180}
+ end
+Use
+---
+
Generate indexes on MongoDB:
-```
-rake db:mongoid:create_indexes
-```
+ rake db:mongoid:create_indexes
-Before we manipulate the data mongoid_spatial handles is what we call points.
-Points can be:
+Points
+------
* 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]
+* 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
\*only works in ruby 1.9 and up because hashes below ruby 1.9 because they are not ordered
* anything with the method to_lng_lat that converts it to a [long,lat]
+
We store data in the DB as a [lng,lat] array then reformat when it is returned to you
-```ruby
-hudson = River.create(
- name: 'Hudson',
- length: 315,
- average_discharge: 21_400,
- # when setting array LONGITUDE MUST BE FIRST LATITUDE MUST BE SECOND
- # source: [-73.935833,44.106667],
- # but we can use hash in any order,
- # the default keys for latitude and longitude are :lat and :lng respectively
- source: {:lat => 44.106667, :lng => -73.935833},
- mouth: {:latitude => 40.703056, :longitude => -74.026667}
-)
-# now to access this spatial information we can now do this
-hudson.source #=> {:lng => -73.935833, :lat => 44.106667}
-hudson.mouth #=> [-74.026667, 40.703056] # notice how this returned as a lng,lat array because return_array was true
-# notice how the order of lng and lat were switched. it will always come out like this when using spatial.
-# Also adds a handy distance function
-hudson.distance_from(:source, [-74,40], {:unit=>:mi})
+ hudson = River.create(
+ name: 'Hudson',
+ length: 315,
+ discharge: 21_400,
+ # when setting array LNG (x) MUST BE FIRST LAT (y) MUST BE SECOND
+ # source: [-73.935833,44.106667],
+ # but we can use hash in any order
+ source: {:lat => 44.106667, :lng => -73.935833},
+ mouth: {:latitude => 40.703056, :longitude => -74.026667}
-```
-Mongoid Geo has extended all built in spatial symbol extensions
+Now to access this spatial information we can do this
+ hudson.mouth # => [-74.026667, 40.703056]
+
+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:
+
+ # Returns middle point + radius
+ # Useful to search #within_circle
+ hudson.mouth.radius(5) # [[-74.., 40..], 5]
+ hudson.mouth.radius_sphere(5) # [[-74.., 40..], 0.00048..]
+
+ # Returns hash if needed
+ hudson.mounth.to_hsh # {:x => -74.., :y => 40..}
+ hudson.mounth.to_hsh(:lon, :lat) # {:lon => -74.., :lat => 40..}
+
+
+Query
+--------
+
+Before you read about mongoid_spatial have sure you read this:
+
+http://mongoid.org/en/origin/docs/selection.html#standard
+
+All MongoDB queries are handled by Mongoid.
+
+
+You can use Geometry instance directly on any query:
+
* near
- * River.where(:source.near => [-73.98, 40.77])
- * River.where(:source.near => [[-73.98, 40.77],5]) # sets max distance of 5
- * River.where(:source.near => {:point => [-73.98, 40.77], :max => 5}) # sets max distance of 5
- * River.where(:source.near(:sphere) => [[-73.98, 40.77],5]) # sets max distance of 5 radians
- * River.where(:source.near(:sphere) => {:point => [-73.98, 40.77], :max => 5, :unit => :km}) # sets max distance of 5 km
- * River.where(:source.near(:sphere) => [-73.98, 40.77])
-* within
- * River.where(:source.within(:box) => [[-73.99756,40.73083], [-73.988135,40.741404]])
- * River.where(:source.within(:box) => [ {:lat => 40.73083, :lng => -73.99756}, [-73.988135,40.741404]])
- * River.where(:source.within(:polygon) => [ [ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ] ]
- * River.where(:source.within(:polygon) => { a : { x : 10, y : 20 }, b : { x : 15, y : 25 }, c : { x : 20, y : 20 } })
- * River.where(:source.within(:center) => [[-73.98, 40.77],5]) # same format as near
- * River.where(:source.within(:center_sphere) => [[-73.98, 40.77],5]) # same format as near(:sphere)
+ * Bar.where(:location.near => person.house)
-One of the most handy features we have added is geo_near finder
+* near_sphere
+ * Bar.where(:location.near_sphere => person.house)
-```ruby
-# accepts all criteria chains except without, only, asc, desc, order\_by
-River.where(:name=>'hudson').geo_near({:lat => 40.73083, :lng => -73.99756})
+* within_box
+ * Bar.where(:location.within_box => hood.area)
-# geo\_near accepts a few parameters besides a point
-# :num = limit
-# :query = where
-# :unit - [:km, :m, :mi, :ft] - converts :max\_distance to appropriate values and automatically sets :distance\_multiplier. accepts
-# :max\_distance - Integer
-# :distance\_multiplier - Integer
-# :spherical - true - To enable spherical calculations
-River.geo_near([-73.99756,40.73083], :max_distance => 4, :unit => :mi, :spherical => true)
-```
+* within_circle
+ * Bar.where(:location.within_box => hood.area)
+* within_circle_sphere
+ * Bar.where(:location.within_circle_sphere => hood.area)
+* within_polygon
+ * Bar.where(:location.within_polygon => city.area)
+
+
+Class Methods
+-------------
+
+Some method are added to your class when you define a field as spatial.
+
+ field :location, type: Point, spatial: true
+
+
+
+Geometry
+--------
+
+You can also store Circle, Box, Line (LineString) and Polygons.
+Some helper methods are available to them:
+
+
+ # Returns a geometry bounding box
+ # Useful to query #within_box
+ polygon.bbox
+ polygon.bounding_box
+
+ # Returns a geometry calculated middle point
+ # Useful to query for #near
+ polygon.center
+
+ # Returns middle point + radius
+ # Useful to search #within_circle
+ polygon.radius(5) # [[1.0, 1.0], 5]
+ polygon.radius_sphere(5) # [[1.0, 1.0], 0.00048..]
+
+
+
+
Mongo DB 1.9+ New Geo features
---------
Multi-location Documents v.1.9+
@@ -348,10 +386,11 @@
------
* Thanks to Kristian Mandrup for creating the base of the gem and a few of the tests
* Thanks to CarZen LLC. for letting me release the code we are using
+
Contributing
------------
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
@@ -359,10 +398,10 @@
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
Copyright
-----------
-Copyright (c) 2011 Ryan Ong. See LICENSE.txt for
-further details.
+Copyright (c) 2011 Ryan Ong. See LICENSE.txt for further details.