Changes between Version 7 and Version 8 of rfc15_nodatabitmask


Ignore:
Timestamp:
Aug 21, 2007, 8:09:06 AM (17 years ago)
Author:
warmerdam
Comment:

renaming, clarification on default implementation.

Legend:

Unmodified
Added
Removed
Modified

  • rfc15_nodatabitmask

    v7 v8  
    1 = RFC 14: Null Masks =
     1= RFC 14: Band Masks =
    22
    33Author: Frank Warmerdam[[BR]]
    … …  
    77== Summary ==
    88
    9 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 null masks through the GDAL API.
     9Some 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 null masks through the GDAL API, while moving to a uniform means of representing other kinds of masking (nodata values, and alpha bands).
    1010
    11 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 non-zero values indicating valid data.  Normally the value 255 will be used for valid data pixels.
     11The 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 masks are represented as GDT_Byte bands with a value of zero indicating nodata and non-zero values indicating valid data.  Normally the value 255 will be used for valid data pixels.
    1212
    1313== API ==
    … …  
    1616
    1717{{{
    18     GDALRasterBand *GetNullMask();
    19     int             GetNullMaskFlags();
     18    GDALRasterBand *GetMaskBand();
     19    int             GetMaskFlags();
    2020}}}
    2121
    22 Note that the !GetNullMask() should always return a GDALRasterBand mask, even if it is only an all 255 mask with the type indicating "all valid".
     22Note that the !GetMaskBand() should always return a GDALRasterBand mask, even if it is only an all 255 mask with the flags indicating GNMF_ALL_VALID.
    2323
    24 The !GetNullMaskFlags() method returns an ORed set of status flags with the following available definitions that may be extended in the future:
     24The !GetMaskFlags() method returns an bitwise OR-ed set of status flags with the following available definitions that may be extended in the future:
    2525
    2626 * GNMF_ALL_VALID(0x01): There are no invalid pixels, all mask values will be 255.  When used this will normally be the only flag set.
    … …  
    2828 * GNMF_ALPHA(0x04): The mask band is actually an alpha band and may have values other than 0 and 255.
    2929
    30 Note that the !GetNullMask() should always return a GDALRasterBand mask, even if it is only an all 255 mask with the flag GNMF_ALL_VALID set.
    31 
    3230== Default Implementation ==
    3331
    34 The GDALRasterBand class will include a default implementation of !GetNullMask() that returns one of three default implementations. 
     32The GDALRasterBand class will include a default implementation of !GetMaskBand() that returns one of three default implementations. 
    3533
    3634 * If the band has a nodata value set, an instance of the new GDALNodataMaskRasterBand class will be returned.  !GetNullMaskFlags() will return zero (no flags set).
    … …  
    3836 * If neither of the above apply, an instance of the new GDALAllValidRasterBand class will be returned that has 255 values for all pixels.  The null flags will return GNMF_ALL_VALID.
    3937
     38The GDALRasterBand will include a protected poMask instance variable and a bOwnMask flag.  The first call to the default !GetMaskBand() will result in creation of the GDALNodataMaskRasterBand, GDALAllValidMaskRasterBand and their assignment to poMask with bOwnMask set TRUE.  If an alpha band is identified for use, it will be assigned to poMask and bOwnMask set to FALSE.  The GDALRasterBand class will take care of deleting the poMask if set and bOwnMask is true in the destructor.  Derived band classes may safely use the poMask and bOwnMask flag similarly as long as the semantics are maintained.
     39
    4040== Alpha Bands ==
    4141
    42 When a dataset has a normal GDT_Byte alpha (transparency) band that applies, it should be returned as the null mask, but the !GetNullMaskFlags() method should include GNMF_ALPHA.  For processing purposes any value other than 0 should be treated as valid data, though some algorithms will treat values between 1 and 254 as partially transparent. 
     42When a dataset has a normal GDT_Byte alpha (transparency) band that applies, it should be returned as the null mask, but the !GetMaskFlags() method should include GNMF_ALPHA.  For processing purposes any value other than 0 should be treated as valid data, though some algorithms will treat values between 1 and 254 as partially transparent. 
    4343
    4444== Drivers Updated ==
    … …  
    6363== SWIG Implications ==
    6464 
    65 The !GetNullMask() and !GetNullMaskFlags() 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.
     65The !GetMaskBand() and !GetMaskFlags() methods (and corrsponding defines) will need to be added.  The mask should work like a normal raster band for swig purposes so minimal special work should be required.
    6666
    6767== Testing ==