GEOS Extensions

The GEOS Extensions library (GEL) is a set of utilities and tools that extend the GEOS Ruby bindings module. From geos.refractions.net/ …

GEOS (Geometry Engine - Open Source) is a C++ port of the  Java Topology
Suite (JTS). As such, it aims to contain the complete functionality of JTS
in C++. This includes all the OpenGIS Simple Features for SQL spatial
predicate functions and spatial operators, as well as specific JTS
enhanced topology functions.

The GEOS bindings for Ruby come in two flavours these days: the native version bundled with the GEOS source itself and an FFI version. The native bindings seem to be rather abandoned these days while the FFI bindings are actively maintained by… well, the author of this gem, actually. We’re going to effectively deprecate the use of the native bindings for the purposes of this gem and recommend that the FFI bindings be used instead and as such the ffi-geos gem will now become a dependency in the geos-extensions gemspec.

The ffi-geos gem is available at github.com/dark-panda/ffi-geos .

GEL contains a number of enhancements to the GEOS Ruby library:

  • a host of helper methods to make reading and writing to and from WKT and WKB easier. For instance, rather than

    Geos::WktReader.new.read('POINT(0 0')

    you can quickly use

    Geos.read('POINT(0 0)')

    The Geos.read method also works with WKB in both binary and hex, recognizes EWKB and EWKT and can read several of Google Maps JavaScript output formats that we use for our applications. There are also similar methods for outputting to WKT and WKB such as Geos::Geometry#to_wkt, #to_kml, #to_georss and a number of methods to output to Google Maps API-style JavaScript.

  • a bunch of helper methods to quickly grab some information from geometries like Geos::Point#lat and Geos::Point#lng.

  • in all, some 70+ helper methods have been added to Geos::Geometry types.

  • Geos::GeometryCollection has been made an Enumerable.

Google Maps API Output

Starting with version 0.1.0, GEL supports both Google Maps API version 2 and version 3 style outputs. By default and for the sake of backwards compatibility, API version 2 output will remain the default but as Google has deprecated API version 2, so shall we at some point in the future. To switch between API versions, use the Geos::GoogleMaps.use_api(version) method:

g = Geos.read('point(0 0)')
Geos::GoogleMaps.use_api(2)
puts g.to_g_marker
Geos::GoogleMaps.use_api(3)
puts g.to_g_marker

Outputs

new google.maps.Marker(new google.maps.LatLng(0.0, 0.0), {})
new google.maps.Marker({"position": new google.maps.LatLng(0.0, 0.0)})

At an unspecified point in the future, we’ll likely make Google Maps API version 3 the default, but for the time being, we’ll stick with version 2 since switching between the two is pretty painless.

ActiveRecord Extensions

This extension used to contain a bunch of extensions to ActiveRecord, but as of version 0.3.0 we have decided to strip those extensions out and move them into their own gem called activerecord-spatial available at github.com/dark-panda/activerecord-spatial .

Error Handling in 1.0+

Starting with GEL 1.0.0, parser exceptions raised from methods like ‘Geos.from_g_lat_lng` and `Geos.from_box2d` are now instances of `Geos::Extensions::InvalidGLatLngFormatError` and `Geos::Extensions::InvalidBox2DError` respectively, which themselves are inherited from `Geos::ParseError`, `Geos::Error` and `RuntimeError`. This reflects similar changes in ffi-geos 1.0.0. For compatibility purposes with older versions of ffi-geos and the native geos library, the exception classes in `Geos` will be created for you if they aren’t already defined.

Thanks

  • Thanks to Charlie Savage for donating for YAML dumping and loading support.

License

This gem is licensed under an MIT-style license. See the MIT-LICENSE file for details.