Raster Blocks

Raster-type blocks contain rasters with a time axis. Internally, the raster data is stored as NumPy arrays.

API Specification

Module containing the raster block base classes.

class dask_geomodeling.raster.base.RasterBlock(*args)

The base block for temporal rasters.

All raster blocks must be derived from this base class and must implement the following attributes:

  • period: a tuple of datetimes
  • timedelta: a datetime.timedelta (or None if nonequidistant)
  • extent: a tuple (x1, y1, x2, y2)
  • dtype: a numpy dtype object
  • fillvalue: a number
  • geometry: OGR Geometry
  • projection: WKT string
  • geo_transform: a tuple of 6 numbers

These attributes are None if the raster is empty.

A raster data request contains the following fields:

  • mode: values ('vals'), time ('time') or metadata ('meta')
  • bbox: bounding box (x1, y1, x2, y2)
  • projection: wkt spatial reference
  • width: data width
  • height: data height
  • start: start date as naive UTC datetime
  • stop: stop date as naive UTC datetime

The data response contains the following:

  • if mode was 'vals': a three dimensional array of shape (bands, height, width)
  • if mode was 'time': a list of naive UTC datetimes corresponding to the time axis
  • if mode was 'meta': a list of metadata values corresponding to the time axis

dask_geomodeling.raster.combine

Module containing raster blocks that combine rasters.

class dask_geomodeling.raster.combine.Group(*args)

Combine multiple rasters into a single one.

Parameters:args (list of RasterBlock) – multiple RasterBlocks to be combined.

Values at equal timesteps in the contributing rasters are pasted left to right. Therefore values from rasters that are more ‘to the left’ are shadowed by values from rasters more ‘to the right’. However, ‘no data’ values are transparent and do not shadow underlying data values.

In the case of aligned equidistant time characteristics, the procedure will use slicing in the processing of the result for optimum performance.

dask_geomodeling.raster.elemwise

Module containing elementwise raster blocks.

class dask_geomodeling.raster.elemwise.Add(a, b)

Add a value.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Subtract(a, b)

Subtract a constant value from a store or vice versa.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Multiply(a, b)

Multiply by a value.

Parameters:
  • a (RasterBlock, scalar) – Multiplication parameter a
  • b (RasterBlock, scalar) – Multiplication parameter b

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Divide(a, b)

Divide Store by a constant value or vice versa.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Power(a, b)

Raise each number in a to the power b.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.FillNoData(*args)

Combines multiple rasters, filling in nodata values.

Parameters:args (list of RasterBlock) – list of raster sources to be combined.

Values at equal timesteps in the contributing rasters are pasted left to right. Therefore values from rasters that are more ‘to the left’ are shadowed by values from rasters more ‘to the right’. However, ‘no data’ values are transparent and do not shadow underlying data values.

class dask_geomodeling.raster.elemwise.Equal(a, b)

Compares the values of two stores and returns True if they are equal.

Note that “no data” is not equal to “no data”.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.NotEqual(a, b)

Compares the values of two stores and returns False if they are equal.

Note that “no data” is not equal to “no data”.

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Greater(a, b)

Returns True if a is greater than b.

Note that “no data” will always return False

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.GreaterEqual(a, b)

Returns True if a is greater than or equal to b.

Note that “no data” will always return False

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Less(a, b)

Returns True if a is less than b.

Note that “no data” will always return False

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.LessEqual(a, b)

Returns True if a is less than or equal to b.

Note that “no data” will always return False

Parameters:

At least one of the parameters should be a RasterBlock. If the params are both RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Invert(x)

Swaps False and True (“not x” or “~x”).

Parameters:x (RasterBlock) – raster data to invert
class dask_geomodeling.raster.elemwise.And(a, b)

Returns True where a and b are True.

Parameters:

All input parameters should have a boolean dtype and at least one of the parameters should be a RasterBlock. If both are RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Or(a, b)

Returns True where a or b are True.

Parameters:

All input parameters should have a boolean dtype and at least one of the parameters should be a RasterBlock. If both are RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.Xor(a, b)

Returns True where either a or b is True (exclusive-or)

Parameters:

All input parameters should have a boolean dtype and at least one of the parameters should be a RasterBlock. If both are RasterBlocks, they should share exactly the same time structure. The Snap block can be used to accomplish this.

class dask_geomodeling.raster.elemwise.IsData(store)

Returns True where raster has data.

Parameters:store (RasterBlock) –
class dask_geomodeling.raster.elemwise.IsNoData(store)

Returns True where raster has no data.

Parameters:store (RasterBlock) –

dask_geomodeling.raster.misc

Module containing miscellaneous raster blocks.

class dask_geomodeling.raster.misc.Clip(store, source)

Make result values ‘no data’ if it is ‘no data’ in the source. If source is a boolean mask, False values become ‘no data’.

Parameters:
  • store (RasterBlock) – The store-like whose values are to be converted.
  • source (RasterBlock) – The store-like as the source for ‘data or no data’
extent

Intersection of bounding boxes of ‘store’ and ‘source’.

geometry

Intersection of geometries of ‘store’ and ‘source’.

class dask_geomodeling.raster.misc.Classify(store, bins, right=False)

Classify raster data into a binned categories

Parameters:
  • store (RasterBlock) – rasterdata to classify
  • bins (list) – a 1-dimensional and monotonic list of bin edges
  • right (boolean) – whether the intervals include the right or the left bin edge
See also:
https://docs.scipy.org/doc/numpy/reference/generated/numpy.digitize.html
class dask_geomodeling.raster.misc.Reclassify(store, data, select=False)

Reclassify integer data to integers or floats.

Parameters:
  • store (RasterBlock) – rasterdata to reclassify
  • data (list) – list of (from, to) values defining the reclassification the from values can be of bool or int datatype; the to values can be of int or float datatype
  • select (bool) – leave only reclassified values, set others to ‘no data’. Default False.
class dask_geomodeling.raster.misc.Mask(store, value)

Convert ‘data’ values to a single constant value.

Parameters:
  • store (Store) – The store whose values are to be converted.
  • value (number) – The constant value to be given to ‘data’ values.
class dask_geomodeling.raster.misc.MaskBelow(store, value)

Mask data below some value.

Parameters:
  • store (Store) – The store whose values are to be masked.
  • value (number) – The threshold value. Values below this will be masked.
class dask_geomodeling.raster.misc.Step(store, left=0, right=1, location=0, at=None)

Block for a constant step function with one discontinuity.

The step function is defined as: - left if x < location - at if x == location - right if x > location

Parameters:
  • store (RasterBlock) – The raster whose values are the input to the step function.
  • left (number) – value left of the discontinuity
  • right (number) – value right of the discontinuity
  • location (number) – location of the discontinuity
  • at (number) – value at the discontinuity
class dask_geomodeling.raster.misc.Rasterize(source, column_name=None, dtype=None, limit=None)

Converts geometry source to raster

Parameters:
  • source (GeometryBlock) – geometry source
  • column_name (string) – column from the geometry source to rasterize. If column_name is not provided, a boolean raster will be returned indicating where there are geometries.
  • dtype (string) – a numpy datatype specification to return the array. Defaults to ‘int32’ if column_name is not, else it defaults to ‘bool’.
  • limit (int) – the maximum number of geometries. Defaults to the geomodeling.goemetry-limit setting.
Returns:

a raster containing values from ‘column_name’ or True/False.

To rasterize floating point values, it is necessary to pass dtype=’float’.

See also:
https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html
The global geometry-limit setting can be adapted as follows:
>>> from dask import config
>>> config.set({"geomodeling.geometry-limit": 100000})

dask_geomodeling.raster.sources

Module containing raster sources.

class dask_geomodeling.raster.sources.MemorySource(data, no_data_value, projection, pixel_size, pixel_origin, time_first=0, time_delta=None, metadata=None)

A raster source that interfaces data from memory.

Nodata values are supported, but when upsampling the data, these are assumed to be 0 biasing data edges towards 0.

Parameters:
  • data (number or ndarray) – the pixel values this value will be transformed in a 3D array (t, y, x)
  • no_data_value (number) – the pixel value that designates ‘no data’
  • projection (str) – the projection of the given pixel values
  • pixel_size (float or length-2 iterable of floats) – the size of one pixel (in units given by projection) if x and y pixel sizes differ, provide them in (x, y) order
  • pixel_origin (length-2 iterable of floats) – the location (x, y) of pixel with index (0, 0)
  • time_first (integer or naive datetime) – the timestamp of the first frame in data (in milliseconds since 1-1-1970)
  • time_delta (integer or timedelta or NoneType) – the difference between two consecutive frames (in ms)
  • metadata (list or NoneType) – a list of metadata corresponding to the input frames
class dask_geomodeling.raster.sources.RasterFileSource(url, time_first=0, time_delta=300000)

A raster source that interfaces data from a file path.

Parameters:
  • url (str) – the path to the file. File paths have to be contained inside the current root setting. Relative paths are interpreted relative to this setting (but internally stored as absolute paths).
  • time_first (integer or datetime) – the timestamp of the first frame in data (in milliseconds since 1-1-1970), defaults to 1-1-1970
  • time_delta (integer or timedelta) – the difference between two consecutive frames (in ms), defaults to 5 minutes
The global root path can be adapted as follows:
>>> from dask import config
>>> config.set({"geomodeling.root": "/my/data/path"})

Note that this object keeps a file handle open. If you need to close the file handle, call block.close_dataset (or dereference the whole object).

dask_geomodeling.raster.spatial

Module containing raster blocks for spatial operations.

class dask_geomodeling.raster.spatial.Dilate(store, values)

Perform binary dilation on specific values. Dilation is done in the order of the values parameter.

Parameters:
  • store (RasterBlock) – raster to perform dilation on
  • values (list) – only dilate pixels that have these values
class dask_geomodeling.raster.spatial.Smooth(store, size, fill=0)

Smooth the values from a raster spatially using gaussian smoothing.

Parameters:
  • store (Store) – raster to smooth
  • size (scalar) – size of the smoothing in meters. the ‘sigma’ of the gaussian kernel equals size / 3.
  • fill (scalar) – fill value to be used for ‘no data’ values during smoothing. The output will not have ‘no data’ values.

The challenge is to mitigate the edge effects whilst remaining performant. If the necessary margin for smoothing is more than 6 pixels in any direction, the approach used here is requesting a zoomed out geometry, smooth that and zoom back in to the original region of interest.

class dask_geomodeling.raster.spatial.MovingMax(store, size)

Apply a spatial maximum filter to the data using a circular footprint.

Parameters:
  • store (int) – raster to apply the maximum filter on
  • size – diameter of the circular footprint in pixels

This block can be used for visualization of sparse data.

class dask_geomodeling.raster.spatial.HillShade(store, altitude=45, azimuth=315, fill=0)

Calculate a hillshade from the raster values.

Parameters:
  • store (RasterBlock) – RasterBlock object
  • size (scalar) – size of the effect, in projected units
  • altitude (scalar) – Light source altitude in degrees. Default 45.
  • azimuth (scalar) – Light source azimuth in degrees. Default 315.
  • fill (scalar) – fill value to be used for ‘no data’ values during hillshading

Hillshade, adapted from gdal algorithm. Smooths prior to shading to keep it good looking even when zoomed beyond 1:1.

dask_geomodeling.raster.temporal

Module containing raster blocks for temporal operations.

class dask_geomodeling.raster.temporal.Snap(store, index)

Snap the time structure of a raster to that of another raster.

Parameters:
  • store (RasterBlock) – Return values from this block.
  • index (RasterBlock) – Snap values to the times from this block.

On get_data, get_meta or get_time requests, it will return the data and meta from the block supplied as the store parameter, but apparently have the time structure of the Store supplied as the index parameter.

In contrast to the group block, this block does not take advantage of aligned bands in any way. Therefore the perfomance will be noticeably worse, in particular when requesting long timeslices.

class dask_geomodeling.raster.temporal.Shift(store, time)

Shift the the store by some timedelta.

Parameters:
  • store (Store) – The source whose time is to be modified.
  • time (integer) – The time to shift the store, in milliseconds.

Modifies the source’s properties and queries it such that its data appears to be shifted towards the future in case of a positive time parameter.

class dask_geomodeling.raster.temporal.TemporalAggregate(source, frequency, statistic='sum', closed=None, label=None, timezone='UTC')

Geoblock that resamples rasters in time.

Parameters:
  • source (RasterBlock) – The source whose time is to be modified.
  • frequency (string or NoneType) – the frequency to resample to, as pandas offset string if this value is None, this block will return the temporal statistic over the complete time range, with output timestamp at the end of the source’s period.
  • statistic (string) – the type of statistic to perform. Can be 'sum', 'count', 'min', 'max', 'mean', 'median', 'p<percentile>'
  • closed (string or NoneType) – {None, 'left', 'right'}. Determines what side of the interval is closed when resampling.
  • label (string or NoneType) – {None, 'left', 'right'}. Determines what side of the interval is used as output datetime.
  • timezone (string) – timezone to perform the resampling in
See also:
https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.resample.html https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#dateoffset-objects
class dask_geomodeling.raster.temporal.Cumulative(source, statistic='sum', frequency=None, timezone='UTC')

Geoblock that computes a cumulative of a raster over time.

Parameters:
  • source (RasterBlock) – The source whose time is to be modified.
  • statistic (string) – the type of statistic to perform. Can be 'sum', 'count'
  • frequency (string or NoneType) – the frequency at which to restart the cumulative. if this value is None, the cumulative will continue indefinitely
  • timezone (string) – timezone to restart the cumulative
See also:
https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#dateoffset-objects