API Reference

This section documents the main ACOLITE Python API for programmatic use.

Core Processing Functions

acolite_run

acolite.acolite.acolite_run(settings, inputfile=None, output=None)

Orchestrates the full L1R → L2R → L2W processing pipeline.

Parameters:

settings (str or dict): Path to settings file or settings dictionary
inputfile (str, optional): Input file path (overrides settings)
output (str, optional): Output directory (overrides settings)

Returns:

List of output files

Example:

import acolite as ac

# Using settings file
ac.acolite.acolite_run(settings='settings.txt')

# Using settings dict
settings = {
    'inputfile': '/data/S2A_MSIL1C_*.zip',
    'output': '/data/output',
    'l2w_parameters': 'chl_oc3,t_nechad2016'
}
ac.acolite.acolite_run(settings)

acolite_l1r

acolite.acolite.acolite_l1r(bundle, input_type=None)

Converts raw satellite data to Level-1R TOA reflectance.

Parameters:

bundle (str): Path to input data bundle
input_type (str, optional): Force input type detection

Returns:

List of L1R NetCDF file paths

Example:

l1r_files = ac.acolite.acolite_l1r('/data/S2A_MSIL1C_*.zip')

acolite_l2r

acolite.acolite.acolite_l2r(gem, output=None, sub=None, settings=None,
                            output_file=True, target_file=None, return_gem=False)

Applies atmospheric correction to produce surface reflectance.

Parameters:

gem: GEM object or L1R file path
output (str, optional): Output directory
sub (tuple, optional): Subset indices
settings (dict, optional): Processing settings
output_file (bool): Write output file
target_file (str, optional): Target file path
return_gem (bool): Return GEM object instead of file path

Returns:

L2R NetCDF file path or GEM object

Example:

gem = ac.gem.read('/data/scene_L1R.nc')
l2r_file = ac.acolite.acolite_l2r(gem, output='/data/output')

acolite_l2w

acolite.acolite.acolite_l2w(gem, output=None, settings=None,
                            target_file=None, load_data=True, new=True)

Derives water quality parameters from surface reflectance.

Parameters:

gem: GEM object or L2R file path
output (str, optional): Output directory
settings (dict, optional): Processing settings (must include l2w_parameters)
target_file (str, optional): Target file path
load_data (bool): Load data into memory
new (bool): Create new output file

Returns:

L2W NetCDF file path

Example:

settings = {'l2w_parameters': 'chl_oc3,t_nechad2016'}
l2w_file = ac.acolite.acolite_l2w(gem, settings=settings)

GEM Class

The GEM (Generic Extracted Miniscene) class is the core data container for ACOLITE.

Creating/Reading GEM Objects

acolite.gem.gem(ncf)
acolite.gem.read(ncf, sub=None, skip_datasets=[], load_data=True)

Parameters:

ncf (str): Path to NetCDF file
sub (tuple, optional): Subset indices (row_start, row_end, col_start, col_end)
skip_datasets (list): Datasets to skip loading
load_data (bool): Load data into memory

Example:

# Read full file
gem = ac.gem.read('/data/scene_L2R.nc')

# Read with subset
gem = ac.gem.read('/data/scene_L2R.nc', sub=(100, 200, 100, 200))

GEM Attributes

gem.file          # NetCDF file path
gem.gatts         # Global attributes dictionary
gem.datasets      # List of available dataset names
gem.data_mem      # In-memory data storage
gem.nc            # NetCDF file handle

GEM Methods

data()

gem.data(ds, attributes=False, store=False, use_stored=True, sub=None, mask=True)

Read a dataset from the GEM object.

Parameters:

ds (str): Dataset name (e.g., ‘rhos_560’, ‘lat’, ‘lon’)
attributes (bool): Return attributes with data
store (bool): Store data in memory
use_stored (bool): Use stored data if available
sub (tuple): Subset indices
mask (bool): Apply masking

Returns:

numpy array or (array, attributes) tuple

Example:

# Read surface reflectance at 560nm
rhos_560 = gem.data('rhos_560')

# Read with attributes
data, atts = gem.data('rhos_560', attributes=True)

atts()

gem.atts(ds)

Get attributes for a dataset.

write_ds()

gem.write_ds(ds, data, atts=None)

Write a dataset to the GEM file.

Writing GEM Files

acolite.gem.write(gemfile, gem, verbosity=0)

Write a GEM object to file.

Atmospheric Correction Module

Gas Transmittance

acolite.ac.gas_transmittance(sza, vza, pressure=1013, waves=None,
                              uoz=0.3, uwv=1.5, ...)

Calculate gas transmittance for atmospheric gases.

Parameters:

sza (float): Sun zenith angle (degrees)
vza (float): View zenith angle (degrees)
pressure (float): Atmospheric pressure (hPa)
waves (list): Wavelengths (nm)
uoz (float): Ozone concentration (atm-cm)
uwv (float): Water vapor (g/cm²)

Rayleigh Calculations

acolite.ac.ray_tau(wl, Patm=1013.25)

Calculate Rayleigh optical thickness.

acolite.ac.ray_tr(wl, theta_0, theta_v, Patm=1013.25)

Calculate Rayleigh transmittance.

acolite.ac.ray_refl(wl, theta_0, theta_v, phi_0, phi_v, Patm=1013.25, ...)

Calculate Rayleigh reflectance.

AOT Optimization

acolite.ac.optimise_aot_homogeneous(gem, quiet=True, settings=None, ...)

Optimize AOT for homogeneous atmosphere assumption.

Output Module

NetCDF Operations

acolite.output.nc_write(nc_file, ds_dict, ...)

Write datasets to NetCDF file.

GeoTIFF Export

acolite.output.nc_to_geotiff(nc_file, ds=None, ...)

Export NetCDF datasets to GeoTIFF.

acolite.output.nc_to_geotiff_rgb(nc_file, ...)

Export RGB composite as GeoTIFF.

Reprojection

acolite.output.project_acolite_netcdf(input_file, ...)
acolite.output.reproject_acolite_netcdf(input_file, ...)

Reproject ACOLITE NetCDF outputs.

Shared Utilities

File I/O

acolite.shared.nc_read(ncf, ds)        # Read NetCDF dataset
acolite.shared.nc_write(ncf, ds, data) # Write NetCDF dataset
acolite.shared.rsr_read(rsr_file)      # Read RSR file
acolite.shared.rsr_dict(sensor)        # Get RSR dictionary

Projection Utilities

acolite.shared.projection_sub(...)     # Subset projection
acolite.shared.projection_setup(...)   # Setup projection
acolite.shared.utm_epsg(lon, lat)      # Get UTM EPSG code

Region/Geometry

acolite.shared.polygon_crop(data, polygon)  # Crop to polygon
acolite.shared.polygon_limit(polygon)       # Get polygon bounds
acolite.shared.distance_se(lat1, lon1, lat2, lon2)  # Distance calculation

Data Processing

acolite.shared.fillnan(data)           # Fill NaN values
acolite.shared.datascl(data, ...)      # Scale data
acolite.shared.closest_idx(arr, val)   # Find closest index

Global Objects

ACOLITE maintains several global configuration objects:

import acolite as ac

ac.config          # Configuration dictionary
ac.settings        # Settings: {'defaults': {}, 'run': {}, 'user': {}}
ac.param           # Parameter info: {'scaling': {}, 'attributes': {}}
ac.version         # Version string
ac.code_path       # Installation path

Example Workflows

Full Processing Pipeline

import acolite as ac

# Configure settings
settings = {
    'inputfile': '/data/S2A_MSIL1C_*.zip',
    'output': '/data/output',
    'limit': [51.0, 2.5, 51.5, 3.5],  # S, W, N, E
    'l2w_parameters': 'chl_oc3,t_nechad2016,spm_nechad2016',
    'rgb_rhos': True,
    'l2w_export_geotiff': True
}

# Run full pipeline
output_files = ac.acolite.acolite_run(settings)

Step-by-Step Processing

import acolite as ac

# Step 1: Convert to L1R
l1r_files = ac.acolite.acolite_l1r('/data/input.zip')

# Step 2: Read L1R and apply AC
gem = ac.gem.read(l1r_files[0])
l2r_file = ac.acolite.acolite_l2r(gem, output='/data/output')

# Step 3: Compute water products
gem = ac.gem.read(l2r_file)
settings = {'l2w_parameters': 'chl_oc3'}
l2w_file = ac.acolite.acolite_l2w(gem, settings=settings)

Reading Results

import acolite as ac
import matplotlib.pyplot as plt

# Read L2W file
gem = ac.gem.read('/data/output/scene_L2W.nc')

# Get available datasets
print(gem.datasets)

# Read chlorophyll data
chl = gem.data('chl_oc3')

# Read coordinates
lat = gem.data('lat')
lon = gem.data('lon')

# Plot
plt.figure()
plt.pcolormesh(lon, lat, chl, vmin=0, vmax=20)
plt.colorbar(label='Chl-a (mg/m³)')
plt.show()

Station Extraction

import acolite as ac

# Extract data for a station
result = ac.gem.extract(
    st_lon=3.05,
    st_lat=51.25,
    sdate='2023-06-01',
    edate='2023-06-30',
    sensors=['S2A_MSI', 'S2B_MSI'],
    output='/data/extractions'
)