proj4rb 4.1.0 → 5.0.0

data/lib/proj/datum.rb

@@ -1,32 +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 [Float] 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
+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 [Float] 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

@@ -1,34 +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
+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/domain.rb

@@ -0,0 +1,82 @@
+  # encoding: UTF-8
+
+module Proj
+  # Represents a usage domain of a PjObject. Each domain has a scope
+  # describing the purpose and a geographic area of use.
+  # Objects can have multiple domains.
+  class Domain
+    # @return [String] The scope of this domain
+    attr_reader :scope
+
+    # @return [Area] The geographic area of use for this domain
+    attr_reader :area_of_use
+
+    # @param scope [String] The scope describing the purpose of this domain
+    # @param area_of_use [Area] The geographic area of use
+    def initialize(scope:, area_of_use:)
+      @scope = scope
+      @area_of_use = area_of_use
+    end
+
+    # Returns the number of usage domains for an object.
+    # Requires PROJ 9.2+. Returns 1 on older versions for backward compatibility.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_domain_count
+    #
+    # @param pj_object [PjObject] The object to query
+    #
+    # @return [Integer]
+    def self.count(pj_object)
+      if Api.method_defined?(:proj_get_domain_count)
+        Api.proj_get_domain_count(pj_object)
+      else
+        1
+      end
+    end
+
+    # Returns all usage domains for an object.
+    # On PROJ < 9.2, falls back to {Api.proj_get_scope} and {Api.proj_get_area_of_use}
+    # and returns a single domain.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_scope_ex
+    # @see https://proj.org/development/reference/functions.html#c.proj_get_area_of_use_ex
+    #
+    # @param pj_object [PjObject] The object to query
+    #
+    # @return [Array<Domain>]
+    def self.domains(pj_object)
+      use_ex = Api.method_defined?(:proj_get_domain_count)
+      domain_count = use_ex ? Api.proj_get_domain_count(pj_object) : 1
+
+      domain_count.times.map do |index|
+        scope = use_ex ? Api.proj_get_scope_ex(pj_object, index) : Api.proj_get_scope(pj_object)
+
+        p_name = FFI::MemoryPointer.new(:pointer)
+        p_west = FFI::MemoryPointer.new(:double)
+        p_south = FFI::MemoryPointer.new(:double)
+        p_east = FFI::MemoryPointer.new(:double)
+        p_north = FFI::MemoryPointer.new(:double)
+
+        if use_ex
+          result = Api.proj_get_area_of_use_ex(pj_object.context, pj_object, index,
+                                                p_west, p_south, p_east, p_north, p_name)
+        else
+          result = Api.proj_get_area_of_use(pj_object.context, pj_object,
+                                             p_west, p_south, p_east, p_north, p_name)
+        end
+        unless result
+          Error.check_object(pj_object)
+        end
+
+        name = p_name.read_pointer.read_string_to_null.force_encoding('utf-8')
+        area = Area.new(west_lon_degree: p_west.read_double,
+                        south_lat_degree: p_south.read_double,
+                        east_lon_degree: p_east.read_double,
+                        north_lat_degree: p_north.read_double,
+                        name: name)
+
+        new(scope: scope, area_of_use: area)
+      end
+    end
+  end
+end

data/lib/proj/ellipsoid.rb

@@ -1,78 +1,78 @@
-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 [Float]
-    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 [Float]
-    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 [Float]
-    def inverse_flattening
-      self.parameters[:inverse_flattening]
-    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::PjEllps, Api.proj_list_ellps)
+
+      result = Array.new
+      0.step do |i|
+        pj_ellps = Api::PjEllps.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 [Float]
+    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 [Float]
+    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 [Float]
+    def inverse_flattening
+      self.parameters[:inverse_flattening]
+    end
+  end
 end

data/lib/proj/error.rb

@@ -25,11 +25,16 @@ module Proj
     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
 
+    def self.validate_context!(context)
+      return if context.is_a?(Context)
+
+      raise(TypeError, "expected Proj::Context, got #{context.class}")
+    end
+
     # 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
@@ -61,11 +66,5 @@ module Proj
       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
+end

data/lib/proj/file_api_callbacks.rb

@@ -0,0 +1,165 @@
+module Proj
+  # Include this module in a class to create a custom file API for PROJ.
+  # Install it via {Context#set_file_api}.
+  #
+  # The including class must call {#install_callbacks} in its initializer and
+  # implement the following methods:
+  #
+  # * +open(path, access_mode)+ - Open a file. +access_mode+ is one of
+  #   +:PROJ_OPEN_ACCESS_READ_ONLY+, +:PROJ_OPEN_ACCESS_READ_UPDATE+, or
+  #   +:PROJ_OPEN_ACCESS_CREATE+. Return a file object (any Ruby object) or nil on error.
+  # * +read(file, size_bytes)+ - Read up to +size_bytes+ from +file+, return a String.
+  # * +write(file, data)+ - Write +data+ to +file+, return the number of bytes written.
+  # * +seek(file, offset, whence)+ - Seek within +file+ using SEEK_SET/SEEK_CUR/SEEK_END.
+  # * +tell(file)+ - Return the current position in +file+.
+  # * +close(file)+ - Close +file+.
+  # * +exists(path)+ - Return true if the file at +path+ exists.
+  # * +mkdir(path)+ - Create directory at +path+, return true on success.
+  # * +unlink(path)+ - Remove file at +path+, return true on success.
+  # * +rename(original_path, new_path)+ - Rename a file, return true on success.
+  #
+  # The +file+ parameter passed to read/write/seek/tell/close is whatever object
+  # your +open+ method returned.
+  #
+  # @example
+  #   class MyFileApi
+  #     include Proj::FileApiCallbacks
+  #
+  #     def initialize(context)
+  #       install_callbacks(context)
+  #     end
+  #
+  #     def open(path, access_mode)
+  #       # return a file object or nil
+  #     end
+  #     # ... implement remaining methods ...
+  #   end
+  #
+  #   context.set_file_api(MyFileApi)
+  module FileApiCallbacks
+    def install_callbacks(context)
+      # PROJ keeps using this structure after proj_context_set_fileapi returns,
+      # so it must be retained on the Ruby object to avoid GC invalidating it.
+      @proj_file_api = Api::ProjFileApi.new
+      @proj_file_api[:version] = 1
+
+      # Maps native address -> {proj_handle:, file:}. Retaining proj_handle
+      # prevents the MemoryPointer from being GCed while PROJ holds the address.
+      @file_api_handles = {}
+
+      @proj_file_api[:open_cbk] = self.method(:open_callback)
+      @proj_file_api[:read_cbk] = self.method(:read_callback)
+      @proj_file_api[:write_cbk] = self.method(:write_callback)
+      @proj_file_api[:seek_cbk] = self.method(:seek_callback)
+      @proj_file_api[:tell_cbk] = self.method(:tell_callback)
+      @proj_file_api[:close_cbk] = self.method(:close_callback)
+      @proj_file_api[:exists_cbk] = self.method(:exists_callback)
+      @proj_file_api[:mkdir_cbk] = self.method(:mkdir_callback)
+      @proj_file_api[:unlink_cbk] = self.method(:unlink_callback)
+      @proj_file_api[:rename_cbk] = self.method(:rename_callback)
+
+      result = Api.proj_context_set_fileapi(context, @proj_file_api, nil)
+
+      if result != 1
+        Error.check_object(self)
+      end
+    end
+
+    # Open file. Return NULL if error
+    def open_callback(context, path, access_mode, user_data)
+      file = self.open(path, access_mode)
+      return nil unless file
+      register_handle(file)
+    end
+
+    # Read sizeBytes into buffer from current position and return number of bytes read
+    def read_callback(context, handle, buffer, size_bytes, user_data)
+      file = handle_to_file(handle)
+      data = self.read(file, size_bytes)
+      return 0 if data.nil? || data.empty?
+
+      read_bytes = [size_bytes, data.bytesize].min
+      buffer.put_bytes(0, data, 0, read_bytes)
+      read_bytes
+    end
+
+    # Write sizeBytes into buffer from current position and return number of bytes written
+    def write_callback(context, handle, buffer, size_bytes, user_data)
+      file = handle_to_file(handle)
+      data = buffer.get_bytes(0, size_bytes)
+      self.write(file, data)
+    end
+
+    # Seek to offset using whence=SEEK_SET/SEEK_CUR/SEEK_END. Return TRUE in case of success
+    def seek_callback(context, handle, offset, whence, user_data)
+      file = handle_to_file(handle)
+      self.seek(file, offset, whence)
+      return 1 # True
+    end
+
+    # Return current file position
+    def tell_callback(context, handle, user_data)
+      file = handle_to_file(handle)
+      self.tell(file)
+    end
+
+    # Close file
+    def close_callback(context, handle, user_data)
+      file = handle_to_file(handle)
+      self.close(file)
+      unregister_handle(handle)
+    end
+
+    # Return TRUE if a file exists
+    def exists_callback(context, path, user_data)
+      if self.exists(path)
+        1
+      else
+        0
+      end
+    end
+
+    # Return TRUE if directory exists or could be created
+    def mkdir_callback(context, path, user_data)
+      if self.mkdir(path)
+        1
+      else
+        0
+      end
+    end
+
+    # Return TRUE if file could be removed
+    def unlink_callback(context, path, user_data)
+      if self.unlink(path)
+        1
+      else
+        0
+      end
+    end
+
+    # Return TRUE if file could be renamed
+    def rename_callback(context, original_path, new_path, user_data)
+      if self.rename(original_path, new_path)
+        1
+      else
+        0
+      end
+    end
+
+    # Create an opaque handle for PROJ and associate it with a file object.
+    # The MemoryPointer is retained to prevent GC while PROJ holds the address.
+    def register_handle(file)
+      proj_handle = FFI::MemoryPointer.new(:pointer)
+      @file_api_handles[proj_handle.address] = { proj_handle: proj_handle, file: file }
+      proj_handle
+    end
+
+    def handle_to_file(handle)
+      @file_api_handles[handle.address][:file]
+    end
+
+    def unregister_handle(handle)
+      @file_api_handles.delete(handle.address)
+    end
+  end
+end