Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Extensions for the GEOS library.
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app/models/geos
lib
test
.gitignore
MIT-LICENSE
README.rdoc
Rakefile
VERSION
geos-extensions.gemspec

README.rdoc

Zoocasa GEOS Extensions

The Zoocasa GEOS Extensions library (ZGEL) 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 can be installed by installing the GEOS library itself using the –enable-ruby switch during configure or can often be installed via package managers. There is also an FFI-based Ruby gem being written available at github.com/dark-panda/ffi-geos .

ZGEL 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.

We've also included some Rails integration for PostGIS, including:

  • automatic detection of geometry columns and just-in-time conversions for input and output to and from WKB when using PostGIS. This allows you to do stuff like this with your ActiveRecord models:

    m = MyModel.find(12345)
    m.the_geom # => spits out the untouched geometry value as a string in WKB
    m.the_geom_geos # => spits out the geometry wrapped in a Geos::Geometry object
    m.the_geom = 'POINT(0 0)' # => setters will automatically make
    conversions from any of the formats that the Geos.read can recognize,
    so Google Maps formats, WKT, WKB, etc. are all converted
    automatically.
    m.the_geom_wkt # => automatically converts to a WKT string
    m.the_geom_wkb_bin # => automatically converts to WKB in binary

    There's also some funky SRID handling code that will automatically look in the geometry_columns table to make conversions for you when necessary. Saving WKT as “SRID=default; POINT(0 0)” for instance will automatically set the SRID when saving the ActiveRecord, or the SRID can be specified manually.

  • multiple geometry columns are supported and detected for automatically. These column accessors are all generated dynamically at run time.

  • automatic generation of named scopes for ActiveRecord models. The usual suspects are supported:

    • st_contains

    • st_containsproperly

    • st_covers

    • st_coveredby

    • st_crosses

    • st_disjoint

    • st_equals

    • st_intersects

    • st_orderingequals

    • st_overlaps

    • st_touches

    • st_within

    • st_dwithin

    Ordering scopes are also included:

    • order_by_ndims

    • order_by_npoints

    • order_by_nrings

    • order_by_numgeometries

    • order_by_numinteriorring

    • order_by_numinteriorrings

    • order_by_numpoints

    • order_by_length3d

    • order_by_length

    • order_by_length2d

    • order_by_perimeter

    • order_by_perimeter2d

    • order_by_perimeter3d

    • order_by_distance

    • order_by_distance_sphere

    • order_by_maxdistance

    • order_by_hausdorffdistance

    • order_by_distance_spheroid

    • order_by_length2d_spheroid

    • order_by_length3d_spheroid

    • order_by_length_spheroid

    These let you chain together scopes to build geospatial queries:

    neighbourhood = Neighbourhood.find(12345)
    my_model = MyModel.active.
      recent.
      st_within(neighbourhood.the_geom_geos.envelope).
      st_dwithin(point, 0.1).
      all(
        :limit => 10
      )

Google Maps API Output

Starting with version 0.1.0, ZGEL 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.

Running ActiveRecord Tests

ActiveRecord unit tests can be run by setting the TEST_ACTIVERECORD environment variable when running `rake test`. The test database name is geos_extensions_unit_tests and requires PostGIS to be installed. The test scripts will try to find your postgis.sql and spatial_ref_sys.sql files, but if it needs a hint, set the POSTGIS_PATH environment variable to the directory the files are in to create the database properly. You can also set the database up manually before running the tests – just make sure the database has PostGIS installed with the spatial_ref_sys table populated and you'll be fine.

Something went wrong with that request. Please try again.