The significance attached to each bit of the quality values is arbitrary, and it is expected that specialised software packages which need to exploit the full capabilities of the quality component will make a particular choice of bit assignments and interpret these to influence the processing they perform, possibly in quite subtle ways. Such applications can never be truly general-purpose, however, because the number of possible bit assignments is unlimited, so agreement between writers of different software packages about how to interpret each bit cannot be achieved.
Nevertheless, some way of taking account of quality values in general-purpose software is very desirable. To allow this, an additional part of the quality component, termed the bad-bits mask is provided. This is a single 8-bit (unsigned byte) value, whose purpose is to allow the 8-bit quality value associated with each pixel to be converted into a single logical value, which can then be interpreted in the same way by all general-purpose software.
The value of the bad-bits mask for an NDF is obtained by calling the routine NDF_BB:
BYTE BADBIT
...
CALL NDF_BB( INDF, BADBIT, STATUS )
The returned result BADBIT is an unsigned byte number. If the NDF's quality component is undefined and/or a bad-bits value has not previously been set, then a value of zero is returned.
A new value for the bad-bits mask may be set with the routine NDF_SBB:
CALL NDF_SBB( BADBIT, INDF, STATUS )
By definition, the quality value of an individual pixel QUAL is
converted into a logical value by forming the bit-wise ``AND'' with the
bad-bits mask BADBIT and testing if the result is zero.
In effect, this means that each bit which is set in BADBIT acts as a switch to
activate detection of the corresponding bit in QUAL.
If detection of a particular bit is activated and that bit is
set in the QUAL value, then the corresponding NDF pixel is to be regarded as
bad, and should be omitted from processing in much the same way as any
pixel which has been explicitly assigned the bad-pixel value (see
§).
In Fortran implementations which support bit-wise operations, the logical value might be computed as follows:
OK = IIAND( IZEXT( QUAL ), IZEXT( BADBIT ) ) .EQ. 0
where a .FALSE. result indicates a bad pixel.
However, this operation clearly requires non-standard Fortran
functions and is potentially non-portable, so a function NDF_QMASK is
provided to perform this task and to hide the implementation details.
NDF_QMASK is a statement function and is defined by putting the following
include statement into an application, normally immediately after any local
variable declarations:
INCLUDE 'NDF_FUNC'
Conversion of the quality value into a logical value is then performed by the function as follows:
OK = NDF_QMASK( QUAL, BADBIT )
The following example shows how a simple loop to find the average value of a pixel in an image array DATA might be written so as to take account of associated quality values, and exclude affected pixels:
BYTE QUAL( NX, NY )
INTEGER NGOOD, NX, NY, I, J
REAL DATA( NX, NY ), SUM, AVERAG
INCLUDE 'NDF_FUNC'
...
SUM = 0.0
NGOOD = 0
DO 2 J = 1, NY
DO 1 I = 1, NX
IF ( NDF_QMASK( QUAL( I, J ), BADBIT ) ) THEN
SUM = SUM + DATA( I, J )
NGOOD = NGOOD + 1
END IF
1 CONTINUE
2 CONTINUE
IF ( NGOOD .GT. 0 ) AVERAG = SUM / REAL( NGOOD )
As an alternative to the above explicit conversion of quality values into logical values, it is also possible to gain access to the quality array already converted into this form by calling the routine NDF_MAPQL, as follows:
CALL NDF_MAPQL( INDF, PNTR, EL, BAD, STATUS )
This routine returns a pointer to a mapped array of logical values which are derived from the quality array and the current value of the bad-bits mask following the prescription above. Only read access is obtained by this routine and any modifications made to the mapped values will not result in a permanent change to the quality component. If the quality component is undefined, then an array of .TRUE. values is returned.
NDF_MAPQL also has an additional argument BAD, which indicates whether there are any .FALSE. values in the mapped array it returns. If BAD is returned .FALSE., then all the mapped values will have the value .TRUE., so quality information is either absent or, in combination with the bad-bits mask, has no effect. In such cases it may be possible to omit handling of quality values altogether and affect an improvement in algorithmic efficiency as a result.
Finally, it should be noted that while the use of NDF_MAPQL may appear more convenient than explicitly handling the quality values and bad-bits mask, it nevertheless involves an additional pass through the quality array and will therefore be a less efficient option.