proj4rb 3.0.0 → 4.0.0

data/lib/proj/area.rb

@@ -1,32 +1,73 @@
-module Proj
-  class Area
-    attr_reader :name, :west_lon_degree, :south_lat_degree, :east_lon_degree, :north_lat_degree
-
-    def self.for_object(pj_object)
-      p_name = FFI::MemoryPointer.new(:pointer)
-      p_west_lon_degree = FFI::MemoryPointer.new(:double)
-      p_south_lat_degree = FFI::MemoryPointer.new(:double)
-      p_east_lon_degree = FFI::MemoryPointer.new(:double)
-      p_north_lat_degree = FFI::MemoryPointer.new(:double)
-
-      result = Api.proj_get_area_of_use(Context.current, pj_object,
-                                        p_west_lon_degree, p_south_lat_degree, p_east_lon_degree, p_north_lat_degree,
-                                        p_name)
-      unless result
-        Error.check
-      end
-
-      name = p_name.read_pointer.read_string_to_null.force_encoding('utf-8')
-      self.new(name,
-               p_west_lon_degree.read_double, p_south_lat_degree.read_double, p_east_lon_degree.read_double, p_north_lat_degree.read_double)
-    end
-
-    def initialize(name, west_lon_degree, south_lat_degree, east_lon_degree, north_lat_degree)
-      @name = name
-      @west_lon_degree = west_lon_degree
-      @south_lat_degree = south_lat_degree
-      @east_lon_degree = east_lon_degree
-      @north_lat_degree = north_lat_degree
-    end
-  end
-end
+# encoding: UTF-8
+
+module Proj
+  # Areas are used to specify the area of use for the choice of relevant coordinate operations.
+  # See Transformation#new
+  class Area
+    attr_reader :name, :west_lon_degree, :south_lat_degree, :east_lon_degree, :north_lat_degree
+
+    def self.finalize(pointer)
+      proc do
+        Api.proj_area_destroy(pointer)
+      end
+    end
+
+    def initialize(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:, name: nil)
+      @west_lon_degree = west_lon_degree
+      @south_lat_degree = south_lat_degree
+      @east_lon_degree = east_lon_degree
+      @north_lat_degree = north_lat_degree
+      @name = name
+      create_area
+    end
+
+    def to_ptr
+      @area
+    end
+
+    # Sets the bounds for an area
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_area_set_bbox
+    #
+    # @param west_lon_degree [Float] West longitude, in degrees. In [-180,180] range.
+    # @param south_lat_degree [Float] South latitude, in degrees. In [-90,90] range.
+    # @param east_lon_degree [Float] East longitude, in degrees. In [-180,180] range.
+    # @param north_lat_degree [Float] North latitude, in degrees. In [-90,90] range.
+    def set_bounds(west_lon_degree:, south_lat_degree:, east_lon_degree:, north_lat_degree:)
+      Api.proj_area_set_bbox(self, west_lon_degree, south_lat_degree, east_lon_degree, north_lat_degree)
+    end
+
+    # Sets the name for an area
+    #
+    # @param value [String] The name of the area
+    def name=(value)
+      @name = name
+      # This Api wasn't added until proj 9.1
+      if defined?(Api.proj_area_set_name)
+        Api.proj_area_set_name(self, value)
+      end
+    end
+
+    # Returns nice printout of an Area
+    #
+    # @return [String]
+    def to_s
+      "Area west_lon_degree: #{self.west_lon_degree}, south_lat_degree: #{self.south_lat_degree}, east_lon_degree: #{self.east_lon_degree}, north_lat_degree: #{self.north_lat_degree}"
+    end
+
+    private
+
+    # Creates an area
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_area_create
+    def create_area
+      @area = Api.proj_area_create
+      self.set_bounds(west_lon_degree: west_lon_degree, south_lat_degree: south_lat_degree,
+                      east_lon_degree: east_lon_degree, north_lat_degree: north_lat_degree)
+      if name
+        self.name = name
+      end
+      ObjectSpace.define_finalizer(self, self.class.finalize(@area))
+    end
+  end
+end

data/lib/proj/axis_info.rb

@@ -0,0 +1,44 @@
+module Proj
+  class AxisInfo
+    # @!attribute [r] name
+    #   @return [String] Axis name
+    # @!attribute [r] abbreviation
+    #   @return [String] Axis abbreviation
+    # @!attribute [r] direction
+    #   @return [String] Axis direction
+    # @!attribute [r] unit_conv_factor
+    #   @return [String] Axis unit_conv_factor
+    # @!attribute [r] unit_name
+    #   @return [String] Axis unit_name
+    # @!attribute [r] unit_auth_name
+    #   @return [String] Axis unit_auth_name
+    # @!attribute [r] unit_code
+    #   @return [String] Axis unit_code
+    attr_reader :name, :abbreviation, :direction,
+                :unit_name, :unit_auth_name, :unit_code, :unit_conv_factor
+
+      def initialize(name:, abbreviation:, direction:, unit_conv_factor:, unit_name:, unit_auth_name:, unit_code:)
+      @name = name
+      @abbreviation = abbreviation
+      @direction = direction
+      @unit_conv_factor = unit_conv_factor
+      @unit_name = unit_name
+      @unit_auth_name = unit_auth_name
+      @unit_code = unit_code
+    end
+
+    # Returns axis information in PJ_AXIS_DESCRIPTION structure
+    #
+    # @return [PJ_AXIS_DESCRIPTION]
+    def to_description
+      Api::PJ_AXIS_DESCRIPTION.create(name: name, abbreviation: abbreviation, direction: direction,
+                                      unit_conv_factor: unit_conv_factor, unit_name: name, unit_type: self.unit_type)
+    end
+    
+    def unit_type
+      database = Database.new(Context.default)
+      unit = database.unit(self.unit_auth_name, self.unit_code)
+      unit.type
+    end
+  end
+end

data/lib/proj/bounds.rb

@@ -0,0 +1,13 @@
+module Proj
+  class Bounds
+    attr_reader :name, :xmin, :ymin, :xmax, :ymax
+
+    def initialize(xmin, ymin, xmax, ymax, name = nil)
+      @xmin = xmin
+      @ymin = ymin
+      @xmax = xmax
+      @ymax = ymax
+      @name = name
+    end
+  end
+end

data/lib/proj/context.rb

@@ -1,10 +1,24 @@
 module Proj
   # Proj 4.8 introduced the concept of a thread context object to support multi-threaded programs. The bindings
-  # automatically create on context per thread (its stored in local thread storage).
+  # automatically create one context per thread (its stored in local thread storage).
   class Context
-    # The context for the current thread
+    attr_reader :database
+
+    # Returns the default Proj context. This context *must* only be used in the main thread
+    # In general it is better to create new contexts
     #
-    # @return [Context]
+    # @return [Context] The default context
+    def self.default
+      result = Context.allocate
+      # The default Proj Context is represented by a null pointer
+      result.instance_variable_set(:@pointer, FFI::Pointer::NULL)
+      result
+    end
+
+    # The context for the current thread. If a context does not exist
+    # a new one is created
+    #
+    # @return [Context] The context for the current thread
     def self.current
       Thread.current[:proj_context] ||= Context.new
     end
@@ -19,43 +33,33 @@ module Proj
       @pointer = Api.proj_context_create
       ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
 
-      set_database_path
+      @database = Database.new(self)
     end
 
-    # Helper method that tries to locate the Proj coordinate database (proj.db)
-    def set_database_path
-      return unless Api.method_defined?(:proj_context_get_database_path)
-      return if database_path
+    def initialize_copy(original)
+      ObjectSpace.undefine_finalizer(self)
+
+      super
 
-      self.database_path = Config.instance.db_path
+      @pointer = Api.proj_context_clone(original)
+      @database = Database.new(self)
+
+      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
     end
 
     def to_ptr
       @pointer
     end
 
-    # Get the last error number
+    # 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_context_errno proj_context_errno
     #
     # return [Integer]
     def errno
       Api.proj_context_errno(self)
     end
 
-    # Gets the path the Proj database
-    #
-    # return [String]
-    def database_path
-      Api.proj_context_get_database_path(self)
-    end
-
-    # Sets the path to the Proj database
-    def database_path=(value)
-      result = Api.proj_context_set_database_path(self, value, nil, nil)
-      unless result == 1
-        Error.check(self.errno)
-      end
-    end
-
     # Sets a custom log function
     #
     # @example
@@ -65,6 +69,7 @@ module Proj
     #
     # @param pointer [FFI::MemoryPointer] Optional pointer to custom data
     # @param proc [Proc] Custom logging procedure
+    #
     # @return [nil]
     def set_log_function(pointer = nil, &proc)
       Api.proj_log_func(self, pointer, proc)
@@ -72,14 +77,14 @@ module Proj
 
     # Gets the current log level
     #
-    # @return [:PJ_LOG_LEVEL]
+    # @return [PJ_LOG_LEVEL]
     def log_level
       Api.proj_log_level(self, :PJ_LOG_TELL)
     end
 
     # Sets the current log level
     #
-    # @param value [:PJ_LOG_LEVEL]
+    # @param value [PJ_LOG_LEVEL]
     # @return [nil]
     def log_level=(value)
       Api.proj_log_level(self, value)
@@ -89,15 +94,156 @@ module Proj
     #
     # @return [Boolean]
     def use_proj4_init_rules
-      Api.proj_context_get_use_proj4_init_rules(self, 0)
+      result = Api.proj_context_get_use_proj4_init_rules(self, 0)
+      result == 1 ? true : false
     end
 
     # Sets if proj4 init rules should be used
     #
     # @param value [Boolean]
+    #
     # @return [nil]
     def use_proj4_init_rules=(value)
       Api.proj_context_use_proj4_init_rules(self, value ? 1 : 0)
     end
+
+    # Guess the "dialect" of the specified WKT string
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_guess_wkt_dialect
+    #
+    # @param wkt [String] A WKT string
+    #
+    # @return [PJ_GUESSED_WKT_DIALECT]
+    def wkt_dialect(wkt)
+      Api.proj_context_guess_wkt_dialect(self, wkt)
+    end
+
+    # Sets the CA Bundle path which will be used by PROJ when curl and PROJ_NETWORK are enabled.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_ca_bundle_path
+    #
+    # @param path [String] Path to CA bundle.
+    #
+    # @return [nil]
+    def ca_bundle_path=(path)
+      Api.proj_context_set_ca_bundle_path(self, path.encode(:utf8))
+    end
+
+    # Returns the cache used to store grid files locally
+    #
+    # @return [GridCache]
+    def cache
+      GridCache.new(self)
+    end
+
+    # Returns if network access is enabled allowing {Grid} files to be downloaded
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_is_network_enabled
+    #
+    # @return [Boolean] True if network access is enabled, otherwise false
+    def network_enabled?
+      result = Api.proj_context_is_network_enabled(self)
+      result == 1 ? true : false
+    end
+
+    # Enable or disable network access for downloading grid files
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_enable_network
+    #
+    # @param value [Boolean] Specifies if network access should be enabled or disabled
+    def network_enabled=(value)
+      Api.proj_context_set_enable_network(self, value ? 1 : 0)
+    end
+
+    # Returns the URL endpoint to query for remote grids
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_url_endpoint
+    #
+    # @return [String] Endpoint URL
+    def url
+      Api.proj_context_get_url_endpoint(self)
+    end
+
+    # Sets the URL endpoint to query for remote grids. This overrides the default endpoint in the PROJ configuration file or with the PROJ_NETWORK_ENDPOINT environment variable.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_url_endpoint
+    #
+    # @param value [String] Endpoint URL
+    def url=(value)
+      Api.proj_context_set_url_endpoint(self, value)
+    end
+
+    # Returns the user directory used to save grid files.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_get_user_writable_directory
+    #
+    # @param [Boolean] If set to TRUE, create the directory if it does not exist already. Defaults to false
+    #
+    # @return [String] Directory
+    def user_directory(create = false)
+      Api.proj_context_get_user_writable_directory(self, create ? 1 : 0)
+    end
+
+    # Sets the paths that Proj will search when opening one of its resource files
+    # such as the proj.db database, grids, etc.
+    #
+    # If set on the default context, they will be inherited by contexts created later.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_search_paths
+    def search_paths=(paths)
+      # Convert paths to C chars
+      paths_ptr = paths.map do |path|
+        FFI::MemoryPointer.from_string(path)
+      end
+
+      pointer = FFI::MemoryPointer.new(:pointer, paths.size)
+      pointer.write_array_of_pointer(paths_ptr)
+
+      if Api.method_defined?(:proj_context_set_search_paths)
+        Api.proj_context_set_search_paths(self, paths.size, pointer)
+      elsif Api.method_defined?(:pj_set_searchpath)
+        Api.pj_set_searchpath(paths.size, pointer)
+      end
+    end
+
+    # Installs a new {FileApi FileApiImpl}
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_fileapi
+    def set_file_api(file_api_klass)
+      unless file_api_klass.kind_of?(Class)
+        raise("#{file_api_klass} must be a class whose initializer has single argument which is a context")
+      end
+
+      # There is no API to "uninstall" a FileApi. Thus it needs to stay alive
+      # until the context is GCed
+      @file_api = file_api_klass.new(self)
+    end
+
+    # Installs a new {NetworkApi NetworkApiImpl}
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_network_callbacks
+    def set_network_api(network_api_klass)
+      unless network_api_klass.kind_of?(Class)
+        raise("#{network_api_klass} must be a class whose initializer has single argument which is a context")
+      end
+
+      # There is no API to "uninstall" a FileApi. Thus it needs to stay alive
+      # until the context is GCed
+      @network_api = network_api_klass.new(self)
+    end
+
+    # ---  Deprecated -------
+    def database_path
+      self.database.path
+    end
+
+    # Sets the path to the Proj database
+    def database_path=(value)
+      self.database.path = value
+    end
+
+    extend Gem::Deprecate
+    deprecate :database_path, "context.database.path", 2023, 6
+    deprecate :database_path=, "context.database.path=", 2023, 6
   end
 end

data/lib/proj/conversion.rb

@@ -0,0 +1,92 @@
+# encoding: UTF-8
+require 'stringio'
+
+module Proj
+  # Conversions are {CoordinateOperationMix coordinate operations} that convert a source
+  # {Coordinate coordinate} to a new value. In Proj they are defined as operations that
+  # do not exert a change in reference frame while {Transformation transformations } do.
+  class Conversion < PjObject
+    include CoordinateOperationMixin
+
+    # Instantiate a Conversion
+
+    # 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 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 [Conversion]
+    def self.create_conversion(context, name:, auth_name:, code:, method_name:, method_auth_name:, method_code:, params:)
+      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
+
+      pointer = Api.proj_create_conversion(context, name, auth_name, code, method_name, method_auth_name, method_code, params.size, params_ptr)
+      Error.check_context(context)
+      self.create_object(pointer, context)
+    end
+
+    # Instantiates an conversion from a string. The string can be:
+    #
+    # * proj-string,
+    # * WKT string,
+    # * object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", "urn:ogc:def:coordinateOperation:EPSG::1671"),
+    # * Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match.
+    # * OGC URN combining references for compound coordinate reference systems (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated syntax "EPSG:2393+5717"),
+    # * OGC URN combining references for concatenated operations (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618")
+    # * PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (added in 6.2)
+    # * compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (added in 7.1)
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_create
+    #
+    # @param value [String]. See above
+    #
+    # @return [Conversion]
+    def initialize(value, context=nil)
+      context ||= Context.current
+      ptr = Api.proj_create(context, value)
+
+      if ptr.null?
+        Error.check_context(context)
+      end
+
+      if Api.method_defined?(:proj_is_crs) && Api.proj_is_crs(ptr)
+        raise(Error, "Invalid conversion. Proj created an instance of: #{self.proj_type}.")
+      end
+
+      super(ptr, context)
+    end
+
+    # Return an equivalent projection. Currently implemented:
+    # * EPSG_CODE_METHOD_MERCATOR_VARIANT_A (1SP) to EPSG_CODE_METHOD_MERCATOR_VARIANT_B (2SP)
+    # * EPSG_CODE_METHOD_MERCATOR_VARIANT_B (2SP) to EPSG_CODE_METHOD_MERCATOR_VARIANT_A (1SP)
+    # * EPSG_CODE_METHOD_LAMBERT_CONIC_CONFORMAL_1SP to EPSG_CODE_METHOD_LAMBERT_CONIC_CONFORMAL_2SP
+    # * EPSG_CODE_METHOD_LAMBERT_CONIC_CONFORMAL_2SP to EPSG_CODE_METHOD_LAMBERT_CONIC_CONFORMAL_1SP
+    #
+    # @param new_method_epsg_code [String] EPSG code of the target method. Or nil in which case new_method_name must be specified.
+    # @param new_method_name [String] EPSG or PROJ target method name. Or nil in which case new_method_epsg_code must be specified
+    #
+    # @return [Conversion]
+    def convert_to_other_method(new_method_epsg_code: nil, new_method_name: nil)
+      ptr = Api.proj_convert_conversion_to_other_method(self.context, self,
+                                                        new_method_epsg_code ? new_method_epsg_code: 0,
+                                                        new_method_name)
+
+      if ptr.null?
+        Error.check_context(context)
+      end
+
+      self.class.create_object(ptr, context)
+    end
+  end
+end