iCOR plugin for SNAP toolbox
Software User Manual
Version
1.0: 17/04/2017
VITO
Remote Sensing Unit
Boeretang 200 | 2400 Mol | Belgium
Contents
2.3. Download and installation
This document describes the installation and handling of the iCOR plugin for the Sentinel-2 SNAP toolbox.
The plugin allows users to test and perform an iCOR atmospheric correction for
- Landsat-8 and Sentinel2 data
- Land, inland and coastal waters
iCOR, previously known as OPERA (Sterckx et al., 2015) is scene and sensor generic atmospheric correction algorithm that can handle land and water targets and is adaptable with minimal efforts to other hyper- or multi-spectral sensors. All input data required for the atmospheric correction are derived from the image itself or delivered through pre-calculated look-up-tables. Through the use of a single atmospheric correction implementation, discontinuities in the reflectance between land and the highly dynamic water areas are reduced. The workflow of iCOR is depicted in Figure 1. In short following steps are run through: (i) land and water pixels are identified (ii) land pixels are used to derive Aerosol Optical Thickness (AOT) based on an adapted version of the method developed by (Guanter, 2007) (iii) an adjacency correction is performed using SIMEC (Sterckx et al., 2014) over water and fixed background ranges over land targets, and (iv) the radiative transfer equation is solved. iCOR uses MODTRAN 5 (Berk et al., 2006) Look Up Tables (LUT) to perform the atmospheric correction and needs information about the solar and viewing angles (Sun Zenith Angle (SZA), View Zenith Angle (VZA) and Relative Azimuth Angle (RAA)) and a digital elevation model (DEM).
Figure 1 Workflow of iCOR atmospheric correction. LUT = Look-up-Table, SZA = Solar Zenith Angle, VZA = View zenith anhle, RAA = relative azimuth angle, DEM = Digital Elevation Model, TOA = Top-Of-Atmopshere, AOT = Aerosol Optical Thickness, SIMEC = Similarity Environment Correction (Sterckx et al., 2014), L2 = Level 2 atmospherically corrected .
This document is written for Sentinel-2 SNAP Toolbox users. The document assumes that the reader is familiar with the basic concepts in the SNAP software and its integrated processors.
The iCOR plugin for the Sentinel-2 SNAP toolbox is provided as an experimental tool for research purposes. The use of the tool is at own discretion and risk.
AOT Aerosol Optical Thickness
BOA Bottom-of-Atmopshere
DEM Digital Elevation Model
iCOR Image Correction, previously known as OPERA (Sterckx et al., 2015)
SIMEC Similarity Environment correction (Sterckx et al., 2014)
TOA Top-Of-Atmosphere
VITO Vlaams Instituut voor Technologisch Onderzoek
Guanter, L., 2007. New algorithms for atmospheric correction and retrieval of biophysical parameters in earth observation. Application to ENVISAT/MERIS data.
Guanter, L., Alonso, L., Moreno, J., Member, A., 2005. A Method for the Surface Reflectance Retrieval From PROBA / CHRIS Data Over Land : Application to ESA SPARC Campaigns 43, 2908–2917.
Richter, R., Schläpfer, D., Müller, A., 2006. An automatic atmospheric correction algorithm for visible/NIR imagery. Int. J. Remote Sens. 27, 2077–2085. doi:10.1080/01431160500486690
Sterckx, S., Knaeps, E., Adriaensen, S., Reusen, I., Keukelaere, L. De, Hunter, P., 2015. Opera : an Atmospheric Correction for Land and Water. Proc. Sentin. Sci. Work. 3–6.
Sterckx, S., Knaeps, S., Kratzer, S., Ruddick, K., 2014. SIMilarity Environment Correction (SIMEC) applied to MERIS data over inland and coastal waters. Remote Sens. Environ. doi:10.1016/j.rse.2014.06.017
Vermote, E.F., Tanré, D., Deuzé, J.L., Herman, M., Morcrette, J.J., 1997. Second simulation of the satellite signal in the solar spectrum, 6s: an overview. IEEE Trans. Geosci. Remote Sens. 35, 675–686. doi:10.1109/36.581987
2.6 GB of free disk space
OS :
· Window 7 or higher (64bit)
· Linux : Ubuntu 16.04 or Centos7 (different packages) (64bit)
General :
· Python 2.7 – https://www.python.org/download/releases/2.7/
· SNAP 5.0.0 – http://step.esa.int/main/download/
Windows :
· VS2015 redistributables https://www.microsoft.com/en-us/download/details.aspx?id=48145
During the installation of SNAP, select the ‘Configure SNAP for use with Python’ checkbox and refer to the folder where Python 2.7 is installed (by default: C:\Python27\pyhton.exe).
Download iCOR plugin from:
https://remotesensing.vito.be/technology/continuously-improving-image-quality
Run iCOR_Setup.msi
A new window will pop-up iCOR Setup. Go through the installation by selecting Next à ‘I accept the terms in the License Agreement’ à choose the installation folder (by default: C:\Program Files\VITO\iCOR\)
If the tool is successfully installed, you need to provide the installation path to SNAP. Therefore, in the SNAP toolbox go to Tools à Plugins à Downloaded à Add Plugins.
Browse to the directory where the iCOR files where downloaded and select the files:
- iCOR-landsat8-sta-1.0.nbm
- iCOR-sentinel2-sta-1.0.nbm
Select both plugins (iCOR-landsat8-sta and iCOR-sentinel2-sta) and press on Install à Next à Select ‘I accept the terms in the License Agreement’ à Install.
A validation Warning might pop-up:
Press Continue to continue the installation procedure.
To complete the installation, restart SNAP.
If you made adaptations to the installation path of one of the software tools (python by default: C:\Python27\pyhton.exe or iCOR by default: C:\Program Files\VITO\iCOR\), you might need to adapt the settings through Tools à Manage External Tools. A new window will pop-up where you can highlight which tool you’d like to edit.
When the plugin is loaded in SNAP, the tool can be accessed through Optical à iCOR. There are two versions: one for processing Landsat-8 (iCOR-L8) and one for Sentinel-2 (iCOR-S2) data. The set-up of both versions is similar, therefore they will be handled simultaneously in the next paragraphs.
The source product refers to the file containing the metadata of the satellite image, as provided when downloading and unzippping the files:
- Landsat-8: *_MTL.txt file
- Sentinel-2 : S2*.xml file found in the *.SAFE folder
Target product refers to the name of the output product as it will appear in SNAP. You can also choose tosave the output file as a BEAM-DIMAP format, and to open the result immediately in SNAP or not.
Table 1 shows the default values for Landsat-8 and Sentinel-2 .
Table 1: Default parameter settings for iCOR atmospheric correction
ID |
Parameter |
Landsat-8 |
Sentinel-2 |
1 |
Target product file |
… |
… |
2 |
Working Folder Location |
C:\Temp |
C:\Temp |
3 |
Keep Intermediate Files |
FALSE |
FALSE |
4.1 |
Watermask Band Id |
B05 |
B08 |
4.2 |
Watermask Threshold |
0.05 |
0.05 |
5.1 |
Cloud Masking Average Threshold |
0.2 |
0.19 |
5.2 |
Cloud Low Band Identifier |
B01 |
B01 |
5.3 |
Cloud Mask Low Threshold |
0.15 |
0.25 |
5.4 |
Include Cirrus Band Cloud Mask |
TRUE |
TRUE |
5.5 |
Cloud Masking Cirrus Threshold |
0.005 |
0.01 |
6.1 |
Estimate Aerosol Optical Thickness |
TRUE |
TRUE |
6.2 |
Default AOT Override Value |
0.1 |
0.1 |
7 |
Default WaterVapor Override Value |
2 |
2 |
8.1 |
Apply Adjacency Correction |
FALSE |
FALSE |
8.2 |
Default Adjacency Window |
1 |
1 |
1.
Display execution output – When this box is checked, the different steps runs
through by iCOR are displayed.
2. Target product file – Directory where the output file will be stored. It is important to change this path to an existing directory, otherwise no output will be generated.
Comment: To deal with the different tiles within a Sentinel-2 image, the final output name for Sentinel-2 will be the name provided in the Target Product File followed by the full name of the tile.
Target product file = [target_name].tif
è Output files: [target_name][tile_name][resolution].tif
Example:
Target product file = C/TEMP/S2A_OPER_PRD_MSIL1C_*_processed.tif
Output files:
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile1]_*_10M.tif
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile1]_*_20M.tif
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile1]_*_60M.tif
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile2]_*_10M.tif
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile2]_*_20M.tif
- C/TEMP/S2A_OPER_PRD_MSIL1C_*_processedS2A_OPER_*_[Tile2]_*_60M.tif
- …
3. Keep Intermediate Files
This option enables the saving of intermediate products which are used in the atmospheric correction process. These products are:
· Water mask
· Cloud mask
· AOT
4. Water mask
The water mask is obtained using a threshold value on a single band.
4.1. Watermask Band Id – Defines band used to create a land/water mask.
4.2. Watermask Threshold – Defines the threshold value. If the value is below the threshold, the pixel is identified as a water pixel, otherwise it is a land pixel.
5. Cloud mask
The cloud mask is created using multiple threshold levels. A pixel is identified as a cloud if it fulfils following requirements:
TOAreflectance Cloud Low BAND ID > ThresholdCloud Mask Low AND
Average_TOAreflectanceVNIRbands > ThresholdCloud Mask Average
OR if the pixel contains cirrus clouds:
TOAreflectancecirrusband > ThresholdCloud Mask Cirrus
As such, the parameters stand for
5.1. Cloud Mask Low Threshold – Threshold value for the cloud low ID band. If this value is exceeded, one of the requirements of defining a cloud pixel is fulfilled.
5.2. Cloud Low Band Identifier – Band ID used to check the Cloud Mask Low Threshold value.
5.3. Cloud Mask Average Threshold – Threshold value for the average reflectance in the VIS region (0.4 – 0.8 micron, Bands B01 – B04 for Landsat-8 and Bands B01 – B08A for Sentinel-2). If this value is exceeded, one of the requirements of defining a cloud pixel is fulfilled.
5.4. Include Cirrus Band Cloud Mask – If true, iCOR includes the cirrus band to optimise the cloud mask.
5.5. Cloud Masking Cirrus Threshold – This threshold defines a pixel as cirrus cloud when the threshold value is exceeded.
6. Aerosol Optical Thickness
In iCOR an adapted version of the land based AOT retrieval technique described by Guanter et al. (2005b) is implemented. This AOT retrieval algorithm makes use of the spectral variability of the land pixels within the image.
6.1. Estimate Aerosol Optical Thickness – Checking this box enables the image based AOT retrieval
6.2. Default AOT Override Value – If you know the AOT value, you can choose to disable the Estimate Aerosol Optical Thickness retrieval and insert the value.
7. Default WaterVapor Override Value – If you know the Columnar Water Vapour content of the atmosphere, you can adapt this value. By default this value is set at 2.
8. Adjacency correction
The spectra of a target pixel can be contaminated by light originating from surrounding pixels and atmospherically scattered into the target-sensor path, called adjacency effect (R. Richter et al., 2006; Vermote et al., 1997). As a consequence, the overall apparent surface contrast decreases as bright pixels will be darkened and dark pixels brightened. iCOR contains a module which can correct for these artefacts. For land, adjacency corrections will be applied over a fixed range, while over water SIMEC is implemented (SIMilarity Environmental Correction (SIMEC), Sterckx et al., 2014).
8.1. Apply Adjacency Correction – If true the SIMEC adjacency correction will be applied over water bodies.
8.2. Default Adjacency Window – Over land, instead of SIMEC, adjacency effects will be corrected using a fixed range. The extent of this range is given by the value defined in this default adjacency window. The units are number of pixels (N). The weighted average within the NxN box is considered for the adjacency correction. When N is set to 1, no adjacency correction is applied over land.
The generated output contains Bottom-Of-Atmospheric (BOA) reflectance, which are above water water-leaving-reflectance.
For Landsat-8 one output file is created with a spatial resolution of 30 m.
For Sentinel-2, three output files are created for each tile:
- *_60M.tif – containing all spectral information at 60 m spatial resolution
- *_20M.tif – only bands with original spatial resolution of 20 m
- *_10M.tif – only bands with original spatial resolution of 10 m
You can now play with the data in SNAP to improve the visualisation: Select the image of interest in the Product explorer, go to the Window tab and select Open RGB Image window. A new window will pop-up where you can select the appropriate band settings ( A good choice for Landsat-8 and Sentinel-2 is: Red – band_4, Green – band_3, Blue – band_2).
In first instance you might get an image with only black and white colours, since iCOR sets invalid pixels at max float.
To change this, go to the Colour Manipulation window (View à Tools Windows à Colour Manipulation) and change the range of values for the different colour bands (red, green and blue). Double click on the value at the end of the colour bar (highlighted in red in the following figure) and change to more appropriate values (eg. 0 – 0.5). Press enter.
The masks generated in iCOR are solely developed to optimize the atmospheric correction and do not guarantee optimal performance in different conditions. iCOR does not mask bad pixels, and it is advised to look at other sources if a proper mask is needed or wanted.
iCOR makes use of spectral diversity in land pixels to derive the AOT and to conduct the atmospheric corrections. As such, there are situations for which iCOR will not perform well, eg. deserts, open oceans (or tiles not including land pixels) or regions fully covered by snow.
iCOR is an computational intensive tool. Consequently, other programmes might run slow meanwhile and the required time needed to process one image, depending on the size and number of granules, can take a while. For example: one Sentinel-2 granule, without SIMEC adjacency correction, might take half an hour. With SIMEC, the whole process will run even slower.
iCOR failure can occur due to different reasons:
- Paths are not properly defined (See download and installation)
- Python 2.7 was not installed
- Not enough disk space available for processing
Intermediate files are stored into the temp processing folder, as well as a “config.log” file where all processing parameters are stored.
Example :
c:\users\[usenamer]\appData\Local\Temp\icor_3efxwh_proc\
When failure has occurred, useful information can be derived. When the ‘keep_intermediate’ option is selected, it is advisable to clean once and a while these temp folders.
The research leading to the development of the iCOR atmospheric correction tool has received funding from the Belgian Science policy through two Stereo projects under contract n° SR/00/003 (BELCOLOUR) and SR/00/104 (BELCOLOUR II), ESA-ESTEC under contract n° 4000110059/14/NL/GLC (LVF-IMPACT) and has been validated in the European Community's Seventh Framework Programme ([FP7/2007-2013]) under grant agreement n° 606865 (INFORM) and n° 606797 (HIGHROC).
The distribution of the iCOR software as a plugin in the SNAP toolbox received funding from the Belgian Science Policy under grant agreement n° SR/67/342 (INOPS-2).