ffi-gdal 1.0.0.beta3 → 1.0.0.beta4

data/lib/gdal/driver.rb

@@ -1,15 +1,18 @@
 require_relative '../ffi/gdal'
 require_relative 'major_object'
-require_relative 'driver_extensions'
+require_relative 'exceptions'
+require_relative 'driver_mixins/extensions'
+require_relative 'dataset'
+require_relative 'options'
 require 'multi_xml'
-require 'log_switch'
-
 
 module GDAL
+  # Wrapper for GDAL drivers (aka "formats"). Useful for opening and working
+  # with GDAL datasets.
   class Driver
     include MajorObject
     include GDAL::Logger
-    include DriverExtensions
+    include DriverMixins::Extensions
 
     GDAL_DOCS_URL = 'http://gdal.org'
 
@@ -20,55 +23,25 @@ module GDAL
 
     # @param name [String] Short name of the registered GDALDriver.
     # @return [GDAL::Driver]
+    # @raise [GDAL::InvalidDriverName] If +name+ does not represent a valid
+    #   driver name.
     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
+      if driver_ptr.null?
+        fail InvalidDriverName, "'#{name}' is not a valid driver 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]
+      new(driver_ptr)
     end
 
     # @param index [Fixnum] Index of the registered driver.  Must be less than
     #   GDAL::Driver.count.
     # @return [GDAL::Driver]
+    # @raise [GDAL::InvalidDriverIndex] If driver at +index+ does not exist.
     def self.at_index(index)
       if index > count
-        raise "index must be between 0 and #{count - 1}."
+        fail InvalidDriverIndex, "index must be between 0 and #{count - 1}."
       end
 
       driver_ptr = FFI::GDAL.GDALGetDriver(index)
@@ -77,35 +50,34 @@ module GDAL
     end
 
     # @param file_path [String] File to get the driver for.
-    # @return [GDAL::Driver]
+    # @return [GDAL::Driver] Returns nil if the file is unsupported.
     def self.identify_driver(file_path)
       driver_ptr = FFI::GDAL.GDALIdentifyDriver(::File.expand_path(file_path), nil)
+      return nil if driver_ptr.null?
 
       new(driver_ptr)
     end
 
+    attr_reader :c_pointer
+
     # @param driver [GDAL::Driver, FFI::Pointer]
     def initialize(driver)
-      @driver_pointer = GDAL._pointer(GDAL::Driver, driver)
-    end
-
-    def c_pointer
-      @driver_pointer
+      @c_pointer = GDAL._pointer(GDAL::Driver, driver)
     end
 
     # @return [String]
     def short_name
-      FFI::GDAL.GDALGetDriverShortName(@driver_pointer)
+      FFI::GDAL.GDALGetDriverShortName(@c_pointer)
     end
 
     # @return [String]
     def long_name
-      FFI::GDAL.GDALGetDriverLongName(@driver_pointer)
+      FFI::GDAL.GDALGetDriverLongName(@c_pointer)
     end
 
     # @return [String]
     def help_topic
-      "#{GDAL_DOCS_URL}/#{FFI::GDAL.GDALGetDriverHelpTopic(@driver_pointer)}"
+      "#{GDAL_DOCS_URL}/#{FFI::GDAL.GDALGetDriverHelpTopic(@c_pointer)}"
     end
 
     # Lists and describes the options that can be used when calling
@@ -113,9 +85,9 @@ module GDAL
     #
     # @return [Array]
     def creation_option_list
-      return [] unless @driver_pointer
+      return [] unless @c_pointer
 
-      creation_option_list_xml = FFI::GDAL.GDALGetDriverCreationOptionList(@driver_pointer)
+      creation_option_list_xml = FFI::GDAL.GDALGetDriverCreationOptionList(@c_pointer)
       root = MultiXml.parse(creation_option_list_xml)
       return [] if root.nil? || root.empty?
 
@@ -129,12 +101,12 @@ module GDAL
     # @return [Boolean]
     def validate_creation_options(options)
       options_pointer = if options.is_a? GDAL::Options
-        options.c_pointer
-      else
-        GDAL::Options.pointer(options)
-      end
+                          options.c_pointer
+                        else
+                          GDAL::Options.pointer(options)
+                        end
 
-      FFI::GDAL.GDALValidateCreationOptions(@driver_pointer, options_pointer).to_bool
+      FFI::GDAL.GDALValidateCreationOptions(@c_pointer, options_pointer).to_bool
     end
 
     # Copy all of the associated files of a dataset from one file to another.
@@ -143,10 +115,8 @@ module GDAL
     # @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
+    def copy_dataset_files(old_name, new_name)
+      FFI::GDAL.GDALCopyDatasetFiles(@c_pointer, new_name, old_name)
     end
 
     # Create a new Dataset with this driver.  Legal arguments depend on the
@@ -156,53 +126,46 @@ module GDAL
     # @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)
+    # @param band_count [Fixnum]
+    # @param data_type [FFI::GDAL::DataType]
+    # @return [GDAL::Dataset] Returns the *open* dataset.  You'll need to
+    #   close it.
+    def create_dataset(filename, x_size, y_size, band_count: 1, data_type: :GDT_Byte, **options)
       options_pointer = GDAL::Options.pointer(options)
 
-      dataset_pointer = FFI::GDAL.GDALCreate(@driver_pointer,
+      dataset_pointer = FFI::GDAL.GDALCreate(
+        @c_pointer,
         filename,
         x_size,
         y_size,
-        bands,
+        band_count,
         data_type,
         options_pointer
       )
 
-      raise CreateFail if dataset_pointer.null?
+      fail CreateFail if dataset_pointer.null?
 
-      dataset = Dataset.new(dataset_pointer)
+      dataset = GDAL::Dataset.new(dataset_pointer, nil)
       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 destination_path [String] The name for the new dataset file.
     # @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)
+    def copy_dataset(source_dataset, destination_path, strict: true, **options, &progress)
       options_ptr = GDAL::Options.pointer(options)
+      source_dataset_ptr = make_dataset_pointer(source_dataset)
+      fail "Source dataset couldn't be read" if source_dataset_ptr.null?
 
-      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,
+      destination_dataset_ptr = FFI::GDAL.GDALCreateCopy(
+        @c_pointer,
+        destination_path,
         source_dataset_ptr,
         strict,
         options_ptr,
@@ -210,9 +173,9 @@ module GDAL
         nil
       )
 
-      raise CreateFail if destination_dataset_ptr.null?
+      fail CreateFail if destination_dataset_ptr.null?
 
-      dataset = Dataset.new(destination_dataset_ptr)
+      dataset = Dataset.new(destination_dataset_ptr, 'w')
       yield(dataset) if block_given?
       dataset.close
 
@@ -226,9 +189,7 @@ module GDAL
     # @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
+      FFI::GDAL.GDALDeleteDataset(@c_pointer, file_name)
     end
 
     # @param new_name [String]
@@ -236,9 +197,24 @@ module GDAL
     # @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)
+      FFI::GDAL.GDALRenameDataset(@c_pointer, new_name, old_name)
+    end
 
-      cpl_err.to_bool
+    private
+
+    # @param [GDAL::Dataset, FFI::Pointer, String] dataset Can be another
+    #   dataset, the pointer to another dataset, or the path to a dataset.
+    # @return [GDAL::Dataset]
+    def make_dataset_pointer(dataset)
+      if dataset.is_a? GDAL::Dataset
+        dataset.c_pointer
+      elsif dataset.is_a? String
+        GDAL::Dataset.open(dataset, 'r').c_pointer
+      else
+        dataset
+      end
     end
   end
 end
+
+require_relative 'dataset'

data/lib/gdal/driver_mixins/extensions.rb

@@ -0,0 +1,93 @@
+module GDAL
+  module DriverMixins
+    module Extensions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # @return [Array<String>]
+        def short_names
+          names = count.times.map do |i|
+            driver = at_index(i)
+            driver.short_name
+          end
+
+          names.compact.sort
+        end
+
+        # @return [Array<String>]
+        def long_names
+          names = count.times.map do |i|
+            at_index(i).long_name
+          end
+
+          names.compact.sort
+        end
+
+        # @return [Hash{String => String}] Keys are driver short names, values are
+        #   driver long names.
+        def self.names
+          names = count.times.each_with_object({}) do |i, obj|
+            driver = at_index(i)
+            obj[driver.short_name] = driver.long_name
+          end
+
+          Hash[names.sort]
+        end
+      end
+
+      # 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
+end

data/lib/gdal/exceptions.rb

@@ -1,20 +1,48 @@
 module GDAL
+  class CreateFail < StandardError
+  end
+
+  class Error < ::RuntimeError
+  end
+
   class OpenFailure < StandardError
-    def initialize(file, msg=nil)
+    def initialize(file, msg = nil)
       message = msg || "Unable to open file '#{file}'. Perhaps an unsupported file format?"
       super(message)
     end
   end
 
-  class CPLErrFailure < StandardError
+  class InvalidBandNumber < StandardError
   end
 
-  class CreateFail < StandardError
+  class InvalidColorTable < StandardError
+  end
+
+  class InvalidDriverIndex < StandardError
+  end
+
+  class InvalidDriverName < StandardError
+  end
+
+  class InvalidRasterBand < StandardError
+  end
+
+  class NoWriteAccess < RuntimeError
+  end
+
+  class NullObject < TypeError
   end
 
   class RequiredBandNotFound < StandardError
   end
 
-  class InvalidBandNumber < StandardError
+  class UnknownGridAlgorithm < StandardError
+    def initialize(algorithm, msg = nil)
+      message = msg || "Unknown Grid algorithm type '#{algorithm}'."
+      super(message)
+    end
+  end
+
+  class UnsupportedOperation < StandardError
   end
 end

data/lib/gdal/geo_transform.rb

@@ -1,24 +1,30 @@
 require_relative '../ffi/gdal'
-require_relative 'geo_transform_extensions'
+require_relative 'geo_transform_mixins/extensions'
 
 module GDAL
   class GeoTransform
-    include GeoTransformExtensions
+    include GeoTransformMixins::Extensions
 
+    # @return [FFI::Pointer] A pointer that can be used to hold a GeoTransform.
     def self.new_pointer
       FFI::MemoryPointer.new(:double, 6)
     end
 
-    # @param filename [String]
+    # @return [FFI::Pointer] C pointer to the C geo-transform.
+    attr_reader :c_pointer
+
+    # @param [String] filename
+    # @param [String] extension The file extension to use.  When nil, GDAL will
+    #   try to derive it from the +filename+.
     # @return [GDAL::GeoTransform]
-    def self.from_world_file(filename, extension=nil)
+    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
+                 FFI::GDAL.GDALReadWorldFile(filename, extension, gt_ptr)
+               else
+                 FFI::GDAL.GDALLoadWorldFile(filename, gt_ptr)
+               end
 
       return nil unless result
 
@@ -26,24 +32,25 @@ module GDAL
     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
+    def initialize(geo_transform = nil)
+      @c_pointer = if geo_transform.is_a? GDAL::GeoTransform
+                     geo_transform.c_pointer
+                   elsif geo_transform
+                     geo_transform
+                   else
+                     self.class.new_pointer
+                   end
+
+      self.pixel_width ||= 1.0
+      self.pixel_height ||= 1.0
+      self.x_rotation ||= 0.0
+      self.y_rotation ||= 0.0
 
       to_a
     end
 
-    def c_pointer
-      @geo_transform_pointer
-    end
-
     def null?
-      @geo_transform_pointer.null?
+      @c_pointer.null?
     end
 
     # X-coordinate of the center of the upper left pixel.
@@ -53,12 +60,12 @@ module GDAL
     def x_origin
       return nil if null?
 
-      @geo_transform_pointer[0].read_double
+      @c_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)
+      @c_pointer[0].write_double(new_x_origin)
     end
 
     # AKA X-pixel size.
@@ -68,12 +75,12 @@ module GDAL
     def pixel_width
       return nil if null?
 
-      @geo_transform_pointer[1].read_double
+      @c_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)
+      @c_pointer[1].write_double(new_pixel_width)
     end
 
     # Rotation about the x-axis.
@@ -83,12 +90,12 @@ module GDAL
     def x_rotation
       return nil if null?
 
-      @geo_transform_pointer[2].read_double
+      @c_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)
+      @c_pointer[2].write_double(new_x_rotation)
     end
 
     # Y-coordinate of the center of the upper left pixel.
@@ -98,12 +105,12 @@ module GDAL
     def y_origin
       return nil if null?
 
-      @geo_transform_pointer[3].read_double
+      @c_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)
+      @c_pointer[3].write_double(new_y_origin)
     end
 
     # Rotation about the y-axis.
@@ -113,12 +120,12 @@ module GDAL
     def y_rotation
       return nil if null?
 
-      @geo_transform_pointer[4].read_double
+      @c_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)
+      @c_pointer[4].write_double(new_y_rotation)
     end
 
     # AKA Y-pixel size.
@@ -128,51 +135,64 @@ module GDAL
     def pixel_height
       return nil if null?
 
-      @geo_transform_pointer[5].read_double
+      @c_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)
+      @c_pointer[5].write_double(new_pixel_height)
     end
 
     # Converts a (pixel, line) coordinate to a georeferenced (geo_x, geo_y)
-    # location.
+    # location.  Uses the following algorithm:
+    #
+    #   geo_x = x_origin + (pixel * pixel_width) + (line * pixel_rotation)
+    #   geo_y = y_origin + (pixel * y_rotation) + (line * pixel_height)
+    #
+    # This is also the same as doing:
+    #
+    #   geo_transform.invert.world_to_pixel(pixel, line)
     #
     # @param pixel [Float] Input pixel position.
     # @param line [Float] Input line position.
-    # @return [Hash{x_location: Float, y_location: Float}] longitude, latitude.
+    # @return [Hash{x_geo => Float, y_geo => Float}]  +:x_geo+ is the
+    # #   easting/longitude; +:y_geo+ is the northing/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)
+      FFI::GDAL.GDALApplyGeoTransform(@c_pointer, pixel, line, geo_x_ptr, geo_y_ptr)
 
-      { longitude: geo_x_ptr.read_double, latitude: geo_y_ptr.read_double }
+      { x_geo: geo_x_ptr.read_double, y_geo: geo_y_ptr.read_double }
     end
+    alias_method :pixel_to_world, :apply_geo_transform
 
-    # Composes this and the give geo_transform.  The result is equivalent to
-    # applying both geotransforms to a point.
+    # Composes this and the given geo_transform.  The resulting GeoTransform 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)
 
+      unless other_ptr
+        fail GDAL::NullObject, "Unable to access pointer for '#{other_geo_transform}'"
+      end
+
       new_gt_ptr = self.class.new_pointer
-      FFI::GDAL.GDALComposeGeoTransforms(@geo_transform_pointer, other_ptr, new_gt_ptr)
+      FFI::GDAL.GDALComposeGeoTransforms(@c_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
+    # 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)
+      success = FFI::GDAL.GDALInvGeoTransform(@c_pointer, new_geo_transform_ptr)
       return nil unless success
 
       self.class.new(new_geo_transform_ptr)
@@ -182,7 +202,7 @@ module GDAL
     # @param world_extension [String]
     # @return [Boolean]
     def to_world_file(raster_filename, world_extension)
-      FFI::GDAL.GDALWriteWorldFile(raster_filename, world_extension, @geo_transform_pointer)
+      FFI::GDAL.GDALWriteWorldFile(raster_filename, world_extension, @c_pointer)
     end
   end
 end