ffi-gdal 1.0.0.beta16 → 1.0.0

data/lib/gdal/dataset_mixins/warp_methods.rb

@@ -20,7 +20,7 @@ module GDAL
       # @param warp_options [GDAL::WarpOptions] Warp options, normally empty.
       def reproject_image(destination_dataset, resample_algorithm, destination_projection: nil,
         warp_memory_limit: 0.0, max_error: 0.0, progress_function: nil, progress_arg: nil, warp_options: nil)
-        warp_options_struct = warp_options ? warp_options.c_struct : nil
+        warp_options_struct = warp_options&.c_struct
 
         FFI::GDAL::Warper.GDALReprojectImage(
           @c_pointer,                           # hSrcDS
@@ -55,13 +55,14 @@ module GDAL
       # @param progress_arg [FFI::Pointer] Argument to be passed to
       #   +progress_function+.
       # @param warp_options [GDAL::WarpOptions] Warp options, normally empty.
+      # rubocop:disable Metrics/ParameterLists
       def create_and_reproject_image(destination_file_name, resample_algorithm, destination_projection,
         destination_driver, creation_options: {},
         warp_memory_limit: 0.0, max_error: 0.0,
         progress_function: nil, progress_arg: nil,
         warp_options: nil)
         creation_options_ptr = GDAL::Options.pointer(creation_options)
-        warp_options_struct = warp_options ? warp_options.c_struct : nil
+        warp_options_struct = warp_options&.c_struct
 
         FFI::GDAL::Warper.GDALCreateAndReprojectImage(
           @c_pointer,                           # hSrcDS
@@ -78,6 +79,7 @@ module GDAL
           warp_options_struct                   # psOptions
         )
       end
+      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/gdal/driver.rb

@@ -3,7 +3,6 @@
 require 'multi_xml'
 require_relative '../gdal'
 require_relative 'major_object'
-require_relative 'driver_mixins/extensions'
 
 module GDAL
   # Wrapper for GDAL drivers (aka "formats"). Useful for opening and working
@@ -11,11 +10,10 @@ module GDAL
   class Driver
     include MajorObject
     include GDAL::Logger
-    include DriverMixins::Extensions
 
     GDAL_DOCS_URL = 'http://gdal.org'
 
-    # @return [Fixnum]
+    # @return [Integer]
     def self.count
       FFI::GDAL::GDAL.GDALGetDriverCount
     end
@@ -32,7 +30,7 @@ module GDAL
       new(driver_ptr)
     end
 
-    # @param index [Fixnum] Index of the registered driver.  Must be less than
+    # @param index [Integer] 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.
@@ -57,22 +55,34 @@ module GDAL
 
     # @param driver [GDAL::Driver, FFI::Pointer]
     def initialize(driver)
-      @c_pointer = GDAL._pointer(GDAL::Driver, driver)
+      @c_pointer = GDAL._pointer(GDAL::Driver, driver, autorelease: false)
     end
 
     # @return [String]
     def short_name
-      FFI::GDAL::GDAL.GDALGetDriverShortName(@c_pointer)
+      # The returned string should not be freed and is owned by the driver.
+      name, ptr = FFI::GDAL::GDAL.GDALGetDriverShortName(@c_pointer)
+      ptr.autorelease = false
+
+      name
     end
 
     # @return [String]
     def long_name
-      FFI::GDAL::GDAL.GDALGetDriverLongName(@c_pointer)
+      # The returned string should not be freed and is owned by the driver.
+      name, ptr = FFI::GDAL::GDAL.GDALGetDriverLongName(@c_pointer)
+      ptr.autorelease = false
+
+      name
     end
 
     # @return [String]
     def help_topic
-      "#{GDAL_DOCS_URL}/#{FFI::GDAL::GDAL.GDALGetDriverHelpTopic(@c_pointer)}"
+      # The returned string should not be freed and is owned by the driver.
+      url, ptr = FFI::GDAL::GDAL.GDALGetDriverHelpTopic(@c_pointer)
+      ptr.autorelease = false
+
+      "#{GDAL_DOCS_URL}/#{url}"
     end
 
     # Lists and describes the options that can be used when calling
@@ -82,8 +92,11 @@ module GDAL
     def creation_option_list
       return [] unless @c_pointer
 
-      creation_option_list_xml = FFI::GDAL::GDAL.GDALGetDriverCreationOptionList(@c_pointer)
+      # The returned string should not be freed and is owned by the driver.
+      creation_option_list_xml, ptr = FFI::GDAL::GDAL.GDALGetDriverCreationOptionList(@c_pointer)
+      ptr.autorelease = false
       root = MultiXml.parse(creation_option_list_xml)
+
       return [] if root.nil? || root.empty?
 
       list = root['CreationOptionList']
@@ -109,9 +122,11 @@ module GDAL
     # @param new_name [String]
     # @param old_name [String]
     # @return true on success, false on warning.
-    # @raise [GDAL::CPLErrFailure] If failures.
+    # @raise [GDAL::Error] If failures.
     def copy_dataset_files(old_name, new_name)
-      FFI::GDAL::GDAL.GDALCopyDatasetFiles(@c_pointer, new_name, old_name)
+      GDAL::CPLErrorHandler.manually_handle("Unable to copy dataset files: '#{old_name}' -> '#{new_name}'") do
+        FFI::GDAL::GDAL.GDALCopyDatasetFiles(@c_pointer, new_name, old_name)
+      end
     end
 
     # Create a new Dataset with this driver.  Legal arguments depend on the
@@ -119,9 +134,9 @@ module GDAL
     # 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 band_count [Fixnum]
+    # @param x_size [Integer] Width of created raster in pixels.
+    # @param y_size [Integer] Height of created raster in pixels.
+    # @param band_count [Integer]
     # @param data_type [FFI::GDAL::GDAL::DataType]
     # @return [GDAL::Dataset] If no block is given, returns the *open*
     #   (writable) dataset; you'll need to close it. If a block is given,
@@ -201,18 +216,20 @@ module GDAL
     # 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.
+    # @raise [GDAL::Error] If failures.
     def delete_dataset(file_name)
-      FFI::GDAL::GDAL.GDALDeleteDataset(@c_pointer, file_name)
+      GDAL::CPLErrorHandler.manually_handle("Unable to delete dataset: #{file_name}") do
+        FFI::GDAL::GDAL.GDALDeleteDataset(@c_pointer, file_name)
+      end
     end
 
     # @param old_name [String]
     # @param new_name [String]
-    # @return true on success, false on warning.
-    # @raise [GDAL::CPLErrFailure] If failures.
+    # @raise [GDAL::Error] If failures.
     def rename_dataset(old_name, new_name)
-      FFI::GDAL::GDAL.GDALRenameDataset(@c_pointer, new_name, old_name)
+      GDAL::CPLErrorHandler.manually_handle("Unable to rename dataset: #{old_name}") do
+        FFI::GDAL::GDAL.GDALRenameDataset(@c_pointer, new_name, old_name)
+      end
     end
 
     private
@@ -224,7 +241,7 @@ module GDAL
       if dataset.is_a? String
         GDAL::Dataset.open(dataset, 'r').c_pointer
       else
-        GDAL._pointer(GDAL::Dataset, dataset)
+        GDAL._pointer(GDAL::Dataset, dataset, autorelease: false)
       end
     end
   end

data/lib/gdal/environment_methods.rb

@@ -3,32 +3,32 @@
 module GDAL
   # Getters and setters for the GDAL environment.
   module EnvironmentMethods
-    # @return [Fixnum] The maximum cache memory.
+    # @return [Integer] The maximum cache memory.
     def cache_max
       FFI::GDAL::GDAL.GDALGetCacheMax
     end
 
-    # @param bytes [Fixnum]
+    # @param bytes [Integer]
     def cache_max=(bytes)
       FFI::GDAL::GDAL.GDALSetCacheMax(bytes)
     end
 
-    # @return [Fixnum] The maximum cache memory.
+    # @return [Integer] The maximum cache memory.
     def cache_max64
       FFI::GDAL::GDAL.GDALGetCacheMax64
     end
 
-    # @param bytes [Fixnum]
+    # @param bytes [Integer]
     def cache_max64=(bytes)
       FFI::GDAL::GDAL.GDALSetCacheMax64(bytes)
     end
 
-    # @return [Fixnum] The amount of used cache memory.
+    # @return [Integer] The amount of used cache memory.
     def cache_used
       FFI::GDAL::GDAL.GDALGetCacheUsed
     end
 
-    # @return [Fixnum] The amount of used cache memory.
+    # @return [Integer] The amount of used cache memory.
     def cache_used64
       FFI::GDAL::GDAL.GDALGetCacheUsed64
     end

data/lib/gdal/extensions/all.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, '**/extensions/**/*.rb')].sort.each { |f| require f }

data/lib/gdal/{color_entry_mixins → extensions/color_entry}/extensions.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'gdal/color_entry'
 
 module GDAL
   module ColorEntryMixins
@@ -8,7 +9,7 @@ module GDAL
       # @param include_fourth [Boolean] Turn off in case you don't want the fourth
       #   color in the array.
       # @return [Array]
-      def to_a(include_fourth = true)
+      def to_a(include_fourth: true)
         if include_fourth
           [color1, color2, color3, color4]
         else
@@ -18,3 +19,5 @@ module GDAL
     end
   end
 end
+
+GDAL::ColorEntry.include(GDAL::ColorEntryMixins::Extensions)

data/lib/gdal/{color_table_mixins → extensions/color_table}/extensions.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'gdal/color_table'
 
 module GDAL
   module ColorTableMixins
@@ -32,3 +33,5 @@ module GDAL
     end
   end
 end
+
+GDAL::ColorTable.include(GDAL::ColorTableMixins::Extensions)

data/lib/gdal/extensions/dataset/extensions.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'narray'
+require 'ffi-gdal'
+require 'gdal/dataset'
+require 'gdal/raster_band'
+require 'gdal/warp_operation'
+require 'ogr/driver'
+require 'ogr/layer'
+require 'ogr/spatial_reference'
+require 'ogr/coordinate_transformation'
+
+module GDAL
+  class Dataset
+    # Methods not originally supplied with GDAL, but enhance it.
+    module Extensions
+      # @return [Array<GDAL::RasterBand>]
+      def raster_bands
+        1.upto(raster_count).map do |i|
+          raster_band(i)
+        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.
+      #
+      # @example
+      #
+      #   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
+
+      # @return [GDAL::RasterBand, nil]
+      def red_band
+        band = find_band do |b|
+          b.color_interpretation == :GCI_RedBand
+        end
+
+        band.is_a?(GDAL::RasterBand) ? band : nil
+      end
+
+      # @return [GDAL::RasterBand, nil]
+      def green_band
+        band = find_band do |b|
+          b.color_interpretation == :GCI_GreenBand
+        end
+
+        band.is_a?(GDAL::RasterBand) ? band : nil
+      end
+
+      # @return [GDAL::RasterBand, nil]
+      def blue_band
+        band = find_band do |b|
+          b.color_interpretation == :GCI_BlueBand
+        end
+
+        band.is_a?(GDAL::RasterBand) ? band : nil
+      end
+
+      # @return [GDAL::RasterBand, nil]
+      def undefined_band
+        band = find_band do |b|
+          b.color_interpretation == :GCI_Undefined
+        end
+
+        band.is_a?(GDAL::RasterBand) ? band : nil
+      end
+
+      # Converts raster band number +band_number+ to the vector format
+      # +vector_driver_name+.  Similar to gdal_polygonize.py.  If block format is
+      # used, the new DataSource will be closed/flushed when the block returns. If
+      # the non-block format is used, you need to call #close on the DataSource.
+      #
+      # @param file_name [String] Path to write the vector file to.
+      # @param vector_driver_name [String] One of OGR::Driver.names.
+      # @param geometry_type [FFI::GDAL::OGRwkbGeometryType] The type of geometry
+      #   to use when turning the raster into a vector image.
+      # @param layer_name_prefix [String] Prefix of the name to give the new
+      #   vector layer.
+      # @param band_numbers [Array<Integer>,Integer] Number of the raster band or
+      #   bands from this dataset to vectorize.  Can be a single Integer or array
+      #   of Integers.
+      # @return [OGR::DataSource]
+      def to_vector(file_name, vector_driver_name, geometry_type: :wkbUnknown,
+        layer_name_prefix: 'band_number', band_numbers: [1],
+        field_name_prefix: 'field', use_band_masks: true)
+        band_numbers = [band_numbers] unless band_numbers.is_a?(Array)
+        ogr_driver = OGR::Driver.by_name(vector_driver_name)
+
+        if projection.empty?
+          spatial_ref = nil
+        else
+          spatial_ref = OGR::SpatialReference.new(projection)
+          begin
+            spatial_ref.auto_identify_epsg!
+          rescue StandardError
+            OGR::UnsupportedSRS
+          end
+        end
+
+        data_source = ogr_driver.create_data_source(file_name)
+
+        # TODO: fasterer: each_with_index is slower than loop
+        band_numbers.each_with_index do |band_number, i|
+          log "Starting to polygonize raster band #{band_number}..."
+          layer_name = "#{layer_name_prefix}-#{band_number}"
+          layer = data_source.create_layer(layer_name, geometry_type: geometry_type,
+                                                       spatial_reference: spatial_ref)
+
+          field_name = "#{field_name_prefix}#{i}"
+          layer.create_field(OGR::FieldDefinition.new(field_name, :OFTInteger))
+          band = raster_band(band_number)
+
+          raise GDAL::InvalidBandNumber, "Unknown band number: #{band_number}" unless band
+
+          pixel_value_field = layer.feature_definition.field_index(field_name)
+          options = { pixel_value_field: pixel_value_field }
+          options[:mask_band] = band.mask_band if use_band_masks
+          band.polygonize(layer, **options)
+        end
+
+        if block_given?
+          yield data_source
+          data_source.close
+        end
+
+        data_source
+      end
+
+      # Gets the OGR::Geometry that represents the extent of the dataset.
+      #
+      # @return [OGR::Polygon]
+      # TODO: This should return an OGR::Envelope.
+      def extent
+        ul = geo_transform.apply_geo_transform(0, 0)
+        ur = geo_transform.apply_geo_transform(raster_x_size, 0)
+        lr = geo_transform.apply_geo_transform(raster_x_size, raster_y_size)
+        ll = geo_transform.apply_geo_transform(0, raster_y_size)
+
+        ring = OGR::LinearRing.new
+        ring.point_count = 5
+        ring.set_point(0, ul[:x_geo], ul[:y_geo])
+        ring.set_point(1, ur[:x_geo], ur[:y_geo])
+        ring.set_point(2, lr[:x_geo], lr[:y_geo])
+        ring.set_point(3, ll[:x_geo], ll[:y_geo])
+        ring.set_point(4, ul[:x_geo], ul[:y_geo])
+
+        polygon = OGR::Polygon.new
+        polygon.add_geometry(ring)
+        polygon.spatial_reference = spatial_reference
+
+        polygon
+      end
+
+      # @param wkt_geometry_string [String]
+      # @param wkt_srid [Integer]
+      # @return [Boolean]
+      def contains_geometry?(wkt_geometry_string, wkt_srid = 4326)
+        source_srs = OGR::SpatialReference.new_from_epsg(wkt_srid)
+        source_geometry = OGR::Geometry.create_from_wkt(wkt_geometry_string, source_srs)
+        @raster_geometry ||= extent
+
+        coordinate_transformation = OGR::CoordinateTransformation.new(source_srs,
+                                                                      @raster_geometry.spatial_reference)
+        source_geometry.transform!(coordinate_transformation)
+
+        @raster_geometry.contains? source_geometry
+      end
+
+      # Retrieves pixels from each raster band and converts this to an array of
+      # points per pixel.  For example:
+      #
+      #   # If the arrays for each band look like:
+      #   red_band_array = [0, 0, 0]
+      #   green_band_array = [10, 10, 10]
+      #   blue_band_array = [99, 99, 99]
+      #   alpha_band_array = [250, 150, 2]
+      #
+      #   # This array would look like:
+      #   [[0, 10, 99, 2], [0, 10, 99, 150], [0, 10, 99, 250]]
+      # @return NArray
+      def to_na(to_data_type = nil)
+        na = NMatrix.to_na(raster_bands.map { |r| r.to_na(to_data_type) })
+
+        NArray[*na.transpose]
+      end
+    end
+  end
+end
+GDAL::Dataset.include(GDAL::Dataset::Extensions)

data/lib/gdal/{driver_mixins → extensions/driver}/extensions.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'gdal/driver'
+
 module GDAL
-  module DriverMixins
+  class Driver
     module Extensions
       def self.included(base)
         base.extend(ClassMethods)
@@ -30,7 +32,7 @@ module GDAL
             obj[driver.short_name] = driver.long_name
           end
 
-          Hash[names.sort]
+          names.sort.to_h
         end
       end
 
@@ -88,3 +90,5 @@ module GDAL
     end
   end
 end
+
+GDAL::Driver.include(GDAL::Driver::Extensions)

data/lib/gdal/{geo_transform_mixins → extensions/geo_transform}/extensions.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'json'
-require_relative '../exceptions'
+require 'gdal/exceptions'
+require 'gdal/geo_transform'
 
 module GDAL
-  module GeoTransformMixins
+  class GeoTransform
     module Extensions
       # @param base [Class,Module]
       def self.included(base)
@@ -17,8 +17,8 @@ module GDAL
         # pixel dimensions. Assumes north-up.
         #
         # @param envelope [OGR::Envelope]
-        # @param raster_width [Fixnum]
-        # @param raster_height [Fixnum]
+        # @param raster_width [Integer]
+        # @param raster_height [Integer]
         def new_from_envelope(envelope, raster_width, raster_height)
           gt = GDAL::GeoTransform.new
           gt.x_origin = envelope.x_min
@@ -35,7 +35,7 @@ module GDAL
       #
       # @param x_geo [Number]
       # @param y_geo [Number]
-      # @return [Hash{pixel => Fixnum, line Fixnum}]
+      # @return [Hash{pixel => Integer, line Integer}]
       def world_to_pixel(x_geo, y_geo)
         pixel = world_to_x_pixel(x_geo)
         line = world_to_y_pixel(y_geo)
@@ -47,7 +47,7 @@ module GDAL
       # +x_geo+ coordinate.
       #
       # @param x_geo [Number]
-      # @return [Fixnum]
+      # @return [Integer]
       # @raise [GDAL::InvalidGeoTransform] if {GDAL::GeoTransform#pixel_width}
       #   is 0.
       def world_to_x_pixel(x_geo)
@@ -62,7 +62,7 @@ module GDAL
       # coordinate.
       #
       # @param y_geo [Number]
-      # @return [Fixnum]
+      # @return [Integer]
       # @raise [GDAL::InvalidGeoTransform] if {GDAL::GeoTransform#pixel_height}
       #   is 0.
       def world_to_y_pixel(y_geo)
@@ -95,3 +95,5 @@ module GDAL
     end
   end
 end
+
+GDAL::GeoTransform.include(GDAL::GeoTransform::Extensions)

data/lib/gdal/{gridder → extensions/gridder}/point_extracting.rb

@@ -10,7 +10,7 @@ module GDAL
       # really just indented for internal use, but is being left public just in
       # case it serves some benefit for debugging.
       #
-      # @return [NArray]
+      # @return [Array<Array>]
       def points
         return @points if @points
 
@@ -30,7 +30,7 @@ module GDAL
 
       private
 
-      # Checks to make sure that a) if an input_field_name option was give, that
+      # Checks to make sure that a) if an input_field_name option was given, that
       # the layer actually has that field, or b) that the layer has Z values set.
       # Without one of these two things, there's no values to pass along to
       # interpolate.
@@ -42,10 +42,12 @@ module GDAL
       def ensure_z_values
         if layer_missing_specified_field?
           raise OGR::InvalidFieldName, "Field name not found in layer: '#{@options.input_field_name}'"
-        elsif !@options.input_field_name && !@source_layer.any_geometries_with_z?
-          raise GDAL::NoValuesToGrid,
-            "No input_field_name option given and source layer #{@source_layer.name} has no Z values."
         end
+
+        return unless !@options.input_field_name && !@source_layer.any_geometries_with_z?
+
+        raise GDAL::NoValuesToGrid,
+              "No input_field_name option given and source layer #{@source_layer.name} has no Z values."
       end
 
       # @param layer [OGR::Layer] The layer from which to extract point values.