Old Model as of 4.6

We actually have three different concepts of image masks in use: valid mask, ROI, and bitmask overlay. All masks can be displayed as overlays and have the layer style properties color and transparency. The image datatype is alway byte, sample values are either 0 or 255.

1. A valid mask determines raster pixel positions containing valid sample values. The validMask is a property of a RasterDataNode. It is used when computing raster statistics and for creating image layers (invalid areas are fully transparent). The valid mask is computed by (optional) properties of RasterDataNode:
   • noDataValue, for example -999 or NaN
   • validPixelExpression, for example NOT l1b_flags.INVALID
2. A ROI is defined on a raster dataset and is used for statistical computations where it is AND combined with the valid mask. A ROI mask is generated from a ROI definition which again is also a property of a RasterDataNode. ROI definitions are based on the following options
   • include pixels within a given geometry (shape)
   • include pixels under pins
   • include pixels in given value range
   • include pixels where a band-math expression evaluates to a non-zero result
   • AND/OR combine conditions above and optionally invert the result
3. Bitmask overlays are used for image display only. Their main purpose it to overlay images of geo-physical variables with coloured masks based on the quality flags defined in a data product. Bitmask definitions are stored in the product. A RasterDataNode can have zero, one or more references to the definitions in the product. A bitmask definition comprises
   • name and description
   • colour and transparency
   • (Boolean) band-math expression

New Model as of 4.7

Valid masks, ROIs and bitmask overlays shall now be realised using the common concept of a raster data mask while their application in BEAM shall be retained. A ROI would then only be a certain role of a raster data mask in a specific context, such as statistics computation.

General Requirements

1. A user may define any number of masks and attach it to product.
2. A mask is an image whose sample datatype is byte.
3. A mask has a
   1. unique name used to identify it within a product
   2. a colour
   3. a transparency
   4. a human readable label to be used in user interfaces
   5. a human readable category used to group many masks in user interfaces
   6. a human readable description
4. Each mask is given a associated, predefined layer, so that users can quickly visualize it.
5. A mask shall originate from the following sources
   1. single flag
   2. equality with a specific value (0, -999, ...) on any band
   3. equality with an exceptional value (NaN, -Inf, +Inf) on any band
   4. single threshold on any band
   5. value range on any band
   6. general, boolean band arithmetic expression
   7. pixel positions rendered from placemarks and shapes
   8. user selected pixel positions (e.g. via magic stick)
   9. a combination of ROIs, namely:
      1. union(m1, m2, m3, ...)
      2. subtract(m1, m2, m3, ...),
      3. intersect(m1, m2, m3, ...),
      4. negate(m)

Specific Requirements from NEST

These are the requirements for NEST regarding ROIs:

1. There should be multiple user labeled and coloured ROIs that can be applied independently across all bands
2. The user should be able to easily draw an ROI consisting of multiple polygons and then be able to start a new ROI.
3. The DAT shall enable graphical definition and saving/loading of region(s) of interest (ROIs) within a displayed dataset in terms of: rectangles and polygons and direct input of its numerical parameters to any tool that requires it.
4. When saving ROIs, vertices will be saved in terms of lat/lon and loaded into another product at the relative geographic position.
5. An ROI shall be convertible into a binary bit mask of the same dimensions as the dataset to which it relates and be able to use this bitmask in the graph processing.
6. Statistics will be applied for the user specified ROI for all bands.
7. ROIs could also be saved to shape files

Implementation in BEAM

A mask may be modelled as a special raster data node (or special band, so to say).
This way we can easily perform band math with them. Their raster data is rendered only when requested.
The source images for the mask nodes could easily be implemented as JAI {{OpImage}}s.

Geometry-based masks would refer to a new VectorDataNode. The OpImage will render the geometry found in a GeoTools FeatureCollection to the raster data in order to retrieve the bitmask raster tiles. This way we can use any geometry e.g. as ROI.