Skip to contents

Set mask band of a VRT collection

Source: R/vrt-set-mask.R, R/zvrt-pixel-funs-mask.R
vrt_set_maskfun.Rd

This function constructs a cloud mask using the OmniCloudMask python library. It is designed to be used with the vrt_set_maskfun() function.

Usage

vrt_set_maskfun(
  x,
  mask_band,
  mask_values,
  build_mask_pixfun,
  set_mask_pixfun,
  drop_mask_band,
  cache_dir
)

# S3 method for class 'vrt_block'
vrt_set_maskfun(
  x,
  mask_band,
  mask_values,
  build_mask_pixfun = vrtility::build_intmask(),
  set_mask_pixfun = vrtility::set_mask_numpy(),
  drop_mask_band = TRUE,
  cache_dir = getOption("vrt.cache")
)

# S3 method for class 'vrt_collection'
vrt_set_maskfun(
  x,
  mask_band,
  mask_values,
  build_mask_pixfun = vrtility::build_intmask(),
  set_mask_pixfun = vrtility::set_mask_numpy(),
  drop_mask_band = TRUE,
  cache_dir = getOption("vrt.cache")
)

set_mask_numpy()

build_intmask()

build_bitmask()

build_omnicloudmask(
  red,
  green,
  nir,
  patch_size = 600,
  patch_overlap = 300,
  batch_size = 1,
  no_data_value = 0,
  inference_device = NULL
)

Arguments

x

A VRT collection

mask_band

The name of the mask band

mask_values

A numeric vector of integer or bit values to be masked.

build_mask_pixfun

A character string of the Python code to build the mask. Provided functions include build_intmask() and build_bitmask(). See details.

set_mask_pixfun

A character string of the Python code to set the mask. Provided functions include set_mask_numpy(). See details.

drop_mask_band

Logical. If TRUE, the mask band will be removed from the VRT block.

cache_dir

A character string of the directory to use for temporary files. In general this should be left alone. main purpose is to manage cache location when running asyncronously with mirai.

red

The red band index (numeric or integer).

green

The green band index (numeric or integer).

nir

The near-infrared band index (numeric or integer).

patch_size

The size of the patches to use for prediction (numeric or integer, default: 600).

patch_overlap

The overlap between patches (numeric or integer, default: 300).

batch_size

The batch size to use for prediction (numeric or integer, default: 1).

no_data_value

The value to use for no data pixels (numeric, default: 0).

inference_device

The device to use for inference. If NULL, the function will automatically select the best available device (character, default: NULL). Options include "cpu", "cuda", "mps", etc. The order of selection is based on availability: "cuda" > "mps" > "cpu".

Value

A VRT block with the mask band set.

A VRT collection with the mask band set.

A Python function that can be used as a pixel function in a VRT raster. The function will apply the OmniCloudMask model to the specified bands and create a cloud mask.

Details

The build_mask_pixfun function is used to build the mask band. Where the mask band is a true bitmask and bit-wise operations are required, the build_bitmask() function should be used. For integer-based masking, where the mask band is provided as a single band with integer values, the build_intmask() function should be used.

The set_mask_pixfun function is used to apply the mask to the other bands. In general set_mask_numpy() should be used, although a custom function can be provided.

set_mask_numpy simply applies a given mask where values of 0 are assumed to have nodata and values > 0 (typically 255) contain valid data. It is the only provided function for the set_mask_pixfun argument in vrt_set_maskfun(). Alternatively a custom function could be provided if, for example a user wishes to buffer the mask.

build_intmask provides an integer mask function that can be used to mask out pixels based on a band containing true integer/numeric values. This would be appropriate for the Sentinel 2A SCL band, for example.

build_bitmask provides is a simple bit-wise mask function that can be used to mask out pixels based on a true bit mask. This function should be used where bitwise operations are required. e.g. for HLS data, the "Fmask" band requires bitwise operations to extract the mask values.

Examples

s2files <- fs::dir_ls(system.file("s2-data", package = "vrtility"))

ex_collect <- vrt_collect(s2files)
ex_collect |>
  vrt_set_maskfun(
    mask_band = "SCL",
    mask_values = c(0, 1, 2, 3, 8, 9, 10, 11),
    drop_mask_band = FALSE)
#> → <VRT Collection>
#> Mask Function: [hidden]
#>   run print(x, maskfun = TRUE) to view
#> 
#>  VRT SRS: 
#> PROJCS["unknown",GEOGCS["unknown",DATUM["Unknown based on WGS 84 ellipsoid",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]]],PROJECTION["Lambert_Azimuthal_Equal_Area"],PARAMETER["latitude_of_center",50.72],PARAMETER["longitude_of_center",-3.51],PARAMETER["false_easting",0],PARAMETER["false_northing",0],UNIT["metre",1],AXIS["Easting",EAST],AXIS["Northing",NORTH]]
#> 
#>  PROJCS["WGS 84 / UTM zone 30N",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-3],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32630"]]
#> 
#>  PROJCS["OSGB36 / British National Grid",GEOGCS["OSGB36",DATUM["Ordnance_Survey_of_Great_Britain_1936",SPHEROID["Airy 1830",6377563.396,299.3249646,AUTHORITY["EPSG","7001"]],AUTHORITY["EPSG","6277"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4277"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",49],PARAMETER["central_meridian",-2],PARAMETER["scale_factor",0.9996012717],PARAMETER["false_easting",400000],PARAMETER["false_northing",-100000],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","27700"]]
#> 
#> 
#> Bounding Box: NA
#> Pixel res: 19.9923198093722, 19.9923198093722
#> Start Date: NA
#> End Date: NA
#> Number of Items: 5
#> Assets: B02, B03, B04, SCL