cfmask band will disappear, information migrated to pixel_qa band

[loicdtx]

Note from ESPA:

May 9, 2017 - Notice of Upcoming CFMask Discontinuation
Starting June 2, 2017, users will no longer be able to order CFMask processing for Landsat Collection 1 Higher-Level data products. Equivalent information is now available in the pixel_qa band, which is included with all Higher-Level products. For more information on the pixel_qa band, see the Product Characteristics sections of the Landsat 4-7 and Landsat 8 Surface Reflectance Product Guides.

L8 product guide
L4-7 product guide

TODO:

• Add pixel_qa Bit Index table to processLandsat doc
• Create well documented bitVectorToInt function
• Choose sensible default values for processLandsat
• Update tutorial to reflect these changes

Example of bitToInt function

def bit_pos_to_int(x):
    """Takes a list containing bit positions and returns the corresponding
    integer

    Args:
        x (list): A list of bit position (e.g.: [0,3] for 1001, aka 9)

    Return:
        The integer corresponding to the list of bit position provided in the
        list
    """
    bit_list = [0] * (max(x) + 1)
    for i in x:
        bit_list[i] = 1
    out = 0
    for bit in bit_list[::-1]:
        out = (out << 1) | bit
    return out

[GreatEmerald]

On the it value conversion, for a related package I suggested making a function with human-interpretable parameters that define features (=bits) that must (TRUE), must not (FALSE) or may (NA) be present in the output file: JornDallinga/JornDallinga.github.io#3

So, for instance, to obtain Landsat 8 "Clear" values one could have:

GetLandsat8QCMask(fill=FALSE, clear=TRUE, water=FALSE, shadow=FALSE, snow=FALSE,
cloud=FALSE, occlusion=FALSE, cloud_confidence=c("Low", "Medium"), cirrus_confidence="Low")

And that would return integers 322 and 386. This makes it easy to, for instance, not to filter out water pixels (by using water=NA, in which case the function returns 4 integers).