Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

readme

  • Loading branch information...
commit 02ac39b2b4743e369b168261081611d258672229 1 parent 29f817a
@nofxx nofxx authored
Showing with 108 additions and 52 deletions.
  1. +108 −52 README.md
View
160 README.md
@@ -93,84 +93,139 @@ Model Setup
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 :discharge, type: Integer
+ 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
+ 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
+ # spatial indexing
+ spatial_index :mouth
- # default mongodb options
- spatial_index :mouth, {bit: 24, min: -180, max: 180}
+ # default mongodb options
+ spatial_index :mouth, {bit: 24, min: -180, max: 180}
+ end
-end
-```
Use
---
Generate indexes on MongoDB:
-```
-rake db:mongoid:create_indexes
-```
-
-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.
+ rake db:mongoid:create_indexes
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})
-```
-Mongoid Geo has extended all built in spatial symbol extensions
+ 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}
+
+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.within(:box) => [[-73.99756,40.73083], [-73.988135,40.741404]])
+ * Bar.where(:location.near => person.house)
+
+* near_sphere
+ * Bar.where(:location.near_sphere => person.house)
+
+* within_box
+ * Bar.where(:location.within_box => hood.area)
+
+* 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..]
+
@@ -333,6 +388,7 @@ Thanks
* 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
------------
@@ -344,8 +400,8 @@ Contributing
* 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.
Please sign in to comment.
Something went wrong with that request. Please try again.