README.md in mongoid_geospatial-2.5.1 vs README.md in mongoid_geospatial-2.7.0
- old
+ new
@@ -29,20 +29,20 @@
include Mongoid::Document
# Include the module
include Mongoid::Geospatial
- # Just like mongoid,
+ # Just like mongoid,
field :name, type: String
- # define your field, but choose a geometry type:
- field :location, type: Point, :spatial => true
+ # define your field, but choose a geometry type:
+ field :location, type: Point
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
-
+
+ # If your are going to query on your points, don't forget to index:
+ spatial_index :location
+ # You can index points with :spatial => true option too, see below.
end
Generate indexes on MongoDB:
@@ -55,19 +55,18 @@
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
\*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]
+* anything with the a method #to_xy or #to_lng_lat that converts itself to [long, lat] array
-We store data in the DB as a [lng,lat] array then reformat when it is returned to you
+We store data in the DB as a [x, y] array then reformat when it is returned to you
hudson = River.create(
name: 'Hudson',
length: 315,
@@ -79,19 +78,21 @@
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
+Conventions: This lib uses #x and #y everywhere. 1. It's shorter than lat or lng or another variation that also confuses. 2. A point is a 2D mathematical notation, longitude/latitude is when you use that notation to map an sphere. In other words, all longitudes are 'xs' where not all 'xs' are longitudes. In the eyes of a moralist it's not even a valid position point, it does not have #z or #m.
+
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 for mongoid queries:
# Returns middle point + radius
@@ -104,14 +105,14 @@
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
-
+ 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:
@@ -123,29 +124,29 @@
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.within_box(location: hood.area)
-
+
* within_circle
* Bar.within_circle(location: hood.area)
-
+
* within_circle_sphere
* Bar.within_circle_sphere(location: hood.area)
-
+
* within_polygon
* Bar.within_polygon(location: city.area)
External Libraries
@@ -211,12 +212,12 @@
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
@@ -231,40 +232,58 @@
class CrazyGeom
include Mongoid::Document
include Mongoid::Geospatial
- field :location, type: Point
+ field :location, type: Point, :spatial => true, :delegate => true
- field :route, type: Line
- field :area, type: Polygon
-
- field :square, type: Box
- field :around, type: Circle
-
+ 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
+
+ # query by location
+ spatial_scope :location
end
+Helpers
+-------
+You can use `:spatial => true` to add an '2d' index automatically,
+No need for `spatial_index :location`:
+
+
+ field :location, type: Point, :spatial => true
+
+
+You can delegate some point methods to the instance itself:
+
+
+ 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:
Bar.nearby(my.location)
-
+
instead of
Bar.near(location: my.location)
-
+
Good when you're drunk. Just add to your model:
spatial_scope :<field>