rgeo 0.2.2 → 0.2.3

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

@@ -40,93 +40,163 @@ module RGeo
     
     
     # This module contains an implementation of the CS (coordinate
-    # systems) package of the OGC Coordinate Transform spec. It contains
+    # systems) package of the OGC Coordinate Transform spec. It provides
     # classes for representing ellipsoids, datums, coordinate systems,
     # and other related concepts, as well as a parser for the WKT format
     # for specifying coordinate systems.
     # 
     # Generally, the easiest way to create coordinate system objects is
     # to use RGeo::CoordSys::CS.create_from_wkt, which parses the WKT
-    # format. This and other methods of the FactoryMethods module are all
-    # available as convenient module functions on the CS module.
+    # format. You can also use the create methods available for each
+    # object class.
     # 
-    # Almost the entire spec is implemented here. Currently missing are:
+    # Most but not all of the spec is implemented here.
+    # Currently missing are:
     # 
     # * XML format is not implemented. We're assuming that WKT is the
     #   preferred format.
     # * The PT and CT packages are not implemented.
     # * FittedCoordinateSystem is not implemented.
+    # * The defaultEnvelope attribute of CS_CoordinateSystem is not
+    #   implemented.
     
     module CS
       
       
-      module FactoryMethods
+      # A class implementing the CS_CoordinateSystemFactory interface.
+      # It provides methods for building up complex objects from simpler
+      # objects or values.
+      # 
+      # Note that the methods of CS_CoordinateSystemFactory do not provide
+      # facilities for setting the authority. If you need to set authority
+      # values, use the create methods for the object classes themselves.
+      
+      class CoordinateSystemFactory
+        
+        
+        # Create a CompoundCoordinateSystem from a name, and two
+        # constituent coordinate systems.
         
         def create_compound_coordinate_system(name_, head_, tail_)
           CompoundCoordinateSystem.create(name_, head_, tail_)
         end
         
+        
+        # Create an Ellipsoid from a name, semi-major axis, and semi-minor
+        # axis. You can also provide a LinearUnit, but this is optional
+        # and may be set to nil.
+        
         def create_ellipsoid(name_, semi_major_axis_, semi_minor_axis_, linear_unit_)
           Ellipsoid.create_ellipsoid(name_, semi_major_axis_, semi_minor_axis_, linear_unit_)
         end
         
+        
+        # Create an Ellipsoid from a name, semi-major axis, and an inverse
+        # flattening factor. You can also provide a LinearUnit, but this
+        # is optional and may be set to nil.
+        
         def create_flattened_sphere(name_, semi_major_axis_, inverse_flattening_, linear_unit_)
           Ellipsoid.create_flattened_sphere(name_, semi_major_axis_, inverse_flattening_, linear_unit_)
         end
         
+        
+        # Create any object given the OGC WKT format. Raises
+        # Error::ParseError if a syntax error is encounterred.
+        
         def create_from_wkt(str_)
           WKTParser.new(str_).parse
         end
         
+        
+        # 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.
+        
         def create_geographic_coordinate_system(name_, angular_unit_, horizontal_datum_, prime_meridian_, axis0_, axis1_)
           GeographicCoordinateSystem.create(name_, angular_unit_, horizontal_datum_, prime_meridian_, axis0_, axis1_)
         end
         
+        
+        # Create a HorizontalDatum given a name, a horizontal datum type
+        # code, an Ellipsoid, and a WGS84ConversionInfo. The
+        # WGS84ConversionInfo is optional and may be set to nil.
+
         def create_horizontal_datum(name_, horizontal_datum_type_, ellipsoid_, to_wgs84_)
           HorizontalDatum.create(name_, horizontal_datum_type_, ellipsoid_, to_wgs84_)
         end
         
+        
+        # Create a LocalCoordinateSystem given a name, a LocalDatum, a
+        # Unit, and an array of at least one AxisInfo.
+        
         def create_local_coordinate_system(name_, datum_, unit_, axes_)
           LocalCoordinateSystem.create(name_, datum_, unit_, axes_)
         end
         
+        
+        # Create a LocalDatum given a name and a local datum type code.
+        
         def create_local_datum(name_, local_datum_type_)
           LocalDatum.create(name, local_datum_type_)
         end
         
+        
+        # Create a PrimeMeridian given a name, an AngularUnit, and a
+        # longitude offset.
+        
         def create_prime_meridian(name_, angular_unit_, longitude_)
           PrimeMeridian.create(name, angular_unit_, longitude_)
         end
         
+        
+        # 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.
+        
         def create_projected_coordinate_system(name_, gcs_, projection_, linear_unit_, axis0_, axis1_)
           ProjectedCoordinateSystem.create(name_, gcs_, projection_, linear_unit_, axis0_, axis1_)
         end
         
+        
+        # Create a Projection given a name, a projection class, and an
+        # array of ProjectionParameter.
+        
         def create_projection(name_, wkt_projection_class_, parameters_)
           Projection.create(name_, wkt_projection_class_, parameters_)
         end
         
+        
+        # Create a VerticalCoordinateSystem given a name, a VerticalDatum,
+        # a VerticalUnit, and an AxisInfo. The AxisInfo is optional and
+        # may be nil.
+        
         def create_vertical_coordinate_system(name_, vertical_datum_, vertical_unit_, axis_)
           VerticalCoordinateSystem.create(name_, vertical_datum_, vertical_unit_, axis_)
         end
         
+        
+        # Create a VerticalDatum given a name ane a datum type code.
+        
         def create_vertical_datum(name_, vertical_datum_type_)
           VerticalDatum.create(name_, vertical_datum_type_)
         end
         
-      end
-      
-      
-      class CoordinateSystemFactory
-        
-        include FactoryMethods
         
       end
       
       
       class << self
         
-        include FactoryMethods
+        
+        # Parsees OGC WKT format and returns the object created. Raises
+        # Error::ParseError if a syntax error is encounterred.
+        
+        def create_from_wkt(str_)
+          WKTParser.new(str_).parse
+        end
+        
         
       end
       

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

@@ -225,6 +225,7 @@ module RGeo
         class TypeString < ::String  # :nodoc:
         end
         
+        
         class AuthorityClause  # :nodoc:
           
           def initialize(name_, code_)

data/lib/rgeo/coord_sys/srs_database/active_record_table.rb

@@ -41,11 +41,84 @@ module RGeo
     module SRSDatabase
       
       
+      # A spatial reference database implementation that uses ActiveRecord
+      # to access a spatial reference table provided by a spatial database
+      # implementation. You can use this class to obtain coordinate system
+      # information from your installation of, e.g. PostGIS.
+      
       class ActiveRecordTable
         
         @@class_counter = 0
         
         
+        # Create a new ActiveRecord-backed database connection.
+        # 
+        # Options include:
+        # 
+        # <tt>:ar_class</tt>::
+        #   An ActiveRecord class to use. You may provide this if you
+        #   already have an ActiveRecord class that accesses the table.
+        #   If not provided, an ActiveRecord class will be generated
+        #   for you, using the <tt>:ar_base_class</tt>,
+        #   <tt>:database_config</tt>, and <tt>:table_name</tt> options.
+        # <tt>:ar_base_class</tt>::
+        #   Specify an ActiveRecord base class to use when generating an
+        #   ActiveRecord class. Default is ::ActiveRecord::Base. You may
+        #   want to use this if you have a base class already that
+        #   specifies an existing database connection and/or other
+        #   class-scope options.
+        # <tt>:database_config</tt>::
+        #   If provided, <tt>establish_connection</tt> will be called on
+        #   the generated ActiveRecord class, with the given value.
+        # <tt>:table_name</tt>::
+        #   The table name for the new ActiveRecord class. Defaults to
+        #   the value <tt>spatial_ref_sys</tt>, which is the OGC-specified
+        #   name for this table.
+        # <tt>:srid_column</tt>::
+        #   The name of the SRID column. Defaults to "srid", which is the
+        #   OGC-specified name for this column.
+        # <tt>:auth_name_column</tt>::
+        #   The name of the authority name column. On an OGC-compliant
+        #   database, this column should be named "auth_name". However,
+        #   the default is set to nil; you should set this option
+        #   explicitly if you want to read the authority name.
+        # <tt>:auth_srid_column</tt>::
+        #   The name of the authority srid column. On an OGC-compliant
+        #   database, this column should be named "auth_srid". However,
+        #   the default is set to nil; you should set this option
+        #   explicitly if you want to read the authority's srid.
+        # <tt>:name_column</tt>::
+        #   The name of the coordinate system name column. This column is
+        #   not part of the OGC spec, but it is included in some spatial
+        #   database implementations. Default is nil.
+        # <tt>:description_column</tt>::
+        #   The name of the coordinate system description column. This
+        #   column is not part of the OGC spec, but may be included in
+        #   some spatial database implementations. Default is nil.
+        # <tt>:srtext_column</tt>::
+        #   The name of the spatial reference WKT column. On an
+        #   OGC-compliant database, this column should be named "srtext".
+        #   However, not all databases include this column, so the default
+        #   is set to nil; you should set this option explicitly if you
+        #   want to read the OGC coordinate system specification.
+        # <tt>:proj4text_column</tt>::
+        #   The name of the Proj4 format projection spec column. This
+        #   column is not part of the OGC spec, but may be included in
+        #   some spatial database implementations. Default is nil.
+        # <tt>:cache</tt>::
+        #   If set to true, entries are cached when first retrieved, so
+        #   subsequent requests do not have to make a database round trip.
+        #   Default is false.
+        # 
+        # Some option settings may be provided by the ActiveRecord
+        # connection adapter, if the ActiveRecord class's connection uses
+        # an adapter that is RGeo-savvy. The "postgis" and "spatialite"
+        # adapters are such adapters. They automatically provide the
+        # <tt>:table_name</tt> and all the relevant column settings for
+        # the database-provided spatial reference table as defaults.
+        # However, you can still override those settings if you want to
+        # use a custom table.
+        
         def initialize(opts_={})
           @cache = opts_[:cache] ? {} : nil
           @ar_class = opts_[:ar_class]
@@ -55,13 +128,18 @@ module RGeo
             self.class.const_set("Klass#{@@class_counter}", @ar_class)
             @@class_counter += 1
             @ar_class.class_eval do
-              set_table_name(opts_[:table_name] || 'spatial_ref_sys')
+              establish_connection(opts_[:database_config]) if opts_[:database_config]
             end
           end
           connection_ = @ar_class.connection
           if connection_.respond_to?(:srs_database_columns)
             opts_ = connection_.srs_database_columns.merge(opts_)
           end
+          unless opts_[:ar_class]
+            @ar_class.class_eval do
+              set_table_name(opts_[:table_name] || 'spatial_ref_sys')
+            end
+          end
           @srid_column = opts_[:srid_column] || 'srid'
           @auth_name_column = opts_[:auth_name_column]
           @auth_srid_column = opts_[:auth_srid_column]
@@ -72,6 +150,8 @@ module RGeo
         end
         
         
+        # Retrieve an Entry given an integer SRID.
+        
         def get(ident_)
           ident_ = ident_.to_i
           return @cache[ident_] if @cache && @cache.include?(ident_)
@@ -97,6 +177,8 @@ module RGeo
         end
         
         
+        # Clears the cache if a cache is active.
+        
         def clear_cache
           @cache.clear if @cache
         end

data/lib/rgeo/coord_sys/srs_database/interface.rb

@@ -51,14 +51,25 @@ module RGeo
     module SRSDatabase
       
       
+      # Interface specification for spatial reference system databases.
+      # This module exists primarily for the sake of documentation.
+      # Database implementations need not actually include this module,
+      # but at least need to duck-type its methods.
+      
       module Interface
         
         
+        # Retrieve an Entry given an identifier. The identifier is usually
+        # a numeric spatial reference ID (SRID), but could be a string
+        # value for certain database types.
+        
         def get(ident_)
           nil
         end
         
         
+        # Clears any cache utilized by this database.
+        
         def clear_cache
           nil
         end
@@ -67,8 +78,35 @@ module RGeo
       end
       
       
+      # An entry in a spatial reference system database.
+      # Every entry has an identifier, but all the other attributes are
+      # optional and may or may not be present depending on the database.
+      
       class Entry
         
+        
+        # Create an entry.
+        # You must provide an identifier, which may be numeric or a
+        # string. The data hash should contain any other attributes,
+        # keyed by symbol.
+        # 
+        # Some attribute inputs have special behaviors:
+        # 
+        # <tt>:coord_sys</tt>::
+        #   You can pass a CS coordinate system object, or a string in
+        #   WKT format.
+        # <tt>:proj4</tt>::
+        #   You can pass a Proj4 object, or a proj4-format string.
+        # <tt>:name</tt>::
+        #   If the name is not provided directly, it is taken from the
+        #   coord_sys.
+        # <tt>:authority</tt>::
+        #   If the authority name is not provided directly, it is taken
+        #   from the coord_sys.
+        # <tt>:authority_code</tt>::
+        #   If the authority code is not provided directly, it is taken
+        #   from the coord_sys.
+        
         def initialize(ident_, data_={})
           @identifier = ident_
           @authority = data_[:authority]
@@ -94,14 +132,29 @@ module RGeo
           end
         end
         
+        
+        # The database key or identifier.
         attr_reader :identifier
+        
+        # The authority name, if present. Example: "epsg".
         attr_reader :authority
+        
+        # The authority code, e.g. an EPSG code.
         attr_reader :authority_code
+        
+        # A human-readable name for this coordinate system.
         attr_reader :name
+        
+        # A human-readable description for this coordinate system.
         attr_reader :description
+        
+        # The CS::CoordinateSystem object.
         attr_reader :coord_sys
+        
+        # The Proj4 object.
         attr_reader :proj4
         
+        
       end
       
       

data/lib/rgeo/coord_sys/srs_database/proj4_data.rb

@@ -41,10 +41,44 @@ module RGeo
     module SRSDatabase
       
       
+      # A spatial reference database implementation backed by coordinate
+      # system files installed as part of the proj4 library. For a given
+      # Proj4Data object, you specify a single file (e.g. the epsg data
+      # file), and you can retrieve records by ID number.
+      
       class Proj4Data
         
         
-        def initialize(path_, opts_={})
+        # Connect to one of the proj4 data files. You should provide the
+        # file name, optionally the installation directory if it is not
+        # in a typical location, and several additional options.
+        # 
+        # These options are recognized:
+        # 
+        # <tt>:dir</tt>::
+        #   The path for the share/proj directory that contains the
+        #   requested data file. By default, the Proj4Data class will
+        #   try a number of directories for you, including
+        #   /usr/local/share/proj, /opt/local/share/proj, /usr/share/proj,
+        #   and a few other variants. However, if you have proj4 installed
+        #   elsewhere, you can provide an explicit directory using this
+        #   option. You may also pass nil as the value, in which case all
+        #   the normal lookup paths will be disabled, and you will have to
+        #   provide the full path as the file name.
+        # <tt>:cache</tt>::
+        #   If set to true, this class caches previously looked up entries
+        #   so subsequent lookups do not have to reread the file. If set
+        #   to <tt>:read_all</tt>, then ALL values in the file are read in
+        #   and cached the first time a lookup is done. If set to
+        #   <tt>:preload</tt>, then ALL values in the file are read in
+        #   immediately when the database is created. Default is false,
+        #   indicating that the file will be reread on every lookup.
+        # <tt>:authority</tt>::
+        #   If set, its value is taken as the authority name for all
+        #   entries. The authority code will be set to the identifier. If
+        #   not set, then the authority fields of entries will be blank.
+        
+        def initialize(filename_, opts_={})
           dir_ = nil
           if opts_.include?(:dir)
             dir_ = opts_[:dir]
@@ -56,36 +90,47 @@ module RGeo
               end
             end
           end
-          @path = dir_ ? "#{dir_}/#{path_}" : path_
-          @cache = opts_[:cache] ? {} : nil
+          @path = dir_ ? "#{dir_}/#{filename_}" : filename_
           @authority = opts_[:authority]
-          @populate_state = @cache && opts_[:read_all] ? 1 : 0
+          if opts_[:cache]
+            @cache = {}
+            case opts_[:cache]
+            when :read_all
+              @populate_state = 1
+            when :preload
+              _search_file(nil)
+              @populate_state = 2
+            else
+              @populate_state = 0
+            end
+          else
+            @cache = nil
+            @populate_state = 0
+          end
         end
         
         
+        # Retrieve the Entry for the given ID number.
+        
         def get(ident_)
           ident_ = ident_.to_s
           return @cache[ident_] if @cache && @cache.include?(ident_)
           result_ = nil
           if @populate_state == 0
             data_ = _search_file(ident_)
-            unless data_
-              @cache[ident_] = nil if @cache
-              return nil
-            end
-            result_ = Entry.new(ident_, :authority => @authority, :authority_code => @authority ? ident_ : nil, :name => data_[1], :proj4 => data_[2])
+            result_ = Entry.new(ident_, :authority => @authority, :authority_code => @authority ? ident_ : nil, :name => data_[1], :proj4 => data_[2]) if data_
             @cache[ident_] = result_ if @cache
           elsif @populate_state == 1
-            _search_file(nil) do |id_, name_, text_|
-              @cache[id_] = Entry.new(id_, :authority => @authority, :authority_code => @authority ? id_ : nil, :name => name_, :proj4 => text_)
-              result_ = @cache[id_] if id_ == ident_
-            end
+            _search_file(nil)
+            result_ = @cache[ident_]
             @populate_state = 2
           end
           result_
         end
         
         
+        # Clear the cache if one exists.
+        
         def clear_cache
           @cache.clear if @cache
           @populate_state = 1 if @populate_state == 2
@@ -114,8 +159,8 @@ module RGeo
                 if line_[-2..-1] == '<>'
                   cur_text_ << line_[0..-3].strip
                   cur_text_ = cur_text_.join(' ')
-                  if block_given?
-                    yield(ident_, cur_name_, cur_text_)
+                  if ident_.nil?
+                    @cache[ident_] = Entry.new(ident_, :authority => @authority, :authority_code => @authority ? id_ : nil, :name => cur_name_, :proj4 => cur_text_)
                   end
                   if cur_ident_ == ident_
                     return [ident_, cur_name_, cur_text_]