Module: GDAL::Dataset::RasterBandMethods

Included in:
GDAL::Dataset
Defined in:
lib/gdal/dataset/raster_band_methods.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.parse_mask_flag_symbols(*flags) ⇒ Integer

Lets you pass in :GMF_ symbols that represent mask band flags and bitwise ors them.

Parameters:

  • flags (Symbol)

Returns:



13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 13

def self.parse_mask_flag_symbols(*flags)
  flags.reduce(0) do |result, flag|
    result | case flag
             when :GMF_ALL_VALID then 0x01
             when :GMF_PER_DATASET then 0x02
             when :GMF_PER_ALPHA then 0x04
             when :GMF_NODATA then 0x08
             else 0
             end
  end
end

.valid_min_buffer_size(buffer_data_type, x_buffer_size, y_buffer_size) ⇒ Integer

Parameters:

Returns:



29
30
31
32
33
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 29

def self.valid_min_buffer_size(buffer_data_type, x_buffer_size, y_buffer_size)
  data_type_bytes = GDAL::DataType.size(buffer_data_type) / 8

  data_type_bytes * x_buffer_size * y_buffer_size
end

Instance Method Details

#add_band(type, **options) ⇒ GDAL::RasterBand?

Parameters:

Returns:

Raises:



73
74
75
76
77
78
79
80
81
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 73

def add_band(type, **options)
  options_ptr = GDAL::Options.pointer(options)

  GDAL::CPLErrorHandler.manually_handle("Unable to add band") do
    FFI::GDAL::GDAL.GDALAddBand(@c_pointer, type, options_ptr)
  end

  raster_band(raster_count)
end

#create_mask_band(*flags) ⇒ Object

Adds a mask band to the dataset.

Parameters:

  • flags (Array<Symbol>, Symbol) —

    Any of the :GMF symbols.

Raises:



87
88
89
90
91
92
93
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 87

def create_mask_band(*flags)
  flag_value = RasterBandMethods.parse_mask_flag_symbols(flags)

  GDAL::CPLErrorHandler.manually_handle("Unable to create Dataset mask band") do
    FFI::GDAL::GDAL.GDALCreateDatasetMaskBand(@c_pointer, flag_value)
  end
end

#raster_band(raster_index) ⇒ GDAL::RasterBand

Parameters:

Returns:



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 58

def raster_band(raster_index)
  if raster_index > raster_count
    raise GDAL::InvalidRasterBand, "Invalid raster band number '#{raster_index}'. Must be <= #{raster_count}"
  end

  raster_band_ptr = FFI::GDAL::GDAL.GDALGetRasterBand(@c_pointer, raster_index)
  raster_band_ptr.autorelease = false

  GDAL::RasterBand.new(raster_band_ptr, self)
end

#raster_count ⇒ Integer

Returns:



50
51
52
53
54
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 50

def raster_count
  return 0 if null?

  FFI::GDAL::GDAL.GDALGetRasterCount(@c_pointer)
end

#raster_io(access_flag, buffer = nil, x_size: nil, y_size: nil, x_offset: 0, y_offset: 0, buffer_x_size: nil, buffer_y_size: nil, buffer_data_type: nil, band_numbers: nil, pixel_space: 0, line_space: 0, band_space: 0) ⇒ FFI::MemoryPointer

rubocop:disable Metrics/ParameterLists

Parameters:

  • access_flag (String) —

    ‘r’ or ‘w’.

  • buffer (FFI::MemoryPointer) (defaults to: nil) —

    The pointer to the data to read/write to the dataset.

  • x_size (Integer) (defaults to: nil) —

    If not given, uses GDAL::Dataset::RasterBandMethods.{{#raster_x_size}.

  • y_size (Integer) (defaults to: nil) —

    If not given, uses GDAL::Dataset::RasterBandMethods.{{#raster_y_size}.

  • x_offset (Integer) (defaults to: 0) —

    The pixel number in the line to start operating on. Note that when using this, x_size - x_offset should be >= 0, otherwise this means you’re telling the method to read past the end of the line. Defaults to 0.

  • y_offset (Integer) (defaults to: 0) —

    The line number to start operating on. Note that when using this, y_size - y_offset should be >= 0, otherwise this means you’re telling the method to read more lines than the raster has. Defaults to 0.

  • buffer_x_size (Integer) (defaults to: nil) —

    The width of the buffer image in which to read/write the raster data into/from. Typically this should be the same size as x_size; if it’s different, GDAL will resample accordingly.

  • buffer_y_size (Integer) (defaults to: nil) —

    The height of the buffer image in which to read/write the raster data into/from. Typically this should be the same size as y_size; if it’s different, GDAL will resample accordingly.

  • buffer_data_type (FFI::GDAL::GDAL::DataType) (defaults to: nil) —

    Can be used to convert the data to a different type. You must account for this when reading/writing to/from your buffer–your buffer size must be buffer_x_size * buffer_y_size.

  • band_numbers (Array<Integer>) (defaults to: nil) —

    The numbers of the bands to do IO on. Pass nil defaults to choose the first band.

  • pixel_space (Integer) (defaults to: 0) —

    The byte offset from the start of one pixel value in the buffer to the start of the next pixel value within a line. If defaulted (0), the size of buffer_data_type is used.

  • line_space (Integer) (defaults to: 0) —

    The byte offset from the start of one line in the buffer to the start of the next. If defaulted (0), the size of buffer_data_type * +buffer_x_size* is used.

  • band_space (Integer) (defaults to: 0) —

    The byte offset from the start of one band’s data to the start of the next. If defaulted (0), the size of line_space * +buffer_y_size* is used.

Returns:

  • (FFI::MemoryPointer) —

    The buffer that was passed in.

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
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
170
171
172
173
174
175
176
177
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 132

def raster_io(access_flag, buffer = nil,
  x_size: nil, y_size: nil, x_offset: 0, y_offset: 0,
  buffer_x_size: nil, buffer_y_size: nil, buffer_data_type: nil,
  band_numbers: nil,
  pixel_space: 0, line_space: 0, band_space: 0)
  x_size ||= raster_x_size
  y_size ||= raster_y_size
  buffer_x_size ||= x_size
  buffer_y_size ||= y_size
  buffer_data_type ||= raster_band(1).data_type

  band_numbers_ptr, band_count = InternalFunctions.band_numbers_args(band_numbers)
  band_count = raster_count if band_count.zero?

  buffer ||= GDAL._pointer_from_data_type(buffer_data_type, buffer_x_size * buffer_y_size * band_count)

  gdal_access_flag = GDAL._gdal_access_flag(access_flag)

  min_buffer_size = RasterBandMethods.valid_min_buffer_size(buffer_data_type, buffer_x_size, buffer_y_size)

  unless buffer.size >= min_buffer_size
    raise GDAL::BufferTooSmall, "Buffer size (#{buffer.size}) too small (#{min_buffer_size})"
  end

  GDAL::CPLErrorHandler.manually_handle("Unable to perform raster band IO") do
    FFI::GDAL::GDAL::GDALDatasetRasterIO(
      @c_pointer,                     # hDS
      gdal_access_flag,               # eRWFlag
      x_offset,                       # nXOff
      y_offset,                       # nYOff
      x_size,                         # nXSize
      y_size,                         # nYSize
      buffer,                         # pData
      buffer_x_size,                  # nBufXSize
      buffer_y_size,                  # nBufYSize
      buffer_data_type,               # eBufType
      band_count,                     # nBandCount
      band_numbers_ptr,               # panBandMap (WTH is this?)
      pixel_space,                    # nPixelSpace
      line_space,                     # nLineSpace
      band_space                      # nBandSpace
    )
  end

  buffer
end

#raster_x_size ⇒ Integer?

Returns:



36
37
38
39
40
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 36

def raster_x_size
  return nil if null?

  FFI::GDAL::GDAL.GDALGetRasterXSize(@c_pointer)
end

#raster_y_size ⇒ Integer?

Returns:



43
44
45
46
47
 
# File 'lib/gdal/dataset/raster_band_methods.rb', line 43

def raster_y_size
  return nil if null?

  FFI::GDAL::GDAL.GDALGetRasterYSize(@c_pointer)
end