Bitmask/QA bands

[simonff]

Pixels of integer raster bands sometimes contain bit-packed values - eg, MODIS MOD09GA: https://developers.google.com/earth-engine/datasets/catalog/MODIS_006_MOD09GA

Such bands are sometimes called QA bands, as they often contain per-pixel QA information.

Bitmask usually take up up to 4 bits, and some bit values can be unused.

Examples from the MOD09GA description:

Example A, single bit 4: Bit 4: Digital elevation model quality flag (0 = Valid, 1 = Missing/inferior)

Example B, two bits 0 and 1: 00 (0): corrected product produced at ideal quality all bands 01 (1): corrected product produced at less than ideal quality some or all bands 10 (2): corrected product not produced due to cloud effects all bands 11 (3): corrected product not produced due to other reasons some or all bands may be fill value

In Earth Engine, we represent them with the following protocol buffer messages:

message BitmaskValue { int32 value = 1; string description = 2; }

message BitmaskPart { string description = 1; // Meaning of the bit pattern. int32 first_bit = 2; // 0-based index of the lowest bit int32 bit_count = 3; // Number of bits in the pattern repeated BitmaskValue values = 4; // Explanation for possible bit values. }

message Bitmask { repeated BitmaskPart bitmask_parts = 1; }

The MOD09GA examples above are implemented like this (syntax is YAML):

Example A

 bitmask:
      bitmask_parts:
...
   - description: Digital elevation model quality flag
        first_bit: 4
        bit_count: 1
        values:
        - value: 0
          description: Valid
        - value: 1
          description: Missing/inferior

Example B:

 bitmask:
      bitmask_parts:
      - description: MODLAND QA bits
        first_bit: 0
        bit_count: 2
        values:
        - value: 0
          description: Corrected product produced at ideal quality
            - all bands
        - value: 1
          description: Corrected product produced at less than ideal
            quality - some or all bands
        - value: 2
          description: Corrected product not produced due to cloud
            effects - all bands
        - value: 3
          description: Corrected product not produced for other reasons
            - some or all bands, may be fill value (11) 

[cholmes]

I think this is just an asset in our representation, which can be included. Could be good to write up more about it, but don't think it is a core stac spec thing.