ffi-gdal 0.0.4 → 1.0.0.beta1

data/lib/gdal/driver.rb

@@ -0,0 +1,244 @@
+require_relative '../ffi/gdal'
+require_relative 'major_object'
+require_relative 'driver_extensions'
+require 'multi_xml'
+require 'log_switch'
+
+
+module GDAL
+  class Driver
+    include MajorObject
+    include GDAL::Logger
+    include DriverExtensions
+
+    GDAL_DOCS_URL = 'http://gdal.org'
+
+    # @return [Fixnum]
+    def self.count
+      FFI::GDAL.GDALGetDriverCount
+    end
+
+    # @param name [String] Short name of the registered GDALDriver.
+    # @return [GDAL::Driver]
+    def self.by_name(name)
+      driver_ptr = FFI::GDAL.GDALGetDriverByName(name)
+      return nil if driver_ptr.null?
+
+      new(driver_ptr)
+    end
+
+    # @return [Array<String>]
+    def self.short_names
+      return @short_names if @short_names
+
+      names = 0.upto(count - 1).map do |i|
+        driver = at_index(i)
+        driver.short_name
+      end
+
+      @short_names = names.compact.sort
+    end
+
+    # @return [Array<String>]
+    def self.long_names
+      return @long_names if @long_names
+
+      names = 0.upto(count - 1).map do |i|
+        at_index(i).long_name
+      end
+
+      @long_names = names.compact.sort
+    end
+
+    # @return [Hash{String => String}] Keys are driver short names, values are
+    #   driver long names.
+    def self.names
+      return @names if @names
+
+      names = 0.upto(count - 1).each_with_object({}) do |i, obj|
+        driver = at_index(i)
+        obj[driver.short_name] = driver.long_name
+      end
+
+      @names = Hash[names.sort]
+    end
+
+    # @param index [Fixnum] Index of the registered driver.  Must be less than
+    #   GDAL::Driver.count.
+    # @return [GDAL::Driver]
+    def self.at_index(index)
+      if index > count
+        raise "index must be between 0 and #{count - 1}."
+      end
+
+      driver_ptr = FFI::GDAL.GDALGetDriver(index)
+
+      new(driver_ptr)
+    end
+
+    # @param file_path [String] File to get the driver for.
+    # @return [GDAL::Driver]
+    def self.identify_driver(file_path)
+      driver_ptr = FFI::GDAL.GDALIdentifyDriver(::File.expand_path(file_path), nil)
+
+      new(driver_ptr)
+    end
+
+    # @param driver [GDAL::Driver, FFI::Pointer]
+    def initialize(driver)
+      @driver_pointer = GDAL._pointer(GDAL::Driver, driver)
+    end
+
+    def c_pointer
+      @driver_pointer
+    end
+
+    # @return [String]
+    def short_name
+      FFI::GDAL.GDALGetDriverShortName(@driver_pointer)
+    end
+
+    # @return [String]
+    def long_name
+      FFI::GDAL.GDALGetDriverLongName(@driver_pointer)
+    end
+
+    # @return [String]
+    def help_topic
+      "#{GDAL_DOCS_URL}/#{FFI::GDAL.GDALGetDriverHelpTopic(@driver_pointer)}"
+    end
+
+    # Lists and describes the options that can be used when calling
+    # GDAL::Dataset.create or GDAL::Dataset.create_copy.
+    #
+    # @return [Array]
+    def creation_option_list
+      return [] unless @driver_pointer
+
+      creation_option_list_xml = FFI::GDAL.GDALGetDriverCreationOptionList(@driver_pointer)
+      root = MultiXml.parse(creation_option_list_xml)
+      return [] if root.nil? || root.empty?
+
+      list = root['CreationOptionList']
+      return [] if list.nil? || list.empty?
+
+      list['Option']
+    end
+
+    # @param options [Hash]
+    # @return [Boolean]
+    def validate_creation_options(options)
+      options_pointer = if options.is_a? GDAL::Options
+        options.c_pointer
+      else
+        GDAL::Options.pointer(options)
+      end
+
+      FFI::GDAL.GDALValidateCreationOptions(@driver_pointer, options_pointer).to_bool
+    end
+
+    # Copy all of the associated files of a dataset from one file to another.
+    #
+    # @param new_name [String]
+    # @param old_name [String]
+    # @return true on success, false on warning.
+    # @raise [GDAL::CPLErrFailure] If failures.
+    def copy_dataset_files(new_name, old_name)
+      cpl_err = FFI::GDAL.GDALCopyDatasetFiles(@driver_pointer, new_name, old_name)
+
+      cpl_err.to_bool
+    end
+
+    # Create a new Dataset with this driver.  Legal arguments depend on the
+    # driver and can't be retrieved programmatically.  NOTE: In order to write
+    # out all data to the destination, you must call #close on the dataset!
+    #
+    # @param filename [String]
+    # @param x_size [Fixnum] Width of created raster in pixels.
+    # @param y_size [Fixnum] Height of created raster in pixels.
+    # @param bands [Fixnum]
+    # @param data_type [FFI::GDAL::GDALDataType]
+    # @return [GDAL::Dataset] Returns the *closed* dataset.  You'll need to
+    #   reopen it if you with to continue working with it.
+    # @todo Implement options.
+    def create_dataset(filename, x_size, y_size, bands: 1, data_type: :GDT_Byte, **options)
+      options_pointer = GDAL::Options.pointer(options)
+
+      dataset_pointer = FFI::GDAL.GDALCreate(@driver_pointer,
+        filename,
+        x_size,
+        y_size,
+        bands,
+        data_type,
+        options_pointer
+      )
+
+      raise CreateFail if dataset_pointer.null?
+
+      dataset = Dataset.new(dataset_pointer)
+      yield(dataset) if block_given?
+
+      dataset
+    end
+
+    # @param filename [String] The name for the new dataset file.
+    # @param source_dataset [GDAL::Dataset, FFI::Pointer] The dataset to copy.
+    # @param strict [Boolean] +false+ indicates the copy may adapt as needed for
+    #   the output format.
+    # @param options [Hash]
+    # @param progress [Proc] For outputting copy progress.  Conforms to the
+    #   FFI::GDAL::GDALProgressFunc signature.
+    def copy_dataset(filename, source_dataset, strict: true, **options, &progress)
+      options_ptr = GDAL::Options.pointer(options)
+
+      source_dataset_ptr = if source_dataset.is_a? GDAL::Dataset
+        source_dataset.c_pointer
+      elsif source_dataset.is_a? String
+        GDAL::Dataset.open(source_dataset, 'r').c_pointer
+      else
+        source_dataset
+      end
+
+      raise "Source dataset couldn't be read" if source_dataset_ptr.null?
+
+      destination_dataset_ptr = FFI::GDAL.GDALCreateCopy(@driver_pointer,
+        filename,
+        source_dataset_ptr,
+        strict,
+        options_ptr,
+        progress,
+        nil
+      )
+
+      raise CreateFail if destination_dataset_ptr.null?
+
+      dataset = Dataset.new(destination_dataset_ptr)
+      yield(dataset) if block_given?
+      dataset.close
+
+      dataset
+    end
+
+    # Delete the dataset represented by +file_name+.  Depending on the driver,
+    # this could mean deleting associated files, database objects, etc.
+    #
+    # @param file_name [String]
+    # @return true on success, false on warning.
+    # @raise [GDAL::CPLErrFailure] If failures.
+    def delete_dataset(file_name)
+      cpl_err = FFI::GDAL.GDALDeleteDataset(@driver_pointer, file_name)
+
+      cpl_err.to_bool
+    end
+
+    # @param new_name [String]
+    # @param old_name [String]
+    # @return true on success, false on warning.
+    # @raise [GDAL::CPLErrFailure] If failures.
+    def rename_dataset(new_name, old_name)
+      cpl_err = FFI::GDAL.GDALRenameDataset(@driver_pointer, new_name, old_name)
+
+      cpl_err.to_bool
+    end
+  end
+end

data/lib/gdal/driver_extensions.rb

@@ -0,0 +1,56 @@
+module GDAL
+  module DriverExtensions
+    
+    # The things that this driver can do, as reported by its metadata.
+    # Possibilities include:
+    #   * :open
+    #   * :create
+    #   * :copy
+    #   * :virtual_io
+    #   * :rasters
+    #   * :vectors
+    #
+    # @return [Array<Symbol>]
+    def capabilities
+      caps = []
+      caps << :open if can_open_datasets?
+      caps << :create if can_create_datasets?
+      caps << :copy if can_copy_datasets?
+      caps << :virtual_io if can_do_virtual_io?
+      caps << :rasters if can_do_rasters?
+      caps << :vectors if can_do_vectors?
+
+      caps
+    end
+
+    # @return [Boolean]
+    def can_open_datasets?
+      metadata_item('DCAP_OPEN') == 'YES'
+    end
+
+    # @return [Boolean]
+    def can_create_datasets?
+      metadata_item('DCAP_CREATE') == 'YES'
+    end
+
+    # @return [Boolean]
+    def can_copy_datasets?
+      metadata_item('DCAP_CREATECOPY') == 'YES'
+    end
+
+    # @return [Boolean]
+    def can_do_virtual_io?
+      metadata_item('DCAP_VIRTUALIO') == 'YES'
+    end
+
+    # @return [Boolean]
+    def can_do_rasters?
+      metadata_item('DCAP_RASTER') == 'YES'
+    end
+
+    # @return [Boolean]
+    def can_do_vectors?
+      metadata_item('DCAP_VECTOR') == 'YES'
+    end
+  end
+end

data/lib/gdal/environment_methods.rb

@@ -0,0 +1,43 @@
+module GDAL
+  module EnvironmentMethods
+    # @return [Fixnum] The maximum cache memory.
+    def cache_max
+      FFI::GDAL.GDALGetCacheMax
+    end
+
+    # @param bytes [Fixnum]
+    def cache_max=(bytes)
+      FFI::GDAL.GDALSetCacheMax(bytes)
+    end
+
+    # @return [Fixnum] The maximum cache memory.
+    def cache_max64
+      FFI::GDAL.GDALGetCacheMax64
+    end
+
+    # @param bytes [Fixnum]
+    def cache_max64=(bytes)
+      FFI::GDAL.GDALSetCacheMax64(bytes)
+    end
+
+    # @return [Fixnum] The amount of used cache memory.
+    def cache_used
+      FFI::GDAL.GDALGetCacheUsed
+    end
+
+    # @return [Fixnum] The amount of used cache memory.
+    def cache_used64
+      FFI::GDAL.GDALGetCacheUsed64
+    end
+
+    # @return [Boolean]
+    def flush_cache_block
+      FFI::GDAL.GDALFlushCacheBlock
+    end
+
+    # @param file_name [String]
+    def dump_open_datasets(file_name)
+      FFI::GDAL.GDALDumpOpenDatasets(file_name)
+    end
+  end
+end

data/lib/{ffi-gdal → gdal}/exceptions.rb

@@ -1,7 +1,7 @@
 module GDAL
   class OpenFailure < StandardError
     def initialize(file, msg=nil)
-      message = msg || "Unabled to open file '#{file}'. Perhaps an unsupported file format?"
+      message = msg || "Unable to open file '#{file}'. Perhaps an unsupported file format?"
       super(message)
     end
   end
@@ -14,4 +14,7 @@ module GDAL
 
   class RequiredBandNotFound < StandardError
   end
+
+  class InvalidBandNumber < StandardError
+  end
 end

data/lib/gdal/geo_transform.rb

@@ -0,0 +1,188 @@
+require_relative '../ffi/gdal'
+require_relative 'geo_transform_extensions'
+
+module GDAL
+  class GeoTransform
+    include GeoTransformExtensions
+
+    def self.new_pointer
+      FFI::MemoryPointer.new(:double, 6)
+    end
+
+    # @param filename [String]
+    # @return [GDAL::GeoTransform]
+    def self.from_world_file(filename, extension=nil)
+      gt_ptr = new_pointer
+
+      result = if extension
+        FFI::GDAL.GDALReadWorldFile(filename, extension, gt_ptr)
+      else
+        FFI::GDAL.GDALLoadWorldFile(filename, gt_ptr)
+      end
+
+      return nil unless result
+
+      new(gt_ptr)
+    end
+
+    # @param geo_transform [FFI::Pointer]
+    def initialize(geo_transform=nil)
+      @geo_transform_pointer = if geo_transform.is_a? GDAL::GeoTransform
+        geo_transform.c_pointer
+      elsif geo_transform
+        geo_transform
+      else
+        self.class.new_pointer
+      end
+
+      to_a
+    end
+
+    def c_pointer
+      @geo_transform_pointer
+    end
+
+    def null?
+      @geo_transform_pointer.null?
+    end
+
+    # X-coordinate of the center of the upper left pixel.
+    # In wikipedia's World Map definition, this is "C".
+    #
+    # @return [Float]
+    def x_origin
+      return nil if null?
+
+      @geo_transform_pointer[0].read_double
+    end
+
+    # @param new_x_origin [Float]
+    def x_origin=(new_x_origin)
+      @geo_transform_pointer[0].write_double(new_x_origin)
+    end
+
+    # AKA X-pixel size.
+    # In wikipedia's World Map definition, this is "A".
+    #
+    # @return [Float]
+    def pixel_width
+      return nil if null?
+
+      @geo_transform_pointer[1].read_double
+    end
+
+    # @param new_pixel_width [Float]
+    def pixel_width=(new_pixel_width)
+      @geo_transform_pointer[1].write_double(new_pixel_width)
+    end
+
+    # Rotation about the x-axis.
+    # In wikipedia's World File definition, this is "B".
+    #
+    # @return [Float]
+    def x_rotation
+      return nil if null?
+
+      @geo_transform_pointer[2].read_double
+    end
+
+    # @param new_x_rotation [Float]
+    def x_rotation=(new_x_rotation)
+      @geo_transform_pointer[2].write_double(new_x_rotation)
+    end
+
+    # Y-coordinate of the center of the upper left pixel.
+    # In wikipedia's World Map definition, this is "F".
+    #
+    # @return [Float]
+    def y_origin
+      return nil if null?
+
+      @geo_transform_pointer[3].read_double
+    end
+
+    # @param new_y_origin [Float]
+    def y_origin=(new_y_origin)
+      @geo_transform_pointer[3].write_double(new_y_origin)
+    end
+
+    # Rotation about the y-axis.
+    # In wikipedia's World Map definition, this is "D".
+    #
+    # @return [Float]
+    def y_rotation
+      return nil if null?
+
+      @geo_transform_pointer[4].read_double
+    end
+
+    # @param new_y_rotation [Float]
+    def y_rotation=(new_y_rotation)
+      @geo_transform_pointer[4].write_double(new_y_rotation)
+    end
+
+    # AKA Y-pixel size.
+    # In wikipedia's World Map definition, this is "E".
+    #
+    # @return [Float]
+    def pixel_height
+      return nil if null?
+
+      @geo_transform_pointer[5].read_double
+    end
+
+    # @param new_pixel_height [Float]
+    def pixel_height=(new_pixel_height)
+      @geo_transform_pointer[5].write_double(new_pixel_height)
+    end
+
+    # Converts a (pixel, line) coordinate to a georeferenced (geo_x, geo_y)
+    # location.
+    #
+    # @param pixel [Float] Input pixel position.
+    # @param line [Float] Input line position.
+    # @return [Hash{x_location: Float, y_location: Float}] longitude, latitude.
+    def apply_geo_transform(pixel, line)
+      geo_x_ptr = FFI::MemoryPointer.new(:double)
+      geo_y_ptr = FFI::MemoryPointer.new(:double)
+      FFI::GDAL.GDALApplyGeoTransform(@geo_transform_pointer, pixel, line, geo_x_ptr, geo_y_ptr)
+
+      { longitude: geo_x_ptr.read_double, latitude: geo_y_ptr.read_double }
+    end
+
+    # Composes this and the give geo_transform.  The result is equivalent to
+    # applying both geotransforms to a point.
+    #
+    # @param other_geo_transform [GDAL::GeoTransform, FFI::Pointer]
+    # @return [GDAL::GeoTransform]
+    def compose(other_geo_transform)
+      other_ptr = GDAL._pointer(GDAL::GeoTransform, other_geo_transform)
+
+      new_gt_ptr = self.class.new_pointer
+      FFI::GDAL.GDALComposeGeoTransforms(@geo_transform_pointer, other_ptr, new_gt_ptr)
+      return nil if new_gt_ptr.null?
+
+      GDAL::GeoTransform.new(new_gt_ptr)
+    end
+
+    # Inverts the current 3x2 set of coefficients and returns a new GeoTransform.
+    # Useful for converting from the geotransform equation from pixel to geo to
+    # being geo to pixel.
+    #
+    # @return [GDAL::GeoTransform]
+    def invert
+      new_geo_transform_ptr = self.class.new_pointer
+      success = FFI::GDAL.GDALInvGeoTransform(@geo_transform_pointer, new_geo_transform_ptr)
+      return nil unless success
+
+      self.class.new(new_geo_transform_ptr)
+    end
+
+    # @param raster_filename [String] The target raster file.
+    # @param world_extension [String]
+    # @return [Boolean]
+    def to_world_file(raster_filename, world_extension)
+      FFI::GDAL.GDALWriteWorldFile(raster_filename, world_extension, @geo_transform_pointer)
+    end
+  end
+end