Class: GDAL::Driver

Inherits:
Object
  • Object
show all
Includes:
Extensions, Logger, MajorObject
Defined in:
lib/gdal/driver.rb,
lib/gdal/extensions/driver/extensions.rb

Overview

Wrapper for GDAL drivers (aka “formats”). Useful for opening and working with GDAL datasets.

Defined Under Namespace

Modules: Extensions

Constant Summary collapse

GDAL_DOCS_URL = 
"http://gdal.org"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Extensions

#can_copy_datasets?, #can_create_datasets?, #can_do_rasters?, #can_do_vectors?, #can_do_virtual_io?, #can_open_datasets?, #capabilities, included

Methods included from MajorObject

#all_metadata, #description, #metadata, #metadata_domain_list, #metadata_item, #null?, #set_metadata_item

Constructor Details

#initialize(driver) ⇒ Driver

Returns a new instance of Driver.

Parameters:



57
58
59
 
# File 'lib/gdal/driver.rb', line 57

def initialize(driver)
  @c_pointer = GDAL._pointer(GDAL::Driver, driver, autorelease: false)
end

Instance Attribute Details

#c_pointer ⇒ Object (readonly)

Returns the value of attribute c_pointer.



54
55
56
 
# File 'lib/gdal/driver.rb', line 54

def c_pointer
  @c_pointer
end

Class Method Details

.at_index(index) ⇒ GDAL::Driver

Parameters:

  • index (Integer) —

    Index of the registered driver. Must be less than GDAL::Driver.count.

Returns:

Raises:



37
38
39
40
41
42
43
 
# File 'lib/gdal/driver.rb', line 37

def self.at_index(index)
  raise InvalidDriverIndex, "index must be between 0 and #{count - 1}." if index > count

  driver_ptr = FFI::GDAL::GDAL.GDALGetDriver(index)

  new(driver_ptr)
end

.by_name(name) ⇒ GDAL::Driver

Parameters:

  • name (String) —

    Short name of the registered GDALDriver.

Returns:

Raises:



25
26
27
28
29
30
31
 
# File 'lib/gdal/driver.rb', line 25

def self.by_name(name)
  driver_ptr = FFI::GDAL::GDAL.GDALGetDriverByName(name)

  raise InvalidDriverName, "'#{name}' is not a valid driver name." if driver_ptr.null?

  new(driver_ptr)
end

.count ⇒ Integer

Returns:



17
18
19
 
# File 'lib/gdal/driver.rb', line 17

def self.count
  FFI::GDAL::GDAL.GDALGetDriverCount
end

.identify_driver(file_path) ⇒ GDAL::Driver

Returns nil if the file is unsupported.

Parameters:

  • file_path (String) —

    File to get the driver for.

Returns:

  • (GDAL::Driver) —

    Returns nil if the file is unsupported.



47
48
49
50
51
52
 
# File 'lib/gdal/driver.rb', line 47

def self.identify_driver(file_path)
  driver_ptr = FFI::GDAL::GDAL.GDALIdentifyDriver(::File.expand_path(file_path), nil)
  return nil if driver_ptr.null?

  new(driver_ptr)
end

Instance Method Details

#copy_dataset(source_dataset, destination_path, progress_block = nil, progress_arg = nil, strict: true, **options) {|destination_dataset| ... } ⇒ true

Copies source_dataset to destination_path. Will yield a writable GDAL::Driver.{GDAL{GDAL::Dataset} of the destination dataset then close it if a block is given.

Parameters:

  • source_dataset (GDAL::Dataset, FFI::Pointer) —

    The dataset to copy.

  • destination_path (String) —

    The name for the new dataset file.

  • strict (Boolean) (defaults to: true) —

    false indicates the copy may adapt as needed for the output format.

  • options (Hash)
  • progress_block (Proc, FFI::GDAL::GDAL.GDALProgressFunc) (defaults to: nil) —

    For outputting copy progress. Conforms to the FFI::GDAL::GDAL.GDALProgressFunc signature.

  • progress_arg (Proc) (defaults to: nil)

Yield Parameters:

Returns:

  • (true)

Raises:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/gdal/driver.rb', line 187

def copy_dataset(source_dataset, destination_path, progress_block = nil, progress_arg = nil, strict: true,
  **options)
  source_dataset_ptr = make_dataset_pointer(source_dataset)
  raise GDAL::OpenFailure, "Source dataset couldn't be read" if source_dataset_ptr&.null?

  options_ptr = GDAL::Options.pointer(options)

  destination_dataset_ptr = FFI::GDAL::GDAL.GDALCreateCopy(
    @c_pointer,
    destination_path,
    source_dataset_ptr,
    strict,
    options_ptr,
    progress_block,
    progress_arg
  )

  raise CreateFail if destination_dataset_ptr.nil? || destination_dataset_ptr.null?

  if block_given?
    dataset = Dataset.new(destination_dataset_ptr, "w")
    yield(dataset)
    dataset.close
  end

  true
end

#copy_dataset_files(old_name, new_name) ⇒ Object

Copy all of the associated files of a dataset from one file to another.

Parameters:

Returns:

  • true on success, false on warning.

Raises:



126
127
128
129
130
 
# File 'lib/gdal/driver.rb', line 126

def copy_dataset_files(old_name, new_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_dataset(filename, x_size, y_size, band_count: 1, data_type: :GDT_Byte, **options) ⇒ GDAL::Dataset

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!

Parameters:

Returns:

  • (GDAL::Dataset) —

    If no block is given, returns the open (writable) dataset; you’ll need to close it. If a block is given, returns the result of the block.

Raises:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/gdal/driver.rb', line 144

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::GDAL.GDALCreate(
    @c_pointer,
    filename,
    x_size,
    y_size,
    band_count,
    data_type,
    options_pointer
  )

  raise CreateFail if dataset_pointer.null?

  dataset = GDAL::Dataset.new(dataset_pointer, "w")

  if block_given?
    result = yield(dataset)
    dataset.close

    result
  else
    dataset
  end
end

#creation_option_list ⇒ Array

Lists and describes the options that can be used when calling GDAL::Dataset.create or GDAL::Dataset.create_copy.

Returns:

  • (Array) 


92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/gdal/driver.rb', line 92

def creation_option_list
  return [] unless @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"]
  return [] if list.nil? || list.empty?

  list["Option"]
end

#delete_dataset(file_name) ⇒ Object

Delete the dataset represented by file_name. Depending on the driver, this could mean deleting associated files, database objects, etc.

Parameters:

Raises:



220
221
222
223
224
 
# File 'lib/gdal/driver.rb', line 220

def delete_dataset(file_name)
  GDAL::CPLErrorHandler.manually_handle("Unable to delete dataset: #{file_name}") do
    FFI::GDAL::GDAL.GDALDeleteDataset(@c_pointer, file_name)
  end
end

#help_topic ⇒ String

Returns:



80
81
82
83
84
85
86
 
# File 'lib/gdal/driver.rb', line 80

def help_topic
  # 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

#long_name ⇒ String

Returns:



71
72
73
74
75
76
77
 
# File 'lib/gdal/driver.rb', line 71

def long_name
  # 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

#rename_dataset(old_name, new_name) ⇒ Object

Parameters:

Raises:



229
230
231
232
233
 
# File 'lib/gdal/driver.rb', line 229

def rename_dataset(old_name, new_name)
  GDAL::CPLErrorHandler.manually_handle("Unable to rename dataset: #{old_name}") do
    FFI::GDAL::GDAL.GDALRenameDataset(@c_pointer, new_name, old_name)
  end
end

#short_name ⇒ String

Returns:



62
63
64
65
66
67
68
 
# File 'lib/gdal/driver.rb', line 62

def short_name
  # 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

#validate_creation_options(options) ⇒ Boolean

Parameters:

  • options (Hash)

Returns:

  • (Boolean) 


110
111
112
113
114
115
116
117
118
 
# File 'lib/gdal/driver.rb', line 110

def validate_creation_options(options)
  options_pointer = if options.is_a? GDAL::Options
                      options.c_pointer
                    else
                      GDAL::Options.pointer(options)
                    end

  FFI::GDAL::GDAL.GDALValidateCreationOptions(@c_pointer, options_pointer)
end