Marine Litter

A Python project for detecting marine litter via satellite imagery using artificial intelligence (plus some GUI: JavaScript for Google Earth Engine).

This page concentrates on development, for project overview, technical details, and usage, see the Documentation.

Development Setup

Prerequisites

• Python ≥3.11
• uv package and project manager
• ruff for formatting and linting, it also calls isort and black.

Install these like

• Windows: winget install -e astral-sh.uv astral-sh.ruff
• macOS: brew install uv ruff
• Linux: sudo apt install pipx && pipx install uv ruff

Quick Start

For development, Python should be used in a venv. This is done by uv automatically into project root .venv/, when not called with --active.

# get dependencies including pytest etc.
uv sync

If you prefer to keep the venv outside of the project, and to avoid the need to prepend non-uv calls with uv run , you can create a venv manually and activate it, but need to add --active to uv sync calls then:

# get dependencies including pytest etc.
uv sync --active

Then you could use the Python scripts in 'scripts/', or run pytest, but you might want to understand the repo structure and configurations first...

Repository Structure

/docker/       - Docker related files, including readme for setup
./docs/         - for documentation via https://www.mkdocs.org/
./resources/    - GIS configuration etc.
./scripts/      - to run for analysis
./secrets/      - (git-ignored) credentials
./src/          - actual package code
./tests/        - for pytest
./web_gee/      - frontend: JavaScript for Google Earth Engine

Some temporary (git-ignored) directories like _temp/, or site/ may be produced by certain tools or scripts.

The 'pyproject.toml' in the project root is used by the mentioned above tools uv, ruff, or installed then dev dependencies, like pytest, or mkdocs.

Note the subtle naming differences between

• project name 'Marine Litter'
• git repo name 'Marine_Litter'
• Python package name 'marine-litter', and
• module name marine_litter.

Configuration of the Python scripts

The project uses Pydantic Settings for configuration. You should copy '.example.env' to a parallel '.env' (which should stay excluded by '.gitignore'), and adjust the values as needed, see als 'src/marine_litter/ml_settings.py', or 'tests/test_ml_settings.py'.

When 'ml_settings.py' evolves, also update '.example.env' and tests accordingly.

Development and Analysis

Git

We use a specific branch naming convention to maintain clarity (with date for creation)

• feature/<featurename>_<YYYYMMDD>
• bugfix/<bugname>_<YYYYMMDD>

Using uv, ruff, and pytest (Quality Checks)

While developing, please regularly run the following commands.

Adapt parameters, like omitting --active when using local '.venv/', see uv documentation for details

Ensure all these are fine before committing a change to git.

# update dependencies (including `dev` ones), updates `uv.lock`
uv sync --active --upgrade

# check code and fix linting issues
ty check --output-format concise
ruff check --preview --fix --unsafe-fixes

# run all tests
pytest tests

Docker

See the extra Docker readme, namely you could test the built Docker image by

docker run --rm --env-file .env -v ./secrets:/marine_litter/secrets:ro marine_litter python scripts/run_all.py --dry-run

Frontend Development (JavaScript for Google Earth Engine)

TBD

Analysis and Other Scripts

You may want to run the complete pipeline, or parts of it like below. Depending on your OS and having

• 'scripts/' in PATH
• a venv active, or
• parameters to add

adapt how you call the all-in-one or single scripts:

run_all.py
scripts\run_all.py
uv run scripts/run_all.py
uv run --active scripts/run_all.py

CVE-2025-63396 (PyTorch Profiler Bug)

• Status: CVSS 3.3 LOW - Not a security vulnerability
• Affected: PyTorch 2.5, 2.7.1, 2.9.1 (likely)
• Issue: Forgetting profiler.stop() causes crashes/hangs in torch.profiler.profile
• References:
  • NVD CVE Details
  • PyTorch GitHub Issue
  • PyTorch Security Advisories

Why not a security issue?

• Requires user error (API misuse)
• Only affects developer's own code
• Cannot be exploited for attacks

Recommendation

• Safe to ignore, if using the profiler, call .stop() properly
• Watch for future PyTorch releases addressing this.

Documentation

We use MkDocs for documentation, and Read the Docs to publish it.

MkDocs

To improve the documentation, add or edit the Markdown files in 'docs/' and create a pull request.

The standard usage to test changes is to start a local documentation server, which nicely auto-reloads on changes (adapt the port if needed):

mkdocs serve -a 127.0.0.1:8001

You could also create, or update a documentation 'site/' (git-ignored) by calling mkdocs build.

Read the Docs

To publish the documentation, Read the Docs needs 'docs/requirements.txt', which is generated from the dependencies given in 'docs/requirements.in'.

• install pip-tools (see 'pyproject.toml' "dev" group, should be done by uv sync already)

  pip install -U pip-tools

• call

  pip-compile docs/requirements.in

• commit and push the generated docs/requirements.txt, if the "docs" dependencies change.

Note, these "docs" dependencies need to keep in sync in

• 'docs/requirements.in' and
• 'pyproject.toml',

like to test the Documentation via mkdocs serve before pushing.

License, Issues and Contributing

This project is licensed under the MIT License, see LICENSE.txt.

Report bugs or request features via project's issues: https://github.com/MI4People/Marine_Litter/issues.

Contributing

• Fork the repository
• Create a branch as written above under Git
• Follow the coding and quality guidelines from above
• Submit a pull request.