s2_mask: Apply cloud masks

In pobsteta/theia2r: An R toolbox to find, download and preprocess Sentinel-2 data

Description

s2_mask Applies a cloud mask to a Sentinel-2 product. Since raster functions are used to perform computations, output files are physical rasters (no output VRT is allowed).

s2_perc_masked computes the percentage of cloud-masked surface. The function is similar to s2_mask, but it returns percentages instead of masked rasters.

Usage

s2_mask(infiles, maskfiles, mask_type = "cloud_medium_proba",
  smooth = 20, buffer = 10, max_mask = 80, outdir = "./masked",
  tmpdir = NA, rmtmp = TRUE, save_binary_mask = FALSE, format = NA,
  subdirs = NA, compress = "DEFLATE", parallel = FALSE,
  overwrite = FALSE, .log_message = NA, .log_output = NA)

s2_perc_masked(infiles, maskfiles, mask_type = "cloud_medium_proba",
  tmpdir = NA, rmtmp = TRUE, parallel = FALSE)

Arguments

infiles	A vector of input filenames. Input files are paths of products already converted from SAFE format to a format managed by GDAL (use s2_translate to do it); their names must be in the theia2r naming convention (safe_shortname).
maskfiles	A vector of filenames from which to take the information about cloud coverage (for now, only SCL products have been implemented). It is not necessary that maskfiles elements strictly match infiles ones. Input files are paths of products already converted from SAFE format to a format managed by GDAL (use s2_translate to do it); their names must be in the theia2r naming convention (safe_shortname).
mask_type	(optional) Character vector which determines the type of mask to be applied. Accepted values are: "nomask": do not mask any pixel; "nodata": mask pixels checked as "No data" or "Saturated or defective" in the SCL product (all pixels with values are maintained); "cloud_high_proba": mask pixels checked as "No data", "Saturated or defective" or "Cloud (high probability)" in the SCL product; "cloud_medium_proba": mask pixels checked as "No data", "Saturated or defective" or "Cloud (high or medium probability)" in the SCL product; "cloud_low_proba": mask pixels checked as "No data", "Saturated or defective" or "Cloud (any probability)" in the SCL product; "cloud_and_shadow": mask pixels checked as "No data", "Saturated or defective", "Cloud (any probability)" or "Cloud shadow" in the SCL product; "clear_sky": mask pixels checked as "No data", "Saturated or defective", "Cloud (any probability)", "Cloud shadow" or "Thin cirrus" in the SCL product (only pixels classified as clear-sky surface - so "Dark area", "Vegetation", "Bare soil", "Water" or "Snow" - are maintained); "land": mask pixels checked as "No data", "Saturated or defective", "Cloud (any probability)", "Cloud shadow", "Dark area", "Thin cirrus", "Water" or "Snow" in the SCL product (only pixels classified as land surface - so "Vegetation" or "Bare soil" - are maintained); a string in the following form: "scl_n_m_n", where n, m and n are one or more SCL class numbers (e.g. "scl_0_8_9_11"): mask pixels corresponding to the classes specified in the string. E.g. string "scl_0_8_9_11" can be used to mask classes 0 ("No data"), 8-9 ("Cloud (high or medium probability)") and 11 ("Snow"); "opaque_clouds" (still to be implemented).
smooth	(optional) Numerical (positive): should the mask be smoothed=the size (in the unit of inmask, typically metres) to be used as radius for the smoothing (the higher it is, the more smooth the output mask will result). Defaul is 20.
buffer	(optional) Numerical (positive or negative): the size of the buffer (in the unit of inmask, typically metres) to be applied to the masked area after smoothing it (positive to enlarge, negative to reduce). Defaul is 10.
max_mask	(optional) Numeric value (range 0 to 100), which represents the maximum percentage of allowed masked surface (by clouds or any other type of mask chosen with argument mask_type) for producing outputs. Images with a percentage of masked surface greater than max_mask are not processed (the list of expected output files which have not been generated is returned as an attribute, named "skipped"). Default value is 80. Notice that the percentage is computed on non-NA values (if input images had previously been clipped and masked using a polygon, the percentage is computed on the surface included in the masking polygons).
outdir	(optional) Full name of the output directory where the files should be created (default: "current directory"masked" subdir of current directory). outdir can bot be an existing or non-existing directory (in the second case, its parent directory must exists). If it is a relative path, it is expanded from the common parent directory of infiles.
tmpdir	(optional) Path where intermediate files (VRT) will be created. Default is a temporary directory.
rmtmp	(optional) Logical: should temporary files be removed? (Default: TRUE). This parameter takes effect only if the output files are not VRT (in this case temporary files cannot be deleted, because rasters of source bands are included within them).
save_binary_mask	(optional) Logical: should binary masks be exported? Binary mask are intermediate rasters used to apply the cloud mask: pixel values can be 1 (no cloud mask), 0 (cloud mask) or NA (original NA value, i.e. because input rasters had been clipped on the extent polygons). If FALSE (default) they are not exported; if TRUE, they are exported as MSK prod type (so saved within outdir, in a subdirectory called "MSK" if subdirs = TRUE). Notice that the presence of "MSK" products is not checked before running theia2r(), as done for the other products; this means that missing products which are not required to apply cloud masks will not be produced.
format	(optional) Format of the output file (in a format recognised by GDAL). Default is the same format of input images (or "GTiff" in case of VRT input images).
subdirs	(optional) Logical: if TRUE, different indices are placed in separated outfile subdirectories; if FALSE, they are placed in outfile directory; if NA (default), subdirectories are created only if more than a single spectral index is required.
compress	(optional) In the case a GTiff format is present, the compression indicated with this parameter is used.
parallel	(optional) Logical: if TRUE, masking is conducted using parallel processing, to speed-up the computation for large rasters. The number of cores is automatically determined; specifying it is also possible (e.g. parallel = 4). If FALSE (default), single core processing is used. Multiprocess masking computation is always performed in singlecore mode if format != "VRT" (because in this case there is no gain in using multicore processing).
overwrite	(optional) Logical value: should existing output files be overwritten? (default: FALSE)
.log_message	(optional) Internal parameter (it is used when the function is called by theia2r()).
.log_output	(optional) Internal parameter (it is used when the function is called by theia2r()).

Value

s2_mask returns a vector with the names of the created products. An attribute "toomasked" contains the paths of the outputs which were not created cause to the high percentage of cloud coverage.

s2_perc_masked returns a names vector with the percentages of masked surtfaces.

Note

License: GPL 3.0

Author(s)

Luigi Ranghetti, phD (2017) [e-mail]

pobsteta/theia2r documentation built on May 25, 2019, 2:21 p.m.