rgeo 0.1.19 → 0.1.20

data/History.rdoc

@@ -1,3 +1,14 @@
+=== 0.1.20 / 2010-11-30
+
+* API CHANGE: Methods that raised MethodUnimplemented now raise UnsupportedCapability instead. Removed MethodUnimplemented.
+* API CHANGE: Renamed RGeo::Features to RGeo::Feature, RGeo::Errors to RGeo::Error, and RGeo::ImplHelpers to RGeo::ImplHelper. The old pluralized names are aliased to the new names for now for backward compatibility, though they are deprecated and will be removed shortly.
+* Renamed the tests directory to test. Generally speaking, I'm getting rid of pluralized names.
+* Added RGeo::CoordSys::Proj4 representing a proj4 coordinate system. It uses the proj4 library.
+* Added Factory#proj4 as an optional method indicated by the :proj4 capability.
+* All existing geometry implementations now support proj4.
+* You can now cause casting to transform between proj4 projections by specifying the :project parameter.
+* A Geography implementation with an arbitrary projection backed by proj4 is now available.
+
 === 0.1.19 / 2010-11-23
 
 * The GEOS implementation now supports ZM (4-dimensional data), via a wrapper since the underlying GEOS library doesn't support 4d data natively.

data/README.rdoc

@@ -47,11 +47,15 @@ RGeo has the following prerequisites:
   available without it. This C/C++ library may be available via your
   operating system's package manager, or you can download it from
   http://geos.osgeo.org/
+* Proj 4.7.0 or later is also recommended. This is needed if you want
+  to translate coordinates between geographic projections. It also may
+  be available via your operating system's package manager, or from
+  http://trac.osgeo.org/proj/
 * 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 version 1.5.2 or later, which is required to read the attributes.
+  gem, version 1.5.2 or later, which is required to read the 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").
@@ -77,18 +81,28 @@ the switches interpreted by the gem command. For example:
 
  gem install rgeo -- --with-geos-dir=/path/to/my/geos/installation
 
+Similarly, the gem installation looks for the Proj.4 library in the
+following locations by default:
+
+* /usr/local
+* /usr/local/proj
+* /usr/local/proj4
+* /opt/local
+* /usr
+
+If Proj4 is installed in a different location, you must provide its
+installation prefix directory using the "--with-proj-dir" option.
+
 === To-do items
 
 This is our planned feature roadmap, in rough priority order.
 
-* Projection subsystem, and support for arbitrary projections in the
-  geography module, utilizing proj4.
 * SpatiaLite and PostGIS adapters for ActiveRecord. (We already have an
   adapter for MySQL Spatial.)
 * Integration with certain third-party services such as SimpleGeo.
 * Support for bbox and crs elements of GeoJSON.
 * Ellipsoidal geography implementation, probably utilizing geographiclib.
-* Rubinius support for GEOS integration.
+* Rubinius support for C library integration.
 * JRuby support via JTS integration.
 * Support for writing shapefiles. (Reading is already implemented.)
 * Read and write other formats such as GeoRSS and KML.
@@ -109,9 +123,11 @@ RGeo is written by Daniel Azuma (http://www.daniel-azuma.com/).
 
 Development of RGeo is sponsored by GeoPage, Inc. (http://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 (http://www.osgeo.org/).
+RGeo links with the GEOS library to handle most Cartesian geometric
+calculations, and with the Proj4 library to handle projections and
+coordinate transforms. These libraries are maintained by the Open Source
+Geospatial Foundation; these and other OSGeo projects can be found on
+OSGeo's web site (http://www.osgeo.org/).
 
 The ActiveRecord adapters owe some debt to the spatial_adapter plugin
 (http://github.com/fragility/spatial_adapter). We made a few different

data/Version

@@ -1 +1 @@
-0.1.19
+0.1.20

data/ext/geos_c_impl/factory.c

@@ -223,7 +223,7 @@ RGeo_Globals* rgeo_init_geos_factory()
   RGeo_Globals* globals = ALLOC(RGeo_Globals);
   VALUE rgeo_module = rb_define_module("RGeo");
   globals->geos_module = rb_define_module_under(rgeo_module, "Geos");
-  globals->features_module = rb_define_module_under(rgeo_module, "Features");
+  globals->features_module = rb_define_module_under(rgeo_module, "Feature");
   
   // Add C methods to the factory.
   VALUE geos_factory_class = rb_const_get_at(globals->geos_module, rb_intern("Factory"));

data/{lib/rgeo/geography/simple_mercator.rb → ext/proj4_c_impl/extconf.rb}

@@ -1,6 +1,6 @@
 # -----------------------------------------------------------------------------
 # 
-# Simple spherical geography implementation for RGeo
+# Makefile builder for Proj4 wrapper
 # 
 # -----------------------------------------------------------------------------
 # Copyright 2010 Daniel Azuma
@@ -34,36 +34,41 @@
 ;
 
 
-require 'rgeo/geography'
+require 'mkmf'
 
+header_dirs_ =
+  [
+   '/usr/local/include',
+   '/usr/local/proj/include',
+   '/usr/local/proj4/include',
+   '/opt/local/include',
+   ::Config::CONFIG['includedir'],
+   '/usr/include',
+  ]
+lib_dirs_ =
+  [
+   '/usr/local/lib',
+   '/usr/local/proj/lib',
+   '/usr/local/proj4/lib',
+   '/opt/local/lib',
+   ::Config::CONFIG['libdir'],
+   '/usr/lib',
+  ]
+header_dirs_.delete_if{ |path_| !::File.directory?(path_) }
+lib_dirs_.delete_if{ |path_| !::File.directory?(path_) }
 
-module RGeo
-  
-  module Geography
-    
-    
-    # This namespace contains the simple mercator implementation.
-    
-    module SimpleMercator
-    end
-    
-    
+found_proj_ = false
+header_dirs_, lib_dirs_ = dir_config('proj', header_dirs_, lib_dirs_)
+if have_header('proj_api.h')
+  $libs << ' -lproj'
+  if have_func('pj_init_plus', 'proj_api.h')
+    found_proj_ = true
+  else
+    $libs.gsub!(' -lproj', '')
   end
-  
-  
 end
-
-
-# Dependency source files.
-paths_ = [
-  'features',
-  'wkrep',
-  'impl_helpers',
-  'cartesian',
-  'geography/simple_mercator/projector',
-  'geography/simple_mercator/feature_methods',
-  'geography/simple_mercator/feature_classes',
-  'geography/factory',
-  'geography/projected_window',
-]
-paths_.each{ |path_| require "rgeo/#{path_}" }
+unless found_proj_
+  puts "**** WARNING: Unable to find Proj headers or Proj version is too old."
+  puts "**** Compiling without Proj support."
+end
+create_makefile('coord_sys/proj4_c_impl')

data/ext/proj4_c_impl/main.c

@@ -0,0 +1,256 @@
+/*
+  -----------------------------------------------------------------------------
+  
+  Main initializer for Proj4 wrapper
+  
+  -----------------------------------------------------------------------------
+  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.
+  -----------------------------------------------------------------------------
+*/
+
+
+#ifdef HAVE_PROJ_API_H
+#ifdef HAVE_PJ_INIT_PLUS
+#define RGEO_PROJ4_SUPPORTED
+#endif
+#endif
+
+#ifdef __cplusplus
+#define RGEO_BEGIN_C extern "C" {
+#define RGEO_END_C }
+#else
+#define RGEO_BEGIN_C
+#define RGEO_END_C
+#endif
+
+
+#ifdef RGEO_PROJ4_SUPPORTED
+
+#include <ruby.h>
+#include <proj_api.h>
+
+#endif
+
+
+RGEO_BEGIN_C
+
+
+#ifdef RGEO_PROJ4_SUPPORTED
+
+
+typedef struct {
+  projPJ pj;
+  VALUE original_str;
+} RGeo_Proj4Data;
+
+
+#define RGEO_PROJ4_DATA_PTR(obj) ((RGeo_Proj4Data*)DATA_PTR(obj))
+
+
+// Destroy function for proj data.
+
+static void destroy_proj4_func(RGeo_Proj4Data* data)
+{
+  if (data->pj) {
+    pj_free(data->pj);
+  }
+  free(data);
+}
+
+
+static void mark_proj4_func(RGeo_Proj4Data* data)
+{
+  if (!NIL_P(data->original_str)) {
+    rb_gc_mark(data->original_str);
+  }
+}
+
+
+static VALUE alloc_proj4(VALUE klass)
+{
+  VALUE result = Qnil;
+  RGeo_Proj4Data* data = ALLOC(RGeo_Proj4Data);
+  if (data) {
+    data->pj = NULL;
+    data->original_str = Qnil;
+    result = Data_Wrap_Struct(klass, mark_proj4_func, destroy_proj4_func, data);
+  }
+  return result;
+}
+
+
+static VALUE method_proj4_initialize_copy(VALUE self, VALUE orig)
+{
+  // Clear out any existing value
+  projPJ pj = RGEO_PROJ4_DATA_PTR(self)->pj;
+  if (pj) {
+    pj_free(pj);
+    RGEO_PROJ4_DATA_PTR(self)->pj = NULL;
+    RGEO_PROJ4_DATA_PTR(self)->original_str = Qnil;
+  }
+  
+  // Copy value from orig
+  RGEO_PROJ4_DATA_PTR(self)->pj = RGEO_PROJ4_DATA_PTR(orig)->pj;
+  RGEO_PROJ4_DATA_PTR(self)->original_str = RGEO_PROJ4_DATA_PTR(orig)->original_str;
+  
+  return self;
+}
+
+
+static VALUE method_proj4_get_geographic(VALUE self)
+{
+  VALUE result = Qnil;
+  RGeo_Proj4Data* data = ALLOC(RGeo_Proj4Data);
+  if (data) {
+    data->pj = pj_latlong_from_proj(RGEO_PROJ4_DATA_PTR(self)->pj);
+    data->original_str = Qnil;
+    result = Data_Wrap_Struct(CLASS_OF(self), mark_proj4_func, destroy_proj4_func, data);
+  }
+  return result;
+}
+
+
+static VALUE method_proj4_original_str(VALUE self)
+{
+  return RGEO_PROJ4_DATA_PTR(self)->original_str;
+}
+
+
+static VALUE method_proj4_canonical_str(VALUE self)
+{
+  VALUE result = Qnil;
+  projPJ pj = RGEO_PROJ4_DATA_PTR(self)->pj;
+  if (pj) {
+    char* str = pj_get_def(pj, 0);
+    if (str) {
+      result = rb_str_new2(str);
+      pj_dalloc(str);
+    }
+  }
+  return result;
+}
+
+
+static VALUE method_proj4_is_geographic(VALUE self)
+{
+  VALUE result = Qnil;
+  projPJ pj = RGEO_PROJ4_DATA_PTR(self)->pj;
+  if (pj) {
+    result = pj_is_latlong(pj) ? Qtrue : Qfalse;
+  }
+  return result;
+}
+
+
+static VALUE method_proj4_is_geocentric(VALUE self)
+{
+  VALUE result = Qnil;
+  projPJ pj = RGEO_PROJ4_DATA_PTR(self)->pj;
+  if (pj) {
+    result = pj_is_geocent(pj) ? Qtrue : Qfalse;
+  }
+  return result;
+}
+
+
+static VALUE method_proj4_is_valid(VALUE self)
+{
+  return RGEO_PROJ4_DATA_PTR(self)->pj ? Qtrue : Qfalse;
+}
+
+
+static VALUE cmethod_proj4_transform(VALUE method, VALUE from, VALUE to, VALUE x, VALUE y, VALUE z)
+{
+  VALUE result = Qnil;
+  projPJ from_pj = RGEO_PROJ4_DATA_PTR(from)->pj;
+  projPJ to_pj = RGEO_PROJ4_DATA_PTR(to)->pj;
+  if (from_pj && to_pj) {
+    double xval = rb_num2dbl(x);
+    double yval = rb_num2dbl(y);
+    double zval = 0.0;
+    if (!NIL_P(z)) {
+      zval = rb_num2dbl(z);
+    }
+    int err = pj_transform(from_pj, to_pj, 1, 1, &xval, &yval, NIL_P(z) ? NULL : &zval);
+    if (!err && xval != HUGE_VAL && yval != HUGE_VAL && (NIL_P(z) || zval != HUGE_VAL)) {
+      result = rb_ary_new2(NIL_P(z) ? 2 : 3);
+      rb_ary_push(result, rb_float_new(xval));
+      rb_ary_push(result, rb_float_new(yval));
+      if (!NIL_P(z)) {
+        rb_ary_push(result, rb_float_new(zval));
+      }
+    }
+  }
+  return result;
+}
+
+
+static VALUE cmethod_proj4_create(VALUE klass, VALUE str)
+{
+  VALUE result = Qnil;
+  Check_Type(str, T_STRING);
+  RGeo_Proj4Data* data = ALLOC(RGeo_Proj4Data);
+  if (data) {
+    data->pj = pj_init_plus(RSTRING_PTR(str));
+    data->original_str = str;
+    result = Data_Wrap_Struct(klass, mark_proj4_func, destroy_proj4_func, data);
+  }
+  return result;
+}
+
+
+static void rgeo_init_proj4()
+{
+  VALUE rgeo_module = rb_define_module("RGeo");
+  VALUE coordsys_module = rb_define_module_under(rgeo_module, "CoordSys");
+  VALUE proj4_class = rb_define_class_under(coordsys_module, "Proj4", rb_cObject);
+  rb_define_module_function(proj4_class, "_create", cmethod_proj4_create, 1);
+  rb_define_method(proj4_class, "initialize_copy", method_proj4_initialize_copy, 1);
+  rb_define_method(proj4_class, "_original_str", method_proj4_original_str, 0);
+  rb_define_method(proj4_class, "_canonical_str", method_proj4_canonical_str, 0);
+  rb_define_method(proj4_class, "_valid?", method_proj4_is_valid, 0);
+  rb_define_method(proj4_class, "_geographic?", method_proj4_is_geographic, 0);
+  rb_define_method(proj4_class, "_geocentric?", method_proj4_is_geocentric, 0);
+  rb_define_method(proj4_class, "_get_geographic", method_proj4_get_geographic, 0);
+  rb_define_module_function(proj4_class, "_transform_coords", cmethod_proj4_transform, 5);
+}
+
+
+#endif
+
+
+void Init_proj4_c_impl()
+{
+#ifdef RGEO_PROJ4_SUPPORTED
+  rgeo_init_proj4();
+#endif
+}
+
+
+RGEO_END_C

data/lib/rgeo.rb

@@ -41,46 +41,44 @@
 # 
 # RGeo comprises a number of modules.
 # 
-# The RGeo::Features module contains interface specifications for spatial
+# The RGeo::Feature module contains interface specifications for spatial
 # objects implemented by RGeo. These interfaces closely follow the OGC
 # Simple Features Specifiation (SFS). This module forms the core of RGeo.
 # 
+# The RGeo::CoordSys module contains classes for representing spatial
+# reference systems and coordinate transformations. For example, it
+# includes a wrapper for the Proj4 library, supporting many geographic
+# projections.
+# 
 # The RGeo::Cartesian module provides a basic pure ruby implementation of
 # spatial objects in a Cartesian (flat) coordinate system. It does not
 # implement all the geometric analysis operations in the SFS, but it
 # implements the data structures without requiring an external C library,
 # so it is often sufficient for basic applications.
 # 
-# The RGeo::Geos module is another cartesian implementation that wraps the
-# GEOS library to provide a full, high-performance implementation of
+# The RGeo::Geos module is another Cartesian implementation that wraps
+# the GEOS library to provide a full, high-performance implementation of
 # Cartesian geometry that includes every operation defined in the SFS. It
 # requires GEOS 3.2 or later.
 # 
 # The RGeo::Geography module contains spatial implementations that
 # operate in latitude-longitude coordinates and are well-suited for
-# geographic location based applications.
-# 
-# One of the geography implementations is RGeo::Geography::SimpleMercator,
-# which uses the same coordinate system and projection as that used by
-# Google and Bing Maps, and is ideally suited for visualization
-# applications based on those technologies.
-# 
-# The RGeo::Geography::SimpleSpherical provides another geography
-# implementation that does not use a projection, but instead performs
-# geometric operations on a spherical approximation of the globe. This
-# implementation does not provide all the geometric analysis operations
-# in the SFS, but it may be useful for cases when you need more accuracy
-# than a projected implementation would provide.
+# geographic location based applications. Geography implementations may
+# also be linked to projections.
 # 
 # The RGeo::WKRep module contains tools for reading and writing spatial
 # data in the OGC Well-Known Text (WKT) and Well-Known Binary (WKB)
-# representations. It also supports their variants such as the PostGIS
+# representations. It also supports common variants such as the PostGIS
 # EWKT and EWKB representations.
 # 
 # The RGeo::GeoJSON module contains tools for GeoJSON serialization of
 # spatial objects. These tools work with any of the spatial object
 # implementations.
 # 
+# The RGeo::Shapefile module contains tools for reading ESRI shapefiles,
+# an industry standard (if somewhat legacy) file format commonly used for
+# providing geographic data sets.
+# 
 # === Loading the library
 # 
 # After installing the RGeo gem, you can load the library with:
@@ -95,43 +93,57 @@
 #  require 'rgeo/all'
 # 
 # You may also eagerly load individual modules:
-#  require 'rgeo/features'
+#  require 'rgeo/feature'
 #  require 'rgeo/cartesian'
-#  require 'rgeo/geos'
+#  require 'rgeo/coord_sys'
 #  require 'rgeo/geography'
-#  require 'rgeo/geography/simple_mercator'
-#  require 'rgeo/geography/simple_spherical'
-#  require 'rgeo/wkrep'
+#  require 'rgeo/geos'
 #  require 'rgeo/geo_json'
+#  require 'rgeo/shapefile'
+#  require 'rgeo/wkrep'
 # 
-# === Future modules
-# 
-# RGeo is in active development with several additional modules planned
-# for future releases. These include:
-# 
-# * RGeo::Shapefile, which provides tools for reading and writing
-#   spatial objects in the ESRI shapefile format.
-# * RGeo::Rails, which provides close integration with Ruby On Rails
-#   for developing location-based web applications.
-# * RGeo::JTS, which provides a Cartesian SFS implementation backed by
-#   the JTS library (which can run natively in JRuby.)
-# * RGeo::Projection, which wraps and provides an API for the proj4
-#   library, providing a way to compute arbitrary projections.
-# * RGeo::Geography extensions to provide highly accurate ellipsoidal
-#   geometric calculations, and support arbitrary map projections
-#   via RGeo::Projection.
+# === Spatial connection adapters for ActiveRecord
+# 
+# RGeo also provides ActiveRecord connection adapters for common spatial
+# databases. You can specify and use these connection adapters in the same
+# way you use any other connection adapter, for example by specifying the
+# adapter name in a Rails application's database.yml file. You do not need
+# to require any files to gain access to these adapters. RGeo makes them
+# available to ActiveRecord automatically.
+# 
+# These adapters are:
+# 
+# <tt>mysqlspatial</tt>::
+#   An adapter based on the standard mysql adapter. It extends the stock
+#   adapter to provide support for spatial columns in MySQL, mapping the
+#   values properly to RGeo spatial objects. Like the standard mysql
+#   adapter, this requires the mysql gem (version 2.8 or later).
+# <tt>mysql2spatial</tt>::
+#   An adapter for MySQL spatial based on the mysql2 adapter. It requires
+#   the mysql2 gem (version 0.2.6 or later).
+# <tt>spatialite</tt>::
+#   An adapter for the SpatiaLite extension to Sqlite3. It is based on
+#   the stock sqlite3 adapter, and requires the sqlite3-ruby gem.
+#   <b>(INCOMPLETE)</b>
+# <tt>postgis</tt>::
+#   An adapter for the PostGIS extension to Postgresql. It is based on
+#   the stock postgres adapter, and requires the pg gem.
+#   <b>(INCOMPLETE)</b>
 
 module RGeo
   
   autoload(:Cartesian, 'rgeo/cartesian')
-  autoload(:Errors, 'rgeo/errors')
-  autoload(:Features, 'rgeo/features')
+  autoload(:CoordSys, 'rgeo/coord_sys')
+  autoload(:Error, 'rgeo/error')
+  autoload(:Errors, 'rgeo/error')
+  autoload(:Feature, 'rgeo/feature')
+  autoload(:Features, 'rgeo/feature')
   autoload(:GeoJSON, 'rgeo/geo_json')
   autoload(:Geography, 'rgeo/geography')
   autoload(:Geos, 'rgeo/geos')
-  autoload(:ImplHelpers, 'rgeo/impl_helpers')
-  autoload(:WKRep, 'rgeo/wkrep')
+  autoload(:ImplHelper, 'rgeo/impl_helper')
   autoload(:Shapefile, 'rgeo/shapefile')
+  autoload(:WKRep, 'rgeo/wkrep')
   
 end