Installation

ACOLITE is distributed as Python source code and requires a conda environment for dependency management.

Requirements

  • Python 3.9 or later (3.11+ recommended)

  • Conda package manager (Anaconda or Miniconda)

  • ~500 MB disk space for code and LUTs

Quick Install

  1. Clone the repository (use --depth 1 to avoid pulling old LUT history):

    git clone --depth 1 https://github.com/acolite/acolite
cd acolite

  2. Create and activate the conda environment:

    conda create -n acolite -c conda-forge python=3
conda activate acolite

  3. Install dependencies:

    conda install -c conda-forge numpy matplotlib scipy gdal \
    libgdal-jp2openjpeg libgdal-netcdf pyproj scikit-image \
    pyhdf pyresample netcdf4 h5py requests pygrib cartopy zarr

  4. Test the installation:

    python launch_acolite.py

Using environment.yml

Alternatively, use the provided environment file:

conda env create -f environment.yml
conda activate acolite

Dependencies

Core Dependencies

The following packages are required (all available from conda-forge):

Package

Purpose

numpy

Numerical computing

scipy

Scientific computing and interpolation

matplotlib

Visualization and RGB output

gdal

Geospatial data I/O

libgdal-jp2openjpeg

JPEG2000 support (Sentinel-2)

libgdal-netcdf

NetCDF support for GeoTIFF export

pyproj

Coordinate transformations

scikit-image

Image processing

pyhdf

HDF4 file support

pyresample

Resampling and reprojection

netcdf4

NetCDF file I/O

h5py

HDF5 file support

requests

HTTP downloads

pygrib

GRIB file support (meteorological data)

cartopy

Map projections

zarr

Zarr format support

Note

GDAL >= 3.9 is recommended. For earlier versions, the libgdal-* packages are not required.

Optional Dependencies

  • fsspec, aiohttp - Required for zarr cloud data access

  • libRadtran v2.0.5 - Required for TACT thermal processing

Look-Up Tables (LUTs)

ACOLITE uses pre-computed Look-Up Tables for atmospheric correction. LUTs are not included in the repository to reduce download size, but are automatically downloaded when first needed.

To pre-download LUTs for specific sensors:

python launch_acolite.py --retrieve_luts --sensor Sentinel2,Landsat8

Available LUT sensors: Sentinel2, Sentinel3, Landsat5, Landsat7, Landsat8, Landsat9, VIIRS, PlanetScope, etc.

LUTs are stored in the data/LUT/ directory and cached for future use.

EarthData Account Setup

An EarthData account is required for:

  • Downloading ancillary data (ozone, water vapor, pressure, wind)

  • Accessing SRTM DEM data

  • Accessing ASTER GED emissivity data

  1. Create an account at https://urs.earthdata.nasa.gov/users/new

  2. Authorize required applications in your EarthData profile:

    • OB.DAAC Data Access

    • LP DAAC Data Pool

  3. Configure credentials using one of these methods:

    Option A: .netrc file (recommended)

    Add to ~/.netrc:

    machine earthdata
login YOUR-USERNAME
password YOUR-PASSWORD

    Ensure proper permissions:

    chmod 600 ~/.netrc

    Option B: Environment variables

    export EARTHDATA_u=YOUR-USERNAME
export EARTHDATA_p=YOUR-PASSWORD

    Option C: Credentials file

    Edit config/credentials.txt:

    EARTHDATA_u=YOUR-USERNAME
EARTHDATA_p=YOUR-PASSWORD

TACT Installation (Optional)

The Thermal Atmospheric Correction Tool (TACT) requires libRadtran for atmospheric simulations.

Option 1: Conda installation (easiest)

conda install conda-forge::rubin-libradtran

Add to your settings file:

use_system_libradtran=True

Option 2: Manual installation

mkdir -p external
cd external
wget http://www.libradtran.org/download/libRadtran-2.0.5.tar.gz
tar -xzf libRadtran-2.0.5.tar.gz
cd libRadtran-2.0.5
./configure
make
make check

For improved spectral resolution, add reptran data:

cd external/libRadtran-2.0.5
wget "http://www.meteo.physik.uni-muenchen.de/~libradtran/lib/exe/fetch.php?media=download:reptran_2017_all.tar.gz" -O reptran_2017_all.tar.gz
tar -xzf reptran_2017_all.tar.gz

Verifying Installation

Test your installation by running the GUI:

python launch_acolite.py

Or test the CLI:

python launch_acolite.py --cli --help

Troubleshooting

GDAL import errors

Ensure GDAL is installed from conda-forge, not pip:

conda install -c conda-forge gdal

Missing JP2000 support

Install the JPEG2000 GDAL plugin:

conda install -c conda-forge libgdal-jp2openjpeg

LUT download failures

Check your internet connection and try manual download from https://github.com/acolite/acolite_luts

EarthData authentication errors

Verify your .netrc file permissions (must be 600) and that your account has the required application authorizations.