README.md in mongoid_geospatial-2.3.0 vs README.md in mongoid_geospatial-2.5.0
- old
+ new
@@ -1,11 +1,10 @@
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.
Version 2+ is going to be beta testing, when it's ready I'll release v3,
So the major version stays the same as mongoid.
@@ -23,111 +22,43 @@
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:
rake db:mongoid:create_indexes
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)
* 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
@@ -148,14 +79,22 @@
mouth: {:latitude => 40.703056, :longitude => -74.026667}
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
hudson.mouth.radius(5) # [[-74.., 40..], 5]
hudson.mouth.radius_sphere(5) # [[-74.., 40..], 0.00048..]
@@ -163,10 +102,16 @@
# Returns hash if needed
hudson.mounth.to_hsh # {:x => -74.., :y => 40..}
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
--------
Before you read about mongoid_spatial have sure you read this:
@@ -176,33 +121,153 @@
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)
-Class Methods
--------------
+External Libraries
+------------------
-Some method are added to your class when you define a field as spatial.
+Use RGeo?
+https://github.com/dazuma/rgeo
- field :location, type: Point, spatial: true
+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:
+
+ Bar.nearby(my.location)
+
+instead of
+
+ Bar.near(location: my.location)
+
+Good when you're drunk. Just add to your model:
+
+ spatial_scope :<field>
Geometry
--------