riogrande.io.core#

Low-level I/O functions for reading and writing GeoTIFF raster data.

This module provides the functional layer beneath Source and Band. It contains functions for tag management, band index lookup, block loading with optional rescaling, band writing and updating, coordinate registration, and LZW compression.

Most functions in this module operate directly on open rasterio DatasetWriter or DatasetReader objects and are called internally by the Source and Band class methods.

Attributes#

NS

Functions#

compress_tif(source[, output, compression])

Compress tif file with LZW compression

coregister_raster(source, reference[, output])

Align raster to have identical resolution.

get_bands_by_tag(source[, ns])

Find all bands that match specific tags

load_block(source[, view, scaling_params])

Get a block from a specific band of a .tif file along with the transform

update_band(src, data[, window])

Find a specific band and update it with data

write_band(src, data[, bidx, window])

Write data to a specific band of a tif file and set the tags

Module Contents#

riogrande.io.core.compress_tif(source, output=None, compression='lzw')[source]#

Compress tif file with LZW compression

Band tags are copied band-by-band using _get_tags() and _set_tags().

Parameters:

  • source (str) – The path to the tif file you want to compress

  • output (str or None) – Optional path to output file. If not set, the resulting file will inherit the filename from source and get a _compress appendix via output_filename(). If compression is 'none', i.e. no compression the appendix will be '_decompressed'.

  • compression (str or None) – Type of compression to use, default is LZW. See GDAL documentation for details.

Returns:

The name of the compressed file

Return type:

str

See also

compress()

Convenience wrapper on the Source class.

riogrande.io.core.coregister_raster(source, reference, output=None)[source]#

Align raster to have identical resolution.

Resolution will be calculated automatically from bounds and height/width of reference raster using rasterio.warp.calculate_default_transform(). Reprojection is performed with rasterio.warp.reproject() and rasterio.enums.Resampling.nearest. CRS compatibility is verified with check_crs().

Parameters:

  • source (str) – The path to the tif file you want to co-register

  • reference (str) – The path to the tif file with the pixel registration to use as reference for co-registration

  • output (str or None) – The path to write the co-registered map to. If None, a filename is generated by output_filename().

Returns:

The name of the file that holds co-registered map

Return type:

str

riogrande.io.core.get_bands_by_tag(source, ns=NS, **tags)[source]#

Find all bands that match specific tags

This method check the metadata (including those of bands) in one or several tif files and returns the file paths, as well as, the band indexes for all bands with matching tags.

Whenever a band has tags that match, the name of the tif file, as well as, the band index are added to the list of returned matches.

If the tags are found in the metadata of a dataset the path to the file and a band index of None are added to the list of returned matches (this different form the rasterio convention to that uses bidx=0 for “all bands” - I find that confusing).

Parameters:

  • source (str) – A glob pattern string passed to glob.glob(), leading to (potentially) multiple source files that will be checked.

  • ns (str) – The namespace to search the tags in. It is dicouraged to change this value from the default as all tagging related methods of this package use the same default namespace.

  • **tags (Any) – Arbitrary number of keyword arguments that will be compared to the tags of each tif file.

Returns:

A list of tuples with source (path) and bandindex entries in tuples.

Return type:

list

See also

_get_bidx_by_tag()

Find a single band in one open dataset.

_find_bidxs()

Return all matching band indexes in one dataset.

riogrande.io.core.load_block(source, view=None, scaling_params=None, **tags)[source]#

Get a block from a specific band of a .tif file along with the transform

You can select what band(s) to load by passing keyword arguments as tags (see **tags below) and limit the area to load by passing a view (converted to a rasterio.windows.Window via view_to_window()).

Parameters:

  • source (str) – The path to the tif file to load

  • view (tuple[int, int, int, int] or None) – An optional tuple (x, y, width, height) defining the area to load. If None is provided (the default) then the entire file is loaded.

  • scaling_params (dict or None) –

    Optional dictionary to set a rescaling of the data. If provided, the following keywords are accepted:

    scalingtuple[float, float]

    Factors to rescale the number of pixels. Values >1 will upscale.

    methodrasterio.enums.Resampling

    The resampling method. If not provided then rasterio.enums.Resampling.bilinear is used.

  • **tags (Any) – Arbitrary number of keyword arguments to describe the band to select. See _get_bidx_by_tag() for further details.

Returns:

data: holding a numpy array with the actual data transform: an affine.Affine object that encodes the transformation used orig_profile: The profile information of the original .tif file

Return type:

dict

See also

write_band()

Write data to a specific band.

view_to_window()

Convert a view tuple to a rasterio Window.

riogrande.io.core.update_band(src, data, window=None, **tags)[source]#

Find a specific band and update it with data

This function writes a data array in a band specified with tags, identified via _get_bidx_by_tag(). If no band with the matching tags is found a BandSelectionNoMatchError is raised.

Parameters:

  • src (DatasetWriter) – tif file opened with rasterio.open()

  • data (NDArray) – The array to write into the file

  • window (Window or None) – An optional rasterio.windows.Window to specify an area to write.

  • **tags (Any) – Arbitrary number of keyword arguments that will be used to find the band to write into.

Return type:

None

See also

write_band()

Write to a band by explicit index.

riogrande.io.core.write_band(src, data, bidx=1, window=None, **tags)[source]#

Write data to a specific band of a tif file and set the tags

Parameters:

  • src (DatasetWriter) – tif file opened with rasterio.open()

  • data (NDArray) – The array to write into the file

  • bidx (int) – Band index to write into the file

  • window (Window or None) – An optional rasterio.windows.Window to specify an area to write.

  • **tags (Any) – Arbitrary number of keyword arguments that will be set as tags. The value provided is converted to a string with serialize() via _set_tags() before being written to the file.

Return type:

None

See also

update_band()

Find a band by tags and update it.

load_block()

Load a block of data from a band.

riogrande.io.core.NS = 'GEORACOON'[source]#