Setup

To run the package, the following prerequisites need to be met:

Input imagery available
Vector file with sample points
Prepared tsbrowser configuration file

Input imagery

To run the package, time series of satellite imagery are required. Have a look at the demonstration data provided here to learn how to structure these data. The tool supports two ways of data preparation:

Default mode
Legacy mode

In default mode, you need to prepare the imagery together with corresponding quality assessment (QA) layers, typically cloud masks. The tool then evaluates the QA layers on-the-fly in order to plot clean time series. The second option, legacy mode, bypasses on-the-fly evaluation and therefore requires pre-filtered imagery. The demo data set contains examples for both operating modes in the raster directory.

Vector file with sample points

The sample vector file provides the actual sample points which should be interpreted. To give the tsbrowser utility all the necessary information, a few fields in the attribute table need to be specified per sample:

ID: unique ID of the sample (int or str)
QA raster file directory for the sample (str, path either absolute or relative to the vector file directory)
Imagery raster file directory for the sample (str, path either absolute or relative to the vector file directory)

The exact names of the respective attributes need to be given in the tsbrowser configuration file. The demonstration data set includes a suitable shapefile in the vector directory.

`tsbrowser` configuration file

The tsbrowser configuration file includes all the available parameters of the tool. Please refer to the comments given for each parameter for further details. The configuration of tsbrowser depends strongly on locally available input data and its specific properties. Therefore, there is no default configuration that will work out-of-the-box. The configuration file needs to be set up for each use case. If interpretation is carried out by multiple users, we recommend to split the sample points into several partitions and create configurations per user.

Configuration

tsbrowser configuration file

import matplotlib.dates as mdates

# set interpreter ID
interpreter = 'jdoe'

# set point sample vector file path
# the path can be specified either absolute or relative to the configuration file directory
path = "vector/demo_points.shp"

# define required attribute names
legacy_mode = False  # if True, the program expects pre-processed image chips and all
# parameters regarding on-the-fly quality evaluation are ignored
attr_id = "id"
attr_q_loc = "default"  # location of quality raster files for the feature
attr_i_loc = "default"  # location of image raster files for the feature

# set quality raster file search options
q_pattern = "SCL*.tif"
q_recursive = True

# set image raster file search options
i_pattern = "L2A*.tif"
i_recursive = True

# set options for retrieving the image acquisition timestamp
t_mode = "filename"  # possible values: metadata, filename
t_slice = slice(4, 19)  # used if t_mode == filename
t_format = "%Y%m%dT%H%M%S"  # used if t_mode == filename

# set quality evaluation parameters
q_mode = "classes"  # possible values: classes, threshold_lt, threshold_gt
q_band = 1  # set which band to read from each quality raster file
masking_classes = (0, 8, 9, 11)  # used if mode == 'classes'
valid_classes = None 
eval_bitwise = False # used if mode == "classes"
threshold = 3  # used if mode in ('threshold_gt', 'threshold_lt')
overall_valid_ratio = 0.1
specific_radius = 9
specific_valid_ratio = 0.8

# define the flag label set with a right mouse button click
default_flag_label = "0"
add_flag_labels = "a b c d e f g h".split()

# set an output directory to store flag files (json format)
# if None, write to the directory containing the sample vector file 
flag_dir = "flags-demo"

# assign names to input bands
layermap = {"B02": 1, "B03": 2, "B04": 3, "B08": 4, "B11": 5}

# Indices which should be calculated on the fly
# only simple arithmetic operations are supported (+,-,*,/)
indices = {
    # "NDMI": "(B08 - B11) / (B08 + B11)",  # Normalized Difference Moisture Index
    "NDVI": "(B08 - B04) / (B08 + B04)",  # Normalized Difference Vegetation Index
    # "NBR": "(B08 - B11) / (B08 + B11)",  # Normalized Burn Ratio
    # "TCW": " 0.0315*B02 + 0.2021*B03 + 0.3102*B04 + 0.1594*B08 - 0.6806*B11 - 0.6109*B12" # TC wetness
}

# configure which bands to display in the 3 time series sub-plots
timeseries = {"ts_B1": "B04", "ts_B2": "B11", "ts_B3": "NDVI"}

# configure which band combination to display in the 2 image sub-plots
images = {"img_L": ("B04", "B03", "B02"), "img_R": ("B11", "B08", "B04")}

# initial image chip size [m]
chip_width = 1000
chip_height = 1000

# image pixel value scale factor handling
apply_metadata_zscale = True
zscale = 1.0

# define band-specific min/max contrast stretch (absolute reflectance, e.g. 0.1 means 10% reflectance)
contrast = {
    "B02": (0.0, 1500.0),
    "B03": (0.0, 1800.0),
    "B04": (0.0, 2000.0),
    "B08": (0.0, 6000.0),
    "B11": (0.0, 5000.0),
}

# contrast = {'B02': 'mean_stddev',
# 'B03': 'mean_stddev',
# 'B04': 'mean_stddev',
# 'B08': 'mean_stddev',
# 'B11': 'mean_stddev'}

# contrast = {'B02': 'median_mad',
# 'B03': 'median_mad',
# 'B04': 'median_mad',
# 'B08': 'median_mad',
# 'B11': 'median_mad'}

# contrast = {'B02': 'pct_clip',
# 'B03': 'pct_clip',
# 'B04': 'pct_clip',
# 'B05': 'pct_clip',
# 'B08': 'pct_clip',
# 'B11': 'pct_clip'
# }

pct_min = 0.3  # for stretch mode pct_clip
pct_max = 98.0  # for stretch mode pct_clip

std_factor = 2.5  # for stretch mode mean_stddev and median_mad

# format x-axis of time series plots
monthLoc = mdates.MonthLocator(bymonth=range(1, 13, 3)) # quarterly ticks
# monthLoc = mdates.MonthLocator(bymonth=range(1, 13, 6)) # half-yearly ticks
monthFmt = mdates.DateFormatter("%Y %b %d")

# VHR module options
vhr_zoom = 17
remove_duplicates = True