proj4rb 3.0.0 → 4.0.0

data/lib/proj/session.rb

@@ -0,0 +1,46 @@
+module Proj
+  class Session
+    attr_reader :context
+
+    def self.finalize(context, pointer)
+      proc do
+        Api.proj_insert_object_session_destroy(context, pointer)
+      end
+    end
+
+    def initialize(context = nil)
+      @context = context || Context.current
+      @pointer = Api.proj_insert_object_session_create(@context)
+      ObjectSpace.define_finalizer(self, self.class.finalize(@context, @pointer))
+    end
+
+    def to_ptr
+      @pointer
+    end
+
+    # Returns SQL statements needed to insert the passed object into the database.
+    #
+    # @param object [PjObject] - The object to insert into the database. Currently only PrimeMeridian, Ellipsoid, Datum, GeodeticCRS, ProjectedCRS, VerticalCRS, CompoundCRS or BoundCRS are supported.
+    # @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
+    # @param numeric_codes [Boolean] - Whether intermediate objects that can be created should use numeric codes (true), or may be alphanumeric (false)
+    # @param allowed_authorities  [Array[String]] - Authorities to which intermediate objects are allowed to refer to. "authority" will be implicitly added to it.
+    #
+    # @return [Strings] - List of insert statements
+    def get_insert_statements(object, authority, code, numeric_codes = false, allowed_authorities = nil)
+      allowed_authorities_ptr = if allowed_authorities
+                                  # Add extra item at end for null pointer
+                                  pointer = FFI::MemoryPointer.new(:pointer, allowed_authorities.size + 1)
+
+                                  # Convert strings to C chars
+                                  allowed_authorities.each_with_index do |authority, i|
+                                    pointer.put_pointer(i, FFI::MemoryPointer.from_string(authority))
+                                  end
+                                  pointer
+                                end
+
+      strings_ptr = Api.proj_get_insert_statements(self.context, self, object, authority, code, numeric_codes ? 1 : 0, allowed_authorities_ptr, nil)
+      Strings.new(strings_ptr)
+    end
+  end
+end

data/lib/proj/strings.rb

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+require 'forwardable'
+
+module Proj
+  class Strings
+    include Enumerable
+    extend Forwardable
+
+    attr_reader :strings
+
+    def initialize(pointer)
+      @strings = Array.new
+      read_strings(pointer)
+      Api.proj_string_list_destroy(pointer)
+    end
+
+    private
+
+    def read_strings(pointer)
+      unless pointer.null?
+        loop do
+          string_ptr = pointer.read_pointer
+          break if string_ptr.null?
+          @strings << string_ptr.read_string_to_null
+          pointer += FFI::Pointer::SIZE
+        end
+      end
+    end
+
+    def_delegators :@strings, :[], :count, :each, :empty?, :join, :size, :length, :to_s
+  end
+end

data/lib/proj/transformation.rb

@@ -1,61 +1,102 @@
-module Proj
-  # Transformation objects convert {Coordinate Coordinates} from one {Crs} to another.
-  class Transformation < PjObject
-    # Transforms a {Coordinate} from the source {Crs} to the target {Crs}. Coordinates should be expressed in
-    # the units and axis order of the definition of the source CRS. The returned transformed coordinate will
-    # be in the units and axis order of the definition of the target CRS.
-    #
-    # For most geographic Crses, the units will be in degrees. For geographic CRS defined by the EPSG authority,
-    # the order of coordinates is latitude first, longitude second. When using a PROJ initialization string,
-    # on contrary, the order will be longitude first, latitude second.
-    #
-    # For projected CRS, the units may vary (metre, us-foot, etc..).
-    #
-    # For projected CRS defined by the EPSG authority, and with EAST / NORTH directions, the axis order might be
-    # easting first, northing second, or the reverse. When using a PROJ string, the order will be
-    # easting first, northing second, except if the +axis parameter modifies it.
-    #
-    # @param source [Crs | String] - The source Crs. See the Crs documentation for the string format
-    # @param target [Crs | String] - The target Crs. See the Crs documentation for the string format
-    # @param context [Context]
-    def initialize(source, target, context=nil)
-      pointer = if source.is_a?(Crs) && target.is_a?(Crs)
-                  if Api.method_defined?(:proj_create_crs_to_crs_from_pj)
-                    Api.proj_create_crs_to_crs_from_pj(context, source, target, nil, nil)
-                  else
-                    Api.proj_create_crs_to_crs(context, source.definition, target.definition, nil)
-                  end
-                else
-                  Api.proj_create_crs_to_crs(context, source, target, nil)
-                end
-
-      if pointer.null?
-        Error.check
-      end
-
-      super(pointer, context)
-    end
-
-    # Transforms a {Coordinate} from the source {Crs} to the target {Crs}. Coordinates should be expressed in
-    # the units and axis order of the definition of the source CRS. The returned transformed coordinate will
-    # be in the units and axis order of the definition of the target CRS.
-    #
-    # @param coord [Coordinate]
-    # @return [Coordinate]
-    def forward(coord)
-      struct = Api.proj_trans(self, :PJ_FWD, coord)
-      Coordinate.from_coord(struct)
-    end
-
-    # Transforms a {Coordinate} from the target {Crs} to the source {Crs}. Coordinates should be expressed in
-    # the units and axis order of the definition of the source CRS. The returned transformed coordinate will
-    # be in the units and axis order of the definition of the target CRS.
-    #
-    # @param coord [Coordinate]
-    # @return [Coordinate]
-    def inverse(coord)
-      struct = Api.proj_trans(self, :PJ_INV, coord)
-      Coordinate.from_coord(struct)
-    end
-  end
+module Proj
+  # Transformations are {CoordinateOperationMix coordinate operations} that
+  # convert {Coordinate coordinates} from one {Crs} to another.
+  # In Proj they are defined as operations that exert a change in reference frame
+  # while {Conversion conversions } do not.
+  class Transformation < PjObject
+    include CoordinateOperationMixin
+
+    # Create a Transformation
+    #
+    # @param context [Context] Context
+    # @param name [String] Name of the transformation. Default is nil.
+    # @param auth_name [String] Transformation authority name. Default is nil.
+    # @param code [String] Transformation code. Default is nil.
+    # @param source_crs [CoordinateSystem] Source CRS
+    # @param target_crs [CoordinateSystem] Target CRS
+    # @param interpolation_crs [CoordinateSystem] Interpolation. Default is nil
+    # @param method_name [String] Method name. Default is nil.
+    # @param method_auth_name [String] Method authority name. Default is nil.
+    # @param method_code [String] Method code. Default is nil.
+    # @param params [Array<Parameter>] Parameter descriptions
+    # @param accuracy [Double] Accuracy of the transformation in meters. A negative value means unknown.
+    #
+    # @return [Transformation]
+    def self.create(context, name: nil, auth_name: nil, code: nil,
+                    source_crs:, target_crs:, interpolation_crs: nil,
+                    method_name: nil, method_auth_name: nil, method_code: nil,
+                    params:, accuracy:)
+
+      params_ptr = FFI::MemoryPointer.new(Api::PJ_PARAM_DESCRIPTION, params.size)
+      params.each_with_index do |param, i|
+        param_description_target = Api::PJ_PARAM_DESCRIPTION.new(params_ptr[i])
+        param_description_source = param.to_description
+        param_description_target.to_ptr.__copy_from__(param_description_source.to_ptr, Api::PJ_PARAM_DESCRIPTION.size)
+      end
+
+      ptr = Api.proj_create_transformation(context, name, auth_name, code,
+                                           source_crs, target_crs, interpolation_crs,
+                                           method_name, method_auth_name, method_code,
+                                           params.count, params_ptr, accuracy)
+      self.create_object(ptr, context)
+    end
+
+    # Transforms a {Coordinate} from the source {Crs} to the target {Crs}. Coordinates should be expressed in
+    # the units and axis order of the definition of the source CRS. The returned transformed coordinate will
+    # be in the units and axis order of the definition of the target CRS.
+    #
+    # For most geographic Crses, the units will be in degrees. For geographic CRS defined by the EPSG authority,
+    # the order of coordinates is latitude first, longitude second. When using a PROJ initialization string,
+    # on contrary, the order will be longitude first, latitude second.
+    #
+    # For projected CRS, the units may vary (metre, us-foot, etc..).
+    #
+    # For projected CRS defined by the EPSG authority, and with EAST / NORTH directions, the axis order might be
+    # easting first, northing second, or the reverse. When using a PROJ string, the order will be
+    # easting first, northing second, except if the +axis parameter modifies it.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_create_crs_to_crs_from_pj
+    # @see  https://proj.org/development/reference/functions.html#c.proj_create_crs_to_crs proj_create_crs_to_crs
+    #
+    # @param source [Crs | String] The source Crs. See the Crs documentation for the string format
+    # @param target [Crs | String] The target Crs. See the Crs documentation for the string format
+    # @param area [Area] If an area is specified a more accurate transformation between two given systems can be chosen
+    # @param context [Context]
+    # @param authority [String] Restricts the authority of coordinate operations looked up in the database
+    # @param accuracy [Float] Sets the minimum desired accuracy (in metres) of the candidate coordinate operations
+    # @param allow_ballpark [Boolean] Set to false to disallow the use of Ballpark transformation in the candidate coordinate operations.
+    # @param only_best [Boolean] Set to true to cause PROJ to error out if the best transformation cannot be used. Requires Proj 9.2 and higher
+    #
+    # @return [Transformation] A new transformation
+    def initialize(source, target, context=nil,
+                   area: nil, authority: nil, accuracy: nil, allow_ballpark: nil, only_best: nil, force_over: nil)
+
+      context ||= Context.current
+
+      options = {"AUTHORITY": authority,
+                 "ACCURACY": accuracy.nil? ? nil : accuracy.to_s,
+                 "ALLOW_BALLPARK": allow_ballpark.nil? ? nil : (allow_ballpark ? "YES" : "NO"),
+                 "ONLY_BEST": only_best.nil? ? nil : (only_best ? "YES" : "NO"),
+                 "FORCE_OVER": force_over.nil? ? nil : (force_over ? "YES" : "NO")}
+      options_ptr = create_options_pointer(options)
+
+      ptr = if source.is_a?(Crs) && target.is_a?(Crs)
+              if Api.method_defined?(:proj_create_crs_to_crs_from_pj)
+                Api.proj_create_crs_to_crs_from_pj(context, source, target, area, options_ptr)
+              else
+                Api.proj_create_crs_to_crs(context, source.definition, target.definition, area)
+              end
+            else
+              Api.proj_create_crs_to_crs(context, source, target, nil)
+            end
+
+      if ptr.null?
+        Error.check_context(context)
+        # If that does not raise an error then no operation was found
+        raise(Error, "No operation found matching criteria")
+      end
+
+      super(ptr, context)
+    end
+  end
 end

data/lib/proj/unit.rb

@@ -1,54 +1,109 @@
-module Proj
-  class Unit
-    attr_reader :id, :to_meter, :factor, :name
-
-    def self.list
-      # First get linear units
-      pointer_to_array = FFI::Pointer.new(Api::PJ_UNITS, Api.proj_list_units)
-      result = Array.new
-      0.step do |i|
-        ellipse_info = Api::PJ_UNITS.new(pointer_to_array[i])
-        break if ellipse_info[:id].nil?
-        result << self.new(ellipse_info[:id], ellipse_info[:to_meter], ellipse_info[:factor], ellipse_info[:name])
-      end
-
-      # Now get angular linear units
-      if Api.method_defined?(:proj_list_angular_units)
-        pointer_to_array = FFI::Pointer.new(Api::PJ_UNITS, Api.proj_list_angular_units)
-        0.step do |i|
-          ellipse_info = Api::PJ_UNITS.new(pointer_to_array[i])
-          break result if ellipse_info[:id].nil?
-          result << self.new(ellipse_info[:id], ellipse_info[:to_meter], ellipse_info[:factor], ellipse_info[:name])
-        end
-      end
-      result
-    end
-
-    def self.get(id)
-      self.list.find {|ellipsoid| ellipsoid.id == id}
-    end
-
-    def initialize(id, to_meter, factor, name)
-      @id = id
-      @to_meter = to_meter
-      @factor = factor
-      @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}\", to_meter=\"#{to_meter}\", factor=\"#{factor}\", name=\"#{name}\">"
-    end
-  end
+module Proj
+  class Unit
+    # @!attribute [r] auth_name
+    #   @return [String] Authority name
+    # @!attribute [r] code
+    #   @return [String] Object code
+    # @!attribute [r] name
+    #   @return [String] Object name. For example "metre", "US survey foot", etc
+    # @!attribute [r] category
+    #   @return [String] Category of the unit: one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time"
+    # @!attribute [r] conv_factor
+    #   @return [String] Conversion factor to apply to transform from that unit to the corresponding SI unit (metre for "linear", radian for "angular", etc.). It might be 0 in some cases to indicate no known conversion factor
+    # @!attribute [r] proj_short_name
+    #   @return [String] PROJ short name, like "m", "ft", "us-ft", etc... Might be nil
+    # @!attribute [r] deprecated
+    #   @return [Boolean] Whether the object is deprecated
+    attr_reader :auth_name, :code, :name, :category, :conv_factor, :proj_short_name, :deprecated
+
+    # Returns a list of built in Units. This is deprecated. Use Database#units instead
+    def self.built_in(auth_name: nil, category: nil, allow_deprecated: false)
+      # First get linear units
+      pointer_to_array = FFI::Pointer.new(Api::PJ_UNITS, Api.proj_list_units)
+      result = Array.new
+      0.step do |i|
+        unit_info = Api::PJ_UNITS.new(pointer_to_array[i])
+        break if unit_info[:id].nil?
+        result << self.new('PROJ', unit_info[:id], unit_info[:name],
+                           'length', unit_info[:factor], unit_info[:id], false)
+      end
+
+      # Now get angular linear units
+      if Api.method_defined?(:proj_list_angular_units)
+        pointer_to_array = FFI::Pointer.new(Api::PJ_UNITS, Api.proj_list_angular_units)
+        0.step do |i|
+          unit_info = Api::PJ_UNITS.new(pointer_to_array[i])
+          break result if unit_info[:id].nil?
+          result << self.new('PROJ', unit_info[:id], unit_info[:name],
+                             'angular', unit_info[:factor], unit_info[:id], false)
+        end
+      end
+
+      if auth_name
+        result = result.find_all {|unit_info| unit_info.auth_name == auth_name}
+      end
+
+      if category
+        result = result.find_all {|unit_info| unit_info.category == category}
+      end
+      result
+    end
+
+    # Create a new Unit
+    # 
+    # @param auth_name [String] Authority name
+    # @param code [String] Object code
+    # @param name [String] Object name. For example "metre", "US survey foot", etc
+    # @param category [String] Category of the unit: one of "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time" or "time"
+    # @param conv_factor [String] Conversion factor to apply to transform from that unit to the corresponding SI unit (metre for "linear", radian for "angular", etc.). It might be 0 in some cases to indicate no known conversion factor
+    # @param proj_short_name [String] PROJ short name, like "m", "ft", "us-ft", etc... Might be nil
+    # @param deprecated [Boolean] Whether the object is deprecated
+    #
+    # @return [Unit]
+    def initialize(auth_name, code, name, category, conv_factor, proj_short_name, deprecated)
+      @auth_name = auth_name
+      @code = code
+      @name = name
+      @category = category
+      @conv_factor = conv_factor
+      @proj_short_name = proj_short_name
+      @deprecated = deprecated
+    end
+
+    def <=>(other)
+      self.name <=> other.name
+    end
+
+    def ==(other)
+      self.auth_name == other.auth_name &&
+      self.code == other.code
+    end
+
+    def type
+      case self.category
+      when "linear"
+        :PJ_UT_LINEAR
+      when "linear_per_time"
+        :PJ_UT_LINEAR
+      when "angular"
+        :PJ_UT_ANGULAR
+      when "angular_per_time"
+        :PJ_UT_ANGULAR
+      when "scale"
+        :PJ_UT_SCALE
+      when "scale_per_time"
+        :PJ_UT_SCALE
+      when "time"
+        :PJ_UT_TIME
+      end
+    end
+
+    def to_s
+      self.name
+    end
+    
+    def inspect
+      "#<#{self.class} authority=\"#{auth_name}\", code=\"#{code}\", name=\"#{name}\">"
+    end
+  end
 end

data/lib/proj.rb

@@ -1,31 +1,132 @@
 # encoding: UTF-8
 
 require_relative 'api/api'
-require_relative 'proj/config'
+
+require_relative 'proj/pj_object'
+require_relative 'proj/pj_objects'
+require_relative 'proj/coordinate_operation_mixin'
+require_relative 'proj/projection'
+require_relative 'proj/conversion'
+require_relative 'proj/crs'
+require_relative 'proj/transformation'
 
 require_relative 'proj/area'
+require_relative 'proj/axis_info'
+require_relative 'proj/bounds'
+require_relative 'proj/coordinate_system'
+require_relative 'proj/crs_info'
 require_relative 'proj/context'
 require_relative 'proj/coordinate'
+require_relative 'proj/database'
+require_relative 'proj/datum'
+require_relative 'proj/datum_ensemble'
 require_relative 'proj/ellipsoid'
 require_relative 'proj/error'
-require_relative 'proj/point'
+require_relative 'proj/file_api'
+require_relative 'proj/grid'
+require_relative 'proj/grid_cache'
+require_relative 'proj/grid_info'
+require_relative 'proj/network_api'
+require_relative 'proj/parameter'
+require_relative 'proj/operation'
+require_relative 'proj/operation_factory_context'
+require_relative 'proj/parameters'
 require_relative 'proj/prime_meridian'
+require_relative 'proj/session'
+require_relative 'proj/strings'
 require_relative 'proj/unit'
 
-require_relative 'proj/pj_object'
-require_relative 'proj/operation'
-require_relative 'proj/crs'
-require_relative 'proj/projection'
-require_relative 'proj/transformation'
-
 module Proj
+  # Returns information about the Proj library
+  #
+  # @see https://proj.org/development/reference/functions.html#c.proj_info proj_info
   def self.info
     Api.proj_info
   end
 
+  # Returns the Proj version
+  #
+  # @see https://proj.org/development/reference/functions.html#c.proj_info proj_info
   def self.version
     self.info[:version]
   end
+
+  # Returns default search paths
+  #
+  # @see https://proj.org/development/reference/functions.html#c.proj_info proj_info
+  #
+  # @return Array<string> List of search paths
+  def self.search_paths
+    self.info[:searchpath].split(";")
+  end
+
+  # Return information about the specific init file
+  #
+  # @see https://proj.org/development/reference/functions.html#c.proj_init_info proj_init_info
+  #
+  # @param file_name [String] The name of the init file (not the path)
+  #
+  # @return [PJ_INIT_INFO]
+  def self.init_file_info(file_name)
+    Api.proj_init_info(file_name)
+  end
+
+  # Converts degrees to radians
+  #
+  # see https://proj.org/development/reference/functions.html#c.proj_torad proj_torad
+  #
+  # @param value [Double] Value in degrees to convert
+  #
+  # @return [Double]
+  def self.degrees_to_radians(value)
+    Api.proj_torad(value)
+  end
+
+  # Converts radians degrees
+  #
+  # see https://proj.org/development/reference/functions.html#c.proj_todeg proj_todeg
+  #
+  # @param value [Double] Value in radians to convert
+  #
+  # @return [Double]
+  def self.radians_to_degrees(value)
+    Api.proj_todeg(value)
+  end
+
+  # Convert string of degrees, minutes and seconds to radians.
+  #
+  # see https://proj.org/development/reference/functions.html#c.proj_dmstor proj_dmstor
+  #
+  # @param value [String] Value to be converted to radians
+  #
+  # @return [Double]
+  def self.degrees_minutes_seconds_to_radians(value)
+    ptr = FFI::MemoryPointer.new(:string)
+    Api.proj_dmstor(value, ptr)
+  end
+
+  # Convert radians to a string representation of degrees, minutes and seconds
+  #
+  # @see https://proj.org/development/reference/functions.html#c.proj_rtodms proj_rtodms
+  # @see https://proj.org/development/reference/functions.html#c.proj_rtodms2 proj_rtodms2
+  #
+  # @param value [Double] Value to be converted in radians
+  # @param positive [String] Character denoting positive direction, typically 'N' or 'E'. Default 'N'
+  # @param negative [String] Character denoting negative direction, typically 'S' or 'W'. Default 'S'
+  #
+  # @return [String]
+  def self.radians_to_degrees_minutes_seconds(value, positive='N', negative='S')
+    ptr = FFI::MemoryPointer.new(:char, 100)
+    if Api::PROJ_VERSION < Gem::Version.new('9.2.0')
+      Api.proj_rtodms(ptr, value, positive.ord, negative.ord)
+    else
+      Api.proj_rtodms2(ptr, ptr.size, value, positive.ord, negative.ord)
+    end
+    ptr.read_string_to_null
+  end
 end
 
-Proj::Config.instance.set_search_paths
+at_exit do
+  # Clean up any Proj allocated resources on exit. See https://proj.org/development/reference/functions.html#c.proj_cleanup
+  Proj::Api.proj_cleanup
+end

data/proj4rb.gemspec

@@ -1,17 +1,17 @@
 Gem::Specification.new do |spec|
   spec.name = 'proj4rb'
-  spec.version = '3.0.0'
-  spec.summary = 'Ruby bindings for the Proj.4 Carthographic Projection library'
+  spec.version = '4.0.0'
+  spec.summary = 'Ruby bindings for the Proj coordinate transformation library'
   spec.description = <<-EOF
-    Proj4rb is a ruby binding for the Proj.4 Carthographic Projection library, that supports conversions between a very large number of geographic coordinate systems and datumspec.
+    Ruby bindings for the Proj coordinate transformation library
   EOF
   spec.platform = Gem::Platform::RUBY
   spec.authors = ['Guilhem Vellut', 'Jochen Topf', 'Charlie Savage']
   spec.homepage = 'https://github.com/cfis/proj4rb'
-  spec.required_ruby_version = '>= 2.4.1'
+  spec.required_ruby_version = '>= 2.7'
   spec.license = 'MIT'
 
-  spec.requirements << 'Proj (Proj4) Library'
+  spec.requirements << 'Proj Library'
   spec.require_path = 'lib'
   spec.files = Dir['ChangeLog',
                    'Gemfile',

data/test/abstract_test.rb

@@ -3,5 +3,27 @@ require 'minitest/autorun'
 require 'proj'
 
 class AbstractTest < Minitest::Test
-end
+  def self.proj7?
+    Proj::Api::PROJ_VERSION >= Gem::Version.new("7.0.0")
+  end
 
+  def self.proj8?
+    Proj::Api::PROJ_VERSION >= Gem::Version.new("8.0.0")
+  end
+
+  def self.proj9?
+    Proj::Api::PROJ_VERSION >= Gem::Version.new("9.0.0")
+  end
+
+  def proj7?
+    self.class.proj7?
+  end
+
+  def proj8?
+    self.class.proj8?
+  end
+
+  def proj9?
+    self.class.proj9?
+  end
+end