Welcome to gscpy’s documentation!

Installation

After you have received the gscpy package, you can install it with

$ python setup.py install

After this process it is recommended to use the script i_script with GRASS GIS. This is necessary because some modules from this package call other modules from this package that are only present if they are located in the script folder of GRASS GIS. It is possible that some of these modules require administration rights. The reason for this is that, for example, when downloading data to the hard disk, any write permissions must be present.

To launch a Python script from GUI, use File -> Launch Python script and select /path/to/gscpy/i_script.py.

Now you can launch the following modules:
  • i.script: A simple module that import Scripts from a package to GRASS GIS script directory.
  • g.database: Create a GRASS GIS Database.
  • g.c.mapset: Create a mapset in a GRASS GIS Database if it is not existent.
  • s1.download: Data download including basic adjustments for Sentinel-1 with sentinelsat.
  • i.dr.import: Import data into a mapset from a file by considering a certain pattern.
  • i.fr.import: Import pyroSAR dataset in a directory based on their metadata.
  • pr.geocode: Wrapper function for geocoding SAR images using pyroSAR.
  • t.c.register: Creation of Sentinel-1 space-time cube.

Examples

Here are some examples of how you can use the gscpy package with GRASS GIS. In the examples most of the modules are executed within the GRASS terminal. It is also possible to do all these steps with the graphical GUI. Most of the examples are from FOSS4G 2014 workshop

Data

These data are from here. These data are already in a GRASS GIS database. To show the import routines I exported the files within the mapset climate_2000_2012 with out.l.gdal. This mapset contains temperature and precipitation series for North Carolina from State Climate Office of North Carolina.

Contents

Data

The data is from here. The data is already in a GRASS GIS database. To show the import routines I exported the files within the mapset climate_2000_2012 with out.l.gdal. This mapset contains temperature and precipitation series for the whole North Carolina from State Climate Office of North Carolina.

Create a Mapset

Start GRASS with a location and create a mapset climate_2000_2012. Therefore, you can use g.c.mapset:

$ g.c.mapset mapset=climate_2000_2012
Create a Mapset

After we start GRASS GIS new the created mapset is present:

Create a Mapset

Sentinel 1 Downloader

Here is an example of how to use the Sentinel downloader, to map all available data (flag: -p):

$ ds1.download -p username=DALEK password=exterminate region=myGEoJsOnFile.geojson timestart=2015-01-02
  timeend=2015-01-12 outdir='home/usr/data' producttype=SLC

Another way is to use the GUI:

Type your Username and Password:

Create a Mapset

After the definition of a region with a geojson file you can specify the sensing period, polarization and the product type:

Create a Mapset Create a Mapset Create a Mapset

With flag -p you can print all available products. If the flag is missing all data will be downloaded:

Create a Mapset

Geocoding Example

After we downloaded the Sentinel 1 Files with ds1.download we want to geocode all the files automatically. Thus, we start with command pr.geocode the geocode GUI. Now we can specify our directory where the sentinel data are:

input

After these we specify our output directory:

output

if we click on Run now the geocode processing will run with ESA´s SNAP software:

run

If there is any scene that is already processed the pr.geocode module will skip these files:

exist

Find Processed Scenes

After we downloaded the Sentinel 1 Files with pr.geocode all the processed files are find in the output directory:

dir

In this directory their are S1A scenes as well as S1B scenes. Consider a case where we want to find and import all the sentinel 1B scenes. Thus, we can run the command:

$ i.fr.import -p input_dir=/media/ibaris/Shared/Documents/DATA/FuentedePiedra_VV/VV sensor=S1B

to print all the detected scenes:

p

We can import all the detected scenes if we delete the flag -p:

$ i.fr.import input_dir=/media/ibaris/Shared/Documents/DATA/FuentedePiedra_VV/VV sensor=S1B
import

To be sure we can run the command g.list type=raster:

import

Spatio-temporal data handling with Sentinel Data

After the process of geocoding and import of the scenes we create a huge amount of data as shown in section Find Processed Scenes. To better handle the long time series of maps, we create temporal datasets which serve as containers for the time series and we will further manipulate them instead of individual maps. Usually, we create empty datasets of type strds (space-time raster dataset) and after that we register the raster files into the strds. With t.c.register we can combine these two steps and with the flag -m we will visualize the temporal extents of the dataset (Note, that we use absolute and weekly time.):

$ t.c.register -m -t output=Intensity temporaltype=absolute title="Average Intensity"
  description="Weekly Intensity average in [dB]" start=2016-12-04
  increment="1 weeks"

Look at the temporal extents:

Create a Mapset Create a Mapset

Spatio-temporal Calculation with Sentinel Data

In the previous step we create a spatio-temporal dataset in unit dB. Now, we will convert the dB units to linear unit with t.raster.mapcalc. To do this we launch the mapcalc GUI with:

$ t.rast.mapcalc

We choose the space time raster dataset that we created in the previous step Intensity. To convert the unit [dB] in [linear] we use the formula:

pow(10, (dB/10))
Create a Mapset

Now, we will click Run:

Create a Mapset

If we now list all spatio-temporal dataset we see two entries: The one for Intensity and the another one Intensity_lin that we created in with t.raster.mapcalc:

Create a Mapset

We can also import the dataset into the display. Here is the dataset in unit [dB]:

Create a Mapset

And here is the dataset in unit [linear]:

Create a Mapset

Import / Export Raster Files

After downloading the data (See section Data), you can list all available raster files within the directory climate_2000_2012, by using the module i.dr.import:

$ i.dr.input -p input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012

Now you can see all files:

Create a Mapset

To show the pattern parameter of the module i.dr.import we want to consider only files that has the string tempmean in their filenames:

$ i.dr.input -p input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012 pattern=.*tempmean
Create a Mapset

With the command:

$ i.dr.input input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012

you can import all raster files located in /media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012. To be sure you can use the command:

$ g.list type=raster
Create a Mapset

You could export all files with the command out.l.gdal like:

$ out.l.gdal type=raster outdir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012

With the flag: -p you can see the files that will be exported:

Create a Mapset

Spatio-temporal data handling in General

To better handle the long time series of maps, we create temporal datasets which serve as containers for the time series and we will further manipulate them instead of individual maps. Usually, we create empty datasets of type strds (space-time raster dataset) and after that we register the raster files into the strds. With t.c.register we can combine these two steps and with the flag -m we will visualize the temporal extents of the dataset (Note, that we use absolute time.):

$ t.c.register -m -t output=tempmean temporaltype=absolute title="Average temperature"
  description="Monthly temperature average in NC [deg C]" pattern="*tempmean" start=2000-01-01
  increment="1 months"

For the preciptation dataset:

$ t.c.register -m -t output=precip_sum title="Preciptation"
  description="Monthly precipitation sums in NC [mm]" pattern="*precip" start=2000-01-01
  increment="1 months" semantictype=sum

Look at the temporal extents:

Create a Mapset Create a Mapset

With t.list type=strds we can see the new created datasets:

$ t.list type=strds
Create a Mapset

Download, Geocode and Import Chain

It is also possible to run a processing chain with p.chain:

$ p.chain

Now you can input all the same things described in the single modules ds1.download and pr.geocode

Create a Mapset

Technical documentation

Here are the technical documentation which contains all classes and functions.

Contents:

Import Scripts

Import Scripts from a package to GRASS GIS.

This class will copy any suitable python file like ‘i_dr_import.py’ into the GRASS script folder, without the ‘.py’ extension and changes the name to ‘i.dr.import’. This class will exclude such files like ‘__init__.py’ or ‘setup.py’. For more exclusions the parameter exclusion can be used.

class gscpy.i_script.Grassify(input_dir, export_path=None, pattern=None, exclusion=None)[source]

Import Scripts from a package to GRASS GIS.

This class will copy any suitable python file like ‘i_dr_import.py’ into the GRASS script folder without the ‘.py’ extension and changes the name to ‘i.dr.import’. This class will exclude such files like ‘__init__.py’ or ‘setup.py’. For more exclusions the parameter exclusion can be used.

Parameters:
  • input_dir (str) – Directory of python files
  • export_path (str, optional) – Script directory of GRASS GIS (automatically in Linux systems).
  • pattern (str, optional) – The pattern of file names.
  • exclusion (str) – Which files or pattern should be excluded?.
extension

A list which contains all supported GRASS GIS candidates.

Type:list
exclusion
Type:str
import_path

Dir parameter.

Type:str
export_path
Type:str
filter_p

Combines pattern and extension.

Type:str
files

All detected files.

Type:list
copy(replace=False)[source]

Copy files.

print_products()[source]

Print all detected files.

Examples

The general usage is

$ i.script [-r-p] input_dir=string [pattern=string] [exclusion=string] [export_path=string] [--verbose] [--quiet]

Import all suitable python files from a directory into the GRASS script folder

$ i.script input_dir=/home/user/package

Import all suitable python files from a directory into the GRASS script folder and exclude all files that include the string ‘test’

$ i.script input_dir=/home/user/package exclude=test.*

Note

This class copies all files and replaces all ‘_’ with ‘.’.

Notes

Flags:
  • r : Overwrite file if it is existent (be careful padawan!)
  • p : Print the detected files and exit.

Indices and tables

Indices and tables