Quickstart

Constructing a view

A dask-geomodeling view can be constructed by creating a Block instance:

from dask_geomodeling.raster import RasterFileSource
source = RasterFileSource('/path/to/geotiff')

The view can now be used to obtain data from the specified file. More complex views can be created by nesting block instances:

from dask_geomodeling.raster import Smooth
smoothed = Smooth(source, 5)
smoothed_plus_two = smoothed + 2

Obtaining data from a view

To obtain data from a view directly, use the get_data method:

request = {
    "mode": "vals",
    "bbox": (138000, 480000, 139000, 481000),
    "projection": "epsg:28992",
    "width": 256,
    "height": 256
}
data = add.get_data(**request)

Which field to include in the request and what data to expect depends on the type of the block used. In this example, we used a RasterBlock. The request and response specifications are listed in the documentation of the specific block type.

Showing data on the map

If you a are using Jupyter and our ipyleaflet plugin (see `installation`__), you can inspect your dask-geomodeling View on an interactive map widget.

from ipyleaflet import Map, basemaps, basemap_to_tiles
from dask_geomodeling.ipyleaflet_plugin import GeomodelingLayer

# create the geomodeling layer and the background layer
# the 'styles' parameter refers to a matplotlib colormap;
# the 'vmin' and 'vmax' parameters determine the range of the colormap
geomodeling_layer = GeomodelingLayer(
    add, styles="viridis", vmin=0, vmax=10, opacity=0.5
)
osm_layer = basemap_to_tiles(basemaps.OpenStreetMap.Mapnik)

# center the map on the middle of the View's extent
extent = add.extent
Map(
    center=((extent[1] + extent[3]) / 2, (extent[0] + extent[2]) / 2),
    zoom=14,
    layers=[osm_layer, geoomdeling_layer]
)

Please consult the `ipyleaflet<https://ipyleaflet.readthedocs.io>`_ docs for examples in how to add different basemaps, other layers, or add controls.

Delayed evaluation

Dask-geomodeling revolves around lazy data evaluation. Each Block first evaluates what needs to be done for certain request, storing that in a compute graph. This graph can then be evaluated to obtain the data. The data is evaluated with dask, and the specification of the compute graph also comes from dask. For more information about how a graph works, consult the dask documentation:

We use the previous example to demonstrate how this works:

import dask
request = {
    "mode": "vals",
    "bbox": (138000, 480000, 139000, 481000),
    "projection": "epsg:28992",
    "width": 256,
    "height": 256
}
graph, name = add.get_compute_graph(**request)
data = dask.get(graph, [name])

Here, we first generate a compute graph using dask-geomodeling, then evaluate the graph using dask. The power of this two-step procedure is twofold:

  1. Dask supports threaded, multiprocessing, and distributed schedulers. Consult the dask documentation to try these out.
  2. The name is a unique identifier of this computation: this can easily be used in caching methods.