rgeo 0.1.19 → 0.1.20

data/lib/rgeo/coord_sys/proj4.rb

@@ -0,0 +1,275 @@
+# -----------------------------------------------------------------------------
+# 
+# Proj4 wrapper 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.
+# -----------------------------------------------------------------------------
+;
+
+
+module RGeo
+  
+  module CoordSys
+    
+    
+    # This is a Ruby wrapper around a Proj4 coordinate system.
+    # It represents a single geographic coordinate system, which may be
+    # a flat projection, a geocentric (3-dimensional) coordinate system,
+    # or a geographic (latitude-longitude) coordinate system.
+    # 
+    # Generally, these are used to define the projection for a
+    # Feature::Factory. You can then convert between coordinate systems
+    # by casting geometries between such factories using the :project
+    # option. You may also use this object directly to perform low-level
+    # coordinate transformations.
+    
+    class Proj4
+      
+      
+      def inspect  # :nodoc:
+        "#<#{self.class}:0x#{object_id.to_s(16)} #{_canonical_str.inspect}>"
+      end
+      
+      
+      def to_s  # :nodoc:
+        canonical_str
+      end
+      
+      
+      def hash  # :nodoc:
+        canonical_hash.hash
+      end
+      
+      
+      # Returns true if this Proj4 is equivalent to the given Proj4.
+      # 
+      # Note: this tests for equivalence by comparing only the hash
+      # definitions of the Proj4 objects, and returning true if those
+      # definitions are equivalent. In some cases, this may still return
+      # false even if the actual coordinate systems are identical, since
+      # there are sometimes multiple ways to express a given coordinate
+      # system.
+      
+      def eql?(rhs_)
+        rhs_.is_a?(Proj4) && rhs_._canonical_hash == canonical_hash
+      end
+      
+      
+      # Returns the "canonical" string definition for this coordinate
+      # system, as reported by Proj4. This may be slightly different
+      # from the definition used to construct this object.
+      
+      def canonical_str
+        unless defined?(@canonical_str)
+          @canonical_str = _canonical_str
+        end
+        @canonical_str
+      end
+      
+      
+      # Returns the "canonical" hash definition for this coordinate
+      # system, as reported by Proj4. This may be slightly different
+      # from the definition used to construct this object.
+      
+      def canonical_hash
+        unless defined?(@canonical_hash)
+          @canonical_hash = {}
+          canonical_str.strip.split(/\s+/).each do |elem_|
+            if elem_ =~ /^\+(\w+)(=(\S+))?$/
+              @canonical_hash[$1] = $3
+            end
+          end
+        end
+        @canonical_hash
+      end
+      
+      
+      # Returns the string definition originally used to construct this
+      # object. Returns nil if this object wasn't created by a string
+      # definition; i.e. if it was created using get_geographic.
+      
+      def original_str
+        _original_str
+      end
+      
+      
+      # Returns true if this Proj4 object is a geographic (lat-long)
+      # coordinate system.
+      
+      def geographic?
+        _geographic?
+      end
+      
+      
+      # Returns true if this Proj4 object is a geocentric (3dz)
+      # coordinate system.
+      
+      def geocentric?
+        _geocentric?
+      end
+      
+      
+      # Get the geographic (unprojected lat-long) coordinate system
+      # corresponding to this coordinate system; i.e. the one that uses
+      # the same ellipsoid and datum.
+      
+      def get_geographic
+        _get_geographic
+      end
+      
+      
+      class << self
+        
+        
+        # Returns true if Proj4 is supported in this installation.
+        # If this returns false, the other methods such as create
+        # will not work.
+        
+        def supported?
+          respond_to?(:_create)
+        end
+        
+        
+        # Create a new Proj4 object, given a definition, which may be
+        # either a string or a hash. Returns nil if the given definition
+        # is invalid or Proj4 is not supported.
+        
+        def create(defn_)
+          result_ = nil
+          if supported?
+            if defn_.kind_of?(::Hash)
+              defn_ = defn_.map{ |k_, v_| v_ ? "+#{k_}=#{v_}" : "+#{k_}" }.join(' ')
+            end
+            result_ = _create(defn_)
+            result_ = nil unless result_._valid?
+          end
+          result_
+        end
+        
+        
+        # Create a new Proj4 object, given a definition, which may be
+        # either a string or a hash. Raises Error::UnsupportedCapability
+        # if the given definition is invalid or Proj4 is not supported.
+        
+        def new(defn_)
+          result_ = create(defn_)
+          unless result_
+            raise Error::UnsupportedCapability, "Proj4 not supported in this installation"
+          end
+          result_
+        end
+        
+        
+        # Low-level coordinate transform method.
+        # Transforms the given coordinate (x, y, [z]) from one proj4
+        # coordinate system to another. Returns an array with either two
+        # or three elements.
+        
+        def transform_coords(from_proj_, to_proj_, x_, y_, z_=nil, opts_={})
+          degrees_ = !opts_[:radians]
+          if degrees_ && from_proj_._geographic?
+            x_ *= ImplHelper::Math::RADIANS_PER_DEGREE
+            y_ *= ImplHelper::Math::RADIANS_PER_DEGREE
+          end
+          result_ = _transform_coords(from_proj_, to_proj_, x_, y_, z_)
+          if result_ && degrees_ && to_proj_._geographic?
+            result_[0] *= ImplHelper::Math::DEGREES_PER_RADIAN
+            result_[1] *= ImplHelper::Math::DEGREES_PER_RADIAN
+          end
+          result_
+        end
+        
+        
+        # Low-level geometry transform method.
+        # Transforms the given geometry between the given two projections.
+        # The resulting geometry is constructed using the to_factory.
+        # Any projections associated with the factories themselves are
+        # ignored.
+        
+        def transform(from_proj_, from_geometry_, to_proj_, to_factory_)
+          case from_geometry_
+          when Feature::Point
+            _transform_point(from_proj_, from_geometry_, to_proj_, to_factory_)
+          when Feature::Line
+            to_factory_.line(from_geometry_.points.map{ |p_| transform(from_proj_, p_, to_proj_, to_factory_) })
+          when Feature::LinearRing
+            _transform_linear_ring(from_proj_, from_geometry_, to_proj_, to_factory_)
+          when Feature::LineString
+            to_factory_.line_string(from_geometry_.points.map{ |p_| transform(from_proj_, p_, to_proj_, to_factory_) })
+          when Feature::Polygon
+            _transform_polygon(from_proj_, from_geometry_, to_proj_, to_factory_)
+          when Feature::MultiPoint
+            to_factory_.multi_point(from_geometry_.map{ |p_| _transform_point(from_proj_, p_, to_proj_, to_factory_) })
+          when Feature::MultiLineString
+            to_factory_.multi_line_string(from_geometry_.map{ |g_| transform(from_proj_, g_, to_proj_, to_factory_) })
+          when Feature::MultiPolygon
+            to_factory_.multi_polygon(from_geometry_.map{ |p_| _transform_polygon(from_proj_, p_, to_proj_, to_factory_) })
+          when Feature::GeometryCollection
+            to_factory_.collection(from_geometry_.map{ |g_| transform(from_proj_, g_, to_proj_, to_factory_) })
+          end
+        end
+        
+        
+        def _transform_point(from_proj_, from_point_, to_proj_, to_factory_)  # :nodoc:
+          from_factory_ = from_point_.factory
+          from_has_z_ = from_factory_.has_capability?(:z_coordinate)
+          from_has_m_ = from_factory_.has_capability?(:m_coordinate)
+          to_has_z_ = to_factory_.has_capability?(:z_coordinate)
+          to_has_m_ = to_factory_.has_capability?(:m_coordinate)
+          coords_ = _transform_coords(from_proj_, to_proj_, from_point_.x, from_point_.y,
+                                      from_has_z_ ? from_point_.z : nil)
+          extras_ = []
+          extras_ << coords_[2].to_f if to_has_z_
+          extras_ << from_has_m_ ? from_point_.m : 0.0 if to_has_m_?
+          to_factory_.point(coords_[0], coords_[1], extras_)
+        end
+        
+        
+        def _transform_linear_ring(from_proj_, from_ring_, to_proj_, to_factory_)  # :nodoc:
+          to_factory_.linear_ring(from_ring_.points[0..-2].map{ |p_| transform(from_proj_, p_, to_proj_, to_factory_) })
+        end
+        
+        
+        def _transform_polygon(from_proj_, from_polygon_, to_proj_, to_factory_)  # :nodoc:
+          ext_ = _transform_linear_ring(from_proj_, from_polygon_.exterior_ring, to_proj_, to_factory_)
+          int_ = from_polygon_.interior_rings.map{ |r_| _transform_linear_ring(from_proj_, r_, to_proj_, to_factory_) }
+          to_factory_.polygon(ext_, int_)
+        end
+        
+        
+      end
+      
+      
+    end
+    
+    
+  end
+  
+end

data/lib/rgeo/{errors.rb → error.rb}

@@ -43,21 +43,17 @@ module RGeo
   
   # All RGeo errors are members of this namespace.
   
-  module Errors
+  module Error
     
     # Base class for all RGeo-related exceptions
     class RGeoError < ::RuntimeError
     end
     
-    # The method is unimplemented
-    class MethodUnimplemented < RGeoError
-    end
-    
     # The specified geometry is invalid
     class InvalidGeometry < RGeoError
     end
     
-    # The specified capability is not supported
+    # The specified capability is not supported or not implemented
     class UnsupportedCapability < RGeoError
     end
     
@@ -67,5 +63,8 @@ module RGeo
     
   end
   
+  # Deprecated alias
+  Errors = Error
+  
   
 end

data/lib/rgeo/{features.rb → feature.rb}

@@ -41,7 +41,7 @@ require 'rgeo'
 module RGeo
   
   
-  # The Features namespace contains interfaces and general tools for
+  # The Feature namespace contains interfaces and general tools for
   # implementations of the Open Geospatial Consortium Simple Features
   # Specification (SFS), version 1.1.0.
   # 
@@ -65,31 +65,33 @@ module RGeo
   # itself. The implementation should separately document any such
   # extensions that it may provide.
   
-  module Features
+  module Feature
   end
   
+  # Deprecated alias
+  Features = Feature
+  
   
 end
 
 
 # Dependency files
-require 'rgeo/errors'
+require 'rgeo/error'
 
 # Implementation files
-require 'rgeo/features/factory'
-require 'rgeo/features/types'
-require 'rgeo/features/geometry'
-require 'rgeo/features/point'
-require 'rgeo/features/curve'
-require 'rgeo/features/line_string'
-require 'rgeo/features/linear_ring'
-require 'rgeo/features/line'
-require 'rgeo/features/surface'
-require 'rgeo/features/polygon'
-require 'rgeo/features/geometry_collection'
-require 'rgeo/features/multi_point'
-require 'rgeo/features/multi_curve'
-require 'rgeo/features/multi_line_string'
-require 'rgeo/features/multi_surface'
-require 'rgeo/features/multi_polygon'
-
+require 'rgeo/feature/factory'
+require 'rgeo/feature/types'
+require 'rgeo/feature/geometry'
+require 'rgeo/feature/point'
+require 'rgeo/feature/curve'
+require 'rgeo/feature/line_string'
+require 'rgeo/feature/linear_ring'
+require 'rgeo/feature/line'
+require 'rgeo/feature/surface'
+require 'rgeo/feature/polygon'
+require 'rgeo/feature/geometry_collection'
+require 'rgeo/feature/multi_point'
+require 'rgeo/feature/multi_curve'
+require 'rgeo/feature/multi_line_string'
+require 'rgeo/feature/multi_surface'
+require 'rgeo/feature/multi_polygon'

data/lib/rgeo/{features → feature}/curve.rb

@@ -36,7 +36,7 @@
 
 module RGeo
   
-  module Features
+  module Feature
     
     
     # == SFS 1.1 Description
@@ -88,7 +88,7 @@ module RGeo
       # Returns a floating-point scalar value.
       
       def length
-        raise Errors::MethodUnimplemented
+        raise Error::UnsupportedCapability, "Method Curve#length not defined."
       end
       
       
@@ -101,7 +101,7 @@ module RGeo
       # Returns an object that supports the Point interface.
       
       def start_point
-        raise Errors::MethodUnimplemented
+        raise Error::UnsupportedCapability, "Method Curve#start_point not defined."
       end
       
       
@@ -114,7 +114,7 @@ module RGeo
       # Returns an object that supports the Point interface.
       
       def end_point
-        raise Errors::MethodUnimplemented
+        raise Error::UnsupportedCapability, "Method Curve#end_point not defined."
       end
       
       
@@ -128,7 +128,7 @@ module RGeo
       # specification, which stipulates an integer return value.
       
       def is_closed?
-        raise Errors::MethodUnimplemented
+        raise Error::UnsupportedCapability, "Method Curve#is_closed? not defined."
       end
       
       
@@ -144,7 +144,7 @@ module RGeo
       # specification, which stipulates an integer return value.
       
       def is_ring?
-        raise Errors::MethodUnimplemented
+        raise Error::UnsupportedCapability, "Method Curve#is_ring? not defined."
       end
       
       

data/lib/rgeo/{features → feature}/factory.rb

@@ -36,11 +36,11 @@
 
 module RGeo
   
-  module Features
+  module Feature
     
     
     # This is a standard interface for factories of features.
-    # Generally, each Features implementation will implement these
+    # Generally, each Feature implementation will implement these
     # methods as a standard way to create features.
     # 
     # If the implementation is unable to create the given feature,
@@ -96,6 +96,9 @@ module RGeo
       #   Supports an "m" coordinate. When an implementation supports
       #   this capability, geometries know about M coordinates, and the
       #   Point#m method is available.
+      # <tt>:proj4</tt>::
+      #   Has a proj4-defined projection. When an implementation supports
+      #   this capability, the Factory#proj4 method is available.
       
       def has_capability?(name_)
         nil
@@ -238,7 +241,7 @@ module RGeo
       # 
       # It should return either a casted result object, false, or nil.
       # A nil return value indicates that casting should be forced to
-      # fail (and ::RGeo::Features::cast will return nil).
+      # fail (and ::RGeo::Feature::cast will return nil).
       # A false return value indicates that this method declines to
       # override the casting algorithm, and RGeo should use its default
       # algorithm to cast the object. Therefore, by default, you should
@@ -249,6 +252,19 @@ module RGeo
       end
       
       
+      # This is an optional method that returns a RGeo::CoordSys::Proj4
+      # representing the projection for the coordinate system of features
+      # created by this factory, or nil if there is no such proj4
+      # projection.
+      # 
+      # If a factory supports this method, it should indicate this by
+      # returning true for the <tt>:proj4</tt> capability.
+      
+      def proj4
+        nil
+      end
+      
+      
     end