Rastereasy Library ================== Overview and structuration -------------------------- The rastereasy library provides functions for the easy manipulation (resampling, cropping, reprojection, tiling, ...) and visualization (color composites, spectra) of geospatial raster and vector data (e.g., *.tif, *.jp2, *.shp). It simplifies geospatial workflows with efficiency. A geospatial image is read and represented within the :class:`~rastereasy.Geoimage` class, which contains most of the required functions for processing and visualization. Other classes are related to :class:`~rastereasy.InferenceTools` (some functions related to clustering, domain adaptation, fusion) :class:`~rastereasy.shpfiles` or :class:`~rastereasy.rasters` (to deal with shapefiles and rasters respectively) The goal of `rastereasy` is to simplify geospatial workflows by offering tools for: - Reading and processing raster and vector files. - Resampling, cropping, reprojecting, stacking, ... raster images. - Applying classic filters (gaussian, median, laplace, sobel) and generic ones. - Creating visualizations such as color composites or spectral analyses. - Use (train / apply) some classical Machine Learning algorithms. - Provide some tools for late fusion of classifications (Dempster-Shafer). - Provide some tools for some ML algorithms, basic domain adaptation, ... - ... The Geoimage class ------------------ The :class:`~rastereasy.Geoimage` class contains most of the required functions for processing and visualization. Other classes are related to :class:`~rastereasy.InferenceTools` (some functions related to clustering, domain adaptation, fusion) :class:`~rastereasy.shpfiles` or :class:`~rastereasy.rasters` (to deal with shapefiles and rasters respectively). Apart from :class:`~rastereasy.Geoimage` class, **rastereasy** also provides functions to handle bounding boxes (e.g., extracting common areas between two images, or extending the spatial area of an image to match the extent of another) and to create stacks from individual band files (see in examples). The Geoimage object is the core of the **rastereasy** library. It acts as a wrapper around a NumPy array, enriched with essential geospatial metadata like its Coordinate Reference System (CRS), spatial resolution, nodata information and geotransform. It provides a wide range of intuitive methods for data processing, analysis, and visualization. **Attributes** ============= .. attribute:: image :type: numpy.ndarray The raw pixel data of the image as a NumPy array. The shape is typically (rows, columns, bands). .. attribute:: names :type: dict A dictionary mapping band numbers or default keys to band names. Example: ``{'1': 'Red', '2': 'Green', ...}``. .. attribute:: nb_bands :type: int The total number of spectral bands in the image. .. attribute:: shape :type: tuple The shape of the image as (rows, columns). .. attribute:: resolution :type: float or tuple The spatial resolution of the pixels (e.g., ``10.0`` for square pixels). .. attribute:: nodata :type: float The kind of nodata **Key Methods** =============== General information ------------------- .. method:: info() Print detailed information about the image. Data Manipulation & Transformation ------------------------------------ .. method:: save(path) Saves the Geoimage to a file (e.g., GeoTIFF), preserving geospatial metadata. .. method:: crop(bbox) Crops the image to a specified bounding box. .. method:: resample(scale_factor) Changes the spatial resolution of the image. .. method:: reproject(projection) Transforms the image to a new Coordinate Reference System. .. method:: stack(other_geoimage) Combines the current Geoimage with another one into a multi-band image. .. method:: select_bands(bands) Extracts one or more spectral bands by name or index. .. method:: switch_band() Change the position of a specified band in the image. .. method:: remove_bands() Remove specified bands from the image. .. method:: standardize() Applies standardization to the image bands. .. method:: inverse_standardize() Revert standardization. .. method:: filter(kernel_type, sigma) Applies a spatial filter (e.g., 'gaussian', 'sobel') to the image. .. method:: kmeans(n_clusters) Performs K-Means clustering on the image pixels using their band values as features. Operators & Comparisons ------------------------- The class overloads standard operators for intuitive element-wise algebra: * **Arithmetic**: ``+``, ``-``, ``*``, ``/``, ``**`` can be used with scalars or other Geoimage objects. * **Comparison**: ``<``, ``>``, ``!=``, ``==``, ``<=``, ``>=`` produce boolean masks. * **Boolean operation**: ``and``, ``or``, ``xor``, ``isnan()`` produce boolean masks. .. method:: replace_values(value_to_replace, new_value) Change some specific values in the image .. method:: astype(dtype) Convert the image data to a specified data type. .. method:: percentage_pixels(value) Percentage of pixels with a specific value .. method:: where(condition, value1, value2) Select values based on a condition, similar to numpy.where(). Statistics ---------- .. method:: min(axis) Minimal values along various axes .. method:: max(axis) Maximal values along various axes .. method:: median(axis) Median values along various axes .. method:: sum(axis) Sum of values along various axes .. method:: mean(axis) Mean of values along various axes .. method:: std(axis) Standard deviation of values along various axes .. method:: abs() Absolute values Coordinate information ----------------------- .. method:: get_meta() Get the metadata dictionary. .. method:: get_bounds() Get the geographic bounds of the image. .. method:: latlon2pixel(coord_lat, coord_lon) Convert geographic coordinates (latitude, longitude) to pixel coordinates. .. method:: pixel2latlon(i, j) Convert pixel coordinates to geographic coordinates (latitude, longitude). Visualization & Analysis -------------------------- .. method:: visu() Displays a quick visualization of the image. .. method:: hist() Plots histograms of the band values. .. method:: colorcomp(bands=['Red', 'Green', 'Blue']) Creates and displays a false-color composite image from specified bands. .. method:: plot_spectra(pixel) Plots the spectral signature for a given pixel coordinate. Numpy tables ------------ .. method:: numpy_channel_first() Extract image data as a NumPy array in channel-first format. .. method:: numpy_channel_last() Extract image data as a NumPy array in channel-last format. .. method:: numpy_table() Extract image data as a 2D table of shape (pixels, bands). .. method:: image_from_table() Create a new Geoimage from a 2D table of shape (pixels, bands) .. method:: upload_image() Update the image data with a new image array. Machine learning ---------------- .. method:: kmeans() Perform K-means clustering on the image data. .. method:: predict() Apply a pre-trained machine learning model to the image. .. method:: adapt() Adjust spectral characteristics to match a target image. .. method:: fuse_dempster_shafer_2() Fuse the 3 band image (associated with mass functions) from multiple sources using Dempster-Shafer theory with two hypotheses: A and B. Attribute manipulation ---------------------- .. method:: reset_names() Reset the band names to sequential numbers ("1", "2", ...). .. method:: change_nodata() Modify the no-data value of the image. .. method:: change_names() Modify the names of spectral bands. .. method:: activate_history() Activate history tracking for the image object. .. method:: copy() Create a deep copy of the Geoimage object. Shapefiles ---------- .. method:: extract_from_shapefile() Extract data from areas matching a shapefile attribute value. .. method:: extract_from_shapeimage() Extract data from areas matching a shape image value. .. note:: This module requires external dependencies such as `rasterio`, `numpy`, and `matplotlib`. .. contents:: Table of Contents :depth: 2 :local: Simple start example -------------------- Here is a quick overview of what you can do with rastereasy: .. code-block:: python import rastereasy # Load a georeferenced image image = rastereasy.Geoimage("example.tif") # Get image information image.info() # Create a color composite image.colorcomp(['4', '3', '2']) # Resample and reproject image_resampling = image.resample(2) image_reprojected = image.reproject("EPSG:4326") # Save the processed image image.save("processed_image.tif") Using and citing the toolbox ----------------------------- If you use this toolbox in your research, please cite it as: Corpetti, T., Matelot, P., de la Brosse, A., & Lissak, C. (2025). *Rastereasy: A Python package for easy manipulation of remote sensing images*. Manuscript submitted for publication, Journal of Open Source Software. Some interesting functions --------------------------- Below are some of the primary functions provided by the module: Resampling Function ~~~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.resample Projection Function ~~~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.reproject Cropping Function ~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.crop Machine Learning ~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.kmeans .. autofunction:: rastereasy.Geoimage.predict Band manipulation ~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.stack .. autofunction:: rastereasy.Geoimage.reorder_bands .. autofunction:: rastereasy.Geoimage.remove_bands Filtering ~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.filter Access to numpy ~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.numpy_channel_first .. autofunction:: rastereasy.Geoimage.numpy_channel_last .. autofunction:: rastereasy.Geoimage.image_from_table Processing on images ~~~~~~~~~~~~~~~~~~~~ .. autofunction:: rastereasy.Geoimage.adapt .. autofunction:: rastereasy.Geoimage.fuse_dempster_shafer_2hypotheses .. autofunction:: rastereasy.Geoimage.image_from_table Additional Notes ---------------- Refer to the examples in the :doc:`examples gallery ` section for practical applications of the library.