proj4rb 3.0.0 → 4.0.0

data/lib/proj/crs_info.rb

@@ -0,0 +1,47 @@
+# encoding: UTF-8
+module Proj
+  class CrsInfo
+    attr_reader :auth_name, :code, :name, :type, :deprecated, :bbox_valid,
+                :west_lon_degree, :south_lat_degree, :east_lon_degree, :north_lat_degree,
+                :area_name, :projection_method_name, :celestial_body_name
+
+    def self.from_proj_crs_info(proj_crs_info)
+      data = {auth_name: proj_crs_info[:auth_name],
+              code: proj_crs_info[:code],
+              name: proj_crs_info[:name],
+              type: proj_crs_info[:type],
+              deprecated: proj_crs_info[:deprecated] == 1 ? true : false,
+              bbox_valid: proj_crs_info[:bbox_valid] == 1 ? true : false,
+              west_lon_degree: proj_crs_info[:west_lon_degree],
+              south_lat_degree: proj_crs_info[:south_lat_degree],
+              east_lon_degree: proj_crs_info[:east_lon_degree],
+              north_lat_degree: proj_crs_info[:north_lat_degree],
+              area_name: proj_crs_info[:area_name],
+              projection_method_name: proj_crs_info[:projection_method_name]}
+
+      if Api::PROJ_VERSION >= Gem::Version.new('8.1.0')
+        data[:celestial_body_name] = proj_crs_info[:celestial_body_name]
+      end
+
+      new(**data)
+    end
+
+    def initialize(auth_name:, code:, name:, type:, deprecated:, bbox_valid:,
+                   west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:,
+                   area_name:, projection_method_name:, celestial_body_name: nil)
+      @auth_name = auth_name
+      @code = code
+      @name = name
+      @type = type
+      @deprecated = deprecated
+      @bbox_valid = bbox_valid
+      @west_lon_degree = west_lon_degree
+      @south_lat_degree = south_lat_degree
+      @east_lon_degree = east_lon_degree
+      @north_lat_degree = north_lat_degree
+      @area_name = area_name
+      @projection_method_name = projection_method_name
+      @celestial_body_name = celestial_body_name
+    end
+  end
+end

data/lib/proj/database.rb

@@ -0,0 +1,305 @@
+module Proj
+  CelestialBody = Struct.new(:auth_name, :name)
+
+  # This class provides access the Proj SQLite database called proj.db. The database
+  # stores transformation information that must be accessible for the library to work properly.
+  #
+  # @see https://proj.org/resource_files.html#proj-db
+  class Database
+    attr_reader :context
+
+    # Create a new database instance to query the Proj database
+    #
+    # @param context [Context] A proj Context
+    #
+    # @return [Database]
+    def initialize(context)
+      @context = context
+    end
+
+    # Returns the path the Proj database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_path
+    #
+    # return [String]
+    def path
+      if Api.method_defined?(:proj_context_get_database_path)
+        Api.proj_context_get_database_path(self.context)
+      end
+    end
+
+    # Sets the path to the Proj database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_database_path
+    #
+    # @param value [String] Path to the proj database
+    #
+    # @return [Database] Returns reference to the current database instance
+    def path=(value)
+      result = Api.proj_context_set_database_path(self.context, value, nil, nil)
+      unless result == 1
+        Error.check_context(self.context)
+      end
+      self
+    end
+
+    # Returns SQL statements to run to initiate a new valid auxiliary empty database.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_structure
+    #
+    # @return [Array<Strings>] List of sql statements
+    def structure
+      ptr = Api.proj_context_get_database_structure(self.context, nil)
+      Strings.new(ptr)
+    end
+
+    # Return a metadata from the database.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_database_metadata
+    #
+    # @param key [String] The name of the metadata item. Must not be nil
+    #                       Available keys:
+    #                         DATABASE.LAYOUT.VERSION.MAJOR
+    #                         DATABASE.LAYOUT.VERSION.MINOR
+    #                         EPSG.VERSION
+    #                         EPSG.DATE
+    #                         ESRI.VERSION
+    #                         ESRI.DATE
+    #                         IGNF.SOURCE
+    #                         IGNF.VERSION
+    #                         IGNF.DATE
+    #                         NKG.SOURCE
+    #                         NKG.VERSION
+    #                         NKG.DATE
+    #                         PROJ.VERSION
+    #                         PROJ_DATA.VERSION
+    #
+    # @return [String] Returned metadata
+    def metadata(key)
+      Api.proj_context_get_database_metadata(self.context, key)
+    end
+
+    # Returns the set of authority codes of the given object type.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_codes_from_database
+    #
+    # @param auth_name [String] Authority name. Must not be nil.
+    # @param type [PJ_TYPE] Object type.
+    # @param allow_deprecated [Boolean] Specifies if deprecated objects should be returned. Default is false.
+    #
+    # @return [Strings] Returned authority codes
+    def codes(auth_name, type, allow_deprecated = false)
+      ptr = Api.proj_get_codes_from_database(self.context, auth_name, type, allow_deprecated ? 1 : 0)
+      Strings.new(ptr)
+    end
+
+    # Return a list of authorities used in the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_authorities_from_database
+    #
+    # @return [Array<Strings>] List of authorities
+    def authorities
+      ptr = Api.proj_get_authorities_from_database(self.context)
+      Strings.new(ptr)
+    end
+
+    # Enumerate CRS infos from the database, taking into account various criteria.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_crs_info_list_from_database
+    #
+    # @param auth_name [String] Authority name. Use nil to specify all authorities
+    # @param parameters [Parameters] Parameters to specify search criteria. May be nil
+    #
+    # @return [Array<CrsInfo>] Returned crs infos
+    def crs_info(auth_name = nil, parameters = nil)
+      out_result_count = FFI::MemoryPointer.new(:int)
+      ptr = Api.proj_get_crs_info_list_from_database(self.context, auth_name, parameters, out_result_count)
+
+      result = out_result_count.read_int.times.map do |index|
+        index_ptr = ptr + (index * FFI::Pointer::SIZE)
+        struct = Api::PROJ_CRS_INFO.new(index_ptr.read_pointer)
+        CrsInfo.from_proj_crs_info(struct)
+      end
+
+      Api.proj_crs_info_list_destroy(ptr)
+      result
+    end
+
+    # Returns information about a Grid from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_get_info_from_database
+    #
+    # @param name [String] The name of the grid
+    #
+    # @return [Grid]
+    def grid(name)
+      out_full_name = FFI::MemoryPointer.new(:string)
+      out_package_name = FFI::MemoryPointer.new(:string)
+      out_url = FFI::MemoryPointer.new(:string)
+      out_downloadable = FFI::MemoryPointer.new(:int)
+      out_open_license = FFI::MemoryPointer.new(:int)
+      out_available = FFI::MemoryPointer.new(:int)
+
+      result = Api.proj_grid_get_info_from_database(self.context, name,
+                                                    out_full_name, out_package_name, out_url,
+                                                    out_downloadable, out_open_license, out_available)
+
+      if result == 1
+        full_name_ptr = out_full_name.read_pointer
+        package_name_ptr = out_package_name.read_pointer
+        url_ptr = out_url.read_pointer
+
+        downloadable_ptr = out_downloadable
+        open_license_ptr = out_open_license
+        available_ptr = out_available
+
+        full_name = full_name_ptr.read_string_to_null
+        package_name = package_name_ptr.read_string_to_null
+        url = url_ptr.read_string_to_null
+
+        downloadable = downloadable_ptr.read_int == 1 ? true : false
+        open_license = open_license_ptr.read_int == 1 ? true : false
+        available = available_ptr.read_int == 1 ? true : false
+
+        Grid.new(name, self.context,
+                 full_name: full_name, package_name: package_name,
+                 url: url ? URI(url) : nil,
+                 downloadable: downloadable, open_license: open_license, available: available)
+      else
+        Error.check_context(self.context)
+      end
+    end
+
+    # Returns a list of geoid models available
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_geoid_models_from_database
+    #
+    # @param authority [String] Authority name into which the object will be inserted. Must not be nil
+    # @param code [Integer] Code with which the object will be inserted.Must not be nil
+    #
+    # @return [Strings] List of insert statements
+    def geoid_models(authority, code)
+      ptr = Api.proj_get_geoid_models_from_database(self.context, authority, code, nil)
+      Strings.new(ptr)
+    end
+
+    # Returns a list of celestial bodies from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_list_from_database
+    #
+    # @param authority [String] Authority name, used to restrict the search. Set to nil for all authorities.
+    #
+    # @return [Array<CelestialBody>] List of insert statements
+    def celestial_bodies(authority = nil)
+      out_result_count = FFI::MemoryPointer.new(:int)
+      ptr = Api.proj_get_celestial_body_list_from_database(self.context, authority, out_result_count)
+
+      body_ptrs = ptr.read_array_of_pointer(out_result_count.read_int)
+      result = body_ptrs.map do |body_ptr|
+        # First read the pointer to a structure
+        struct = Api::ProjCelestialBodyInfo.new(body_ptr)
+
+        # Now map this to a Ruby Struct
+        CelestialBody.new(struct[:auth_name], struct[:name])
+      end
+
+      Api.proj_celestial_body_list_destroy(ptr)
+
+      result
+    end
+
+    # Return the name of the celestial body of the specified object.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_celestial_body_name
+    #
+    # @param object [PjObject] Object of type CRS, Datum or Ellipsoid. Must not be nil.
+    #
+    # @return [String] The name of the celestial body or nil
+    def celestial_body_name(object)
+      Api.proj_get_celestial_body_name(self.context, object)
+    end
+
+    # Suggests a database code for the specified object.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_suggests_code_for
+    #
+    # @param object [PjObject] Object for which to suggest a code.
+    # @param authority [String]  Authority name into which the object will be inserted.
+    # @param numeric_code [Boolean] Whether the code should be numeric, or derived from the object name.
+    #
+    # @return [String] The suggested code
+    def suggest_code_for(object, authority, numeric_code)
+      ptr = Api.proj_suggests_code_for(self.context, object, authority, numeric_code ? 1 : 0, nil)
+      result = ptr.read_string_to_null
+      Api.proj_string_destroy(ptr)
+      result
+    end
+
+    # Returns a list of units from the database
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_units_from_database
+    #
+    # @param auth_name [String] Authority name, used to restrict the search. Or nil for all authorities.
+    # @param category [String] Filter by category, if this parameter is not nil. Category is one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time
+    # @param allow_deprecated [Boolean] Whether deprecated units should also be returned. Default false.
+    #
+    # @return [Array<Unit>] Array of units
+    def units(auth_name: nil, category: nil, allow_deprecated: false)
+      # Create pointer to read the count output parameter
+      out_result_count = FFI::MemoryPointer.new(:int)
+
+      # Result is an array of pointers to structures
+      pp_units = Api.proj_get_units_from_database(Context.current, auth_name, category, allow_deprecated ? 1 : 0, out_result_count)
+      count = out_result_count.read(:int)
+      array_p_units = pp_units.read_array_of_pointer(count)
+
+      result = Array.new(count)
+      count.times do |i|
+        unit_info = Api::PROJ_UNIT_INFO.new(array_p_units[i])
+
+        result[i] = Unit.new(unit_info[:auth_name],
+                             unit_info[:code],
+                             unit_info[:name],
+                             unit_info[:category],
+                             unit_info[:conv_factor],
+                             unit_info[:proj_short_name],
+                             unit_info[:deprecated])
+      end
+
+      Api.proj_unit_list_destroy(pp_units)
+
+      result
+    end
+
+    # Returns information for a unit of measure from a database lookup
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_uom_get_info_from_database
+    #
+    # @param auth_name [String] Authority name
+    # @param code [String] Unit of measure code
+    #
+    # @return [Unit] Unit
+    def unit(auth_name, code)
+      out_name = FFI::MemoryPointer.new(:string)
+      out_conv_factor = FFI::MemoryPointer.new(:double)
+      out_category = FFI::MemoryPointer.new(:string)
+
+      result = Api.proj_uom_get_info_from_database(self.context, auth_name, code,
+                                                    out_name, out_conv_factor , out_category)
+
+      if result == 1
+        name_ptr = out_name.read_pointer
+        conv_factor_ptr = out_conv_factor
+        category_ptr = out_category.read_pointer
+
+        name = name_ptr.read_string_to_null
+        conv_factor = conv_factor_ptr.read_double
+        category = category_ptr.read_string_to_null
+
+        Unit.new(auth_name, code, name, category, conv_factor, nil, false)
+      else
+        Error.check_context(self.context)
+      end
+    end
+  end
+end

data/lib/proj/datum.rb

@@ -0,0 +1,32 @@
+module Proj
+  class Datum < PjObject
+    # Returns the frame reference epoch of a dynamic geodetic or vertical reference frame
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_dynamic_datum_get_frame_reference_epoch
+    #
+    # @return [Double] The frame reference epoch as decimal year, or -1 in case of error.
+    def frame_reference_epoch
+      Api.proj_dynamic_datum_get_frame_reference_epoch(self.context, self)
+    end
+
+    # Return the ellipsoid
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_ellipsoid
+    #
+    # @return [PjObject]
+    def ellipsoid
+      ptr = Api.proj_get_ellipsoid(self.context, self)
+      self.class.create_object(ptr, self.context)
+    end
+
+    # Returns the prime meridian
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_prime_meridian
+    #
+    # @return [PjObject]
+    def prime_meridian
+      ptr = Api.proj_get_prime_meridian(self.context, self)
+      self.class.create_object(ptr, self.context)
+    end
+  end
+end

data/lib/proj/datum_ensemble.rb

@@ -0,0 +1,34 @@
+module Proj
+  class DatumEnsemble < PjObject
+
+    # Returns the number of members of a datum ensemble
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_datum_ensemble_get_member_count
+    #
+    # @return [Integer]
+    def count
+      Api.proj_datum_ensemble_get_member_count(self.context, self)
+    end
+
+    # Returns a member from a datum ensemble.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_datum_ensemble_get_member
+    #
+    # @param index [Integer] Index of the datum member to extract. Should be between 0 and DatumEnsembel#count - 1.
+    #
+    # @return [Integer]
+    def [](index)
+      ptr = Api.proj_datum_ensemble_get_member(self.context, self, index)
+      self.class.create_object(ptr, self.context)
+    end
+
+    # Returns the positional accuracy of the datum ensemble
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_datum_ensemble_get_accuracy
+    #
+    # @return [Float] The data ensemble accuracy or -1 in case of error
+    def accuracy
+      Api.proj_datum_ensemble_get_accuracy(self.context, self)
+    end
+  end
+end

data/lib/proj/ellipsoid.rb

@@ -1,42 +1,78 @@
-module Proj
-  class Ellipsoid
-    attr_reader :id, :major, :ell, :name
-
-    def self.list
-      pointer_to_array = FFI::Pointer.new(Api::PJ_ELLPS, Api.proj_list_ellps)
-      result = Array.new
-      0.step do |i|
-        ellipse_info = Api::PJ_ELLPS.new(pointer_to_array[i])
-        break result if ellipse_info[:id].nil?
-        result << self.new(ellipse_info[:id], ellipse_info[:major], ellipse_info[:ell], ellipse_info[:name])
-      end
-    end
-
-    def self.get(id)
-      self.list.find {|ellipsoid| ellipsoid.id == id}
-    end
-
-    def initialize(id, major, ell, name)
-      @id = id
-      @major = major
-      @ell = ell
-      @name = name
-    end
-
-    def <=>(other)
-      self.id <=> other.id
-    end
-
-    def ==(other)
-      self.id == other.id
-    end
-
-    def to_s
-      self.id
-    end
-    
-    def inspect
-      "#<#{self.class} id=\"#{id}\", major=\"#{major}\", ell=\"#{ell}\", name=\"#{name}\">"
-    end
-  end
+module Proj
+  class Ellipsoid < PjObject
+    # Returns a list of ellipsoids that are built into Proj. A more comprehensive
+    # list is stored in the Proj database and can be queried via PjObject#create_from_database
+    def self.built_in
+      pointer_to_array = FFI::Pointer.new(Api::PJ_ELLPS, Api.proj_list_ellps)
+
+      result = Array.new
+      0.step do |i|
+        pj_ellps = Api::PJ_ELLPS.new(pointer_to_array[i])
+        break result if pj_ellps[:id].nil?
+        result << pj_ellps
+      end
+      result
+    end
+
+    # Returns ellipsoid parameters
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_ellipsoid_get_parameters
+    #
+    # @return [Hash] Hash of ellipsoid parameters. Axes are in meters
+    def parameters
+      @parameters ||= begin
+        out_semi_major_metre = FFI::MemoryPointer.new(:double)
+        out_semi_minor_metre = FFI::MemoryPointer.new(:double)
+        out_is_semi_minor_computed = FFI::MemoryPointer.new(:int)
+        out_inv_flattening = FFI::MemoryPointer.new(:double)
+
+        result = Api.proj_ellipsoid_get_parameters(self.context, self, out_semi_major_metre, out_semi_minor_metre, out_is_semi_minor_computed, out_inv_flattening)
+
+        if result != 1
+          Error.check_object(self)
+        end
+
+        {semi_major_axis: out_semi_major_metre.read_double,
+         semi_minor_axis: out_semi_minor_metre.read_double,
+         semi_minor_axis_computed: out_is_semi_minor_computed.read_int == 1 ? true : false,
+         inverse_flattening: out_inv_flattening.null? ? nil : out_inv_flattening.read_double}
+      end
+    end
+
+    # Returns the semi-major axis in meters
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_ellipsoid_get_parameters
+    #
+    # @return [Double]
+    def semi_major_axis
+      self.parameters[:semi_major_axis]
+    end
+
+    # Returns the semi-minor axis in meters
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_ellipsoid_get_parameters
+    #
+    # @return [Double]
+    def semi_minor_axis
+      self.parameters[:semi_minor_axis]
+    end
+
+    # Returns whether the semi-minor axis is computed
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_ellipsoid_get_parameters
+    #
+    # @return [Boolean]
+    def semi_minor_axis_computed
+      self.parameters[:semi_minor_axis_computed]
+    end
+
+    # Returns the inverse flattening value
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_ellipsoid_get_parameters
+    #
+    # @return [Double]
+    def inverse_flattening
+      self.parameters[:inverse_flattening]
+    end
+  end
 end

data/lib/proj/error.rb

@@ -1,18 +1,71 @@
 module Proj
+  # Represents error thrown by Proj
+  #
+  # @see https://proj.org/development/errorhandling.html
   class Error < StandardError
-    def self.check(errno=nil)
-      unless errno
-        errno = Context.current.errno
+    # Error codes typically related to coordinate operation initialization
+    PROJ_ERR_INVALID_OP = 1024 # Other/unspecified error related to coordinate operation initialization
+    PROJ_ERR_INVALID_OP_WRONG_SYNTAX = PROJ_ERR_INVALID_OP + 1 # Invalid pipeline structure, missing +proj argument, etc
+    PROJ_ERR_INVALID_OP_MISSING_ARG = PROJ_ERR_INVALID_OP + 2 # Missing required operation parameter
+    PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE = PROJ_ERR_INVALID_OP + 3 # One of the operation parameter has an illegal value
+    PROJ_ERR_INVALID_OP_MUTUALLY_EXCLUSIVE_ARGS = PROJ_ERR_INVALID_OP + 4 # Mutually exclusive arguments
+    PROJ_ERR_INVALID_OP_FILE_NOT_FOUND_OR_INVALID = PROJ_ERR_INVALID_OP + 5 # File not found (particular case of PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE)
+
+    # Error codes related to transformation on a specific coordinate
+    PROJ_ERR_COORD_TRANSFM = 2048 # Other error related to coordinate transformation
+    PROJ_ERR_COORD_TRANSFM_INVALID_COORD  = PROJ_ERR_COORD_TRANSFM + 1 # For e.g lat > 90deg
+    PROJ_ERR_COORD_TRANSFM_OUTSIDE_PROJECTION_DOMAIN = PROJ_ERR_COORD_TRANSFM + 2 # Coordinate is outside of the projection domain. e.g approximate mercator with |longitude - lon_0| > 90deg, or iterative convergence method failed
+    PROJ_ERR_COORD_TRANSFM_NO_OPERATION = PROJ_ERR_COORD_TRANSFM + 3 # No operation found, e.g if no match the required accuracy, or if ballpark transformations were asked to not be used and they would be only such candidate
+    PROJ_ERR_COORD_TRANSFM_OUTSIDE_GRID = PROJ_ERR_COORD_TRANSFM + 4 # Point to transform falls outside grid or subgrid
+    PROJ_ERR_COORD_TRANSFM_GRID_AT_NODATA = PROJ_ERR_COORD_TRANSFM + 5 # Point to transform falls in a grid cell that evaluates to nodata
+
+    # Other type of errors
+    PROJ_ERR_OTHER = 4096
+    PROJ_ERR_OTHER_API_MISUSE = PROJ_ERR_OTHER + 1 # Error related to a misuse of PROJ API
+    PROJ_ERR_OTHER_NO_INVERSE_OP = PROJ_ERR_OTHER + 2 # No inverse method available
+    PROJ_ERR_OTHER_NETWORK_ERROR = PROJ_ERR_OTHER + 3 # Failure when accessing a network resource
+
+    # Check the context to see if an error occurred. If an error has happened will
+    # raise an exception.
+    def self.check_context(context)
+      unless context.errno == 0
+        # raise(self, "#{self.category(context.errno)}: #{self.message(context)}")
+        raise(self, self.message(context, context.errno))
       end
+    end
 
-      if errno != 0
-        message = if Api.method_defined?(:proj_errno_string)
-                    Api.proj_errno_string(errno)
-                  else
-                    Api.pj_strerrno(errno)
-                  end
+    def self.check_object(pj_object)
+      # It would be nice if Proj exposed the proj_context_errno_set method so
+      # we don't need a pj_object
+      context = pj_object.context
+      unless context.errno == 0
+        message = self.message(context, context.errno)
+        Api.proj_errno_reset(pj_object)
         raise(self, message)
       end
     end
+
+    # Returns the current error-state of the context. An non-zero error codes indicates an error.
+    #
+    # See https://proj.org/development/reference/functions.html#c.proj_errno_string proj_errno_string
+    #
+    # @param context [Context] The context the error occurred in
+    # @param errno [Integer] The error number
+    #
+    # return [String]
+    def self.message(context, errno)
+      if Api.method_defined?(:proj_context_errno_string)
+        Api.proj_context_errno_string(context, errno)
+      elsif Api.method_defined?(:proj_errno_string)
+        Api.proj_errno_string(errno)
+      end
+    end
+
+    # Converts an errno to a error category
+    def self.category(errno)
+      self.constants.find do |constant|
+        self.const_get(constant) == errno
+      end
+    end
   end
 end