ffi-gdal 1.0.3 → 1.1.0

data/lib/gdal/utils/dem.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "dem/options"
+
+module GDAL
+  module Utils
+    # Wrapper for gdaldem using GDALDEMProcessing C API.
+    #
+    # @see https://gdal.org/programs/gdaldem.html gdaldem utility documentation.
+    # @see https://gdal.org/api/gdal_utils.html#_CPPv417GDALDEMProcessingPKc12GDALDatasetHPKcPKcPK24GDALDEMProcessingOptionsPi
+    #   GDALDEMProcessing C API.
+    class DEM
+      # Perform the gdaldem (GDALDEMProcessing) operation.
+      #
+      # @example Create a raster dataset.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #
+      #   dataset = GDAL::Utils::DEM.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     processing: "hillshade"
+      #   )
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Create a raster dataset for color-relief.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #
+      #   dataset = GDAL::Utils::DEM.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     processing: "color-relief",
+      #     color_filename: "color.txt"
+      #   )
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Create a raster dataset with options.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   options = GDAL::Utils::DEM::Options.new(options: ["-of", "GTiff", "-co", "TILED=YES"])
+      #
+      #   dataset = GDAL::Utils::DEM.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     processing: "hillshade",
+      #     options: options
+      #   )
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Create a raster dataset using block syntax.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #
+      #   GDAL::Utils::DEM.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     processing: "hillshade"
+      #   ) do |dataset|
+      #     # Do something with the dataset.
+      #     puts dataset.raster_x_size
+      #
+      #     # Dataset will be closed automatically.
+      #   end
+      #   src_dataset.close
+      #
+      # @param dst_dataset_path [String] The path to the destination dataset.
+      # @param src_dataset [OGR::DataSource] The source dataset.
+      # @param processing [String] The processing type
+      #   (one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", "Roughness").
+      # @param color_filename [String] color file (mandatory for "color-relief" processing, should be NULL otherwise).
+      # @param options [GDAL::Utils::DEM::Options] Options.
+      # @yield [GDAL::Dataset] The destination dataset.
+      # @return [GDAL::Dataset] The destination dataset (only if block is not specified; dataset must be closed).
+      # @raise [GDAL::Error] If the operation fails.
+      def self.perform(dst_dataset_path:, src_dataset:, processing:, color_filename: nil, options: Options.new, &block)
+        result_code_ptr = ::FFI::MemoryPointer.new(:int)
+        dst_dataset_ptr = ::FFI::GDAL::Utils.GDALDEMProcessing(
+          dst_dataset_path,
+          src_dataset.c_pointer,
+          processing,
+          color_filename,
+          options.c_pointer,
+          result_code_ptr
+        )
+        success = result_code_ptr.read_int.zero?
+
+        raise ::GDAL::Error, "GDALDEMProcessing failed." if dst_dataset_ptr.null? || !success
+
+        ::GDAL::Dataset.open(dst_dataset_ptr, "w", &block)
+      end
+    end
+  end
+end

data/lib/gdal/utils/grid/options.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    class Grid
+      # Ruby wrapper for GDALGridOptions C API (options for gdal_grid utility).
+      #
+      # @see GDAL::Utils::Grid
+      # @see https://gdal.org/programs/gdal_grid.html gdal_grid utility documentation.
+      class Options
+        # @private
+        class AutoPointer < ::FFI::AutoPointer
+          # @param pointer [FFI::Pointer]
+          def self.release(pointer)
+            return unless pointer && !pointer.null?
+
+            ::FFI::GDAL::Utils.GDALGridOptionsFree(pointer)
+          end
+        end
+
+        # @return [AutoPointer] C pointer to the GDALGridOptions.
+        attr_reader :c_pointer
+
+        # @return [Array<String>] The options.
+        attr_reader :options
+
+        # Create a new instance.
+        #
+        # @see https://gdal.org/programs/gdal_grid.html
+        #   List of available options could be found in gdal_grid utility documentation.
+        #
+        # @example Create a new instance.
+        #  options = GDAL::Utils::Grid::Options.new(options: ["-of", "GTiff", "-outsize", "10", "10"])
+        #
+        # @param options [Array<String>] The options list.
+        def initialize(options: [])
+          @options = options
+          @string_list = ::GDAL::Utils::Helpers::StringList.new(strings: options)
+          @c_pointer = AutoPointer.new(options_pointer)
+        end
+
+        private
+
+        attr_reader :string_list
+
+        def options_pointer
+          ::FFI::GDAL::Utils.GDALGridOptionsNew(string_list.c_pointer, nil)
+        end
+      end
+    end
+  end
+end

data/lib/gdal/utils/grid.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "grid/options"
+
+module GDAL
+  module Utils
+    # Wrapper for gdal_grid using GDALGrid C API.
+    #
+    # @see https://gdal.org/programs/gdal_grid.html gdal_grid utility documentation.
+    # @see https://gdal.org/api/gdal_utils.html#_CPPv48GDALGridPKc12GDALDatasetHPK15GDALGridOptionsPi GDALGrid C API.
+    class Grid
+      # Perform the gdal_grid (GDALGrid) operation.
+      #
+      # @example Create a raster dataset.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   dataset = GDAL::Utils::Grid.perform(dst_dataset_path: "destination.tif", src_dataset: src_dataset)
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Create a raster dataset with options.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   dataset = GDAL::Utils::Grid.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     options: GDAL::Utils::Grid::Options.new(options: ["-of", "GTiff", "-co", "COMPRESS=DEFLATE"])
+      #   )
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Create a raster dataset using block syntax.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   GDAL::Utils::Grid.perform(dst_dataset_path: "destination.tif", src_dataset: src_dataset) do |dataset|
+      #     # Do something with the dataset.
+      #     puts dataset.raster_x_size
+      #
+      #     # Dataset will be closed automatically.
+      #   end
+      #   src_dataset.close
+      #
+      # @param dst_dataset_path [String] The path to the destination dataset.
+      # @param src_dataset [OGR::DataSource] The source dataset.
+      # @param options [GDAL::Utils::Grid::Options] Options.
+      # @yield [GDAL::Dataset] The destination dataset.
+      # @return [GDAL::Dataset] The destination dataset (only if block is not specified; dataset must be closed).
+      # @raise [GDAL::Error] If the operation fails.
+      def self.perform(dst_dataset_path:, src_dataset:, options: Options.new, &block)
+        result_code_ptr = ::FFI::MemoryPointer.new(:int)
+        dst_dataset_ptr = ::FFI::GDAL::Utils.GDALGrid(
+          dst_dataset_path,
+          src_dataset.c_pointer,
+          options.c_pointer,
+          result_code_ptr
+        )
+        success = result_code_ptr.read_int.zero?
+
+        raise ::GDAL::Error, "GDALGrid failed." if dst_dataset_ptr.null? || !success
+
+        ::GDAL::Dataset.open(dst_dataset_ptr, "w", &block)
+      end
+    end
+  end
+end

data/lib/gdal/utils/helpers/dataset_list.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    module Helpers
+      # A basic wrapper for C Array of dataset handlers (e.g. GDALDatasetH *pahSrcDS).
+      #
+      # @private
+      # @note This class is intended only to be used internally in ffi-gdal. It's API may change.
+      #   Do not use this class directly.
+      class DatasetList
+        # @return [FFI::Pointer] C pointer to the Array of dataset handlers (e.g. GDALDatasetH *pahSrcDS).
+        attr_reader :c_pointer
+
+        # @return [Array<GDAL::Dataset>] List of datasets.
+        attr_reader :datasets
+
+        # @param datasets [Array<GDAL::Dataset>] List of datasets.
+        def initialize(datasets: [])
+          @datasets = datasets
+          @c_pointer = datasets_pointer
+        end
+
+        # @return [Integer] The number of datasets in the list.
+        def count
+          dataset_pointers.count
+        end
+
+        private
+
+        def dataset_pointers
+          @dataset_pointers ||= datasets.map(&:c_pointer)
+        end
+
+        def datasets_pointer
+          ::FFI::MemoryPointer
+            .new(:pointer, count)
+            .write_array_of_pointer(dataset_pointers)
+        end
+      end
+    end
+  end
+end

data/lib/gdal/utils/helpers/string_list.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    module Helpers
+      # A basic wrapper for CPLStringList (e.g. char **papszArgv).
+      #
+      # @private
+      # @note This class is intended only to be used internally in ffi-gdal. It's API may change.
+      #   Do not use this class directly.
+      class StringList
+        class AutoPointer < ::FFI::AutoPointer
+          # @param pointer [FFI::Pointer]
+          def self.release(pointer)
+            return unless pointer && !pointer.null?
+
+            ::FFI::CPL::String.CSLDestroy(pointer)
+          end
+        end
+
+        # @return [FFI::Pointer] C pointer to CPLStringList (e.g. char **papszArgv).
+        attr_reader :c_pointer
+
+        # @return [Array<String>] Strings in the list.
+        attr_reader :strings
+
+        # @param strings [Array<String>] Strings to build the list.
+        def initialize(strings: [])
+          @strings = strings
+          @c_pointer = AutoPointer.new(string_list_pointer)
+        end
+
+        private
+
+        def string_list_pointer
+          pointer = ::FFI::Pointer.new(FFI::Pointer::NULL)
+
+          strings.each do |string|
+            pointer = ::FFI::CPL::String.CSLAddString(pointer, string.to_s)
+          end
+
+          pointer
+        end
+      end
+    end
+  end
+end

data/lib/gdal/utils/helpers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    # Internal helpers for GDAL Utils.
+    module Helpers
+      autoload :DatasetList, File.expand_path("helpers/dataset_list", __dir__)
+      autoload :StringList, File.expand_path("helpers/string_list", __dir__)
+    end
+  end
+end

data/lib/gdal/utils/info/options.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    class Info
+      # Ruby wrapper for GDALInfoOptions C API (options for gdalinfo utility).
+      #
+      # @see GDAL::Utils::Info
+      # @see https://gdal.org/programs/gdalinfo.html gdalinfo utility documentation.
+      class Options
+        # @private
+        class AutoPointer < ::FFI::AutoPointer
+          # @param pointer [FFI::Pointer]
+          def self.release(pointer)
+            return unless pointer && !pointer.null?
+
+            ::FFI::GDAL::Utils.GDALInfoOptionsFree(pointer)
+          end
+        end
+
+        # @return [AutoPointer] C pointer to the GDALInfoOptions.
+        attr_reader :c_pointer
+
+        # @return [Array<String>] The options.
+        attr_reader :options
+
+        # Create a new instance.
+        #
+        # @see https://gdal.org/programs/gdalinfo.html
+        #   List of available options could be found in gdalinfo utility documentation.
+        #
+        # @example Create a new instance.
+        #  options = GDAL::Utils::Info::Options.new(options: ["-json", "-mdd", "all"])
+        #
+        # @param options [Array<String>] The options list.
+        def initialize(options: [])
+          @options = options
+          @string_list = ::GDAL::Utils::Helpers::StringList.new(strings: options)
+          @c_pointer = AutoPointer.new(options_pointer)
+        end
+
+        private
+
+        attr_reader :string_list
+
+        def options_pointer
+          ::FFI::GDAL::Utils.GDALInfoOptionsNew(string_list.c_pointer, nil)
+        end
+      end
+    end
+  end
+end

data/lib/gdal/utils/info.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "info/options"
+
+module GDAL
+  module Utils
+    # Wrapper for gdalinfo using GDALInfo C API.
+    #
+    # @see https://gdal.org/programs/gdalinfo.html gdalinfo utility documentation.
+    # @see https://gdal.org/api/gdal_utils.html#_CPPv48GDALInfo12GDALDatasetHPK15GDALInfoOptions GDALInfo C API.
+    class Info
+      # Perform the gdalinfo (GDALInfo) operation.
+      #
+      # @example Get info for a dataset.
+      #   dataset = GDAL::Dataset.open("my.tif", "r")
+      #   info = GDAL::Utils::Info.perform(dataset: dataset)
+      #   dataset.close
+      #
+      # @example Get info for a dataset with options.
+      #   dataset = GDAL::Dataset.open("my.tif", "r")
+      #   info = GDAL::Utils::Info.perform(
+      #     dataset: dataset,
+      #     options: GDAL::Utils::Info::Options.new(options: ["-json", "-mdd", "all"])
+      #   )
+      #   dataset.close
+      #
+      # @param dataset [GDAL::Dataset] The dataset to get info for.
+      # @param options [GDAL::Utils::Info::Options] Options.
+      # @return [String] The info string.
+      def self.perform(dataset:, options: Options.new)
+        string, str_pointer = ::FFI::GDAL::Utils.GDALInfo(dataset.c_pointer, options.c_pointer)
+
+        string
+      ensure
+        # Returned string pointer must be freed with CPLFree().
+        ::FFI::CPL::VSI.VSIFree(str_pointer)
+      end
+    end
+  end
+end

data/lib/gdal/utils/nearblack/options.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    class Nearblack
+      # Ruby wrapper for GDALNearblackOptions C API (options for nearblack utility).
+      #
+      # @see GDAL::Utils::Nearblack
+      # @see https://gdal.org/programs/nearblack.html nearblack utility documentation.
+      class Options
+        # @private
+        class AutoPointer < ::FFI::AutoPointer
+          # @param pointer [FFI::Pointer]
+          def self.release(pointer)
+            return unless pointer && !pointer.null?
+
+            ::FFI::GDAL::Utils.GDALNearblackOptionsFree(pointer)
+          end
+        end
+
+        # @return [AutoPointer] C pointer to the GDALNearblackOptions.
+        attr_reader :c_pointer
+
+        # @return [Array<String>] The options.
+        attr_reader :options
+
+        # Create a new instance.
+        #
+        # @see https://gdal.org/programs/nearblack.html
+        #   List of available options could be found in nearblack utility documentation.
+        #
+        # @example Create a new instance.
+        #  options = GDAL::Utils::Nearblack::Options.new(options: ["-of", "GTiff", "-near", "10"])
+        #
+        # @param options [Array<String>] The options list.
+        def initialize(options: [])
+          @options = options
+          @string_list = ::GDAL::Utils::Helpers::StringList.new(strings: options)
+          @c_pointer = AutoPointer.new(options_pointer)
+        end
+
+        private
+
+        attr_reader :string_list
+
+        def options_pointer
+          ::FFI::GDAL::Utils.GDALNearblackOptionsNew(string_list.c_pointer, nil)
+        end
+      end
+    end
+  end
+end

data/lib/gdal/utils/nearblack.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "nearblack/options"
+
+module GDAL
+  module Utils
+    # Wrapper for nearblack using GDALNearblack C API.
+    #
+    # @see https://gdal.org/programs/nearblack.html nearblack utility documentation.
+    # @see https://gdal.org/api/gdal_utils.html#_CPPv413GDALNearblackPKc12GDALDatasetH12GDALDatasetHPK20GDALNearblackOptionsPi
+    #   GDALNearblack C API.
+    class Nearblack
+      # Perform the nearblack (GDALNearblack) operation.
+      #
+      # @example Perform nearblack on dataset (for dst_dataset_path).
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #
+      #   dataset = GDAL::Utils::Nearblack.perform(dst_dataset_path: "destination.tif", src_dataset: src_dataset)
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Perform nearblack on dataset with options (for dst_dataset_path).
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   options = GDAL::Utils::Nearblack::Options.new(options: ["-near", "10"])
+      #
+      #   dataset = GDAL::Utils::Nearblack.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     options: options
+      #   )
+      #
+      #   # Do something with the dataset.
+      #   puts dataset.raster_x_size
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dataset.close
+      #   src_dataset.close
+      #
+      # @example Perform nearblack on dataset (for dst_dataset_path) using block syntax.
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   options = GDAL::Utils::Nearblack::Options.new(options: ["-near", "10"])
+      #
+      #   GDAL::Utils::Nearblack.perform(
+      #     dst_dataset_path: "destination.tif",
+      #     src_dataset: src_dataset,
+      #     options: options
+      #   ) do |dataset|
+      #     # Do something with the dataset.
+      #     puts dataset.raster_x_size
+      #
+      #     # Dataset will be closed automatically.
+      #   end
+      #   src_dataset.close
+      #
+      # @example Perform nearblack on dataset (for dst_dataset).
+      #   src_dataset = GDAL::Dataset.open("source.tif", "r")
+      #   dst_dataset = GDAL::Dataset.open("destination.tif", "w")
+      #
+      #   GDAL::Utils::Nearblack.perform(dst_dataset: dst_dataset, src_dataset: src_dataset)
+      #
+      #   # You must close the dataset when you are done with it.
+      #   dst_dataset.close
+      #   src_dataset.close
+      #
+      # @param dst_dataset_path [String] The path to the destination dataset.
+      # @param dst_dataset [GDAL::Dataset] The destination dataset.
+      # @param src_dataset [GDAL::Dataset] The source dataset.
+      # @param options [GDAL::Utils::Nearblack::Options] Options.
+      # @yield [GDAL::Dataset] The destination dataset.
+      # @return [GDAL::Dataset] The destination dataset (only if block is not specified; dataset must be closed).
+      def self.perform(src_dataset:, dst_dataset: nil, dst_dataset_path: nil, options: Options.new, &block)
+        if dst_dataset
+          for_dataset(dst_dataset: dst_dataset, src_dataset: src_dataset, options: options)
+        else
+          for_dataset_path(dst_dataset_path: dst_dataset_path, src_dataset: src_dataset, options: options, &block)
+        end
+      end
+
+      def self.for_dataset(dst_dataset:, src_dataset:, options: Options.new)
+        result_dataset_ptr(dst_dataset: dst_dataset, src_dataset: src_dataset, options: options)
+
+        # Return the input dataset as the output dataset (dataset is modified in place).
+        dst_dataset
+      end
+      private_class_method :for_dataset
+
+      def self.for_dataset_path(dst_dataset_path:, src_dataset:, options: Options.new, &block)
+        dst_dataset_ptr = result_dataset_ptr(
+          dst_dataset_path: dst_dataset_path, src_dataset: src_dataset, options: options
+        )
+
+        ::GDAL::Dataset.open(dst_dataset_ptr, "w", &block)
+      end
+      private_class_method :for_dataset_path
+
+      def self.result_dataset_ptr(src_dataset:, dst_dataset_path: nil, dst_dataset: nil, options: Options.new)
+        result_code_ptr = ::FFI::MemoryPointer.new(:int)
+        dst_dataset_ptr = ::FFI::GDAL::Utils.GDALNearblack(
+          dst_dataset_path,
+          dst_dataset&.c_pointer,
+          src_dataset.c_pointer,
+          options.c_pointer,
+          result_code_ptr
+        )
+        success = result_code_ptr.read_int.zero?
+
+        raise ::GDAL::Error, "GDALNearblack failed." if dst_dataset_ptr.null? || !success
+
+        dst_dataset_ptr
+      end
+      private_class_method :result_dataset_ptr
+    end
+  end
+end

data/lib/gdal/utils/rasterize/options.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GDAL
+  module Utils
+    class Rasterize
+      # Ruby wrapper for GDALRasterizeOptions C API (options for gdal_rasterize utility).
+      #
+      # @see GDAL::Utils::Rasterize
+      # @see https://gdal.org/programs/gdal_rasterize.html gdal_rasterize utility documentation.
+      class Options
+        # @private
+        class AutoPointer < ::FFI::AutoPointer
+          # @param pointer [FFI::Pointer]
+          def self.release(pointer)
+            return unless pointer && !pointer.null?
+
+            ::FFI::GDAL::Utils.GDALRasterizeOptionsFree(pointer)
+          end
+        end
+
+        # @return [AutoPointer] C pointer to the GDALRasterizeOptions.
+        attr_reader :c_pointer
+
+        # @return [Array<String>] The options.
+        attr_reader :options
+
+        # Create a new instance.
+        #
+        # @see https://gdal.org/programs/gdal_rasterize.html
+        #   List of available options could be found in gdal_rasterize utility documentation.
+        #
+        # @example Create a new instance.
+        #  options = GDAL::Utils::Rasterize::Options.new(options: ["-of", "GTiff", "-ts", "10", "10"])
+        #
+        # @param options [Array<String>] The options list.
+        def initialize(options: [])
+          @options = options
+          @string_list = ::GDAL::Utils::Helpers::StringList.new(strings: options)
+          @c_pointer = AutoPointer.new(options_pointer)
+        end
+
+        private
+
+        attr_reader :string_list
+
+        def options_pointer
+          ::FFI::GDAL::Utils.GDALRasterizeOptionsNew(string_list.c_pointer, nil)
+        end
+      end
+    end
+  end
+end