config

Configuration classes that define the inputs and parameters for the fmask function.

class fmask.config.AngleConstantInfo(solarZenithAngle, solarAzimuthAngle, viewZenithAngle, viewAzimuthAngle)

An implementation of AnglesInfo that uses constant angles accross the scene.

getSolarAzimuthAngle(indices)

Return the solar azimuth angle

getSolarZenithAngle(indices)

Return the solar zenith angle

getViewAzimuthAngle(indices)

Return the view azimuth angle

getViewZenithAngle(indices)

Return the view zenith angle

class fmask.config.AnglesFileInfo(solarZenithFilename, solarZenithBand, solarAzimuthFilename, solarAzimuthBand, viewZenithFilename, viewZenithBand, viewAzimuthFilename, viewAzimuthBand)

An implementation of AnglesInfo that reads the information from GDAL supported files.

getSolarAzimuthAngle(indices)

Return the average solar azimuth angle for the given indices

getSolarZenithAngle(indices)

Return the average solar zenith angle for the given indices

getViewAzimuthAngle(indices)

Return the average view azimuth angle for the given indices

getViewZenithAngle(indices)

Return the average view zenith angle for the given indices

prepareForQuerying()

Called when fmask is about to query this object for angles.

static readData(filename, bandNum)

releaseMemory()

Called when fmask has finished querying this object.

setScaleToRadians(scale)

Set scaling factor to get radians from angles image values.

class fmask.config.AnglesInfo

Abstract base class that Contains view and solar angle information for file (in radians).

getSolarAzimuthAngle(indices)

Return the average solar azimuth angle for the given indices

getSolarZenithAngle(indices)

Return the average solar zenith angle for the given indices

getViewAzimuthAngle(indices)

Return the average view azimuth angle for the given indices

getViewZenithAngle(indices)

Return the average view zenith angle for the given indices

prepareForQuerying()

Called when fmask is about to query this object for angles. Derived class should do any reading of files into memory required here.

releaseMemory()

Called when fmask has finished querying this object. Can release any allocated memory.

setScaleToRadians(scale)

Set scaling factor to get radians from angles image values.

class fmask.config.FmaskConfig(sensor)

Class that contains the configuration parameters of the fmask run.

setAnglesInfo(info)

Set an instance of AnglesInfo. By default this is None and will need to be set before fmask will run.

The fmask.config.readAnglesFromLandsatMTL() function can be used to obtain this from a Landsat .mtl file.

setCirrusBandTestThresh(thresh)

Change the threshold used by Zhu et al 2015, section 2.2.1 for the cirrus band test. Defaults to 0.01.

setCirrusProbRatio(ratio)

Change the ratio used by Zhu et al 2015 Equation 1 to determine the cirrus cloud probability. Defaults to 0.04.

setCloudBufferSize(bufferSize)

Extra buffer of this many pixels on cloud layer. Defaults to 5.

setDefaultExtension(extension)

Sets the default extension used by temporary files created by fmask. Defaults to the extension of the driver that RIOS is configured to use.

Note that this should include the ‘.’ - ie ‘.img’.

setEqn17CloudProbThresh(thresh)

Change the threshold used by Equation 17. The threshold given here is the constant term added to the end of the equation for the land probability threshold. Original paper had this as 0.2, although Zhu et al’s MATLAB code now defaults it to 0.225 (i.e. 22.5%)

setEqn19NIRFillThresh(thresh)

Change the threshold used by Equation 19 to determine potential cloud shadow from the difference between NIR and flood filled NIR. Defaults to 0.02.

setEqn1Swir2Thresh(thresh)

Change the threshold used by Equation 1 for the SWIR2 band. This defaults to 0.03

setEqn1ThermThresh(thresh)

Change the threshold used by Equation one for BT. This defaults to 27.

setEqn20GreenSnowThresh(thresh)

Change the threshold used by Equation 20 (snow) for green reflectance. This defaults to 0.1

setEqn20NirSnowThresh(thresh)

Change the threshold used by Equation 20 (snow) for NIR reflectance. This defaults to 0.11

setEqn20ThermThresh(thresh)

Change the threshold used by Equation 20 (snow) for BT. This defaults to 3.8.

setEqn2WhitenessThresh(thresh)

Change the threshold used by Equation 2 to determine whiteness from visible bands. This defaults to 0.7.

setEqn7Swir2Thresh(thresh)

Change the threshold used by Equation 7 (water test) for the Swir2 band. This defaults to 0.03.

setGdalDriverName(driverName)

Change the GDAL driver used for writing the final output file. Default value is taken from the default for the RIOS package, as per $RIOS_DFLT_DRIVER.

setKeepIntermediates(keepIntermediates)

Set to True to keep the intermediate files created in processed. This is False by default.

setMinCloudSize(minCloudSize)

Set the minimum cloud size retained. This minimum is applied before any buffering of clouds. Size is specified as an area, in pixels.

setReflectiveBand(band, index)

Tell fmask which band is in which index in the reflectance data stack file. band should be one of the BAND_* constants. index is zero based (ie 0 is first band in the file).

These are set to default values for each sensor which are normally correct, but this function can be used to update.

setSen2displacementTest(useDisplacementTest)

Set whether or not to use the Frantz (2018) parallax displacement test to remove false clouds. Pass True if the test is desired, False otherwise.

setShadowBufferSize(bufferSize)

Extra buffer of this many pixels on cloud layer. Defaults to 10.

setStrictFmask(strictFmask)

Set whatever options are necessary to run strictly as per Fmask paper (Zhu & Woodcock). Setting this will override the settings of other parameters on this object.

setTOARefOffsetDict(offsetDict)

Set the reflectance offsets to the given list. This should contain an offset value for each band used with the Fmask code. The keys are the named constants in the config module, BAND_*.

The offset is added to the corresponding band pixel values before dividing by the scaling value.

This facility is made available largely for use with Sentinel-2, after ESA unilaterally starting using non-zero offsets in their Level-1C imagery (Nov 2021). However, it can be used with Landsat if required.

setTOARefScaling(scaling)

Set the scaling used in the Top of Atmosphere reflectance image. The calculation is done as

ref = (dn + dnOffset) / scaling

and so is used in conjunction with the offset values (see setTOARefOffsets).

The dnOffset was added in 2021 to cope with ESA’s absurd decision to suddenly introduce an offset in their Sentinel-2 TOA reflectance imagery. For Landsat, there is no need for it ever to be non-zero.

setTempDir(tempDir)

Temporary directory to use. Defaults to ‘.’ (the current directory).

setThermalInfo(info)

Set an instance of ThermalFileInfo. By default this is None and fmask assumes there is no thermal data available.

The fmask.config.readThermalInfoFromLandsatMTL() function can be used to obtain this from a Landsat .mtl file.

setVerbose(verbose)

Print informative messages. Defaults to False.

Eqn17CloudProbThresh = 0.2

Eqn19NIRFillThresh = 0.02

Eqn1Swir2Thresh = 0.03

Eqn1ThermThresh = 27

Eqn20GreenSnowThresh = 0.1

Eqn20NirSnowThresh = 0.11

Eqn20ThermThresh = 3.8

Eqn2WhitenessThresh = 0.7

Eqn7Swir2Thresh = 0.03

TOARefDNoffsetDict = None

TOARefScaling = 10000.0

cirrusBandTestThresh = 0.01

cirrusProbRatio = 0.04

cloudBufferSize = 5

gdalDriverName = <Mock name='mock.applier.DEFAULTDRIVERNAME' id='140658674535184'>

keepIntermediates = False

minCloudSize_pixels = 0

sen2cdiWindow = 7

sen2displacementTest = False

shadowBufferSize = 10

strictFmask = False

tempDir = '.'

verbose = False

class fmask.config.FmaskFilenames(toaRefFile=None, thermalFile=None, outputMask=None, saturationMask=None)

Class that contains the filenames used in the fmask run.

setOutputCloudMaskFile(cloudMask)

Set the output cloud mask path.

Note that this file will be written in the format that RIOS is currently configured to use. See the RIOS documentation for more details. Note that the default is HFA (.img) and can be overridden using environment variables.

setSaturationMask(mask)

Set the mask to use for ignoring saturated pixels. By default no mask is used and all pixels are assumed to be unsaturated. This will cause problems for the whiteness test if some pixels are in fact saturated, but not masked out.

Use the fmask.saturation.makeSaturationMask() function to create this from input radiance data.

This mask should be 1 for pixels that are saturated, 0 otherwise.

Note that this is not in the original paper so cannot be considered ‘strict’, but if provided is used no matter the strict setting in fmask.config.FmaskConfig.

This file should be in any GDAL readable format.

setTOAReflectanceFile(toaRefFile)

Set the path of the input top of atmosphere (TOA) file. It pays to check that the default set of bands match what fmask expects in the fmask.config.FmaskConfig class and update if necessary.

This should have numbers which are reflectance * 1000

Use the fmask.landsatTOA.makeTOAReflectance() function to create this file from raw Landsat radiance (or the fmask_usgsLandsatTOA.py command line program supplied with fmask).

It is assumed that any values that are nulls in the original radiance image are set to the ignore values in the toaRefFile.

This file should be in any GDAL readable format.

setThermalFile(thermalFile)

Set the path of the input thermal file. To make use of this, the fmask.config.FmaskConfig.setThermalInfo() function must also be called so that fmask knows how to use the file.

This file should be in any GDAL readable format.

outputMask = None

saturationMask = None

thermal = None

toaRef = None

class fmask.config.ThermalFileInfo(thermalBand1040um, thermalGain1040um, thermalOffset1040um, thermalK1_1040um, thermalK2_1040um)

Contains parameters for interpreting thermal file. See fmask.config.readThermalInfoFromLandsatMTL().

scaleThermalDNtoC(scaledBT)

Use the given params to unscale the thermal, and then convert it from K to C. Return a single 2-d array of the temperature in deg C.

thermalBand1040um = None

thermalGain1040um = None

thermalK1_1040um = None

thermalK2_1040um = None

thermalOffset1040um = None

fmask.config.readAnglesFromLandsatMTL(mtlfile)

Given the path to a Landsat USGS .MTL file, read the angles out and return an instance of AngleConstantInfo.

This is no longer supported, and this routine now raises an exception.

fmask.config.readMTLFile(mtl)

Very simple .mtl file reader that just creates a dictionary of key and values and returns it

fmask.config.readThermalInfoFromLandsatMTL(mtlfile, thermalBand1040um=0)

Returns an instance of ThermalFileInfo given a path to the mtl file and the index of the thermal band.

fmask.config.BAND_BLUE = 0

~475nm

fmask.config.BAND_CIRRUS = 4

~1360nm

fmask.config.BAND_GREEN = 1

~560nm

fmask.config.BAND_NIR = 3

~780nm

fmask.config.BAND_RED = 2

~660nm

fmask.config.BAND_S2CDI_NIR7 = 8

~783nm

fmask.config.BAND_S2CDI_NIR8A = 7

~865nm

fmask.config.BAND_SWIR1 = 5

~1610nm

fmask.config.BAND_SWIR2 = 6

~2200nm

fmask.config.FMASK_LANDSAT47 = 0

Landsat 4 to 7

fmask.config.FMASK_LANDSAT8 = 1

Landsat 8

fmask.config.FMASK_LANDSATOLI = 3

Landsat OLI

fmask.config.FMASK_SENTINEL2 = 2

Sentinel 2

• Index
• Module Index
• Search Page