mongoid-geo

h1. Mongoid geo

h2. Status update: August, 2011

This project is currently dead, as I can find no time to keep it alive for the time being. The project mostly works, except for monogid/contexts/geo_mongo.rb, which needs some loove ;)

The project "mongoid_spacial":https://github.com/ryanong/mongoid_spacial by @ryanong has taken many of the ideas and core design of mongoid_geo, improved, reworked and optimized it and added many new features such as pagination intgration etc.

Please use the mongoid_spacial gem instead!!

Note: I have created several other "geo" projects in various states, some currently with a "refactor" branch. Would be nice to finish those and have it all integrated some time :)

Cheers!

h3. Running specs

The goal of this branch is to define a good specs structure and build up a good design of this 'geo' add-on this way.

h3. Status update: June, 2011

• A Mongoid::Geo::Config object has been added which you use to configure Mongoid::Geo, see mongoid/geo/config_spec.rb
• GeoPoints and GeoVectors can be integrated using the new #enable_extensions! method on Mongoid::Geo::Config, specs in mongoid/geo/extensions demonstrate how to use this
• Creation of Mongo query hashes for Twin- and NestedOperators have been extracted into Query classes (see mongoid/geo/queries folder)
• #geo_near now uses configuration from Mongoid::Geo::Config, such as the #distance_calculator (if Mongo server doesn't support this) and the #radians_multiplier etc.
• extensions can be enabled using Mongoid::Geo.enabele_extension ; currently supported extensions are :geo_calc, geo_point and geo_vectors (see specs for usage examples)

h2. Example Usage 1.0 (goal)

h2. Example Usage 1.1 (goal)

Would be nice with a simple API that acts as a location repository and can be implemented for any key/value store. Would also be nice to use unit distances as Numeric macros (currently available in geo_magic gem).

h2. Intro

This is a Geo extension for Mongoid 2.

"MongoDB Geospatial Indexing":http://www.mongodb.org/display/DOCS/Geospatial+Indexing

• Supports Mongo DB 1.7+ sphere distance calculations
• Extra geo calculation methods such as #near_sphere etc.
• Adds concept of a special "geo" field (for setting the location point)
• Configure and create geo indexes
• Calculate locations near a given point and return as criteria, sorted by distance

h2. You need help?

Post questions in the "mongoid-geo":http://groups.google.com/group/mongoid-geo group. Here I (and other uses of mongoid-geo) will try to help out and answer any questions.

h2. Suggestions, improvements and bugs?

Please raise issues or suggestions for improvements in the "Issues" section on github. I would recommend that you try to branch the project, try to fix it yourself and make a pull request.

h3. Current integrations

Mongoid geo has now been integrated with "Google-Maps-for-Rails":https://github.com/apneadiving/Google-Maps-for-Rails, thanks to "oli-g":https://github.com/oli-g, see "commit":https://github.com/oli-g/Google-Maps-for-Rails/commit/9ff5c82d33e3fa625e441baa516fee05e9ae979c

h2. Mongoid 2 geo features

The following summarized what geo functionality is already provided by Mongoid 2.0 (as far as I could tell, May 9th, 2011)

h3. Find addresses near a point

h3. Find locations within a circle

h3. Create geo-spatial index

These are the only geo features I could find that are currently built-in for Mongoid 2.

Mongoid Geo implements some nice extra geo features:

h1. Mongoid Geo features

The following briefly demonstrates all the features that mongoid-geo provides:

h2. Geo index

A new geo_index class method

Usage example:

@geo_index :location@

Note: For embedded documents, you must define the index in the root collection class. (davemitchell)

Calling geo_index also adds a #create_index! method to the class to enable construction of the index (on the instances/data in the DB).

I also added a nice little Array macro so you can do this:

h2. Geo option for Array GPS location field

Objective: When setting a geo GPS location array, the setter should try to convert the value to an array of floats

The "old" manual way:

mongoid-geo provides a new @:geo@ option that can be used with any Array field:

Usage example:

Customizing lat/lng attribute names:

Reversing lat/lng for spherical calculations

h2. geo_near

Find all positions sorted nearest to the address loation

@nearest_positions = Position.geo_near(another_address.location, :pos)@

Perform distance locations in Speherical mode inside Mongo DB (default is :plane)

@nearest_positions = Position.geo_near(another_address.location, :pos, :mode => :sphere)@

Other options supported are: @:num, :maxDistance, :distanceMultiplier, :query@

GeoNear returns each distance calculated in degrees. Use the :distanceMultiplier or :unit option to return in the unit of your choice (see unit.rb).

Set @:distanceMultiplier = 6371@ to get distance in KMs Set @@:distanceMultiplier = @3963.19@ to get distance in Miles

You can also use the :unit option instead like this (supports :feet, :meters, :kms, :miles):

@results = Address.geo_near @center.location, :location, :unit => :feet, :dist_order => :desc@

The geo_near query result is returned as a Mongoid::Criteria

@results.desc(:distance).map(&:distance)@

Note that the @:fromLocation@ field, stores the location the distance was last calculated as a Hash of the GPS location point it was calculated from:

@[23.5, -47].hash@

This hash can be retrieved (and used for comparison?) using the @fromHash@ field

@from = results.first.fromHash@

You can also at any time get the GPS location point which the distance of any result instance was calculated from, using the @fromPoint field

@from = results.first.fromPoint@

You can now explicitly set/configure the Mongo DB version used. This will affect whether built-in Mongo DB distance calculation will be used or using standalone Ruby Haversine algorithm. By default the Mongo DB version is set to 1.8 (as of May 9, 2011) . See geo_near specs for more details/info on this.

@Mongoid::Geo.mongo_db_version = 1.7@

h2. Mongoid Geo extra inclusions

Find addresses near a point using spherical distance calculation

h2. Mongoid Geo extra inflections

h3. near_sphere

h3. near_max

Find points near a given point within a maximum distance

You can also use a Hash to define the near_max

Or use an Object (which must have the methods @#point@ and @#distance@ that return the point and max distance from that point)

Note: For the points, you can also use a hash or an object with the methods/keys, either @:lat, :lng@ or @:latitude, :longitude@

Example:

h3. within_box

You can also use a Hash to define the box

Or use an object (which must have the methods @#lower_left@ and @#upper_right@ that return the points of the bounding box)

h3. within_center

You can also use a hash to define the circle, with @:center@ and @:radius@ keys

Or use an object (which must have the methods #center and #radius that return the center and radius of the circle))

h2. Note on the specs

The specs still use the old "Javascript" like method convention, such as #nearSphere Don't let that fool you ;)

h2. Contribute

Please feel free to contribute to the project!

I aim to deliver a complete geo package for use with Mongoid. This gem should work nicely with "geo_calc":https://github.com/kristianmandrup/geo_calc and "geo_vectors":https://github.com/kristianmandrup/geo_vectors that I'm also working on.

Your assistance on any of these projects will be greatly appreciated :)