rgeo 0.1.17 → 0.1.18

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 0.1.18 / 2010-11-22
+
+* API CHANGE: GeoJSON defaults to no JSON parser rather than to the JSON library. GeoJSON also fails better when attempting to use a JSON parser that isn't installed.
+* Added a decorator tool for FactoryGenerator
+* Added an analysis module for Cartesian geometries, and implemented an algorithm for determining whether a ring is clockwise or counterclockwise. (We needed this to interpret shapefiles.)
+* First pass implementation of shapefile reading. It passes a basic test suite I borrowed from shapelib, but I haven't yet done an exhaustive test on every case.
+* The simple Cartesian implementation mistakenly clamped x and y to lat/lon limits. Fixed.
+
 === 0.1.17 / 2010-11-20
 
 * Implemented ActiveRecord adapters that cover MySQL Spatial for the mysql and mysql2 gems. SpatiaLite and PostGIS adapters are coming later.

data/README.rdoc

@@ -9,10 +9,10 @@ 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. A number of features (such as Rails integration)
-are not yet complete, and there are numerous 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.
+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
 
@@ -30,10 +30,10 @@ Use RGeo to:
 * Correctly handle spherical geometry, and compute projections for
   geographic data analysis.
 * Store and retrieve spatial data in industry standard spatial database
-  systems such as PostGIS.
+  systems such as MySQL Spatial, SpatiaLite, and PostGIS.
 * Generate and interpret GeoJSON data for communication with common
-  location-based services; and read and write ESRI shapefiles for
-  interaction with legacy GIS data.
+  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.
@@ -48,6 +48,14 @@ 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/
+* 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
 
@@ -70,26 +78,34 @@ the switches interpreted by the gem command. For example:
 
  gem install rgeo -- --with-geos-dir=/path/to/my/geos/installation
 
-=== Known issues and to-do items
+=== Known issues
 
-RGeo is currently under development and several planned features are not
-yet complete. These include:
+* 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.
 
-* SpatiaLite and PostGIS adapters for ActiveRecord.
+=== 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 ESRI shapefile reading and writing.
-* Projection subsystem, and support for arbitrary projections in the geography module, utilizing proj4.
-* Several more operations on SimpleCartesian and SimpleSpherical.
-* Geography implementation utilizing ellipsoidal geometry, probably utilizing geographiclib.
-* Additional third-party integration, possibly including SimpleGeo, GeoRSS, KML.
+* 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.
 
-Additionally, not all implemented features are well-tested yet. In
-general, we currently consider this library to be "pre-alpha" quality,
-intended for experimentation and feedback but not production. It has been
-deployed in production at GeoPage, but only in a limited capacity.
-
 === Development and support
 
 Documentation is available at http://virtuoso.rubyforge.org/rgeo/README_rdoc.html
@@ -115,6 +131,9 @@ The ActiveRecord adapters owe some debt to the spatial_adapter plugin
 design decisions for RGeo, but studying the spatial_adapter source gave us
 a head start on our implementation.
 
+Although we don't use shapelib (http://shapelib.maptools.org/) to read
+ESRI shapefiles, we did borrow a bunch of their test cases.
+
 === License
 
 Copyright 2010 Daniel Azuma

data/Version

@@ -1 +1 @@
-0.1.17
+0.1.18

data/lib/rgeo.rb

@@ -131,6 +131,7 @@ module RGeo
   autoload(:Geos, 'rgeo/geos')
   autoload(:ImplHelpers, 'rgeo/impl_helpers')
   autoload(:WKRep, 'rgeo/wkrep')
+  autoload(:Shapefile, 'rgeo/shapefile')
   
 end
 

data/lib/rgeo/cartesian.rb

@@ -82,3 +82,4 @@ require 'rgeo/cartesian/feature_methods'
 require 'rgeo/cartesian/feature_classes'
 require 'rgeo/cartesian/factory'
 require 'rgeo/cartesian/interface'
+require 'rgeo/cartesian/analysis'

data/lib/rgeo/cartesian/analysis.rb

@@ -0,0 +1,115 @@
+# -----------------------------------------------------------------------------
+# 
+# Cartesian toplevel interface
+# 
+# -----------------------------------------------------------------------------
+# 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.
+# -----------------------------------------------------------------------------
+;
+
+
+module RGeo
+  
+  module Cartesian
+    
+    
+    module Analysis
+      
+      class << self
+        
+        
+        # Given a LineString, which must be a ring, determine whether the
+        # ring proceeds clockwise or counterclockwise.
+        # Returns 1 for counterclockwise, or -1 for clockwise.
+        # 
+        # Returns 0 if the ring is empty.
+        # The return value is undefined if the object is not a ring, or
+        # is not in a Cartesian coordinate system.
+        
+        def ring_direction(ring_)
+          size_ = ring_.num_points - 1
+          return 0 if size_ == 0
+          
+          # Extract unit-length segments from the ring.
+          segs_ = []
+          size_.times do |i_|
+            p0_ = ring_.point_n(i_)
+            p1_ = ring_.point_n(i_+1)
+            x_ = p1_.x - p0_.x
+            y_ = p1_.y - p0_.y
+            r_ = ::Math.sqrt(x_*x_ + y_*y_)
+            if r_ > 0.0
+              segs_ << x_/r_ << y_/r_
+            end
+          end
+          segs_ << segs_[0] << segs_[1]
+          
+          # Extract angles from the segments by subtracting the segments.
+          # Note angles are represented as cos/sin pairs so we don't
+          # have to calculate any trig functions.
+          angs_ = []
+          size_.times do |i_|
+            x0_, y0_, x1_, y1_ = segs_[i_*2,4]
+            angs_ << x0_*x1_ + y0_*y1_ << x0_*y1_ - x1_*y0_
+          end
+          
+          # Now add the angles and count revolutions.
+          # Again, our running sum is represented as a cos/sin pair.
+          revolutions_ = 0
+          sin_ = 0.0
+          cos_ = 1.0
+          angs_.each_slice(2) do |(x_, y_)|
+            ready_ = y_ > 0.0 && sin_ > 0.0 || y_ < 0.0 && sin_ < 0.0
+            if y_ != 0.0
+              s_ = sin_*x_ + cos_*y_
+              c_ = cos_*x_ - sin_*y_
+              r_ = ::Math.sqrt(s_*s_ + c_*c_)
+              sin_ = s_ / r_
+              cos_ = c_ / r_
+            end
+            if ready_
+              if y_ > 0.0 && sin_ <= 0.0
+                revolutions_ += 1
+              elsif y_ < 0.0 && sin_ >= 0.0
+                revolutions_ -= 1
+              end
+            end
+          end
+          revolutions_
+        end
+        
+        
+      end
+      
+    end
+    
+    
+  end
+  
+end

data/lib/rgeo/cartesian/feature_classes.rb

@@ -48,20 +48,6 @@ module RGeo
       include ::RGeo::ImplHelpers::BasicPointMethods
       
       
-      def _validate_geometry
-        @x = @x % 360.0
-        @x -= 360.0 if @x >= 180.0
-        @y = 90.0 if @y > 90.0
-        @y = -90.0 if @y < -90.0
-        super
-      end
-      
-      
-      def _xyz
-        @xyz ||= PointXYZ.from_latlon(@y, @x)
-      end
-      
-      
       def distance(rhs_)
         rhs_ = ::RGeo::Features.cast(rhs_, @factory)
         case rhs_

data/lib/rgeo/features/factory.rb

@@ -90,12 +90,12 @@ module RGeo
       # 
       # <tt>:z_coordinate</tt>::
       #   Supports a "z" coordinate. When an implementation supports
-      #   z_coordinate, the Factory#epoint and Point#z methods are
-      #   available.
+      #   this capability, geometries know about Z coordinates, and the
+      #   Point#z method is available.
       # <tt>:m_coordinate</tt>::
-      #   Supports a "m" coordinate. When an implementation supports
-      #   m_coordinate, the Factory#epoint and Point#m methods are
-      #   available.
+      #   Supports an "m" coordinate. When an implementation supports
+      #   this capability, geometries know about M coordinates, and the
+      #   Point#m method is available.
       
       def has_capability?(name_)
         nil

data/lib/rgeo/features/factory_generator.rb

@@ -101,6 +101,16 @@ module RGeo
       end
       
       
+      # Return a new FactoryGenerator that calls the given delegate, but
+      # modifies the configuration passed to it. You can provide defaults
+      # for configuration values not explicitly specified, and you can
+      # force certain values to override the given configuration.
+      
+      def self.decorate(delegate_, default_config_={}, force_config_={})
+        ::Proc.new{ |c_| delegate_.call(default_config_.merge(c_).merge(force_config_)) }
+      end
+      
+      
     end
     
     

data/lib/rgeo/geo_json/coder.rb

@@ -47,6 +47,11 @@ module RGeo
     class Coder
       
       
+      @@json_available = nil
+      @@yajl_available = nil
+      @@activesupport_available = nil
+      
+      
       # Create a new coder settings object. The geo factory is passed as
       # a required argument.
       # 
@@ -67,36 +72,60 @@ module RGeo
       #   sole argument and returning the JSON hash, or it may be one of
       #   the special values <tt>:json</tt>, <tt>:yajl</tt>, or
       #   <tt>:active_support</tt>. Setting one of those special values
-      #   will require the corresponding library to be available. The
-      #   default is <tt>:json</tt>, which is present in the standard
+      #   will require the corresponding library to be available. Note
+      #   that the <tt>:json</tt> library is present in the standard
       #   library in Ruby 1.9, but requires the "json" gem in Ruby 1.8.
-      #   If the specified parser is not available, then decode will not
+      #   If a parser is not specified, then the decode method will not
       #   accept a String or IO object; it will require a Hash.
       
       def initialize(opts_={})
         @geo_factory = opts_[:geo_factory] || ::RGeo::Cartesian.preferred_factory
         @entity_factory = opts_[:entity_factory] || EntityFactory.instance
-        @json_parser = opts_[:json_parser] || :json
+        @json_parser = opts_[:json_parser]
         case @json_parser
         when :json
-          begin
-            require 'json'
+          if @@json_available.nil?
+            begin
+              require 'json'
+              @@json_available = true
+            rescue ::LoadError
+              @@json_available = false
+            end
+          end
+          if @@json_available
             @json_parser = ::Proc.new{ |str_| ::JSON.parse(str_) }
-          rescue ::LoadError
+          else
+            raise Errors::RGeoError, "JSON library is not available. You may need to install the 'json' gem."
           end
         when :yajl
-          begin
-            require 'yajl'
+          if @@yajl_available.nil?
+            begin
+              require 'yajl'
+              @@yajl_available = true
+            rescue ::LoadError
+              @@yajl_available = false
+            end
+          end
+          if @@yajl_available
             @json_parser = ::Proc.new{ |str_| ::Yajl::Parser.new.parse(str_) }
-          rescue ::LoadError
+          else
+            raise Errors::RGeoError, "Yajl library is not available. You may need to install the 'yajl' gem."
           end
         when :active_support
-          begin
-            require 'active_support/json'
+          if @@activesupport_available.nil?
+            begin
+              require 'active_support/json'
+              @@activesupport_available = true
+            rescue ::LoadError
+              @@activesupport_available = false
+            end
+          end
+          if @@activesupport_available
             @json_parser = ::Proc.new{ |str_| ::ActiveSupport::JSON.decode(str_) }
-          rescue ::LoadError
+          else
+            raise Errors::RGeoError, "ActiveSupport::JSON library is not available. You may need to install the 'activesupport' gem."
           end
-        when ::Proc
+        when ::Proc, nil
           # Leave as is
         else
           raise ::ArgumentError, "Unrecognzied json_parser: #{@json_parser.inspect}"
@@ -110,6 +139,12 @@ module RGeo
       # Encode the given object as GeoJSON. The object may be one of the
       # geometry objects specified in RGeo::Features, or an appropriate
       # GeoJSON wrapper entity supported by this coder's entity factory.
+      # 
+      # This method returns a JSON object (i.e. a hash). In order to
+      # generate a string suitable for transmitting to a service, you
+      # will need to JSON-encode it. This is usually accomplished by
+      # calling <tt>to_json</tt> on the hash object, if you have the
+      # appropriate JSON library installed.
       
       def encode(object_)
         if @entity_factory.is_feature_collection?(object_)

data/lib/rgeo/geo_json/interface.rb

@@ -78,10 +78,10 @@ module RGeo
       #   sole argument and returning the JSON hash, or it may be one of
       #   the special values <tt>:json</tt>, <tt>:yajl</tt>, or
       #   <tt>:active_support</tt>. Setting one of those special values
-      #   will require the corresponding library to be available. The
-      #   default is <tt>:json</tt>, which is present in the standard
+      #   will require the corresponding library to be available. Note
+      #   that the <tt>:json</tt> library is present in the standard
       #   library in Ruby 1.9, but requires the "json" gem in Ruby 1.8.
-      #   If the specified parser is not available, then decode will not
+      #   If a parser is not specified, then the decode method will not
       #   accept a String or IO object; it will require a Hash.
       
       def decode(input_, opts_={})
@@ -111,10 +111,10 @@ module RGeo
       #   sole argument and returning the JSON hash, or it may be one of
       #   the special values <tt>:json</tt>, <tt>:yajl</tt>, or
       #   <tt>:active_support</tt>. Setting one of those special values
-      #   will require the corresponding library to be available. The
-      #   default is <tt>:json</tt>, which is present in the standard
+      #   will require the corresponding library to be available. Note
+      #   that the <tt>:json</tt> library is present in the standard
       #   library in Ruby 1.9, but requires the "json" gem in Ruby 1.8.
-      #   If the specified parser is not available, then decode will not
+      #   If a parser is not specified, then the decode method will not
       #   accept a String or IO object; it will require a Hash.
       
       def coder(opts_={})

data/lib/rgeo/shapefile.rb

@@ -0,0 +1,60 @@
+# -----------------------------------------------------------------------------
+# 
+# Shapefile processing for RGeo
+# 
+# -----------------------------------------------------------------------------
+# 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.
+# -----------------------------------------------------------------------------
+;
+
+
+# Parent file
+require 'rgeo'
+
+
+module RGeo
+  
+  
+  # This module contains an implementation of ESRI Shapefiles.
+  # Use the Shapefile::Reader class to read a shapefile, extracting
+  # geometry and attribute data from it.
+  # RGeo does not yet have support for writing shapefiles.
+  
+  module Shapefile
+  end
+  
+  
+end
+
+
+# Dependency files
+require 'rgeo/features'
+
+# Implementation files
+require 'rgeo/shapefile/reader'