Image Collection<a class="headerlink" href="#module-sgis.raster.image_collection" title="Link to this heading">¶

Parameters:

func_ (Callable)
copy (bool)

property band_id: str¶: Band id.

property bounds: tuple[int, int, int, int] | None¶: Bounds as tuple (minx, miny, maxx, maxy).

buffer(distance, copy=True)[source]¶

Buffer array points with the value 1 in a binary array.

Parameters:

distance (int) – Number of array cells to buffer by.
copy (bool) – Whether to copy the Band.

Return type:

Returns:

Band with buffered values.

clip(mask)[source]¶

Clip band values to geometry mask while preserving bounds.

Return type:: Band
Parameters:: mask (GeoDataFrame | GeoSeries | Polygon | MultiPolygon)

property crs: CRS | None¶: Coordinate reference system.

property date: str¶: Tile name from filename_regex.

classmethod from_geopandas(gdf, *, res=None, out_shape=None, bounds=None, fill=0, all_touched=False, merge_alg=MergeAlg.replace, default_value=1, dtype=None, **kwargs)[source]¶

Create Band from a GeoDataFrame.

Return type:

None

Parameters:

gdf (GeoDataFrame | GeoSeries)
res (int | None)
out_shape (tuple[int, int] | None)
bounds (Any | None)
fill (int)
all_touched (bool)
merge_alg (Callable)
default_value (int)
dtype (Any | None)

get_n_largest(n, precision=1e-06, column='value')[source]¶

Get the largest values of the array as polygons in a GeoDataFrame.

Return type:

GeoDataFrame

Parameters:

n (int)
precision (float)
column (str)

get_n_smallest(n, precision=1e-06, column='value')[source]¶

Get the lowest values of the array as polygons in a GeoDataFrame.

Return type:

GeoDataFrame

Parameters:

n (int)
precision (float)
column (str)

gradient(degrees=False, copy=True)[source]¶

Get the slope of an elevation band.

Calculates the absolute slope between the grid cells based on the image resolution.

For multi-band images, the calculation is done for each band.

Parameters:

band – band instance.
degrees (bool) – If False (default), the returned values will be in ratios, where a value of 1 means 1 meter up per 1 meter forward. If True, the values will be in degrees from 0 to 90.
copy (bool) – Whether to copy or overwrite the original Raster. Defaults to True.

Return type:

Returns:

The class instance with new array values, or a copy if copy is True.

Examples:¶

Making an array where the gradient to the center is always 10.

>>> import sgis as sg
>>> import numpy as np
>>> arr = np.array(
...         [
...             [100, 100, 100, 100, 100],
...             [100, 110, 110, 110, 100],
...             [100, 110, 120, 110, 100],
...             [100, 110, 110, 110, 100],
...             [100, 100, 100, 100, 100],
...         ]
...     )

Now let’s create a Raster from this array with a resolution of 10.

>>> band = sg.Band(arr, crs=None, bounds=(0, 0, 50, 50), res=10)

The gradient will be 1 (1 meter up for every meter forward). The calculation is by default done in place to save memory.

>>> band.gradient(copy=False)
>>> band.values
array([[0., 1., 1., 1., 0.],
    [1., 1., 1., 1., 1.],
    [1., 1., 0., 1., 1.],
    [1., 1., 1., 1., 1.],
    [0., 1., 1., 1., 0.]])

property has_array: bool¶: Whether the array is loaded.

property height: int¶: Pixel heigth of the image band.

load(bounds=None, indexes=None, masked=True, file_system=None, **kwargs)[source]¶

Load and potentially clip the array.

The array is stored in the ‘values’ property.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)
masked (bool)

sample(size=1000, mask=None, **kwargs)[source]¶

Take a random spatial sample area of the Band.

Return type:

Parameters:

size (int)
mask (Any)

property tile: str¶: Tile name from filename_regex.

to_geopandas(column='value', dropna=True)[source]¶

Create a GeoDataFrame from the image Band.

Parameters:

column (str) – Name of resulting column that holds the raster values.
dropna (bool) – Whether to remove values that are NA or equal to the nodata value.

Return type:

GeoDataFrame

Returns:

A GeoDataFrame with a geometry column and array values.

to_numpy()[source]¶

Convert the raster to a numpy.ndarray.

Return type:: ndarray | MaskedArray

value_counts()[source]¶

Value count of each value of the band’s array.

Return type:: Series

property values: ndarray¶: The numpy array, if loaded.

property width: int¶: Pixel width of the image band.

write(path, driver='GTiff', compress='LZW', file_system=None, **kwargs)[source]¶

Write the array as an image file.

Return type:

None

Parameters:

path (str | Path)
driver (str)
compress (str)

zonal(polygons, aggfunc, array_func=None, dropna=True)[source]¶

Calculate zonal statistics in polygons.

Parameters:

polygons (GeoDataFrame) – A GeoDataFrame of polygon geometries.
aggfunc (str | Callable | list[Callable | str]) – Function(s) of which to aggregate the values within each polygon.
array_func (Callable | None) – Optional calculation of the raster array before calculating the zonal statistics.
dropna (bool) – If True (default), polygons with all missing values will be removed.

Return type:

GeoDataFrame

Returns:

A GeoDataFrame with aggregated values per polygon.

class BandMasking(band_id, values)[source]¶

Bases: object

Frozen dict with forced keys.

Parameters:

band_id (str)
values (Sequence[int] | dict[int, Any])

class GCSFile[source]¶

Bases: object

Placeholder.

class GCSFileSystem[source]¶

Bases: object

Placeholder.

class Image(data=None, res=<class 'sgis.raster.image_collection.None_'>, mask=None, processes=1, df=None, nodata=None, all_file_paths=None, **kwargs)[source]¶

Bases: _ImageBandBase

Image consisting of one or more Bands.

Parameters:

data (str | Path | Sequence[Band] | None)
res (int | None_)
mask (Band | None)
processes (int)
df (DataFrame | None)
nodata (int | None)
all_file_paths (list[str] | None)

apply(func_, copy=True, **kwargs)[source]¶

Apply a function to each band of the Image.

Return type:

Parameters:

func_ (Callable)
copy (bool)

band_class¶: alias of Band

property band_ids: list[str]¶: The Band ids.

property bands: list[Band]¶: The Image Bands.

property bounds: tuple[int, int, int, int] | None¶: Bounds of the Image (minx, miny, maxx, maxy).

clip(mask, copy=True)[source]¶

Clip band values to geometry mask while preserving bounds.

Return type:

Parameters:

mask (GeoDataFrame | GeoSeries | Polygon | MultiPolygon)
copy (bool)

copy()[source]¶

Copy the instance and its attributes.

Return type:: Image

property crs: str | None¶: Coordinate reference system of the Image.

property date: str¶: Tile name from filename_regex.

property file_paths: list[str]¶: The Band file paths.

get_brightness(bounds=None, rbg_bands=None)[source]¶

Get a Band with a brightness score of the Image’s RBG bands.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
rbg_bands (list[str] | None)

get_image_metadata_dict()[source]¶

Creates a nested dict of metadata.

The dict structure will be:

{ :rtype: dict

image_path: {
image_attribute: value, …, “bands”: {

band_id: {
band_attribute: band_value,

}, …,

}

}

}

Return type:: dict

load(bounds=None, indexes=None, file_system=None, **kwargs)[source]¶

Load all image Bands with threading.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)

ndvi(red_band, nir_band, padding=0, copy=True)[source]¶

Calculate the NDVI for the Image.

Return type:

NDVIBand

Parameters:

red_band (str)
nir_band (str)
padding (int)
copy (bool)

sample(n=1, size=1000, mask=None, **kwargs)[source]¶

Take a random spatial sample of the image.

Return type:

Parameters:

n (int)
size (int)
mask (Any)

property tile: str¶: Tile name from filename_regex.

to_geopandas(column='value')[source]¶

Convert the array to a GeoDataFrame of grid polygons and values.

Return type:: GeoDataFrame
Parameters:: column (str)

write_image_metadata()[source]¶

Write file ‘metadata.json’ under image path.

The file will be used to give the image attributes and avoid the much slower metadata fetching with rasterio.

See method ‘get_image_metadata_dict’ for info on the structure of the json file.

Return type:: None

class ImageCollection(data, res=<class 'sgis.raster.image_collection.None_'>, level=<class 'sgis.raster.image_collection.None_'>, processes=1, metadata=None, nodata=None, **kwargs)[source]¶

Bases: _ImageBase

Collection of Images.

Loops though Images.

Parameters:

data (str | Path | Sequence[Image] | Sequence[str | Path])
res (int | None_)
level (str | None_ | None)
processes (int)
metadata (str | dict | DataFrame | None)
nodata (int | None)

apply(func_, copy=True, **kwargs)[source]¶

Apply a function to each image of the collection.

Return type:

Parameters:

func_ (Callable)
copy (bool)

band_class¶: alias of Band

property bounds: tuple[int, int, int, int]¶: Total bounds for all Images combined.

clip(mask, dropna=True, copy=True)[source]¶

Clip all image Bands while preserving bounds.

Return type:

Parameters:

mask (Geometry | GeoDataFrame | GeoSeries)
dropna (bool)
copy (bool)

property crs: Any¶: Common coordinate reference system of the Images.

property date: Any¶: List of image dates.

explode(copy=True)[source]¶

Make all Images single-banded.

Return type:: ImageCollection
Parameters:: copy (bool)

filter(bands=None, date_ranges=None, bbox=None, intersects=None, max_cloud_cover=None, copy=True)[source]¶

Filter images and bands in the collection.

Return type:

Parameters:

bands (str | list[str] | None)
date_ranges (tuple[str | Timestamp | None, str | Timestamp | None] | tuple[tuple[str | Timestamp | None, str | Timestamp | None], ...])
bbox (GeoDataFrame | GeoSeries | Geometry | tuple[float] | None)
intersects (GeoDataFrame | GeoSeries | Geometry | tuple[float] | None)
max_cloud_cover (int | None)
copy (bool)

get_unique_band_ids()[source]¶

Get a list of unique band_ids across all images.

Return type:: list[str]

groupby(by, copy=True, **kwargs)[source]¶

Group the Collection by Image or Band attribute(s).

Return type:

ImageCollectionGroupBy

Parameters:

by (str | list[str])
copy (bool)

image_class¶: alias of Image

property image_paths: Any¶: List of image paths.

property images: list[Image]¶: List of images in the Collection.

load(bounds=None, indexes=None, file_system=None, **kwargs)[source]¶

Load all image Bands with threading.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)

merge(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge all areas and all bands to a single Band.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str | Callable)
as_int (bool)
indexes (int | tuple[int] | None)

merge_by_band(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge all areas to a single tile, one band per band_id.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str)
as_int (bool)
indexes (int | tuple[int] | None)

pixelwise(func, kwargs=None, index_aligned_kwargs=None, masked=True, processes=None)[source]¶

Run a function for each pixel.

The function should take a 1d array as first argument. This will be the pixel values for all bands in all images in the collection.

Return type:

ndarray | tuple[ndarray] | None

Parameters:

func (Callable)
kwargs (dict | None)
index_aligned_kwargs (dict | None)
masked (bool)
processes (int | None)

plot_pixels(by=None, x_var='date', y_label='value', p=0.95, ylim=None, figsize=(20, 8), rounding=3)[source]¶

Plot each individual pixel in a dotplot for all dates.

Parameters:

by (str | list[str] | None) – Band attributes to groupby. Defaults to “bounds” and “band_id” if all bands have no-None band_ids, otherwise defaults to “bounds”.
x_var (str) – Attribute to use on the x-axis. Defaults to “date” if the ImageCollection is sortable by date, otherwise a range index. Can be set to “days_since_start”.
y_label (str) – Label to use on the y-axis.
p (float) – p-value for the confidence interval.
ylim (tuple[float, float] | None) – Limits of the y-axis.
figsize (tuple[int]) – Figure size as tuple (width, height).
rounding (int) – rounding of title n

Return type:

None

sample(n=1, size=500)[source]¶

Sample one or more areas of a given size and set this as mask for the images.

Return type:

Parameters:

n (int)
size (int)

sample_images(n)[source]¶

Sample one or more images in a copy of the ImageCollection.

Return type:: ImageCollection
Parameters:: n (int)

sample_tiles(n)[source]¶

Sample one or more tiles in a copy of the ImageCollection.

Return type:: ImageCollection
Parameters:: n (int)

sort_images(ascending=True)[source]¶

Sort Images by date, then file path if date attribute is missing.

Return type:: ImageCollection
Parameters:: ascending (bool)

union_all()[source]¶

(Multi)Polygon representing the union of all image bounds.

Return type:: Polygon | MultiPolygon

class ImageCollectionGroupBy(data, by, collection)[source]¶

Bases: object

Iterator and merger class returned from groupby.

Can be iterated through like pandas.DataFrameGroupBy. Or use the methods merge_by_band or merge.

Parameters:

data (Iterable[tuple[Any], ImageCollection])
by (list[str])
collection (ImageCollection)

merge(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge each group into a single Band, returned as combined Image.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str | Callable)
as_int (bool)
indexes (int | tuple[int] | None)

merge_by_band(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge each group into separate Bands per band_id, returned as an ImageCollection.

Return type: