Struct gdal::raster::RasterBand

pub struct RasterBand<'a> { /* private fields */ }

Represents a single band of a dataset.

This object carries the lifetime of the dataset that contains it. This is necessary to prevent the dataset from being dropped before the band.

Implementations

impl<'a> RasterBand<'a>

pub unsafe fn c_rasterband(&self) -> GDALRasterBandH

Returns the wrapped C pointer

Safety

This method returns a raw C pointer

pub unsafe fn from_c_rasterband( dataset: &'a Dataset, c_rasterband: GDALRasterBandH ) -> Self

Create a RasterBand from a wrapped C pointer

Safety

This method operates on a raw C pointer

pub fn block_size(&self) -> (usize, usize)

The size of a preferred I/O raster block size as a (cols, rows) tuple. Reading/writing chunks corresponding to the returned value should offer the best performance.

pub fn x_size(&self) -> usize

Get x-size (width, or number of column) of the band. Note: This may not be the same as number of columns of the owning Dataset, due to scale.

pub fn y_size(&self) -> usize

Get y-size (height, or number of rows) of the band Note: This may not be the same as number of rows of the owning Dataset, due to scale.

pub fn size(&self) -> (usize, usize)

Get dimensions of the band, as a (cols, rows) tuple. Note: This may not be the same as raster_size on the owning_dataset due to scale.

pub fn read_into_slice<T: Copy + GdalType>( &self, window: (isize, isize), window_size: (usize, usize), size: (usize, usize), buffer: &mut [T], e_resample_alg: Option<ResampleAlg> ) -> Result<()>

Read data from this band into a slice, where T implements GdalType

Arguments

• window - the window position from top left
• window_size - the window size (GDAL will interpolate data if window_size != buffer_size)
• size - the desired size to read
• buffer - a slice to hold the data (length must equal product of size parameter)
• e_resample_alg - the resample algorithm used for the interpolation. Default: NearestNeighbor.

Example

use gdal::Dataset;
use gdal::raster::{GdalDataType, ResampleAlg};
let dataset = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
let band1 = dataset.rasterband(1)?;
assert_eq!(band1.band_type(), GdalDataType::UInt8);
let size = 4;
let mut buf = vec![0; size*size];
band1.read_into_slice::<u8>((0, 0), band1.size(), (size, size), buf.as_mut_slice(), Some(ResampleAlg::Bilinear))?;
assert_eq!(buf, [101u8, 119, 94, 87, 92, 110, 92, 87, 91, 90, 89, 87, 92, 91, 88, 88]);

pub fn read_as<T: Copy + GdalType>( &self, window: (isize, isize), window_size: (usize, usize), size: (usize, usize), e_resample_alg: Option<ResampleAlg> ) -> Result<Buffer<T>>

Read a Buffer<T> from this band, where T implements GdalType.

Arguments

• window - the window position from top left
• window_size - the window size (GDAL will interpolate data if window_size != buffer_size)
• buffer_size - the desired size of the ‘Buffer’
• e_resample_alg - the resample algorithm used for the interpolation. Default: NearestNeighbor.

Example

use gdal::Dataset;
use gdal::raster::{GdalDataType, ResampleAlg};
let dataset = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
let band1 = dataset.rasterband(1)?;
assert_eq!(band1.band_type(), GdalDataType::UInt8);
let size = 4;
let buf = band1.read_as::<u8>((0, 0), band1.size(), (size, size), Some(ResampleAlg::Bilinear))?;
assert_eq!(buf.size, (size, size));
assert_eq!(buf.data, [101u8, 119, 94, 87, 92, 110, 92, 87, 91, 90, 89, 87, 92, 91, 88, 88]);

pub fn read_as_array<T: Copy + GdalType>( &self, window: (isize, isize), window_size: (usize, usize), array_size: (usize, usize), e_resample_alg: Option<ResampleAlg> ) -> Result<Array2<T>>

Available on crate feature array only.

Read a Array2<T> from this band, where T implements GdalType.

Arguments

• window - the window position from top left
• window_size - the window size (GDAL will interpolate data if window_size != array_size)
• array_size - the desired size of the ‘Array’
• e_resample_alg - the resample algorithm used for the interpolation

Note

The Matrix shape is (rows, cols) and raster shape is (cols in x-axis, rows in y-axis).

pub fn read_band_as<T: Copy + GdalType>(&self) -> Result<Buffer<T>>

Read the full band as a Buffer<T>, where T implements GdalType.

pub fn read_block<T: Copy + GdalType>( &self, block_index: (usize, usize) ) -> Result<Array2<T>>

Available on crate feature array only.

Read a Array2<T> from a Dataset block, where T implements GdalType.

Arguments

• block_index - the block index

Notes

The Matrix shape is (rows, cols) and raster shape is (cols in x-axis, rows in y-axis).

pub fn write<T: GdalType + Copy>( &mut self, window: (isize, isize), window_size: (usize, usize), buffer: &Buffer<T> ) -> Result<()>

Write a Buffer<T> into a Dataset.

Arguments

• window - the window position from top left
• window_size - the window size (GDAL will interpolate data if window_size != Buffer.size)
• buffer - the data to write into the window

pub fn band_type(&self) -> GdalDataType

Returns the pixel datatype of this band.

pub fn no_data_value(&self) -> Option<f64>

Returns the no-data value of this band.

pub fn set_no_data_value(&mut self, no_data: Option<f64>) -> Result<()>

Set the no data value of this band.

If no_data is None, any existing no-data value is deleted.

pub fn color_interpretation(&self) -> ColorInterpretation

Returns the color interpretation of this band.

pub fn set_color_interpretation( &mut self, interp: ColorInterpretation ) -> Result<()>

Set the color interpretation for this band.

pub fn color_table(&self) -> Option<ColorTable<'_>>

Get the color table for this band if it has one.

pub fn set_color_table(&mut self, colors: &ColorTable<'_>)

Set the color table for this band.

See ColorTable for usage example.

pub fn scale(&self) -> Option<f64>

Returns the scale of this band if set.

pub fn set_scale(&mut self, scale: f64) -> Result<()>

Set the scale for this band.

pub fn offset(&self) -> Option<f64>

Returns the offset of this band if set.

pub fn set_offset(&mut self, offset: f64) -> Result<()>

Set the offset for this band.

pub fn actual_block_size(&self, x: usize, y: usize) -> Result<(usize, usize)>

Get actual block size (at the edges) when block size does not divide band size.

pub fn overview_count(&self) -> Result<i32>

pub fn overview(&self, overview_index: isize) -> Result<RasterBand<'a>>

pub fn unit(&self) -> String

Return the unit of the rasterband. If there is no unit, the empty string is returned.

pub fn mask_flags(&self) -> Result<GdalMaskFlags>

Read the band mask flags for a GDAL RasterBand.

pub fn create_mask_band(&mut self, shared_between_all_bands: bool) -> Result<()>

Create a new mask band for the layer. shared_between_all_bands indicates if all bands of the dataset use the same mask.

pub fn open_mask_band(&self) -> Result<RasterBand<'_>>

Open the mask-Rasterband

pub fn get_statistics( &self, force: bool, is_approx_ok: bool ) -> Result<Option<StatisticsAll>>

Fetch image statistics.

Returns the minimum, maximum, mean and standard deviation of all pixel values in this band. If approximate statistics are sufficient, the is_approx_ok flag can be set to true in which case overviews, or a subset of image tiles may be used in computing the statistics.

If force is false results will only be returned if it can be done quickly (i.e. without scanning the data). If forceisfalseand results cannot be returned efficiently, the method will returnNone`.

Note that file formats using PAM (Persistent Auxiliary Metadata) services will generally cache statistics in the .pam file allowing fast fetch after the first request.

This methods is a wrapper for GDALGetRasterStatistics.

pub fn compute_raster_min_max( &self, is_approx_ok: bool ) -> Result<StatisticsMinMax>

Compute the min/max values for a band.

If is_approx_ok is true, then the band’s GetMinimum()/GetMaximum() will be trusted. If it doesn’t work, a subsample of blocks will be read to get an approximate min/max. If the band has a nodata value it will be excluded from the minimum and maximum.

If is_approx_ok is false, then all pixels will be read and used to compute an exact range.

This methods is a wrapper for GDALComputeRasterMinMax.

Trait Implementations

impl<'a> Metadata for RasterBand<'a>

fn description(&self) -> Result<String>

For most crate::Datasets, method returns this is the originating filename. For crate::raster::RasterBands it is a description (if supported) or "".

fn metadata_domains(&self) -> Vec<String>

Metadata in GDAL is partitioned into namespaces, knows as “domains” in the GDAL Data Model. GDAL types with metadata (a.k.a. “Major Objects”) have a default or “root” domain identified by the empty string (""). Specific “Major Object” types may have other conventionally recognized domains. For example, in raster Datasets you may come across the domains SUBDATASETS, IMAGE_STRUCTURE, RPC, IMAGERY, xml:, etc.

fn metadata_domain(&self, domain: &str) -> Option<Vec<String>>

Get all the metadata values within the given domain. Returns None if domain is not defined. Entries in the returned Vec<String> are formatted as “Name=value” pairs

fn metadata_item(&self, key: &str, domain: &str) -> Option<String>

Get a single metadata entry, as indicated by key and domain.

fn set_metadata_item( &mut self, key: &str, value: &str, domain: &str ) -> Result<()>

Set a metadata item in given domain at given key.

fn set_description(&mut self, description: &str) -> Result<()>

For Datasets this sets the dataset name; normally application code should not set the “description” for GDALDatasets. For RasterBands it is actually a description (if supported) or "".

fn metadata(&self) -> MetadataIter<'_>where Self: Sized,

Get an iterator over metadata entries, across all domains.