Contributing¶

Thank you for considering contributing to GEE ACOLITE! This guide explains how to report issues, propose features, and submit code or documentation improvements.

Ways to Contribute¶

🐛 Report Bugs¶

Before opening a new issue, check whether it has already been reported in Issues. If not, create one including:

• A clear description of the problem
• Minimal reproducible code
• Full traceback
• Environment details (see template below)

Issue Template:

### Bug Description
[Clear and concise description]

### Steps to Reproduce
1. ...
2. ...
3. ...

### Expected Behavior
[What you expected to happen]

### Actual Behavior
[What actually happened]

### Environment
- OS: [e.g., Ubuntu 22.04, Windows 11]
- Python: [e.g., 3.11.0]
- gee_acolite: [e.g., 1.2.0]
- ACOLITE: [e.g., 20231023]
- earthengine-api: [e.g., 0.1.390]

### Reproducible Code
```python
# Minimal code to reproduce the error

Traceback¶

[Paste the full traceback here]

### ✨ Request Features

Open a [GitHub Issue](https://github.com/Aouei/gee_acolite/issues) and describe:

1. The use case and motivation
2. The expected behavior
3. A usage example if possible

### 📝 Improve Documentation

- Fix typos or unclear explanations
- Add usage examples or notebooks
- Improve API docstrings

### 💻 Contribute Code

See the [Development](#development) section below.

## Development

### Setting Up the Development Environment

GEE ACOLITE uses ACOLITE as a Git submodule. Make sure to initialise it after cloning:

```bash
# Fork and clone
git clone https://github.com/your-username/gee_acolite.git
cd gee_acolite

# Initialise the ACOLITE submodule
git submodule update --init --recursive

# Create and activate a virtual environment (Python >= 3.11 required)
python -m venv venv
source venv/bin/activate       # Linux / macOS
venv\Scripts\activate          # Windows

# Install the package in development mode
pip install -e .

# Optional: install visualisation dependencies
pip install -e ".[viz]"

conda create -n gee_acolite python=3.11
conda activate gee_acolite
pip install -e .

Project Structure¶

gee_acolite/
├── gee_acolite/              # Source code
│   ├── __init__.py
│   ├── correction.py         # ACOLITE class — main DSF workflow
│   ├── water_quality.py      # Water quality products (SPM, Chl-a, Rrs…)
│   ├── bathymetry.py         # Satellite-derived bathymetry (SDB)
│   ├── utils/
│   │   ├── l1_convert.py     # DN → TOA, geometry, resampling
│   │   ├── masks.py          # Water / cloud / shadow masking
│   │   └── search.py         # Sentinel-2 search + cloud probability
│   └── sensors/
│       └── sentinel2.py      # Band definitions and scale groups
├── ACOLITE/                  # Git submodule (Vanhellemont)
├── tests/                    # Notebooks and scripts for manual testing
├── docs/                     # MkDocs documentation
├── pyproject.toml            # Package configuration
└── README.md

Code Style¶

We follow PEP 8. Use NumPy-style docstrings and type hints:

# Import order: stdlib → third-party → GEE → local
import os

import numpy as np
import scipy.interpolate

import ee

from gee_acolite.utils import masks


def compute_rrs(image: ee.Image, settings: dict) -> ee.Image:
    """
    Convert surface reflectance to remote sensing reflectance.

    Parameters
    ----------
    image : ee.Image
        L2W image containing ``rhos_B*`` bands.
    settings : dict
        ACOLITE settings dictionary.

    Returns
    -------
    ee.Image
        Image with ``Rrs_B*`` bands added.

    Examples
    --------
    >>> rrs_image = compute_rrs(l2w_image, settings)
    """
    ...

Testing¶

Tests are organised as Jupyter notebooks under tests/ and one standalone script (tests/test_tiled_mode.py). To run the script:

python tests/test_tiled_mode.py

For notebook-based tests, open the relevant notebook in tests/tests/ or tests/SDB/ and run all cells. GEE authentication is required:

import ee
ee.Authenticate()
ee.Initialize(project="your-project-id")

When contributing new functionality, add a minimal notebook or extend an existing one demonstrating the expected behaviour.

Contribution Workflow¶

1. Fork the repository on GitHub
2. Create a branch for your change:

   git checkout -b feat/my-new-feature
   

3. Commit using Conventional Commits:

   git commit -m "feat(bathymetry): add multi-band SDB calibration"
   

4. Push to your fork:

   git push origin feat/my-new-feature
   

5. Open a Pull Request against main

Commit Convention¶

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

Release tags (append to commit message to trigger version bump in CI):

Examples:

feat(water_quality): add Dogliotti turbidity for B5

fix(correction): handle NaN values in dark spectrum retrieval

docs(api): update ACOLITE.correct() return type description

chore: bump earthengine-api dependency to >=0.1.390 [release-patch]

Pull Request Guidelines¶

Checklist before opening a PR:

• [ ] Code follows PEP 8
• [ ] New functionality has a test notebook or script
• [ ] Docstrings are complete and use NumPy style
• [ ] Documentation updated if public API changed
• [ ] All existing tests/notebooks still work

PR Template:

## Description
[What does this PR change and why?]

## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation / refactor

## How to Test
[Steps or notebook to verify the change]

## Related Issues
Closes #[issue number]

Documentation¶

Build Locally¶

pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-mermaid2-plugin

# Live preview with auto-reload
mkdocs serve
# → http://127.0.0.1:8000

Add a New Page¶

1. Create a .md file in docs/
2. Register it in mkdocs.yml under nav:

nav:
  - Section:
      - New Page: path/to/page.md

Admonitions¶

Use MkDocs Material admonitions to highlight important information:

!!! note "GEE initialisation"
    Always call `ee.Initialize(project=...)` before using any GEE functionality.

!!! warning "ACOLITE submodule"
    ACOLITE must be initialised with `git submodule update --init --recursive`.

!!! tip "Dark spectrum"
    The `getInfo()` call for the dark spectrum is the only client-side bottleneck
    per image. Keep the collection small to reduce processing time.

Community¶

Code of Conduct¶

• Be respectful and constructive
• Accept and give feedback in good faith
• Focus on what is best for the project and its users

Communication¶

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions, ideas, and general conversation

Frequently Asked Questions¶

Do I need to know ACOLITE internals to contribute?¶

No. Most contributions involve GEE-side code (correction.py, water_quality.py, bathymetry.py) which does not require deep knowledge of ACOLITE. The ACOLITE interaction is isolated to LUT loading and dark spectrum retrieval in correction.py.

What Python version is required?¶

Python >= 3.11 is required, matching the requires-python constraint in pyproject.toml.

How do I authenticate with GEE?¶

import ee
ee.Authenticate()            # only needed once
ee.Initialize(project="your-cloud-project")

See the GEE Python quickstart for full instructions.

My ACOLITE submodule is empty — what do I do?¶

git submodule update --init --recursive

If you cloned without --recurse-submodules, the ACOLITE/ directory will be empty until you run the command above.

Thank you for contributing to GEE ACOLITE!