[GRASS-SVN] r62111 - grass/trunk/lib/python/docs/src
svn_grass at osgeo.org
svn_grass at osgeo.org
Sat Sep 27 09:54:16 PDT 2014
Author: huhabla
Date: 2014-09-27 09:54:16 -0700 (Sat, 27 Sep 2014)
New Revision: 62111
Added:
grass/trunk/lib/python/docs/src/temporal.rst
Log:
Added sphinx documentation for the temporal framework
Added: grass/trunk/lib/python/docs/src/temporal.rst
===================================================================
--- grass/trunk/lib/python/docs/src/temporal.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/temporal.rst 2014-09-27 16:54:16 UTC (rev 62111)
@@ -0,0 +1,371 @@
+The 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 on which the high level API is based on.
+
+**python::temporal::core**
+
+ The core functionality of the temporal framework:
+
+ - Initialization function :func:`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 :class:`~temporal.core.SQLDatabaseInterfaceConnection` to sqlite3 and postgresql
+ database backends
+ - Functions to create the temporal database
+
+**python::temporal::base**
+
+ Implements of basic dataset informations and SQL conversion of such information:
+
+ - Definition of the SQL serialize class :class:`~temporal.base.DictSQLSerializer` that converts the content of temporal
+ classes into SQL SELECT, INSERT or UPDATE statements
+ - Definition of :class:`~temporal.base.SQLDatabaseInterface` that is the base class for all temporal datatype subclasses
+ - Contains classes for all datasets [#allds]_ that contain
+ basic informations (id, name, mapset, creator, ...)
+
+**python::temporal::spatial_extent**
+
+ Implements of 2d and 3d spatial extents of all datasets:
+
+ - Implements class :class:`~temporal.spatial_extent.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 [#allds]_
+
+**python::temporal::temporal_extent**
+
+ Implements of the temporal extent of all datasets for relative and absolute time:
+
+ - Implements class :class:`~temporal.temporal_extent.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 [#allds]_
+
+**python::temporal::metadata**
+
+ Implements the metadata base classes and datatype specific derivatives fpr all datasets [#allds]_.
+
+**python::temporal::spatial_topology_dataset_connector**
+
+ Implements the interface to link datasets by spatial topological relations
+
+**python::temporal::temporal_topology_dataset_connector**
+
+ Implements the interface to link datasets by temporal topological relations
+
+**python::temporal::c_libraries_interface**
+
+ The RPC C-library interface for exit safe and fast access to raster, vector and 3D raster informations.
+
+**python::temporal::temporal_granularity**
+
+ The computation of the temporal granularity for a list
+ of :class:`~temporal.abstract_dataset.AbstractDataset` objects for absolute and relative is implemented here.
+
+**python::temporal::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:
+
+- **python::temporal::temporal_algebra**
+- **python::temporal::temporal_vector_algebra**
+- **python::temporal::temporal_vector_operator**
+
+High level API
+**************
+
+The high level API utilizes the low level API
+
+**python::temporal::abstract_dataset**
+
+ - Implements the base class for all datasets [#allds]_ :class:`~temporal.abstract_dataset.AbstractDataset`.
+ - Implements the the select, insert and update functionality as well as
+ convenient functions to access the base, extent and metadata informations
+
+**python::temporal::abstract_map_dataset**
+
+ - Implements the base class :class:`~temporal.abstract_map_dataset.AbstractMapDataset` for all map layer specific classes
+ - Provides the interface to all map layer specific informations in the temporal database
+
+**python::temporal::abstract_space_time_dataset**
+
+ - Implements the base class :class:`~temporal.abstract_space_time_dataset.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 informations in the temporal database
+
+**python::temporal::space_time_datasets**
+
+ This module contains all classes that represent specific datasets [#allds]_. A module developer uses these
+ map layer and Space Time Dataset object representations to perform spatio-temporal tasks.
+
+
+**python::temporal::spatio_temporal_relationships**
+
+ The logic to compute spatio-temporal topology for a single list or two lists of :class:`~temporal.abstract_dataset.AbstractDataset` objects
+ is implemented in this module.
+ The class :class:`~temporal.spatio_temporal_relationships.SpatioTemporalTopologyBuilder` provides a convenient
+ interface for topology computation.
+
+**python::temporal::gui_support**
+
+ Helper functions to support the listing of space time datasets in the automatically generated GUI.
+
+Temporal Framework Testsuite
+****************************
+
+All temporal framework specific unittests and doctests are located here:
+
+- **python::temporal::testsuite**
+
+
+Shared Module functionality
+***************************
+
+Functionality that is shared between different temporal GRASS modules, such as
+map listing, space time dataset creation, map registration and unregistration,
+aggregation, extraction, map calculation, statistics as well as import and export of
+space time datasets are defined here:
+
+**python::temporal::aggregation**
+
+ Aggregation of Space Time Raster Datasets based on topological relations.
+ Used in *t.rast.aggregate* and *t.rast.aggregate.ds*
+
+**python::temporal::extract**
+
+ Extraction of subsets from Space Time Datasets including map algebra and vector selection statements.
+ Used in *t.rast.extract*, *t.rast3d.extract* and *t.vect.extract*.
+
+**python::temporal::factory**
+
+ Factory functions to create datasets of all types [#allds]_.
+
+**python::temporal::open_stds**
+
+ Convenient functions to open existing Space Time Datasets or to create new ones. Used in almost all temporal modules.
+
+**python::temporal::list_stds**
+
+ Convenient functions to list datasets of all types [#allds]_ registered in the temporal database.
+
+**python::temporal::mapcalc**
+
+ Simple temporal algebra for Scpae Time Raster and 3d Raster datasets. Used in *t.rast.mapcalc* and *t.rast3d.mapcalc*
+
+**python::temporal::register**
+
+ Convenient functions to register a single or multiple map layer in the temporal database and
+ SpaceTime Datasets. Used in several modules, most important *t.register*.
+
+**python::temporal::sampling**
+
+ Sampling functions used in several modules.
+
+**python::temporal::stds_export**
+
+ Functions to export of Space Time Datasets, used in *t.rast.export*, *t.rast3d.export* and *t.vect.export*.
+
+**python::temporal::stds_import**
+
+ Functions to import Space Time Datasets, used in *t.rast.import*, *t.rast3d.import* and *t.vect.import*.
+
+**python::temporal::univar_statistics**
+
+ Simple statistical analysis functions for Space Time Datasets, used in *t.rast.univar*, *t.rast3d.univar*
+ and *t.vect.univar*.
+
+
+.. [#allds] : Raster Map Layer, 3d Raster Map Layer, Vector Map Layer, Space time Raster Datasets (STRDS),
+ Space Time 3d Raster Datasets (STR3DS) and Space Time Vector Datasets (STVDS)
+
+Examples
+--------
+
+Howto start example
+*******************
+
+This simple example shows how to open a space time raster dataset
+to access its registered maps.
+
+.. code-block:: python
+
+ # Lets import the temporal framework and
+ # the script framework
+ import grass.temporal as tgis
+ import grass.script as grass
+
+ # 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 at 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()
+ grass.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 informations about the space time raster dataset to stdout
+ strds.print_info()
+
+ # Get all maps that are registered in the strds and print
+ # informations 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):
+
+.. code-block:: python
+
+ # Lets import the temporal framework and
+ # the script framework
+ import grass.temporal as tgis
+ import grass.script as grass
+
+ # The id of the new space time dataset
+ id="test at 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()
+ grass.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:
+ grass.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
+*****************
+
+.. code-block:: python
+
+ import grass.script as grass
+ import grass.temporal as tgis
+
+ id="test at 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()
+ grass.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()
+
+
+:Authors: Soeren Gebbert
+
+:TODO: add more documentation
+
More information about the grass-commit
mailing list