riogrande.io.models

Data model classes for GeoTIFF raster sources and bands.

This module defines Source and Band, the two central data model classes of the riogrande package. A Source represents a single GeoTIFF file together with its metadata (tags, profile, namespace), while a Band encapsulates one raster band within a source, including band-specific tags, a band index, and configurable mask and data readers.

Together these classes form the primary interface through which raster data is opened, read, written, and tagged throughout the package.

Classes

Band	A Band object encapsulates metadata and configuration for accessing
Source	A Source object represents a file-based dataset (GeoTIFF) along with associated

Module Contents

class riogrande.io.models.Band

A Band object encapsulates metadata and configuration for accessing a band in a raster dataset. It references a parent Source object, contains band-specific tags, and holds parameters for reading.

Parameters:

• source (Source) – The Source object from which this band originates.

• tags (dict) – Optional dictionary of key-value metadata associated with the band. Defaults to an empty dictionary.

• bidx (int or None) – Band index in the source dataset (1-based). If None, defaults to an implicit index or is determined at runtime.

• read_params (dict) – Dictionary of parameters controlling how the band is read (e.g., windowing, resampling). Defaults to an empty dictionary.

Examples

>>> s = Source("example.tif")
>>> b = Band(source=s, bidx=1, tags={"type": "NIR"})
>>> b
Band(tags={'type': 'NIR'})
>>> b._use_mask
'self'
>>> b._ns
'GEORACOON'

__hash__()

Compute a hash value for the Band.

Returns:

Hash value for the object.

Return type:

int

__repr__()

Return a string representation of the Band’s tags.

Returns:

String representation of the tags.

Return type:

str

add(band, out_band=None, **add_kwargs)

Add the values of another band to this band, element-wise.

The data from both bands are added using numpy.add(), and the result is stored in out_band or overwrites this band by default.

Parameters:

• band (Band) – Band whose values will be added.

• out_band (Band or None) – Destination Band for storing the result. If None (default), the operation overwrites this band.

• **add_kwargs (dict) – Additional keyword arguments passed to numpy.add().

See also

subtract()

Element-wise subtraction of another band.

count_valid_pixels(selector, no_data, limit_count=0)

Count the number of valid pixels in the band, optionally under a selector.

Valid pixels are those that are not equal to no_data. If a selector mask is provided, only pixels where the selector is True are counted. The per-block counting is delegated to count_contribution().

Parameters:

• selector (NDArray or None) – Boolean numpy.ndarray of the same shape as the band, indicating which pixels to include in the count. If None, all pixels are considered.

• no_data (int or float) – Pixel value considered invalid (e.g., nodata value).

• limit_count (int) – Optional early-exit threshold. If > 0, the method returns a boolean: - True if the number of valid pixels exceeds limit_count - False otherwise If limit_count is 0, the method returns the actual count.

Returns:

• If limit_count is 0, returns the total count of valid pixels.

• If limit_count > 0, returns True/False depending on whether the count exceeds the limit.

Return type:

int or bool

See also

count_contribution()

Per-block pixel counting function.

get_min_max()

Compute the min/max of valid pixels.

data_reader(match=None, **kwargs)

Context manager for reading data from this band.

Opens the underlying Source for reading and yields a callable that reads data from the specified band index.

Parameters:

• match (str or list or None) – Optional selection of tags to identify a matching band. Ignored if the band has bidx set.

• **kwargs – Additional keyword arguments passed to rasterio.io.DatasetReader.read, e.g., window, masked, out_dtype.

Yields:

Callable – A partial function that reads data from the band.

data_writer(match=None, **kwargs)

Context manager for writing data to this band.

Opens the underlying Source for writing and yields a callable that writes data to the specified band index.

Parameters:

• match (str or list or None) – Optional selection of tags to identify a matching band. Ignored if the band has bidx set.

• **kwargs – Additional keyword arguments passed to rasterio.io.DatasetWriter.write, e.g., window specification.

Yields:

Callable – A partial function that writes data to the band.

export_tags(match=None)

Write the band’s set tags back to the source file.

The band index is resolved with get_bidx() and the tags are written via set_tags().

Parameters:

match (str or list or None) – Optional selection of tags to identify a matching band. If provided, the routine tries to find a single band in the source file for which only the tags specified in this list have matching values. It can be used if you want to export some new tags or if you have updated some tags and want to export these new values.

Notes

• If the band has the bidx attribute set, match is ignored.

• Example:

>>> b1.export_tags(match=’category’)
# Identifies the band via the ‘category’ tag and updates other tags

See also

import_tags()

Load tags from the source file into this band object.

get_bidx()

Resolve the band index in the source file.

get_bidx(match=None)

Determine the correct band index in the source file.

If the bidx attribute is already set, it is checked for existence in the Source file. If bidx is None, the method tries to infer the correct band index using the tags attribute via find_index(). The optional match argument can limit which tags are considered for matching.

Parameters:

match (str or list or None) –

Selection of tags to identify the correct band. If an integer is

provided, it is converted to a single-element list. If None (default), all tags in self.tags are considered. Ignored if bidx is set.

Notes

• Can be used when exporting or updating tags to identify a single band in the source.

• Example:

  >>> b1.get_bidx(match='category')
  # Finds the band whose 'category' tag matches
  

Returns:

Index of the band in the Source that matches this band.

Return type:

int

Raises:

BandSelectionNoMatchError – If there is no clear match for the band in the source file or if the specified bidx does not exist.

See also

export_tags()

Write tags using the resolved band index.

import_tags()

Load tags using the resolved band index.

get_data(**kwargs)

Read the full data array of this band from the source file.

All keyword arguments except okwargs are passed to the read method of the underlying Source. The optional okwargs are passed to the read method of the Source.

Parameters:

**kwargs – Optional keyword arguments for Source.read. Common options include window, out_shape, resampling, etc. Special keyword: if okwargs is present, it is passed to Source.open when opening the file.

Returns:

A NumPy array containing the data of this band.

Return type:

NDArray

get_mask_reader()

Return the appropriate mask reader for this band based on _use_mask.

Returns:

A callable that reads a mask array when called. Depending on _use_mask, it may read the band mask via mask_reader(), the dataset mask via mask_reader(), or return a constant array via _mask_full().

Return type:

Callable

Raises:

InvalidMaskSelectorError – If _use_mask has an invalid value.

See also

set_mask_reader()

Configure which mask to use.

get_min_max(no_data, selector=None)

Compute the minimum and maximum values of the band, optionally under a selector.

Only pixels not equal to no_data and selected by the selector are considered. Per-block min/max are computed with numpy.nanmin() / numpy.nanmax().

Parameters:

• no_data (int or float) – Value considered invalid; these pixels are ignored.

• selector (NDArray or None) – Boolean numpy.ndarray of the same shape as the band, indicating which pixels to include. If None, all pixels are considered.

Returns:

Tuple (min_value, max_value) over the selected valid pixels. Returns None if no valid pixels are found.

Return type:

tuple of (float, float) or None

See also

count_valid_pixels()

Count valid (non-nodata) pixels.

import_tags(match=None, keep=True)

Import tags from the source file (at its band index) into this Band object.

The band index is resolved with get_bidx() and tags are read via get_tags().

Parameters:

• match (str or list or None) – Optional selection of tags to match a band in the source file. Used internally by get_bidx() to locate the correct band.

• keep (bool) – If True, update the existing tags dictionary with the imported tags. If False, replace the existing tags dictionary with the imported tags.

See also

export_tags()

Write this band’s tags back to the source file.

init_source(profile, overwrite=False, **kwargs)

Initialize the source file for this band, creating it if necessary.

Updates the source’s profile and optionally overwrites an existing file.

Parameters:

• profile (dict) – Dictionary specifying the profile of the dataset. This will update the source’s profile before creating or opening the file.

• overwrite (bool) – If True, any existing file at the source path will be overwritten. Equivalent to deleting the existing source and creating a new one.

• **kwargs – Additional keyword arguments passed to the underlying Source.init_source method.

load_block(view=None, scaling_params=None, match=None)

Load a block of data from this band along with its transform.

This reads a portion of the band data from the source, optionally applying scaling/resampling. The block can be limited to a rectangular region (view), and the specific band can be selected via match (tags or bidx). Delegates to load_block() via load_block(). See load_block() for further details.

Parameters:

• view (tuple[int, int, int, int] or None) – Optional window defined as (x, y, width, height) in pixels. If None, the entire band is read.

• scaling_params (dict or None) –

  Optional dictionary specifying rescaling parameters:

  • scaling: tuple[float, float], factors to rescale the number of pixels.

    Values >1 will upscale.

  • method: rasterio.enums.Resampling, resampling method (default: bilinear)

• match (str or list or None) – Optional tag(s) or criteria to identify the band in the source. If None, the current bidx or all tags are used.

Returns:

Dictionary containing:

• data: numpy.ndarray with the band data of shape (1, height, width)

• transform: affine.Affine transformation object for the loaded block

• orig_profile: Original raster profile of the source band

Return type:

dict[str, Any]

See also

load_block()

Analogous method on the Source class.

load_block()

Underlying function with full parameter details.

mask_reader(match=None, **kwargs)

Context manager for reading the band-specific mask.

Always returns the mask associated with this specific band.

Parameters:

• match (str or list or None) – Optional selection of tags to identify the band.

• **kwargs – Keyword arguments passed to Source.open.

Yields:

Callable – Partial function to read the band mask.

set_data(data, overwrite=False, **kwargs)

Write data to the band in the underlying source file.

Uses data_writer() as the context manager for writing.

Parameters:

• data (NDArray) – numpy.ndarray containing the data to write.

• overwrite (bool) – If True, overwrite an existing source file. If False and the source exists, the file is opened in update mode ('r+').

• **kwargs – Additional keyword arguments passed to data_writer().

See also

get_data()

Read the full data array of this band.

data_writer()

Context manager used for writing.

set_mask_reader(use='band')

Set which mask should be used when reading data for this band.

Parameters:

use ({'self', 'band', 'source', 'mask_none', 'mask_all'}, default 'band') –

Determines how the mask is applied:

• 'self' or 'band': use the band-specific mask (i.e., rasterio.io.DatasetReader.read_masks()).

• 'source': use the dataset mask from the source (i.e., rasterio.io.DatasetReader.dataset_mask()).

• 'mask_none': consider all pixels valid (returns an array of 1s).

• 'mask_all': consider all pixels invalid (returns an array of 0s).

Raises:

AssertionError – If use is not one of the allowed options.

See also

get_mask_reader()

Return the mask-reading callable based on the current setting.

subtract(band, out_band=None, **add_kwargs)

Subtract another band from this band, element-wise.

The operation computes self - band by adding the negative of the second band to this band via numpy.add(). The result is stored in out_band or overwrites this band by default.

Parameters:

• band (Band) – Band to subtract from this band.

• out_band (Band or None) – Destination Band for storing the result. If None (default), the operation overwrites this band.

• **sub_kwargs (dict) – Additional keyword arguments passed to the underlying operation.

See also

add()

Element-wise addition of another band.

bidx: int | None = None

property index_exists: bool

Check whether the band’s index exists in the source dataset.

Returns:

True if the band’s index (bidx) is set and exists in the parent Source. False if no bidx is set or if the index is absent.

Return type:

bool

read_params: dict

property shape: tuple[int, int]

Return the shape of the band as a tuple (height, width).

This corresponds to the shape of the NumPy array.

Returns:

Tuple (height, width) representing the number of rows and columns in the band.

Return type:

tuple of int

source: Source

property source_exists: bool

Check whether the parent source file of the Band exists on disk.

This property queries the parent Source object to determine if the underlying file is present.

Returns:

True if the file exists.

Return type:

bool

property status: None

Print the current status of the Band.

Reports include:

• Existence of the source file.

• Presence of the band’s index in the source.

• Exact and partial matches for the band’s tags.

• Warnings if the index or tags are inconsistent.

Return type:

None

tags: dict

class riogrande.io.models.Source(path, tags=None, profile=None, ns=core.NS)

A Source object represents a file-based dataset (GeoTIFF) along with associated tags, profile metadata, and namespace information.

Parameters:

• path (str or Path) – Path to the dataset file.

• tags (dict or None) – Optional dictionary of key-value metadata associated with the source. Defaults to an empty dictionary.

• profile (dict or None) – Optional dictionary of dataset profile information (e.g. width, height, dtype). Defaults to an empty dictionary.

• ns (str) – Namespace string used to distinguish sources. Defaults to “GEORACOON”.

Examples

>>> s1 = Source("example.tif", tags={"type": "satellite"})
>>> s1
Source(path=example.tif, exists: False)
>>> s1.tags
{'type': 'satellite'}
>>> s1._ns
'GEORACOON'

__eq__(other)

Test equality between two Source objects.

Parameters:

other (Source) – Source object to compare against.

Returns:

True if both objects are Source instances with the same path, tags, and namespace.

Return type:

bool

__hash__()

Compute a hash value for the Source.

Returns:

Hash based on path, namespace, and tag values.

Return type:

int

__repr__()

Return a string representation of the Source.

Returns:

String representation of the object.

Return type:

str

check_compatibility(*sources)

Check whether this source is compatible with one or more other sources.

Delegates to check_compatibility(), which verifies CRS, linear units, and spatial resolution.

Parameters:

*sources (Source) – One or more additional Source objects to check against this one.

Returns:

True if all provided sources are compatible with this one.

Return type:

bool

See also

check_compatibility()

Underlying compatibility check.

compress(output=None, compression='lzw', keep_original=False)

Compress the source file using a given compression algorithm.

A new compressed GeoTIFF is created via compress_tif(). By default, the original file is replaced with the compressed one unless keep_original is set.

Parameters:

• output (str or None) – Path to the output file. If None (default), the compressed file overwrites the current source path.

• compression (str or None) – Compression algorithm to use. Default is 'lzw'. See GDAL documentation for valid options.

• keep_original (bool) – If True, the original uncompressed file is preserved. If False (default), the uncompressed file is deleted after compression.

Return type:

None

Notes

• Updates the path attribute of the Source to point to the new compressed file.

See also

compress_tif()

Underlying compression function.

data_reader(bands=None, **kwargs)

Context manager for reading multiple bands as a 3D array.

Opens the source file and prepares a callable that reads the requested bands as a 3-dimensional array (band, row, column).

Parameters:

• bands (list[Band] or None) – A collection of Band objects specifying which bands to read. If None, all bands in the dataset are used.

• **kwargs (dict) – Additional keyword arguments forwarded to open() (e.g., mode, driver options).

Yields:

callable – A callable equivalent to src.read(indexes=...) that returns a 3D numpy array with shape (len(bands), height, width).

export_mask(mask, window)

Write a mask into the source file.

Parameters:

• mask (NDArray) – Array to use as a mask. Values greater than 0 represent valid pixels; 0 represents invalid/masked pixels.

• window (Window) – The raster window to which the mask should be written.

Return type:

None

find_index(tags)

Find a single band index matching the given tags.

Parameters:

tags (dict) – Tag key–value pairs to search for.

Returns:

The band index if exactly one match is found, None otherwise.

Return type:

int or None

find_indexes(tags, mode='all')

Find band indexes matching the given tags.

Parameters:

• tags (dict) – Tag key–value pairs to search for.

• mode (str) –

  Matching mode:

  • ’all’: All provided tags must be present.

  • ’any’: Any one of the provided tags may match (currently not implemented, placeholder).

Returns:

The list of band indexes matching the tags.

Return type:

list of int

get_band(bidx=None, **tags)

Retrieve a specific band as a Band object.

A Band can be selected either by its index (bidx) or by matching tags. If both are provided, they must match the same band.

Parameters:

• bidx (int or None) – Optional band index to select.

• **tags (dict) – Optional tag key-value pairs to match the band via _get_bidx_by_tag().

Returns:

A Band object corresponding to the requested band, including associated tags.

Return type:

Band

Raises:

• SourceNotSavedError – If the source file does not exist on disk.

• BandSelectionNoMatchError – If no band matches the provided index or tags.

• AssertionError – If the index and tag selection refer to different bands.

See also

get_bands()

Return all bands in the dataset.

get_bands()

Return all bands present in the dataset.

Returns:

A list of Band objects for all bands in the dataset.

Return type:

list of Band

See also

get_band()

Retrieve a single band by index or tags.

get_bidx(band)

Resolve the band index of a given Band object in the source.

Attempts to identify the band index (bidx) associated with the provided Band, based on either its explicit index or its tags. If both are given, they must resolve to the same unique band.

Parameters:

band (Band) – The Band object for which to resolve the band index.

Returns:

The resolved band index if a unique match is found, otherwise None.

Return type:

int or None

Raises:

BandSelectionAmbiguousError – If only tags are provided, and they match multiple bands, or if both bidx and tags are given, but they are inconsistent.

get_mask(**kwargs)

Read the dataset mask from the file.

Except okwargs all keyword arguments are passed to the rasterio.io.DatasetReader.dataset_mask() method of the source via mask_reader().

Parameters:

**kwargs (dict) – Optional set of keyword arguments to pass to the read method of the source. Notable exception: if okwargs is present, it is passed to open() when accessing the source.

Returns:

An array representing the dataset mask. Non-zero values indicate valid pixels, and 0 indicates masked/invalid pixels.

Return type:

NDArray

See also

mask_reader()

Context manager yielding the underlying mask-read callable.

get_tag_values(tag, bidx=None)

Fetch the value of a tag for one or more bands.

If a tag is not present for a given band, the value will be None and a mapping {bidx: value} for all bands will be returned.

Parameters:

• tag (str) – The tag key to look up.

• bidx (int or list or None) – Band index (int), list of indices, or None. If None, all bands are queried.

Returns:

A mapping of band index to the tag value (or None if missing).

Return type:

dict

get_tags(bidx)

Retrieve all tags for a specific band.

Reads and deserializes tags via _get_tags().

Parameters:

bidx (int) – The band index to query.

Returns:

A dictionary of tag key-value pairs associated with the band.

Return type:

dict

See also

set_tags()

Write tags back to the source file.

get_tag_values()

Fetch values for a single tag key across multiple bands.

has_band(band)

Check whether a given Band is present in the source.

Parameters:

band (Band) – The band object to test for.

Returns:

True if the band is present.

Return type:

bool

has_bidx(bidx)

Check whether a band index exists in the source.

Parameters:

bidx (int) – The band index to check for (1-based, as in rasterio).

Returns:

True if the band index exists in the dataset.

Return type:

bool

has_tags(tags)

Check whether any band contains all the provided tags.

Parameters:

tags (dict) – Dictionary of tag key–value pairs to look for.

Returns:

True if at least one band contains all provided tags.

Return type:

bool

import_profile(update_self=True)

Read the profile from the source file

Opens the file via open() and reads the rasterio profile.

Parameters:

update_self (bool) – If True (default), update the profile attribute with the values fetched from the source file. If False, the object’s profile remains unchanged.

Returns:

The profile dictionary retrieved from the source file.

Return type:

dict

See also

init_source()

Create or overwrite the source file using the stored profile.

init_source(overwrite=False, **kwargs)

Initialize or create the source file.

This method either creates a new file (empty dataset) on disk or opens an existing one via open(). If overwrite is True, the existing file will be replaced.

Parameters:

• overwrite (bool) – If True, overwrite an existing file.

• **kwargs (dict) – Additional keyword arguments passed to the open() method when creating the dataset (e.g., driver options, compression).

Return type:

None

See also

import_profile()

Read the profile from an existing source file.

load_block(view=None, scaling_params=None, **tags)

Load a block of raster data from the source along with the transform.

Band where data is loaded from needs to be identified with tags. If no tags are provided data from bidx=1 is returned. See load_block() for further details.

Parameters:

• view (tuple[int, int, int, int] or None) – The window to read, given as (row_start, row_stop, col_start, col_stop). If None (default), the entire raster is read.

• scaling_params (dict, optional) –

  Parameters controlling rescaling of the data. If provided, the dictionary may include:

  • scaling : tuple of float Factors to rescale the raster dimensions. Values > 1 upscale, values < 1 downscale.

  • method : rasterio.enums.Resampling, optional Resampling method to use. Defaults to rasterio.enums.Resampling.bilinear.

• **tags (dict) – Band selection criteria. See Source.get_bidx() for details. Tags need to present to the source file.

Returns:

A dictionary with the following entries:

• data : The loaded raster data. Shape depends on band selection and scaling.

• transform : affine.Affine transform mapping array coordinates to spatial coordinates.

• orig_profile : Copy of the original raster profile metadata.

Return type:

dict

See also

load_block()

Underlying function with full parameter details.

mask_reader(**kwargs)

Context manager for reading the dataset mask.

Opens the source file and yields its dataset_mask method, which can be called to read the internal mask as an array.

Parameters:

**kwargs (dict) – Keyword arguments passed to open().

Yields:

callable – A callable that can be used to read the mask.

mask_writer(**kwargs)

Context manager for writing to the dataset mask.

Opens the source file with internal TIFF mask support enabled and yields the write_mask method of the underlying dataset.

Parameters:

**kwargs (dict) – Keyword arguments passed to open().

Yields:

callable – A callable that can be used to write a mask array.

open(*args, **kwargs)

Open the source file for I/O operations.

This context manager wraps the underlying rasterio dataset, yielding an open dataset object. If the file is openend in writing mode the profile is injected into the open function. Therefore: the profile needs to be set when calling this method with writing mode!

Parameters:

• *args (tuple) – Positional arguments forwarded to _get_source().

• **kwargs (dict) – Keyword arguments forwarded to _get_source().

Yields:

DatasetReader or DatasetWriter – Open rasterio dataset object, ready for reading or writing.

set_tags(bidx, tags)

Set one or more tags for a specific band or the dataset.

Tags are serialized via serialize() before being written to the file by _set_tags().

Parameters:

• bidx (int or None) – The band index to set tags for. If None, tags are applied to the Source metadata (bidx=0).

• tags (dict) – A dictionary of key-value pairs to assign as tags.

Return type:

None

See also

get_tags()

Read and deserialize tags for a band.

property band_indexes

Band indexes available in the source.

Returns:

The band indexes present in the dataset.

Return type:

list

property exists: bool

Check whether the source file exists on disk.

Returns:

True if the file exists, False otherwise.

Return type:

bool

path

profile

property shape: tuple[int, int]

Return the numpy shape of the data stored in this Source.

Requesting the shape will synchronize the profile with the data written on disk.

Returns:

A 2-tuple (height, width) representing the dataset dimensions.

Return type:

tuple

tags