rastereasy package

Submodules

rastereasy.rastereasy module

Core module for the rastereasy package. Contains the main Geoimage class and utility functions for raster processing.

rastereasy.rastereasy.read_geoim(source_name, read_image=True, channel_first=True)

Read a geotiff image file.

Parameters

source_namestr

Path to the geotiff image file

read_imagebool, optional

If True, read both image data and metadata. If False, read only metadata. Default is True.

channel_firstbool, optional

If True, return image with shape (bands, rows, cols). If False, return image with shape (rows, cols, bands). Only relevant when read_image is True. Default is True.

Returns

numpy.ndarray or None

Image data if read_image is True, None otherwise

dict

Metadata dictionary from rasterio

Examples

>>> # Read image data and metadata
>>> image, meta = read_geoim("path/to/image.tif")
>>>
>>> # Read only metadata
>>> meta = read_geoim("path/to/image.tif", read_image=False)

rastereasy.rastereasy.write_geoim(im, meta_input, dest_name, channel_first=True)

Write a geotiff image to disk.

Parameters

imnumpy.ndarray

Image data to write

meta_inputdict

Metadata dictionary with rasterio metadata fields

dest_namestr

Output path for the geotiff file

channel_firstbool, optional

If True, assumes image has shape (bands, rows, cols). If False, assumes image has shape (rows, cols, bands). Default is True.

Examples

>>> write_geoim(image, metadata, "output.tif")

rastereasy.rastereasy.diff_im(im1, im2)

Calculate the L1 norm (sum of absolute differences) between two Geoimages.

Parameters

im1Geoimage

First image

im2Geoimage

Second image

Returns

float

L1 norm of the difference between the images

rastereasy.rastereasy.im2tiles_sequence(source_name, dest_name, nb_row, nb_col, overlap=0, type_name='sequence', verbose=0)

Split a sequence of GeoTIFF images into tiles.

Parameters

source_namestr

Directory containing the GeoTIFF images.

dest_namestr

Destination directory for tiled images.

nb_rowint

Number of rows in each tiled image.

nb_colint

Number of columns in each tiled image.

overlapint, optional

Overlap between tiles in pixels. Default is 0.

type_namestr, optional

Naming convention for output tiles: - “sequence”: Outputs as name_tif_001.tif, name_tif_002.tif, etc. - “coord”: Outputs as name_tif_tiles_{row}-{col}.tif. Default is “sequence”.

verboseint, optional

If 1, prints information about processed images. Default is 0.

Raises

ValueError

If type_name is not “sequence” or “coord”.

Examples

>>> im2tiles_sequence(
>>>      source_name="/path/to/source",
>>>      dest_name="/path/to/destination",
>>>      nb_row=256,
>>>      nb_col=256,
>>>      overlap=10,
>>>      type_name="sequence",
>>>      verbose=1)

rastereasy.rastereasy.im2tiles(source_name, dest_name, nb_row, nb_col, overlap=0, type_name='sequence', verbose=0, name_tile=None)

Split a geotif image into tiles.

Parameters

source_namestr

A tif file to be split.

dest_namestr

Destination directory for tiled images.

nb_rowint

Number of rows in each tiled image.

nb_colint

Number of columns in each tiled image.

overlapint, optional

Overlap between tiles in pixels. Default is 0.

type_namestr, optional

Naming convention for output tiles. Either “sequence” or “coord”. Default is “sequence”.

verboseint, optional

If 1, prints information about processed images. Default is 0.

name_tilestr, optional

Generic name for output tiles. If None, uses source_name without extension. Default is None.

Raises

ValueError

If type_name is not “sequence” or “coord”.

Examples

>>> im2tiles(
>>>      source_name="input.tif",
>>>      dest_name="/path/to/destination",
>>>      nb_row=256,
>>>      nb_col=256,
>>>      overlap=10,
>>>      type_name="sequence")

rastereasy.rastereasy.crop_rio(data, deb_row, end_row, deb_col, end_col, dest_name=None, meta=None, channel_first=True)

Crop a georeferenced image.

Parameters

datastr or numpy.ndarray

Path to a GeoTIFF image or a numpy array containing image data. If a numpy array is provided, meta must also be provided.

deb_rowint

Starting row coordinate (pixel).

end_rowint

Ending row coordinate (pixel).

deb_colint

Starting column coordinate (pixel).

end_colint

Ending column coordinate (pixel).

dest_namestr, optional

Path to save the cropped image. If None, the image is not saved. Default is None.

metadict, optional

Metadata dictionary (required if data is a numpy array). Default is None.

channel_firstbool, optional

If True, assumes/returns image with shape (bands, rows, cols). If False, assumes/returns image with shape (rows, cols, bands). Default is True.

Returns

numpy.ndarray

Cropped image data

dict

Updated metadata

Raises

ValueError

If data is a numpy array but meta is not provided.

Examples

>>> # Crop from a file
>>> im, meta = crop_rio("input.tif", 100, 500, 200, 600, "cropped.tif")
>>>
>>> # Crop from a numpy array
>>> im, meta = crop_rio(image_array, 100, 500, 200, 600, meta=metadata)

rastereasy.rastereasy.crop_rio_sequence(source_name, deb_row, end_row, deb_col, end_col, dest_name=None)

Crop a sequence of georeferenced images.

Parameters

source_namestr

Path to the directory containing GeoTIFF images.

deb_rowint

Starting row coordinate (pixel).

end_rowint

Ending row coordinate (pixel).

deb_colint

Starting column coordinate (pixel).

end_colint

Ending column coordinate (pixel).

dest_namestr, optional

Path to save the cropped images. If None, images are not saved. Default is None.

Returns

list of numpy.ndarray

List of cropped images

list of dict

List of updated metadata

Examples

>>> images, metadatas = crop_rio_sequence("input_dir", 100, 500, 200, 600, "output_dir")

rastereasy.rastereasy.resampling(data, final_resolution, dest_name=None, method='cubic_spline', channel_first=True, meta=None)

Resample a georeferenced image to a new resolution.

Parameters

datastr or numpy.ndarray

The name of the input TIFF image or a numpy array with shape (N, row, col). If a numpy array is provided, an associated meta is required.

final_resolutionfloat

The desired resolution of the output image (in meters or degrees).

dest_namestr, optional

The name of the resampled image file to save. If None, the image is not saved. Default is None.

methodstr, optional

The resampling method to use. Available methods: ‘cubic_spline’ (default), ‘nearest’, ‘bilinear’, ‘cubic’,

‘lanczos’, ‘average’, ‘mode’, ‘max’, ‘min’, ‘med’, ‘sum’, ‘q1’, ‘q3’.

Default is ‘cubic_spline’.

channel_firstbool, optional

Whether to output the image in a shape of (bands, rows, cols). If False, the output shape will be (rows, cols, bands). Default is True.

metadict, optional

Metadata to use if data is a numpy array. Default is None.

Returns

numpy.ndarray

The resampled image.

dict

The metadata associated with the resampled image.

Examples

>>> # Resample a GeoTIFF image to a new resolution
>>> resampled_image, meta = resampling('image.tif', 10)
>>>
>>> # Resample a numpy array with custom metadata
>>> data = np.random.rand(4, 100, 100)  # Example data
>>> meta = {'driver': 'GTiff', 'count': 4, 'dtype': 'float32', 'width': 100, 'height': 100}
>>> resampled_image, meta = resampling(data, 10, meta=meta)

rastereasy.rastereasy.np2rio(image)

Convert a numpy array in channel-last format to channel-first format for rasterio.

Parameters

imagenumpy.ndarray

Input image in channel-last format (rows, cols, bands).

Returns

numpy.ndarray

Image in channel-first format (bands, rows, cols).

Examples

>>> rio_image = np2rio(numpy_image)

rastereasy.rastereasy.rio2np(image)

Convert a rasterio image in channel-first format to channel-last format for numpy.

Parameters

imagenumpy.ndarray

Input image in channel-first format (bands, rows, cols).

Returns

numpy.ndarray

Image in channel-last format (rows, cols, bands).

Examples

>>> numpy_image = rio2np(rio_image)

rastereasy.rastereasy.image2table(image, channel_first=True)

Reshape an image into a 2D table of size (rows*cols, bands).

Parameters

imagenumpy.ndarray

Input image array.

channel_firstbool, optional

If True, assumes input has shape (bands, rows, cols). If False, assumes input has shape (rows, cols, bands). Default is True.

Returns

numpy.ndarray

A 2D array of shape (rows*cols, bands).

Examples

>>> table = image2table(image, channel_first=True)

rastereasy.rastereasy.table2image(table, size, channel_first=True)

Reshape a 2D table back into a 3D image.

Parameters

tablenumpy.ndarray

Input table with shape (rows*cols, bands) or (rows*cols,).

sizetuple

Size of the output image as (rows, cols).

channel_firstbool, optional

If True, output will have shape (bands, rows, cols). If False, output will have shape (rows, cols, bands). Default is True.

Returns

numpy.ndarray

Reshaped 3D image.

Examples

>>> image = table2image(table, (400, 600), channel_first=True)

rastereasy.rastereasy.shp2geoim2(shapefile_path, attribute='code', resolution=10, nodata=0)

Convertit un shapefile en données raster et métadonnées géospatiales.

Cette fonction transforme des données vectorielles d’un shapefile en une matrice raster et génère les métadonnées appropriées pour le géoréférencement.

Parameters

shapefile_pathstr

Chemin d’accès au fichier shapefile (.shp).

attributestr, optional

Attribut du shapefile à utiliser pour les valeurs des pixels dans le raster. Default is ‘code’.

resolutionfloat, optional

Résolution spatiale (taille des pixels) du raster de sortie en unités du système de coordonnées (généralement mètres ou degrés). Default is 10.

nodataint or float, optional

Valeur à attribuer aux zones situées en dehors des formes du shapefile. Default is 0.

Returns

tuple

Un tuple contenant: - data (numpy.ndarray): Tableau 2D contenant les données rasterisées - meta (dict): Dictionnaire de métadonnées avec les informations de géoréférencement

Raises

ValueError

Si le shapefile n’a pas de système de coordonnées (CRS) défini Si l’attribut spécifié n’existe pas dans le shapefile

Examples

>>> data, meta = shp2geoim2("landcover.shp", attribute="landtype", resolution=30)
>>> im = Geoimage(data=data, meta=meta)
>>> im.info()

class rastereasy.rastereasy.shpfiles

Bases: object

Utility class for working with shapefiles and converting them to raster formats.

This class contains static methods for operations like: - Getting attribute names from shapefiles - Converting shapefiles to raster data - Converting shapefiles directly to Geoimage objects

Examples

>>> # Get attributes from a shapefile
>>> attributes = shpfiles.get_shapefile_attributes("landcover.shp")
>>>
>>> # Convert a shapefile to a raster file
>>> shpfiles.shp2raster("landcover.shp", "landcover.tif", attribute="landtype")
>>>
>>> # Convert a shapefile to a Geoimage object
>>> landcover_img = shpfiles.shp2geoim("landcover.shp", attribute="landtype")

static get_shapefile_attributes(shapefile_path)

Get the attribute field names from a shapefile.

Parameters

shapefile_pathstr

Path to the input shapefile.

Returns

list

List of attribute field names in the shapefile.

Examples

>>> attributes = shpfiles.get_shapefile_attributes("landcover.shp")
>>> print(attributes)
>>> ['FID', 'landtype', 'area', 'perimeter']

static shp2geoim(shapefile_path, attribute='code', resolution=10, nodata=0)

Convert a shapefile to a Geoimage object.

Parameters

shapefile_pathstr

Path to the input shapefile.

attributestr, optional

Attribute field in the shapefile to assign values to each pixel. Default is ‘code’.

resolutionfloat, optional

Spatial resolution of the output raster in meters/degrees. Default is 10.

nodataint or float, optional

Value to assign to areas outside the shapes. Default is 0.

Returns

Geoimage

A Geoimage object containing the rasterized data.

Notes

• The shapefile_path should be the full path to a shapefile (.shp) on the disk.

• The attribute field will be assigned to each pixel in the rasterized Geoimage.

• To get the attributes of a shapefile, see shpfiles.get_shapefile_attributes()

• The resolution sets the size of each pixel in the output image.

Examples

>>> geo_img = shpfiles.shp2geoim("landcover.shp", attribute='landtype', resolution=5)

static shp2raster(shapefile_path, dest_name, attribute='code', resolution=10, nodata=0)

Convert a shapefile to a GeoTIFF raster file.

Parameters

shapefile_pathstr

Path to the input shapefile.

dest_namestr

Path to save the output raster file.

attributestr, optional

Attribute field in the shapefile to assign values to each pixel. Default is ‘code’.

resolutionfloat, optional

Spatial resolution of the output raster in meters/degrees. Default is 10.

nodataint or float, optional

Value to assign to areas outside the shapes. Default is 0.

Notes

• The shapefile_path should be the full path to a shapefile (.shp) on the disk.

• To get the attributes of a shapefile, see shpfiles.get_shapefile_attributes()

• The output raster will be written in GeoTIFF format to the path specified by dest_name.

Examples

>>> shpfiles.shp2raster("landcover.shp", "landcover.tif", attribute='landtype', resolution=5)

class rastereasy.rastereasy.rasters

Bases: object

Utility class for raster image operations.

This class provides static methods for operations like stacking multiple images and removing bands from images.

Examples

>>> # Stack two images
>>> combined_image = rasters.stack(image1, image2)
>>>
>>> # Remove bands from an image
>>> reduced_image = rasters.remove_bands(image, bands=["NIR", "SWIR1"])

static stack(im1, im2, dtype='float64', dest_name=None, reformat_names=False)

Stack two Geoimage objects into a single image.

Parameters

im1Geoimage

First image to stack

im2Geoimage

Second image to stack

dtypestr, optional

Data type for the output image. Default is ‘float64’.

dest_namestr, optional

Path to save the stacked image. Default is None.

reformat_namesbool, optional

How to handle band names: - If True: Reset all names like {“1”:1, “2”:2, …} - If False: Adapt names like {“NIR_1”:1, “R_1”:2, “G_1”:3, “R_2”:4, …} Default is False.

Returns

Geoimage

A new Geoimage containing all bands from both input images

Examples

>>> combined = rasters.stack(sentinel2_img, landsat8_img)
>>> combined.info()

static remove_bands(im, bands, reformat_names=True, dest_name=None)

Remove specified bands from an image.

Parameters

imGeoimage

The input image

bandsstr, list, or numpy.ndarray

The bands to remove, specified as either: - A string with a band name (e.g., ‘SWIR1’) - A list or array of band names (e.g., [‘R’, ‘G’, ‘B’]) - An integer representing the band index (e.g., 4) - A list or array of band indices (e.g., [4, 2, 3])

reformat_namesbool, optional

If True, the band names are renumbered from 1 after removal. If False, the original band names are preserved (gaps may remain). Default is True.

dest_namestr, optional

Path to save the modified image. Default is None.

Returns

Geoimage

A new Geoimage with the specified bands removed

Examples

>>> reduced_img = rasters.remove_bands(image, bands=["NIR", "SWIR1"])
>>> reduced_img.info()

class rastereasy.rastereasy.Visualizer

Bases: object

Utility class for visualizing raster image data.

This class provides methods for interactive plotting and exploration of spectral data in georeferenced images.

Examples

>>> # Extract and plot spectral values from user-selected pixels
>>> series, pixel_i, pixel_j = Visualizer.plot_spectra(image, bands=['R', 'G', 'B'])

static plot_spectra(im, bands=None, fig_size=(15, 5), percentile=2, title='', title_im='Original image (click outside to stop)', title_spectra='Spectra', xlabel='Bands', ylabel='Value')

Plots and extracts spectral values from user-selected pixels on a multispectral image.

Parameters

imGeoimage

Multispectral georeferenced image to analyze.

bandslist, optional

List of bands to use for the color composition in the image plot. Default is None (uses the first three bands).

fig_sizetuple, optional

Size of the figure in inches, specified as (width, height). Default is (15, 5).

percentileint, optional

Percentile value for the color composition scaling. Default is 2.

titlestr, optional

Main title for the figure. Default is ‘’.

title_imstr, optional

Title for the image plot. Default is “Original image (click outside to stop)”.

title_spectrastr, optional

Title for the spectra curves plot. Default is “Spectra”.

xlabelstr, optional

X-axis label for the spectra curves plot. Default is “Bands”.

ylabelstr, optional

Y-axis label for the spectra curves plot. Default is “Value”.

Returns

list of lists

Collection of spectral series extracted from the selected pixels.

list of int

List of row indices (i-coordinates) of the selected pixels.

list of int

List of column indices (j-coordinates) of the selected pixels.

Notes

The data collection stops when the user clicks outside the image area or clicks the “Finish” button.

Examples

>>> series, i_coords, j_coords = Visualizer.plot_spectra(
>>>      image, bands=['B01', 'B02', 'B03'], fig_size=(10, 5))

class rastereasy.rastereasy.InferenceTools

Bases: object

Utility class for inference operations on raster images.

This class provides methods for clustering, spectral adaptation fusion, … of georeferenced images.

Examples

>>> # Perform K-means clustering on an image
>>> classified_img, model = InferenceTools.kmeans(image, n_clusters=5)
>>>
>>> # Adapt spectral properties of one image to match another
>>> adapted_img = InferenceTools.adapt(source_img, target_img, mapping='sinkhorn')

static kmeans(im, n_clusters=4, bands=None, random_state=None, dest_name=None, standardization=True)

Perform K-means clustering on a Geoimage.

Parameters

imGeoimage

Input image to cluster

n_clustersint, optional

Number of clusters (categories) to create. Default is 4.

bandslist, optional

List of bands to use for clustering. If None, all bands are used. Default is None.

random_stateint, optional

Random state for reproducible results. Default is None.

dest_namestr, optional

Path to save the clustered image. Default is None.

standardizationbool, optional

Whether to standardize bands before clustering. Default is True.

Returns

Geoimage

A new Geoimage with clusters as pixel values

tuple

A tuple containing the KMeans model and the scaler (if standardization was applied)

Examples

>>> classified_img, model = InferenceTools.kmeans(image, n_clusters=3)
>>> classified_img.visu()
>>>
>>> # Clustering with specific bands
>>> classified_img, model = InferenceTools.kmeans(
>>>     image, n_clusters=4, bands=["8", "2", "1"], random_state=42)

static fuse_dempster_shafer_2hypotheses(*images)

Fuse mass functions from multiple sources using Dempster-Shafer theory with two hypotheses: A and B.

Parameters

*imagesGeoimage

Each input is a 3-band Geoimage.

• Band 1: mass function m(A)

• Band 2: mass function m(B)

• Band 3: mass function m(A ∪ B)

Returns

Geoimage

A new Geoimage with 3 bands containing the fused mass functions: m(A), m(B), and m(A ∪ B).

Geoimage

A new Geoimage with 1 band containing the conflict values.

Examples

>>> fused, conflict = fuse_dempster_shafer_2hypotheses(im1, im2, im3)
>>> fused, conflict = fuse_dempster_shafer_2hypotheses(im1, im2, im3, im4)
>>> fused, conflict = fuse_dempster_shafer_2hypotheses(im1, im2)

static adapt(ims, imt, tab_source=None, nb=1000, mapping='gaussian', reg_e=0.1, mu=1.0, eta=0.01, bias=False, max_iter=20, verbose=True, sigma=1)

Adjusts the spectral characteristics of a source image to match those of a target image using optimal transport methods.

This function normalizes the data, applies the chosen optimal transport algorithm to adapt the spectral characteristics, and then restores the original data scale.

Parameters

imsGeoimage

Source image whose spectral characteristics will be adjusted.

imtGeoimage or numpy.ndarray

Target image serving as a reference for spectral adjustment, or a NumPy array of shape (N, bands) containing N spectral samples.

tab_sourcenumpy.ndarray, optional

Required if imt is a NumPy array. Must be an array of shape (M, bands) containing spectral samples from the source image.

nbint, optional

Number of random samples used to train the transport model. Default is 1000.

mappingstr, optional

Optimal transport method to use. Available options: - ‘emd’: Earth Mover’s Distance (more precise but slower) - ‘sinkhorn’: Sinkhorn transport with regularization (good balance) - ‘mappingtransport’: Mapping-based transport (flexible) - ‘gaussian’: Transport with Gaussian assumptions (faster, robust) Default is ‘gaussian’.

reg_efloat, optional

Regularization parameter for Sinkhorn transport. Default is 1e-1.

mufloat, optional

Regularization parameter for mapping-based methods. Default is 1e0.

etafloat, optional

Learning rate for mapping-based transport methods. Default is 1e-2.

biasbool, optional

Adds a bias term to the transport model if enabled. Default is False.

max_iterint, optional

Maximum number of iterations for iterative transport methods. Default is 20.

verbosebool, optional

Enables progress messages during processing. Default is True.

sigmafloat, optional

Standard deviation used for Gaussian transport methods. Default is 1.

Returns

Geoimage

A new image where the spectral bands of the source image ims are adapted to match those of the target image imt.

Raises

ValueError

If an unrecognized mapping method is specified.

RuntimeError

If the adaptation process fails.

Notes

• This function uses optimal transport tools (via the POT library).

• Raster data is normalized before transport and then denormalized afterward.

• Pixels with nodata values in both images are excluded from calculations.

• Adjusted values are limited to remain within valid ranges.

Examples

>>> adapted_image = InferenceTools.adapt(source_image, target_image, mapping='sinkhorn', reg_e=0.01)
>>> adapted_image.save('adapted_image.tif')
>>>
>>> # Adaptation using sample arrays
>>> adapted_image = InferenceTools.adapt(source_image, tab_target, tab_source, mapping='sinkhorn', reg_e=0.01)
>>> adapted_image.save('adapted_image.tif')
>>> adapted_image.save('adapted_image.tif')
>>>
>>> # Adaptation using different methods
>>> adapted_gaussian = InferenceTools.adapt(source_image, target_image, mapping='gaussian')
>>> adapted_emd = InferenceTools.adapt(source_image, target_image, mapping='emd')

rastereasy.rastereasy.files2stack(imagefile_path, resolution=None, names='origin', dest_name=None, ext='jp2', history=False)

Create a stacked Geoimage from multiple single-band images.

This function creates a multi-band Geoimage by stacking individual images, either from a list of image paths or from all images in a directory. All input images should have 1 band each.

Parameters

imagefile_pathstr or list of str

• If a list of strings: paths to image files to stack (e.g., [‘image1.jp2’, ‘image2.jp2’, …])

• If a string: path to a directory containing images with the specified extension

resolutionfloat, optional

Resolution to which all images will be resampled. If None, all images must have the same resolution already. Default is None.

namesdict or str, optional

How to name the spectral bands in the stack: - If a dict: Maps band names to indices (e.g., {‘B’: 1, ‘G’: 2, ‘R’: 3, …}) - If “origin” (default): Uses the original filenames as band names - If None: Assigns numeric names (‘1’, ‘2’, ‘3’, …) Default is “origin”.

dest_namestr, optional

Path to save the stacked image as a TIFF file. Default is None (no file saved).

extstr, optional

File extension of images to load if imagefile_path is a directory. Default is ‘jp2’.

historybool, optional

Whether to enable history tracking for the output Geoimage. Default is False.

Returns

Geoimage

A stacked Geoimage containing all the input images as bands.

Examples

>>> # Stack from a list of image files
>>> list_images = ['band1.jp2', 'band2.jp2', 'band3.jp2']
>>> stacked_image = files2stack(list_images)
>>> stacked_image.save('stacked.tif')
>>>
>>> # Stack all jp2 files from a directory with resolution resampling
>>> folder_path = './my_bands_folder'
>>> stacked_image = files2stack(folder_path, resolution=10)
>>> stacked_image.info()

Notes

This function is particularly useful for combining separate band files (common in satellite imagery) into a single multi-band image for analysis.

rastereasy.rastereasy.extract_common_areas(im1, im2, resolution='min', projection=None)

Extract the overlapping area between two GeoImages.

Parameters

im1Geoimage

First input image

im2Geoimage

Second input image

resolution{‘min’, ‘max’, None}, optional

How to handle resolution differences: - ‘min’: Use the more precise (smaller pixel size) resolution - ‘max’: Use the less precise (larger pixel size) resolution - None: Keep original resolutions Default is ‘min’.

projectionstr, optional

Projection system for output images. If None, uses im1’s projection. Example: “EPSG:4326” Default is None.

Returns

Geoimage, Geoimage

Two new Geoimages containing only the common overlapping area

Examples

>>> # Extract common area with smallest pixel size
>>> common_im1, common_im2 = extract_common_areas(image1, image2)
>>>
>>> # Extract common area with specific projection
>>> common_im1, common_im2 = extract_common_areas(image1, image2, projection="EPSG:4326")

Notes

This function is useful for preparing images for analysis or comparison when they cover different geographical areas but have an overlapping region.

rastereasy.rastereasy.extend_common_areas(image1, image2, nodata_value=0, resolution='min', projection=None)

Extend two images to cover their combined area, filling new areas with nodata value.

Parameters

image1Geoimage

First input image

image2Geoimage

Second input image

nodata_valueint or float, optional

Value to use for areas outside the original image bounds. Default is 0.

resolution{‘min’, ‘max’}, optional

How to handle resolution differences: - ‘min’: Use the more precise (smaller pixel size) resolution - ‘max’: Use the less precise (larger pixel size) resolution Default is ‘min’.

projectionstr, optional

Projection to use for output images. If None, uses image1’s projection. Default is None.

Returns

Geoimage, Geoimage

Two new Geoimages, each covering the combined area of both input images

Examples

>>> extended_im1, extended_im2 = extend_common_areas(image1, image2)

Notes

This function is useful for preparing images with different extents for comparison or mathematical operations that require the same dimensions.

rastereasy.rastereasy.colorcomp(image, bands, name_save='', names=None, percentile=2, channel_first=True, meta=None, fig_size=(5, 5), title='', extent=None)

Create a color composite visualization from a multi-band image.

This function generates an RGB color composite from a multi-band image by selecting three bands to represent red, green, and blue channels. The image can be displayed and/or saved as a file.

Parameters

imagenumpy.ndarray

Input image data as a 3D array.

bandslist of str

List of three band identifiers to use for the RGB composite. Can be either: - Band names (e.g., [“R”, “G”, “B”]) if names dictionary is provided - Band indices as strings (e.g., [“4”, “3”, “2”])

name_savestr, optional

Path to save the color composite image. If empty, image is not saved. Default is ‘’.

namesdict, optional

Dictionary mapping band names to band indices (e.g., {‘R’: 4, ‘G’: 3, ‘B’: 2}). Required if using band names in the bands parameter. Default is None.

percentileint, optional

Percentile value for contrast stretching (e.g., 2 for a 2-98% stretch). Default is 2.

channel_firstbool, optional

Whether input image has shape (bands, rows, cols). If False, assumes shape (rows, cols, bands). Default is True.

metadict, optional

Metadata dictionary (required if saving the image). Default is None.

fig_sizetuple, optional

Size of the figure in inches as (width, height). Default is DEF_FIG_SIZE.

titlestr, optional

Title for the visualization. Default is ‘’.

extentlist or None, optional

The extent of coordinates as [xmin, xmax, ymin, ymax]. If None, no extent is shown. Default is None.

Returns

None

Function displays and/or saves the color composite but doesn’t return any values.

Raises

ValueError

If meta is None when trying to save the image.

Examples

>>> # Create and display a false color composite
>>> colorcomp(image, bands=["NIR", "R", "G"], names={'R': 3, 'G': 2, 'B': 1, 'NIR': 4})
>>>
>>> # Create, display and save a natural color composite
>>> colorcomp(image, bands=["3", "2", "1"], name_save="rgb_composite.tif", meta=metadata)

class rastereasy.rastereasy.Geoimage(source_name=None, names=None, history=False, data=None, meta=None, georef=None, target_crs='EPSG:4326')

Bases: object

Main class for manipulating georeferenced raster images.

This class provides a comprehensive toolkit for working with geospatial raster data, supporting operations such as image creation, visualization, band manipulation, reprojection, resampling, cropping, and more.

Parameters

source_namestr, optional

Path to a GeoTIFF image file to load. If provided, the image data and metadata will be read from this file.

namesdict, optional

Dictionary mapping band names to band indices (e.g., {‘NIR’: 1, ‘R’: 2, ‘G’: 3}). If not provided, bands will be named numerically (‘1’, ‘2’, ‘3’, …).

historybool, optional

Whether to track modification history for the image. Default is False.

datanumpy.ndarray, optional

Image data to initialize the object with. Must be provided with meta. Shape should be (bands, rows, cols).

metadict, optional

Metadata dictionary containing rasterio metadata fields (e.g., crs, transform). Required if data is provided.

georefbool, optional

Whether the image is georeferenced. If None, will be determined from metadata.

target_crsstr, optional

Target coordinate reference system if reprojection is needed during loading. Default is “EPSG:4326”.

Attributes

imagenumpy.ndarray

The image data array with shape (bands, rows, cols).

shapetuple

The dimensions of the image as (rows, cols).

nb_bandsint

The number of spectral bands in the image.

resolutionfloat

The spatial resolution of the image (pixel size in map units).

namesdict

Dictionary mapping band names to band indices.

nodatafloat or int

Value used to represent no data or invalid pixels.

Examples

>>> # Create a Geoimage from a file
>>> img = Geoimage("landsat_image.tif")
>>> img.info()
>>> # Create a Geoimage from a NumPy array with metadata
>>> meta = {'driver': 'GTiff', 'width': 100, 'height': 100, 'count': 3,
>>> ...         'crs': CRS.from_epsg(4326), 'transform': Affine(0.1, 0, 0, 0, -0.1, 0)}
>>> data = np.zeros((3, 100, 100))
>>> img = Geoimage(data=data, meta=meta)
>>> # Create a Geoimage with custom band names
>>> img = Geoimage("landsat_image.tif", names={'R': 1, 'G': 2, 'B': 3, 'NIR': 4})

where(condition, value1, value2)

Select values based on a condition, similar to numpy.where().

This method allows for conditional operations, selecting values from value1 where condition is True, and from value2 where it’s False.

Parameters

conditionGeoimage

Boolean mask indicating where to select values from value1

value1Geoimage or scalar

Values to use where condition is True

value2Geoimage or scalar

Values to use where condition is False

Returns

Geoimage

New Geoimage containing the result of the conditional selection

Examples

>>> # Create a cloud-free composite from two images
>>> cloud_free = image1.where(cloud_mask, image2, image1)
>>>
>>> # Threshold an image
>>> thresholded = image.where(image > 100, 255, 0)

update_from(other)

Update the current Geoimage with the attributes from another Geoimage.

This method copies all attributes from the other Geoimage to this one, effectively replacing this image’s content with that of other.

Parameters

otherGeoimage

The Geoimage to copy attributes from

Returns

None

This method modifies the current object in place

Examples

>>> result = image1.where(mask, 0, image1)  # Create a masked copy
>>> image1.update_from(result)  # Update the original with the masked version

reset_names()

Reset the band names to sequential numbers (“1”, “2”, …).

This method is useful when multiple stacks, removals, or additions of bands have left the band naming confusing or inconsistent.

Returns

selfGeoimage

The method returns the object itself to allow method chaining

Examples

>>> stacked_image = image1.apply_stack(image2)
>>> stacked_image.reset_names()
>>> stacked_image.info()  # Shows bands renamed to "1", "2", ...

change_nodata(nodatavalue)

Modify the no-data value of the image.

Parameters

nodatavaluefloat or int

The new no-data value to assign

Returns

selfGeoimage

The method returns the object itself to allow method chaining

Examples

>>> image.change_nodata(np.nan)  # Use NaN as nodata
>>> image.change_nodata(-9999)   # Use -9999 as nodata

change_names(names)

Modify the names of spectral bands.

Parameters

namesdict

Dictionary mapping band names to band indices (e.g., {‘R’: 1, ‘G’: 2, ‘B’: 3, ‘NIR’: 4})

Returns

selfGeoimage

The method returns the object itself to allow method chaining

Raises

ValueError

If the number of provided names doesn’t match the number of bands

Examples

>>> sentinel2_names = {'B': 1, 'G': 2, 'R': 3, 'NIR': 4, 'SWIR1': 5, 'SWIR2': 6}
>>> image.change_names(sentinel2_names)
>>> image.info()  # Shows updated band names

activate_history()

Activate history tracking for the image object.

This method enables logging of operations performed on the image, which can be useful for tracking processing steps and debugging.

Returns

selfGeoimage

The method returns the object itself to allow method chaining

Examples

>>> image = Geoimage("landsat_image.tif")
>>> image.activate_history()
>>> image.resampling(30,inplace=True)  # This operation will be tracked in history
>>> image.info()  # The history section will show the resampling operation

See Also

deactivate_history : Disable history tracking info : Display image information including history

deactivate_history()

Deactivate history tracking for the image object.

This method disables logging of operations performed on the image.

Returns

selfGeoimage

The method returns the object itself to allow method chaining

Examples

>>> image.deactivate_history()
>>> image.resampling(15)  # This operation won't be tracked in history

See Also

activate_history : Enable history tracking

copy()

Create a deep copy of the Geoimage object.

Returns

Geoimage

A new Geoimage instance that is a complete copy of the current object

Examples

>>> original = Geoimage("landsat_image.tif")
>>> duplicate = original.copy()
>>> duplicate.resampling(15,inplace=True)  # This won't affect the original image

Notes

This method creates a completely independent copy. Changes to the copy won’t affect the original image, and vice versa.

info()

Print detailed information about the image.

This method displays a comprehensive overview of the image’s properties, including: - Dimensions (rows, columns, bands) - Spatial resolution - Geographic coordinates of the center - Projection system - Data type - Nodata value - Band names - Processing history (if history tracking is enabled)

Examples

>>> image = Geoimage("landsat_image.tif")
>>> image.info()
>>> - Size of the image:
>>>    - Rows (height): 1024
>>>    - Col (width): 1024
>>>    - Bands: 4
>>> - Spatial resolution: 30.0 meters / degree
>>> - Central point latitude - longitude coordinates: (36.12345, -118.67890)
>>> - Driver: GTiff
>>> - Data type: uint16
>>> - Projection system: EPSG:32611
>>> - Nodata: 0
>>> - Given names for spectral bands:
>>>    {'B': 1, 'G': 2, 'R': 3, 'NIR': 4}
>>> --- History of modifications---
>>> [2023-09-15 10:30:22] - Read image landsat_image.tif
>>> [2023-09-15 10:31:45] - Apply resampling at 30.000000 meters

get_type()

Get the data type of the image.

Returns

str

The NumPy data type of the image (e.g., ‘uint8’, ‘float32’)

Examples

>>> data_type = image.get_type()
>>> print(f"Image has data type: {data_type}")

get_spatial_resolution()

Get the spatial resolution of the image.

Returns

float

The spatial resolution in meters or degrees (depending on the projection)

Examples

>>> resolution = image.get_spatial_resolution()
>>> print(f"Image has {resolution} meter resolution")

get_latlon_coordinates()

Get the latitude and longitude coordinates of the central point of the image.

Returns

tuple of float

The (latitude, longitude) of the center of the image

Examples

>>> lat, lon = image.get_latlon_coordinates()
>>> print(f"Image center is at latitude {lat}, longitude {lon}")

get_size()

Get the size (dimensions) of the image.

Returns

tuple of int

The (rows, columns) dimensions of the image

Examples

>>> rows, cols = image.get_size()
>>> print(f"Image has {rows} rows and {cols} columns")

get_nb_bands()

Get the number of spectral bands in the image.

Returns

int

The number of bands

Examples

>>> nb_bands = image.get_nb_bands()
>>> print(f"Image has {nb_bands} spectral bands")

get_meta()

Get the metadata dictionary.

Returns

dict

A copy of the rasterio metadata dictionary

Examples

>>> metadata = image.get_meta()
>>> print(f"Image CRS: {metadata['crs']}")

get_nodata()

Get the nodata value of the image.

Returns

float, int, or None

The nodata value if it exists, otherwise None

Examples

>>> nodata = image.get_nodata()
>>> print(f"Nodata value: {nodata}")

get_bounds()

Get the geographic bounds of the image.

Returns

rasterio.coords.BoundingBox

The bounding box of the image (left, bottom, right, top)

Examples

>>> bounds = image.get_bounds()
>>> print(f"Image covers from ({bounds.left}, {bounds.bottom}) to ({bounds.right}, {bounds.top})")

get_names()

Get the band names dictionary.

Returns

dict

A copy of the dictionary mapping band names to band indices

Examples

>>> names = image.get_names()
>>> print(f"Red band is at index {names.get('R', 'unknown')}")

get_georef()

Check if the image is georeferenced.

Returns

bool

True if the image is georeferenced, False otherwise

Examples

>>> is_georeferenced = image.get_georef()
>>> if not is_georeferenced:
...     print("Warning: Image is not georeferenced")

unique()

Get the unique values in the image.

Returns

numpy.ndarray

Array of unique values found in the image

Examples

>>> unique_values = image.unique()
>>> print(f"Image contains {len(unique_values)} unique values")
>>> print(f"Values: {unique_values}")

Notes

This method is particularly useful for categorical data or classified images to see how many classes are present.

abs(axis=None, inplace=False)

Calculate the absolute value of the image data.

This method modifies the image content directly by replacing all values with their absolute values.

Parameters

axisstr or None, optional

Not used, kept for API consistency with other statistical methods. Default is None.

inplacebool, default False

If False, return a copy. Otherwise, do absolute value in place and return None.

Returns

Geoimage

The absolute value image or None if inplace=True

Examples

>>> difference = image1 - image2  # May contain negative values
>>> diff_abs = difference.abs()  # Compute absolute values of `differences`
>>> difference.abs(inplace = True)  # Directly convert differences to absolute values
>>> difference.info()

sum(axis=None)

Calculate the sum of image values along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the sum: - ‘band’: Sum across spectral bands for each pixel - ‘row’: Sum across rows (lines) for each band and column - ‘col’: Sum across columns for each band and row - None: Sum of all values in the image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the sum of the entire image

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing sums along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing sums along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing sums along cols

• If axis=’pixel’: Array with shape (nb_bands) containing sums along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> total = image.sum()  # Sum of all pixel values
>>> print(f"Total pixel sum: {total}")
>>>
>>> band_sums = image.sum(axis='pixel')  # Sum along all pixels for each band

min(axis=None)

Calculate the minimum value along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the minimum: - ‘band’: Minimum across spectral bands for each pixel - ‘row’: Minimum across rows (lines) for each band and column - ‘col’: Minimum across columns for each band and row - None: Global minimum of the entire image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the global minimum

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing mins along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing mins along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing mins along cols

• If axis=’pixel’: Array with shape (nb_bands) containing mins along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> min_value = image.min()  # Global minimum value
>>> print(f"Minimum pixel value: {min_value}")
>>>
>>> band_mins = image.min(axis='pixel')  # Minimum along all pixels for each band

max(axis=None)

Calculate the maximum value along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the maximum: - ‘band’: Maximum across spectral bands for each pixel - ‘row’: Maximum across rows (lines) for each band and column - ‘col’: Maximum across columns for each band and row - None: Global maximum of the entire image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the global maximum

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing max along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing max along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing max along cols

• If axis=’pixel’: Array with shape (nb_bands) containing maxs along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> max_value = image.max()  # Global maximum value
>>> print(f"Maximum pixel value: {max_value}")
>>>
>>> band_maxs = image.max(axis='pixel')  # Maximum along all pixels for each band

mean(axis=None)

Calculate the mean value along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the mean: - ‘band’: Mean across spectral bands for each pixel - ‘row’: Mean across rows (lines) for each band and column - ‘col’: Mean across columns for each band and row - None: Global mean of the entire image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the global mean

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing mean along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing mean along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing mean along cols

• If axis=’pixel’: Array with shape (nb_bands) containing mean along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> mean_value = image.mean()  # Global mean value
>>> print(f"Mean pixel value: {mean_value}")
>>>
>>> band_means = image.mean(axis='pixel')  # Mean along all pixels for each band

Notes

This method uses np.nanmean, which ignores NaN values in the calculation. If you have NaN values as nodata, they won’t affect the mean calculation.

std(axis=None)

Calculate the standard deviation along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the standard deviation: - ‘band’: Std dev across spectral bands for each pixel - ‘row’: Std dev across rows (lines) for each band and column - ‘col’: Std dev across columns for each band and row - None: Global standard deviation of the entire image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the global std

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing std along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing std along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing std along cols

• If axis=’pixel’: Array with shape (nb_bands) containing std along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> std_value = image.std()  # Global standard deviation
>>> print(f"Standard deviation of pixel values: {std_value}")
>>>
>>> band_stds = image.std(axis='pixel')  # Standard deviation along all pixels for each band

median(axis=None)

Calculate the median value along a specified axis.

Parameters

axis{‘band’, ‘row’, ‘col’, None}, optional

The axis along which to compute the median: - ‘band’: Median across spectral bands for each pixel - ‘row’: Median across rows (lines) for each band and column - ‘col’: Median across columns for each band and row - None: Global median of the entire image Default is None.

Returns

float or numpy.ndarray

• If axis=None: A single value representing the global median

• If axis=’band’: Array with shape (nb_rows,nb_cols) containing median along bands

• If axis=’row’: Array with shape (nb_bands,nb_cols) containing median along rows

• If axis=’col’: Array with shape (nb_bands,nb_rows) containing median along cols

• If axis=’pixel’: Array with shape (nb_bands) containing median along all pixels for each band

Raises

ValueError

If an invalid axis is specified

Examples

>>> median_value = image.median()  # Global median value
>>> print(f"Median pixel value: {median_value}")
>>>
>>> band_medians = image.median(axis='pixel')  # Median along all pixels for each band

Notes

The median is the value separating the higher half from the lower half of the data. It’s less sensitive to outliers than the mean, making it useful for images with extreme values or noise.

replace_values(value_to_replace, new_value)

Replace all pixels that match a specified value across all bands.

Parameters

value_to_replacefloat, int, or array-like

The value(s) to search for in each pixel across all bands: - If a single value: Looks for pixels where all bands equal this value - If an array: Looks for pixels where each band matches the corresponding value

in the array (must have the same length as the number of bands)

new_valuefloat, int, or array-like

The value(s) to assign to the matching pixels: - If a single value: Assigns this value to all bands of matching pixels - If an array: Assigns each value to the corresponding band of matching pixels

(must have the same length as the number of bands)

Returns

selfGeoimage

The modified image, allowing method chaining

Examples

>>> # Replace all nodata (0) values with NaN
>>> image.replace_values(0, np.nan)
>>>
>>> # Replace a specific RGB color [255, 0, 0] with [0, 0, 0] (black)
>>> image.replace_values([255, 0, 0], [0, 0, 0])

Notes

This method is useful for replacing nodata values, specific classes in a classification, or adjusting specific spectral signatures in an image.

percentage_pixels(value=None)

Calculate the percentage of pixels with a specified value across all bands.

This method calculates what percentage of the total pixels have the specified value in all bands. It’s particularly useful for calculating coverage of nodata values, specific land cover classes, or other categorical values.

Parameters

valueint, float, list, or array-like, optional

The value to check for in each band of a pixel: - If a single number: Checks for pixels where all bands equal this value - If a vector: Checks for pixels where each band matches the corresponding

value in the vector (must have same length as number of bands)

• If None: Uses the image’s nodata value (default)

Returns

float

The percentage of pixels (from 0 to 100) where all bands have the specified value

Examples

>>> # Calculate percentage of nodata pixels
>>> pct_nodata = image.percentage_pixels()  # Uses image's nodata value
>>> print(f"Image contains {pct_nodata:.2f}% nodata pixels")
>>>
>>> # Calculate percentage of pixels with a specific class value
>>> pct_water = image.percentage_pixels(1)  # Assuming 1 = water class
>>> print(f"Water covers {pct_water:.2f}% of the image")
>>>
>>> # Calculate percentage of pixels with a specific spectral signature
>>> pct_rgb_black = image.percentage_pixels([0, 0, 0])  # RGB black pixels
>>> print(f"Black pixels (RGB=0,0,0) cover {pct_rgb_black:.2f}% of the image")

Notes

This method handles both single values and vectors for the value parameter. The calculation correctly handles NaN values by considering NaN equal to NaN.

hist(**args)

Display histograms of the image data.

This method provides a flexible way to visualize the distribution of pixel values in one or more bands of the image. It supports various customization options for the histogram display.

Parameters

bandsstr, int, list, optional

The bands to visualize. If not specified, all bands are included. This can be band names (e.g., [“NIR”, “R”, “G”]) or indices (e.g., [4, 3, 2]).

superposebool, optional

If True, all histograms are plotted on the same figure. If False (default), each band gets its own separate histogram figure.

binsint, optional

The number of bins for computing the histogram. Default is 100.

xminfloat, optional

The minimum value to plot on the x-axis. Values lower than this won’t be displayed.

xmaxfloat, optional

The maximum value to plot on the x-axis. Values higher than this won’t be displayed.

titlestr, optional

The title for the histogram figure.

histtypestr, optional

The type of histogram to draw. Default is ‘stepfilled’. Other options include ‘bar’, ‘step’, ‘barstacked’, etc.

alphafloat, optional

The transparency of the histogram bars (0.0 to 1.0). Default is 0.6.

fig_sizetuple, optional

The size of the figure in inches as (width, height). Default is DEF_FIG_SIZE.

labelstr or list of str, optional

The labels for the histogram. If not provided, default labels will be created.

**argsdict, optional

Additional keyword arguments passed to matplotlib’s hist function.

Returns

None

This method displays the histogram(s) but doesn’t return any values.

Examples

>>> # Display histograms for all bands
>>> image.hist(bins=100)
>>>
>>> # Display histogram for a single band with customization
>>> image.hist(bands="NIR", bins=150, histtype='stepfilled',
>>>            title="NIR Band Distribution", xmin=0, xmax=10000)
>>>
>>> # Superpose histograms from multiple bands
>>> image.hist(bands=["NIR", "R", "G"], bins=100, superpose=True,
>>>            alpha=0.7, fig_size=(10, 6))

Notes

This method is based on rasterio’s show_hist function and supports most of matplotlib’s histogram customization options. It’s useful for understanding the distribution of values in your image and identifying potential issues like saturation, quantization, or outliers.

colorcomp(bands=None, dest_name='', percentile=2, fig_size=(5, 5), title='', extent='latlon')

Create and display a color composite image from selected bands.

This method creates an RGB color composite by assigning three bands to the red, green, and blue channels. It’s useful for creating false color compositions, natural color images, or any three-band visualization.

Parameters

bandslist of str, optional

List of three band identifiers to use for the RGB composite (in order: R, G, B). Can be band names (e.g., [“NIR”, “R”, “G”]) or indices (e.g., [“4”, “3”, “2”]). If None, uses the first three bands in the image. Default is None.

dest_namestr, optional

Path to save the color composite image. If empty, the image is not saved. Default is ‘’.

percentileint, optional

Percentile value for contrast stretching (e.g., 2 for a 2-98% stretch). This enhances the visual contrast of the image. Default is 2.

fig_sizetuple, optional

Size of the figure in inches as (width, height). Default is DEF_FIG_SIZE.

titlestr, optional

Title for the visualization. Default is ‘’.

extent{‘latlon’, ‘pixel’, None}, optional

Type of extent to use for the plot: - ‘latlon’: Use latitude/longitude coordinates (default) - ‘pixel’: Use pixel coordinates - None: Don’t show coordinate axes

Returns

None

This method displays and/or saves the color composite but doesn’t return any values.

Raises

ValueError

If the image has only 2 bands, which is not enough for an RGB composite. If an invalid extent value is provided.

Examples

>>> # Create a natural color composite (for Landsat/Sentinel-2 style ordering)
>>> image.colorcomp(bands=["R", "G", "B"])
>>>
>>> # Create a color-infrared composite (vegetation appears red)
>>> image.colorcomp(bands=["NIR", "R", "G"], title="Color-Infrared Composite")
>>>
>>> # Create and save a false color composite
>>> image.colorcomp(bands=["SWIR1", "NIR", "G"], dest_name="false_color.tif")
>>>
>>> # Change the contrast stretch
>>> image.colorcomp(bands=["R", "G", "B"], percentile=5)  # More aggressive stretch

Notes

Common band combinations for satellite imagery include: - Natural color: R, G, B (shows the scene as human eyes would see it) - Color-infrared: NIR, R, G (vegetation appears red, useful for vegetation analysis) - Agriculture: SWIR, NIR, B (highlights crop health and soil moisture) - Urban: SWIR, NIR, R (emphasizes urban areas and bare soil)

convert_3bands(bands=None, dest_name=None, percentile=2, reformat_names=False)

Convert an image to a 3-band 8-bit RGB composite.

This method creates a new Geoimage with exactly 3 bands in 8-bit format (0-255), suitable for standard RGB visualization or export to conventional image formats.

Parameters

bandslist of str, optional

List of three band identifiers to use for the RGB composite (in order: R, G, B). Can be band names (e.g., [“NIR”, “R”, “G”]) or indices (e.g., [“4”, “3”, “2”]). If None, uses the first three bands in the image. Default is None.

dest_namestr, optional

Path to save the 3-band image. If None, the image is not saved. Default is None.

percentileint, optional

Percentile value for contrast stretching (e.g., 2 for a 2-98% stretch). This enhances the visual contrast of the image. Default is 2.

reformat_namesbool, optional

Whether to reset band names to a simple numeric format (“1”, “2”, “3”). If False, keeps the original names of the selected bands. Default is False.

Returns

Geoimage

A new Geoimage with 3 bands (R, G, B) in 8-bit format.

Examples

>>> # Create a natural color composite
>>> rgb_image = image.convert_3bands(bands=["R", "G", "B"])
>>> rgb_image.info()  # Should show 3 bands, uint8 data type
>>>
>>> # Create a false color composite with custom names
>>> false_color = image.convert_3bands(
>>>     bands=["SWIR", "NIR", "R"], dest_name="false_color.tif",
>>>     reformat_names=True)

Notes

This method is useful for: - Creating standardized RGB exports - Preparing data for conventional image viewers that expect 3-band 8-bit data - Reducing file size by converting to 8-bit - Creating visually enhanced compositions with contrast stretching

plot_spectra(bands=None, fig_size=(15, 5), percentile=2, title='', title_im='Original image (click outside to stop)', title_spectra='Spectra', xlabel='Bands', ylabel='Value')

Interactive tool to explore and plot spectral values from user-selected pixels.

This method displays the image and allows the user to click on pixels to see their spectral values across all bands plotted as a line graph. Multiple pixels can be selected to compare different spectral signatures.

Parameters

bandslist of str, optional

List of three band identifiers to use for the background image display. If None, uses the first three bands in the image. Default is None.

fig_sizetuple, optional

Size of the figure in inches as (width, height). Default is (15, 5).

percentileint, optional

Percentile value for contrast stretching of the background image. Default is 2.

titlestr, optional

Main title for the figure. Default is ‘’.

title_imstr, optional

Title for the image panel. Default is “Original image (click outside to stop)”.

title_spectrastr, optional

Title for the spectral plot panel. Default is “Spectra”.

xlabelstr, optional

X-axis label for the spectral plot. Default is “Bands”.

ylabelstr, optional

Y-axis label for the spectral plot. Default is “Value”.

Returns

tuple

A tuple containing: - series : list of lists - Spectral values for each selected pixel - pixel_i : list of int - Row coordinates of selected pixels - pixel_j : list of int - Column coordinates of selected pixels

Examples

>>> # Explore spectral signatures in the image
>>> spectra, rows, cols = image.plot_spectra()
>>> print(f"Selected {len(spectra)} pixels")
>>>
>>> # Customize the display
>>> spectra, rows, cols = image.plot_spectra(
>>>     bands=["NIR", "R", "G"],
>>>     title_im="Click on different vegetation types",
>>>     title_spectra="Vegetation Spectral Signatures")

Notes

To end pixel selection, click outside the image area or on the “Finish” button. This tool is particularly useful for: - Exploring spectral differences between land cover types - Identifying spectral anomalies - Training classification algorithms - Building spectral libraries

visu(bands=None, title='', percentile=2, fig_size=(5, 5), cmap=None, colorbar=False, extent='latlon')

Visualize one or more bands of the image.

This method provides a flexible way to display individual bands or multiple bands as separate figures. Unlike colorcomp, which creates RGB composites, this method displays each band in grayscale or with a specified colormap.

Parameters

bandsstr, list of str, or None, optional

The bands to visualize: - If None: Displays all bands separately - If a string: Displays a single specified band - If a list: Displays each specified band separately Default is None.

titlestr, optional

Base title for the visualization. Band names will be appended. Default is ‘’.

percentileint, optional

Percentile value for contrast stretching (e.g., 2 for a 2-98% stretch). Default is 2.

fig_sizetuple, optional

Size of the figure in inches as (width, height). Default is DEF_FIG_SIZE.

cmapstr, optional

Matplotlib colormap name to use for display. Examples: ‘viridis’, ‘plasma’, ‘gray’, ‘RdYlGn’ Default is None (uses matplotlib default).

colorbarbool, optional

Whether to display a colorbar next to each image. Default is False.

extent{‘latlon’, ‘pixel’, None}, optional

Type of extent to use for the plot: - ‘latlon’: Use latitude/longitude coordinates (default) - ‘pixel’: Use pixel coordinates - None: Don’t show coordinate axes

Examples

>>> # Visualize all bands
>>> image.visu()
>>>
>>> # Visualize a single band with a colormap and colorbar
>>> image.visu("NIR", cmap='plasma', colorbar=True, title="Near Infrared Band")
>>>
>>> # Visualize selected bands
>>> image.visu(["Red", "NIR", "NDVI"], fig_size=(10, 8))

Notes

This method is useful for: - Examining individual spectral bands in detail - Comparing several derived indices side by side - Applying different colormaps to highlight specific features - Visualizing single-band thematic data (e.g., elevation, classification results)

numpy_channel_first(bands=None)

Extract image data as a NumPy array in channel-first format.

This method returns a NumPy array representation of the image data with bands as the first dimension (bands, rows, cols), which is the format used by rasterio.

Parameters

bandsstr, list of str, or None, optional

The bands to include in the output: - If None: Returns all bands - If a string: Returns a single specified band - If a list: Returns the specified bands in the given order Default is None.

Returns

numpy.ndarray

Image data as a NumPy array with shape (bands, rows, cols)

Examples

>>> # Get the complete image as a NumPy array
>>> array = image.numpy_channel_first()
>>> print(f"Array shape: {array.shape}")
>>> print(f"Data type: {array.dtype}")
>>>
>>> # Extract specific bands
>>> rgb_array = image.numpy_channel_first(bands=["R", "G", "B"])
>>> print(f"RGB array shape: {rgb_array.shape}")

Notes

This format (bands, rows, cols) is commonly used with rasterio and some other geospatial libraries. For libraries that expect channel-last format (like most image processing libraries), use numpy_channel_last() instead.

numpy_channel_last(bands=None)

Extract image data as a NumPy array in channel-last format.

This method returns a NumPy array representation of the image data with bands as the last dimension (rows, cols, bands), which is the format used by most image processing libraries and frameworks.

Parameters

bandsstr, list of str, or None, optional

The bands to include in the output: - If None: Returns all bands - If a string: Returns a single specified band - If a list: Returns the specified bands in the given order Default is None.

Returns

numpy.ndarray

Image data as a NumPy array with shape (rows, cols, bands)

Examples

>>> # Get the complete image as a NumPy array
>>> array = image.numpy_channel_last()
>>> print(f"Array shape: {array.shape}")
>>>
>>> # Extract RGB bands for use with image processing libraries
>>> rgb = image.numpy_channel_last(bands=["R", "G", "B"])
>>> import cv2
>>> blurred = cv2.GaussianBlur(rgb, (5, 5), 0)

Notes

This format (rows, cols, bands) is commonly used with image processing libraries like OpenCV, scikit-image, PIL, and deep learning frameworks. For libraries that expect channel-first format (like rasterio), use numpy_channel_first() instead.

numpy_table(bands=None)

Extract image data as a 2D table of shape (pixels, bands).

This method reshapes the image into a 2D table where each row represents a pixel and each column represents a band. This format is useful for machine learning, statistical analysis, or any operation that treats pixels as independent samples.

Parameters

bandsstr, list of str, or None, optional

The bands to include in the output: - If None: Returns all bands - If a string: Returns a single specified band - If a list: Returns the specified bands in the given order Default is None.

Returns

numpy.ndarray

Image data as a 2D table with shape (rows*cols, bands)

Examples

>>> # Convert the entire image to a table
>>> table = image.numpy_table()
>>> print(f"Table shape: {table.shape}")
>>>
>>> # Process specific bands as a table
>>> nir_red = image.numpy_table(bands=["NIR", "R"])
>>> print(f"Shape: {nir_red.shape}")
>>> ndvi = (nir_red[:, 0] - nir_red[:, 1]) / (nir_red[:, 0] + nir_red[:, 1])
>>> print(f"Mean NDVI: {ndvi.mean()}")

Notes

This format is particularly useful for: - Machine learning where each pixel is a sample and each band is a feature - Clustering algorithms like K-means - Statistical analysis across bands - Vectorized operations on pixels

image_from_table(table, names=None, dest_name=None)

Create a new Geoimage from a 2D table of shape (pixels, bands).

This method converts a 2D table where each row represents a pixel and each column represents a band into a new Geoimage object. It essentially performs the inverse operation of numpy_table().

Parameters

tablenumpy.ndarray

The 2D table to convert, with shape (rows*cols, bands) or (rows*cols,) for a single band.

namesdict, optional

Dictionary mapping band names to band indices. If None, bands will be named sequentially (“1”, “2”, “3”, …). Default is None.

dest_namestr, optional

Path to save the new image. If None, the image is not saved. Default is None.

Returns

Geoimage

A new Geoimage created from the reshaped table

Raises

ValueError

If the number of rows in the table doesn’t match the dimensions of the original image

Examples

>>> # Create a modified image from a processed table
>>> table = image.numpy_table()
>>> normalized = (table - table.mean()) / table.std()  # Standardize
>>> normalized_image = image.image_from_table(normalized)
>>> normalized_image.visu()
>>>
>>> # Save the result
>>> table = image.numpy_table(bands=["NIR", "R"])
>>> ndvi = np.zeros((table.shape[0], 1))  # Create single-band output
>>> ndvi[:, 0] = (table[:, 0] - table[:, 1]) / (table[:, 0] + table[:, 1])
>>> ndvi_image = image.image_from_table(ndvi, names={"NDVI": 1}, dest_name="ndvi.tif")

Notes

The dimensions of the original image (rows, cols) are preserved, so the table must have exactly rows*cols rows. The number of bands can be different from the original image.

upload_table(table, names=None, dest_name=None)

Update the image data with a 2D table of shape (pixels, bands).

This method replaces the current image data with the content of a 2D table where each row represents a pixel and each column represents a band. The table is reshaped to match the image dimensions.

Parameters

tablenumpy.ndarray

The 2D table to upload, with shape (rows*cols, bands) or (rows*cols,) for a single band.

namesdict, optional

Dictionary mapping band names to band indices. If None, bands will be named sequentially (“1”, “2”, “3”, …). Default is None.

dest_namestr, optional

Path to save the updated image. If None, the image is not saved. Default is None.

Returns

selfGeoimage

The updated image, allowing method chaining

Raises

ValueError

If the number of rows in the table doesn’t match the dimensions of the original image

Examples

>>> # Update an image with processed data
>>> table = image.numpy_table()
>>> table = np.log(table + 1)  # Log transform
>>> image.upload_table(table)
>>> image.visu()
>>>
>>> # Upload a single-band result and save
>>> ndvi_table = (nir - red) / (nir + red)  # Assuming nir and red are numpy arrays
>>> image.upload_table(ndvi_table, names={"NDVI": 1}, dest_name="ndvi.tif")

Notes

Unlike image_from_table() which creates a new image, this method modifies the current image in place. The dimensions of the image (rows, cols) are preserved, but the number of bands can change if the table has a different number of columns.

upload_image(image, names=None, dest_name=None, channel_first=True, inplace=False)

Update the image data with a new image array.

This method replaces the current image data with a new image array. The new image must have compatible dimensions with the current image.

imagenumpy.ndarray

The new image data to upload, with shape: - (bands, rows, cols) if channel_first=True - (rows, cols, bands) if channel_first=False - (rows, cols) for a single band

namesdict, optional

Dictionary mapping band names to band indices. If None, bands will be named

sequentially (“1”, “2”, “3”, …).

Default is None.

dest_namestr, optional

Path to save the updated image. If None, the image is not saved. Default is None.

channel_firstbool, optional

Whether the input image has channels in the first dimension (True) or the last dimension (False). Default is True.

inplacebool, default False

If False, return a copy. Otherwise, upload image in place and return None.

Geoimage

The updated image or None if inplace=True

ValueError

If the spatial dimensions of the new image don’t match the original image

>>> # Create a new filtered image without modifying the original
>>> array = image.numpy_channel_first()
>>> filtered = apply_some_filter(array)  # Apply some processing
>>> filtered_image = image.upload_image(filtered)
>>> filtered_image.visu()
>>> image.visu()  # Original remains unchanged
>>>
>>> # Create a single-band image from NDVI calculation
>>> nir = image.numpy_channel_first(bands=["NIR"])
>>> red = image.numpy_channel_first(bands=["Red"])
>>> ndvi = (nir - red) / (nir + red)
>>> ndvi_image = image.upload_image(ndvi, names={"NDVI": 1},
>>>                                dest_name="ndvi.tif")
>>> # Update an image with processed data
>>> array = image.numpy_channel_first()
>>> filtered = some_filter_function(array)  # Apply some processing
>>> image.upload_image(filtered, inplace=True)
>>> image.visu()
>>>
>>> # Upload an image in channel-last format
>>> import cv2
>>> bgr = cv2.imread('rgb.jpg')  # OpenCV uses BGR order
>>> rgb = bgr[:, :, ::-1]  # Convert BGR to RGB
>>> image.upload_image(rgb, channel_first=False, dest_name="from_jpeg.tif", inplace=True))

The spatial dimensions (rows, cols) must match the original image, but the number of bands can change.

astype(dtype)

Convert the image data to a specified data type.

This method changes the data type of the image pixels (e.g., from float32 to uint8). This can be useful for reducing memory usage or preparing data for specific operations.

Parameters

dtypestr or numpy.dtype

The target data type (e.g., ‘uint8’, ‘float32’, ‘int16’)

Returns

selfGeoimage

The modified image with the new data type, allowing method chaining

Examples

>>> # Convert to 8-bit unsigned integer
>>> image.astype('uint8')
>>> image.info()  # Should show dtype: uint8
>>>
>>> # Convert to 32-bit floating point
>>> image.astype('float32')
>>> image.visu()

Notes

Common data types for geospatial data: - uint8: 8-bit unsigned integer (0-255), useful for RGB display - int16: 16-bit signed integer (-32768 to 32767), common for satellite data - uint16: 16-bit unsigned integer (0-65535), common for satellite data - float32: 32-bit floating point, useful for continuous values and calculations - float64: 64-bit floating point, highest precision but more memory usage

Warning: Converting to a smaller data type may result in loss of information or precision. For example, converting float32 to uint8.

reproject(projection='EPSG:3857', inplace=False, dest_name=None)

Reproject the image to a different coordinate reference system (CRS).

This method transforms the image to a new projection system, which changes how the image’s coordinates are interpreted. This can be useful for aligning data from different sources or preparing data for specific analyses.

Parameters

projectionstr, optional

The target projection as an EPSG code or PROJ string. Examples:

• “EPSG:4326”: WGS84 geographic (lat/lon)

• “EPSG:3857”: Web Mercator (used by web maps)

• “EPSG:32619”: UTM Zone 19N

Default is “EPSG:3857” (Web Mercator).

inplacebool, default False

If False, return a copy. Otherwise, do reprojection in place and return None.

dest_namestr, optional

Path to save the reprojected image. If None, the image is not saved. Default is None.

Returns

Geoimage

The reprojected image or None if inplace=True

Examples

>>> # Reproject to WGS84 (latitude/longitude)
>>> image_reprojected = image.reproject("EPSG:4326")
>>> image_reprojected.info()  # Shows new projection
>>>
>>> # Reproject to UTM Zone 17N and save
>>> image_reprojected = image.reproject("EPSG:32617", dest_name="utm.tif")
>>>
>>>
>>> # Reproject to WGS84 (latitude/longitude) and modify inplace the image
>>> image.reproject("EPSG:4326", inplace=True)
>>> image.info()  # Shows new projection
>>>
>>> # Reproject to UTM Zone 17N and save
>>> image.reproject("EPSG:32617", dest_name="utm.tif", inplace=True)

Notes

• Reprojection can change the pixel values due to resampling

• The dimensions of the image will typically change during reprojection

• Common projection systems include:

• EPSG:4326 - WGS84 geographic coordinates (latitude/longitude)

• EPSG:3857 - Web Mercator (used by Google Maps, OpenStreetMap)

• EPSG:326xx - UTM Zone xx North (projected coordinate system)

• EPSG:327xx - UTM Zone xx South (projected coordinate system)

latlon2pixel(coord_lat, coord_lon)

Convert geographic coordinates (latitude, longitude) to pixel coordinates.

This method transforms a point defined by its latitude and longitude to the corresponding pixel location (row, col) in the image.

Parameters

coord_latfloat

Latitude of the point

coord_lonfloat

Longitude of the point

Returns

tuple of int

The pixel coordinates as (row, col) or (i, j)

Examples

>>> # Convert a geographic location to pixel coordinates
>>> latitude, longitude = 42.36, -71.06  # Boston, MA
>>> row, col = image.latlon2pixel(latitude, longitude)
>>> print(f"This location is at pixel ({row}, {col})")
>>>
>>> # Check if a specific location is within the image extent
>>> row, col = image.latlon2pixel(latitude, longitude)
>>> in_bounds = (0 <= row < image.shape[0]) and (0 <= col < image.shape[1])
>>> print(f"Location is within image: {in_bounds}")

Notes

• The image must be georeferenced (have valid CRS and transform)

• If the point is outside the image extent, the function will still return pixel coordinates, but they may be outside the valid image dimensions

• Row (i) corresponds to the vertical position (along latitude)

• Column (j) corresponds to the horizontal position (along longitude)

pixel2latlon(i, j)

Convert pixel coordinates to geographic coordinates (latitude, longitude).

This method transforms a pixel location (row, col) in the image to the corresponding point defined by its latitude and longitude.

Parameters

iint

Row index (vertical position) in the image

jint

Column index (horizontal position) in the image

Returns

tuple of float

The geographic coordinates as (latitude, longitude)

Examples

>>> # Convert pixel coordinates to geographic location
>>> row, col = 500, 700
>>> latitude, longitude = image.pixel2latlon(row, col)
>>> print(f"Pixel ({row}, {col}) is at lat/lon: ({latitude}, {longitude})")
>>>
>>> # Find coordinates of image corners
>>> nw_lat, nw_lon = image.pixel2latlon(0, 0)  # Northwest corner
>>> se_lat, se_lon = image.pixel2latlon(image.shape[0]-1, image.shape[1]-1)  # Southeast
>>> print(f"Image covers from ({nw_lat}, {nw_lon}) to ({se_lat}, {se_lon})")

Notes

• The image must be georeferenced (have valid CRS and transform)

• Pixel coordinates typically start at (0, 0) in the upper-left corner of the image

• For most projections, latitude increases going north and longitude increases going east

save(dest_name)

Save the image to a GeoTIFF or JPEG2000 file.

This method writes the image data and all its metadata (projection, transform, etc.) to a georeferenced file that can be read by most geospatial software.

Parameters

dest_namestr

Path to save the image. File format is determined by the extension: - .tif or .tiff: GeoTIFF format - .jp2: JPEG2000 format

Returns

None

Examples

>>> # Save as GeoTIFF
>>> image.save("output.tif")
>>>
>>> # Save as JPEG2000
>>> image.save("output.jp2")

Notes

• GeoTIFF (.tif) is the most widely supported format

• JPEG2000 (.jp2) offers compression and is good for large images

• The saved file will include all metadata (projection, transform, etc.)

• To save a subset of bands, first use select_bands() to create a new image with only the desired bands, then save that image

extract_from_shapefile(name_shp, value, attribute='code', nodata_value=0, inplace=False, keep_size=False)

Extract data from areas matching a shapefile attribute value.

This method modifies the image by keeping only data where the shapefile has polygons with the specified attribute value. All other areas are set to nodata_value.

Parameters

name_shpstr

Path to the shapefile (.shp) to use for extraction

valueint or float

The attribute value to extract (e.g., extract only areas with code=3)

attributestr, optional

The name of the attribute field in the shapefile to use. Default is ‘code’.

nodata_valueint or float, optional

Value to assign to areas outside the extracted regions. Default is 0.

inplacebool, default False

If False, return a copy. Otherwise, do the extraction in place

keep_sizebool, optional

If True, output has the same dimensions as input. If False, output is cropped to the shapefile extent. Default is False.

Returns

Geoimage

The image containing only the extracted regions or None if inplace = True

Examples

>>> # Extract only forest areas (assuming forest has code 3 in the shapefile)
>>> image_forest = image.extract_from_shapefile("landcover.shp", 3)
>>> image.visu()
>>>
>>> # Keep only urban areas and preserve the original image size
>>> image.extract_from_shapefile(
>>>      "landcover.shp", 1, attribute="class",
>>>      nodata_value=-9999, keep_size=True, inplace=True)
>>> image.save("urban_areas.tif")

Notes

• The shapefile must be in the same CRS as the image, or reprojection may be necessary

• Use shpfiles.get_shapefile_attributes(name_shp) to view available attributes

extract_from_shapeimage(shp, value, attribute='code', inplace=False, nodata_value=0, keep_size=False)

Extract data from areas matching a shape image value.

This method modifies the image by keeping only data where another Geoimage (typically created from a shapefile) has the specified value. All other areas are set to nodata_value.

Parameters

shpGeoimage

A Geoimage object, typically created from a shapefile, to use for extraction

valueint or float

The pixel value to extract from (e.g., extract only where shp has value 3)

attributestr, optional

Not used for this method, kept for API consistency with extract_from_shapefile. Default is ‘code’.

nodata_valueint or float, optional

Value to assign to areas outside the extracted regions. Default is 0.

inplacebool, default False

If False, return a copy. Otherwise, do the extraction in place

keep_sizebool, optional

If True, output has the same dimensions as input. If False, output is cropped to the shape image extent. Default is False.

Returns

Geoimage

A new Geoimage containing only the extracted regions or None if inplace=True

Examples

>>> # First create a shape image from a shapefile
>>> landcover = shpfiles.shp2geoim("landcover.shp", attribute="class")
>>>
>>> # Keep only forest areas (assuming forest has value 3)
>>> image_forest = image.extract_from_shapeimage(landcover, 3)
>>> image_forest.visu()

Notes

• The shape image must have the same CRS as the target image,or it will be resampled to match

kmeans(n_clusters=4, bands=None, random_state=None, dest_name=None, standardization=True, nb_points=1000)

Perform K-means clustering on the image data.

This method performs an unsupervised classification using K-means clustering, which groups pixels with similar spectral characteristics into a specified number of clusters.

Parameters

n_clustersint, optional

Number of clusters (classes) to create. Default is 4.

bandslist of str or None, optional

List of bands to use for clustering. If None, all bands are used. Default is None.

random_stateint or None, optional

Random seed for reproducible results. If None, results may vary between runs. Default is RANDOM_STATE (defined globally).

dest_namestr, optional

Path to save the clustered image. If None, the image is not saved. Default is None.

standardizationbool, optional

Whether to standardize bands before clustering (recommended). Default is True.

nb_pointsint or None, optional

Number of random points to sample for training the model. If None, all valid pixels are used (may be slow for large images). Default is 1000.

Returns

Geoimage

A new Geoimage containing the cluster IDs (0 to n_clusters-1)

tuple

A tuple containing (kmeans_model, scaler) for reusing the model on other images

Examples

>>> # Basic K-means clustering with 5 clusters
>>> classified, model = image.kmeans(n_clusters=5)
>>> classified.visu(colorbar=True, cmap='viridis')
>>>
>>> # Cluster using only specific bands and save result
>>> classified, model = image.kmeans(
>>>      n_clusters=3, bands=["NIR", "Red", "Green"],
>>>      dest_name="clusters.tif")
>>>
>>> # Apply same model to another image
>>> other_classified = other_image.apply_ML_model(model)

Notes

• Standardization is recommended, especially when bands have different ranges

• The returned model can be used with apply_ML_model() on other images

apply_ML_model(model, bands=None)

Apply a pre-trained machine learning model to the image.

This method applies a machine learning model (such as one created by kmeans()) to the image data, creating a new classified or transformed image.

Parameters

modeltuple

A tuple containing (ml_model, scaler) where: - ml_model: A trained scikit-learn model with a predict() method - scaler: The scaler used for standardization (or None if not used)

bandslist of str or None, optional

List of bands to use as input for the model. If None, all bands are used. Default is None.

Returns

Geoimage

A new Geoimage containing the model output

Examples

>>> # Train a model on one image and apply to another
>>> classified, model = reference_image.kmeans(n_clusters=5)
>>> new_classified = target_image.apply_ML_model(model)
>>> new_classified.visu(colorbar=True, cmap='viridis')
>>>
>>> # Train on specific bands and apply to the same bands
>>> _, model = image.kmeans(bands=["NIR", "Red"], n_clusters=3)
>>> result = image.apply_ML_model(model, bands=["NIR", "Red"])
>>> result.save("classified.tif")

Notes

• The model must have been trained on data with the same structure as what it’s being applied to (e.g., same number of bands)

• If a scaler was used during training, it will be applied before prediction

• This method is useful for:

• Applying a classification model to new images

• Ensuring consistent classification across multiple scenes

• Time-series analysis with consistent classification

adapt(imt, tab_source=None, nb=1000, mapping='gaussian', reg_e=0.1, mu=1.0, eta=0.01, bias=False, max_iter=20, verbose=True, sigma=1, inplace=False)

Adjust spectral characteristics to match a target image.

This method adapts the spectral characteristics of the current image to match those of a target image using optimal transport methods. This is useful for harmonizing images from different sensors or acquisitions.

Parameters

imtGeoimage or numpy.ndarray

Target image serving as a reference for spectral adjustment, or a NumPy array of shape (N, bands) containing N spectral samples.

tab_sourcenumpy.ndarray, optional

Required if imt is a NumPy array. Must be an array of shape (M, bands) containing spectral samples from the source image.

nbint, optional

Number of random samples used to train the transport model. Default is 1000.

mappingstr, optional

Optimal transport method to use: - ‘emd’: Earth Mover’s Distance (simplest) - ‘sinkhorn’: Sinkhorn transport with regularization (balanced) - ‘mappingtransport’: Mapping-based transport (flexible) - ‘gaussian’: Transport with Gaussian assumptions (default, robust) Default is ‘gaussian’.

reg_efloat, optional

Regularization parameter for Sinkhorn transport. Default is 1e-1.

mufloat, optional

Regularization parameter for mapping-based methods. Default is 1e0.

etafloat, optional

Learning rate for mapping-based transport methods. Default is 1e-2.

biasbool, optional

Whether to add a bias term to the transport model. Default is False.

max_iterint, optional

Maximum number of iterations for iterative transport methods. Default is 20.

verbosebool, optional

Whether to display progress information. Default is True.

sigmafloat, optional

Standard deviation used for Gaussian transport methods. Default is 1.

inplacebool, default False

If False, return a copy. Otherwise, do the adaptation in place and return None.

Returns

The image with adapted spectral characteristics or None if inplace=True

Examples

>>> # Basic spectral adaptation
>>> image_adapt = image1.adapt(image2)
>>> image_adapt.visu()  # Now spectrally similar to image2
>>>
>>> # Use specific transport method
>>> image_adapt = image1.adapt(image2, mapping='sinkhorn', reg_e=0.01)
>>> image_adapt.save("adapted_image.tif")
>>>
>>> # Adaptation using sample arrays
>>> adapted_image = image1.adapt(tab_target, tab_source = tab_source, mapping='sinkhorn', reg_e=0.01)
>>>
>>> # Basic spectral adaptation and modify inplace the image
>>> image1.adapt(image2, inplace=True)
>>> image1.visu()  # Now spectrally similar to image2

Notes

• This method is useful for:

  • Harmonizing multi-sensor data

  • Matching images acquired under different conditions

  • Preparing time-series data for consistent analysis

• Different mapping methods have different characteristics:

  • ‘emd’: Most accurate but slowest

  • ‘sinkhorn’: Good balance between accuracy and speed

  • ‘mappingtransport’: Flexible and can handle complex transformations

  • ‘gaussian’: Fastest and works well for most cases

fuse_dempster_shafer_2(*images)

Fuse the 3 band image (associated with mass functions) from multiple sources using Dempster-Shafer theory with two hypotheses: A and B.

Parameters

*imagesGeoimage

Each input is a 3-band Geoimage.

• Band 1: mass function m(A)

• Band 2: mass function m(B)

• Band 3: mass function m(A ∪ B)

Returns

Geoimage

A new Geoimage with 3 bands containing the fused mass functions: m(A), m(B), and m(A ∪ B).

Geoimage

A new Geoimage with 1 band containing the conflict values.

Examples

>>> fused, conflict = im1.fuse_dempster_shafer_2(im2)
>>> fused, conflict = im1.fuse_dempster_shafer_2(im1, im2, im3, im4)

standardize(scaler=None, dest_name=None, type='standard', inplace=False, dtype='float64')

Standardize band values.

This method performs statistical standardization of image bands, modifying the current image so values have specific statistical properties, such as zero mean and unit variance (for ‘standard’ type) or values in the 0-1 range (for ‘minmax’ type).

Parameters

scalerobject or None, optional

Scikit-learn scaler object to use. If None, a new scaler is created. Default is None.

dest_namestr, optional

Path to save the standardized image. If None, image is not saved. Default is None.

type{‘standard’, ‘minmax’}, optional

Type of standardization to apply: - ‘standard’: Standardize to zero mean and unit variance (z-scores) - ‘minmax’: Scale values to the range [0, 1] Default is ‘standard’.

inplacebool, default False

If False, return the standardization in a new image. Otherwise, do standardization in place and return None.

dtypestr, optional

Data type for the standardized image. Default is ‘float64’.

Returns

Geoimage

The image with standardized values or None if inplace=True

Examples

>>> # Standard standardization (zero mean, unit variance)
>>> im_standardized  = image.standardize()
>>> print(f"Mean: {im_standardized.mean()}, Std: {im_standardized.std()}")
>>>
>>> # Min-max scaling to [0, 1] range
>>> im_standardized  = iimage.standardize(type='minmax')
>>> print(f"Min: {im_standardized.min()}, Max: {im_standardized.max()}")
>>>
>>> # Standardize one image and apply same transformation to another (target)
>>> _, scaler = image.standardize()
>>> target_std = target.standardize(scaler=scaler)
>>>
>>> # Standard standardization of the image directly
>>> # With zero mean, unit variance
>>> image.standardize(inplace=True)
>>> print(f"Mean: {image.mean()}, Std: {image.std()}")
>>>
>>> # With min-max scaling to [0, 1] range
>>> image.standardize(type='minmax', inplace=True)
>>> print(f"Min: {image.min()}, Max: {image.max()}")
>>>
>>> # Standardize one image and apply same transformation to another (target)
>>> _, scaler = image.standardize()
>>> target.standardize(scaler=scaler, inplace=True)

Notes

• When using a pre-fit scaler, make sure it was created with data having similar statistical properties.

• Standardization is often a prerequisite for machine learning algorithms that are sensitive to data scales.

inverse_standardize(scaler, dest_name=None, inplace=False, dtype='float64')

Revert standardization.

This method creates an image by applying the inverse of a standardization transformation, converting standardized values back to their original scale.

Parameters

scalerobject

Scikit-learn scaler object that was used for the original standardization. This must have an inverse_transform() method (like StandardScaler or MinMaxScaler).

dest_namestr, optional

Path to save the restored image. If None, image is not saved. Default is None.

inplacebool, default False

If False, return a copy of the inverse standardization. Otherwise, do operation in place and return None.

dtypestr, optional

Data type for the output image. Default is ‘float64’.

Returns

Geoimage

The image with values transformed back to the original scale or None if inplace=True

Examples

>>> # Standardize and then restore original values
>>> image_copy = image.copy()
>>> image_copy_std, scaler = image_copy.standardize()
>>> image_copy_back = image_copy_std.inverse_standardize(scaler)
>>> image_copy_back.visu()  # Should look like the original
>>>
>>> # With inplace = True
>>> image_copy_std, scaler = image_copy.standardize()
>>> image_copy_std.inverse_standardize(scaler, inplace=True)
>>> image_copy_std.visu()  # Should look like the original

Notes

• The scaler must be the exact one used for the original standardization to ensure accurate inverse transformation

• This is often used as the final step in a processing pipeline to convert results back to physically meaningful units

resampling(final_resolution, dest_name=None, inplace=False, method='cubic_spline', update_history=True)

Resample the image to a different resolution.

This method changes the spatial resolution of the image by resampling the pixel values. The resampling process creates a new grid of pixels at the target resolution and interpolates values from the original grid.

Parameters

final_resolutionfloat

The target resolution in the image’s coordinate system units (typically meters or degrees). A smaller value results in a higher-resolution (larger) image.

dest_namestr, optional

Path to save the resampled image. If None, the image is not saved. Default is None.

inplacebool, default False

If False, return a copy. Otherwise, do the resampling in place and return None.

methodstr, optional

Resampling algorithm to use. Options include:

• ‘cubic_spline’ (default): High-quality interpolation, good for continuous data

• ‘nearest’: Nearest neighbor interpolation, preserves original values, best for categorical data

• ‘bilinear’: Linear interpolation between points, faster than cubic

• ‘cubic’: Standard cubic interpolation

• ‘lanczos’: High-quality downsampling

• ‘average’: Takes the average of all contributing pixels, useful for downsampling

update_historybool, optional

Whether to update the image processing history. Default is True.

Returns

Geoimage

A copy of the resampled image or None if inplace=True

Examples

>>> # Resample to 30 meter resolution
>>> image_resampled = image.resampling(30)
>>> print(f"New resolution: {image.resolution}")
>>>
>>> # Resample using nearest neighbor (best for categorical data)
>>> classified_image_resampled = classified_image.resampling(10, method='nearest')
>>>
>>> # Resample and save the result
>>> image_resampled = image.resampling(20, dest_name='resampled_20m.tif')
>>>
>>>
>>> # Resample directly the image to 30 meter resolution
>>> image.resampling(30, inplace=True)
>>> print(f"New resolution: {image.resolution}")
>>>
>>> # Resample directly the image using nearest neighbor (best for categorical data)
>>> classified_image.resampling(10, method='nearest', inplace=True)
>>>
>>> # Resample and save the result
>>> image.resampling(20, dest_name='resampled_20m.tif', inplace=True)

Notes

• When upsampling (to higher resolution), no new information is created;

the function only interpolates between existing pixels - When downsampling (to lower resolution), information is lost - The choice of resampling method is important: - For continuous data (e.g., elevation, reflectance): ‘cubic_spline’, ‘bilinear’, or ‘cubic’ - For categorical data (e.g., land classifications): ‘nearest’ or ‘mode’ - This method changes the dimensions (shape) of the image

crop(deb_row_lon, end_row_lon, deb_col_lat, end_col_lat, dest_name=None, pixel=True, inplace=False)

Crop the image to a specified extent.

This method extracts a rectangular subset of the image, defined either by pixel coordinates or by geographic coordinates, and updates the current image to contain only the cropped region.

Parameters

deb_row_lonint or float

Starting position: - If pixel=True: Starting row (y) coordinate - If pixel=False: Starting longitude coordinate

end_row_lonint or float

Ending position: - If pixel=True: Ending row (y) coordinate - If pixel=False: Ending longitude coordinate

deb_col_latint or float

Starting position: - If pixel=True: Starting column (x) coordinate - If pixel=False: Starting latitude coordinate

end_col_latint or float

Ending position: - If pixel=True: Ending column (x) coordinate - If pixel=False: Ending latitude coordinate

dest_namestr, optional

Path to save the cropped image. If None, the image is not saved. Default is None.

inplacebool, default False

If False, return a copy. Otherwise, do cropping in place and return None.

pixelbool, optional

Coordinate system flag: - If True: Coordinates are interpreted as pixel indices (row, col) - If False: Coordinates are interpreted as geographic coordinates (lon, lat) Default is True.

Returns

Geoimage

A copy of the cropped image or None if inplace=True

Examples

>>> # Crop using pixel coordinates
>>> original_shape = image.shape
>>> image_crop = image.crop(100, 500, 200, 600)
>>> print(f"Original shape: {original_shape}, New shape: {image_crop.shape}")
>>>
>>> # Crop using geographic coordinates
>>> image_crop = image.crop(-122.5, -122.3, 37.8, 37.7, pixel=False)
>>> image.visu()
>>>
>>> # Crop and save the result
>>> image_crop = image.crop(100, 500, 200, 600, dest_name='cropped_area.tif')
>>>
>>>
>>> # Crop using pixel coordinates
>>> original_shape = image.shape
>>> image.crop(100, 500, 200, 600, inplace=True) # inplace = True : modify directly the image
>>> print(f"Original shape: {original_shape}, New shape: {image.shape}")
>>>
>>> # Crop using geographic coordinates
>>> image.crop(-122.5, -122.3, 37.8, 37.7, pixel=False, inplace=True)
>>> image.visu()
>>>
>>> # Crop and save the result
>>> image.crop(100, 500, 200, 600, dest_name='cropped_area.tif', inplace=True)

Notes

• The cropping operation changes the spatial extent of the image but preserves

the resolution and projection. - When using pixel coordinates, the format is (row_start, row_end, col_start, col_end). - When using geographic coordinates, the format is (lon_start, lon_end, lat_start, lat_end).

select_bands(bands=None, dest_name=None, inplace=False, reformat_names=False)

Select only specified bands in the image

This method modifies the image to contain only the specified bands, discarding all other bands. Band naming can be preserved or updated based on parameters.

Parameters

bandsstr, list, int, or None, optional

The bands to keep in the image. Format depends on band naming: - If using named bands: band name(s) as string(s) (e.g., ‘NIR’, [‘R’, ‘G’, ‘B’]) - If using indexed bands: band index/indices as int(s) or string(s) (e.g., 3, [‘1’, ‘4’, ‘7’]) If None, no bands are selected (invalid operation).

dest_namestr, optional

Path to save the modified image. If None, the image is not saved. Default is None.

inplacebool, default False

If False, return a copy. Otherwise, modify the image by keeping only selected bands

reformat_namesbool, optional

Band naming behavior: - If True: Rename bands sequentially as “1”, “2”, “3”, etc. - If False: Preserve original band names when possible Default is False.

Returns

Geoimage

The modified image with only selected bands or None if inplace=True.

Raises

ValueError

If no bands are specified, or if any specified band doesn’t exist in the image.

Examples

>>> # Extract only 3 specific bands
>>> original_bands = list(image.names.keys())
>>> image_selected = image.select_bands(['NIR', 'Red', 'Green'])
>>> print(f"Original bands: {original_bands}, New bands: {list(image_selected.names.keys())}")
>>>
>>> # Keep bands and renumber them sequentially
>>> image.select_bands([4, 3, 2], reformat_names=True, inplace=True)
>>> print(f"Band names after reordering: {list(image.names.keys())}")
>>>
>>> # Select a single band
>>> nir = image.select_bands('NIR', dest_name='nir_only.tif')

Notes

• If band names contain duplicates, they will be automatically reformatted.

• The band order in the result matches the order in the ‘bands’ parameter.

stack(im_to_stack, dtype=None, dest_name=None, inplace=False, reformat_names=False)

Stack bands from another image onto this image.

This method combines the bands from another image with the current image, modifying the current image to include all bands from both sources.

Parameters

im_to_stackGeoimage

The image whose bands will be stacked onto this image. Should have the same spatial dimensions (rows, cols).

dtypestr or None, optional

The data type for the stacked image. If None, an appropriate type is determined based on the types of both input images. Common values: ‘float64’, ‘float32’, ‘int32’, ‘uint16’, ‘uint8’. Default is None.

dest_namestr, optional

Path to save the stacked image. If None, the image is not saved. Default is None.

inplacebool, default False

If False, return a copy of the stacked image. Otherwise, do stacking in place and return None.

reformat_namesbool, optional

If True, band names will be reset to a simple numeric format (“1”, “2”, “3”, …). If False, the function will preserve original band names where possible, adding suffixes if needed to resolve conflicts. Default is False.

Returns

Geoimage

The image with additional bands or None if inplace=True

Raises

ValueError

If the spatial dimensions of the images don’t match or an unknown dtype is specified.

Examples

>>> # Stack two images with different spectral bands
>>> optical = Geoimage("optical.tif", names={'R': 1, 'G': 2, 'B': 3})
>>> thermal = Geoimage("thermal.tif", names={'T': 1})
>>> combined = optical.stack(thermal)
>>> print(f"Combined bands: {list(combined.names.keys())}")
>>>
>>> # Stack and rename bands sequentially
>>> combined = optical.stack(thermal, reformat_names=True)
>>> print(f"After renaming: {list(combined.names.keys())}")
>>>
>>> # Stack with explicit data type
>>> combined = optical.stack(thermal, dtype='float32', dest_name='combined.tif')
>>>
>>> # Stack in the image directly
>>> optical.stack(thermal, reformat_names=True, inplace=True)
>>> print(f"After renaming: {list(combined.names.keys())}")

Notes

• The bands from both images are combined along the band dimension (axis 0).

• Band naming conflicts are resolved automatically, adding suffixes if needed.

• The spatial dimensions (rows, cols) of both images must match.

remove_bands(bands, inplace=False, reformat_names=False, dest_name=None)

Remove specified bands from the image.

This method modifies the current image by removing the specified bands. The remaining bands can be renamed sequentially or retain their original names.

Parameters

bandsstr, list, int, or array-like

The bands to remove from the image. Format depends on band naming: - If using named bands: band name(s) as string(s) (e.g., ‘NIR’, [‘R’, ‘G’, ‘B’]) - If using indexed bands: band index/indices as int(s) or string(s) (e.g., 3, [‘1’, ‘4’, ‘7’])

inplacebool, default False

If False, return a copy. Otherwise, do removing in place and return None.

reformat_namesbool, optional

Band naming behavior after removal: - If True: Rename remaining bands sequentially as “1”, “2”, “3”, etc. - If False: Preserve original band names with their indices updated Default is False.

dest_namestr, optional

Path to save the modified image. If None, the image is not saved. Default is None.

Returns

Geoimage

The image with specified bands removed or None if inplace=True

Raises

ValueError

If any specified band doesn’t exist in the image, or if removing all bands.

Examples

>>> # Remove a single band
>>> original_bands = list(image.names.keys())
>>> image_removed = image.remove_bands('B4')
>>> print(f"Original: {original_bands}, After removal: {list(image_removed.names.keys())}")
>>>
>>> # Remove multiple bands and rename sequentially
>>> image_removed = image.remove_bands(['B1', 'B2'], reformat_names=True)
>>> print(f"After renaming: {list(image_removed = .names.keys())}")
>>>
>>> # Remove bands and save the result
>>> image_removed = image.remove_bands(['SWIR1', 'SWIR2'], dest_name='visible_only.tif')
>>>
>>> # Remove a single band
>>> original_bands = list(image.names.keys())
>>> image.remove_bands('B4', inplace=True)
>>> print(f"Original: {original_bands}, After removal: {list(image.names.keys())}")
>>>
>>> # Remove multiple bands and rename sequentially
>>> image.remove_bands(['B1', 'B2'], reformat_names=True, inplace=True)
>>> print(f"After renaming: {list(image.names.keys())}")
>>>
>>> # Remove bands and save the result
>>> image.remove_bands(['SWIR1', 'SWIR2'], dest_name='visible_only.tif', inplace=True)

Notes

• If reformat_names=False (default), band names are preserved but indices are updated.

• If reformat_names=True, bands are renamed sequentially (1, 2, 3, …).

reorder_bands(band_order, inplace=False)

Reorder the image bands according to the specified order.

This method changes the order of bands in the image based on the specified band_order parameter. The current image is modified in-place or in a new Geoimage.

Parameters

band_orderlist or dict

The desired band order specification: - If list: A list of band names in the desired order Example: [‘NIR’, ‘Red’, ‘Green’, ‘Blue’] - If dict: A dictionary mapping band names to their desired positions (1-based) Example: {‘NIR’: 1, ‘Red’: 2, ‘Green’: 3, ‘Blue’: 4}

inplacebool, default False

If False, return a copy. Otherwise, do reorder bands in place and return None.

Returns

Geoimage

A copy of the image with reordered bands or None if inplace=True

Raises

ValueError

If band_order is not a list or dictionary, or if it contains bands that don’t exist in the image.

Examples

>>> # Reorder bands using a list (most common usage)
>>> image.info()  # Shows original band order
>>> image_reorder = image.reorder_bands(['B6', 'B5', 'B4'])
>>> image_reorder.info()  # Shows new band order
>>>
>>> # Directly reorder bands using a dictionary with explicit positions
>>> image.reorder_bands({'NIR': 1, 'Red': 2, 'Green': 3}, inplace=True)
>>>
>>> # Reorder bands and save
>>> image.reorder_bands(['R', 'G', 'B']).save('rgb_order.tif')

Notes

• All bands in the image must be included in band_order if using a list.

• If using a dictionary, bands not specified will be excluded.

• The band indices in the result will be updated to match the new order.

switch_band(band_to_switch, band_to_position=None, inplace=False)

Change the position of a specified band in the image.

This method modifies the current image by moving a specified band to a new position, either at the beginning of the band sequence or after a specific band.

Parameters

band_to_switchstr, int, or list

The band(s) to move to a new position. Can be specified as a band name, band index, or a list containing a single band identifier.

band_to_positionstr, int, or None, optional

The target position specification: - If None: Move the band to the first position (beginning of the sequence) - If specified: Move the band to the position immediately after this band Default is None.

inplacebool, default False

If False, return a copy. Otherwise, do switch in place and return None.

Returns

Geoimage

The image with the reordered bands or None if inplace=True

Raises

ValueError

If specified bands don’t exist or if input parameters are invalid.

Examples

>>> # Move NIR band to the first position
>>> image.info()  # Check original band order
>>> im_switch = image.switch_band('NIR')
>>> im_switch.info()  # NIR is now the first band
>>>
>>> # Move SWIR band to position after Red band
>>> im_switch = image.switch_band('SWIR', 'Red')
>>> im_switch.info()  # SWIR now follows Red
>>>
>>> # Using band indices instead of names
>>> iim_switch = mage.switch_band(5, 2)  # Move band 5 to after band 2
>>>
>>> # Move NIR band to the first position and change image directly
>>> image.info()  # Check original band order
>>> image.switch_band('NIR', inplace=True)
>>> image.info()  # NIR is now the first band
>>>
>>> # Move SWIR band to position after Red band
>>> image.switch_band('SWIR', 'Red', inplace=True)
>>> image.info()  # SWIR now follows Red
>>>
>>> # Using band indices instead of names
>>> image.switch_band(5, 2, inplace=True)  # Move band 5 to after band 2

Notes

• When multiple bands should be moved as a unit, provide them in a list

as the band_to_switch parameter. - The band indices in the result will be updated to reflect the new order.

add_band(spectral_band, name_band=None, after_band=None, dtype=None, inplace=False, dest_name=None)

Add a new spectral band to the image.

This method adds a new spectral band to the current image. The new band can be placed at the end of the band stack (default) or after a specified band.

Parameters

spectral_bandnumpy.ndarray

The spectral band data to add. Can be in any of the following formats: - 2D array with shape (rows, cols) - 3D array with shape (1, rows, cols) - 3D array with shape (rows, cols, 1) The spatial dimensions must match the current image.

name_bandstr, optional

Name to assign to the new band. If None, a sequential name will be used. Default is None.

after_bandstr, int, or None, optional

Specify where to insert the new band: - If None: Add to the end of the band stack (default) - If str or int: Insert after the specified band name or index Default is None.

dtypestr or None, optional

Data type for the new band and resulting image. If None, preserves the highest precision type between the current image and the new band. Common values: ‘float64’, ‘float32’, ‘int32’, ‘uint16’, ‘uint8’. Default is None.

inplacebool, default False

If False, return a copy of the image with added band Otherwise, adding band in place and return None.

dest_namestr, optional

Path to save the updated image. If None, the image is not saved. Default is None.

Returns

Geoimage

The modified image with the new band added or None if inplace=True.

Raises

ValueError

If dimensions don’t match, if the dtype is unknown, or if the after_band doesn’t exist in the image.

Examples

>>> # Add a NDVI band to the end
>>> ndvi = (image.select_band('NIR') - image.select_band('Red') / (image.select_band('NIR') + image.select_band('Red')
>>> image_and_ndvi = image.add_band(ndvi, name_band='NDVI')
>>> image_and_ndvi.info()  # Shows NDVI as the last band
>>>
>>> # Add a band after a specific position
>>> image_and_ndvi = image.add_band(thermal_data, name_band='TIR', after_band='NIR')
>>>
>>> # Add with explicit data type and save
>>> image.add_band(elevation, name_band='DEM', dtype='float32',inplace = True,
>>>                dest_name='with_dem.tif')

Notes

• This method modifies the current image by adding a new band.

• The spatial dimensions (rows, cols) of the new band must match the current image.

rastereasy.utils module

rastereasy.utils.parse_rdc_meta(rdc_path)

Reads the .rdc file and returns a dictionary of metadata.

rastereasy.utils.get_crs_from_rdc(rdc_meta)

Creates a CRS object based on the information extracted from the RDC file.

Parameters:

rdc_meta (dict) – A dictionary containing metadata from the RDC file.

Returns:

A CRS object defined by rasterio.

Return type:

CRS

rastereasy.utils.isfile_casesensitive(path)

rastereasy.utils.find_rst_and_rdc(base_name)

Finds the correct file names for .rst and .rdc files, handling case sensitivity.

Parameters:

base_name (str) – The base name of the files (without extension).

Returns:

A tuple containing:

• rst_file (str): The full path to the .rst file, or None if not found.

• rdc_file (str): The full path to the .rdc file, or None if not found.

Return type:

tuple

rastereasy.utils.read_rst_with_rdc(rst_file, rdc_file, target_crs='EPSG:4326')

Reads an .rst file with its associated .rdc metadata file, reprojects the data if the coordinate system is not standard, and returns the data array and metadata.

Parameters:

• rst_file (str) – Path to the .rst raster file.

• rdc_file (str) – Path to the associated .rdc metadata file.

• target_crs (str) – Target CRS for reprojection (default is “EPSG:4326”).

Returns:

A tuple containing:

• data (numpy.ndarray): The raster data array.

• metadata (dict): Metadata including the CRS, transform, and other info.

Return type:

tuple

rastereasy.utils.list_fles(path, ext)

returns a list with sorted files in the folder “path” with extension “ext”

rastereasy.utils.normalize(band, percentile=2)

rastereasy.utils.get_percentile(band, percentile=2)

rastereasy.utils.get_tiles_recovery(ds, width=128, height=128, overlap=28)

get window and transformation information for the split of an image ds in snippets of size width x height with an overlap

rastereasy.utils.split_image_to_tiles(source_name, dest_name, size_row, size_col, overlap=0, name='sequence', verbose=0, name_tile=None)

Split a georeferenced image into smaller tiles with optional overlap and save the resulting tiles and associated georeferencing information.

Parameters

source_namestr

The file path to the input georeferenced image (e.g., a GeoTIFF) that needs to be split.

dest_namestr

The destination folder where the tiles and their associated georeferencing information will be saved.

size_rowint

The number of rows (row) for each tile. This defines the vertical size of each tile.

size_colint

The number of columns (col) for each tile. This defines the horizontal size of each tile.

overlapint, optional, default=0

The number of pixels to overlap between adjacent tiles. If set to 0, there will be no overlap between tiles.

namestr, optional, default=’sequence’

The base name for the saved tiles. The tiles will be named sequentially (e.g., ‘sequence_1.tif’, ‘sequence_2.tif’, etc.) unless name_tile is provided.

verboseint, optional, default=0

If set to 1 or higher, additional information about the process will be printed (e.g., progress messages).

name_tilestr, optional, default=None

If specified, the base name for the tiles will be overridden. Each tile will be named according to this value (e.g., ‘tile_1.tif’, ‘tile_2.tif’, etc.).

Returns

None

The function saves the resulting tiles and georeferencing information into the specified destination folder. It does not return any value.

Examples

>>> split_image_to_tiles('input_image.tif', 'tiles_folder', 256, 256)
>>> # Split an image into 256x256 tiles with no overlap:
>>>
>>> split_image_to_tiles('input_image.tif', 'tiles_folder', 256, 256, overlap=50)
>>> # Split an image into 256x256 tiles with 50 pixels overlap:
>>>
>>> split_image_to_tiles('input_image.tif', 'tiles_folder', 128, 128, name='part')
>>> # Split an image into 128x128 tiles and name the tiles 'part_1', 'part_2', etc.:

Notes

• The function reads a georeferenced image, splits it into smaller tiles of size size_row x size_col, and saves each tile with its associated georeferencing information.

• If an overlap is specified, the tiles will include the specified number of pixels from adjacent tiles, ensuring that there is continuity across the tiles when reconstructed.

rastereasy.utils.resampling_source(source_name, final_resolution, dest_name=None, method='cubic_spline', channel_first=True)

Resamples a GeoTIFF image to a specified resolution.

Parameters:

• source_name (str) – Name of the input GeoTIFF image.

• final_resolution (float) – Desired resolution in meters.

• dest_name (str, optional) – Name of the output resampled image. Defaults to None.

• method (str, optional) – Resampling method. Defaults to “cubic_spline”. See details here: https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Resampling.

• channel_first (bool, optional) – If True, outputs an image with shape (bands x rows x cols). If False, outputs an image with shape (rows x cols x bands). Defaults to True.

Returns:

The resampled image. - meta (dict): Metadata of the resampled image.

Return type:

• image (numpy.ndarray)

rastereasy.utils.resample_image_with_resolution(src_filename, resolution, method='cubic_spline', dest_name=None, channel_first=True)

Resamples an image to a specified resolution.

Parameters:

• src_filename (str) – Name of the input GeoTIFF image.

• resolution (float) – Desired resolution in meters.

• method (str, optional) – Resampling method. Defaults to “cubic_spline”. See details here: https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Resampling.

• dest_name (str, optional) – Name of the output resampled image. Defaults to None.

• channel_first (bool, optional) – If True, outputs an image with shape (bands x rows x cols). If False, outputs an image with shape (rows x cols x bands). Defaults to True.

Returns:

A tuple containing:

• image (numpy.ndarray): The resampled image.

• meta (dict): Metadata of the resampled image.

Return type:

tuple

rastereasy.utils.resampling_image(image, meta, final_resolution, dest_name=None, method='cubic_spline', channel_first=True)

Resampling of an image

• image: the input image as a numpy array

• meta: metadata of the image (dictionary)

• final_resolution: the desired resolution (in meters)

• dest_name: (optional) name of the resampled image file

• method: resampling method (default: cubic_spline)

• channel_first (optional, default True): output an image of shape (bands x height x width)

  otherwise: (height x width x bands)

• return: resampled image, updated meta

rastereasy.utils.numpy_to_string_list(a, delimiter=', ')

Converts a NumPy object into a list of strings, with an optional delimiter.

Parameters:

• a – A NumPy object (integer, array of integers or strings).

• delimiter – The delimiter to use between elements of the list (default: ‘, ‘).

Returns:

A list of strings.

rastereasy.utils.latlon_to_pixels(meta, lat, lon)

Converts latitude/longitude coordinates to pixel coordinates (i, j).

Arguments: - meta: metadata dictionary (from src.meta) - lat: latitude - lon: longitude

Returns: - pix_i, pix_j: pixel indices (row, column) corresponding to the input coordinates

rastereasy.utils.pixels_to_latlon(meta, pix_i, pix_j)

Converts pixel coordinates to latitude/longitude.

Arguments: - meta: metadata dictionary (from src.meta) - pix_i: row (i) coordinate of the pixel - pix_j: column (j) coordinate of the pixel

Returns: - lat, lon: corresponding latitude and longitude

rastereasy.utils.reindex_dictionary(dictionary, keys_to_remove)

Reindexes a dictionary after removing specified keys.

Parameters:

• dictionary – The dictionary to modify.

• keys_to_remove – A list of keys to remove.

Returns:

A new dictionary with the removed keys and reindexed values.

rastereasy.utils.reindex_dictionary_keep_order(dictionary, keys_to_keep)

Reindexes a dictionary keeping only specified keys and preserving their order.

Parameters:

• dictionary – The dictionary to modify.

• keys_to_keep – A list of keys to keep.

Returns:

A new dictionary with the specified keys and reindexed values.

rastereasy.utils.reorder_dict_by_values(dictionary)

Reorders a dictionary by its values in ascending order.

Parameters:

dictionary – The dictionary to reorder.

Returns:

A new dictionary with items ordered by their values.

rastereasy.utils.lowest_value_dict(dictionary)

returns the lowest in a dictionary

rastereasy.utils.has_duplicates(tab)

Verify if a table has similar values

Parameters:

tab – the table

Returns:

True if it contains similar values, False else

rastereasy.utils.split_keys(names_dict, key)

Returns two lists of keys: one with keys before a given key and one with keys after it.

Parameters

names_dictdict

Dictionary containing keys and their values.

keystr

The key used to split the lists of keys before and after.

Returns

list, list

Two lists: one with keys before the given key and one with keys after.

rastereasy.utils.initialize_dict(n)

create a dictionnary such as {“1”:1,”2”:2,…,”n”:n}

rastereasy.utils.add_ordered_key(dictionary_input, key_name=None)

Adds a key to the end of an ordered dictionary, following specific rules.

Parameters:

• dictionary – The ordered dictionary to modify.

• key_name – The name of the new key (optional).

Returns:

The modified dictionary with the new key.

rastereasy.utils.concat_dicts_with_keys(dict1, dict2)

Concatenates two dictionaries, renaming duplicate keys with a suffix and assigning sequential values.

Parameters:

• dict1 – The first dictionary.

• dict2 – The second dictionary.

Returns:

A new dictionary with renamed keys and sequential values.

rastereasy.utils.has_common_key(dict1, dict2)

Checks if there is at least one common key between two dictionaries.

Parameters:

• dict1 (dict) – The first dictionary.

• dict2 (dict) – The second dictionary.

Returns:

True if there is at least one common key, False otherwise.

Return type:

bool

rastereasy.utils.concat_dicts_with_keys_unmodified(dict1, dict2)

Concatenates two dictionaries, renaming duplicate keys with a suffix and assigning sequential values.

Parameters:

• dict1 – The first dictionary.

• dict2 – The second dictionary.

Returns:

A new dictionary with renamed keys and sequential values.

rastereasy.utils.latlon2meters(lon1, lat1, lon2, lat2)

rastereasy.utils.calculate_bounds(meta)

Compute boundaries from meta_informations Input : meta informations Output : bounding bos

rastereasy.utils.ajust_sizes(im1, im2)

rastereasy.utils.is_value_compatible(value, dtype_str)

Checks if the given value is compatible with the specified data type (provided as a string).

Parameters: - value: the value to be checked - dtype_str: the data type as a string (e.g., ‘bool’, ‘uint8’, ‘int32’, etc.)

Returns: - True if the value is compatible with the data type, False otherwise

rastereasy.utils.adapt_nodata(dtype_str, nodata)

Adjusts the nodata value if it’s not compatible with the specified data type.

Parameters: - dtype_str: the target data type as a string (e.g., ‘bool’, ‘uint8’, ‘int32’, etc.) - nodata: the current nodata value

Returns: - The adjusted nodata value, compatible with dtype_str

rastereasy.utils.extract_colorcomp(im_input, bands=None, percentile=2)

Extracts a color composition from an image.

Parameters:

• im_input (geoimage) – The input image.

• bands (numpy.ndarray, optional) – A NumPy array specifying the bands to extract. - Can be a list of integer indices (e.g., [4, 2, 3]). - Can be a list of band names (e.g., [“R”, “G”, “B”]). If band names are used, the names argument must also be provided.

• percentile (int, optional) – The percentile to use for stretching the intensity values (default: 2).

Returns:

A new geoimage containing the extracted color composition.

Return type:

geoimage

Raises:

ValueError – If invalid band indices or names are provided.

Note: - If band names are used, a corresponding dictionary must be provided in the names argument to map band names to indices.

rastereasy.utils.reset_matplotlib(mode='inline')

rastereasy.utils.is_notebook()

rastereasy.utils.plot_clic_spectra(im, imc, figsize=(15, 5), plot_legend=False, names=None, title_im='Original image (click outside or finish button to stop)', title_spectra='Spectra', xlabel='Bands', ylabel='Value', callback=None)

rastereasy.utils.dict_keys_to_list(d)

Convert dictionary keys to a list of strings.

Parameters

ddict

The input dictionary.

Returns

list of str

A list containing the keys of the dictionary as strings.

Example

>>> dict_keys_to_list({'a': 1, 'b': 2, 'c': 3})
['a', 'b', 'c']

rastereasy.utils.match_dimensions(tab1, tab2)

rastereasy.utils.resize_array(array, new_shape)

rastereasy.utils.fusion_2classes(m1, m2)

Fuse two mass function tables using a specified rule.

Parameters

m1numpy.ndarray

A N x 3 array representing source 1. Columns correspond to m(class 1), m(class 2), and m(class 1 ∪ class 2).

m2numpy.ndarray

A N x 3 array representing source 2. Columns correspond to m(class 1), m(class 2), and m(class 1 ∪ class 2).

Returns

numpy.ndarray

A N x 3 array containing the fused mass functions: m(class 1), m(class 2), and m(class 1 ∪ class 2).

numpy.ndarray

A 1D array of length N containing the conflict values for each row.

Examples

>>> fused, conflict = fuse_mass_functions(m1, m2)

rastereasy.utils.fusion_multisource(*args)

Fuse multiple mass function tables from different sources.

Parameters

*argstuple of numpy.ndarray

Each argument is an N x 3 array representing a source. Columns correspond to m(class 1), m(class 2), and m(class 1 ∪ class 2).

Returns

numpy.ndarray

A N x 3 array containing the fused mass functions: m(class 1), m(class 2), and m(class 1 ∪ class 2).

numpy.ndarray

A 1D array of length N containing the conflict values for each row.

Examples

>>> fused, conflict = fusion_multisource(m1, m2, m3)

Module contents

Rastereasy: A Python library for raster data processing.

This package provides tools to handle georeferenced raster images with functionalities like resampling, reprojection, NDVI computation, and more.

Modules:

• rastereasy: Core functionalities for raster data.

• utils: Helper functions for common operations.

Example:

>>> import rastereasy
>>> image = rastereasy.Geoimage("example.tif")
>>> image.info()
>>> image.colorcomp(['4', '3', '2'], inplace = True)
>>> image.resampling(2, inplace = True)
>>> image.reproject("EPSG:4326", inplace = True)
>>> image.save("output.tif")