API¶

class geedim.image.ImageAccessor(ee_image)¶

Bases: object

Accessor for ee.Image.

Parameters:: ee_image (ee.Image) – Image to access.

property info: dict[str, Any]¶: Earth Engine information as returned by ee.Image.getInfo().

property stac: dict[str, Any] | None¶: STAC dictionary. None if there is no STAC entry for this image.

property id: str | None¶: Earth Engine ID.

property index: str | None¶: Earth Engine index.

property date: datetime | None¶: Acquisition date & time. None if the system:time_start property is not present.

property properties: dict[str, Any]¶: Earth Engine image properties.

property crs: str | None¶: CRS of the minimum scale band.

property transform: list[float] | None¶: Georeferencing transform of the minimum scale band.

property shape: tuple[int, int] | None¶: (height, width) dimensions of the minimum scale band in pixels. None if the image has no fixed projection.

property count: int¶: Number of image bands.

property dtype: str | None¶: Minimum size data type able to represent all image bands.

property nodata: float | int | None¶

Masked pixel value used by Earth Engine when exporting.

For integer dtype, this is the minimum possible dtype value, and for floating point dtype, it is float('-inf').

property size: int | None¶: Image export size (bytes). None if the image has no fixed projection.

property profile: dict[str, Any] | None¶: Export image profile for Rasterio. None if the image has no fixed projection.

property scale: float | None¶: Scale of the minimum scale band in units of its CRS.

property geometry: dict | None¶: GeoJSON geometry of the image extent. None if the image has no fixed projection.

property bounded: bool¶: Whether the image is bounded.

property bandNames: list[str]¶: List of the image band names.

property bandProps: list[dict[str, Any]]¶: List of STAC band properties.

property specBands: list[str]¶: List of spectral band names.

property cloudSupport: bool¶: Whether this image has cloud mask support.

static monitorTask(task, label=None)¶

Monitor and display the progress of an export task.

Parameters:

task (Task) – Earth Engine task to monitor (e.g. as returned by toGoogleCloud()).
label (str | None) – Optional label for progress display. Defaults to the task description.

Return type:

None

projection(min_scale=True)¶

Return the projection of the minimum / maximum scale band.

Parameters:: min_scale (bool) – Whether to return the projection of the minimum (True), or maximum (False) scale band.
Returns:: Projection.
Return type:: Projection

fixed()¶

Whether the image has a fixed projection.

Return type:: Number

resample(method)¶

Resample the image.

Extends ee.Image.resample() by providing an average method for downsampling and returning images without fixed projections (e.g. composites) unaltered.

Composites can be resampled by resampling their component images.

See https://developers.google.com/earth-engine/guides/resample for background information.

Parameters:: method (ResamplingMethod | str) – Resampling method to use. With the average method, the image is reprojected to the minimum scale projection before resampling.
Returns:: Resampled image if the source has a fixed projection, otherwise the source image.
Return type:: Image

toDType(dtype)¶

Convert the image data dtype.

Parameters:: dtype (str) – A NumPy / Rasterio data type to convert to.
Returns:: Converted image.
Return type:: Image

scaleOffset()¶

Apply any STAC scales and offsets to the image (e.g. for converting digital numbers to physical units).

Returns:: Scaled and offset image if STAC scales and offsets are available, otherwise the source image.
Return type:: Image

regionCoverage(region=None, scale=None, **kwargs)¶

Find the percentage of a region covered by each band of this image. The image is treated as a mask image e.g. as returned by ee.Image.mask().

Parameters:

region (dict | Geometry) – Region over which to find coverage as a GeoJSON dictionary or ee.Geometry. Defaults to the image geometry.
scale (float | Number) – Scale at which to find coverage. Defaults to the minimum scale of the image bands.
kwargs – Optional keyword arguments for ee.Image.reduceRegion(). Defaults to bestEffort=True.

Returns:

Dictionary with band name keys, and band cover percentage values.

Return type:

Dictionary

addMaskBands(**kwargs)¶

Return this image with mask and related bands added.

Existing mask bands are overwritten except if this image has no fixed projection, in which case no bands are added or overwritten.

Parameters:

mask_cirrus (bool) – Whether to mask cirrus clouds. Valid for Landsat 8-9 images, and for Sentinel-2 images with the qa mask_method. Defaults to True.
mask_shadows (bool) – Whether to mask cloud shadows. Valid for Landsat images, and for Sentinel-2 images with the qa or cloud_prob mask_method. Defaults to True.
mask_saturation (bool) – Whether to mask saturation. Valid for Landsat images. Defaults to False.
mask_nonphysical (bool) – Whether to mask reflectance outside the 0-1 reflectance range. Valid for Landsat surface reflectance images, and Sentinel-2 images. Defaults to False.
mask_aerosols (bool) – Whether to mask high aerosol levels. Valid for Landsat 8-9 surface reflectance images. Defaults to False.
mask_method (CloudMaskMethod) – Method used to mask clouds. Valid for Sentinel-2 images. Defaults to cloud_score.
prob (float) – Cloud probability threshold (%). Valid for Sentinel-2 images with the cloud_prob mask_method. Defaults to 60.
dark (float) – NIR threshold [0-1]. NIR values below this threshold are potential cloud shadows. Valid for Sentinel-2 images with the qa or cloud_prob mask_method. Defaults to 0.15.
shadow_dist (int) – Maximum distance (m) to look for cloud shadows from cloud edges. Valid for Sentinel-2 images with the qa or cloud_prob mask_method. Defaults to 1000.
buffer (int) – Distance (m) to dilate cloud. Valid for Sentinel-2 images with the qa or cloud_prob mask_method. Defaults to 50.
cdi_thresh (float) – Cloud Displacement Index threshold. Values below this threshold are considered potential clouds. If this parameter is None (the default), the index is not used. Valid for Sentinel-2 images with the qa or cloud_prob mask_method. See https://developers.google.com/earth-engine/apidocs/ee-algorithms-sentinel2-cdi for details.
max_cloud_dist (int) – Maximum distance (m) to look for clouds when forming the cloud distance band. Valid for Landsat and Sentinel-2 images. Defaults to 5000.
score (float) – Cloud Score+ threshold. Valid for Sentinel-2 images with the cloud_score mask_method. Defaults to 0.6.
cs_band (CloudScoreBand) – Cloud Score+ band to threshold. Valid for Sentinel-2 images with the cloud_score mask_method. Defaults to cs.

Returns:

Image with added mask bands.

Return type:

Image

maskClouds()¶

Return this image with cloud mask applied when supported, otherwise return this image unaltered.

Mask bands should be added with addMaskBands() before calling this method.

Returns:: Masked image.
Return type:: Image

prepareForExport(crs=None, crs_transform=None, shape=None, region=None, scale=None, resampling=near, dtype=None, scale_offset=False, bands=None)¶

Prepare the image for export.

Warning

Depending on the supplied arguments, the prepared image may be a reprojected and clipped version of the source. This type of image is not recommended for use in map display or further computation.

Parameters:

crs (str | None) – CRS of the prepared image as a well-known authority (e.g. EPSG) or WKT string. Defaults to the CRS of the minimum scale band.
crs_transform (Sequence[float] | None) – Georeferencing transform of the prepared image, as a sequence of 6 numbers. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].
shape (tuple[int, int] | None) – (height, width) dimensions of the prepared image in pixels.
region (dict[str, Any] | Geometry | None) – Region defining the prepared image bounds as a GeoJSON dictionary or ee.Geometry. Defaults to the image geometry. Ignored if crs_transform is supplied.
scale (float | None) – Pixel scale (m) of the prepared image. Defaults to the minimum scale of the image bands. Ignored if crs_transform is supplied.
resampling (str | ResamplingMethod) – Resampling method to use for reprojecting. Ignored for images without fixed projections e.g. composites. Composites can be resampled by resampling their component images.
dtype (str | None) – Data type of the prepared image (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to the minimum size data type able to represent all image bands.
scale_offset (bool) – Whether to apply any STAC band scales and offsets to the image (e.g. for converting digital numbers to physical units).
bands (list[str | int] | str | List) – Bands to include in the prepared image as a list of names / indexes, or a regex string. Defaults to all bands.

Returns:

Prepared image.

Return type:

Image

toGoogleCloud(filename, type=drive, folder=None, wait=True, **kwargs)¶

Export the image to a raster file on Google Drive, Earth Engine asset, or raster file on Google Cloud Storage, using a batch task.

prepareForExport() can be called before this method to apply export parameters.

Parameters:

filename (str) – Destination file or asset name (excluding extension).
type (ExportType) – Export type.
folder (str | None) – Google Drive folder (when type is drive), Earth Engine asset project (when type is asset), or Google Cloud Storage bucket (when type is cloud). Can include sub-folders, or an image collection name if type is asset. If type is asset and folder is not supplied, filename should be a valid Earth Engine asset ID. Required if type is cloud.
wait (bool) – Whether to wait for the export to complete before returning.
kwargs – Additional arguments to the type dependent Earth Engine function: Export.image.toDrive(), Export.image.toAsset() or Export.image.toCloudStorage().

Returns:

Export task, started if wait is False, or completed if wait is True.

Return type:

Task

toGeoTIFF(file, overwrite=False, nodata=True, driver=gtiff, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the image to a GeoTIFF file.

Export projection and bounds are defined by crs, transform and shape, and data type by dtype. prepareForExport() can be called before this method to apply export parameters.

The image is retrieved as separate tiles which are downloaded and decompressed concurrently. Tile size can be controlled with max_tile_size, max_tile_dim and max_tile_bands, and download / decompress concurrency with max_requests and max_cpus.

GeoTIFF default namespace tags are written with properties, and band tags with bandProps.

Parameters:

file (PathLike | str | OpenFile) – Destination file. Can be a path or URI string, or an OpenFile object in binary mode ('wb').
overwrite (bool) – Whether to overwrite the destination file if it exists.
nodata (bool | int | float) – How to set the GeoTIFF nodata tag. If True (the default), the nodata tag is set to nodata. Otherwise, if False, the nodata tag is not set. A custom value can also be provided, in which case the nodata tag is set to this value. Usually, a custom value would be supplied when the image has been unmasked with ee.Image.unmask(nodata).
driver (str | Driver) – File format driver.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Return type:

None

toNumPy(masked=False, structured=False, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the image to a NumPy array.

Export projection and bounds are defined by crs, transform and shape, and data type by dtype. prepareForExport() can be called before this method to apply export parameters.

Parameters:

masked (bool) – Return a ndarray with masked pixels set to the nodata value (False), or a MaskedArray (True).
structured (bool) – Return a 3D array with (row, column, band) dimensions and a numerical dtype (False), or a 2D array with (row, column) dimensions and a structured dtype representing the image bands (True).
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Returns:

NumPy array.

Return type:

ndarray

toXarray(masked=False, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the image to an Xarray DataArray.

Export projection and bounds are defined by crs, transform and shape, and data type by dtype. prepareForExport() can be called before this method to apply export parameters.

DataArray attributes include crs, transform and nodata values for compatibility with rioxarray, as well as ee and stac JSON strings of the Earth Engine property and STAC dictionaries.

Parameters:

masked (bool) – Set masked pixels in the returned array to the nodata value (False), or to NaN (True). If True, the image dtype is integer, and one or more pixels are masked, the returned array is converted to a minimal floating point type able to represent dtype.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Returns:

Image DataArray.

Return type:

DataArray

class geedim.collection.ImageCollectionAccessor(ee_coll)¶

Bases: object

Accessor for ee.ImageCollection.

Parameters:: ee_coll (ee.ImageCollection) – Image collection to access.

static fromImages(images)¶

Create an image collection with support for cloud masking, from the given images.

Images from spectrally compatible Landsat collections can be combined i.e. Landsat-4 with Landsat-5, and Landsat-8 with Landsat-9. Otherwise, images should belong to the same collection. Images may include composites created with composite(), which are treated as belonging to the collection of their component images.

Use this method (instead of ee.ImageCollection or ee.ImageCollection.fromImages()) to support cloud masking on a collection built from a sequence of images.

Parameters:: images (Any) – Sequence of images, or anything that can be used to construct an image.
Returns:: Image collection.
Return type:: ImageCollection

property info: dict[str, Any]¶: Earth Engine information as returned by ee.ImageCollection.getInfo(), but limited to the first 5000 images.

property stac: dict[str, Any] | None¶: STAC dictionary. None if there is no STAC entry for this collection.

property id: str | None¶: Earth Engine ID.

property schemaPropertyNames: tuple[str]¶: Names of properties to include in schema.

property schema: dict[str, dict]¶: Dictionary of property abbreviations and descriptions used to form schemaTable and propertiesTable.

property schemaTable: str¶: schema formatted as a printable table string.

property properties: dict[str, dict[str, Any]]¶: Dictionary of image properties. Keys are the image indexes and values the image property dictionaries.

property propertiesTable: str¶: The schema defined subset of properties, abbreviated and formatted as a printable table string.

property specBands: list[str]¶: List of spectral band names.

property cloudSupport: bool¶: Whether this collection has cloud mask support.

addMaskBands(**kwargs)¶

Return this collection with mask and related bands added.

Existing mask bands are overwritten, except on images without fixed projections, where no mask bands are added or overwritten.

Parameters:: kwargs – Cloud masking arguments - see geedim.image.ImageAccessor.addMaskBands() for details.
Returns:: Image collection with added mask bands.
Return type:: ImageCollection

maskClouds()¶

Return this collection with cloud masks applied when supported, otherwise return this collection unaltered.

Mask bands should be added with addMaskBands() before calling this method.

Returns:: Masked image collection.
Return type:: ImageCollection

medoid(bands=None)¶

Find the medoid composite of the collection images.

See https://www.mdpi.com/2072-4292/5/12/6481 for a description of the method.

Parameters:: bands (list | List) – List of bands to include in the medoid score. Defaults to specBands if available, otherwise all bands.
Returns:: Medoid composite image.
Return type:: Image

filter(start_date=None, end_date=None, region=None, fill_portion=None, cloudless_portion=None, custom_filter=None, **kwargs)¶

Filter the collection on date, region, filled / cloud-free portion, and custom criteria.

Filled and cloud-free portions are only included in returned image properties when one or both of fill_portion / cloudless_portion are supplied. If fill_portion or cloudless_portion are supplied, region is required.

Filter speeds can be improved by supplying multiple of the start_date, end_date, region and custom_filter arguments.

Parameters:

start_date (str | datetime | Date) – Start date, in ISO format if a string.
end_date (str | datetime | Date) – End date, in ISO format if a string. Defaults to a millisecond after start_date if start_date is supplied. Ignored if start_date is not supplied.
region (dict | Geometry) – Region that images should intersect as a GeoJSON dictionary or ee.Geometry.
fill_portion (float | Number) – Lower limit on the filled (valid) portion of region (%).
cloudless_portion (float | Number) – Lower limit on the cloud-free portion of the filled portion of region (%).
custom_filter (str | None) – Custom image property filter expression e.g. property > value. See the Earth Engine docs for details.
kwargs – Cloud masking arguments used for cloudless_portion - see geedim.image.ImageAccessor.addMaskBands() for details.

Returns:

Filtered image collection.

Return type:

ImageCollection

composite(method=None, mask=True, resampling=near, date=None, region=None, **kwargs)¶

Create a composite from the images in the collection.

Parameters:

method (CompositeMethod | str) – Compositing method. By default, q_mosaic is used for cloud mask supported collections, and mosaic otherwise.
mask (bool) – Whether to cloud mask images before compositing. No effect if cloud masking is not supported.
resampling (ResamplingMethod | str) – Resampling method to use on images before compositing.
date (str | datetime | Date) – Sort component images by the absolute difference between their capture time and this date. If a string, it should be in ISO format. Images are sorted by their capture time if both date and region are None (the default).
region (dict | Geometry) – Sort component images by their cloud-free portion inside this region when cloud masking is supported, otherwise sort by their filled (valid) portion. Can be a GeoJSON dictionary or ee.Geometry. Images are sorted by their capture date if both date and region are None (the default).
kwargs – Cloud/shadow masking arguments - see geedim.image.ImageAccessor.addMaskBands() for details.

Returns:

Composite image.

Return type:

Image

prepareForExport(crs=None, crs_transform=None, shape=None, region=None, scale=None, resampling=near, dtype=None, scale_offset=False, bands=None)¶

Prepare the collection for export.

Warning

The prepared collection images are reprojected and clipped versions of their source images. This type of image is not recommended for use in map display or further computation.

Parameters:

crs (str | None) – CRS of the prepared images as a well-known authority (e.g. EPSG) or WKT string. Defaults to the CRS of the minimum scale band of the first image.
crs_transform (Sequence[float] | None) – Georeferencing transform of the prepared images, as a sequence of 6 numbers. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].
shape (tuple[int, int] | None) – (height, width) dimensions of the prepared images in pixels.
region (dict[str, Any] | Geometry | None) – Region defining the prepared image bounds as a GeoJSON dictionary or ee.Geometry. Defaults to the geometry of the first image. Ignored if crs_transform is supplied.
scale (float | None) – Pixel scale (m) of the prepared images. Defaults to the minimum scale of the first image’s bands. Ignored if crs_transform is supplied.
resampling (str | ResamplingMethod) – Resampling method to use for reprojecting. Ignored for images without fixed projections e.g. composites. Composites can be resampled by resampling their component images.
dtype (str | None) – Data type of the prepared images (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to the minimum size data type able to represent all the first image’s bands.
scale_offset (bool | None) – Whether to apply any STAC band scales and offsets to the images (e.g. for converting digital numbers to physical units).
bands (list[str | int] | str | None) – Bands to include in the prepared images as a list of names / indexes, or a regex string. Defaults to all bands of the first image.

Returns:

Prepared collection.

Return type:

ImageCollection

toGoogleCloud(type=drive, folder=None, wait=True, split=bands, **kwargs)¶

Export the collection to raster files on Google Drive, Earth Engine assets, or raster files on Google Cloud Storage, using batch tasks.

All bands in the collection should share the same projection, bounds and data type. prepareForExport() can be called before this method to apply export parameters and create an export-ready collection.

A maximum of 5000 images can be exported.

Parameters:

type (ExportType) – Export type.
folder (str | None) – Google Drive folder (when type is drive), Earth Engine asset project (when type is asset), or Google Cloud Storage bucket (when type is cloud). Can include sub-folders, or an image collection name if type is asset. Required if type is asset or cloud.
wait (bool) – Whether to wait for the exports to complete before returning.
split (str | SplitType) – Export a file / asset for each collection band (bands), or for each collection image (images). Files / assets are named with their band name, and band descriptions / names set to the system:index property of the band’s source image, when split is bands. Otherwise, files / assets are named with the system:index property of the source image, and band descriptions / names set to the image band names, when split is images. Band names are prefixed with 'B_' if split is bands and type is asset.
kwargs – Additional arguments to the type dependent Earth Engine function: Export.image.toDrive(), Export.image.toAsset() or Export.image.toCloudStorage().

Returns:

List of image export tasks, started if wait is False, or completed if wait is True.

Return type:

list[Task]

toGeoTIFF(dirname, overwrite=False, split=bands, nodata=True, driver=gtiff, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the collection to GeoTIFF files.

Export projection and bounds are defined by the crs, transform and shape properties, and the data type by the dtype property of the collection images. All bands in the collection should share the same projection, bounds and data type. prepareForExport() can be called before this method to apply export parameters and create an export-ready collection.

Images are retrieved as separate tiles which are downloaded and decompressed concurrently. Tile size can be controlled with max_tile_size, max_tile_dim and max_tile_bands, and download / decompress concurrency with max_requests and max_cpus.

When split is images, GeoTIFF default namespace tags are written with the properties, and band tags with the bandProps attributes of their source images.

A maximum of 5000 images can be exported.

Parameters:

dirname (PathLike | str | OpenFile) – Destination directory. Can be a path or URI string, or an OpenFile object.
overwrite (bool) – Whether to overwrite destination files if they exist.
split (str | SplitType) – Export a file for each collection band (bands), or for each collection image (images). Files are named with their band name, and file band descriptions are set to the system:index property of the band’s source image, when split is bands. Otherwise, files are named with the system:index property of the file’s source image, and file band descriptions are set to the image band names, when split is images.
nodata (bool | int | float) – How to set the GeoTIFF nodata tags. If True (the default), the nodata tags are set to the nodata value of the collection images. Otherwise, if False, the nodata tags are not set. A custom value can also be provided, in which case the nodata tags are set to this value. Usually, a custom value would be supplied when the collection images have been unmasked with ee.Image.unmask(nodata).
driver (str | Driver) – File format driver.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Return type:

None

toNumPy(masked=False, structured=False, split=bands, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the collection to a NumPy array.

A maximum of 5000 images can be exported.

Parameters:

masked (bool) – Return a ndarray with masked pixels set to the shared nodata value of the collection images (False), or a MaskedArray (True).
structured (bool) – Return a 4D array with a numerical dtype (False), or a 2D array with a structured dtype (True). Array dimension ordering, and structured dtype fields depend on the value of split.
split (str | SplitType) – Return a 4D array with (row, column, band, image) dimensions (bands), or a 4D array with (row, column, image, band) dimensions ( images), when structured is False. Otherwise, return a 2D array with (row, column) dimensions and a structured dtype representing images nested in bands (bands), or a 2D array with (row, column) dimensions and a structured dtype representing bands nested in images (images), when structured is True.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Returns:

NumPy array.

Return type:

ndarray

toXarray(masked=False, split=bands, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None)¶

Export the collection to an Xarray Dataset.

DataArray attributes include crs, transform and nodata values for compatibility with rioxarray, as well as ee and stac JSON strings of the Earth Engine property and STAC dictionaries.

A maximum of 5000 images can be exported.

Parameters:

masked (bool) – Set masked pixels in the returned dataset to the shared nodata value of the collection images (False), or to NaN (True). If True, the export data type is integer, and one or more pixels are masked, the returned dataset is converted to a minimal floating point type able to represent the export data type.
split (str | SplitType) – Return a dataset with bands as variables (bands), or a dataset with images as variables (images). Variables are named with their band name, and time coordinates are converted from the system:start_time property of the images when split is bands. Variables are named with the system:index property of their image, and band coordinates are set to image band names when split is images.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.

Returns:

Xarray Dataset.

Return type:

Dataset

class geedim.enums.CompositeMethod(*values)¶

Bases: _StrChoiceEnum

Enumeration for the compositing method i.e. the method for finding a composite pixel from the corresponding component image pixels.

q_mosaic = 'q-mosaic'¶: Use the unmasked pixel with the highest cloud distance (distance to nearest cloud). When more than one pixel has the same cloud distance, the first one is used.

mosaic = 'mosaic'¶: Use the first unmasked pixel.

medoid = 'medoid'¶: Medoid of the unmasked pixels i.e. the pixel from the image with the minimum sum of spectral distances to the rest of the images. Where more than one pixel has the same summed distance, the first one is used. See https://www.mdpi.com/2072-4292/5/12/6481 for detail.

median = 'median'¶: Median of the unmasked pixels.

mode = 'mode'¶: Mode of the unmasked pixels.

mean = 'mean'¶: Mean of the unmasked pixels.

class geedim.enums.CloudMaskMethod(*values)¶

Bases: _StrChoiceEnum

Enumeration for the Sentinel-2 cloud masking method.

cloud_prob = 'cloud-prob'¶: Threshold the Sentinel-2 Cloud Probability.

Deprecated since version 1.9.0: Please use the cloud_score method.

qa = 'qa'¶: Bit mask the QA60 quality assessment band.

Deprecated since version 1.9.0: Please use the cloud_score method.

cloud_score = 'cloud-score'¶: Threshold the Sentinel-2 Cloud Score+.

class geedim.enums.CloudScoreBand(*values)¶

Bases: _StrChoiceEnum

Enumeration for the Sentinel-2 Cloud Score+ band to use with the cloud_score cloud masking method.

cs = 'cs'¶: Pixel quality score based on spectral distance from a (theoretical) clear reference.

cs_cdf = 'cs_cdf'¶: Value of the cumulative distribution function of possible cs values for the estimated cs value.

class geedim.enums.ResamplingMethod(*values)¶

Bases: _StrChoiceEnum

Enumeration for the resampling method.

near = 'near'¶: Nearest neighbour.

bilinear = 'bilinear'¶: Bilinear.

bicubic = 'bicubic'¶: Bicubic.

average = 'average'¶: Average.

class geedim.enums.ExportType(*values)¶

Bases: _StrChoiceEnum

Enumeration for the export type.

drive = 'drive'¶: Export to Google Drive.

asset = 'asset'¶: Export to Earth Engine asset.

cloud = 'cloud'¶: Export to Google Cloud Storage.

class geedim.enums.SpectralDistanceMetric(*values)¶

Bases: _StrChoiceEnum

Enumeration for the spectral distance metric.

sam = 'sam'¶: Spectral angle mapper.

sid = 'sid'¶: Spectral information divergence.

sed = 'sed'¶: Squared euclidean distance.

emd = 'emd'¶: Earth movers distance.

class geedim.enums.SplitType(*values)¶

Bases: _StrChoiceEnum

Enumeration for how an image collection is split when exporting.

bands = 'bands'¶: Split collection by band.

images = 'images'¶: Split collection by image.

class geedim.enums.Driver(*values)¶

Bases: _StrChoiceEnum

Enumeration for the image file format.

gtiff = 'gtiff'¶: GeoTIFF.

cog = 'cog'¶: Cloud Optimised GeoTIFF.

class geedim.mask.MaskedImage(ee_image, mask=False, region=None, **kwargs)¶

Bases: BaseImage

A class for encapsulating an Earth Engine image.

Mask and related bands are added to the supplied ee_image when it has a fixed projection.

Deprecated since version 2.0.0: Please use the ee.Image.gd accessor instead.

Parameters:

ee_image (ee.Image) – Image to encapsulate.
mask (bool) – Whether to mask the image.
region (dict | ee.Geometry) – Region over which to find filled and cloud-free portions for the image, as a GeoJSON dictionary or ee.Geometry. Portions are stored in the image properties. If None, portions are not found (the default).
kwargs – Cloud masking parameters - see addMaskBands() for details.

property ee_image: Image¶: Encapsulated Earth Engine image.

static from_id(image_id, **kwargs)¶

Create a MaskedImage instance from an Earth Engine image ID.

Parameters:

image_id (str) – ID of the Earth Engine image to encapsulate.
kwargs – Keyword arguments to pass to MaskedImage.

Returns:

Image.

Return type:

MaskedImage

property band_properties: list[dict[str, Any]]¶: List of STAC band properties.

download(filename, overwrite=False, num_threads=None, nodata=True, driver=gtiff, max_tile_size=4, max_tile_dim=10000, max_tile_bands=1024, max_requests=32, max_cpus=None, **export_kwargs)¶

Export the image to a GeoTIFF file.

GeoTIFF default namespace tags are written with properties, and band tags with band_properties.

Parameters:

filename (PathLike | str | OpenFile) – Destination file. Can be a path or URI string, or an OpenFile object in binary mode ('wb').
overwrite (bool) – Whether to overwrite the destination file if it exists.
num_threads (int | None) – Deprecated and has no effect. max_requests and max_cpus can be used to limit concurrency.
nodata (bool | int | float) – How to set the GeoTIFF nodata tag. If True (the default), the nodata tag is set to nodata. Otherwise, if False, the nodata tag is not set. A custom value can also be provided, in which case the nodata tag is set to this value. Usually, a custom value would be supplied when the image has been unmasked with ee.Image.unmask(nodata).
driver (str | Driver) – File format driver.
max_tile_size (float) – Maximum tile size (MB). Should be less than the Earth Engine size limit (32 MB).
max_tile_dim (int) – Maximum tile width / height (pixels). Should be less than the Earth Engine limit (10000).
max_tile_bands (int) – Maximum number of tile bands. Should be less than the Earth Engine limit (1024).
max_requests (int) – Maximum number of concurrent tile downloads. Should be less than the max concurrent requests quota.
max_cpus (int | None) – Maximum number of tiles to decompress concurrently. Defaults to one less than the number of CPUs, or one, whichever is greater. Values larger than the default can stall the asynchronous event loop and are not recommended.
export_kwargs – Arguments to prepareForExport().

Return type:

None

export(filename, type=drive, folder=None, wait=True, **export_kwargs)¶

Export the image to a raster file on Google Drive, Earth Engine asset, or raster file on Google Cloud Storage, using a batch task.

Parameters:

filename (str) – Destination file or asset name (excluding extension).
type (ExportType) – Export type.
folder (str | None) – Google Drive folder (when type is drive), Earth Engine asset project (when type is asset), or Google Cloud Storage bucket (when type is cloud). Can include sub-folders, or an image collection name if type is asset. If type is asset and folder is not supplied, filename should be a valid Earth Engine asset ID. Required if type is cloud.
wait (bool) – Whether to wait for the export to complete before returning.
export_kwargs – Arguments to prepareForExport().

Returns:

Export task, started if wait is False, or completed if wait is True.

Return type:

Task

property footprint: dict | None¶: GeoJSON geometry of the image extent. None if the image has no fixed projection.

property has_fixed_projection: bool¶: Whether the image has a fixed projection.

mask_clouds()¶: Apply the cloud mask if supported, otherwise leave the image unaltered.

static monitor_export(task, label=None)¶

Monitor and display the progress of an export task.

Parameters:

task (Task) – Earth Engine task to monitor (e.g. as returned by export()).
label (str | None) – Optional label for progress display. Defaults to the task description.

Return type:

None

property name: str | None¶: Image name (id with slashes replaced by dashes).

property refl_bands: list[str]¶: List of spectral band names.

property transform: Affine | None¶: Georeferencing transform of the minimum scale band.

class geedim.collection.MaskedCollection(ee_collection, add_props=None)¶

Bases: ImageCollectionAccessor

A class for encapsulating an Earth Engine image collection.

Deprecated since version 2.0.0: Please use the ee.ImageCollection.gd accessor instead.

Parameters:

ee_collection (ee.ImageCollection) – Image collection to encapsulate.
add_props (list[str] | None) – Additional image properties to include in schema and properties.

classmethod from_name(name, add_props=None)¶

Create a MaskedCollection from an Earth Engine image collection ID.

Parameters:

name (str) – Image collection ID.
add_props (list[str] | None) – Additional image properties to include in schema and properties.

Returns:

Image collection.

Return type:

MaskedCollection

classmethod from_list(image_list, add_props=None)¶

Create a MaskedCollection with support for cloud masking, that contains the given images.

Images from spectrally compatible Landsat collections can be combined i.e. Landsat-4 with Landsat-5, and Landsat-8 with Landsat-9. Otherwise, images should all belong to the same collection. Images may include composites as created with composite(). Composites are treated as belonging to the collection of their component images.

Use this method (instead of ee.ImageCollection() or ee.ImageCollection.fromImages()) to support cloud masking on a collection built from a sequence of images.

Parameters:

image_list (list[str | BaseImage | Image]) – Sequence of images, as Earth Engine image IDs, ee.Image instances or BaseImage instances.
add_props (list[str] | None) – Additional image properties to include in schema and properties.

Returns:

Image collection.

Return type:

MaskedCollection

property ee_collection: ImageCollection¶: Encapsulated Earth Engine image collection.

property name: str¶: Earth Engine image collection ID.

property image_type: type¶: MaskedImage class for images in ee_collection.

property stats_scale: float | None¶: Scale to use for finding mask portions. None if there is no STAC band information for this collection.

property schema: dict[str, dict]¶: Dictionary of property abbreviations and descriptions used to form schema_table, properties and properties_table.

property schema_table: str¶: schema formatted as a printable table string.

property properties: dict[str, dict[str, Any]]¶: Dictionary of image properties. Keys are the image IDs and values the image property dictionaries.

property properties_table: str¶: properties abbreviated with schema and formatted as a printable table string.

property refl_bands: list[str]¶: List of spectral band names.

search(*args, **kwargs)¶

Filter the collection on date, region, filled / cloud-free portion, and custom criteria.

Filter speeds can be improved by supplying multiple of the start_date, end_date, region and custom_filter arguments.

Parameters:

start_date – Start date, in ISO format if a string.
end_date – End date, in ISO format if a string. Defaults to a millisecond after start_date if start_date is supplied. Ignored if start_date is not supplied.
region – Region that images should intersect as a GeoJSON dictionary or ee.Geometry.
fill_portion – Lower limit on the filled (valid) portion of region (%).
cloudless_portion – Lower limit on the cloud-free portion of the filled portion of region (%).
custom_filter – Custom image property filter expression e.g. property > value. See the Earth Engine docs for details.
kwargs – Cloud masking arguments used for cloudless_portion - see geedim.image.ImageAccessor.addMaskBands() for details.

Returns:

Filtered image collection.

Return type:

MaskedCollection

composite(*args, **kwargs)¶

Create a composite from the images in the collection.

Parameters:

method – Compositing method. By default, q_mosaic is used for cloud mask supported collections, and mosaic otherwise.
mask – Whether to cloud mask images before compositing. No effect if cloud masking is not supported.
resampling – Resampling method to use on images before compositing.
date – Sort component images by the absolute difference between their capture time and this date. If a string, it should be in ISO format. Images are sorted by their capture time if both date and region are None (the default).
region – Sort component images by their cloud-free portion inside this region when cloud masking is supported, otherwise sort by their filled (valid) portion. Can be a GeoJSON dictionary or ee.Geometry. Images are sorted by their capture date if both date and region are None (the default).
kwargs – Cloud/shadow masking arguments - see geedim.image.ImageAccessor.addMaskBands() for details.

Returns:

Composite image.

Return type:

MaskedImage