Browse files

readme

  • Loading branch information...
1 parent 7ce873f commit 9a4b7d1a6a1fa871760b4ef94a949be56743f3c6 @nofxx nofxx committed Sep 14, 2012
Showing with 130 additions and 91 deletions.
  1. +130 −91 README.md
View
221 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,22 +123,29 @@ 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
@@ -220,14 +172,101 @@ This lib won't stand in your way.
Write your own wrapper if you want.
-Class Methods
--------------
+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:
-* MISSING: this is the last part I'm working on...wait and comment *
+ 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>

0 comments on commit 9a4b7d1

Please sign in to comment.