RSGISLib Image Calibration Module¶

The image calibration module contains functions for calibrating optical data from DN to radience and top of atmosphere reflectance and, using coefficients from 6S, surface reflectance.

For obtaining the correct parameters for each function it is recomented that rather than running directly they are called through the Atmospheric and Radiometric Correction of Satellite Imagery (ARCSI) software.

More details on ARCSI are avaialble from https://remotesensing.info/arcsi

class rsgislib.imagecalibration.AOTLUTFeat(AOT=None, Coeffs=None)¶

Create a list of these objects to pass to the rsgislib.imagecalibration.apply6SCoeffElevAOTLUTParam

Parameters

AOT – is the AOT value.
Coeffs – is the 6S coeffients as a Band6S object.
AOT – is the AOT value.
Coeffs – is the 6S coeffients as a Band6S object.

class rsgislib.imagecalibration.Band6SCoeff(band=None, aX=None, bX=None, cX=None, DirIrr=None, DifIrr=None, EnvIrr=None)¶: Create a list of these objects to provide the Coeffs for ElevLUTFeat and AOTLUTFeat.

class rsgislib.imagecalibration.ElevLUTFeat(Elev=None, Coeffs=None)¶

Create a list of these objects to pass to the rsgislib.imagecalibration.apply6SCoeffElevLUTParam

Parameters

Elev – is the elevation value.
Coeffs – is the 6S coeffients as a Band6S object.
Elev – is the elevation value.
Coeffs – is the 6S coeffients as a Band6S object.

rsgislib.imagecalibration.calcClearSkyRegions(cloudsImg, validAreaImg, outputClearSkyMask, outFormat, tmpPath='./tmpClearSky', deleteTmpFiles=True, initClearSkyRegionDist=5000, initClearSkyRegionMinSize=3000, finalClearSkyRegionDist=1000, morphSize=21)¶

Given a cloud mask, identify the larger extent regions of useful clear-sky regions.

Parameters

cloudsImg – An image with the input mask of the cloud (pixel == 1) and shadow (pixel == 2)
validAreaImg – A mask of the image data area (1 = valid and 0 = not-valid; i.e., outside of the data area)
outputClearSkyMask – The output mask of the clear sky areas
outFormat – The output image format.
tmpPath – The path for temporay images produced during the processing to be stored (Default: ‘./tmpClearSky’; Note. all temp files are generated as KEA files).
deleteTmpFiles – Boolean as to whether the intermediate files should be deleted following processing (Default: True - delete files).
initClearSkyRegionDist – The distance in metres from a cloud/shadow object for the initial identification of clear sky regions (Default: 5000)
initClearSkyRegionMinSize – The minimum size (in pixels) of the initial clear sky regions (Default: 3000 pixels)
finalClearSkyRegionDist – The distance in metres from a cloud/shadow object for the final boundaries of the clear sky regions (Default: 1000)
morphSize – the size of the circular morphological operator used to tidy up the result (Default: 21)

Example:

import rsgislib.imagecalibration
cloudsImg = "./Outputs/LS8_20160605_lat52lon261_r24p203_clouds.kea"
validAreaImg = "./Outputs/LS8_20160605_lat52lon261_r24p203_valid.kea"
outputMask = "./Outputs/LS8_20160605_lat52lon261_r24p203_openskyvalid.kea"
tmpPath = "./temp"
rsgislib.imagecalibration.calcClearSkyRegions(cloudsImg, validAreaImg, outputMask, 'KEA', tmpPath)

rsgislib.imagecalibration.getESUNValue(radiance, toaRefl, day, month, year, solarZenith)¶

Get the ESUN value where a radiance and TOA Reflectance value are known for a pixel.

Parameters

radiance – input at sensor radiance value.
toaRefl – input the known at sensor (top of atmosphere) reflectance value for the given radiance.
day – input the day of the acquisition.
month – input the month of the acquisition.
year – input the year of the acquisition.
solarZenith – input the solar zenith angle for the acquisition.

Returns

esun radiance

rsgislib.imagecalibration.performDOSCalc(inputFile, outputFile, gdalformat='KEA', nonNegative=True, noDataVal=0, darkObjReflVal=0, darkObjPercentile=0.01, copyBandNames=True, calcStatsPyd=True)¶

A command to perform a dark object subtraction (DOS) on an input image.

Parameters

inputFile – input image to which the DOS method is to be applied. Typically, this image with be in top of atmosphere reflectance (TOA)
outputFile – the output image file
gdalformat – the output image file format (default = KEA)
nonNegative – is a boolean specifying where negative output pixel values will be accepted (Dafualt is True; i.e., no negative values)
noDataVal – is the no data value within the input image file.
darkObjReflVal – is an offset which is applied to all pixel values to make a minimum reflectance value (Default = 0)
darkObjPercentile – is the percentile of the input image used to define the dark object threshold, range is 0 - 1 (Default is 0.01; i.e., 1%).
copyBandNames – is a boolean specifying that the band names of the input image should be copied to the output image file (Default: True)
calcStatsPyd – is a boolean specifying that the image stats and pyramids should be calculated on the output image (Default: True)

Example:

import rsgislib.imagecalibration
rsgislib.imagecalibration.performDOSCalc("LS5TM_20110701_lat52lon421_r24p204_rad_toa.kea", 'LS5TM_20110701_lat52lon421_r24p204_rad_toa_dos.kea")

Radiance¶

rsgislib.imagecalibration.landsat2Radiance(outputImage, gdalformat, bandDefnSeq)¶

Converts Landsat DN values to at sensor radiance.

Where:

Parameters

outputImage – is a string containing the name of the output file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsLandsatRadianceGainsOffsets objects that define the inputs * bandName - Name of image band in output file. * fileName - input image file. * bandIndex - Index (starting from 1) of the band in the image file. * lMin - lMin value from Landsat header. * lMax - lMax value from Landsat header. * qCalMin - qCalMin value from Landsat header. * qCalMax - qCalMax value from Landsat header.

rsgislib.imagecalibration.landsat2RadianceMultiAdd(outputImage, gdalformat, bandDefnSeq)¶

Converts Landsat DN values to at sensor radiance.

Where:

Parameters

outputImage – is a string containing the name of the output file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsLandsatRadianceGainsOffsets objects that define the inputs * bandName - Name of image band in output file. * fileName - input image file. * bandIndex - Index (starting from 1) of the band in the image file. * addVal - RADIANCE_ADD value from Landsat header. * multiVal - RADIANCE_MULT value from Landsat header.

rsgislib.imagecalibration.spot5ToRadiance(inputImage, outputImage, gdalformat, bandDefnSeq)¶

Converts WorldView2 DN values to at sensor radiance.

Where:

Parameters

inputImage – is a string containing the name of the input file
outputImage – is a string containing the name of the output file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsSPOT5RadianceGainsOffsets objects in order of the input image bands that define the inputs * bandName - Name of image band in output file. * bandIndex - Index (starting from 1) of the output image band order (i.e., to reorder the image bands). * gain - PHYSICAL_GAIN value from SPOT5 XML header. * bias - PHYSICAL_BIAS value from SPOT5 XML header.

rsgislib.imagecalibration.worldview2ToRadiance(inputImage, outputImage, gdalformat, bandDefnSeq)¶

Converts WorldView2 DN values to at sensor radiance.

Where:

Parameters

inputImage – is a string containing the name of the input file
outputImage – is a string containing the name of the output file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsWorldView2RadianceGainsOffsets objects that define the inputs * bandName - Name of image band in output file. * bandIndex - Index (starting from 1) of the band in the image file. * absCalFact - ABSCALFACTOR value from WorldView2 XML header. * effBandWidth - EFFECTIVEBANDWIDTH value from WorldView2 XML header.

rsgislib.imagecalibration.toaRefl2Radiance(inputFiles, outputFile, gdalFormat, datatype, scaleFactor, solarDistance, solarZenith, solarIrradianceVals)¶

Converts at sensor (Top of Atmosphere; TOA) reflectance values to at sensor radiance. This is the inverse of imagecalibration.radiance2TOARefl().

Where:

Parameters

inputFiles – can be either a single input image file with the same number of bands as the list of ESUN values or a list of single band images (same number of as the number of ESUN values).
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 if not wanted.
solarDistance – is a float specifying the solar-earth distance (see imagecalibration.calcSolarDistance).
solarZenith – is a a float with the solar zenith in degrees at the time of the acquisition (note 90-solarElevation = solarZenith).
solarIrradianceVals – is a sequence of floats each with the name ‘irradiance’ (ESUN) which is in order of the bands in the input image.

Top-of Atmosphere Reflectance¶

rsgislib.imagecalibration.radiance2TOARefl(inputFile, outputFile, gdalFormat, datatype, scaleFactor, year, month, day, solarZenith, solarIrradianceVals)¶

Converts at sensor radiance values to Top of Atmosphere Reflectance.

Where:

Parameters

inputFile – is a string containing the name of the input image file
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 if not wanted.
year – is an int with the year of the sensor acquisition.
month – is an int with the month of the sensor acquisition.
day – is an int with the day of the sensor acquisition.
solarZenith – is a a float with the solar zenith in degrees at the time of the acquisition (note 90-solarElevation = solarZenith).
solarIrradianceVals – is a sequence of floats each with the name ‘irradiance’ which is in order of the bands in the input image.

rsgislib.imagecalibration.landsatThermalRad2Brightness(inputImage, outputImage, gdalformat, datatype, scaleFactor, bandDefnSeq)¶

Converts Landsat TM thermal radiation to degrees celsius for at sensor temperature.

Where:

Parameters

inputImage – is a string containing the name of the input file path.
outputImage – is a string containing the name of the output file path.
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 for no scaling.
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsLandsatThermalCoeffs objects that define the inputs * bandName - Name of image band in output file. * bandIndex - Index (starting from 1) of the band in the image file. * k1 - k1 coefficient from Landsat header. * k2 - k2 coefficient from Landsat header.

Surface Reflectance (6S)¶

rsgislib.imagecalibration.apply6SCoeffSingleParam(inputFile, outputFile, gdalFormat, datatype, scaleFactor, noDataValue, useNoDataValue, bandCoeffs)¶

Converts at sensor radiance values to surface reflectance by applying coefficients from the 6S model for each band (aX, bX, cX).

Where:

Parameters

inputFile – is a string containing the name of the input image file
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 for no scaling.
noDataValue – is a float which if all bands contain that value will be ignored.
useNoDataValue – is a boolean as to whether the no data value specified is to be used.
bandCoeffs – is a sequence of objects with the following named fields. * band - An integer specifying the image band in the input file. * aX - A float for the aX coefficient. * bX - A float for the bX coefficient. * cX - A float for the cX coefficient.

rsgislib.imagecalibration.apply6SCoeffElevAOTLUTParam()¶

imagecalibration.apply6SCoeffElevLUTParam(inputRadFile, inputDEMFile, inputAOTImage, outputFile, gdalFormat, datatype, scaleFactor, noDataValue, useNoDataValue, lutElevAOT) Converts at sensor radiance values to surface reflectance by applying coefficients from the 6S model for each band (aX, bX, cX), where the coefficients can be varied for surface elevation.

Where:

Parameters

inputRadFile – is a string containing the name of the input Radiance image file
inputDEMFile – is a string containing the name of the input DEM image file (needs to be the same projection and resolution as radiance image.)
inputAOTImage – is a string containing the name of the input AOT image file (needs to be the same projection and resolution as radiance image.)
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 for no scaling.
noDataValue – is a float which if all bands contain that value will be ignored.
useNoDataValue – is a boolean as to whether the no data value specified is to be used.
lutElevAOT –
is a sequence of objects with the following named fields - note these are expected to be in elevation order (low to high and then AOT order (low to high). * ‘Elev’ - The elevation for the element in the LUT (in metres).
- ’AOT’ - The AOT value for this element within the LUT.
- ’Coeffs’ - The sequence of 6S coeffecients for the given elevation and AOT for the element in the LUT.
  
  ’band’ - An integer specifying the image band in the input file (band numbers start at 1).
  
  ’aX’ - A float for the aX coefficient.
  
  ’bX’ - A float for the bX coefficient.
  
  ’cX’ - A float for the cX coefficient.

rsgislib.imagecalibration.apply6SCoeffElevLUTParam(inputRadFile, inputDEMFile, outputFile, gdalFormat, datatype, scaleFactor, noDataValue, useNoDataValue, lutElev)¶

Converts at sensor radiance values to surface reflectance by applying coefficients from the 6S model for each band (aX, bX, cX), where the coefficients can be varied for surface elevation.

Where:

Parameters

inputRadFile – is a string containing the name of the input Radiance image file
inputDEMFile – is a string containing the name of the input DEM image file (needs to be the same projection and resolution as radiance image.)
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
scaleFactor – is a float which can be used to scale the output pixel values (e.g., multiple by 1000), set as 1 for no scaling.
noDataValue – is a float which if all bands contain that value will be ignored.
useNoDataValue – is a boolean as to whether the no data value specified is to be used.
lutElev –
is a sequence of objects with the following named fields - note these are expected to be in elevation order (low to high). * ‘Elev’ - The elevation for the element in the LUT (in metres). * ‘Coeffs’ - The sequence of 6S coeffecients for the given elevation for the element in the LUT.
- ’band’ - An integer specifying the image band in the input file (band numbers start at 1).
- ’aX’ - A float for the aX coefficient.
- ’bX’ - A float for the bX coefficient.
- ’cX’ - A float for the cX coefficient.

rsgislib.imagecalibration.calcStandardisedReflectanceSD2010(inputDataMaskImg, srefInputImage, inputSolarIrradiance, inputIncidenceAngleImg, inputExitanceAngleImg, outputFile, gdalFormat, reflScaleFactor, brdfBeta, outIncidenceAngle, outExitanceAngle)¶

Calculate standardised reflectance, with respect to solar and view angles, as defined by Shepherd and Dymond (2010)

Where:

Parameters

inputDataMaskImg – is a string containing the name and path to a binary mask specifying the region to be calculated (1 = True)
srefInputImage – is a surface reflectance image
inputSolarIrradiance – is the solar irradiance for each band of the SREF image. The image will have four times the number of bands as the SREF with Direct, Diffuse, Environment and Total irradiance for each (generated by imagecalibration.calcIrradianceImageElevLUT).
inputIncidenceAngleImg – is a string containing the name and path to a file with the incidence angle for each pixel.
inputExitanceAngleImg – is a string containing the name and path to a file with the existance angle for each pixel.
outputFile – is a string containing the name of the output image file
gdalFormat – is a string containing the GDAL format for the output file - eg ‘KEA’
reflScaleFactor – is a float with the scale factor to convert the SREF image to a range of 0-1 (e.g., 1000)
brdfBeta – is the beta parameters in equation 8 in Shepherd and Dymond (2010) for solar elevations between 50 - 70 degrees a value of 1 can be used.
outIncidenceAngle – is the incidence angle to which the output image is standardised to (Recommend: 0).
outExitanceAngle – is the exitance angle to which the output image is standardised to (Recommend: 0).

Surface Reflectance (DOS)¶

rsgislib.imagecalibration.applySubtractOffsets(inputFile, inputOffsetsFile, outputFile, gdalformat, datatype, nonNegative, useNoDataVal, noDataVal, darkObjReflVal)¶

This function performs a dark obejct subtraction (DOS) using a set of defined offsets for retriving surface reflectance.

Where:

Parameters

inputFile – is a string containing the name of the input image file
inputOffsetsFile – is a string containing the name of the input offsets image file, which must have the same number of bands as the input image.:param outputFile: is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
nonNegative – is a boolean specifying whether any negative values from the offset application should be removed (i.e., set to 1; 0 being no data).
useNoDataVal – a boolean specifying whether a no data value is present within the input image.
noDataVal – is a float specifying the no data value for the input image.
darkObjReflVal – is a float specifying the minimum value within the reflectance value used for the dark targets used for the subtraction

rsgislib.imagecalibration.applySubtractSingleOffsets(inputFile, outputFile, gdalformat, datatype, nonNegative, useNoDataVal, noDataVal, darkObjReflVal, offsetsList)¶

This function performs a dark obejct subtraction (DOS) using a set of defined offsets for retriving surface reflectance.

Where:

Parameters

inputFile – is a string containing the name of the input image file
outputFile – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
datatype – is an containing one of the values from rsgislib.TYPE_*
nonNegative – is a boolean specifying whether any negative values from the offset application should be removed (i.e., set to 1; 0 being no data).
useNoDataVal – a boolean specifying whether a no data value is present within the input image.
noDataVal – is a float specifying the no data value for the input image.
darkObjReflVal – is a float specifying the minimum value within the reflectance value used for the dark targets used for the subtraction:param offsetsList: is a list of offset values to be applied to the input image bands (specified with keyword ‘offset’).

rsgislib.imagecalibration.performDOSCalc(inputFile, outputFile, gdalformat='KEA', nonNegative=True, noDataVal=0, darkObjReflVal=0, darkObjPercentile=0.01, copyBandNames=True, calcStatsPyd=True)¶

A command to perform a dark object subtraction (DOS) on an input image.

Parameters

inputFile – input image to which the DOS method is to be applied. Typically, this image with be in top of atmosphere reflectance (TOA)
outputFile – the output image file
gdalformat – the output image file format (default = KEA)
nonNegative – is a boolean specifying where negative output pixel values will be accepted (Dafualt is True; i.e., no negative values)
noDataVal – is the no data value within the input image file.
darkObjReflVal – is an offset which is applied to all pixel values to make a minimum reflectance value (Default = 0)
darkObjPercentile – is the percentile of the input image used to define the dark object threshold, range is 0 - 1 (Default is 0.01; i.e., 1%).
copyBandNames – is a boolean specifying that the band names of the input image should be copied to the output image file (Default: True)
calcStatsPyd – is a boolean specifying that the image stats and pyramids should be calculated on the output image (Default: True)

Example:

import rsgislib.imagecalibration
rsgislib.imagecalibration.performDOSCalc("LS5TM_20110701_lat52lon421_r24p204_rad_toa.kea", 'LS5TM_20110701_lat52lon421_r24p204_rad_toa_dos.kea")

Irradiance¶

rsgislib.imagecalibration.calcIrradianceImageElevLUT(inputDataMaskImg, inputDEMFile, inputIncidenceAngleImg, inputSlopeImg, srefInputImage, shadowMaskImg, outputFile, gdalFormat, solarZenith, reflScaleFactor, lutElev)¶

Calculate the incoming irradiance (Direct, Diffuse, Environment and Total) for sloped surfaces (Eq 1. Shepherd and Dymond 2010).

Where:

Parameters

inputDataMaskImg – is a string containing the name and path to a binary mask specifying the region to be calculated (1 = True)
inputDEMFile – is a string containing the name of the input DEM image file.
inputIncidenceAngleImg – is a string containing the name and path to a file with the incidence angle for each pixel.
inputSlopeImg – is a string containing the name and path to a file with the slope in degrees for each pixel.
srefInputImage – is a surface reflectance image with the same number of bands for measurements are provided for in the LUT
shadowMaskImg – is a binary mask image for the areas of the image in direct shadow (pixel value 1) and therefore don’t recieve any direct irradiance.
outputFile – is a string containing the name of the output image file
gdalFormat – is a string containing the GDAL format for the output file - eg ‘KEA’
solarZenith – is a float with the solar zenith for the whole scene.
reflScaleFactor – is a float with the scale factor to convert the SREF image to a range of 0-1
lutElev –
is a sequence of objects with the following named fields - note these are expected to be in elevation order (low to high). * ‘Elev’ - The elevation for the element in the LUT (in metres). * ‘BandVals’ - The sequence of solar irradiance values for the bands in the SREF image.
- ’band’ - An integer specifying the image band in the input file (band numbers start at 1).
- ’DirIrr’ - A float for the direct irradiance for this band and elevation (i.e., as provided by 6S).
- ’DifIrr’ - A float for the diffuse irradiance for this band and elevation (i.e., as provided by 6S).
- ’EnvIrr’ - A float for the environment irradiance for this band and elevation (i.e., as provided by 6S).

Cloud Masking¶

rsgislib.imagecalibration.applyLandsatTMCloudFMask(inputTOAImage, inputThermalImage, inputSaturateImage, inValidAreaImage, outputImage, gdalFormat, sunAz, sunZen, senAz, senZen, scaleFactorIn, tmpImgsBase, tmpImgsFileExt, rmTmpImgs)¶

Applies the FMASK (Zhu and Woodcock 2012, RSE 118, pp83-94) cloud masking algorithm to the input image returning an output image with the cloud (pixel value 1) and shadow (pixel value 2).

Where:

Parameters

inputTOAImage – is a string containing the name of the input image TOA reflectance file
inputThermalImage – is a string containing the name of the input image with at sensor temperature (in celsius):param inputSaturateImage: is a string containing the name of the input image file mask for the saturated pixels per band (including thermal)
inValidAreaImage – is a string containing the name of a binary image specifying the valid area of the image data (1 is valid area)
outputImage – is a string containing the name of the output image file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
sunAz – is the solar azimuth of the input image
sunZen – is the solar azimuth of the input image
senAz – is the sensor azimuth of the input image
senZen – is the sensor azimuth of the input image
scaleFactorIn – is a float with the scale factor used to multiple the input image (reflectance and thermal) data.
tmpImgsBase – is a string specifying a base path and name for the tmp images used for this processing
tmpImgsFileExt – is a string for the file extention of the output images (e.g., .kea)
whitenessThreshold – is a float specifying the whiteness threshold (default is 0.7; Equation 2), this parameter is optional.
rmTmpImgs – is a bool specifying whether the tmp images should be deleted at the end of the processing (Optional; Default = True)

Example:

rsgislib.imagecalibration
inputReflImage = 'LS5TM_20110701_lat52lon421_r24p204_rad_toa.kea'
inputSatImage= 'LS5TM_20110701_lat52lon421_r24p204_sat.kea'
inValidImage = 'LS5TM_20110701_lat52lon421_r24p204_valid.kea'
inputThermalImage = 'LS5TM_20110701_lat52lon421_r24p204_thermal.kea'
outputImage = 'LS5TM_20110701_lat52lon421_r24p204_clouds.kea'
tmpImgsBase = './tmp/LS5TM_20110701_lat52lon421_r24p204'
if not os.path.exists(tmpImgsBase):
    os.makedirs(tmpImgsBase)
    tmpImgsBase = os.path.join(tmpImgsBase, 'LS5TM_20110701_lat52lon421_r24p204')

sunAz = math.radians(143.94209355)
sunZen = math.radians(90-57.48916743)

rsgislib.imagecalibration.applyLandsatTMCloudFMask(inputReflImage, inputThermalImage, inputSatImage, inValidImage, outputImage, 'KEA', sunAz, sunZen, senAz, senZen, 1000.0, tmpImgsBase, '.kea', 0.7, False)

rsgislib.imagecalibration.calcClearSkyRegions(cloudsImg, validAreaImg, outputClearSkyMask, outFormat, tmpPath='./tmpClearSky', deleteTmpFiles=True, initClearSkyRegionDist=5000, initClearSkyRegionMinSize=3000, finalClearSkyRegionDist=1000, morphSize=21)¶

Given a cloud mask, identify the larger extent regions of useful clear-sky regions.

Parameters

cloudsImg – An image with the input mask of the cloud (pixel == 1) and shadow (pixel == 2)
validAreaImg – A mask of the image data area (1 = valid and 0 = not-valid; i.e., outside of the data area)
outputClearSkyMask – The output mask of the clear sky areas
outFormat – The output image format.
tmpPath – The path for temporay images produced during the processing to be stored (Default: ‘./tmpClearSky’; Note. all temp files are generated as KEA files).
deleteTmpFiles – Boolean as to whether the intermediate files should be deleted following processing (Default: True - delete files).
initClearSkyRegionDist – The distance in metres from a cloud/shadow object for the initial identification of clear sky regions (Default: 5000)
initClearSkyRegionMinSize – The minimum size (in pixels) of the initial clear sky regions (Default: 3000 pixels)
finalClearSkyRegionDist – The distance in metres from a cloud/shadow object for the final boundaries of the clear sky regions (Default: 1000)
morphSize – the size of the circular morphological operator used to tidy up the result (Default: 21)

Example:

import rsgislib.imagecalibration
cloudsImg = "./Outputs/LS8_20160605_lat52lon261_r24p203_clouds.kea"
validAreaImg = "./Outputs/LS8_20160605_lat52lon261_r24p203_valid.kea"
outputMask = "./Outputs/LS8_20160605_lat52lon261_r24p203_openskyvalid.kea"
tmpPath = "./temp"
rsgislib.imagecalibration.calcClearSkyRegions(cloudsImg, validAreaImg, outputMask, 'KEA', tmpPath)

rsgislib.imagecalibration.calcCloudShadowMask(inputCloudMask, inputReflImage, inValidAreaImage, outputImage, darkImgBand, gdalFormat, scaleFactor, tmpImgsBase, tmpImgsFileExt, sunAz, sunZen, senAz, senZen, rmTmpImgs)¶

Calculate a cloud shadow mask from an inputted cloud mask. Where:

Parameters

inputCloudMask – is a string containing the name of the input cloud mask
inputTOAImage – is a string containing the name of the input image TOA reflectance file
inValidAreaImage – is a string containing the name of a binary image specifying the valid area of the image data (1 is valid area)
outputImage – is a string containing the name of the output image file
darkImgBand – is an integer specifying the image band from the reflectance image which is to used to find the shadows (the NIR is often recommended).
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
scaleFactor – is a float with the scale factor used to multiple the input image reflectance data.
tmpImgsBase – is a string specifying a base path and name for the tmp images used for this processing
tmpImgsFileExt – is a string for the file extention of the output images (e.g., .kea)
sunAz – is the solar azimuth of the input image
sunZen – is the solar azimuth of the input image
senAz – is the sensor azimuth of the input image
senZen – is the sensor azimuth of the input image
rmTmpImgs – is a bool specifying whether the tmp images should be deleted at the end of the processing (Optional; Default = True)

Utilities¶

rsgislib.imagecalibration.saturatedPixelsMask(outputImage, gdalformat, bandDefnSeq)¶

Creates a mask of the saturated image pixels on a per band basis.

Where:

Parameters

outputImage – is a string containing the name of the output file
gdalformat – is a string containing the GDAL format for the output file - eg ‘KEA’
bandDefnSeq – is a sequence of rsgislib.imagecalibration.CmdsSaturatedPixel objects that define the inputs * bandName - Name of image band in output file. * fileName - input image file. * bandIndex - Index (starting from 1) of the band in the image file. * satVal - Saturation value for the image band.

rsgislib.imagecalibration.calcNadirImgViewAngle(inImgFootprint, outViewAngleImg, gdalFormat, sateAltitude, minXXCol, minXYCol, maxXXCol, maxXYCol, minYXCol, minYYCol, maxYXCol, maxYYCol)¶

Calculate the sensor view angle for each pixel for a nadir sensor. Need to provide the satellite altitude in metres, for Landsat this is 705000.0.

Where:

Parameters

inImgFootprint – is a string containing the name/path of the input file. This file needs to be to have a RAT with only one clump with pixel value 1.
outViewAngleImg – is a string for the name/path of the output file.
gdalFormat – is a string for the GDAL format
sateAltitude – is a float in metres for the satellite altitude.
minXXCol – is a string for the minXX column in the RAT.
minXYCol – is a string for the minXY column in the RAT.
maxXXCol – is a string for the maxXX column in the RAT.
maxXYCol – is a string for the maxXY column in the RAT.
minYXCol – is a string for the minYX column in the RAT.
minYYCol – is a string for the minYY column in the RAT.
maxYXCol – is a string for the maxYX column in the RAT.
maxYYCol – is a string for the maxYY column in the RAT.

rsgislib.imagecalibration.getJulianDay(year, month, day)¶

Calculates the julian day for the input date.

Where:

Parameters

year – is an int with the year of the sensor acquisition.
month – is an int with the month of the sensor acquisition.
day – is an int with the day of the sensor acquisition.

Returns

julianDay - float

rsgislib.imagecalibration.calcSolarDistance(julianDay)¶

Calculates the earth-solar distance from the given julian day.

Where:

Parameters: julianDay – is an int with the julian day of the sensor acquisition.
Returns: solarDistance - float

rsgislib.imagecalibration.getESUNValue(radiance, toaRefl, day, month, year, solarZenith)¶

Get the ESUN value where a radiance and TOA Reflectance value are known for a pixel.

Parameters

radiance – input at sensor radiance value.
toaRefl – input the known at sensor (top of atmosphere) reflectance value for the given radiance.
day – input the day of the acquisition.
month – input the month of the acquisition.
year – input the year of the acquisition.
solarZenith – input the solar zenith angle for the acquisition.

Returns

esun radiance

Solar Angles¶

rsgislib.imagecalibration.solarangles.getSolarIrrConventionSolarAzimuthFromUSGS(solarAz)¶

IN: USGS Convertion:

         N (0)
         |
W (-90)-----E (90) 
         |
  (-180) S (180)

OUT: Solar Irradiance Convertion:

         N (0)
         |
W (270)-----E (90) 
         |
         S (180)

rsgislib.imagecalibration.solarangles.getSolarIrrConventionSolarAzimuthFromTrad(solarAz)¶

IN: Traditional Convertion:

  (-180) N (180)
         |
W (-90)-----E (90) 
         |
         S (0)

OUT: Solar Irradiance Convertion:

         N (0)
         |
W (270)-----E (90) 
         |
         S (180)    

rsgislib.imagecalibration.solarangles.calcSolarAzimuthZenith(inputImg, inImgDateTime, outputImg, gdalformat)¶

Function which calculate a solar azimuth (band 1) and zenith (band 2) image.

Parameters

inputImg – input image file (can be any image with a spatial header)
inImgDateTime – a datatime object for the data/time of the acquasition
outputImg – output image file and path
gdalformat – output file format (e.g., KEA)

RSGISLib Image Calibration Module¶

Radiance¶

Top-of Atmosphere Reflectance¶

Surface Reflectance (6S)¶

Surface Reflectance (DOS)¶

Irradiance¶

Cloud Masking¶

Utilities¶

Solar Angles¶

Table of Contents

Previous topic

Next topic

This Page