User Guide

This guide covers the main processing workflows and concepts in ACOLITE.

Processing Pipeline Overview

ACOLITE processes satellite imagery through three levels:

Raw Data → L1R (TOA Reflectance) → L2R (Surface Reflectance) → L2W (Water Products)

Level 1R (L1R)

Converts sensor-specific raw data to standardized TOA reflectance:

  • Reads raw radiance/reflectance data

  • Applies radiometric calibration

  • Generates rhot_* (TOA reflectance) datasets

  • Stores geometry (sun/view angles) and geolocation

Level 2R (L2R)

Applies atmospheric correction using the DSF algorithm:

  • Estimates aerosol optical thickness (AOT)

  • Removes atmospheric path radiance

  • Corrects for gas absorption (ozone, water vapor)

  • Generates rhos_* (surface reflectance) datasets

Level 2W (L2W)

Derives water quality parameters:

  • Computes bio-optical parameters (chlorophyll, turbidity, etc.)

  • Applies quality masking

  • Generates derived product datasets

Dark Spectrum Fitting (DSF)

The DSF algorithm is ACOLITE’s core atmospheric correction method. It works by:

  1. Identifying dark pixels in the scene (typically water)

  2. Fitting the dark spectrum to aerosol models

  3. Estimating AOT from the fit

  4. Extrapolating atmospheric correction to all pixels

DSF Modes

dsf_aot_estimate controls how AOT is estimated:

  • tiled (default) - Estimate AOT in tiles, interpolate spatially

  • fixed - Use a fixed AOT value (dsf_fixed_aot)

  • segmented - Segment scene and estimate per segment

Tiled Processing

For large scenes, DSF processes in tiles:

dsf_tile_dimensions=100,100
dsf_tile_smoothing=True
dsf_tile_interp_method=linear

Fixed AOT

When atmospheric conditions are known:

dsf_aot_estimate=fixed
dsf_fixed_aot=0.1
dsf_fixed_lut=ACOLITE-LUT-202110-MOD2

Region Selection

ACOLITE offers multiple ways to subset scenes:

Bounding Box

Specify South, West, North, East coordinates:

limit=51.0,2.5,51.5,3.5

Polygon

Use a GeoJSON, shapefile, or WKT string:

polygon=/path/to/region.geojson
polygon_limit=True
polygon_clip=False

Station Extraction

Extract a box around a point:

station_lon=3.05
station_lat=51.25
station_box_size=10
station_box_units=km

Buffering

Add a buffer around the region:

limit_buffer=5
limit_buffer_units=km

Ancillary Data

ACOLITE can automatically retrieve atmospheric ancillary data:

ancillary_data=True
ancillary_type=GMAO_MERRA2_MET

Data Sources

  • GMAO_MERRA2_MET - MERRA-2 reanalysis (default)

  • GMAO_FP_MET - GMAO Forward Processing

  • O3_AURAOMI_24h - Aura OMI ozone

Default Values

When ancillary data is unavailable:

uoz_default=0.3
uwv_default=1.5
pressure_default=1013.25
wind_default=2

DEM and Pressure

Use a Digital Elevation Model for pressure correction:

dem_pressure=True
dem_source=copernicus30

DEM Sources

  • copernicus30 - Copernicus 30m DEM (default, auto-download)

  • copernicus90 - Copernicus 90m DEM

  • srtm - SRTM 30m (requires EarthData account)

Shadow Masking

Mask DEM-derived shadows:

dem_shadow_mask=True
dem_shadow_mask_extend=True

Sun Glint Correction

ACOLITE offers multiple approaches to handle sun glint:

Interface Reflectance

Model air-water interface reflection:

dsf_interface_reflectance=True
dsf_interface_option=default

Residual Glint Correction

Remove remaining glint in SWIR bands:

dsf_residual_glint_correction=True
dsf_residual_glint_correction_method=default
glint_mask_rhos_threshold=0.05

Adjacency Correction (RAdCor)

Physics-based correction for adjacency effects near bright targets:

adjacency_correction=True
adjacency_correction_method=radcor
radcor_kernel_radius=5.0

RAdCor is particularly important for:

  • Coastal waters near beaches

  • Inland waters surrounded by vegetation

  • Small water bodies

Masking

ACOLITE applies several masks to L2W products:

Land/Water Masking

l2w_mask=True
l2w_mask_wave=1600
l2w_mask_threshold=0.0215

Negative Reflectance

l2w_mask_negative_rhow=True
l2w_mask_negative_wave_range=400,900

Cirrus

l2w_mask_cirrus=True
l2w_mask_cirrus_threshold=0.005

High TOA

l2w_mask_high_toa=True
l2w_mask_high_toa_threshold=0.3

Output Options

NetCDF Options

netcdf_projection=True
netcdf_compression=True
netcdf_compression_level=4

GeoTIFF Export

l1r_export_geotiff=False
l2r_export_geotiff=True
l2w_export_geotiff=True
export_cloud_optimized_geotiff=True

RGB Images

rgb_rhot=True
rgb_rhos=True
rgb_rhow=False

## Customize RGB bands
rgb_red_wl=650
rgb_green_wl=560
rgb_blue_wl=480

## Scaling
rgb_min=0.0,0.0,0.0
rgb_max=0.15,0.15,0.15

Map Output

map_l2w=True
map_title=True
map_colorbar=True
map_scalebar=True

Reprojection

Reproject outputs to a specific coordinate system:

output_projection=True
output_projection_epsg=32631
output_projection_resolution=10
output_projection_resampling_method=bilinear

Thermal Processing (TACT)

Process thermal bands to surface temperature (Landsat only):

tact_run=True
tact_profile_source=era5
tact_emissivity=water

TACT requires libRadtran to be installed. See Installation.

Sensor-Specific Settings

Sentinel-2

s2_target_res=10
geometry_type=grids_footprint
geometry_res=60

Sentinel-3 OLCI

smile_correction=True
use_supplied_ancillary=True

VIIRS

viirs_option=img+mod
viirs_scanline_projection=True

Landsat

landsat_qa_output=False

See Supported Sensors for more sensor-specific information.

Processing Examples

Sentinel-2 Coastal Water

inputfile=S2A_MSIL1C_*.zip
output=/data/output

## Region of interest
limit=51.0,2.5,51.5,3.5

## Atmospheric correction
atmospheric_correction=True
dsf_aot_estimate=tiled
ancillary_data=True
dem_pressure=True

## Water products
l2w_parameters=chl_oc3,t_nechad2016,spm_nechad2016

## Masking
l2w_mask=True
l2w_mask_water_parameters=True

## Output
rgb_rhos=True
l2w_export_geotiff=True
map_l2w=True

Landsat Thermal (TACT)

inputfile=LC08_L1TP_*.tar.gz
output=/data/output

## Enable thermal processing
tact_run=True
tact_profile_source=era5
tact_emissivity=water

## Standard atmospheric correction
atmospheric_correction=True
ancillary_data=True

Hyperspectral (PRISMA)

inputfile=PRS_L1_*.he5
output=/data/output

atmospheric_correction=True
dsf_aot_estimate=tiled

## Hyperspectral-specific
prisma_rhot_per_pixel_sza=True

## Water products
l2w_parameters=chl_oc3

Troubleshooting

No atmospheric correction applied

Check that atmospheric_correction=True and verify the scene contains valid dark pixels.

Missing water products

Ensure l2w_parameters is set and the mask settings are not too aggressive.

Memory errors

For large scenes, process in tiles or use region subsetting:

dsf_tile_dimensions=50,50
l2w_data_in_memory=False

Noisy results

Try smoothing the AOT retrieval:

dsf_smooth_aot=True
dsf_smooth_box=10,10