Instruction - Adjacency-Effect Correction

Mininum input

The AEC.run function is used to perform adjacency-effect correction (AEC) in T-Mart. Correction is performed directly on level-1 products, and the output is adjacency-effect-free top-of-atmosphere products in the same format as the input level-1 products, therefore this workflow can be followed by any amtospheric correction tools. Currently it supports Sentinel-2 MSI, Landsat 8/9 OLI/OLI-2 and PRISMA imagery.

NASA EarthData credentials are needed to retrieve ozone, water vapour, and aerosol optical thickness and composition for accurate AEC. You may need to approve OB.DAAC Data Access in your EarthData account: click Authorized Apps under the Applications tab - click the APPROVE MORE APPLICATIONS button near the bottom, and authorize OB.DAAC Data Access.

Minimum input to the AEC.run function includes a path to satellite files and EarthData credentials. See AEC.run Function for all the arguments.

import tmart
file = 'user/test/S2A_MSIL1C_20160812T143752_N0204_R096_T20MKB_20160812T143749.SAFE'
username = 'abcdef'
password = '123456'

# T-Mart uses multiprocessing, which must be wrapped in 'if __name__ == "__main__":' for Windows users. This is optional for Unix-based systems
if __name__ == "__main__":
    tmart.AEC.run(file, username, password)

Overwrite existing files

By default, the processing creates a copy of the original satellite files in the same directory, in a new folder named ‘AEC_*’. To overwrite the eixsting files, add ‘overwrite=True’ to the arguments:

tmart.AEC.run(file, username, password, overwrite=True)

Ancillary and log files

During the AEC process, a number of files are generated:

  • tmart_log_*.txt: detailed processing information, as printed in the Python console.

  • tmart_atm_info_*.txt: atmosphere and aerosol information used in the processing. This includes aerosol type, angstrom exponent, single scattering albedo, AOT at 550 nm, total column ozone, and total precipitable water vapour.

  • tmart_ancillary/*.nc: GMAO MERRA2 ancillary files from the NASA Ocean Biology Processing Group.

  • AEC_completed_*.txt: a record of bands that have been corrected for the adjacency effect.

  • tmart_preview.png: an image preview of pixels identified as water (only run when AE_land is False).

AEC configuration

A TXT configuration file is stored in the tmart package folder. Its path is printed in the Python console and the log file. Brief descriptions are given in the file. Most of the configuration settings are tuned for best performance.

Identify water extent

By default, T-Mart identifies water pixels and only modify their values, leaving land pixel values unchanged to facilitate the existing calibration of atmospheric correction processors that extract information from land pixels.

When water_detection_method = NDWI in config.txt, water identification is based on the normalized difference between the green and NIR bands. The green and NIR bands are configurable in config.txt, and can be swapped to use any normalized difference. Pixels with NDWI values lower than mask_NDWI_threshold are treated as non-water, and the default value is 0. Adjust this threshold if needed based on the scene’s water/land separation.

When water_detection_method = SWIR, water pixels are identified as the SWIR band reflectance lower than the threshold mask_SWIR_threshold (default value: 0.03). Increase this value if a significant number of water pixels are falsely masked as land.

Both mask_SWIR_threshold or mask_NDWI_threshold can be adjusted in config.txt. Modifying mask_SWIR_threshold in the AEC.run function overwrites the value in config.txt. Alternatively, setting AE_land to True enables AEC across the entire scene.

Additional arguments

AOT and n_photon can be specified manually. AOT is the aerosol optical thickness at 550 nm, you can specify it if you are certain about its value or simply to test the impact of using different values. n_photon is the number of photons used in each T-Mart run; the default value of 100,000 is recommended for accurate results. It can be reduced to 10,000 for quicker computation.

tmart.AEC.run(file, username, password, overwrite=True, AOT = 0.05, n_photon = 10_000)

User-input atmospheric information

Alternative to retrieving atmospheric parameters from NASA EarthData, users may provide a custom atmospheric information file via the atm_info_file argument.

When atm_info_file is supplied, the parameters are read directly from the text file and the EarthData credentials (username, password) are no longer required. You may copy an existing tmart_atm_info_*.txt file generated by a previous run and edit the values manually.

How parameters in the file are used:

  • Aerosol mixing ratio: The ratio of maritime aerosol in the maritime/continental mixture is always read directly from the file and used in the simulation.

  • Aerosol Angstrom exponent and single-scattering albedo: These two are ignored when an input file is provided. They are only used internally to derive the aerosol mixing ratio when EarthData is queried. If a file is supplied, the ratio in the file is used as-is.

  • AOT: The AOT value in the file is used only when AOT="MERRA2". Otherwise, the value specified by AOT=<float> is used.

  • Ozone and water vapour: Total column ozone and water vapour must be provided in the file and are always read from it when atm_info_file is specified.

Example content:

Ratio of maritime aerosol in maritime/continental mixture: 0.32149729438202934
Aerosol angstrom exponent: 1.1694952659402162
Aerosol single scattering albedo: 0.9274053986128525
AOT550: 0.07811043870567436
Total column ozone: 264.1938889212531 DU
Total precipitable water vapour: 19.350930129831248 kg m-2

Example usage without credentials:

tmart.AEC.run(file, atm_info_file="tmart_atm_info_example.txt")

This allows fully offline processing with user control over the atmospheric state.

Assumptions in AEC

A few assumptions are made in the processing, violations can lead to various degrees of errors in the output AE-free product:

  • Isotropic/Lambertian surface

  • Vertically stratified but horizontally homogeneous atmospheric molecules and aerosols across the scene

  • Flat surface or lack of topography

See AEC.run Function for all the arguments.

PRISMA image processing

T-Mart supports AE correction for ACOLITE-generated L1R PRISMA files. The modified L1R files from T-Mart can then be reprocessed in ACOLITE for atmospheric correction.

Video tutorials