proj4rb 3.0.0 → 4.0.0

data/lib/proj/file_api.rb

@@ -0,0 +1,166 @@
+module Proj
+  module FileApiCallbacks
+    def install_callbacks(context)
+      proj_file_api = Api::PROJ_FILE_API.new
+      proj_file_api[:version] = 1
+
+      # Store procs to instance variables so they don't get garbage collected
+      @open_cbk = proj_file_api[:open_cbk] = self.method(:open_callback)
+      @read_cbk = proj_file_api[:read_cbk] = self.method(:read_callback)
+      @write_cbk = proj_file_api[:write_cbk] = self.method(:write_callback)
+      @seek_cbk = proj_file_api[:seek_cbk] = self.method(:seek_callback)
+      @tell_cbk = proj_file_api[:tell_cbk] = self.method(:tell_callback)
+      @close_cbk = proj_file_api[:close_cbk] = self.method(:close_callback)
+      @exists_cbk = proj_file_api[:exists_cbk] = self.method(:exists_callback)
+      @mkdir_cbk = proj_file_api[:mkdir_cbk] = self.method(:mkdir_callback)
+      @unlink_cbk = proj_file_api[:unlink_cbk] = self.method(:unlink_callback)
+      @rename_cbk = 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)
+      result = self.open(path, access_mode)
+      result ?  FFI::MemoryPointer.new(:size_t) : nil
+    end
+
+    # Read sizeBytes into buffer from current position and return number of bytes read
+    def read_callback(context, handle, buffer, size_bytes, user_data)
+      data = self.read(size_bytes)
+      read_bytes = [size_bytes, data.size].min
+      buffer.write_bytes(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)
+      data = buffer.get_bytes(0, size_bytes)
+      self.write(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)
+      self.seek(offset, whence)
+      return 1 # True
+    end
+
+    # Return current file position
+    def tell_callback(context, handle, user_data)
+      self.tell
+    end
+
+    # Close file
+    def close_callback(context, handle, user_data)
+      self.close
+    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.mdkir(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
+  end
+
+  # Proj allows its file api to be replaced by a custom implementation. This can be
+  # done by calling Context#set_file_api with a user defined Class that includes the
+  # FileApiCallbacks module and implements its required methods.
+  #
+  # The FileApiImpl class is a simple example file api implementation.
+  class FileApiImpl
+    include FileApiCallbacks
+
+    def initialize(context)
+      install_callbacks(context)
+    end
+
+    def open(path, access_mode)
+      case access_mode
+      when :PROJ_OPEN_ACCESS_READ_ONLY
+        if File.exist?(path)
+          @file = File.open(path, :mode => 'rb')
+        else
+          nil # False
+        end
+      when :PROJ_OPEN_ACCESS_READ_UPDATE
+        if File.exist?(path)
+          @file = File.open(path, :mode => 'r+b')
+        else
+          nil # False
+        end
+      when :PROJ_OPEN_ACCESS_CREATE
+        @file = File.open(path, :mode => 'wb')
+      end
+    end
+
+    def read(size_bytes)
+      @file.read(size_bytes)
+    end
+
+    def write(data)
+      @file.write(data)
+    end
+
+    def seek(offset, whence)
+      @file.seek(offset, whence)
+    end
+
+    def tell
+      @file.tell
+    end
+
+    def close
+      @file.close
+    end
+
+    def exists(path)
+      File.exist?(path)
+    end
+
+    def mkdir(path)
+      Dir.mkdir(path)
+    end
+
+    def unlink(path)
+      File.unlink(path) if File.exist?(path)
+    end
+
+    def rename(original_path, new_path)
+      File.rename(original_path, new_path)
+    end
+  end
+end

data/lib/proj/grid.rb

@@ -0,0 +1,121 @@
+module Proj
+  # Grids define models that are used to perform dimension shifts.
+  #
+  # Grid files can be quite large and may not be included with Proj depending on how
+  # it was packaged and any grid licensing requirements. Therefore, Proj has the ability
+  # to download grids on the fly if {Context#network_enabled? networking} is enabled.
+  #
+  # @see https://proj.org/community/rfc/rfc-4.html#rfc4
+  class Grid
+    # @!attribute [r] context
+    #   @return [Context] The grid context
+    # @!attribute [r] name
+    #   @return [String] The grid's name
+    # @!attribute [r] full_name
+    #   @return [String] The grid's full name
+    # @!attribute [r] package_name
+    #   @return [String] The grid's package name
+    # @!attribute [r] url
+    #   @return [URI] A url that can be used to download the grid
+    attr_reader :context, :name, :full_name, :package_name, :url
+
+    def initialize(name, context = Context.default, full_name: nil, package_name: nil, url: nil,
+                   downloadable: false, open_license: false, available: false)
+      @name = name
+      @context = context
+      @full_name = full_name
+      @package_name = package_name
+      @url = url
+      @downloadable = downloadable
+      @open_license = open_license
+      @available = available
+    end
+
+    # Returns whether the grid can be downloaded
+    #
+    # @return [Boolean]
+    def downloadable?
+      @downloadable
+    end
+
+    # Returns whether the grid is released with an open license
+    #
+    # @return [Boolean]
+    def open_license?
+      @open_license
+    end
+
+    # Returns whether the grid is available at runtime
+    #
+    # @return [Boolean]
+    def available?
+      @available
+    end
+
+    # Returns information about this grid
+    #
+    # See https://proj.org/development/reference/functions.html#c.proj_grid_info proj_grid_info
+    #
+    # @return [GridInfo]
+    def info
+      ptr = Api.proj_grid_info(self.name)
+      GridInfo.new(ptr)
+    end
+
+    # Returns if a grid is available in the PROJ user-writable directory.
+    # This method will only return true if Context#network_enabled? is true
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_is_download_needed
+    #
+    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
+    #
+    # @return [Boolean]
+    def downloaded?(ignore_ttl = false)
+      if self.context.network_enabled?
+        result = Api.proj_is_download_needed(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0)
+        result == 1 ? false : true
+      else
+        false
+      end
+    end
+
+    # Download a file in the PROJ user-writable directory if has not already been downlaoded.
+    # This function can only be used if networking is enabled
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_download_file
+    #
+    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
+    # @yieldparam percent [Double] The progress downloading the file in the range of 0 to 1
+    #
+    # @return [Boolean] True if the download was successful or unneeded. Otherwise false
+    def download(ignore_ttl = false)
+      callback = if block_given?
+                   Proc.new do |context, percent, user_data|
+                     result = yield percent
+                     # Return 1 to tell Proj to keep downloading the file
+                     result ? 1 : 0
+                   end
+                 end
+
+      result = Api.proj_download_file(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0, callback, nil)
+      result == 1 ? true : false
+    end
+
+    # Deletes the grid if it has been downloaded
+    def delete
+      if self.downloaded?
+        path = File.join(self.context.user_directory, self.name)
+        File.delete(path) if File.exist?(path)
+      end
+    end
+
+    # Returns the path to the grid if it has been downloaded
+    #
+    # @return [String]
+    def path
+      if self.downloaded?
+        File.join(self.context.user_directory, self.name)
+      end
+    end
+  end
+end

data/lib/proj/grid_cache.rb

@@ -0,0 +1,64 @@
+module Proj
+  # To avoid repeated network access, it is possible to enable a local cache of grids.
+  # Grid data is stored in a SQLite3 database, cache.db, that is by default stored
+  # stored in the PROJ user writable directory.
+  #
+  # The local cache is enabled by default with a size of 300MB. Cache settings can be overridden
+  # by this class, env variables or the proj.ini file
+  #
+  # @see https://proj.org/usage/network.html#caching
+  class GridCache
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    # Enables or disables the grid cache
+    #
+    # @param value [Boolean]
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_enable
+    def enabled=(value)
+      Api.proj_grid_cache_set_enable(self.context, value ? 1 : 0)
+    end
+
+    # Set the path and file of the local cache file which is sqlite database. By default
+    # it is stored in the user writable directory.
+    #
+    # @param value [String] - Full path to the cache. If set to nil then caching will be disabled.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_filename
+    def path=(value)
+      Api.proj_grid_cache_set_filename(self.context, value.encode('UTF-8'))
+      value
+    end
+
+    # Sets the cache size
+    #
+    # @param value [Integer] Maximum size in Megabytes (1024*1024 bytes), or negative value to set unlimited size.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_max_size
+    def max_size=(value)
+      Api.proj_grid_cache_set_max_size(self.context, value)
+      value
+    end
+
+    # Specifies the time-to-live delay for re-checking if the cached properties of files are still up-to-date.
+    #
+    # @param value [Integer] Delay in seconds. Use negative value for no expiration.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_ttl
+    def ttl=(value)
+      Api.proj_grid_cache_set_ttl(self.context, value)
+      value
+    end
+
+    # Clears the cache
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_clear
+    def clear
+      Api.proj_grid_cache_clear(self.context)
+    end
+  end
+end

data/lib/proj/grid_info.rb

@@ -0,0 +1,19 @@
+module Proj
+  class GridInfo
+    attr_reader :gridname, :filename, :format,
+                :lower_left, :upper_right,
+                :size_lon, :size_lat, :cell_size_lon, :cell_size_lat
+
+    def initialize(pj_grid_info)
+      @filename = pj_grid_info[:filename].to_ptr.read_string
+      @gridname = pj_grid_info[:gridname].to_ptr.read_string
+      @format = pj_grid_info[:format].to_ptr.read_string
+      @lower_left = pj_grid_info[:lowerleft]
+      @upper_right = pj_grid_info[:upperright]
+      @size_lon = pj_grid_info[:n_lon]
+      @size_lat = pj_grid_info[:n_lat]
+      @cell_size_lon = pj_grid_info[:cs_lon]
+      @cell_size_lat = pj_grid_info[:cs_lat]
+    end
+  end
+end

data/lib/proj/network_api.rb

@@ -0,0 +1,92 @@
+require 'net/http'
+
+module Proj
+  module NetworkApiCallbacks
+    def install_callbacks(context)
+      @open_cbk = self.method(:open_callback)
+      @close_cbk = self.method(:close_callback)
+      @header_value_cbk = self.method(:header_value_callback)
+      @read_range_cbk = self.method(:read_range_callback)
+
+      result = Api.proj_context_set_network_callbacks(context, @open_cbk, @close_cbk, @header_value_cbk, @read_range_cbk, nil)
+
+      if result != 1
+        Error.check_object(self)
+      end
+    end
+
+    def open_callback(context, url, offset, size_to_read, buffer, out_size_read, error_string_max_size, out_error_string, user_data)
+      uri = URI.parse(url)
+      data = self.open(uri, offset, size_to_read)
+      out_size = [size_to_read, data.size].min
+      out_size_read.write(:size_t, out_size)
+      buffer.write_bytes(data, 0, out_size)
+
+      # Return fake handle
+      FFI::MemoryPointer.new(:size_t)
+    end
+
+    def close_callback(context, handle, user_data)
+      self.close
+    end
+
+    def header_value_callback(context, handle, header_name_ptr, user_data)
+      header_name = header_name_ptr.read_string_to_null
+      value = self.header_value(header_name)
+      FFI::MemoryPointer.from_string(value)
+    end
+
+    def read_range_callback(context, handle, offset, size_to_read, buffer, error_string_max_size, out_error_string, user_data)
+      data = self.read_range(offset, size_to_read)
+      out_size = [size_to_read, data.size].min
+      buffer.write_bytes(data, 0, out_size)
+      out_size
+    end
+  end
+
+  # Proj allows its network api to be replaced by a custom implementation. This can be
+  # done by calling Context#set_network_api with a user defined Class that includes the
+  # NetworkApiCallbacks module and implements its required methods.
+  #
+  # @see https://proj.org/usage/network.html
+  #
+  # The NetworkApiImpl class is a simple example of a network api implementation.
+  class NetworkApiImpl
+    include NetworkApiCallbacks
+
+    def initialize(context)
+      install_callbacks(context)
+    end
+
+    def open(uri, offset, size_to_read)
+      @uri = uri
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      if uri.scheme == "https"
+        @http.use_ssl = true
+        @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+      @http.start
+
+      read_data(offset, size_to_read)
+    end
+
+    def close
+      @http.finish
+    end
+
+    def header_value(name)
+      @response[name]
+    end
+
+    def read_range(offset, size_to_read)
+      read_data(offset, size_to_read)
+    end
+
+    def read_data(offset, size_to_read)
+      headers = {"Range": "bytes=#{offset}-#{offset + size_to_read - 1}"}
+      request = Net::HTTP::Get.new(@uri.request_uri, headers)
+      @response = @http.request(request)
+      @response.body.force_encoding("ASCII-8BIT")
+    end
+  end
+end

data/lib/proj/operation.rb

@@ -1,43 +1,43 @@
-module Proj
-  class Operation
-    attr_reader :id, :description
-
-    def self.list
-      pointer_to_array = FFI::Pointer.new(Api::PJ_OPERATIONS, Api.proj_list_operations)
-      result = Array.new
-      0.step do |i|
-        operation_info = Api::PJ_OPERATIONS.new(pointer_to_array[i])
-        break result if operation_info[:id].nil?
-        id = operation_info[:id]
-        description = operation_info[:descr].read_pointer.read_string.force_encoding('UTF-8')
-        result << self.new(id, description)
-      end
-      result
-    end
-
-    def self.get(id)
-      self.list.find {|operation| operation.id == id}
-    end
-
-    def initialize(id, description)
-      @id = id
-      @description = description
-    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 Operation
+    attr_reader :id, :description
+
+    def self.list
+      pointer_to_array = FFI::Pointer.new(Api::PJ_OPERATIONS, Api.proj_list_operations)
+      result = Array.new
+      0.step do |i|
+        operation_info = Api::PJ_OPERATIONS.new(pointer_to_array[i])
+        break result if operation_info[:id].nil?
+        id = operation_info[:id]
+        description = operation_info[:descr].read_pointer.read_string.force_encoding('UTF-8')
+        result << self.new(id, description)
+      end
+      result
+    end
+
+    def self.get(id)
+      self.list.find {|operation| operation.id == id}
+    end
+
+    def initialize(id, description)
+      @id = id
+      @description = description
+    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
 end

data/lib/proj/operation_factory_context.rb

@@ -0,0 +1,136 @@
+module Proj
+  # A context for building coordinate operations between two CRS.
+  class OperationFactoryContext
+    attr_reader :context
+
+    def self.finalize(pointer)
+      proc do
+        Api.proj_operation_factory_context_destroy(pointer)
+      end
+    end
+
+    # Create a new OperationFactoryContext
+    #
+    # @param context   - The context to use or the current context if nil
+    # @param authority - If authority is nil or the empty string, then coordinate operations
+    #                    from any authority will be searched, with the restrictions set
+    #                    in the authority_to_authority_preference database table.
+    #                    If authority is set to "any", then coordinate operations from any
+    #                    authority will be searched
+    #                    If authority is a non-empty string different of "any", then coordinate
+    #                    operations will be searched only in that authority namespace.
+    def initialize(context, authority: nil)
+      @pointer = Api.proj_create_operation_factory_context(context, authority)
+      ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
+    end
+
+    # Find a list of CoordinateOperation from source_crs to target_crs
+    #
+    # @param source [Crs] Source CRS. Must not be nil.
+    # @param target [Crs] Target CRS. Must not be nil.
+    #
+    # @return [Array] - Returns a list of operations
+    def create_operations(source, target)
+      ptr = Api.proj_create_operations(self.context, source, target, self)
+      PjObjects.new(ptr, self.context)
+    end
+
+    # Specifies whether ballpark transformations are allowed.
+    #
+    # @param value - Set to True allow ballpark transformations otherwise False
+    def ballpark_transformations=(value)
+      Api.proj_operation_factory_context_set_allow_ballpark_transformations(self.context, self, value ? 1 : 0)
+    end
+
+    # Set the desired accuracy of the resulting coordinate transformations.
+    #
+    # @param value [double] - Accuracy in meters. Set to 0 to disable the filter.
+    def desired_accuracy=(value)
+      Api.proj_operation_factory_context_set_desired_accuracy(self.context, self, value)
+    end
+
+    # Set the desired area of interest for the resulting coordinate transformations. For an
+    # area of interest crossing the anti-meridian, west_lon_degree will be greater than east_lon_degree.
+    #
+    # @param west  West longitude (in degrees).
+    # @param south South latitude (in degrees).
+    # @param east East longitude (in degrees).
+    # @param north North latitude (in degrees).
+    def set_area_of_interest(west, south, east, north)
+      Api.proj_operation_factory_context_set_area_of_interest(self.context, self, west, south, east, north)
+    end
+
+    # Set the name of the desired area of interest for the resulting coordinate transformations.
+    #
+    # @param value - Name of the area. Must be known of the database.
+    def area_of_interest_name=(value)
+      Api.proj_operation_factory_context_set_area_of_interest_name(self.context, self, value)
+    end
+
+    # Set how source and target CRS extent should be used when considering if a transformation
+    # can be used (only takes effect if no area of interest is explicitly defined).
+    #
+    # @param value [PROJ_CRS_EXTENT_USE] How source and target CRS extent should be used.
+    def crs_extent_use=(value)
+      Api.proj_operation_factory_context_set_crs_extent_use(self.context, self, value)
+    end
+
+    # Set the spatial criterion to use when comparing the area of validity of coordinate operations
+    # with the area of interest / area of validity of source and target CRS.
+    #
+    #  @param value [PROJ_SPATIAL_CRITERION] spatial criterion to use
+    def spatial_criterion=(value)
+      Api.proj_operation_factory_context_set_spatial_criterion(self.context, self, value)
+    end
+
+    # Set how grid availability is used.
+    #
+    #  @param [PROJ_GRID_AVAILABILITY_USE] - Use how grid availability is used.
+    def grid_availability=(value)
+      Api.proj_operation_factory_context_set_grid_availability_use(self.context, self, value)
+    end
+
+    # Set whether PROJ alternative grid names should be substituted to the official authority names.
+    #
+    # @param value [boolean] - Whether PROJ alternative grid names should be used
+    def use_proj_alternative_grid_names=(value)
+      Api.proj_operation_factory_context_set_use_proj_alternative_grid_names(self.context, self, value ? 1 : 0)
+    end
+
+    # Set whether an intermediate pivot CRS can be used for researching coordinate operations
+    # between a source and target CRS.
+    #
+    # @param value [PROJ_INTERMEDIATE_CRS_USE] - Whether and how intermediate CRS may be used
+    def allow_use_intermediate_crs=(value)
+      Api.proj_operation_factory_context_set_allow_use_intermediate_crs(self.context, self, value)
+    end
+
+    # Restrict the potential pivot CRSs that can be used when trying to build a coordinate operation
+    # between two CRS that have no direct operation.
+    #
+    # @param values [Array] - Array of string with the format ["auth_name1", "code1", "auth_name2", "code2"]
+    def allowed_intermediate_crs=(values)
+      # Convert strings to C chars
+      values_ptr = values.map do |value|
+        FFI::MemoryPointer.from_string(value)
+      end
+
+      # Add extra item at end for null pointer
+      pointer = FFI::MemoryPointer.new(:pointer, values.size + 1)
+      pointer.write_array_of_pointer(values_ptr)
+
+      Api.proj_operation_factory_context_set_allowed_intermediate_crs(self.context, self, pointer)
+    end
+
+    # Set whether transformations that are superseded (but not deprecated) should be discarded.
+    #
+    # @param value [bool] - Whether to discard superseded crses
+    def discard_superseded=(value)
+      Api.proj_operation_factory_context_set_discard_superseded(self.context, self, value ? 1 : 0)
+    end
+
+    def to_ptr
+      @pointer
+    end
+  end
+end