Parameters

Tmart Class

Create a Tmart object that does radiative transfer modelling.

Arguments:

  • Surface – Surface object from the Surface module.

  • Atmosphere – Atmosphere object from the Atmosphere module.

  • shadow – True or False, whether to test if light is blocked by another surface at a collision.

  • VROOM – VROOM acceleration. 0: no acceleration. 1: all collisions are directed towards the sun.

Example usage:

my_tmart = tmart.Tmart(Surface = my_surface, Atmosphere= my_atm)

Atmosphere Class

class Atmosphere(atm_profile, aot550=0, aerosol_type='Maritime', n_layers=20, AEROSOL_SCALE_HEIGHT=2, no_absorption=False, specify_ot_rayleigh=-1, specify_abs=-1)

Bases: object

Create an Atmosphere object that is wavelength independent. I.e., a wavelength-dependent atmosphere is generated every time TMart is run.

Arguments:

  • atm_profile – AtmosProfile object from Py6S.

  • aot550 – AOT at 550nm.

  • aerosol_type – ‘BiomassBurning’, ‘Continental’, ‘Desert’, ‘Maritime’, ‘Stratospheric’ or ‘Urban’, as provided by 6S. Alternatively, a decimal between 0 and 1 indicating the ratio of ‘Maritime’ aerosol in a ‘Maritime’ and ‘Continental’ mixture.

  • wl – central wavelength in nm.

  • n_layers – Number of atmosphere layers to use. Default 20.

  • AEROSOL_SCALE_HEIGHT – Aerosol scale height in km. Default 2km.

  • no_absorption – Boolean, if yes -> remove all absorption.

  • specify_ot_rayleigh – Specify rayleigh optical thickness, only for testing.

  • specify_abs – Specifiy absorption optical thickness, only for testing.

Example usage:

from Py6S.Params.atmosprofile import AtmosProfile

# Atmophere profile comes from 6S
atm_profile = AtmosProfile.PredefinedType(AtmosProfile.MidlatitudeSummer) 
aerosol_type = 'Maritime' 
aot550 = 0.1
n_layers = 20
aerosol_scale_height = 2 # Unless you have a reason, don't change this

# Synthesize an atmosphere object    
my_atm = tmart.Atmosphere(atm_profile, aot550, aerosol_type, n_layers, aerosol_scale_height)

Surface Class

class SpectralSurface(land_cover)

Bases: object

Create an object to capture the spectral reflectance of surfaces when looping wavelengths. This can be used as input to reflectance in the Surface object.

Arguments:

  • land_cover – Text, currently support ‘soil’, ‘vegetation’, ‘water’ and ‘water_chl1’ ([chla]=1).

Example usage:

# Create object
water = tmart.SpectralSurface('water_chl1')

# Find spectral reflectance at 400nm
water.wl(400)

# Create a spectral surface in a numpy array 
wl = 400 # your variable in a loop
np.full((2, 2), water.wl(wl))
wl(wavelength)

Specify the wavelength of interest in nm and returns the reflectance of the surface.

class Surface(DEM, reflectance, isWater, cell_size, alignPixels=True)

Bases: object

Create an Surface object.

Arguments:

  • DEM – Numpy array, Digital Elevation Model, the elevation of pixels.

  • reflectance – Numpy array, reflectance of land or water-leaving reflectance of water, Lambertian.

  • isWater – Numpy array, which pixels are water pixels. 1 is water, 0 is land.

  • cell_size – The width and length of each pixel, in meters.

  • alignPixels – Boolean. If true: the southeast corner of the pixel will take the elevation in DEM. If false: the centre of the pixel will take the elevation in DEM.

Example usage:

image_DEM = np.array([[0,0],[0,0]]) # in meters
image_reflectance = np.array([[0.1,0.1],[0.1,0.1]]) # unitless     
image_isWater = np.array([[1,1],[1,1]]) # 1 is water, 0 is land
cell_size = 20_000 
my_surface = tmart.Surface(image_DEM,image_reflectance,image_isWater,cell_size)
set_background(bg_ref=None, bg_isWater=None, bg_elevation=None, bg_coords=None)

Set background information, 1 or 2 background surfaces can be set; If 2 surfaces: the first background is the one closer to [0,0]

Arguments:

  • bg_ref – A number or a list of two numbers. Reflectance of each background surface. Default average reflectance of the pixels.

  • bg_isWater – A number or a list of two numbers. If each of the background surface is water. Default land.

  • bg_elevation – A number. The elevation of the background surfaces. Default 0.

  • bg_coords – A list of two lists of two numbers. Two XY coordinates divide the two background surfaces. Default [[0,0],[1,1]].

Example usage:

my_surface.set_background(bg_ref        = [0.02,0.02], # background reflectance
                          bg_isWater    = [0,0], # if is water
                          bg_elevation  = 0, # elevation of both background
                          bg_coords     = [[0,0],[10,10]]) # a line dividing two background

calcref Function

calc_ref(df, n_photon=None, detail=False)

Analyze the results of T-Mart and calculate reflectances.

Arguments:

  • df – Results from T-Mart runs

  • n_photon – Specify the number of photons in the run when firing the photon upwards. If not specified, the number of unique pt_id will be used. This can lead to errors when photons were fired upwards because some photons will not have pt_id.

  • detail – Boolean. Differentiate Cox-Munk, whitecap, water-leaving and land contributions

Output:

  • A list of atmospheric intrinsic reflectance, direct reflectance, environmental reflectance and total reflectance.

Example usage:

R = tmart.calc_ref(results)
for k, v in R.items():
    print(k, '     ' , v)

surface_rho.calculate Function

calculate(wl, viewing_zenith, solar_zenith, relative_azimuth, aot550=0.05, wind_speed=3, n_photon=100000, atm_profile=None, aerosol_type=None, spectral_surface=None, as_pandas_df=True)

Calculate sea-surface reflectance factor. See Wu et al. 2023, Lee et al. 2010, or Mobley 1999 for full description.

Arguments:

  • wl – central wavelength in nm, or a list for iteration: [starting_wavelength, ending wavelength, interval].

  • viewing_zenith – viewing zenith angle in degrees.

  • solar_zenith – solar zenith angle in degrees.

  • relative_azimuth – relative azimuth angle in degrees.

  • aot550 – aerosol optical thickness at 550nm.

  • wind_speed – wind speed in m/s.

  • n_photon – number of photons in each T-Mart run. 100_000 is recommended, 10_000 can be used to view quick results.

  • atm_profile – AtmosProfile object from Py6S. Default ‘MidlatitudeSummer’

  • aerosol_type – ‘BiomassBurning’, ‘Continental’, ‘Desert’, ‘Maritime’, ‘Stratospheric’ or ‘Urban’, as provided by 6S. Default ‘Maritime’

  • spectral_surface – a SpectralSurface object in T-Mart. Default ‘water_chl1’

  • as_pandas_df – If true, return a pandas dataframe, else return a dictionary

Example usage:

tmart.surface_r.calculate(wl=800, viewing_zenith=40, solar_zenith=30, relative_azimuth=135)

AEC.run Function

run(file, username, password, overwrite=False, AOT='MERRA2', n_photon=100000, AOT_offset=0.0, n_jobs=100, mask_SWIR_threshold=None)

Run adjacency-effect correction on satellite files. See ‘Introduction - Adjacency-Effect Correction’ for detailed instructions.

Arguments:

  • file – String. Path to satellite files. For L8/S2: provide path to the folder. For PRISMA: provide ACOLITE L1R file. SAFE.zip for S2 is supported: when doing so it is recommended to set overwrite as True to save space.

  • username – String. Username of EarthData account.

  • password – String. Password of EarthData account.

  • overwrite – Boolean. If overwrite the existing files. The default is False and it creates a folder in the same directory that starts with AEC in the name

  • AOT – ‘MERRA2’: use ancillary data (default). Float: AOT at 550nm. ‘NIR’: calculate in T-Mart by finding dark pixels in NIR when considering the AE.

  • n_photon – Int. Number of photons in each T-Mart run, 100_000 is recommended for accurate results.

  • AOT_offset – Float. Value added to AOT at 550nm. If resulted AOT is negative, it will be corrected to 0.

  • n_jobs – Int. Number of jobs in Python multiprocessing. One CPU core processes one job at a time. n_photon is evenly distributed across the jobs.

  • mask_SWIR_threshold – Float. Reflectance threshold in a SWIR band used to mask non-water pixels in the processing. If specified, this overwrites the value in config.txt.

Example usage:

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

# T-Mart uses multiprocessing, which needs to be wrapped in 'if __name__ == "__main__":' for Windows users
if __name__ == "__main__":
    tmart.AEC.run(file, username, password)