RFC 14: Null Masks

Author: Frank Warmerdam
Contact: warmerdam@…
Status: Development

Summary

Some file formats support a concept of a bitmask to identify pixels that are not valid data. This can be particularly valuable with byte image formats where a nodata pixel value can not be used because all pixel values have a valid meaning. This RFC tries to formalize a way of recognising and accessing such nodata bitmasks through the GDAL API.

The basic approach is to treat such masks as raster bands, but not regular raster bands on the datasource. Instead they are freestanding raster bands in a manner similar to the overview raster band objects. The nodata masks are represented as GDT_Byte bands with a value of zero indicating nodata and 255 indicating valid data. Intermediate values do not normally occur but in they future they might be interpreted as a confidence value or alpha transparency values.

API

GDALRasterBand is extended with the following methods:

    GDALRasterBand *GetNullMask();
    GDALNullMaskType GetNullMaskType();

Note that the GetNullMask() should always return a GDALRasterBand mask, even if it is only an all 255 mask with thetype

The GDALNullMaskType enumeration has the following values:

• GDALNMTAllValid: There are no invalid pixels, all mask values will be 255.
• GDALNMTPerBand: The mask band is meaningful and is unique to this band (other bands may have masks with different areas of validity)
• GDALNMTPerDataset: The mask band is meaningful and is shared between all bands on this dataset.

Note that the GetNullMask() should always return a GDALRasterBand mask, even if it is only an all 255 mask with the type set to GDALNMTAllValid.

Default Implementation

The GDALRasterBand class will include a default implementation of GetNullMask() that returns one of two default implementations. The first default implement is a GDALNMTAllValid band that returns all 255. The second default implementation would return a mask computed by reading the imagery data and comparing it to the nodata value. The nodata based one would be used when the base band has a nodata value.

Drivers Updated

These drivers will be updated:

• JPEG Driver: support the "zlib compressed mask appended to the file" approach used by a few data providers.
• GRASS Driver: updated to support handling null values as masks.

Possibly updated:

• HDF4 Driver: This driver might possibly be updated to return real mask if we can figure out a way.
• SDE Driver: This driver might be updated if Howard has sufficient time and enthusiasm.

Implementation Plan

This change will be implemented by Frank Warmerdam in trunk in time for the 1.5.0 release.

SWIG Implications

The GetNullMask() and GetNullMaskType() methods (and corrsponding defines) will need to be added. The bitmask should work like a normal raster band for swig purposes so minimal special work should be required.

Testing

Issues

I'm tempted to change GetNullMaskType() into GetNullMaskFlags() and have the result be an or-ed set of flags. It would allow us to differentiate mask bands auto generated from nodata, and add special interpretations in the future, like is-alpha or is-confidence.

• I haven't filled in how creation of masks works.
• I haven't talked about bitmask-via-spill file possibilities for the PAM subsystem.