GRASS GIS Temporal Framework¶
Introduction¶
The GRASS GIS Temporal Framework implements the temporal GIS functionality of GRASS GIS and provides an API to implement spatio-temporal processing modules. The framework introduces space time datasets that represent time series of raster, 3D raster or vector maps. This framework provides the following functionalities:
- Assign time stamp to maps and register maps in the temporal database
- Modification of time stamps
- Creation, renaming and deletion of space time datasets
- Registration and un-registration of maps in space time datasets
- Query of maps that are registered in space time datasets using SQL where statements
- Analysis of the spatio-temporal topology of space time datasets
- Sampling of space time datasets
- Computation of temporal and spatial relationships between registered maps
- Higher level functions that are shared between modules
Most of the functions described above are member functions of dedicated map layer and space time dataset classes.
Temporal API¶
The temporal framework API consists of several dedicated modules. Each module contains one or several classes as well as function definition. The API can be roughly divided in a low level and high level part. However, several functions from the low level module are used in module implementation as well.
Low level API¶
The low level API implements the core functionality of the temporal framework. Core functionality is for example the database interface, the temporal database creation and initialization, the SQL object serialization, all classes that represent table entries, datetime mathematics and many more.
core
¶
The core functionality of the temporal framework:
- Initialization function
init()
- Definition of global variables
- Several global functions to access TGIS specific variables
- Interfaces to the TGIS C-library and PyGRASS messenger objects
- Database interface connection class
SQLDatabaseInterfaceConnection
to sqlite3 and postgresql database backends- Functions to create the temporal database
base
¶
Implements of basic dataset information and SQL conversion of such information:
- Definition of the SQL serialize class
DictSQLSerializer
that converts the content of temporal classes into SQL SELECT, INSERT or UPDATE statements- Definition of
SQLDatabaseInterface
that is the base class for all temporal datatype subclasses- Contains classes for all datasets [1] that contain basic information (id, name, mapset, creator, …)
spatial_extent
¶
Implements of 2d and 3d spatial extents of all datasets:
- Implements class
SpatialExtent
that is the base class for all dataset specific spatial extent classes It provides spatial topological logic and operations for 2D and 3D extents- Implements spatial extent classes for all datasets [1]
temporal_extent
¶
Implements of the temporal extent of all datasets for relative and absolute time:
- Implements class
TemporalExtent
that is the base class for all dataset specific temporal extent classes It provides temporal topological logic and operations- Implements temporal extent classes for relative time and absolute time for all datasets [1]
metadata
¶
Implements the metadata base classes and datatype specific derivatives fpr all datasets [1].
spatial_topology_dataset_connector
¶
Implements the interface to link datasets by spatial topological relations
temporal_topology_dataset_connector
¶
Implements the interface to link datasets by temporal topological relations
c_libraries_interface
¶
The RPC C-library interface for exit safe and fast access to raster, vector and 3D raster information.
temporal_granularity
¶
The computation of the temporal granularity for a list ofAbstractDataset
objects for absolute and relative is implemented here.
datetime_math
¶
This module contains function to parse, convert and process datetime objects in the temporal framework.
Spatio-temporal algebra classes for space time raster and vector datasets are defined in:
High level API¶
The high level API utilizes the low level API. Its classes and functions are usually used to implement temporal processing algorithms and temporal GRASS modules.
abstract_dataset
¶
- Implements the base class for all datasets [1]
AbstractDataset
.- Implements the the select, insert and update functionality as well as convenient functions to access the base, extent and metadata information
abstract_map_dataset
¶
- Implements the base class
AbstractMapDataset
for all map layer specific classes- Provides the interface to all map layer specific information in the temporal database
abstract_space_time_dataset
¶
- Implements the base class
AbstractSpaceTimeDataset
for all Space Time Datasets classes- Contains the creation and deletion functionality, the map registration and un-registration, access methods to map layer objects and so on
- Provides the interface to all Space Time Dataset specific information in the temporal database
space_time_datasets
¶
This module contains all classes that represent specific datasets [1]. A module developer uses these map layer and Space Time Dataset object representations to perform spatio-temporal tasks.
spatio_temporal_relationships
¶
The logic to compute spatio-temporal topology for a single list or two lists ofAbstractDataset
objects is implemented in this module. The classSpatioTemporalTopologyBuilder
provides a convenient interface for topology computation.
gui_support
¶
Helper functions to support the listing of space time datasets in the automatically generated GUI.
Examples¶
Howto start example¶
This simple example shows how to open a space time raster dataset to access its registered maps.
# Lets import the temporal framework and
# the script framework
import grass.temporal as tgis
import grass.script as gs
# Make sure the temporal database exists
# and set the temporal GIS environment
tgis.init()
# We create the temporal database interface for fast processing
dbif = tgis.SQLDatabaseInterfaceConnection()
dbif.connect()
# The id of a space time raster dataset is build from its name and its mapset
id = "test@PERMANENT"
# We create a space time raster dataset object
strds = tgis.SpaceTimeRasterDataset(id)
# Check if the space time raster dataset is in the temporal database
if strds.is_in_db(dbif=dbif) == False:
dbif.close()
gs.fatal(_("Space time %s dataset <%s> not found") % (
strds.get_new_map_instance(None).get_type(), id))
# Fill the object with the content from the temporal database
strds.select(dbif=dbif)
# Print information about the space time raster dataset to stdout
strds.print_info()
# Get all maps that are registered in the strds and print
# information about the maps to stdout
maps = strds.get_registered_maps_as_objects(dbif=dbif)
# We iterate over the temporal sorted map list
for map in maps:
# We fill the map object with the content
# from the temporal database. We use the existing
# database connection, otherwise a new connection
# will be established for each map object
# which slows the processing down
map.select(dbif=dbif)
map.print_info()
# Close the database connection
dbif.close()
Creation of a space time dataset¶
This example shows howto create a space time dataset. The code is generic and works for different space time datasets (raster, 3D raster and vector):
# Lets import the temporal framework and
# the script framework
import grass.temporal as tgis
import grass.script as gs
# The id of the new space time dataset
id="test@PERMANENT"
# The title of the new space time dataset
title="This is a test dataset"
# The description of the space time dataset
description="The description"
# The type of the space time dataset (strds, str3ds or stvds)
type="strds"
# The temporal type of the space time dataset (absolute or relative)
temporal_type="absolute"
# Make sure the temporal database exists
# and set the temporal GIS environment
tgis.init()
# We use the dataset factory to create an new space time dataset instance of a specific type
stds = tgis.dataset_factory(type, id)
# We need a dtabase connection to insert the content of the space time dataset
dbif = tgis.SQLDatabaseInterfaceConnection()
dbif.connect()
# First we check if the dataset is already in the database
if stds.is_in_db(dbif=dbif) and overwrite == False:
dbif.close()
gs.fatal(_("Space time %s dataset <%s> is already in the database. "
"Use the overwrite flag.") %
(stds.get_new_map_instance(None).get_type(), name))
# We delete the exiting dataset and create a new one in case we are allowed to overwrite it
if stds.is_in_db(dbif=dbif) and overwrite == True:
gs.warning(_("Overwrite space time %s dataset <%s> "
"and unregister all maps.") %
(stds.get_new_map_instance(None).get_type(), name))
stds.delete(dbif=dbif)
stds = stds.get_new_instance(id)
# We set the initial values. This function also created the command history.
stds.set_initial_values(temporal_type=temporaltype, semantic_type="mean",
title=title, description=description)
# Now we can insert the new space time dataset in the database
stds.insert(dbif=dbif)
# Close the database connection
dbif.close()
Temporal shifting¶
import grass.script as gs
import grass.temporal as tgis
id="test@PERMANENT"
type="strds"
# Make sure the temporal database exists
tgis.init()
dbif = tgis.SQLDatabaseInterfaceConnection()
dbif.connect()
stds = tgis.dataset_factory(type, id)
if stds.is_in_db(dbif) == False:
dbif.close()
gs.fatal(_("Space time dataset <%s> not found in temporal database") % (id))
stds.select(dbif=dbif)
stds.snap(dbif=dbif)
stds.update_command_string(dbif=dbif)
dbif.close()
References¶
- Gebbert, S., Pebesma, E., 2014. TGRASS: A temporal GIS for field based environmental modeling. Environmental Modelling & Software. 2(1):201-219. doi:10.1016/j.envsoft.2013.11.001
- TGRASS related articles in the GRASS GIS Wiki
- Supplementary material of the publication The GRASS GIS Temporal Framework
to be published in
International Journal of Geographical Information Science in 2017, Download
The GRASS GIS Temporal Framework: Object oriented code design with examples
Authors: | Soeren Gebbert |
---|---|
TODO: | add more documentation |