riogrande.io.models =================== .. py:module:: riogrande.io.models .. autoapi-nested-parse:: Data model classes for GeoTIFF raster sources and bands. This module defines :class:`Source` and :class:`Band`, the two central data model classes of the ``riogrande`` package. A :class:`Source` represents a single GeoTIFF file together with its metadata (tags, profile, namespace), while a :class:`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 ------- .. autoapisummary:: riogrande.io.models.Band riogrande.io.models.Source Module Contents --------------- .. py:class:: Band A ``Band`` object encapsulates metadata and configuration for accessing a band in a raster dataset. It references a parent :class:`Source` object, contains band-specific tags, and holds parameters for reading. :param source: The ``Source`` object from which this band originates. :type source: Source :param tags: Optional dictionary of key-value metadata associated with the band. Defaults to an empty dictionary. :type tags: dict :param bidx: Band index in the source dataset (1-based). If ``None``, defaults to an implicit index or is determined at runtime. :type bidx: int or None :param read_params: Dictionary of parameters controlling how the band is read (e.g., windowing, resampling). Defaults to an empty dictionary. :type read_params: dict .. rubric:: 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' .. py:method:: __hash__() Compute a hash value for the Band. :returns: Hash value for the object. :rtype: int .. py:method:: __repr__() Return a string representation of the Band's tags. :returns: String representation of the tags. :rtype: str .. py:method:: 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 :func:`numpy.add`, and the result is stored in ``out_band`` or overwrites this band by default. :param band: :class:`Band` whose values will be added. :type band: Band :param out_band: Destination :class:`Band` for storing the result. If None (default), the operation overwrites this band. :type out_band: Band or None :param \*\*add_kwargs: Additional keyword arguments passed to :func:`numpy.add`. :type \*\*add_kwargs: dict .. seealso:: :meth:`subtract` Element-wise subtraction of another band. .. py:method:: 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 :func:`~riogrande.helper.count_contribution`. :param selector: Boolean :class:`numpy.ndarray` of the same shape as the band, indicating which pixels to include in the count. If None, all pixels are considered. :type selector: NDArray or None :param no_data: Pixel value considered invalid (e.g., nodata value). :type no_data: int or float :param limit_count: 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. :type limit_count: int :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. :rtype: int or bool .. seealso:: :func:`~riogrande.helper.count_contribution` Per-block pixel counting function. :meth:`get_min_max` Compute the min/max of valid pixels. .. py:method:: 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. :param match: Optional selection of tags to identify a matching band. Ignored if the band has ``bidx`` set. :type match: str or list or None :param \*\*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. .. py:method:: 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. :param match: Optional selection of tags to identify a matching band. Ignored if the band has ``bidx`` set. :type match: str or list or None :param \*\*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. .. py:method:: export_tags(match = None) Write the band’s set tags back to the source file. The band index is resolved with :meth:`get_bidx` and the tags are written via :meth:`~riogrande.io.models.Source.set_tags`. :param match: 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. :type match: str or list or None .. rubric:: 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 .. seealso:: :meth:`import_tags` Load tags from the source file into this band object. :meth:`get_bidx` Resolve the band index in the source file. .. py:method:: 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 :class:`Source` file. If ``bidx`` is None, the method tries to infer the correct band index using the ``tags`` attribute via :meth:`~riogrande.io.models.Source.find_index`. The optional ``match`` argument can limit which tags are considered for matching. :param match: 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. .. rubric:: 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 :type match: str or list or None :returns: Index of the band in the ``Source`` that matches this band. :rtype: int :raises ~riogrande.io.exceptions.BandSelectionNoMatchError: If there is no clear match for the band in the source file or if the specified ``bidx`` does not exist. .. seealso:: :meth:`export_tags` Write tags using the resolved band index. :meth:`import_tags` Load tags using the resolved band index. .. py:method:: 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``. :param \*\*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. :rtype: NDArray .. py:method:: 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 :meth:`mask_reader`, the dataset mask via :meth:`~riogrande.io.models.Source.mask_reader`, or return a constant array via :meth:`_mask_full`. :rtype: Callable :raises ~riogrande.io.exceptions.InvalidMaskSelectorError: If `_use_mask` has an invalid value. .. seealso:: :meth:`set_mask_reader` Configure which mask to use. .. py:method:: 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 :func:`numpy.nanmin` / :func:`numpy.nanmax`. :param no_data: Value considered invalid; these pixels are ignored. :type no_data: int or float :param selector: Boolean :class:`numpy.ndarray` of the same shape as the band, indicating which pixels to include. If None, all pixels are considered. :type selector: NDArray or None :returns: Tuple (min_value, max_value) over the selected valid pixels. Returns None if no valid pixels are found. :rtype: tuple of (float, float) or None .. seealso:: :meth:`count_valid_pixels` Count valid (non-nodata) pixels. .. py:method:: 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 :meth:`get_bidx` and tags are read via :meth:`~riogrande.io.models.Source.get_tags`. :param match: Optional selection of tags to match a band in the source file. Used internally by :meth:`get_bidx` to locate the correct band. :type match: str or list or None :param keep: If True, update the existing ``tags`` dictionary with the imported tags. If False, replace the existing ``tags`` dictionary with the imported tags. :type keep: bool .. seealso:: :meth:`export_tags` Write this band's tags back to the source file. .. py:method:: 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. :param profile: Dictionary specifying the profile of the dataset. This will update the source's profile before creating or opening the file. :type profile: dict :param overwrite: If True, any existing file at the source path will be overwritten. Equivalent to deleting the existing source and creating a new one. :type overwrite: bool :param \*\*kwargs: Additional keyword arguments passed to the underlying ``Source.init_source`` method. .. py: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 :func:`~riogrande.io.core.load_block` via :meth:`~riogrande.io.models.Source.load_block`. See :func:`~riogrande.io.core.load_block` for further details. :param view: Optional window defined as (x, y, width, height) in pixels. If `None`, the entire band is read. :type view: tuple[int, int, int, int] or None :param scaling_params: 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) :type scaling_params: dict or None :param match: Optional tag(s) or criteria to identify the band in the source. If `None`, the current `bidx` or all tags are used. :type match: str or list or None :returns: Dictionary containing: - ``data``: :class:`numpy.ndarray` with the band data of shape (1, height, width) - ``transform``: :class:`affine.Affine` transformation object for the loaded block - ``orig_profile``: Original raster profile of the source band :rtype: dict[str, Any] .. seealso:: :meth:`~riogrande.io.models.Source.load_block` Analogous method on the Source class. :func:`~riogrande.io.core.load_block` Underlying function with full parameter details. .. py:method:: mask_reader(match = None, **kwargs) Context manager for reading the band-specific mask. Always returns the mask associated with this specific band. :param match: Optional selection of tags to identify the band. :type match: str or list or None :param \*\*kwargs: Keyword arguments passed to `Source.open`. :Yields: *Callable* -- Partial function to read the band mask. .. py:method:: set_data(data, overwrite = False, **kwargs) Write data to the band in the underlying source file. Uses :meth:`data_writer` as the context manager for writing. :param data: :class:`numpy.ndarray` containing the data to write. :type data: NDArray :param overwrite: If True, overwrite an existing source file. If False and the source exists, the file is opened in update mode (``'r+'``). :type overwrite: bool :param \*\*kwargs: Additional keyword arguments passed to :meth:`data_writer`. .. seealso:: :meth:`get_data` Read the full data array of this band. :meth:`data_writer` Context manager used for writing. .. py:method:: set_mask_reader(use = 'band') Set which mask should be used when reading data for this band. :param use: Determines how the mask is applied: - ``'self'`` or ``'band'``: use the band-specific mask (i.e., :meth:`rasterio.io.DatasetReader.read_masks`). - ``'source'``: use the dataset mask from the source (i.e., :meth:`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). :type use: {'self', 'band', 'source', 'mask_none', 'mask_all'}, default 'band' :raises AssertionError: If `use` is not one of the allowed options. .. seealso:: :meth:`get_mask_reader` Return the mask-reading callable based on the current setting. .. py:method:: 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 :func:`numpy.add`. The result is stored in ``out_band`` or overwrites this band by default. :param band: :class:`Band` to subtract from this band. :type band: Band :param out_band: Destination :class:`Band` for storing the result. If None (default), the operation overwrites this band. :type out_band: Band or None :param \*\*sub_kwargs: Additional keyword arguments passed to the underlying operation. :type \*\*sub_kwargs: dict .. seealso:: :meth:`add` Element-wise addition of another band. .. py:attribute:: bidx :type: int | None :value: None .. py:property:: index_exists :type: 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. :rtype: bool .. py:attribute:: read_params :type: dict .. py:property:: shape :type: 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. :rtype: tuple of int .. py:attribute:: source :type: Source .. py:property:: source_exists :type: 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. :rtype: bool .. py:property:: status :type: 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. .. py:attribute:: tags :type: dict .. py:class:: 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. :param path: Path to the dataset file. :type path: str or Path :param tags: Optional dictionary of key-value metadata associated with the source. Defaults to an empty dictionary. :type tags: dict or None :param profile: Optional dictionary of dataset profile information (e.g. width, height, dtype). Defaults to an empty dictionary. :type profile: dict or None :param ns: Namespace string used to distinguish sources. Defaults to "GEORACOON". :type ns: str .. rubric:: Examples >>> s1 = Source("example.tif", tags={"type": "satellite"}) >>> s1 Source(path=example.tif, exists: False) >>> s1.tags {'type': 'satellite'} >>> s1._ns 'GEORACOON' .. py:method:: __eq__(other) Test equality between two Source objects. :param other: Source object to compare against. :type other: Source :returns: True if both objects are Source instances with the same path, tags, and namespace. :rtype: bool .. py:method:: __hash__() Compute a hash value for the Source. :returns: Hash based on path, namespace, and tag values. :rtype: int .. py:method:: __repr__() Return a string representation of the Source. :returns: String representation of the object. :rtype: str .. py:method:: check_compatibility(*sources) Check whether this source is compatible with one or more other sources. Delegates to :func:`~riogrande.helper.check_compatibility`, which verifies CRS, linear units, and spatial resolution. :param \*sources: One or more additional :class:`Source` objects to check against this one. :type \*sources: Source :returns: True if all provided sources are compatible with this one. :rtype: bool .. seealso:: :func:`~riogrande.helper.check_compatibility` Underlying compatibility check. .. py:method:: compress(output = None, compression = 'lzw', keep_original = False) Compress the source file using a given compression algorithm. A new compressed GeoTIFF is created via :func:`~riogrande.io.core.compress_tif`. By default, the original file is replaced with the compressed one unless `keep_original` is set. :param output: Path to the output file. If None (default), the compressed file overwrites the current source path. :type output: str or None :param compression: Compression algorithm to use. Default is ``'lzw'``. See GDAL documentation for valid options. :type compression: str or None :param keep_original: If True, the original uncompressed file is preserved. If False (default), the uncompressed file is deleted after compression. :type keep_original: bool :rtype: None .. rubric:: Notes - Updates the ``path`` attribute of the Source to point to the new compressed file. .. seealso:: :func:`~riogrande.io.core.compress_tif` Underlying compression function. .. py:method:: 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). :param bands: A collection of ``Band`` objects specifying which bands to read. If None, all bands in the dataset are used. :type bands: list[Band] or None :param \*\*kwargs: Additional keyword arguments forwarded to :meth:`open` (e.g., mode, driver options). :type \*\*kwargs: dict :Yields: *callable* -- A callable equivalent to ``src.read(indexes=...)`` that returns a 3D numpy array with shape `(len(bands), height, width)`. .. py:method:: export_mask(mask, window) Write a mask into the source file. :param mask: Array to use as a mask. Values greater than 0 represent valid pixels; 0 represents invalid/masked pixels. :type mask: NDArray :param window: The raster window to which the mask should be written. :type window: Window :rtype: None .. py:method:: find_index(tags) Find a single band index matching the given tags. :param tags: Tag key–value pairs to search for. :type tags: dict :returns: The band index if exactly one match is found, None otherwise. :rtype: int or None .. py:method:: find_indexes(tags, mode = 'all') Find band indexes matching the given tags. :param tags: Tag key–value pairs to search for. :type tags: dict :param mode: Matching mode: - 'all': All provided tags must be present. - 'any': Any one of the provided tags may match (currently not implemented, placeholder). :type mode: str :returns: The list of band indexes matching the tags. :rtype: list of int .. py:method:: get_band(bidx = None, **tags) Retrieve a specific band as a Band object. A :class:`Band` can be selected either by its index (`bidx`) or by matching tags. If both are provided, they must match the same band. :param bidx: Optional band index to select. :type bidx: int or None :param \*\*tags: Optional tag key-value pairs to match the band via :func:`~riogrande.io.core._get_bidx_by_tag`. :type \*\*tags: dict :returns: A ``Band`` object corresponding to the requested band, including associated tags. :rtype: :class:`Band` :raises ~riogrande.io.exceptions.SourceNotSavedError: If the source file does not exist on disk. :raises ~riogrande.io.exceptions.BandSelectionNoMatchError: If no band matches the provided index or tags. :raises AssertionError: If the index and tag selection refer to different bands. .. seealso:: :meth:`get_bands` Return all bands in the dataset. .. py:method:: get_bands() Return all bands present in the dataset. :returns: A list of ``Band`` objects for all bands in the dataset. :rtype: list of :class:`Band` .. seealso:: :meth:`get_band` Retrieve a single band by index or tags. .. py:method:: 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. :param band: The Band object for which to resolve the band index. :type band: Band :returns: The resolved band index if a unique match is found, otherwise None. :rtype: 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. .. py:method:: get_mask(**kwargs) Read the dataset mask from the file. Except `okwargs` all keyword arguments are passed to the :meth:`rasterio.io.DatasetReader.dataset_mask` method of the source via :meth:`mask_reader`. :param \*\*kwargs: Optional set of keyword arguments to pass to the ``read`` method of the source. Notable exception: if ``okwargs`` is present, it is passed to :meth:`open` when accessing the source. :type \*\*kwargs: dict :returns: An array representing the dataset mask. Non-zero values indicate valid pixels, and 0 indicates masked/invalid pixels. :rtype: NDArray .. seealso:: :meth:`mask_reader` Context manager yielding the underlying mask-read callable. .. py:method:: 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. :param tag: The tag key to look up. :type tag: str :param bidx: Band index (int), list of indices, or None. If None, all bands are queried. :type bidx: int or list or None :returns: A mapping of band index to the tag value (or None if missing). :rtype: dict .. py:method:: get_tags(bidx) Retrieve all tags for a specific band. Reads and deserializes tags via :func:`~riogrande.io.core._get_tags`. :param bidx: The band index to query. :type bidx: int :returns: A dictionary of tag key-value pairs associated with the band. :rtype: dict .. seealso:: :meth:`set_tags` Write tags back to the source file. :meth:`get_tag_values` Fetch values for a single tag key across multiple bands. .. py:method:: has_band(band) Check whether a given Band is present in the source. :param band: The band object to test for. :type band: Band :returns: True if the band is present. :rtype: bool .. py:method:: has_bidx(bidx) Check whether a band index exists in the source. :param bidx: The band index to check for (1-based, as in rasterio). :type bidx: int :returns: True if the band index exists in the dataset. :rtype: bool .. py:method:: has_tags(tags) Check whether any band contains all the provided tags. :param tags: Dictionary of tag key–value pairs to look for. :type tags: dict :returns: True if at least one band contains all provided tags. :rtype: bool .. py:method:: import_profile(update_self = True) Read the profile from the source file Opens the file via :meth:`open` and reads the rasterio profile. :param update_self: If True (default), update the ``profile`` attribute with the values fetched from the source file. If False, the object's profile remains unchanged. :type update_self: bool :returns: The profile dictionary retrieved from the source file. :rtype: dict .. seealso:: :meth:`init_source` Create or overwrite the source file using the stored profile. .. py:method:: 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 :meth:`open`. If ``overwrite`` is True, the existing file will be replaced. :param overwrite: If True, overwrite an existing file. :type overwrite: bool :param \*\*kwargs: Additional keyword arguments passed to the :meth:`open` method when creating the dataset (e.g., driver options, compression). :type \*\*kwargs: dict :rtype: None .. seealso:: :meth:`import_profile` Read the profile from an existing source file. .. py:method:: 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 :func:`~riogrande.io.core.load_block` for further details. :param view: The window to read, given as (row_start, row_stop, col_start, col_stop). If None (default), the entire raster is read. :type view: tuple[int, int, int, int] or None :param scaling_params: 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 :data:`rasterio.enums.Resampling.bilinear`. :type scaling_params: dict, optional :param \*\*tags: Band selection criteria. See :meth:`Source.get_bidx` for details. Tags need to present to the source file. :type \*\*tags: dict :returns: A dictionary with the following entries: - ``data`` : The loaded raster data. Shape depends on band selection and scaling. - ``transform`` : :class:`affine.Affine` transform mapping array coordinates to spatial coordinates. - ``orig_profile`` : Copy of the original raster profile metadata. :rtype: dict .. seealso:: :func:`~riogrande.io.core.load_block` Underlying function with full parameter details. .. py:method:: 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. :param \*\*kwargs: Keyword arguments passed to :meth:`open`. :type \*\*kwargs: dict :Yields: *callable* -- A callable that can be used to read the mask. .. py:method:: 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. :param \*\*kwargs: Keyword arguments passed to :meth:`open`. :type \*\*kwargs: dict :Yields: *callable* -- A callable that can be used to write a mask array. .. py:method:: 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!** :param \*args: Positional arguments forwarded to :meth:`_get_source`. :type \*args: tuple :param \*\*kwargs: Keyword arguments forwarded to :meth:`_get_source`. :type \*\*kwargs: dict :Yields: *DatasetReader or DatasetWriter* -- Open rasterio dataset object, ready for reading or writing. .. py:method:: set_tags(bidx, tags) Set one or more tags for a specific band or the dataset. Tags are serialized via :func:`~riogrande.helper.serialize` before being written to the file by :func:`~riogrande.io.core._set_tags`. :param bidx: The band index to set tags for. If None, tags are applied to the Source metadata (bidx=0). :type bidx: int or None :param tags: A dictionary of key-value pairs to assign as tags. :type tags: dict :rtype: None .. seealso:: :meth:`get_tags` Read and deserialize tags for a band. .. py:property:: band_indexes Band indexes available in the source. :returns: The band indexes present in the dataset. :rtype: list .. py:property:: exists :type: bool Check whether the source file exists on disk. :returns: True if the file exists, False otherwise. :rtype: bool .. py:attribute:: path .. py:attribute:: profile .. py:property:: shape :type: 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. :rtype: tuple .. py:attribute:: tags