Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Geospatial data library for Ruby
Ruby C

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
ext/geos_c_impl
lib
tests
.gitignore
History.rdoc
README.rdoc
Rakefile
Version

README.rdoc

RGeo

RGeo is a spatial data library for Ruby.

It provides an implementation of the Open Geospatial Consortium's Simple Features Specification, used by most standard spatial/geographic data storage systems such as PostGIS. It also provides a suite of useful tools for writing location-based applications using Ruby-based frameworks such as Ruby On Rails.

IMPORTANT: RGeo is currently under development, and we consider it to be in a “pre-alpha” state. Several features are not yet complete, and there are known bugs and holes in the test suite. We also expect the APIs to be in flux for a short while longer. Therefore, we do not yet recommend the use of RGeo in production.

Summary

RGeo is a core component for writing location-based applications in the Ruby programming language. It provides the basic tools for modeling location data and communicating with geolocation-aware storage systems and location-based services.

Use RGeo to:

  • Represent spatial and geolocation data objects such as points, lines, and polygons in your Ruby application.

  • Perform standard spatial analysis operations such as finding intersections, creating buffers, and computing lengths and areas.

  • Correctly handle spherical geometry, and compute projections for geographic data analysis.

  • Store and retrieve spatial data in industry standard spatial database systems such as MySQL Spatial, SpatiaLite, and PostGIS.

  • Generate and interpret GeoJSON data for communication with common location-based web services such as SimpleGeo.

  • Read legacy GIS data from ESRI shapefiles.

  • Extend Ruby On Rails to handle location data in a web application.

  • Write spatial applications following the latest open standards from the Open Geospatial Consortium.

Requirements

RGeo has the following prerequisites:

  • Ruby 1.8.7 or later. Ruby 1.9.2 or later preferred. Rubinius and JRuby are not yet supported.

  • GEOS 3.2 or later highly recommended. Some functions will not be available without it. This C/C++ library may be available via your operating system's package manager, or you can download it from geos.osgeo.org/

  • If you are using the GeoJSON tools under Ruby 1.8.7, you should install the “json” gem. Ruby 1.9 has JSON support in its standard library and does not require the gem.

  • If you are using the shapefile reader, you should install the “dbf” gem for access to shape attributes.

  • The ActiveRecord adapters for MySQL Spatial, PostGIS, and SpatiaLite require ActiveRecord 3.0.3 or later, Arel 2.0 or later, and the corresponding database driver gems (e.g. “mysql” or “mysql2”).

Installation

Install RGeo as a gem:

gem install rgeo

Note: By default, the gem installation looks for the required GEOS library in the following locations:

  • /usr/local

  • /usr/local/geos

  • /opt/local

  • /usr

If GEOS has been installed in a different location, you must provide its installation prefix directory using the “–with-geos-dir” option. This option must be preceded by “–” to separate it, as a build switch, from the switches interpreted by the gem command. For example:

gem install rgeo -- --with-geos-dir=/path/to/my/geos/installation

Known issues

  • Some planned and documented functionality on the SimpleCartesian and SimpleSpherical data implementations is not yet implemented.

  • Reading of shapefile attributes is dependent on the “dbf” gem. Unfortunately, the current version of dbf, 1.5.0, has a hard dependency on ActiveSupport 3.0.1, which renders it incompatible with the ActiveRecord adapters, which require at least ActiveRecord 3.0.3 (not to mention also rendering it incompatible with Rails 3.0.3…) I have filed a bug report with dbf to try to get this resolved.

To-do items

This is our potential feature roadmap.

  • SpatiaLite and PostGIS adapters for ActiveRecord. (We already have an adapter for MySQL Spatial.)

  • Support for bbox and crs elements of GeoJSON.

  • Support for writing shapefiles. (Reading is now implemented.)

  • Projection subsystem, and support for arbitrary projections in the geography module, utilizing proj4.

  • Geography implementation utilizing ellipsoidal geometry, probably utilizing geographiclib.

  • Integration with other third-party formats and services, potentially including SimpleGeo, GeoRSS, KML.

  • JRuby support via JTS integration.

  • Rubinius support for GEOS integration.

Development and support

Documentation is available at virtuoso.rubyforge.org/rgeo/README_rdoc.html

Source code is hosted on Github at github.com/dazuma/rgeo

Report bugs on Github issues at github.org/dazuma/rgeo/issues

Contact the author at dazuma at gmail dot com.

Acknowledgments

RGeo is written by Daniel Azuma (www.daniel-azuma.com/).

Development of RGeo is sponsored by GeoPage, Inc. (www.geopage.com/).

RGeo links with the Open Source Geospatial Foundation's GEOS library to handle most Cartesian geometric calculations. GEOS and many other OSGeo projects can be found on OSGeo's web site (www.osgeo.org/).

The ActiveRecord adapters owe some debt to the spatial_adapter plugin (github.com/fragility/spatial_adapter). We made a few different design decisions for RGeo, but studying the spatial_adapter source gave us a head start on our implementation.

Although we don't use shapelib (shapelib.maptools.org/) to read ESRI shapefiles, we did borrow a bunch of their test cases.

License

Copyright 2010 Daniel Azuma

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the copyright holder, nor the names of any other contributors to this software, may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Something went wrong with that request. Please try again.