rgeo 0.2.2 → 0.2.3

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 0.2.3 / 2010-12-19
+
+* The "simpler mercator" geographic type incorrectly reported EPSG 3857 instead of EPSG 3785 for the projection. Dyslexia fixed.
+* Geographic types couldn't have their coord_sys set. Fixed.
+* You can now pass an :srs_database option when creating most factory types. This lets the factory look up its coordinate system using the given SRID.
+* There are now explicit methods you can call to obtain FactoryGenerator objects; you should not need to call <tt>method</tt>.
+* Wrote RDocs for all the CoordSys::CS and CoordSys::SRSDatabase classes.
+
 === 0.2.2 / 2010-12-15
 
 The main theme for this release was support for spatial reference system databases. The basic functionality is done and ready for experimentation. However, documentation is still in progress, and we're still working on some ideas to make coordinate system management more seamless by integrating the SRS databases with FactoryGenerator.

data/README.rdoc

@@ -47,7 +47,7 @@ RGeo is known to work with the following Ruby implementations:
 * Rubinius 1.1 or later.
 * Partial support for JRuby 1.5 or later, but a bunch of features are
   missing because GEOS and Proj are not available from Java. We plan on
-  integrating with JTS in the future.
+  integrating with JTS or possibly ffi-geos in the future.
 
 Some features also require the following:
 
@@ -107,7 +107,7 @@ The RGeo suite of tools is evolving rapidly. The current to-do list for
 the core library includes:
 
 * Ellipsoidal geography implementation, possibly utilizing geographiclib.
-* JRuby support via the JTS library.
+* JRuby support via the JTS library, or possibly via ffi-geos.
 * Windows build support.
 
 Each of the current add-on modules also has its own feature roadmap, and

data/Version

@@ -1 +1 @@
-0.2.2
+0.2.3

data/lib/rgeo/cartesian/factory.rb

@@ -52,7 +52,6 @@ module RGeo
       # See ::RGeo::Cartesian::simple_factory for a list of supported options.
       
       def initialize(opts_={})
-        @srid = opts_[:srid].to_i
         @has_z = opts_[:has_z_coordinate] ? true : false
         @has_m = opts_[:has_m_coordinate] ? true : false
         @proj4 = opts_[:proj4]
@@ -63,10 +62,20 @@ module RGeo
         else
           @proj4 = nil
         end
+        srid_ = opts_[:srid]
         @coord_sys = opts_[:coord_sys]
         if @coord_sys.kind_of?(::String)
           @coord_sys = CoordSys::CS.create_from_wkt(@coord_sys) rescue nil
         end
+        if (!@proj4 || !@coord_sys) && srid_ && (db_ = opts_[:srs_database])
+          entry_ = db_.get(srid_.to_i)
+          if entry_
+            @proj4 ||= entry_.proj4
+            @coord_sys ||= entry_.coord_sys
+          end
+        end
+        srid_ ||= @coord_sys.authority_code if @coord_sys
+        @srid = srid_.to_i
       end
       
       

data/lib/rgeo/cartesian/interface.rb

@@ -49,10 +49,13 @@ module RGeo
       # RGeo will try to provide a fully-functional and performant
       # implementation if possible. If not, the simple Cartesian
       # implementation will be returned.
+      # In practice, this means it returns a Geos implementation if
+      # available; otherwise it falls back to the simple implementation.
       # 
       # The given options are passed to the factory's constructor.
       # What options are available depends on the particular
-      # implementation. Unsupported options are ignored.
+      # implementation. See Geos::factory and Cartesian::simple_factory
+      # for details. Unsupported options are ignored.
       
       def preferred_factory(opts_={})
         if ::RGeo::Geos.supported?
@@ -82,13 +85,27 @@ module RGeo
       #   not all types.
       # * Assertions for polygons and multipolygons are not implemented.
       # 
-      # Unimplemented operations will return nil if invoked.
+      # Unimplemented operations may raise Error::UnsupportedOperation
+      # if invoked.
       # 
       # Options include:
       # 
       # <tt>:srid</tt>::
       #   Set the SRID returned by geometries created by this factory.
       #   Default is 0.
+      # <tt>:proj4</tt>::
+      #   The coordinate system in Proj4 format, either as a
+      #   CoordSys::Proj4 object or as a string or hash representing the
+      #   proj4 format. Optional.
+      # <tt>:coord_sys</tt>::
+      #   The coordinate system in OGC form, either as a subclass of
+      #   CoordSys::CS::CoordinateSystem, or as a string in WKT format.
+      #   Optional.
+      # <tt>:srs_database</tt>::
+      #   Optional. If provided, the value should be an implementation of
+      #   CoordSys::SRSDatabase::Interface. If both this and an SRID are
+      #   provided, they are used to look up the proj4 and coord_sys
+      #   objects from a spatial reference system database.
       # <tt>:has_z_coordinate</tt>::
       #   Support a Z coordinate. Default is false.
       # <tt>:has_m_coordinate</tt>::
@@ -99,6 +116,33 @@ module RGeo
       end
       
       
+      # Returns a Feature::FactoryGenerator that creates preferred
+      # factories. The given options are used as the default options.
+      # 
+      # A common case for this is to provide the <tt>:srs_database</tt>
+      # as a default. Then, the factory generator need only be passed
+      # an SRID and it will automatically fetch the appropriate Proj4
+      # and CoordSys objects.
+      
+      def preferred_factory_generator(defaults_={})
+        ::Proc.new{ |c_| preferred_factory(defaults_.merge(c_)) }
+      end
+      alias_method :factory_generator, :preferred_factory_generator
+      
+      
+      # Returns a Feature::FactoryGenerator that creates simple factories.
+      # The given options are used as the default options.
+      # 
+      # A common case for this is to provide the <tt>:srs_database</tt>
+      # as a default. Then, the factory generator need only be passed
+      # an SRID and it will automatically fetch the appropriate Proj4
+      # and CoordSys objects.
+      
+      def simple_factory_generator(defaults_={})
+        ::Proc.new{ |c_| simple_factory(defaults_.merge(c_)) }
+      end
+      
+      
     end
     
   end

data/lib/rgeo/coord_sys/cs/entities.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 # -----------------------------------------------------------------------------
 # 
 # OGC CS objects for RGeo
@@ -42,57 +43,174 @@ module RGeo
     module CS
       
       
+      # An axis orientation constant for AxisInfo.
+      # Unknown or unspecified axis orientation. This can be used for
+      # local or fitted coordinate systems.
       AO_OTHER = 0
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go North. This is usually used for
+      # Grid Y coordinates and Latitude.
       AO_NORTH = 1
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go South. This is rarely used.
       AO_SOUTH = 2
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go East. This is rarely used.
       AO_EAST = 3
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go West. This is usually used for
+      # Grid X coordinates and Longitude.
       AO_WEST = 4
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go up. This is used for vertical
+      # coordinate systems.
       AO_UP = 5
+      
+      # An axis orientation constant for AxisInfo.
+      # Increasing ordinates values go down. This is used for vertical
+      # coordinate systems.
       AO_DOWN = 6
       
+      
+      # A datum type constant for HorizontalDatum.
+      # Lowest possible value for horizontal datum types.
       HD_MIN = 1000
+      
+      # A datum type constant for HorizontalDatum.
+      # Unspecified horizontal datum type. Horizontal datums with this
+      # type should never supply a conversion to WGS84 using Bursa Wolf
+      # parameters.
       HD_OTHER = 1000
+      
+      # A datum type constant for HorizontalDatum.
+      # These datums, such as ED50, NAD27 and NAD83, have been designed
+      # to support horizontal positions on the ellipsoid as opposed to
+      # positions in 3-D space. These datums were designed mainly to
+      # support a horizontal component of a position in a domain of
+      # limited extent, such as a country, a region or a continent.
       HD_CLASSIC = 1001
+      
+      # A datum type constant for HorizontalDatum.
+      # A geocentric datum is a "satellite age" modern geodetic datum
+      # mainly of global extent, such as WGS84 (used in GPS), PZ90 (used
+      # in GLONASS) and ITRF. These datums were designed to support both
+      # a horizontal component of position and a vertical component of
+      # position (through ellipsoidal heights). The regional realizations
+      # of ITRF, such as ETRF, are also included in this category.
       HD_GEOCENTRIC = 1002
+      
+      # A datum type constant for HorizontalDatum.
+      # Highest possible value for horizontal datum types.
       HD_MAX = 1999
+      
+      # A datum type constant for VerticalDatum.
+      # Lowest possible value for vertical datum types.
       VD_MIN = 2000
+      
+      # A datum type constant for VerticalDatum.
+      # Unspecified vertical datum type.
       VD_OTHER = 2000
+      
+      # A datum type constant for VerticalDatum.
+      # A vertical datum for orthometric heights that are measured along
+      # the plumb line.
       VD_ORTHOMETRIC = 2001
+      
+      # A datum type constant for VerticalDatum.
+      # A vertical datum for ellipsoidal heights that are measured along
+      # the normal to the ellipsoid used in the definition of horizontal
+      # datum.
       VD_ELLIPSOIDAL = 2002
+      
+      # A datum type constant for VerticalDatum.
+      # The vertical datum of altitudes or heights in the atmosphere.
+      # These are approximations of orthometric heights obtained with the
+      # help of a barometer or a barometric altimeter. These values are
+      # usually expressed in one of the following units: meters, feet,
+      # millibars (used to measure pressure levels), or theta value (units
+      # used to measure geopotential height).
       VD_ALTITUDE_BAROMETRIC = 2003
+      
+      # A datum type constant for VerticalDatum.
+      # A normal height system.
       VD_NORMAL = 2004
+      
+      # A datum type constant for VerticalDatum.
+      # A vertical datum of geoid model derived heights, also called
+      # GPS-derived heights. These heights are approximations of
+      # orthometric heights (H), constructed from the ellipsoidal heights
+      # (h) by the use of the given geoid undulation model (N) through
+      # the equation: H=h-N.
       VD_GEOID_MODE_DERIVED = 2005
+      
+      # A datum type constant for VerticalDatum.
+      # This attribute is used to support the set of datums generated for
+      # hydrographic engineering projects where depth measurements below
+      # sea level are needed. It is often called a hydrographic or a
+      # marine datum. Depths are measured in the direction perpendicular
+      # (approximately) to the actual equipotential surfaces of the
+      # earth's gravity field, using such procedures as echo-sounding.
       VD_DEPTH = 2006
+      
+      # A datum type constant for VerticalDatum.
+      # Highest possible value for vertical datum types.
       VD_MAX = 2999
+      
+      # A datum type constant for LocalDatum.
+      # Lowest possible value for local datum types.
       LD_MIN = 10000
+      
+      # A datum type constant for LocalDatum.
+      # Highest possible value for local datum types.
       LD_MAX = 32767
       
       
+      # This is a base class for all OGC coordinate system objects.
+      # This includes both interfaces and data types from the OGC
+      # Coordinate Transformation spec.
+      # 
+      # This is a non-instantiable abstract class.
+      
       class Base
         
-        def initialize(name_)  # :nodoc:
-          @name = name_.to_s
-        end
-        
-        attr_reader :name
         
-        def inspect
+        def inspect  # :nodoc:
           "#<#{self.class}:0x#{object_id.to_s(16)} #{to_wkt}>"
         end
         
+        
+        # Tests for equality. Two objects are defined as equal if they
+        # have the same type (class) and the same WKT representation.
+        
         def eql?(rhs_)
           rhs_.class == self.class && rhs_.to_wkt == self.to_wkt
         end
         alias_method :==, :eql?
         
+        
+        # Returns the default WKT representation.
+        
         def to_s
           to_wkt
         end
         
+        
+        # Computes the WKT representation. Options include:
+        # 
+        # <tt>:standard_brackets</tt>::
+        #   If set to true, outputs parentheses rather than square
+        #   brackets. Default is false.
+        
         def to_wkt(opts_={})
           opts_[:standard_brackets] ? _to_wkt('(', ')') : _to_wkt('[', ']')
         end
         
+        
         def _to_wkt(open_, close_)  # :nodoc:
           content_ = _wkt_content(open_, close_).map{ |obj_| ",#{obj_}" }.join
           if defined?(@authority) && @authority
@@ -103,30 +221,47 @@ module RGeo
           "#{_wkt_typename}#{open_}#{@name.inspect}#{content_}#{authority_}#{close_}"
         end
         
+        
         class << self
           
           private :new
           
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # Details of axis. This is used to label axes, and indicate the
+      # orientation.
+      
       class AxisInfo < Base
         
+        # :stopdoc:
         NAMES_BY_VALUE = ['OTHER', 'NORTH', 'SOUTH', 'EAST', 'WEST', 'UP', 'DOWN']
+        # :startdoc:
         
         def initialize(name_, orientation_)  # :nodoc:
-          super(name_)
-          if orientation_.kind_of?(::String)
-            @orientation = NAMES_BY_VALUE.index(orientation_).to_i
+          @name = name_
+          case orientation_
+          when ::String, ::Symbol
+            @orientation = NAMES_BY_VALUE.index(orientation_.to_s.upcase).to_i
           else
             @orientation = orientation_.to_i
           end
         end
         
+        
+        # Human readable name for axis. Possible values are "X", "Y",
+        # "Long", "Lat" or any other short string.
+        attr_reader :name
+        
+        # Gets enumerated value for orientation.
         attr_reader :orientation
         
+        
         def _wkt_typename  # :nodoc:
           "AXIS"
         end
@@ -135,26 +270,51 @@ module RGeo
           [NAMES_BY_VALUE[@orientation]]
         end
         
+        
         class << self
           
+          
+          # Creates an AxisInfo. you must pass the human readable name for
+          # the axis (e.g. "X", "Y", "Long", "Lat", or other short string)
+          # and either an integer orientation code or a string. Possible
+          # orientation values are "<tt>OTHER</tt>", "<tt>NORTH</tt>",
+          # "<tt>SOUTH</tt>", "<tt>EAST</tt>", "<tt>WEST</tt>",
+          # "<tt>UP</tt>", and "<tt>DOWN</tt>", or the corresponding
+          # integer values 0-5.
+          
           def create(name_, orientation_)
             new(name_, orientation_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A named projection parameter value. The linear units of
+      # parameters' values match the linear units of the containing
+      # projected coordinate system. The angular units of parameter
+      # values match the angular units of the geographic coordinate
+      # system that the projected coordinate system is based on.
+      
       class ProjectionParameter < Base
         
         def initialize(name_, value_)  # :nodoc:
-          super(name_)
+          @name = name_
           @value = value_.to_f
         end
         
+        
+        # The parameter name.
+        attr_reader :name
+        
+        # The parameter value.
         attr_reader :value
         
+        
         def _wkt_typename  # :nodoc:
           "PARAMETER"
         end
@@ -163,21 +323,32 @@ module RGeo
           [@value]
         end
         
+        
         class << self
           
+          
+          # Create a parameter given the name and value.
+          
           def create(name_, value_)
             new(name_, value_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Parameters for a geographic transformation into WGS84. The Bursa
+      # Wolf parameters should be applied to geocentric coordinates, where
+      # the X axis points towards the Greenwich Prime Meridian, the Y axis
+      # points East, and the Z axis points North.
+      
       class WGS84ConversionInfo < Base
         
         def initialize(dx_, dy_, dz_, ex_, ey_, ez_, ppm_)  # :nodoc:
-          super('TOWGS84')
           @dx = dx_.to_f
           @dy = dy_.to_f
           @dz = dz_.to_f
@@ -187,33 +358,94 @@ module RGeo
           @ppm = ppm_.to_f
         end
         
+        
+        # Bursa Wolf shift in meters.
         attr_reader :dx
+        
+        # Bursa Wolf shift in meters.
         attr_reader :dy
+        
+        # Bursa Wolf shift in meters.
         attr_reader :dz
+        
+        # Bursa Wolf rotation in arc seconds.
         attr_reader :ex
+        
+        # Bursa Wolf rotation in arc seconds.
         attr_reader :ey
+        
+        # Bursa Wolf rotation in arc seconds.
         attr_reader :ez
+        
+        # Bursa Wolf scaling in in parts per million.
         attr_reader :ppm
         
+        
         def _to_wkt(open_, close_)  # :nodoc:
           "TOWGS84#{open_}#{@dx},#{@dy},#{@dz},#{@ex},#{@ey},#{@ez},#{@ppm}#{close_}"
         end
         
+        
         class << self
           
+          
+          # Create the horizontal datum shift transformation into WGS84,
+          # given the seven Bursa Wolf parameters.
+          # The Bursa Wolf shift should be in meters, the rotation in arc
+          # seconds, and the scaling in parts per million.
+          
           def create(dx_, dy_, dz_, ex_, ey_, ez_, ppm_)
             new(dx_, dy_, dz_, ex_, ey_, ez_, ppm_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A base interface for metadata applicable to coordinate system
+      # objects.
+      # 
+      # The metadata items "Abbreviation"’, "Alias", "Authority",
+      # "AuthorityCode", "Name" and "Remarks" were specified in the Simple
+      # Features interfaces, so they have been kept here.
+      # 
+      # This specification does not dictate what the contents of these
+      # items should be. However, the following guidelines are suggested:
+      # 
+      # When CS_CoordinateSystemAuthorityFactory is used to create an
+      # object, the "Authority" and "AuthorityCode" values should be set
+      # to the authority name of the factory object, and the authority
+      # code supplied by the client, respectively. The other values may or
+      # may not be set. (If the authority is EPSG, the implementer may
+      # consider using the corresponding metadata values in the EPSG
+      # tables.)
+      # 
+      # When CS_CoordinateSystemFactory creates an object, the "Name"
+      # should be set to the value supplied by the client. All of the
+      # other metadata items should be left empty.
+      # 
+      # == Notes
+      # 
+      # This is a non-instantiable abstract class.
+      # 
+      # Most subclasses will have a set of optional parameters in their
+      # "create" method to set the metadata fields. These parameters are,
+      # in order:
+      # 
+      # * <b>authority</b>: authority name
+      # * <b>authority_code</b>: authority-specific identification code
+      # * <b>abbreviation</b>: an abbreviation
+      # * <b>alias</b>: an alias
+      # * <b>remarks</b>: provider-supplied remarks.
+      
       class Info < Base
         
         def initialize(name_, authority_=nil, authority_code_=nil, abbreviation_=nil, alias_=nil, remarks_=nil)  # :nodoc:
-          super(name_)
+          @name = name_
           @authority = authority_ ? authority_.to_s : nil
           @authority_code = authority_code_ ? authority_code_.to_s : nil
           @abbreviation = abbreviation_ ? abbreviation_.to_s : nil
@@ -221,15 +453,51 @@ module RGeo
           @remarks = remarks_ ? remarks_.to_s : nil
         end
         
-        attr_reader :authority
-        attr_reader :authority_code
+        
+        # Gets the abbreviation.
         attr_reader :abbreviation
+        
+        # Gets the alias.
         attr_reader :alias
+        
+        # Gets the authority name.
+        # An Authority is an organization that maintains definitions of
+        # Authority Codes. For example the European Petroleum Survey Group
+        # (EPSG) maintains a database of coordinate systems, and other
+        # spatial referencing objects, where each object has a code number
+        # ID. For example, the EPSG code for a WGS84 Lat/Lon coordinate
+        # system is "4326".
+        attr_reader :authority
+        
+        # Gets the authority-specific identification code.
+        # The AuthorityCode is a compact string defined by an Authority to
+        # reference a particular spatial reference object. For example,
+        # the European Survey Group (EPSG) authority uses 32 bit integers
+        # to reference coordinate systems, so all their code strings will
+        # consist of a few digits. The EPSG code for WGS84 Lat/Lon is
+        # "4326".
+        attr_reader :authority_code
+        
+        # Gets the name.
+        attr_reader :name
+        
+        # Gets the provider-supplied remarks.
         attr_reader :remarks
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # Base interface for defining units.
+      # 
+      # == Notes
+      # 
+      # Normally, you will instantiate one of the subclasses LinearUnit or
+      # AngularUnit. However, it is possible to instantiate Unit if it is
+      # not clear whether the data refers to a LinearUnit or AngularUnit.
+      
       class Unit < Info
         
         def initialize(name_, conversion_factor_, *optional_)  # :nodoc:
@@ -237,8 +505,13 @@ module RGeo
           @conversion_factor = conversion_factor_.to_f
         end
         
+        
+        # This field is not part of the OGC CT spec, but is part of the
+        # SFS. It is an alias of the appropriate field in the subclass,
+        # i.e. LinearUnit#meters_per_unit or AngularUnit#radians_per_unit.
         attr_reader :conversion_factor
         
+        
         def _wkt_typename  # :nodoc:
           "UNIT"
         end
@@ -247,47 +520,93 @@ module RGeo
           [@conversion_factor]
         end
         
+        
         class << self
           
+          
+          # Create a bare Unit that does not specify whether it is a
+          # LinearUnit or an AngularUnit, given a unit name and a
+          # conversion factor. You may also provide the optional
+          # parameters specified by the Info interface.
+          
           def create(name_, conversion_factor_, *optional_)
             new(name_, conversion_factor_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Definition of linear units.
+      
       class LinearUnit < Unit
         
-        alias_method :meters_per_unit, :conversion_factor
+        
+        # Returns the number of meters per LinearUnit.
+        # Also available as Unit#conversion_factor.
+        
+        def meters_per_unit
+          @conversion_factor
+        end
+        
         
         class << self
           
+          
+          # Create a LinearUnit given a unit name and a conversion factor
+          # in meters per unit. You may also provide the optional
+          # parameters specified by the Info interface.
+          
           def create(name_, meters_per_unit_, *optional_)
             new(name_, meters_per_unit_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Definition of angular units.
+      
       class AngularUnit < Unit
         
-        alias_method :radians_per_unit, :conversion_factor
+        
+        # Returns the number of radians per AngularUnit.
+        # Also available as Unit#conversion_factor.
+        
+        def radians_per_unit
+          @conversion_factor
+        end
+        
         
         class << self
           
+          
+          # Create an AngularUnit given a unit name and a conversion
+          # factor in radians per unit. You may also provide the optional
+          # parameters specified by the Info interface.
+          
           def create(name_, radians_per_unit_, *optional_)
             new(name_, radians_per_unit_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A meridian used to take longitude measurements from.
+      
       class PrimeMeridian < Info
         
         def initialize(name_, angular_unit_, longitude_, *optional_)  # :nodoc:
@@ -296,9 +615,15 @@ module RGeo
           @longitude = longitude_.to_f
         end
         
+        
+        # Returns the AngularUnits.
         attr_reader :angular_unit
+        
+        # Returns the longitude value relative to the Greenwich Meridian.
+        # The longitude is expressed in this objects angular units.
         attr_reader :longitude
         
+        
         def _wkt_typename  # :nodoc:
           "PRIMEM"
         end
@@ -307,17 +632,30 @@ module RGeo
           [@longitude]
         end
         
+        
         class << self
           
+          
+          # Create a PrimeMeridian given a name, AngularUnits, and the
+          # longitude relative to the Greenwich Meridian, expressed in
+          # the AngularUnits. You may also provide the optional parameters
+          # specified by the Info interface.
+          
           def create(name_, angular_unit_, longitude_, *optional_)
             new(name_, angular_unit_, longitude_, *optional_)
           end
           
+          
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # An approximation of the Earth's surface as a squashed sphere.
+      
       class Ellipsoid < Info
         
         def initialize(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, ivf_definitive_, linear_unit_, *optional_)  # :nodoc:
@@ -329,11 +667,32 @@ module RGeo
           @linear_unit = linear_unit_
         end
         
+        
+        # Gets the equatorial radius. The returned length is expressed in
+        # this object's axis units.
         attr_reader :semi_major_axis
+        
+        # Gets the polar radius. The returned length is expressed in this
+        # object's axis units.
         attr_reader :semi_minor_axis
+        
+        # Returns the value of the inverse of the flattening constant. The
+        # inverse flattening is related to the equatorial/polar radius by
+        # the formula ivf=re/(re-rp). For perfect spheres, this formula
+        # breaks down, and a special IVF value of zero is used.
         attr_reader :inverse_flattening
+        
+        # Is the Inverse Flattening definitive for this ellipsoid? Some
+        # ellipsoids use the IVF as the defining value, and calculate the
+        # polar radius whenever asked. Other ellipsoids use the polar
+        # radius to calculate the IVF whenever asked. This distinction can
+        # be important to avoid floating-point rounding errors.
         attr_reader :ivf_definitive
-        attr_reader :linear_unit
+        
+        # Returns the LinearUnit. The units of the semi-major and
+        # semi-minor axis values.
+        attr_reader :axis_unit
+        
         
         def _wkt_typename  # :nodoc:
           "SPHEROID"
@@ -343,33 +702,77 @@ module RGeo
           [@semi_major_axis, @inverse_flattening]
         end
         
-        def self.create_ellipsoid(name_, semi_major_axis_, semi_minor_axis_, linear_unit_, *optional_)
-          semi_major_axis_ = semi_major_axis_.to_f
-          semi_minor_axis_ = semi_minor_axis_.to_f
-          inverse_flattening_ = semi_major_axis_ / (semi_major_axis_ - semi_minor_axis_)
-          inverse_flattening_ = 0.0 if inverse_flattening_.infinite?
-          new(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, false, linear_unit_, *optional_)
-        end
-        
-        def self.create_flattened_sphere(name_, semi_major_axis_, inverse_flattening_, linear_unit_, *optional_)
-          semi_major_axis_ = semi_major_axis_.to_f
-          inverse_flattening_ = inverse_flattening_.to_f
-          semi_minor_axis_ = semi_major_axis_ - semi_major_axis_ / inverse_flattening_
-          semi_minor_axis_ = semi_major_axis_ if semi_minor_axis_.infinite?
-          new(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, true, linear_unit_, *optional_)
-        end
         
         class << self
           
+          
+          # Create an Ellipsoid given a name, semi-major and semi-minor
+          # axes, the inverse flattening, a boolean indicating whether
+          # the inverse flattening is definitive, and the LinearUnit
+          # indicating the axis units. The LinearUnit is optional and
+          # may be set to nil. You may also provide the optional parameters
+          # specified by the Info interface.
+          
           def create(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, ivf_definitive_, linear_unit_, *optional_)
             new(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, ivf_definitive_, linear_unit_, *optional_)
           end
           
+          
+          # Create an Ellipsoid given a name, semi-major and semi-minor
+          # axes, and the LinearUnit indicating the axis units. In the
+          # resulting ellipsoid, the inverse flattening is not definitive.
+          # The LinearUnit is optional and may be set to nil. You may also
+          # provide the optional parameters specified by the Info interface.
+          
+          def create_ellipsoid(name_, semi_major_axis_, semi_minor_axis_, linear_unit_, *optional_)
+            semi_major_axis_ = semi_major_axis_.to_f
+            semi_minor_axis_ = semi_minor_axis_.to_f
+            inverse_flattening_ = semi_major_axis_ / (semi_major_axis_ - semi_minor_axis_)
+            inverse_flattening_ = 0.0 if inverse_flattening_.infinite?
+            new(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, false, linear_unit_, *optional_)
+          end
+          
+          
+          # Create an Ellipsoid given a name, semi-major axis, inverse
+          # flattening, and the LinearUnit indicating the axis units. In
+          # the resulting ellipsoid, the inverse flattening is definitive.
+          # The LinearUnit is optional and may be set to nil. You may also
+          # provide the optional parameters specified by the Info interface.
+          
+          def create_flattened_sphere(name_, semi_major_axis_, inverse_flattening_, linear_unit_, *optional_)
+            semi_major_axis_ = semi_major_axis_.to_f
+            inverse_flattening_ = inverse_flattening_.to_f
+            semi_minor_axis_ = semi_major_axis_ - semi_major_axis_ / inverse_flattening_
+            semi_minor_axis_ = semi_major_axis_ if semi_minor_axis_.infinite?
+            new(name_, semi_major_axis_, semi_minor_axis_, inverse_flattening_, true, linear_unit_, *optional_)
+          end
+          
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A set of quantities from which other quantities are calculated.
+      # For the OGC abstract model, it can be defined as a set of real
+      # points on the earth that have coordinates. EG. A datum can be
+      # thought of as a set of parameters defining completely the origin
+      # and orientation of a coordinate system with respect to the earth.
+      # A textual description and/or a set of parameters describing the
+      # relationship of a coordinate system to some predefined physical
+      # locations (such as center of mass) and physical directions (such
+      # as axis of spin). The definition of the datum may also include
+      # the temporal behavior (such as the rate of change of the
+      # orientation of the coordinate axes).
+      # 
+      # == Notes
+      # 
+      # This is a non-instantiable abstract class. You must instantiate
+      # one of the subclasses HorizontalDatum, VerticalDatum, or
+      # LocalDatum.
+      
       class Datum < Info
         
         def initialize(name_, datum_type_, *optional_)  # :nodoc:
@@ -377,23 +780,23 @@ module RGeo
           @datum_type = datum_type_.to_i
         end
         
+        
+        # Gets the type of the datum as an enumerated code.
         attr_reader :datum_type
         
+        
         def _wkt_content(open_, close_)  # :nodoc:
           []
         end
         
-        class << self
-          
-          def create(name_, datum_type_, *optional_)
-            new(name_, datum_type_, *optional_)
-          end
-          
-        end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Procedure used to measure vertical distances.
+      
       class VerticalDatum < Datum
         
         def _wkt_typename  # :nodoc:
@@ -406,15 +809,29 @@ module RGeo
         
         class << self
           
+          
+          # Create a VerticalDatum given a name and a datum type code.
+          # You may also provide the optional parameters specified by the
+          # Info interface.
+          
           def create(name_, datum_type_, *optional_)
             new(name_, datum_type_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Local datum. If two local datum objects have the same datum type
+      # and name, then they can be considered equal. This means that
+      # coordinates can be transformed between two different local
+      # coordinate systems, as long as they are based on the same local
+      # datum.
+      
       class LocalDatum < Datum
         
         def _wkt_typename  # :nodoc:
@@ -427,15 +844,25 @@ module RGeo
         
         class << self
           
+          
+          # Create a LocalDatum given a name and a datum type code. You
+          # may also provide the optional parameters specified by the
+          # Info interface.
+          
           def create(name_, datum_type_, *optional_)
             new(name_, datum_type_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Procedure used to measure positions on the surface of the Earth.
+      
       class HorizontalDatum < Datum
         
         def initialize(name_, datum_type_, ellipsoid_, wgs84_parameters_, *optional_)  # :nodoc:
@@ -444,9 +871,16 @@ module RGeo
           @wgs84_parameters = wgs84_parameters_
         end
         
+        
+        # Returns the Ellipsoid.
         attr_reader :ellipsoid
+        
+        # Gets preferred parameters for a Bursa Wolf transformation into
+        # WGS84. The 7 returned values correspond to (dx,dy,dz) in meters,
+        # (ex,ey,ez) in arc-seconds, and scaling in parts-per-million.
         attr_reader :wgs84_parameters
         
+        
         def _wkt_typename  # :nodoc:
           "DATUM"
         end
@@ -457,17 +891,29 @@ module RGeo
           array_
         end
         
+        
         class << self
           
+          
+          # Create a HorizontalDatum given a name, datum type code,
+          # Ellipsoid, and WGS84ConversionInfo. The WGS84ConversionInfo
+          # is optional and may be set to nil. You may also provide the
+          # optional parameters specified by the Info interface.
+          
           def create(name_, datum_type_, ellipsoid_, wgs84_parameters_, *optional_)
             new(name_, datum_type_, ellipsoid_, wgs84_parameters_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A projection from geographic coordinates to projected coordinates.
+      
       class Projection < Info
         
         def initialize(name_, class_name_, parameters_, *optional_)  # :nodoc:
@@ -476,20 +922,33 @@ module RGeo
           @parameters = parameters_ ? parameters_.dup : []
         end
         
+        
+        # Gets the projection classification name
+        # (e.g. "Transverse_Mercator").
         attr_reader :class_name
         
+        
+        # Gets number of parameters of the projection.
+        
         def num_parameters
           @parameters.size
         end
         
+        
+        # Gets an inexed parameter of the projection.
+        
         def get_parameter(index_)
           @parameters[index_]
         end
         
+        
+        # Iterates over the parameters of the projection.
+        
         def each_parameter(&block_)
           @parameters.each(&block_)
         end
         
+        
         def _wkt_typename  # :nodoc:
           "PROJECTION"
         end
@@ -498,17 +957,53 @@ module RGeo
           []
         end
         
+        
         class << self
           
+          
+          # Create a Projection given a name, a projection class, and an
+          # array of ProjectionParameter. You may also provide the
+          # optional parameters specified by the Info interface.
+          
           def create(name_, class_name_, parameters_, *optional_)
             new(name_, class_name_, parameters_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # Base interface for all coordinate systems.
+      # 
+      # A coordinate system is a mathematical space, where the elements
+      # of the space are called positions. Each position is described by
+      # a list of numbers. The length of the list corresponds to the
+      # dimension of the coordinate system. So in a 2D coordinate system
+      # each position is described by a list containing 2 numbers.
+      # 
+      # However, in a coordinate system, not all lists of numbers
+      # correspond to a position -- some lists may be outside the domain
+      # of the coordinate system. For example, in a 2D Lat/Lon coordinate
+      # system, the list (91,91) does not correspond to a position.
+      # 
+      # Some coordinate systems also have a mapping from the mathematical
+      # space into locations in the real world. So in a Lat/Lon coordinate
+      # system, the mathematical position (lat, long) corresponds to a
+      # location on the surface of the Earth. This mapping from the
+      # mathematical space into real-world locations is called a Datum.
+      # 
+      # == Notes
+      # 
+      # This is a non-instantiable abstract class. You must instantiate
+      # one of the subclasses GeocentricCoordinateSystem,
+      # GeographicCoordinateSystem, ProjectedCoordinateSystem,
+      # VerticalCoordinateSystem, LocalCoordinateSystem, or
+      # CompoundCoordinateSystem.
+      
       class CoordinateSystem < Info
         
         def initialize(name_, dimension_, *optional_)  # :nodoc:
@@ -516,11 +1011,38 @@ module RGeo
           @dimension = dimension_.to_i
         end
         
+        
+        # Dimension of the coordinate system
         attr_reader :dimension
         
+        
+        # Gets axis details for dimension within coordinate system. Each
+        # dimension in the coordinate system has a corresponding axis.
+        
+        def get_axis(dimension_)
+          nil
+        end
+        
+        
+        # Gets units for dimension within coordinate system. Each
+        # dimension in the coordinate system has corresponding units.
+        
+        def get_units(dimension_)
+          nil
+        end
+        
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # An aggregate of two coordinate systems (CRS). One of these is
+      # usually a CRS based on a two dimensional coordinate system such
+      # as a geographic or a projected coordinate system with a horizontal
+      # datum. The other is a vertical CRS which is a one-dimensional
+      # coordinate system with a vertical datum.
+      
       class CompoundCoordinateSystem < CoordinateSystem
         
         def initialize(name_, head_, tail_, *optional_)  # :nodoc:
@@ -529,19 +1051,30 @@ module RGeo
           @tail = tail_
         end
         
+        
+        # Gets first sub-coordinate system.
         attr_reader :head
+        
+        # Gets second sub-coordinate system.
         attr_reader :tail
         
+        
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           hd_ = @head.dimension
           index_ < hd_ ? @head.get_axis(index_) : @tail.get_axis(index_ - hd_)
         end
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           hd_ = @head.dimension
           index_ < hd_ ? @head.get_units(index_) : @tail.get_units(index_ - hd_)
         end
         
+        
         def _wkt_typename  # :nodoc:
           "COMPD_CS"
         end
@@ -550,17 +1083,44 @@ module RGeo
           [@head._to_wkt(open_, close_), @tail._to_wkt(open_, close_)]
         end
         
+        
         class << self
           
+          
+          # Create a CompoundCoordinateSystem given two sub-coordinate
+          # systems. You may also provide the optional parameters
+          # specified by the Info interface.
+          
           def create(name_, head_, tail_, *optional_)
             new(name_, head_, tail_, *optional_)
           end
           
+          
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # A local coordinate system, with uncertain relationship to the
+      # world. In general, a local coordinate system cannot be related to
+      # other coordinate systems. However, if two objects supporting this
+      # interface have the same dimension, axes, units and datum then
+      # client code is permitted to assume that the two coordinate systems
+      # are identical. This allows several datasets from a common source
+      # (e.g. a CAD system) to be overlaid. In addition, some
+      # implementations of the Coordinate Transformation (CT) package may
+      # have a mechanism for correlating local datums. (E.g. from a
+      # database of transformations, which is created and maintained from
+      # real-world measurements.)
+      # 
+      # == Notes
+      # 
+      # RGeo's implementation does not provide the Coordinate
+      # Transformation (CT) package.
+      
       class LocalCoordinateSystem < CoordinateSystem
         
         def initialize(name_, local_datum_, unit_, axes_, *optional_)  # :nodoc:
@@ -570,16 +1130,25 @@ module RGeo
           @axes = axes_.dup
         end
         
+        
+        # Gets the local datum.
         attr_reader :local_datum
         
+        
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           @axes[index_]
         end
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           @unit
         end
         
+        
         def _wkt_typename  # :nodoc:
           "LOCAL_CS"
         end
@@ -588,17 +1157,34 @@ module RGeo
           [@local_datum._to_wkt(open_, close_), @unit._to_wkt(open_, close_)] + @axes.map{ |ax_| ax_._to_wkt(open_, close_) }
         end
         
+        
         class << self
           
+          
+          # Create a LocalCoordinateSystem given a name, a LocalDatum, a
+          # Unit, and an array of at least one AxisInfo. You may also
+          # provide the optional parameters specified by the Info
+          # interface.
+          
           def create(name_, local_datum_, unit_, axes_, *optional_)
             new(name_, local_datum_, unit_, axes_, *optional_)
           end
           
+          
         end
         
       end
       
       
+      # == OGC spec description
+      # 
+      # A 3D coordinate system, with its origin at the centre of the
+      # Earth. The X axis points towards the prime meridian. The Y axis
+      # points East or West. The Z axis points North or South. By default
+      # the Z axis will point North, and the Y axis will point East (e.g.
+      # a right handed system), but you should check the axes for
+      # non-default values.
+      
       class GeocentricCoordinateSystem < CoordinateSystem
         
         def initialize(name_, horizontal_datum_, prime_meridian_, linear_unit_, axis0_, axis1_, axis2_, *optional_)  # :nodoc:
@@ -611,18 +1197,34 @@ module RGeo
           @axis2 = axis2_
         end
         
+        
+        # Returns the HorizontalDatum. The horizontal datum is used to
+        # determine where the centre of the Earth is considered to be.
+        # All coordinate points will be measured from the centre of the
+        # Earth, and not the surface.
         attr_reader :horizontal_datum
+        
+        # Returns the PrimeMeridian.
         attr_reader :prime_meridian
+        
+        # Gets the units used along all the axes.
         attr_reader :linear_unit
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           @linear_unit
         end
         
+        
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           [@axis0, @axis1, @axis2][index_]
         end
         
+        
         def _wkt_typename  # :nodoc:
           "GEOCCS"
         end
@@ -635,17 +1237,32 @@ module RGeo
           arr_
         end
         
+        
         class << self
           
+          
+          # Create a GeocentricCoordinateSystem given a name, a
+          # HorizontalDatum, a PrimeMeridian, a LinearUnit, and three
+          # AxisInfo objects. The AxisInfo are optional and may be nil.
+          # You may also provide the optional parameters specified by the
+          # Info interface.
+          
           def create(name_, horizontal_datum_, prime_meridian_, linear_unit_, axis0_, axis1_, axis2_, *optional_)
             new(name_, horizontal_datum_, prime_meridian_, linear_unit_, axis0_, axis1_, axis2_, *optional_)
           end
           
+          
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # A one-dimensional coordinate system suitable for vertical
+      # measurements.
+      
       class VerticalCoordinateSystem < CoordinateSystem
         
         def initialize(name_, vertical_datum_, vertical_unit_, axis_, *optional_)  # :nodoc:
@@ -655,17 +1272,29 @@ module RGeo
           @axis = axis_
         end
         
+        
+        # Gets the vertical datum, which indicates the measurement method.
         attr_reader :vertical_datum
+        
+        # Gets the units used along the vertical axis. The vertical units
+        # must be the same as the CS_CoordinateSystem units.
         attr_reader :vertical_unit
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           @vertical_unit
         end
         
+        
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           @axis
         end
         
+        
         def _wkt_typename  # :nodoc:
           "VERT_CS"
         end
@@ -676,17 +1305,36 @@ module RGeo
           arr_
         end
         
+        
         class << self
           
+          
+          # Create a VerticalCoordinateSystem given a name, a
+          # VerticalDatum, a LinearUnit, and an AxisInfo. The AxisInfo is
+          # optional and may be nil. You may also provide the optional
+          # parameters specified by the Info interface.
+          
           def create(name_, vertical_datum_, vertical_unit_, axis_, *optional_)
             new(name_, vertical_datum_, vertical_unit_, axis_, *optional_)
           end
           
+          
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # A 2D coordinate system suitable for positions on the Earth's surface.
+      # 
+      # == Notes
+      # 
+      # This is a non-instantiable abstract class. You must instantiate
+      # one of the subclasses GeographicCoordinateSystem or
+      # ProjectedCoordinateSystem.
+      
       class HorizontalCoordinateSystem < CoordinateSystem
         
         def initialize(name_, horizontal_datum_, *optional_)  # :nodoc:
@@ -694,11 +1342,22 @@ module RGeo
           @horizontal_datum = horizontal_datum_
         end
         
+        
+        # Returns the HorizontalDatum.
         attr_reader :horizontal_datum
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # A coordinate system based on latitude and longitude. Some
+      # geographic coordinate systems are Lat/Lon, and some are Lon/Lat.
+      # You can find out which this is by examining the axes. You should
+      # also check the angular units, since not all geographic coordinate
+      # systems use degrees.
+      
       class GeographicCoordinateSystem < HorizontalCoordinateSystem
         
         def initialize(name_, angular_unit_, horizontal_datum_, prime_meridian_, axis0_, axis1_, *optional_)  # :nodoc:
@@ -709,25 +1368,47 @@ module RGeo
           @axis1 = axis1_
         end
         
+        
+        # Returns the PrimeMeridian.
         attr_reader :prime_meridian
+        
+        # Returns the AngularUnit. The angular unit must be the same as
+        # the CS_CoordinateSystem units.
         attr_reader :angular_unit
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           @angular_unit
         end
         
+
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           index_ == 1 ? @axis1 : @axis0
         end
         
+        
+        # Gets the number of available conversions to WGS84 coordinates.
+        
         def num_conversion_to_wgs84
           @horizontal_datum.wgs84_parameters ? 1 : 0
         end
         
+        
+        # Gets details on a conversion to WGS84. Some geographic
+        # coordinate systems provide several transformations into WGS84,
+        # which are designed to provide good accuracy in different areas
+        # of interest. The first conversion (with index=0) should provide
+        # acceptable accuracy over the largest possible area of interest.
+        
         def get_wgs84_conversion_info(index_)
           @horizontal_datum.wgs84_parameters
         end
         
+        
         def _wkt_typename  # :nodoc:
           "GEOGCS"
         end
@@ -739,17 +1420,31 @@ module RGeo
           arr_
         end
         
+        
         class << self
           
+          
+          # Create a GeographicCoordinateSystem, given a name, an
+          # AngularUnit, a HorizontalDatum, a PrimeMeridian, and two
+          # AxisInfo objects. The AxisInfo objects are optional and may
+          # be set to nil. You may also provide the optional parameters
+          # specified by the Info interface.
+          
           def create(name_, angular_unit_, horizontal_datum_, prime_meridian_, axis0_, axis1_, *optional_)
             new(name_, angular_unit_, horizontal_datum_, prime_meridian_, axis0_, axis1_, *optional_)
           end
           
+          
         end
         
+        
       end
       
       
+      # == OGC spec description
+      # 
+      # A 2D cartographic coordinate system.
+      
       class ProjectedCoordinateSystem < HorizontalCoordinateSystem
         
         def initialize(name_, geographic_coordinate_system_, projection_, linear_unit_, axis0_, axis1_, *optional_)  # :nodoc:
@@ -761,18 +1456,32 @@ module RGeo
           @axis1 = axis1_
         end
         
+        
+        # Returns the GeographicCoordinateSystem.
         attr_reader :geographic_coordinate_system
+        
+        # Gets the projection.
         attr_reader :projection
+        
+        # Returns the LinearUnits. The linear unit must be the same as
+        # the CS_CoordinateSystem units.
         attr_reader :linear_unit
         
+        
+        # Implements CoordinateSystem#get_units
+        
         def get_units(index_)
           @linear_unit
         end
         
+        
+        # Implements CoordinateSystem#get_axis
+        
         def get_axis(index_)
           index_ == 1 ? @axis1 : @axis0
         end
         
+        
         def _wkt_typename  # :nodoc:
           "PROJCS"
         end
@@ -786,14 +1495,24 @@ module RGeo
           arr_
         end
         
+        
         class << self
           
+          
+          # Create a ProjectedCoordinateSystem given a name, a
+          # GeographicCoordinateSystem, and Projection, a LinearUnit, and
+          # two AxisInfo objects. The AxisInfo objects are optional and
+          # may be set to nil. You may also provide the optional
+          # parameters specified by the Info interface.
+          
           def create(name_, geographic_coordinate_system_, projection_, linear_unit_, axis0_, axis1_, *optional_)
             new(name_, geographic_coordinate_system_, projection_, linear_unit_, axis0_, axis1_, *optional_)
           end
           
+          
         end
         
+        
       end