ffi-gdal 0.0.1

data/lib/ffi-gdal/dataset.rb

@@ -0,0 +1,347 @@
+require_relative '../ffi/gdal'
+require_relative '../ffi-gdal'
+require_relative 'driver'
+require_relative 'geo_transform'
+require_relative 'raster_band'
+require_relative 'exceptions'
+require_relative 'major_object'
+
+
+module GDAL
+
+  # A set of associated raster bands and info common to them all.  It's also
+  # responsible for the georeferencing transform and coordinate system
+  # definition of all bands.
+  class Dataset
+    include FFI::GDAL
+    include MajorObject
+
+    ACCESS_FLAGS = {
+      'r' => :GA_ReadOnly,
+      'w' => :GA_Update
+    }
+
+    # @param path [String] Path to the file that contains the dataset.
+    # @param access_flag [String] 'r' or 'w'.
+    def self.open(path, access_flag)
+      file_path = ::File.expand_path(path)
+      pointer = FFI::GDAL.GDALOpen(file_path, ACCESS_FLAGS[access_flag])
+      raise OpenFailure.new(file_path) if pointer.null?
+
+      new(pointer)
+    end
+
+    # Computes NDVI from the red and near-infrared bands in the dataset.  Raises
+    # a GDAL::RequiredBandNotFound if one of those band types isn't found.
+    #
+    # @param source [String] Path to the dataset that contains the red and NIR
+    #   bands.
+    # @param destination [String] Path to output the new dataset to.
+    # @param driver_name [String] The type of dataset to create.
+    def self.extract_ndvi(source, destination, driver_name: 'GTiff')
+      extract_8bit(source, destination, driver_name) do |original, ndvi_dataset|
+        red = original.red_band
+        nir = original.undefined_band
+
+        if red.nil?
+          fail RequiredBandNotFound, 'Red band not found.'
+        elsif nir.nil?
+          fail RequiredBandNotFound, 'Near-infrared'
+        end
+
+        the_array = original.calculate_ndvi(red.to_a, nir.to_a)
+
+        ndvi_band = ndvi_dataset.raster_band(1)
+        ndvi_band.write_array(the_array)
+      end
+    end
+
+    def self.extract_gndvi(source, destination, driver_name: 'GTiff')
+      extract_8bit(source, destination, driver_name) do |original, gndvi_dataset|
+        green = original.green_band
+        nir = original.undefined_band
+
+        if green.nil?
+          fail RequiredBandNotFound, 'Green band not found.'
+        elsif nir.nil?
+          fail RequiredBandNotFound, 'Near-infrared'
+        end
+
+        the_array = original.calculate_ndvi(green.to_a, nir.to_a)
+
+        gndvi_band = gndvi_dataset.raster_band(1)
+        gndvi_band.write_array(the_array)
+      end
+    end
+
+    def self.extract_nir(source, destination, driver_name: 'GTiff')
+      extract_8bit(source, destination, driver_name) do |original, nir_dataset|
+        nir = original.undefined_band
+        fail RequiredBandNotFound, 'Near-infrared' if nir.nil?
+
+        nir_band = nir_dataset.raster_band(1)
+        nir_band.write_array(nir.to_a)
+      end
+    end
+
+    def self.extract_natural_color(source, destination, driver_name: 'GTiff')
+      original_dataset = open(source, 'r')
+      geo_transform = original_dataset.geo_transform
+      projection = original_dataset.projection
+      rows = original_dataset.raster_y_size
+      columns = original_dataset.raster_x_size
+
+      driver = GDAL::Driver.by_name(driver_name)
+      driver.create_dataset(destination, columns, rows, bands: 3) do |new_dataset|
+        new_dataset.geo_transform = geo_transform
+        new_dataset.projection = projection
+        original_red_band = original_dataset.red_band
+        original_green_band = original_dataset.green_band
+        original_blue_band = original_dataset.blue_band
+
+        new_red_band = new_dataset.raster_band(1)
+        new_red_band.write_array(original_red_band.to_a)
+
+        new_green_band = new_dataset.raster_band(2)
+        new_green_band.write_array(original_green_band.to_a)
+
+        new_blue_band = new_dataset.raster_band(3)
+        new_blue_band.write_array(original_blue_band.to_a)
+      end
+    end
+
+    def self.extract_8bit(source, destination, driver_name)
+      dataset = open(source, 'r')
+      geo_transform = dataset.geo_transform
+      projection = dataset.projection
+      rows = dataset.raster_y_size
+      columns = dataset.raster_x_size
+
+      driver = GDAL::Driver.by_name(driver_name)
+      driver.create_dataset(destination, columns, rows) do |new_dataset|
+        new_dataset.geo_transform = geo_transform
+        new_dataset.projection = projection
+
+        yield dataset, new_dataset
+      end
+    end
+    private_class_method :extract_8bit
+
+    # @param dataset_pointer [FFI::Pointer] Pointer to the dataset in memory.
+    def initialize(dataset_pointer)
+      @gdal_dataset = dataset_pointer
+      @last_known_file_list = []
+      @open = true
+      close_me = -> { self.close }
+      ObjectSpace.define_finalizer self, close_me
+    end
+
+    # @return [FFI::Pointer] Pointer to the GDALDatasetH that's represented by
+    # this Ruby object.
+    def c_pointer
+      @gdal_dataset
+    end
+
+    # Close the dataset.
+    def close
+      @last_known_file_list = file_list
+      GDALClose(@gdal_dataset)
+      @open = false
+    end
+
+    # Tries to reopen the dataset using the first item from #file_list before
+    # the dataset was closed.
+    #
+    # @param access_flag [String]
+    # @return [Boolean]
+    def reopen(access_flag)
+      @gdal_dataset = GDALOpen(@last_known_file_list.first, access_flag)
+
+      @open = true unless @gdal_dataset.null?
+    end
+
+    # @return [Boolean]
+    def open?
+      @open
+    end
+
+    # @return [GDAL::Driver] The driver to be used for working with this
+    #   dataset.
+    def driver
+      return @driver if @driver
+
+      @driver = if @gdal_dataset && !null?
+        Driver.new(dataset: @gdal_dataset)
+      else
+        Driver.new
+      end
+    end
+
+    # Fetches all files that form the dataset.
+    # @return [Array<String>]
+    def file_list
+      list_pointer = GDALGetFileList(c_pointer)
+      file_list = list_pointer.get_array_of_string(0)
+      CSLDestroy(list_pointer)
+
+      file_list
+    end
+
+    # @return [Fixnum]
+    def raster_x_size
+      return nil if null?
+
+      GDALGetRasterXSize(@gdal_dataset)
+    end
+
+    # @return [Fixnum]
+    def raster_y_size
+      return nil if null?
+
+      GDALGetRasterYSize(@gdal_dataset)
+    end
+
+    # @return [Fixnum]
+    def raster_count
+      return 0 if null?
+
+      GDALGetRasterCount(@gdal_dataset)
+    end
+
+    # @param raster_index [Fixnum]
+    # @return [GDAL::RasterBand]
+    def raster_band(raster_index)
+      @raster_bands ||= Array.new(raster_count)
+
+      if @raster_bands[raster_index] && !@raster_bands[raster_index].null?
+        return @raster_bands[raster_index]
+      end
+
+      @raster_bands[raster_index] =
+        GDAL::RasterBand.new(@gdal_dataset, band_id: raster_index)
+    end
+
+    # @return [String]
+    def projection
+      return '' if null?
+
+      GDALGetProjectionRef(@gdal_dataset)
+    end
+
+    # @param new_projection [String]
+    # @return [Boolean]
+    def projection=(new_projection)
+      cpl_err = GDALSetProjection(@gdal_dataset, new_projection)
+
+      cpl_err.to_bool
+    end
+
+    # @return [Symbol]
+    def access_flag
+      return nil if null?
+
+      flag = GDALGetAccess(@gdal_dataset)
+
+      GDALAccess[flag]
+    end
+
+    # @return [GDAL::GeoTransform]
+    def geo_transform
+      @geo_transform ||= GeoTransform.new(@gdal_dataset)
+    end
+
+    # @param new_transform [GDAL::GeoTransform]
+    # @return [GDAL::GeoTransform]
+    def geo_transform=(new_transform)
+      new_pointer = new_transform.c_pointer.dup
+      cpl_err = GDALSetGeoTransform(@gdal_dataset, new_pointer)
+      cpl_err.to_bool
+
+      @geo_transform = GeoTransform.new(@gdal_dataset, geo_transform_pointer: new_pointer)
+    end
+
+    # @return [Fixnum]
+    def gcp_count
+      return 0 if null?
+
+      GDALGetGCPCount(@gdal_dataset)
+    end
+
+    # @return [String]
+    def gcp_projection
+      return '' if null?
+
+      GDALGetGCPProjection(@gdal_dataset)
+    end
+
+    # @return [FFI::GDAL::GDALGCP]
+    def gcps
+      return GDALGCP.new if null?
+
+      gcp_array_pointer = GDALGetGCPs(@gdal_dataset)
+
+      if gcp_array_pointer.null?
+        GDALGCP.new
+      else
+        GDALGCP.new(gcp_array_pointer)
+      end
+    end
+
+    # Iterates raster bands from 1 to #raster_count and yields them to the given
+    # block.
+    def each_band
+      1.upto(raster_count) do |i|
+        yield(raster_band(i))
+      end
+    end
+
+    # Returns the first raster band for which the block returns true.  Ex.
+    #
+    #   dataset.find_band do |band|
+    #     band.color_interpretation == :GCI_RedBand
+    #   end
+    #
+    # @return [GDAL::RasterBand]
+    def find_band
+      each_band do |band|
+        result = yield(band)
+        return band if result
+      end
+    end
+
+    # @param red_band_array [NArray]
+    # @param nir_band_array [NArray]
+    # @return [NArray]
+    def calculate_ndvi(red_band_array, nir_band_array)
+      (nir_band_array - red_band_array) / (nir_band_array + red_band_array)
+    end
+
+    # @return [GDAL::RasterBand]
+    def red_band
+      find_band do |band|
+        band.color_interpretation == :GCI_RedBand
+      end
+    end
+
+    # @return [GDAL::RasterBand]
+    def green_band
+      find_band do |band|
+        band.color_interpretation == :GCI_GreenBand
+      end
+    end
+
+    # @return [GDAL::RasterBand]
+    def blue_band
+      find_band do |band|
+        band.color_interpretation == :GCI_BlueBand
+      end
+    end
+
+    # @return [GDAL::RasterBand]
+    def undefined_band
+      find_band do |band|
+        band.color_interpretation == :GCI_Undefined
+      end
+    end
+  end
+end

data/lib/ffi-gdal/driver.rb

@@ -0,0 +1,151 @@
+require_relative '../ffi/gdal'
+require_relative 'major_object'
+require 'multi_xml'
+require 'log_switch'
+
+
+module GDAL
+  class Driver
+    include FFI::GDAL
+    include MajorObject
+    include LogSwitch::Mixin
+
+    GDAL_DOCS_URL = 'http://gdal.org'
+
+    # @return [Fixnum]
+    def self.driver_count
+      FFI::GDAL.GDALGetDriverCount
+    end
+
+    # @return [GDAL::Driver]
+    def self.by_name(name)
+      new(name: name)
+    end
+
+    # Creates a new GDAL::Driver object based on the mutually exclusive given
+    # parameters.  Pass in only one of the allowed parameters.
+    #
+    # @param file_path [String] File to get the driver for.
+    # @param name [String] Name of the registered GDALDriver.
+    # @param index [Fixnum] Index of the registered driver.  Must be less than
+    #   GDAL::Driver.driver_count.
+    # @param dataset [FFI::Pointer] Pointer to the GDALDataset.
+    def initialize(file_path: file_path, name: name, index: index, dataset: dataset)
+      @gdal_driver_handle = if file_path
+        GDALIdentifyDriver(::File.expand_path(file_path), nil)
+      elsif name
+        GDALGetDriverByName(name)
+      elsif index
+        count = self.class.driver_count
+        raise "index must be between 0 and #{count - 1}." if index > count
+
+        GDALGetDriver(index)
+      elsif dataset
+        GDALGetDatasetDriver(dataset)
+      end
+    end
+
+    def c_pointer
+      @gdal_driver_handle
+    end
+
+    # @return [String]
+    def short_name
+      return '' unless @gdal_driver_handle
+
+      GDALGetDriverShortName(@gdal_driver_handle)
+    end
+
+    # @return [String]
+    def long_name
+      return '' unless @gdal_driver_handle
+
+      GDALGetDriverLongName(@gdal_driver_handle)
+    end
+
+    # @return [String]
+    def help_topic
+      return '' unless @gdal_driver_handle
+
+      "#{GDAL_DOCS_URL}/#{GDALGetDriverHelpTopic(@gdal_driver_handle)}"
+    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 @gdal_driver_handle
+
+      creation_option_list_xml = GDALGetDriverCreationOptionList(@gdal_driver_handle)
+      MultiXml.parse(creation_option_list_xml)['CreationOptionList']['Option']
+    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 = GDALCopyDatasetFiles(@gdal_driver_handle, 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.
+    #
+    # @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 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, type: :GDT_Byte, **options)
+      log "creating dataset with size #{x_size},#{y_size}"
+
+      dataset_pointer = GDALCreate(@gdal_driver_handle,
+        filename,
+        x_size,
+        y_size,
+        bands,
+        type,
+        nil
+      )
+
+      raise CreateFail if dataset_pointer.null?
+
+      dataset = Dataset.new(dataset_pointer)
+      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 = GDALDeleteDataset(@gdal_driver_handle, 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 = GDALRenameDataset(@gdal_driver_handle, new_name, old_name)
+
+
+      cpl_err.to_bool
+    end
+  end
+end

data/lib/ffi-gdal/exceptions.rb

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

data/lib/ffi-gdal/geo_transform.rb

@@ -0,0 +1,137 @@
+require_relative '../ffi/gdal'
+
+
+module GDAL
+  class GeoTransform
+    include FFI::GDAL
+
+    attr_accessor :gdal_dataset
+
+    # @param gdal_dataset [FFI::Pointer]
+    def initialize(dataset, geo_transform_pointer: nil)
+      @gdal_dataset = if dataset.nil?
+        FFI::MemoryPointer.new(:pointer)
+      elsif dataset.is_a? GDAL::Dataset
+        dataset.c_pointer
+      else
+        dataset
+      end
+
+      @gdal_geo_transform = if geo_transform_pointer
+        geo_transform_pointer
+      else
+        container_pointer = FFI::MemoryPointer.new(:double, 6)
+        GDALGetGeoTransform(@gdal_dataset, container_pointer).to_ruby
+        container_pointer
+      end
+
+      to_a
+    end
+
+    def c_pointer
+      @gdal_geo_transform
+    end
+
+    def null?
+      @gdal_geo_transform.null?
+    end
+
+    # All attributes as an Array, in the order:
+    #   * x_origin
+    #   * pixel_width
+    #   * x_rotation
+    #   * y_origin
+    #   * y_rotation
+    #   * pixel_height
+    #
+    # @return [Array]
+    def to_a
+      [
+        x_origin,
+        pixel_width,
+        x_rotation,
+        y_origin,
+        y_rotation,
+        pixel_height
+      ]
+    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?
+
+      @gdal_geo_transform[0].read_double
+    end
+
+    # AKA X-pixel size.
+    # In wikipedia's World Map definition, this is "A".
+    #
+    # @return [Float]
+    def pixel_width
+      return nil if null?
+
+      @gdal_geo_transform[1].read_double
+    end
+
+    # Rotation about the x-axis.
+    # In wikipedia's World Map definition, this is "B".
+    #
+    # @return [Float]
+    def x_rotation
+      return nil if null?
+
+      @gdal_geo_transform[2].read_double
+    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?
+
+      @gdal_geo_transform[3].read_double
+    end
+
+    # Rotation about the y-axis.
+    # In wikipedia's World Map definition, this is "D".
+    #
+    # @return [Float]
+    def y_rotation
+      return nil if null?
+
+      @gdal_geo_transform[4].read_double
+    end
+
+    # AKA Y-pixel size.
+    # In wikipedia's World Map definition, this is "E".
+    #
+    # @return [Float]
+    def pixel_height
+      return nil if null?
+
+      @gdal_geo_transform[5].read_double
+    end
+
+    # The calculated UTM easting of the pixel on the map.
+    #
+    # @return [Float]
+    def x_projection(x_pixel, y_pixel)
+      return nil if null?
+
+      (pixel_width * x_pixel) + (x_rotation * y_pixel) + x_origin
+    end
+
+    # The calculated UTM northing of the pixel on the map.
+    #
+    # @return [Float]
+    def y_projection(x_pixel, y_pixel)
+      return nil if null?
+
+      (y_rotation * x_pixel) + (pixel_height * y_pixel) + y_origin
+    end
+  end
+end

data/lib/ffi-gdal/major_object.rb

@@ -0,0 +1,71 @@
+require_relative '../ffi/gdal'
+
+
+module GDAL
+  module MajorObject
+    include FFI::GDAL
+
+    # @return [Array<String>]
+    def metadata_domain_list
+      # I don't quite get it, but if #GDALGetMetadataDomainList isn't called
+      # twice, the last domain in the list sometimes doesn't get read.
+      GDALGetMetadataDomainList(c_pointer)
+      list_pointer = GDALGetMetadataDomainList(c_pointer)
+      return [] if list_pointer.null?
+
+      strings = list_pointer.get_array_of_string(0)
+
+      strings.compact.delete_if(&:empty?)
+    end
+
+    # @param domain [String] Name of the domain to get metadata for.
+    # @return [Hash]
+    def metadata_for_domain(domain='')
+      m = GDALGetMetadata(c_pointer, domain)
+      return {} if m.null?
+
+      data_array = m.get_array_of_string(0)
+
+      data_array.each_with_object({}) do |key_value_pair, obj|
+        key, value = key_value_pair.split('=', 2)
+
+        begin
+          obj[key] = MultiXml.parse(value)
+        rescue MultiXml::ParseError
+          obj[key] = value
+        end
+      end
+    end
+
+    # @param name [String]
+    # @param domain [String]
+    # @return [String]
+    def metadata_item(name, domain='')
+      GDALGetMetadataItem(c_pointer, name, domain)
+    end
+
+    # @return [Hash{domain => Array<String>}]
+    def all_metadata
+      sub_metadata = metadata_domain_list.each_with_object({}) do |subdomain, obj|
+        metadata_array = metadata_for_domain(subdomain)
+        obj[subdomain] = metadata_array
+      end
+
+      { DEFAULT: metadata_for_domain }.merge(sub_metadata)
+    end
+
+    # @return [String]
+    def description
+      GDALGetDescription(c_pointer)
+    end
+
+    # @param new_description [String]
+    def description=(new_description)
+      GDALSetDescription(c_pointer, new_description.to_s)
+    end
+
+    def null?
+      c_pointer.null?
+    end
+  end
+end