proj4rb 4.1.0 → 5.0.0

data/lib/proj/bounds3d.rb

@@ -0,0 +1,45 @@
+# encoding: UTF-8
+
+module Proj
+  # Represents a 3D bounding box defined by minimum and maximum x/y/z values.
+  # Used with {CoordinateOperationMixin#transform_bounds_3d} to transform 3D
+  # regions between coordinate reference systems. Requires PROJ 9.6+.
+  class Bounds3d
+    # @!attribute [r] xmin
+    #   @return [Float] Minimum x value (e.g., west longitude)
+    # @!attribute [r] ymin
+    #   @return [Float] Minimum y value (e.g., south latitude)
+    # @!attribute [r] zmin
+    #   @return [Float] Minimum z value (e.g., lower elevation)
+    # @!attribute [r] xmax
+    #   @return [Float] Maximum x value (e.g., east longitude)
+    # @!attribute [r] ymax
+    #   @return [Float] Maximum y value (e.g., north latitude)
+    # @!attribute [r] zmax
+    #   @return [Float] Maximum z value (e.g., upper elevation)
+    # @!attribute [r] name
+    #   @return [String, nil] Optional name for this bounds
+    attr_reader :name, :xmin, :ymin, :zmin, :xmax, :ymax, :zmax
+
+    # Creates a new 3D bounding box.
+    #
+    # @param xmin [Float] Minimum x value
+    # @param ymin [Float] Minimum y value
+    # @param zmin [Float] Minimum z value
+    # @param xmax [Float] Maximum x value
+    # @param ymax [Float] Maximum y value
+    # @param zmax [Float] Maximum z value
+    # @param name [String, nil] Optional name
+    #
+    # @return [Bounds3d]
+    def initialize(xmin, ymin, zmin, xmax, ymax, zmax, name = nil)
+      @xmin = xmin
+      @ymin = ymin
+      @zmin = zmin
+      @xmax = xmax
+      @ymax = ymax
+      @zmax = zmax
+      @name = name
+    end
+  end
+end

data/lib/proj/context.rb

@@ -2,7 +2,7 @@ module Proj
   # Proj 4.8 introduced the concept of a thread context object to support multi-threaded programs. The bindings
   # automatically create one context per thread (its stored in local thread storage).
   class Context
-    attr_reader :database
+    attr_reader :database, :life_span
 
     # Returns the default Proj context. This context *must* only be used in the main thread
     # In general it is better to create new contexts
@@ -12,6 +12,7 @@ module Proj
       result = Context.allocate
       # The default Proj Context is represented by a null pointer
       result.instance_variable_set(:@pointer, FFI::Pointer::NULL)
+      result.instance_variable_set(:@life_span, LifeSpan.new)
       result
     end
 
@@ -24,15 +25,17 @@ module Proj
     end
 
     # @!visibility private
-    def self.finalize(pointer)
+    def self.finalize(pointer, life_span)
       proc do
+        life_span.ended!
         Api.proj_context_destroy(pointer)
       end
     end
 
     def initialize
       @pointer = Api.proj_context_create
-      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
+      @life_span = LifeSpan.new
+      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer, @life_span))
 
       @database = Database.new(self)
     end
@@ -43,9 +46,19 @@ module Proj
       super
 
       @pointer = Api.proj_context_clone(original)
+      @life_span = LifeSpan.new
       @database = Database.new(self)
 
-      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
+      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer, @life_span))
+    end
+
+    # Explicitly free the underlying PROJ context.
+    def destroy
+      @life_span.ended!
+      Api.proj_context_destroy(@pointer)
+      @pointer = FFI::Pointer::NULL
+      ObjectSpace.undefine_finalizer(self)
+      nil
     end
 
     def to_ptr
@@ -73,6 +86,8 @@ module Proj
     #
     # @return [nil]
     def set_log_function(pointer = nil, &proc)
+      @log_data_pointer = pointer
+      @log_function = proc
       Api.proj_log_func(self, pointer, proc)
     end
 
@@ -127,7 +142,7 @@ module Proj
     #
     # @return [nil]
     def ca_bundle_path=(path)
-      Api.proj_context_set_ca_bundle_path(self, path.encode(:utf8))
+      Api.proj_context_set_ca_bundle_path(self, path.encode('utf-8'))
     end
 
     # Returns the cache used to store grid files locally
@@ -182,7 +197,19 @@ module Proj
     #
     # @return [String] Directory
     def user_directory(create = false)
-      Api.proj_context_get_user_writable_directory(self, create ? 1 : 0)
+      path = Api.proj_context_get_user_writable_directory(self, create ? 1 : 0)
+      # Normalizes path names
+      File.expand_path(path)
+    end
+
+    # Sets the user directory used to save grid files.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_context_set_user_writable_directory
+    #
+    # @param path [String] Directory path
+    # @param create [Boolean] If true, create the directory if needed. Defaults to true.
+    def set_user_writable_directory(path, create: true)
+      Api.proj_context_set_user_writable_directory(self, path, create ? 1 : 0)
     end
 
     # Sets the paths that Proj will search when opening one of its resource files
@@ -207,9 +234,29 @@ module Proj
       end
     end
 
-    # Installs a new {FileApiImpl FileApi}
+    # Installs a custom file API that PROJ will use for all file operations.
+    #
+    # The class must include {FileApiCallbacks} and implement the following methods
+    # that receive a file handle as their first argument:
+    #
+    # * +open(path, access_mode)+ - Open a file. Return a file object or nil on error.
+    # * +read(file, size_bytes)+ - Read size_bytes from file, return data string.
+    # * +write(file, data)+ - Write data to file, return bytes written.
+    # * +seek(file, offset, whence)+ - Seek within file.
+    # * +tell(file)+ - Return current file position.
+    # * +close(file)+ - Close the file.
+    # * +exists(path)+ - Return true if file exists.
+    # * +mkdir(path)+ - Create directory, return true on success.
+    # * +unlink(path)+ - Remove file, return true on success.
+    # * +rename(original_path, new_path)+ - Rename file, return true on success.
     #
     # @see https://proj.org/development/reference/functions.html#c.proj_context_set_fileapi
+    # @see FileApiCallbacks
+    #
+    # @example
+    #   context.set_file_api(MyCustomFileApi)
+    #
+    # @param file_api_klass [Class] A class whose initializer accepts a single Context argument
     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")
@@ -220,7 +267,7 @@ module Proj
       @file_api = file_api_klass.new(self)
     end
 
-    # Installs a new {NetworkApiImpl NetworkApi}
+    # Installs a new {NetworkApiCallbacks NetworkApi}
     #
     # @see https://proj.org/development/reference/functions.html#c.proj_context_set_network_callbacks
     def set_network_api(network_api_klass)
@@ -228,23 +275,10 @@ module Proj
         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
+      # There is no API to "uninstall" a NetworkApi. 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
+end

data/lib/proj/conversion.rb

@@ -1,91 +1,94 @@
-# encoding: UTF-8
-require 'stringio'
-
-module Proj
-  # Conversions are {CoordinateOperationMixin 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
-    #
-    # @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
+# encoding: UTF-8
+require 'stringio'
+
+module Proj
+  # Conversions are {CoordinateOperationMixin 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
+    #
+    # @return [Conversion]
+    def self.create_conversion(context, name:, auth_name:, code:, method_name:, method_auth_name:, method_code:, params:)
+      Error.validate_context!(context)
+      params_ptr = FFI::MemoryPointer.new(Api::PjParamDescription, params.size)
+      params.each_with_index do |param, i|
+        param_description_target = Api::PjParamDescription.new(params_ptr[i])
+        param_description_source = param.to_description
+        param_description_target.to_ptr.__copy_from__(param_description_source.to_ptr, Api::PjParamDescription.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)
+        pj_type = Api.proj_get_type(ptr)
+        Api.proj_destroy(ptr)
+        raise(Error, "Invalid conversion. Proj created an instance of: #{pj_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