Class: GDAL::RasterBand

Inherits:
Object
  • Object
show all
Includes:
FFI::GDAL, MajorObject
Defined in:
lib/ffi-gdal/raster_band.rb

Constant Summary

Constants included from FFI::GDAL

FFI::GDAL::ALTER_ALL_FLAG, FFI::GDAL::ALTER_NAME_FLAG, FFI::GDAL::ALTER_TYPE_FLAG, FFI::GDAL::ALTER_WIDTH_PRECISION_FLAG, FFI::GDAL::AppDefined, FFI::GDAL::AssertionFailed, FFI::GDAL::CPLES_BackslashQuotable, FFI::GDAL::CPLES_CSV, FFI::GDAL::CPLES_SQL, FFI::GDAL::CPLES_URL, FFI::GDAL::CPLES_XML, FFI::GDAL::CPLES_XML_BUT_QUOTES, FFI::GDAL::CPLE_WrongFormat, FFI::GDAL::CPLErr, FFI::GDAL::CPLValueType, FFI::GDAL::CPL_ENC_ASCII, FFI::GDAL::CPL_ENC_ISO8859_1, FFI::GDAL::CPL_ENC_LOCALE, FFI::GDAL::CPL_ENC_UCS2, FFI::GDAL::CPL_ENC_UCS4, FFI::GDAL::CPL_ENC_UTF16, FFI::GDAL::CPL_ENC_UTF8, FFI::GDAL::CSLT_ALLOWEMPTYTOKENS, FFI::GDAL::CSLT_HONOURSTRINGS, FFI::GDAL::CSLT_PRESERVEESCAPES, FFI::GDAL::CSLT_PRESERVEQUOTES, FFI::GDAL::CSLT_STRIPENDSPACES, FFI::GDAL::CSLT_STRIPLEADSPACES, FFI::GDAL::FileIO, FFI::GDAL::GDALAccess, FFI::GDAL::GDALAsyncStatusType, FFI::GDAL::GDALColorInterp, FFI::GDAL::GDALDataType, FFI::GDAL::GDALMD_AOP_AREA, FFI::GDAL::GDALMD_AOP_POINT, FFI::GDAL::GDALMD_AREA_OR_POINT, FFI::GDAL::GDALPaletteInterp, FFI::GDAL::GDALRATFieldType, FFI::GDAL::GDALRATFieldUsage, FFI::GDAL::GDALRWFlag, FFI::GDAL::GDALTileOrganization, FFI::GDAL::GDAL_DCAP_CREATE, FFI::GDAL::GDAL_DCAP_CREATECOPY, FFI::GDAL::GDAL_DCAP_OPEN, FFI::GDAL::GDAL_DCAP_RASTER, FFI::GDAL::GDAL_DCAP_VECTOR, FFI::GDAL::GDAL_DCAP_VIRTUALIO, FFI::GDAL::GDAL_DMD_CREATIONDATATYPES, FFI::GDAL::GDAL_DMD_CREATIONOPTIONLIST, FFI::GDAL::GDAL_DMD_EXTENSION, FFI::GDAL::GDAL_DMD_EXTENSIONS, FFI::GDAL::GDAL_DMD_HELPTOPIC, FFI::GDAL::GDAL_DMD_LONGNAME, FFI::GDAL::GDAL_DMD_MIMETYPE, FFI::GDAL::GDAL_DMD_OPTIONLIST, FFI::GDAL::GDAL_DMD_SUBDATASETS, FFI::GDAL::GDAL_DS_LAYER_CREATIONOPTIONLIST, FFI::GDAL::GDAL_OF_ALL, FFI::GDAL::GDAL_OF_RASTER, FFI::GDAL::GDAL_OF_READONLY, FFI::GDAL::GDAL_OF_SHARED, FFI::GDAL::GDAL_OF_UPDATE, FFI::GDAL::GDAL_OF_VECTOR, FFI::GDAL::GDAL_OF_VERBOSE_ERROR, FFI::GDAL::GMF_ALL_VALID, FFI::GDAL::GMF_ALPHA, FFI::GDAL::GMF_NODATA, FFI::GDAL::GMF_PER_DATASET, FFI::GDAL::IllegalArg, FFI::GDAL::NoWriteAccess, FFI::GDAL::None, FFI::GDAL::NotSupported, FFI::GDAL::ODrCCreateDataSource, FFI::GDAL::ODrCDeleteDataSource, FFI::GDAL::ODsCCreateGeomFieldAfterCreateLayer, FFI::GDAL::ODsCCreateLayer, FFI::GDAL::ODsCDeleteLayer, FFI::GDAL::OGRAxisOrientation, FFI::GDAL::OGRDatumType, FFI::GDAL::OGRERR_CORRUPT_DATA, FFI::GDAL::OGRERR_FAILURE, FFI::GDAL::OGRERR_INVALID_HANDLE, FFI::GDAL::OGRERR_NONE, FFI::GDAL::OGRERR_NOT_ENOUGH_DATA, FFI::GDAL::OGRERR_NOT_ENOUGH_MEMORY, FFI::GDAL::OGRERR_UNSUPPORTED_GEOMETRY_TYPE, FFI::GDAL::OGRERR_UNSUPPORTED_OPERATION, FFI::GDAL::OGRERR_UNSUPPORTED_SRS, FFI::GDAL::OGRFieldType, FFI::GDAL::OGRJustification, FFI::GDAL::OGRNullFID, FFI::GDAL::OGRStyleToolClassID, FFI::GDAL::OGRStyleToolParamBrushID, FFI::GDAL::OGRStyleToolParamLabelID, FFI::GDAL::OGRStyleToolParamPenID, FFI::GDAL::OGRStyleToolParamSymbolID, FFI::GDAL::OGRStyleToolUnitsID, FFI::GDAL::OGRUnsetMarker, FFI::GDAL::OGR_Z_MARKER, FFI::GDAL::OGRwkbByteOrder, FFI::GDAL::OGRwkbGeometryType, FFI::GDAL::OGRwkbVariant, FFI::GDAL::OLCAlterFieldDefn, FFI::GDAL::OLCCreateField, FFI::GDAL::OLCCreateGeomField, FFI::GDAL::OLCDeleteFeature, FFI::GDAL::OLCDeleteField, FFI::GDAL::OLCFastFeatureCount, FFI::GDAL::OLCFastGetExtent, FFI::GDAL::OLCFastSetNextByIndex, FFI::GDAL::OLCFastSpatialFilter, FFI::GDAL::OLCIgnoreFields, FFI::GDAL::OLCRandomRead, FFI::GDAL::OLCRandomeWrite, FFI::GDAL::OLCReorderFields, FFI::GDAL::OLCSequentialWrite, FFI::GDAL::OLCStringsAsUTF8, FFI::GDAL::OLCTransactions, FFI::GDAL::ObjectNull, FFI::GDAL::OpenFailed, FFI::GDAL::OutOfMemory, FFI::GDAL::UserInterrupt, FFI::GDAL::VERSION, FFI::GDAL::VSI_STAT_EXISTS_FLAG, FFI::GDAL::VSI_STAT_NATURE_FLAG, FFI::GDAL::VSI_STAT_SIZE_FLAG, FFI::GDAL::WKB_25D_BIT

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from MajorObject

#all_metadata, #description, #description=, #metadata_domain_list, #metadata_for_domain, #metadata_item, #null?

Methods included from FFI::GDAL

#CPLFree, #cpla_assert, find_lib, #gdal_check_version, gdal_library_path, search_paths, #srcval, #validate_pointer0, #validate_pointer1, #validate_pointer_err

Constructor Details

#initialize(dataset, band_id: nil, raster_band_pointer: nil) ⇒ RasterBand

Returns a new instance of RasterBand.

Parameters:

  • dataset (GDAL::Dataset, FFI::Pointer)
  • band_id (Fixnum) (defaults to: nil) —

    Requried if not passing in raster_band_pointer.

  • raster_band_pointer (FFI::Pointer) (defaults to: nil) —

    Requried if not passing in band_id.



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/ffi-gdal/raster_band.rb', line 18

def initialize(dataset, band_id: nil, raster_band_pointer: nil)
  @dataset = if dataset.is_a? GDAL::Dataset
    dataset.c_pointer
  else
    dataset
  end

  @gdal_raster_band = if raster_band_pointer
    raster_band_pointer
  elsif band_id
    GDALGetRasterBand(@dataset, band_id)
  else
    raise 'Must pass in band_id or the raster_band_pointer.'
  end
end

Instance Attribute Details

#dataset ⇒ Object (readonly)

Returns the value of attribute dataset.



12
13
14
 
# File 'lib/ffi-gdal/raster_band.rb', line 12

def dataset
  @dataset
end

Instance Method Details

#access_flag ⇒ Symbol

The type of access to the raster band this object currently has.

Returns:

  • (Symbol) —

    Either :GA_Update or :GA_ReadOnly.



59
60
61
62
63
 
# File 'lib/ffi-gdal/raster_band.rb', line 59

def access_flag
  return nil if null?

  GDALGetRasterAccess(@gdal_raster_band)
end

#arbitrary_overviews? ⇒ Boolean

Returns:

  • (Boolean) 


154
155
156
 
# File 'lib/ffi-gdal/raster_band.rb', line 154

def arbitrary_overviews?
  GDALHasArbitraryOverviews(@gdal_raster_band).zero? ? false : true
end

#band_number ⇒ Fixnum

The number of band within the associated dataset that this band represents.

Returns:



69
70
71
72
73
 
# File 'lib/ffi-gdal/raster_band.rb', line 69

def band_number
  return nil if null?

  GDALGetBandNumber(@gdal_raster_band)
end

#block_size ⇒ Hash{x => Fixnum, y => Fixnum}

The natural block size is the block size that is most efficient for accessing the format. For many formats this is simply a whole scanline in which case x is set to #x_size, and y is set to 1.

Returns:



101
102
103
104
105
106
107
 
# File 'lib/ffi-gdal/raster_band.rb', line 101

def block_size
  x_pointer = FFI::MemoryPointer.new(:int)
  y_pointer = FFI::MemoryPointer.new(:int)
  GDALGetBlockSize(@gdal_raster_band, x_pointer, y_pointer)

  { x: x_pointer.read_int, y: y_pointer.read_int }
end

#c_pointer ⇒ Object 



34
35
36
 
# File 'lib/ffi-gdal/raster_band.rb', line 34

def c_pointer
  @gdal_raster_band
end

#category_names ⇒ Array<String>

Returns:



110
111
112
113
114
115
 
# File 'lib/ffi-gdal/raster_band.rb', line 110

def category_names
  names = GDALGetRasterCategoryNames(@gdal_raster_band)
  return [] if names.null?

  names.get_array_of_string(0)
end

#category_names=(names) ⇒ Array<String>

Parameters:

Returns:



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/ffi-gdal/raster_band.rb', line 119

def category_names=(names)
  str_pointers = names.map do |name|
    FFI::MemoryPointer.from_string(name.to_s)
  end

  str_pointers << nil
  names_pointer = FFI::MemoryPointer.new(:pointer, str_pointers.length)

  str_pointers.each_with_index do |ptr, i|
    names_pointer[i].put_pointer(0, ptr)
  end

  cpl_err = GDALSetRasterCategoryNames(@gdal_raster_band, names_pointer)

  cpl_err.to_ruby(warning: [])
end

#color_interpretation ⇒ Symbol

Returns One of FFI::GDAL::GDALColorInterp.

Returns:

  • (Symbol) —

    One of FFI::GDAL::GDALColorInterp.



76
77
78
 
# File 'lib/ffi-gdal/raster_band.rb', line 76

def color_interpretation
  GDALGetRasterColorInterpretation(@gdal_raster_band)
end

#color_table ⇒ GDAL::ColorTable

Returns:



81
82
83
84
85
86
87
 
# File 'lib/ffi-gdal/raster_band.rb', line 81

def color_table
  gdal_color_table = GDALGetRasterColorTable(@gdal_raster_band)
  return nil if gdal_color_table.null?

  @color_table ||= ColorTable.new(@gdal_raster_band,
    color_table_pointer: gdal_color_table)
end

#compute_min_max ⇒ Array{min => Float, max => Float}

The minimum and maximum values for this band.

Returns:

  • (Array{min => Float, max => Float}) 


524
525
526
527
528
529
530
531
532
533
534
 
# File 'lib/ffi-gdal/raster_band.rb', line 524

def compute_min_max
  @min_max = if minimum_value[:value] && maximum_value[:value]
    min_max = FFI::MemoryPointer.new(:double, 2)
    min_max.put_array_of_double 0, [minimum_value[:value], maximum_value[:value]]
    GDALComputeRasterMinMax(@gdal_raster_band, 1, min_max)

    [min_max[0].read_double, min_max[1].read_double]
  else
    [0.0, 0.0]
  end
end

#data_type ⇒ Symbol

The pixel data type for this band.

Returns:

  • (Symbol) —

    One of FFI::GDAL::GDALDataType.



92
93
94
 
# File 'lib/ffi-gdal/raster_band.rb', line 92

def data_type
  GDALGetRasterDataType(@gdal_raster_band)
end

#default_histogram(force = false, &block) {|completion, message| ... } ⇒ Hash{minimum => Float, maximum => Float, buckets => Fixnum, totals => Array<Fixnum>}

Gets the default raster histogram. Results are returned as a Hash so some metadata about the histogram can be returned. Example:

{
  :mininum => -0.9,
  :maximum => 255.9,
  :buckets => 256,
  :totals => [
    3954, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 1, 0,
    0, 0, 10, 27, 201, 699, 1766, 3472, 5013, 6464, 7698, 8352,
    9039, 10054, 11378, 13132, 14377, 14371, 14221, 14963, 14740,
    14379, 13724, 12938, 11318, 9828, 8504, 7040, 5700, 4890,
    4128, 3276, 2749, 2322, 1944, 1596, 1266, 1050, 784, 663,
    547, 518, 367, 331, 309, 279, 178, 169, 162, 149, 109, 98,
    90, 89, 82, 85, 74, 75, 42, 40, 39, 35, 39, 36, 36, 27, 20,
    12, 13, 19, 16, 12, 11, 6, 6, 8, 12, 6, 8, 11, 3, 7, 9, 2,
    5, 2, 5, 1, 4, 0, 0, 1, 0, 1, 2, 1, 0, 2, 1, 0, 0, 1, 0, 1,
    1, 1, 0, 2, 1, 2, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
  ]
}

Also, you can pass a block to get status on the processing. Conforms to FFI::GDAL::GDALProgressFunc.

Parameters:

  • force (Boolean) (defaults to: false) —

    Forces the computation of the histogram. If false and the default histogram isn’t available, this returns nil.

  • block (Proc) —

    No required, but can be used to output progess info during processing.

Yield Parameters:

  • completion (Float) —

    The ration completed as a decimal.

  • message (String) —

    Message string to display.

Returns:

  • (Hash{minimum => Float, maximum => Float, buckets => Fixnum, totals => Array<Fixnum>}) —

    Returns nil if no default histogram is available.



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/ffi-gdal/raster_band.rb', line 360

def default_histogram(force=false, &block)
  min_pointer = FFI::MemoryPointer.new(:double)
  max_pointer = FFI::MemoryPointer.new(:double)
  buckets_pointer = FFI::MemoryPointer.new(:int)
  histogram_pointer = FFI::MemoryPointer.new(:pointer)
  progress_proc = block || nil

  cpl_err = GDALGetDefaultHistogram(@gdal_raster_band,
    min_pointer,
    max_pointer,
    buckets_pointer,
    histogram_pointer,
    force,
    progress_proc,
    nil
  )

  min = min_pointer.read_double
  max = max_pointer.read_double
  buckets = buckets_pointer.read_int

  totals = if buckets.zero?
    []
  else
    histogram_pointer.get_pointer(0).read_array_of_int(buckets)
  end

  formated_buckets(cpl_err, min, max, buckets, totals)
end

#default_raster_attribute_table ⇒ GDAL::RasterAttributeTable

Returns:



311
312
313
314
315
316
317
 
# File 'lib/ffi-gdal/raster_band.rb', line 311

def default_raster_attribute_table
  rat_pointer = GDALGetDefaultRAT(c_pointer)
  return nil if rat_pointer.null?

  GDAL::RasterAttributeTable.new(c_pointer,
    raster_attribute_table_pointer: rat_pointer)
end

#histogram(min, max, buckets, include_out_of_range: false, approx_ok: false, &block) {|completion, message| ... } ⇒ Hash{minimum => Float, maximum => Float, buckets => Fixnum, totals => Array<Fixnum>}

Computes a histogram using the given inputs. If you just want the default histogram, use #default_histogram.

Parameters:

  • min (Float)
  • max (Float)
  • buckets (Fixnum)
  • include_out_of_range (Boolean) (defaults to: false)
  • approx_ok (Boolean) (defaults to: false)
  • block (Proc) —

    No required, but can be used to output progess info during processing.

Yield Parameters:

  • completion (Float) —

    The ration completed as a decimal.

  • message (String) —

    Message string to display.

Returns:

  • (Hash{minimum => Float, maximum => Float, buckets => Fixnum, totals => Array<Fixnum>})

See Also:



408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/ffi-gdal/raster_band.rb', line 408

def histogram(min, max, buckets, include_out_of_range: false,
  approx_ok: false, &block)
  histogram_pointer = FFI::MemoryPointer.new(:pointer, buckets)
  progress_proc = block || nil

  cpl_err = GDALGetRasterHistogram(@gdal_raster_band,
    min.to_f,
    max.to_f,
    buckets,
    histogram_pointer,
    include_out_of_range,
    approx_ok,
    progress_proc,
    'doing things')

  totals = if buckets.zero?
    []
  else
    histogram_pointer.read_array_of_int(buckets)
  end

  formated_buckets(cpl_err, min, max, buckets, totals)
end

#mask_band ⇒ GDAL::RasterBand

Returns:



181
182
183
184
185
186
 
# File 'lib/ffi-gdal/raster_band.rb', line 181

def mask_band
  band_pointer = GDALGetMaskBand(@gdal_raster_band)
  return nil if band_pointer.null?

  self.class.new(dataset, raster_band_pointer: band_pointer)
end

#mask_flags ⇒ Array<Symbol>

Returns:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/ffi-gdal/raster_band.rb', line 189

def mask_flags
  flag_list = GDALGetMaskFlags(@gdal_raster_band).to_s(2).scan(/\d/)
  flags = []

  flag_list.reverse.each_with_index do |flag, i|
    if i == 0 && flag.to_i == 1
      flags << :GMF_ALL_VALID
    elsif i == 1 && flag.to_i == 1
      flags << :GMF_PER_DATASET
    elsif i == 2 && flag.to_i == 1
      flags << :GMF_ALPHA
    elsif i == 3 && flag.to_i == 1
      flags << :GMF_NODATA
    end
  end

  flags
end

#maximum_value ⇒ Hash{value => Float, it_tight => Boolean}

Returns:

  • (Hash{value => Float, it_tight => Boolean}) 


545
546
547
548
549
550
 
# File 'lib/ffi-gdal/raster_band.rb', line 545

def maximum_value
  is_tight = FFI::MemoryPointer.new(:double)
  value = GDALGetRasterMaximum(@gdal_raster_band, is_tight)

  { value: value, is_tight: is_tight.read_bytes(1).to_bool }
end

#minimum_value ⇒ Hash{value => Float, it_tight => Boolean}

Returns:

  • (Hash{value => Float, it_tight => Boolean}) 


537
538
539
540
541
542
 
# File 'lib/ffi-gdal/raster_band.rb', line 537

def minimum_value
  is_tight = FFI::MemoryPointer.new(:bool)
  value = GDALGetRasterMinimum(@gdal_raster_band, is_tight)

  { value: value, is_tight: is_tight.read_bytes(1).to_bool }
end

#no_data_value ⇒ Hash{value => Float, is_associated => Boolean}

The no data value for a band is generally a special marker value used to mark pixels that are not valid data. Such pixels should generally not be displayed, nor contribute to analysis operations.

Returns:

  • (Hash{value => Float, is_associated => Boolean}) 


141
142
143
144
145
146
 
# File 'lib/ffi-gdal/raster_band.rb', line 141

def no_data_value
  associated = FFI::MemoryPointer.new(:bool)
  value = GDALGetRasterNoDataValue(@gdal_raster_band, associated)

  { value: value, is_associated: associated.read_bytes(1).to_bool }
end

#offset ⇒ Hash{value => Float, is_meaningful => Boolean}

This value (in combination with the GetScale() value) is used to transform raw pixel values into the units returned by #units. For example this might be used to store elevations in GUInt16 bands with a precision of 0.1, and starting from -100.

Units value = (raw value * scale) + offset.

For file formats that don’t know this intrinsically a value of 0.0 is returned.

Returns:

  • (Hash{value => Float, is_meaningful => Boolean}) 


281
282
283
284
285
286
 
# File 'lib/ffi-gdal/raster_band.rb', line 281

def offset
  meaningful = FFI::MemoryPointer.new(:bool)
  result = GDALGetRasterOffset(@gdal_raster_band, meaningful)

  { value: result, is_meaningful: meaningful.read_bytes(1).to_bool }
end

#offset=(new_offset) ⇒ FFI::GDAL::CPLErr

Parameters:

  • new_offset (Float)

Returns:



290
291
292
 
# File 'lib/ffi-gdal/raster_band.rb', line 290

def offset=(new_offset)
  GDALSetRasterOffset(@gdal_raster_band, new_offset)
end

#overview(index) ⇒ GDAL::RasterBand

Parameters:

  • index (Fixnum) —

    Must be between 0 and (#overview_count - 1).

Returns:



160
161
162
163
164
165
166
167
 
# File 'lib/ffi-gdal/raster_band.rb', line 160

def overview(index)
  return nil if overview_count.zero?

  overview_pointer = GDALGetOverview(@gdal_raster_band, index)
  return nil if overview_pointer.null?

  self.class.new(dataset, raster_band_pointer: overview_pointer)
end

#overview_count ⇒ Fixnum

Returns:



149
150
151
 
# File 'lib/ffi-gdal/raster_band.rb', line 149

def overview_count
  GDALGetOverviewCount(@gdal_raster_band)
end

#raster_sample_overview(desired_samples = 0) ⇒ GDAL::RasterBand

Returns An optimal overview or the same raster band if the raster band has no overviews.

Parameters:

  • desired_samples (Fixnum) (defaults to: 0) —

    The returned band will have at least this many pixels.

Returns:

  • (GDAL::RasterBand) —

    An optimal overview or the same raster band if the raster band has no overviews.



173
174
175
176
177
178
 
# File 'lib/ffi-gdal/raster_band.rb', line 173

def raster_sample_overview(desired_samples=0)
  band_pointer = GDALGetRasterSampleOverview(@gdal_raster_band, desired_samples)
  return nil if band_pointer.null?

  self.class.new(dataset, raster_band_pointer: band_pointer)
end

#read_block(x_offset, y_offset, image_buffer = nil) ⇒ Object

Read a block of image data, more efficiently than #read. Doesn’t resample or do data type conversion.

Parameters:

  • x_offset (Fixnum) —

    The horizontal block offset, with 0 indicating the left-most block, 1 the next block, etc.

  • y_offset (Fixnum) —

    The vertical block offset, with 0 indicating the top-most block, 1 the next block, etc.



508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/ffi-gdal/raster_band.rb', line 508

def read_block(x_offset, y_offset, image_buffer=nil)
  image_buffer ||= FFI::MemoryPointer.new(:void)
  #puts "x offset: #{x_offset}"
  #puts "y offset: #{y_offset}"

  result = GDALReadBlock(@gdal_raster_band, x_offset, y_offset, image_buffer)

  if result == :none
  elsif result == :failure

  end
end

#readlines ⇒ Object

TODO: Something about the pointer allocation smells here… def read(x_offset: 0, y_offset: 0, x_size: x_size, y_size: 1, pixel_space: 0, line_space: 0)



434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/ffi-gdal/raster_band.rb', line 434

def readlines
  x_offset = 0
  line_size = 1
  pixel_space = 0
  line_space = 0
  scan_line = FFI::MemoryPointer.new(:float, x_size)

  0.upto(y_size - 1) do |y|
    GDALRasterIO(@gdal_raster_band,
      :GF_Read,
      x_offset,
      y,
      x_size,
      line_size,
      scan_line,
      x_size,
      line_size,
      data_type,
      pixel_space,
      line_space
    )

    yield scan_line.read_array_of_float(x_size).dup
  end
end

#scale ⇒ Hash{value => Float, is_meaningful => Boolean}

The raster value scale. This value (in combination with the #offset value) is used to transform raw pixel values into the units returned by #units. For example this might be used to store elevations in GUInt16 bands with a precision of 0.1, and starting from -100.

Units value = (raw value * scale) + offset

For file formats that don’t know this intrinsically a value of one is returned.

Returns:

  • (Hash{value => Float, is_meaningful => Boolean}) 


257
258
259
260
261
262
 
# File 'lib/ffi-gdal/raster_band.rb', line 257

def scale
  meaningful = FFI::MemoryPointer.new(:bool)
  result = GDALGetRasterScale(@gdal_raster_band, meaningful)

  { value: result, is_meaningful: meaningful.read_bytes(1).to_bool }
end

#scale=(new_scale) ⇒ FFI::GDAL::CPLErr

Parameters:

  • new_scale (Float)

Returns:



266
267
268
 
# File 'lib/ffi-gdal/raster_band.rb', line 266

def scale=(new_scale)
  GDALSetRasterScale(@gdal_raster_band, new_scale.to_f)
end

#statistics(approx_ok = true, force = true) ⇒ Hash{mininum: Float, maximum: Float, mean: Float, standard_deviation: Float}

Returns minimum, maximum, mean, and standard deviation of all pixel values in this band.

Parameters:

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

    If true, stats may be computed based on overviews or a subset of all tiles.

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

    If false, stats will only be returned if the calculating can be done without rescanning the image.

Returns:

  • (Hash{mininum: Float, maximum: Float, mean: Float, standard_deviation: Float}) 


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/ffi-gdal/raster_band.rb', line 217

def statistics(approx_ok=true, force=true)
  min = FFI::MemoryPointer.new(:double)
  max = FFI::MemoryPointer.new(:double)
  mean = FFI::MemoryPointer.new(:double)
  standard_deviation = FFI::MemoryPointer.new(:double)

  cpl_err = GDALGetRasterStatistics(@gdal_raster_band,
    approx_ok,
    force,
    min,
    max,
    mean,
    standard_deviation)

  minimum = min.null? ? 0.0 : min.read_double

  case cpl_err.to_ruby
  when :none, :debug
    {
      minimum: min.read_double,
      maximum: max.read_double,
      mean: mean.read_double,
      standard_deviation: standard_deviation.read_double
    }
  when :warning then {}
  when :failure, :fatal then raise CPLErrFailure
  end
end

#to_a ⇒ NArray

Iterates through all lines and builds an NArray of pixels.

Returns:

  • (NArray) 


555
556
557
558
559
560
561
562
563
 
# File 'lib/ffi-gdal/raster_band.rb', line 555

def to_a
  lines = []

  readlines do |line|
    lines << line
  end

  NArray.to_na(lines)
end

#unit_type ⇒ String

Returns:



295
296
297
 
# File 'lib/ffi-gdal/raster_band.rb', line 295

def unit_type
  GDALGetRasterUnitType(@gdal_raster_band)
end

#unit_type=(new_unit_type) ⇒ FFI::GDAL::CPLErr

Parameters:

  • new_unit_type (String) —

    “” indicates unknown, “m” is meters, “ft” is feet; other non-standard values are allowed.

Returns:



302
303
304
305
306
307
308
 
# File 'lib/ffi-gdal/raster_band.rb', line 302

def unit_type=(new_unit_type)
  if defined? FFI::GDAL::GDALSetRasterUnitType
    GDALSetRasterUnitType(@gdal_raster_band, new_unit_type)
  else
    warn "GDALSetRasterUnitType is not defined.  Can't call RasterBand#unit_type="
  end
end

#write_array(pixel_array, x_offset: 0, y_offset: 0, data_type: :GDT_Byte, line_space: 0, pixel_space: 0) ⇒ Object

TODO: Write using #buffer_size to write most efficiently. TODO: Return a value!

Parameters:

  • pixel_array (NArray) —

    The NArray of pixels.

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

    The left-most pixel to start writing.

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

    The top-most pixel to start writing.

  • data_type (FFI::GDAL::GDALDataType) (defaults to: :GDT_Byte) —

    The type of pixel contained in the pixel_array.

  • line_space (Fixnum) (defaults to: 0)
  • pixel_space (Fixnum) (defaults to: 0) 


469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
 
# File 'lib/ffi-gdal/raster_band.rb', line 469

def write_array(pixel_array, x_offset: 0, y_offset: 0, data_type: :GDT_Byte,
  line_space: 0, pixel_space: 0)
  line_size = 1
  x_size = pixel_array.sizes.first
  y_size = pixel_array.sizes.last

  columns_to_write = x_size - x_offset
  lines_to_write = y_size - y_offset
  scan_line = FFI::MemoryPointer.new(:float, columns_to_write)

  (y_offset).upto(lines_to_write - 1) do |y|
    pixels = pixel_array[true, y]
    scan_line.write_array_of_float(pixels.to_a)

    GDALRasterIO(@gdal_raster_band,
      :GF_Write,
      x_offset,     # nXOff
      y,
      x_size,       # nXSize
      line_size,    # nYSize
      scan_line,    # pData
      x_size,       # nBufXSize
      line_size,    # nBufYSize
      data_type,    # eBufType
      pixel_space,  # nPixelSpace
      line_space    # nLineSpace
    )
  end

  GDALFlushRasterCache(@gdal_raster_band)
end

#x_size ⇒ Fixnum

The raster width in pixels.

Returns:



41
42
43
44
45
 
# File 'lib/ffi-gdal/raster_band.rb', line 41

def x_size
  return nil if null?

  GDALGetRasterBandXSize(@gdal_raster_band)
end

#y_size ⇒ Fixnum

The raster height in pixels.

Returns:



50
51
52
53
54
 
# File 'lib/ffi-gdal/raster_band.rb', line 50

def y_size
  return nil if null?

  GDALGetRasterBandYSize(@gdal_raster_band)
end