riogrande.io.core ================= .. py:module:: riogrande.io.core .. autoapi-nested-parse:: Low-level I/O functions for reading and writing GeoTIFF raster data. This module provides the functional layer beneath :class:`~riogrande.io.models.Source` and :class:`~riogrande.io.models.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`` :class:`~rasterio.io.DatasetWriter` or :class:`~rasterio.io.DatasetReader` objects and are called internally by the :class:`~riogrande.io.models.Source` and :class:`~riogrande.io.models.Band` class methods. Attributes ---------- .. autoapisummary:: riogrande.io.core.NS Functions --------- .. autoapisummary:: riogrande.io.core.compress_tif riogrande.io.core.coregister_raster riogrande.io.core.get_bands_by_tag riogrande.io.core.load_block riogrande.io.core.update_band riogrande.io.core.write_band Module Contents --------------- .. py:function:: compress_tif(source, output = None, compression = 'lzw') Compress tif file with LZW compression Band tags are copied band-by-band using :func:`~riogrande.io.core._get_tags` and :func:`~riogrande.io.core._set_tags`. :param source: The path to the tif file you want to compress :type source: str :param output: Optional path to output file. If not set, the resulting file will inherit the filename from ``source`` and get a ``_compress`` appendix via :func:`~riogrande.helper.output_filename`. If compression is ``'none'``, i.e. no compression the appendix will be ``'_decompressed'``. :type output: str or None :param compression: Type of compression to use, default is LZW. See GDAL documentation for details. :type compression: str or None :returns: The name of the compressed file :rtype: str .. seealso:: :meth:`~riogrande.io.models.Source.compress` Convenience wrapper on the :class:`~riogrande.io.models.Source` class. .. py:function:: coregister_raster(source, reference, output = None) Align raster to have identical resolution. Resolution will be calculated automatically from bounds and height/width of reference raster using :func:`rasterio.warp.calculate_default_transform`. Reprojection is performed with :func:`rasterio.warp.reproject` and :attr:`rasterio.enums.Resampling.nearest`. CRS compatibility is verified with :func:`~riogrande.helper.check_crs`. :param source: The path to the tif file you want to co-register :type source: str :param reference: The path to the tif file with the pixel registration to use as reference for co-registration :type reference: str :param output: The path to write the co-registered map to. If ``None``, a filename is generated by :func:`~riogrande.helper.output_filename`. :type output: str or None :returns: The name of the file that holds co-registered map :rtype: str .. py:function:: get_bands_by_tag(source, ns = NS, **tags) 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). :param source: A glob pattern string passed to :func:`glob.glob`, leading to (potentially) multiple source files that will be checked. :type source: str :param ns: 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. :type ns: str :param \*\*tags: Arbitrary number of keyword arguments that will be compared to the tags of each tif file. :type \*\*tags: Any :returns: A list of tuples with source (path) and bandindex entries in tuples. :rtype: list .. seealso:: :func:`~riogrande.io.core._get_bidx_by_tag` Find a single band in one open dataset. :func:`~riogrande.io.core._find_bidxs` Return all matching band indexes in one dataset. .. py:function:: load_block(source, view = None, scaling_params = None, **tags) 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 :class:`rasterio.windows.Window` via :func:`~riogrande.helper.view_to_window`). :param source: The path to the tif file to load :type source: str :param view: An optional tuple (x, y, width, height) defining the area to load. If ``None`` is provided (the default) then the entire file is loaded. :type view: tuple[int, int, int, int] or None :param scaling_params: Optional dictionary to set a rescaling of the data. If provided, the following keywords are accepted: scaling : tuple[float, float] Factors to rescale the number of pixels. Values >1 will upscale. method : rasterio.enums.Resampling The resampling method. If not provided then :attr:`rasterio.enums.Resampling.bilinear` is used. :type scaling_params: dict or None :param \*\*tags: Arbitrary number of keyword arguments to describe the band to select. See :func:`~riogrande.io.core._get_bidx_by_tag` for further details. :type \*\*tags: Any :returns: data: holding a numpy array with the actual data transform: an :class:`affine.Affine` object that encodes the transformation used orig_profile: The profile information of the original .tif file :rtype: dict .. seealso:: :func:`~riogrande.io.core.write_band` Write data to a specific band. :func:`~riogrande.helper.view_to_window` Convert a view tuple to a rasterio Window. .. py:function:: update_band(src, data, window = None, **tags) Find a specific band and update it with data This function writes a data array in a band specified with tags, identified via :func:`~riogrande.io.core._get_bidx_by_tag`. If no band with the matching tags is found a :exc:`~riogrande.io.exceptions.BandSelectionNoMatchError` is raised. :param src: ``tif`` file opened with :func:`rasterio.open` :type src: DatasetWriter :param data: The array to write into the file :type data: NDArray :param window: An optional :class:`rasterio.windows.Window` to specify an area to write. :type window: Window or None :param \*\*tags: Arbitrary number of keyword arguments that will be used to find the band to write into. :type \*\*tags: Any :rtype: None .. seealso:: :func:`~riogrande.io.core.write_band` Write to a band by explicit index. .. py:function:: write_band(src, data, bidx = 1, window = None, **tags) Write data to a specific band of a tif file and set the tags :param src: ``tif`` file opened with :func:`rasterio.open` :type src: DatasetWriter :param data: The array to write into the file :type data: NDArray :param bidx: Band index to write into the file :type bidx: int :param window: An optional :class:`rasterio.windows.Window` to specify an area to write. :type window: Window or None :param \*\*tags: Arbitrary number of keyword arguments that will be set as tags. The value provided is converted to a string with :func:`~riogrande.helper.serialize` via :func:`~riogrande.io.core._set_tags` before being written to the file. :type \*\*tags: Any :rtype: None .. seealso:: :func:`~riogrande.io.core.update_band` Find a band by tags and update it. :func:`~riogrande.io.core.load_block` Load a block of data from a band. .. py:data:: NS :value: 'GEORACOON'