rgeo 0.1.14 → 0.1.15

data/History.rdoc

@@ -1,3 +1,9 @@
+=== 0.1.15 / 2010-11-08
+
+* Cleanup, fixes, documentation, and partial test coverage in the WKT/WKB implementations.
+* Implemented autoload for the various modules.
+* A few minor fixes.
+
 === 0.1.14 / 2010-11-04
 
 * Introduced capability checking API.

data/Version

@@ -1 +1 @@
-0.1.14
+0.1.15

data/lib/rgeo.rb

@@ -1,6 +1,6 @@
 # -----------------------------------------------------------------------------
 # 
-# RGeo Rakefile
+# RGeo main file
 # 
 # -----------------------------------------------------------------------------
 # Copyright 2010 Daniel Azuma
@@ -34,30 +34,80 @@
 ;
 
 
-# RGeo is a spatial data library for Ruby.
+# RGeo is a spatial data library for Ruby. It focuses on the storage and
+# manipulation of spatial data types such as points, lines, and polygons.
+# 
+# === RGeo Modules
+# 
+# RGeo comprises a number of modules.
 # 
 # The RGeo::Features module contains interface specifications for spatial
 # objects implemented by RGeo. These interfaces closely follow the OGC
-# Simple Features Specifiation (SFS).
+# Simple Features Specifiation (SFS). This module forms the core of RGeo.
 # 
-# The RGeo::Cartesian module provides basic implementations of spatial
-# objects in a Cartesian (flat) coordinate system. There is a pure ruby
-# implementation that provides basic services, and there are bridges to
-# external implementations that support all the SFS operations.
+# 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.
 # 
-# One of these external bridges is provided by the RGeo::Geos module,
-# which wraps the GEOS library to provide a full, high-performance
-# Cartesian geometry implementation.
+# 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. Several different
-# implementations are provided, including one designed for map
-# visualization applications that use Google or Bing maps.
+# 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.
+# 
+# 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
+# EWKT and EWKB representations.
 # 
 # The RGeo::GeoJSON module contains tools for GeoJSON serialization of
-# spatial objects.
+# spatial objects. These tools work with any of the spatial object
+# implementations.
+# 
+# === Loading the library
 # 
-# Future modules in development include:
+# After installing the RGeo gem, you can load the library with:
+#  require 'rgeo'
+# 
+# This will "lazy-load" the modules as they are referenced or needed
+# (using autoload).
+# 
+# If, for performance reasons, or because you want to run RGeo in a
+# multithreaded environment, you wish to eagerly load RGeo, you may do so
+# with:
+#  require 'rgeo/all'
+# 
+# You may also eagerly load individual modules:
+#  require 'rgeo/features'
+#  require 'rgeo/cartesian'
+#  require 'rgeo/geos'
+#  require 'rgeo/geography'
+#  require 'rgeo/geography/simple_mercator'
+#  require 'rgeo/geography/simple_spherical'
+#  require 'rgeo/wkrep'
+#  require 'rgeo/geo_json'
+# 
+# === 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.
@@ -65,23 +115,23 @@
 #   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.
+#   geometric calculations, and support arbitrary map projections
+#   via RGeo::Projection.
 
 module RGeo
+  
+  autoload(:Cartesian, 'rgeo/cartesian')
+  autoload(:Errors, 'rgeo/errors')
+  autoload(:Features, 'rgeo/features')
+  autoload(:GeoJSON, 'rgeo/geo_json')
+  autoload(:Geography, 'rgeo/geography')
+  autoload(:Geos, 'rgeo/geos')
+  autoload(:ImplHelpers, 'rgeo/impl_helpers')
+  autoload(:WKRep, 'rgeo/wkrep')
+  
 end
 
-
-# The source files that should be required by default.
-paths_ = [
-  'version',
-  'errors',
-  'features',
-  'impl_helpers',
-  'wkrep',
-  'geos',
-  'cartesian',
-  'geography',
-  'geo_json',
-]
-paths_.each{ |path_| require "rgeo/#{path_}" }
+require 'rgeo/version'

data/lib/rgeo/all.rb

@@ -0,0 +1,48 @@
+# -----------------------------------------------------------------------------
+# 
+# All RGeo submodules
+# 
+# -----------------------------------------------------------------------------
+# 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'
+
+# Implementation files
+require 'rgeo/errors'
+require 'rgeo/features'
+require 'rgeo/impl_helpers'
+require 'rgeo/wkrep'
+require 'rgeo/geos'
+require 'rgeo/cartesian'
+require 'rgeo/geography/all'
+require 'rgeo/geo_json'

data/lib/rgeo/cartesian.rb

@@ -34,10 +34,35 @@
 ;
 
 
+# Parent file
+require 'rgeo'
+
+
 module RGeo
   
   
-  # The cartesian features module
+  # The Cartesian module provides a simple spatial implementation using
+  # the Cartesian coordinate system. This is the default implementation
+  # used by RGeo if no full-featured implementation, such as Geos, is
+  # available.
+  # 
+  # The Cartesian implementation can handle all the SFS 1.1 types, and
+  # provides extensions for Z and M coordinates. It also provides WKT
+  # and WKB serialization using the WKRep module.
+  # 
+  # However, the Cartesian implementation does not implement many of
+  # the more advanced geometric operations. Limitations include:
+  # * relational operators such as Features::Geometry#intersects? are
+  #   not implemented for most types.
+  # * relational constructors such as Features::Geometry#union are
+  #   not implemented for most types.
+  # * buffer, boundary, and convex hull calculation are not implemented
+  #   for most types.
+  # * distance and area calculation are not implemented for most types,
+  #   though length for LineStrings is implemented.
+  # * equality and simplicity evaluation are implemented for some types
+  #   but not all types.
+  # * assertions for polygons and multipolygons are not implemented.
   
   module Cartesian
   end
@@ -46,14 +71,14 @@ module RGeo
 end
 
 
-# Dependency source files.
-paths_ = [
-  'features',
-  'geos',
-  'cartesian/calculations',
-  'cartesian/simple_feature_methods',
-  'cartesian/simple_feature_classes',
-  'cartesian/simple_factory',
-  'cartesian/interface',
-]
-paths_.each{ |path_| require "rgeo/#{path_}" }
+# Dependency files.
+require 'rgeo/features'
+require 'rgeo/wkrep'
+require 'rgeo/impl_helpers'
+
+# Implementation files.
+require 'rgeo/cartesian/calculations'
+require 'rgeo/cartesian/feature_methods'
+require 'rgeo/cartesian/feature_classes'
+require 'rgeo/cartesian/factory'
+require 'rgeo/cartesian/interface'

data/lib/rgeo/cartesian/calculations.rb

@@ -121,6 +121,11 @@ module RGeo
       end
       
       
+      def length
+        ::Math.sqrt(@lensq)
+      end
+      
+      
     end
     
     

data/lib/rgeo/cartesian/{simple_factory.rb → factory.rb}

@@ -42,18 +42,14 @@ module RGeo
     # This class implements the factory for the simple cartesian
     # implementation.
     
-    class SimpleFactory
+    class Factory
       
       include Features::Factory::Instance
       
       
       # Create a new simple cartesian factory.
       # 
-      # Options supported are:
-      # 
-      # <tt>:srid</tt>::
-      #   The SRID reported by features created by this factory.
-      #   Default is 0.
+      # See ::RGeo::Cartesian::simple_factory for a list of supported options.
       
       def initialize(opts_={})
         @srid = opts_[:srid].to_i
@@ -94,82 +90,83 @@ module RGeo
       # See ::RGeo::Features::Factory#parse_wkt
       
       def parse_wkt(str_)
-        WKRep::WKTParser.new(self, :support_higher_dimensions => true).parse(str_)
+        ::RGeo::WKRep::WKTParser.new(:default_factory => self).parse(str_)
       end
       
       
       # See ::RGeo::Features::Factory#parse_wkb
       
       def parse_wkb(str_)
-        WKRep::WKBParser.new(self).parse(str_)
+        ::RGeo::WKRep::WKBParser.new(:default_factory => self).parse(str_)
       end
       
       
       # See ::RGeo::Features::Factory#point
       
       def point(x_, y_, *extra_)
-        SimplePointImpl.new(self, x_, y_, *extra_) rescue nil
+        PointImpl.new(self, x_, y_, *extra_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#line_string
       
       def line_string(points_)
-        SimpleLineStringImpl.new(self, points_) rescue nil
+        LineStringImpl.new(self, points_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#line
       
       def line(start_, end_)
-        SimpleLineImpl.new(self, start_, end_) rescue nil
+        LineImpl.new(self, start_, end_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#linear_ring
       
       def linear_ring(points_)
-        SimpleLinearRingImpl.new(self, points_) rescue nil
+        LinearRingImpl.new(self, points_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#polygon
       
       def polygon(outer_ring_, inner_rings_=nil)
-        SimplePolygonImpl.new(self, outer_ring_, inner_rings_) rescue nil
+        PolygonImpl.new(self, outer_ring_, inner_rings_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#collection
       
       def collection(elems_)
-        SimpleGeometryCollectionImpl.new(self, elems_) rescue nil
+        GeometryCollectionImpl.new(self, elems_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#multi_point
       
       def multi_point(elems_)
-        SimpleMultiPointImpl.new(self, elems_) rescue nil
+        MultiPointImpl.new(self, elems_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#multi_line_string
       
       def multi_line_string(elems_)
-        SimpleMultiLineStringImpl.new(self, elems_) rescue nil
+        MultiLineStringImpl.new(self, elems_) rescue nil
       end
       
       
       # See ::RGeo::Features::Factory#multi_polygon
       
       def multi_polygon(elems_)
-        SimpleMultiPolygonImpl.new(self, elems_) rescue nil
+        MultiPolygonImpl.new(self, elems_) rescue nil
       end
       
       
     end
     
+    
   end
   
 end

data/lib/rgeo/cartesian/{simple_feature_classes.rb → feature_classes.rb}

@@ -39,13 +39,13 @@ module RGeo
   module Cartesian
     
     
-    class SimplePointImpl  # :nodoc:
+    class PointImpl  # :nodoc:
       
       
-      include Features::Point
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicPointMethods
+      include ::RGeo::Features::Point
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicPointMethods
       
       
       def _validate_geometry
@@ -63,9 +63,9 @@ module RGeo
       
       
       def distance(rhs_)
-        rhs_ = Features.cast(rhs_, @factory)
+        rhs_ = ::RGeo::Features.cast(rhs_, @factory)
         case rhs_
-        when SimplePointImpl
+        when PointImpl
           dx_ = @x - rhs_.x
           dy_ = @y - rhs_.y
           ::Math.sqrt(dx_ * dx_ + dy_ * dy_)
@@ -78,105 +78,105 @@ module RGeo
     end
     
     
-    class SimpleLineStringImpl  # :nodoc:
+    class LineStringImpl  # :nodoc:
       
       
-      include Features::LineString
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicLineStringMethods
-      include Cartesian::SimpleLineStringMethods
+      include ::RGeo::Features::LineString
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicLineStringMethods
+      include ::RGeo::Cartesian::LineStringMethods
       
       
     end
     
     
-    class SimpleLineImpl  # :nodoc:
+    class LineImpl  # :nodoc:
       
       
-      include Features::Line
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicLineStringMethods
-      include Cartesian::SimpleLineStringMethods
-      include ImplHelpers::BasicLineMethods
+      include ::RGeo::Features::Line
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicLineStringMethods
+      include ::RGeo::Cartesian::LineStringMethods
+      include ::RGeo::ImplHelpers::BasicLineMethods
       
       
     end
     
     
-    class SimpleLinearRingImpl  # :nodoc:
+    class LinearRingImpl  # :nodoc:
       
       
-      include Features::Line
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicLineStringMethods
-      include Cartesian::SimpleLineStringMethods
-      include ImplHelpers::BasicLinearRingMethods
+      include ::RGeo::Features::Line
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicLineStringMethods
+      include ::RGeo::Cartesian::LineStringMethods
+      include ::RGeo::ImplHelpers::BasicLinearRingMethods
       
       
     end
     
     
-    class SimplePolygonImpl  # :nodoc:
+    class PolygonImpl  # :nodoc:
       
       
-      include Features::Polygon
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicPolygonMethods
+      include ::RGeo::Features::Polygon
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicPolygonMethods
       
       
     end
     
     
-    class SimpleGeometryCollectionImpl  # :nodoc:
+    class GeometryCollectionImpl  # :nodoc:
       
       
-      include Features::GeometryCollection
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicGeometryCollectionMethods
+      include ::RGeo::Features::GeometryCollection
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicGeometryCollectionMethods
       
       
     end
     
     
-    class SimpleMultiPointImpl  # :nodoc:
+    class MultiPointImpl  # :nodoc:
       
       
-      include Features::GeometryCollection
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicGeometryCollectionMethods
-      include ImplHelpers::BasicMultiPointMethods
+      include ::RGeo::Features::GeometryCollection
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicGeometryCollectionMethods
+      include ::RGeo::ImplHelpers::BasicMultiPointMethods
       
       
     end
     
     
-    class SimpleMultiLineStringImpl  # :nodoc:
+    class MultiLineStringImpl  # :nodoc:
       
       
-      include Features::GeometryCollection
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicGeometryCollectionMethods
-      include ImplHelpers::BasicMultiLineStringMethods
+      include ::RGeo::Features::GeometryCollection
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicGeometryCollectionMethods
+      include ::RGeo::ImplHelpers::BasicMultiLineStringMethods
       
       
     end
     
     
-    class SimpleMultiPolygonImpl  # :nodoc:
+    class MultiPolygonImpl  # :nodoc:
       
       
-      include Features::GeometryCollection
-      include ImplHelpers::BasicGeometryMethods
-      include Cartesian::SimpleGeometryMethods
-      include ImplHelpers::BasicGeometryCollectionMethods
-      include ImplHelpers::BasicMultiPolygonMethods
+      include ::RGeo::Features::GeometryCollection
+      include ::RGeo::ImplHelpers::BasicGeometryMethods
+      include ::RGeo::Cartesian::GeometryMethods
+      include ::RGeo::ImplHelpers::BasicGeometryCollectionMethods
+      include ::RGeo::ImplHelpers::BasicMultiPolygonMethods
       
       
     end