GEE Integration¶

How GEE ACOLITE integrates with Google Earth Engine — what runs on the server, what runs on the client, and why.

Architecture Overview¶

GEE ACOLITE uses a hybrid processing model that combines:

• Client-side (local Python): ACOLITE LUT loading, AOT estimation, model selection
• Server-side (GEE cloud): All image operations, band arithmetic, masking, product computation

This design is necessary because ACOLITE's atmospheric correction requires LUT interpolation that cannot be expressed as a GEE computation graph, while pixel-level image operations benefit from GEE's massive parallelism.

Client vs Server: Operation Classification¶

Client-Side Operations¶

These run in the local Python process and block until complete:

Server-Side Operations¶

These return ee.Image or ee.ImageCollection objects. They are lazy — no computation happens until .getInfo(), .export(), or tile rendering is triggered.

GEE Lazy Evaluation¶

GEE uses deferred execution: Python code builds a computation graph but nothing runs until explicitly requested.

Consequence for gee_acolite: the correction formula compute_rhos() is never actually executed on any pixel during Python execution — only when the result is exported or .getInfo() is called by the user.

The getInfo() Bottleneck¶

The single getInfo() per image in compute_pdark() is unavoidable but minimised:

# Inside compute_pdark() — the only blocking call per image
pdark = image.reduceRegion(
    reducer=reducer,          # percentile or min
    geometry=image.geometry(),
    scale=settings.get('s2_target_res', 10),
    maxPixels=1e9,
).getInfo()  # ← transfers ~13 float values from GEE to Python

The response is a dict of 13 scalar values (one per band), typically < 1 KB. Everything else (the correction, the products, the masking) runs server-side without blocking.

Export to GeoTIFF¶

After correction, results live in GEE as lazy ee.Image / ee.ImageCollection objects. To work with them locally as GeoTIFFs, use geemap.

Dependencies¶

import geemap
from datetime import datetime, timedelta
from gee_acolite import ACOLITE
from gee_acolite.utils.search import search_list
from gee_acolite import bathymetry

Download a single mosaic¶

Use bathymetry.multi_image() to collapse a corrected collection into a quality mosaic, then download it as a single GeoTIFF.

bands = [
    'Rrs_B1', 'Rrs_B2', 'Rrs_B3', 'Rrs_B4',
    'Rrs_B5', 'Rrs_B6', 'Rrs_B7', 'Rrs_B8', 'Rrs_B8A',
    'Rrs_B11', 'Rrs_B12',
    'pSDB_green', 'pSDB_red',
    'tur_nechad2016', 'chl_oc3',
]

roi    = ee.Geometry.Rectangle([...])
starts = ['2018-09-19', '2018-10-04', '2018-10-17']
ends   = [
    (datetime.strptime(d, '%Y-%m-%d') + timedelta(days=1)).strftime('%Y-%m-%d')
    for d in starts
]

corrector    = ACOLITE(acolite=acolite, settings='settings.txt')
collection   = search_list(roi, starts, ends, tile='29SND')
corrected, _ = corrector.correct(collection)

mosaic = bathymetry.multi_image(corrected)

geemap.download_ee_image(
    image=mosaic.select(bands),
    filename='output/mosaic.tif',
    region=roi,
    crs='EPSG:32629',
    scale=10,
    dtype='float32',
)

Download an image collection (one file per scene)¶

filenames = [f'{d.replace("-", "_")}.tif' for d in starts]

geemap.download_ee_image_collection(
    collection=corrected.select(bands),
    out_dir='output/scenes/',
    filenames=filenames,
    region=roi,
    crs='EPSG:32629',
    scale=10,
    dtype='float32',
)

Choosing between the two¶