i.sentinel.preproc is a module
for the preprocessing of Sentinel-2 images (Level-1C Single Tile product) which
wraps the import, the atmospheric and the topographic correction using respectively
i.atcorr and i.topo.corr.
It works both with Sentinel-2A and 2B images.
The aim is to provide a simplified module which allows importing images, which area downloaded using i.sentinel.download or any other sources, and performing the atmospheric correction avoiding users to provide all the required input parameters manually. In fact, regarding the atmospheric correction performed with i.atcorr one of the most challenging steps, especially for unexperienced users, is the compiling of the control file with all the required parameters to parametrize the 6S (Second Simulation of Satellite Signal in the Solar Spectrum) model on which i.atcorr is based.
To run i.atcorr, users have to provide the so-called control
file in which all the parameters (geometrical conditions, date, time, longitude
and latitude of the center of the scene, atmospheric model, aerosol model,
visibility or Aerosol Optical Depth -AOD- value, mean elevation target and
bands number) have to be specified with precise syntax rules and codes.
i.sentinel.preproc retrieves as many parameters as possible from the metadata file (e.g. Geometrical conditions, data and time and bands number), longitude and latitude are automatically computed from the computational region while others like the mean target elevation above sea level from the input digital elevation model (DEM). Only a few parameters have to be provided by users who can choose the proper option from a drop-down menu thus avoiding to enter the corresponding code. In any case, i.sentinel.preproc writes a temporary control file, changing it according to the band number, following the syntax rules and codes of i.atcorr and then it runs i.atcorr for all bands. Using the c flag i.sentinel.preproc is able to perform also the topographic correction using i.topo.corr creating the needed information as the illumination model based on the elevation model provided by the user.
When all bands have been processed by the integrated version of i.atcorr, an histogram equalization grayscale color scheme is applied.
If the -t flag is set, a text file ready to be used as input for i.sentinel.mask will be created. In this case a name for the output text file has to be specified.
NOTE: as for i.atcorr, current region settings are ignored. The region is temporary set to maximum image extent and restored at the end of the process.
Important: i.sentinel.preproc requires all the bands of a
Sentinel-2 images. If the module is used only for the atmospheric correction,
all bands from *_B01 to *_B12 must be imported.
Moreover, the original bands name has to be kept unchanged (e.g if the original name is T17SPV_20180315T160021_B02 the imported raster map in the GIS DATABSE must be named T17SPV_20180315T160021_B02).
Important: i.sentinel.preproc allows the import of one image at a time because the input .SAFE folder is also used to automatically identify the corresponding metadata file that is used during the atmospheric correction.
The import can be skipped using the -i flag. Note that even if the import is skipped the input .SAFE folder must be specified to automatically retrieve the metadata file.
i.sentinel.preproc allows performing atmospheric correction of all bands of a Sentinel-2 scene with a single process using i.atcorr. Unlike i.atcorr, it writes the control file changing it according to the band number. The only required inputs are:
Below an example of the control file, taken from the i.atcorr manual page, of a Sentinel-2A image:
25 - geometrical conditions = Sentinel-2A 5 4 19.737 -78.727 35.748 - month day hh.ddd longitude latitude ("hh.ddd" is in decimal hours GMT) 2 - atmospheric model = midlatitude summer 1 - aerosols model = continental 0 - visibility [km] (aerosol model concentration) 0.07 - AOD at 550nm -0.124 - mean target elevation above sea level [km] -1000 - sensor height (here, sensor on board a satellite) 167 - sensor band = Sentinel2A Blue band B2
The geometrical condition of the satellite are read from the metadata file and converted to the corresponding i.atcorr code, 25 for Sentinel-2A mission and 26 for Sentinel-2B.
Date (month and day) and time are read from the metadata file. The date (with the format YYYY-MM-DDTHH:MM:SSZ) is converted in a standard format and only the month and the day are selected and added to the control file.
already in Greenwich Mean Time (GMT), as i.atcorr requires, and it's
automatically converted to decimal hours.
Longitude and latitude are computed from the computational region and converted to WGS84 decimal coordinates.
Only some options are available:
The default option is Automatic which consists in the automatic identification of the proper atmospheric model for the input image. The Automatic option reads the latitude of the center of the computational region and uses it to choose between Midlatitude (15.00 > lat <= 45.00), Tropical (-15.00 > lat <= 15.00) and Subarctic (45.00 > lat <= 60.00) for Northern Hemisphere (obviously it also works for the Southern Hemisphere). Then, the month from the acquisition date is used to distinguish summer or winter in case of Midlatitude or Subarctic model. Once the proper atmospheric model is identified, it is converted to the corresponding code and added to the control file.
Note that this is a simplified and standardized method to identify the atmospheric model. Obviously, it is possible to choose other options from those available.
Also in this case, only some options are available and users have to select the desired one from the drop-down menu, then it is converted to the corresponding code and added to the control file.
By default, i.sentinel.preproc uses the input visibility map to estimate a
visibility value to be added in the control file. If no visibility map is
available for the processed scene, it is possible to use an estimated Aerosol
Optical Depth (AOD) value checking the -a flag.
If the -a flag is checked and a visibility map is provided, the visibility will be ignored and no mean visibility value will be computed and added to the control file. Whereas, if the -a flag isn't checked and an AOD value is provided it will be ignored and not added to the control file.
In the same way, if the -a flag is checked and a visibility map is provided it will be excluded from atmospheric correction process.
The AOD value can be specified by users (e.g. aod_value=0.07) or
automatically retrieved from an AERONET file to be given as input instead of
the AOD value.
i.sentinel.preproc reads the AERONET file, identify the closest available date to the scene date and compute AOD at 550nm using the closest upper and lower wavelength to 550 (e.g. 500nm and 675nm) and applying the Angstrom coefficient.
The type of AERONET file is a Combined file for All Points (Level 1.5 or
To download this kind of file:
Then, giving this file as input (e.g. aeronet_file=your_path/*.dubovik), the AOD at 550nm will be automatically computed and added to the control file.
NOTE: as in i.atcorr manual explained, if an AOD value is provided a value 0 for the visibility has to be entered with the AOD value in the following line. Obviously, i.sentinel.preproc takes into account this syntax rule and automatically adds a 0 value for visibility (or -1 if AOD=0) if an AOD value is provided (through both aod_value and aeronet_file).
Mean target elevation above sea level is automatically estimated from the input digital elevation model. According to the rules for writing the contol file of i.atcorr, the mean elevation value is added as a negative value and converted in kilometers (e.g. if mean=121 in the control file it will be written in [-km], i.e., -0.121).
Since the sensor is on board a satellite, the sensor height is automatically set to -1000.
The number of the band changes automatically according to the band that is processed at that moment. The module reads the name of the band and converts it into the corresponding code.
The example illustrates how to run i.sentinel.preproc for a Sentinel-2A image
(S2A_MSIL1C_20180315T160021_N0206_R097_T17SPV_20180315T194425.SAFE) in the
North Carolina location.
The AERONET file has been downloaded from the EPA-Res_Triangle_Pk station.
i.sentinel.preproc -a -t input_dir=/path/S2A_MSIL1C_20180315T160021_N0206_R097_T17SPV_20180315T194425.SAFE \ elevation=elevation atmospheric_model=Automatic aerosol_model="Continental model" \ aeronet_file=path/180301_180331_EPA-Res_Triangle_Pk.dubovik suffix=cor text_file=/path/input_cloud_mask.txt
Here is the control file automatically written for Band 02 of the input scene
25 5 4 19.74 -78.728 35.749 3 -The Automatic option identified the Midlatitude Winter as the proper model for the scene 1 0 -The visibility is set to 0 with AOD in the following line 0.18867992317 -AOD computed from the input AERONET file -0.122 -1000 167
Here is the output text file ready to be used as input for i.sentinel.mask (-t flag)
blue=T17SPV_20180315T160021_B02_cor green=T17SPV_20180315T160021_B03_cor red=T17SPV_20180315T160021_B04_cor swir11=T17SPV_20180315T160021_B11_cor nir=T17SPV_20180315T160021_B08_cor swir12=T17SPV_20180315T160021_B12_cor nir8a=T17SPV_20180315T160021_B8A_cor
Last changed: $Date$
© 2003-2019 GRASS Development Team, GRASS GIS 7.8.1dev Reference Manual