Raster Blocks

RasterBlocks are the main component of raster operations. Most raster operations take one or more RasterBlocks as input and produce a single RasterBlock as output.

Raster-type blocks contain rasters with data in three dimensions. Besides the x- and y-axes they also have a temporal axis.

Internally, dask-geomodeling stores the raster data as NumPy arrays.

API Specification

Module containing the RasterBlock base classes.

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

The base block for temporal rasters.

All RasterBlocks 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 is None or a dictionary with the following fields:

  • (if mode was "vals") "values": a three dimensional numpy ndarray of shape (bands, height, width)

  • (if mode was "vals") "no_data_value": a number that represents ‘no data’. If the ndarray is a boolean, there is no ‘no data’ value.

  • (if mode was "time"'") "time": a list of naive UTC datetimes corresponding to the time axis

  • (if mode was "meta") "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.

Operation to combine multiple rasters into one along all three axes (x, y and temporal). To only fill ‘no data’ values of input rasters that have the same temporal resolution dask_geomodeling.raster.elemwise.FillNoData is preferred.

Values at equal timesteps in the contributing rasters are considered starting with the leftmost input raster. Therefore, values from rasters that are more ‘to the right’ are shown in the result. ‘no data’ values are transparent and will show data of rasters more ‘to the left’.

Parameters:

*args (list of RasterBlocks) – list of rasters to be combined.

Returns:

RasterBlock that combines all input rasters

dask_geomodeling.raster.elemwise

Module containing elementwise raster blocks.

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

Add two rasters together or add a constant value to a raster.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing the result of the addition.

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

Returns True where both inputs are True.

Either one or both of the inputs should be a boolean RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

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

Divide two rasters or divide a raster by a constant value.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing the result of the division.

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

Compares the values of two rasters and returns True for equal elements.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that ‘no data’ is not equal to ‘no data’: False is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

class dask_geomodeling.raster.elemwise.Exp(x)

Return e raised to the power of the raster values.

Out-of-range results (not representable by the resulting datatype) are set to no data.

Parameters:

x (RasterBlock) – Raster

Returns:

RasterBlock.

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

Combines multiple rasters filling ‘no data’ values.

Values at equal timesteps in the contributing rasters are considered starting with the leftmost input raster. Therefore, values from rasters that are more ‘to the right’ are shown in the result. ‘no data’ values are transparent and will show data of rasters more ‘to the left’.

The temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:

*args (list of RasterBlocks) – Rasters to be combined.

Returns:

RasterBlock that combines values from the inputs.

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

Compares the values of two rasters and returns True if an element in the first term is greater.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that False is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

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

” Compares the values of two rasters and returns True if an element in the first term is greater or equal.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that False is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

class dask_geomodeling.raster.elemwise.Invert(x)

Logically invert a raster (swap True and False).

Takes a single input raster containing boolean values and outputs a boolean raster with the same spatial and temportal properties.

Parameters:

x (RasterBlock) – Boolean raster with values to invert

Returns:

RasterBlock with boolean values opposite to the input raster.

class dask_geomodeling.raster.elemwise.IsData(store)

Returns True where raster has data.

Takes a single input raster and outputs a boolean raster with the same spatial and temporal properties.

Parameters:

store (RasterBlock) – Input raster

Returns:

RasterBlock with boolean values.

class dask_geomodeling.raster.elemwise.IsNoData(store)

Returns True where raster has no data.

Takes a single input raster and outputs a boolean raster with the same spatial and temporal properties.

Parameters:

store (RasterBlock) – Input raster

Returns:

RasterBlock with boolean values.

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

Compares the values of two rasters and returns True if an element in the first term is less.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that False is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

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

Compares the values of two rasters and returns True if an element in the first term is less or equal.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that False is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

class dask_geomodeling.raster.elemwise.Log(x)

Return natural logarithm of the raster values.

Out-of-range results (not representable by the resulting datatype) are set to no data as well as the result of input values < 0.

Parameters:

x (RasterBlock) – Raster

Returns:

RasterBlock.

class dask_geomodeling.raster.elemwise.Log10(x)

Return the base 10 logarithm of the raster values.

Out-of-range results (not representable by the resulting datatype) are set to no data as well as the result of input values < 0.

Parameters:

x (RasterBlock) – Raster

Returns:

RasterBlock.

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

Multiply two rasters or multiply a raster by a constant value.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing the result of the multiplication.

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

Compares the values of two rasters and returns False for equal elements.

This operation can be used to compare two rasters or to compare a raster with a static value. Note that ‘no data’ is not equal to ‘no data’: True is returned if any of the two terms is ‘no data’.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

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

Returns True where any of inputs is True.

Either one or both of the inputs should be a boolean RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

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

Exponential function with either a raster and a number or two rasters.

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing the result of the exponential function.

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

Subtract two rasters or subtract a constant value from a raster

Either one or both of the inputs should be a RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing the result of the function subtract.

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

Exclusive or: returns True where exactly one of the inputs is True.

Where both inputs are True, False is returned.

Either one or both of the inputs should be a boolean RasterBlock. In case of two raster inputs the temporal properties of the rasters should be equal, however spatial properties can be different.

Parameters:
Returns:

RasterBlock containing boolean values

dask_geomodeling.raster.misc

Module containing miscellaneous raster blocks.

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

Classify raster data into binned categories

Takes a RasterBlock and classifies its values based on bins. The bins are supplied as a list of increasing bin edges.

For each raster cell this operation returns the index of the bin to which the raster cell belongs. The lowest possible output cell value is 0, which means that the input value was lower than the lowest bin edge. The highest possible output value is equal to the number of supplied bin edges.

Parameters:
  • store (RasterBlock) – The raster whose cell values are to be classified

  • bins (list) – An increasing list of bin edges

  • right (boolean) – Whether the intervals include the right or the left bin edge, defaults to False.

Returns:

RasterBlock with classified values

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

Clip one raster to the extent of another raster.

Takes two raster inputs, one raster (‘store’) whose values are returned in the output and one raster (‘source’) that is used as the extent. Cells of the ‘store’ raster are replaced with ‘no data’ if there is no data in the ‘source’ raster.

If the ‘source’ raster is a boolean raster, False will result in ‘no data’.

Note that the input rasters are required to have the same time resolution.

Parameters:
  • store (RasterBlock) – Raster whose values are clipped

  • source (RasterBlock) – Raster that is used as the clipping mask

Returns:

RasterBlock with clipped values.

property period

Return period datetime tuple.

class dask_geomodeling.raster.misc.Mask(store, value)

Replace values in a raster with a single constant value. ‘no data’ values are preserved.

Parameters:
  • store (RasterBlock) – The raster whose values are to be converted.

  • value (number) – The constant value to be given to ‘data’ values.

Returns:

RasterBlock containing a single value

class dask_geomodeling.raster.misc.MaskBelow(store, value)

Converts raster cells below the supplied value to ‘no data’.

Raster cells with values greater than or equal to the supplied value are returned unchanged.

Parameters:
  • store (RasterBlock) – The raster whose values are to be masked.

  • value (number) – The constant value below which values are masked.

Returns:

RasterBlock with cells below the input value converted to ‘no data’.

class dask_geomodeling.raster.misc.Rasterize(source, column_name=None, dtype=None, limit=None)

Converts geometry source to raster

This operation is used to transform GeometryBlocks into RasterBlocks. Here geometries (from for example a shapefile) are converted to a raster, using the values from one of the columns.

Note that to rasterize floating point values, it is necessary to pass dtype="float".

Parameters:
  • source (GeometryBlock) – The geometry source to be rasterized

  • column_name (string) – The name of the column whose values will be returned in the raster. If column_name is not provided, a boolean raster will be generated indicating where there are geometries.

  • dtype (string) – A numpy datatype specification to return the array. Defaults to ‘int32’ if column_name is provided, or to ‘bool’ otherwise.

Returns:

RasterBlock with values from ‘column_name’ or a boolean raster.

The global geometry-limit setting can be adapted as follows:
>>> from dask import config
>>> config.set({"geomodeling.geometry-limit": 100000})
class dask_geomodeling.raster.misc.RasterizeWKT(wkt, projection)

Converts a single geometry to a raster mask

Parameters:
  • wkt (string) – the WKT representation of a geometry

  • projection (string) – the projection of the geometry

Returns:

RasterBlock with True for cells that are inside the geometry.

class dask_geomodeling.raster.misc.Reclassify(store, data, select=False)

Reclassify a raster of integer values.

This operation can be used to reclassify a classified raster into desired values. Reclassification is done by supplying a list of [from, to] pairs.

Parameters:
  • store (RasterBlock) – The raster whose cell values are to be reclassified

  • bins (list) – A list of [from, to] pairs defining the reclassification. The from values can be of bool or int datatype; the to values can be of int or float datatype

  • select (boolean) – Whether to set all non-reclassified cells to ‘no data’, defaults to False.

Returns:

RasterBlock with reclassified values

class dask_geomodeling.raster.misc.Step(store, left=0, right=1, value=0, at=None)

Apply a step function to a raster.

This operation classifies the elements of a raster into three categories: less than, equal to, and greater than a value.

The step function is defined as follows, with x being the value of a raster cell:

  • ‘left’ if x < value

  • ‘at’ if x == value

  • ‘right’ if x > value

Parameters:
  • store (RasterBlock) – The input raster

  • left (number) – Value given to cells lower than the input value, defaults to 0

  • right (number) – Value given to cells higher than the input value, defaults to 1

  • value (number) – The constant value which raster cells are compared to, defaults to 0

  • at (number) – Value given to cells equal to the input value, defaults to the average of left and right

Returns:

RasterBlock containing three values; left, right and at.

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.

The raster pixel with its topleft corner at [x, y] will define ranges [x, x + dx) and (y - dy, y]. Here [dx, dy] denotes the (unsigned) pixel size. The topleft corner and top and left edges belong to a pixel.

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.

The value at raster cell with its topleft corner at [x, y] is assumed to define a value for ranges [x, x + dx) and (y - dy, y]. Here [dx, dy] denotes the (unsigned) pixel size. The topleft corner and top and left edges belong to a pixel.

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 spatial dilation on specific cell values.

Cells with values in the supplied list are spatially dilated by one cell in each direction, including diagonals.

Dilation is performed in the order of the values parameter.

Parameters:
  • store (RasterBlock) – Raster to perform dilation on.

  • values (list) – Only cells with these values are dilated.

Returns:

RasterBlock where cells in values list are dilated.

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

Calculate a hillshade from the raster values.

Parameters:
  • store (RasterBlock) – Raster to which the hillshade algorithm is applied.

  • altitude (number) – Light source altitude in degrees, defaults to 45.

  • azimuth (number) – Light source azimuth in degrees, defaults to 315.

  • fill (number) – Fill value to be used for ‘no data’ values.

Returns:

Hillshaded raster

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

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

This can be used for visualization of sparse data.

Parameters:
  • store (RasterBlock) – Raster to which the filter is applied

  • size (integer) – Diameter of the circular footprint. This should always be an odd number larger than 1.

Returns:

RasterBlock with maximum values inside the footprint of each input cell.

class dask_geomodeling.raster.spatial.Place(store, place_projection, anchor, coordinates, statistic='last')

Place an input raster at given coordinates

Note that if the store’s projection is different from the requested one, the data will be reprojected before placing it at a different position.

Parameters:
  • store (RasterBlock) – Raster that will be placed.

  • place_projection (str) – The projection in which this operation is done. This also specifies the projection of the anchor and coordinates args.

  • anchor (list of 2 numbers) – The anchor into the source raster that will be placed at given coordinates.

  • coordinates (list of lists of 2 numbers) – The target coordinates. The center of the bbox will be placed on each of these coordinates.

  • statistic (str) – What method to use to merge overlapping rasters. One of: {“last”, “first”, “count”, “sum”, “mean”, “min”, “max”, “argmin”, “argmax”, “product”, “std”, “var”, “p<number>”}

Returns:

RasterBlock with the source raster placed

property geo_transform

The native geo_transform of this block

Returns None if the store projection and place projections differ.

property geometry

Combined geometry in this block’s native projection.

property projection

The native projection of this block.

Only returns something if the place projection equals the store projection

class dask_geomodeling.raster.spatial.Smooth(store, size, fill=0)

Smooth the values from a raster spatially using Gaussian smoothing.

Parameters:
  • store (RasterBlock) – Raster to be smoothed

  • size (number) – The extent of the smoothing in meters. The ‘sigma’ value for the Gaussian kernal equals size / 3.

  • fill (number) – ‘no data’ are replaced by this value during smoothing, defaults to 0.

Returns:

RasterBlock with spatially smoothed values.

dask_geomodeling.raster.temporal

Module containing raster blocks for temporal operations.

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

Compute the cumulative of a raster over time.

Contrary to dask_geomodeling.raster.temporal.TemporalAggregate, in this operation the timedelta of the resulting raster equals the timedelta of the input raster. Cell values are accumulated over the supplied period. At the end of each period the accumulation is reset.

Parameters:
  • source (RasterBlock) – The input raster whose timesteps are accumulated.

  • statistic (string) – The type of accumulation to perform. Can be "sum" or "count". Defaults to "sum".

  • frequency (string or None) – The period over which accumulation is performed. Supply a pandas offset string (see the references below). If this value is None, the accumulation will continue indefinitely. Defaults to None.

  • timezone (string) – Timezone in which the accumulation is performed, defaults to "UTC".

Returns:

RasterBlock with temporally accumulated data.

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

Shift a temporal raster by some timedelta.

A positive timedelta shifts into the future and a negative timedelta shifts into the past.

Parameters:
  • store (RasterBlock) – The store whose timestamps are to be shifted

  • time (integer) – The timedelta to shift the store, in milliseconds.

Returns:

RasterBlock with its timestamps shifted.

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

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

This operations allows to take the cell values from one raster (‘store’) and the temporal properties of another raster (‘index’).

If the store is not a temporal raster, its cell values are copied to each timestep of the index raster. If the store is also a temporal raster, this operation looks at each ‘index’ timestamp and takes the closest ‘store’ timestamp as cell values.

Parameters:
  • store (RasterBlock) – Return cell values from this raster

  • index (RasterBlock) – Snap values to the timestamps from this raster

Returns:

RasterBlock with temporal properties of the index.

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

Resample a raster in time.

This operation performs temporal aggregation of rasters, for example a hourly average of data that has a 5 minute resolution.. The timedelta of the resulting raster is determined by the ‘frequency’ parameter.

Parameters:
  • source (RasterBlock) – The input raster whose timesteps are aggregated

  • frequency (string or None) – The frequency to resample to, as pandas offset string (see the references below). 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 raster period. Defaults to None.

  • statistic (string) – The type of statistic to perform. Can be one of {"sum", "count", "min", "max", "mean", "median", "std", "var", "p<percentile>"}. Defaults to "sum".

  • closed (string or None) – Determines what side of the interval is closed. Can be "left" or "right". The default depends on the frequency.

  • label (string or None) – Determines what side of the interval is closed. Can be "left" or "right". The default depends on the frequency.

  • timezone (string) – Timezone to perform the resampling in, defaults to "UTC".

Returns:

RasterBlock with temporally aggregated data.