Metadata-Version: 2.4
Name: skema-kelp
Version: 0.1.0
Summary: Satellite-based kelp classification from Sentinel-2 using semantic segmentation
Author-email: Mohsen Ghanbari <mohsenghanbari@uvic.ca>
License: MIT
Project-URL: Homepage, https://github.com/m5ghanba/skema
Project-URL: Repository, https://github.com/m5ghanba/skema
Project-URL: Issues, https://github.com/m5ghanba/skema/issues
Project-URL: Documentation, https://github.com/m5ghanba/skema#readme
Project-URL: Hugging Face, https://huggingface.co/m5ghanba/SKeMa
Project-URL: DOI, https://doi.org/10.57967/hf/6790
Keywords: kelp,sentinel-2,semantic-segmentation,remote-sensing,satellite-imagery,deep-learning,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: albumentations<2,>=1.3
Requires-Dist: click<9,>=8.1
Requires-Dist: numpy<2,>=1.26
Requires-Dist: pytorch-lightning<3,>=2.1
Requires-Dist: rasterio<2,>=1.3
Requires-Dist: scikit-learn<2,>=1.3
Requires-Dist: segmentation-models-pytorch==0.5.0
Requires-Dist: torch<3,>=2.1
Requires-Dist: torchvision<1,>=0.16
Requires-Dist: torchmetrics<2,>=1.7
Requires-Dist: rich<14,>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Dynamic: license-file

# SKeMa
[![DOI](https://img.shields.io/badge/DOI-10.57967%2Fhf%2F6790-blue)](https://doi.org/10.57967/hf/6790)
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-SKeMa-yellow)](https://huggingface.co/m5ghanba/SKeMa)
[![PyPI](https://img.shields.io/pypi/v/skema)](https://pypi.org/project/skema/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Model License: CC BY 4.0](https://img.shields.io/badge/Model%20License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)

**Satellite-based Kelp Mapping using Semantic Segmentation on Sentinel-2 imagery**

`skema` is a Python tool for classifying kelp in Sentinel-2 satellite images using a deep learning segmentation model (PyTorch). It provides a command-line interface (CLI) for easy, reproducible inference. To run the tool you would need to download Sentinel-2 images from the Copernicus Browser. More detailed instruction on how to download these images can be found in Section Usage. The following instructions are provided for anyone with no knowledge of what a command line is, no knowledge of Python or virtual environments, etc. Just follow along step by step.

**Model available on Hugging Face**: [m5ghanba/SKeMa](https://huggingface.co/m5ghanba/SKeMa)  
**DOI**: [10.57967/hf/6790](https://doi.org/10.57967/hf/6790)

---

## ⚡ Quick Start (Experienced Users)
```bash
pip install skema

# Download static files (for model_full only) from sources listed below
# Download Sentinel-2 imagery from https://dataspace.copernicus.eu/browser/

skema --input-dir path/to/S2_scene.SAFE --output-filename output.tif

# For help and all options
skema --help
```

**For detailed installation instructions (beginner-friendly), see [Installation](#-installation) below.**

---

## Citation

If you use **SKeMa** in your research or work, please cite:

```bibtex
@software{skema_2025,
  author       = {Mohsen Ghanbari et al.},
  title        = {SKeMa: Satellite-based Kelp Mapping using Semantic Segmentation on Sentinel-2 imagery},
  year         = 2025,
  publisher    = {Hugging Face},
  doi          = {10.57967/hf/6790},
  url          = {https://huggingface.co/m5ghanba/SKeMa}
}
```

**Plain text**:  
Ghanbari, M., et al. (2025). *SKeMa: Satellite-based Kelp Mapping using Semantic Segmentation on Sentinel-2 imagery*. Hugging Face. https://doi.org/10.57967/hf/6790

---
---

## 🚀 Installation

Before you can set up SKeMa, you'll need **Python** (version 3.8 or higher) and **Git** installed on your computer. These are free tools, and no accounts or sign-ups are required to install them or to clone the repository from GitHub later. We'll install them using your terminal (command line) where possible for simplicity. If you're on Windows, ensure you're using **PowerShell** or **Command Prompt** as Administrator (right-click and select "Run as administrator") for some steps.

### Step 1: Install Prerequisites (Python and Git)

#### On Windows
1. **Check if Winget is available** (it's built into Windows 10 version 2009 or later, or Windows 11, and most modern systems have it):
   - Open PowerShell or Command Prompt.
   - Type `winget --version` and press Enter.
   - If it shows a version number (e.g., "v1.8.0"), proceed. If not (error like "winget is not recognized"), download the App Installer from the Microsoft Store (search for "App Installer") or update Windows via Settings > Update & Security > Windows Update.

2. **Install Python 3.12** (the latest stable version as of October 2025; this meets the >=3.8 requirement):
   - In your terminal, run:
     ```
     winget install -e --id Python.Python.3.12
     ```
   - This downloads and installs Python automatically. It may take a few minutes.
   - **Important**: During installation (if prompted), ensure "Add Python to PATH" is selected (it usually is by default with winget).
   - Restart your terminal after installation.
   - Verify: Run `python --version`. It should output something like "Python 3.12.7". If not, close and reopen the terminal, or manually add Python to PATH (search online for "add Python to PATH Windows").

3. **Install Git**:
   - In your terminal, run:
     ```
     winget install --id Git.Git -e --source winget
     ```
   - This installs Git. It adds itself to PATH automatically.
   - Restart your terminal.
   - Verify: Run `git --version`. It should output something like "git version 2.46.0.windows.1".

   *Alternative if winget fails*: Download the installer from [git-scm.com](https://git-scm.com/download/win) using your browser, run it, and follow the GUI prompts (use defaults). Then verify as above.

#### On macOS
1. **Install Homebrew** (a package manager for CLI installations, if you don't have it):
   - Open Terminal (search for it in Spotlight with Cmd+Space).
   - Run:
     ```
     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
     ```
   - Follow any on-screen prompts (it may ask for your password; this is normal). No account needed.
   - After installation, run the commands it suggests to add Homebrew to your PATH (e.g., `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile` and then `eval "$(/opt/homebrew/bin/brew shellenv)"`).
   - Verify: Run `brew --version`. It should show a version like "4.3.0".

2. **Install Python 3.12**:
   - Run:
     ```
     brew install python@3.12
     ```
   - This installs Python and adds it to PATH.
   - Verify: Run `python3 --version` (note: use `python3` on macOS). It should output "Python 3.12.7".

3. **Install Git**:
   - Run:
     ```
     brew install git
     ```
   - Verify: Run `git --version`. It should output something like "git version 2.46.0".

   *Alternative*: Download the official installer from [python.org](https://www.python.org/downloads/macos/) and [git-scm.com](https://git-scm.com/download/mac) using your browser, run them, and follow GUI steps.

#### On Linux (e.g., Ubuntu/Debian; adjust for other distros like Fedora)
1. **Update your package list**:
   - Open your terminal.
   - Run:
     ```
     sudo apt update
     ```
   - Enter your password when prompted (sudo is for admin privileges; no account needed beyond your user login).

2. **Install Python 3.12**:
   - Run:
     ```
     sudo apt install python3.12 python3.12-venv
     ```
   - This installs Python and the venv module.
   - Verify: Run `python3 --version`. It should output "Python 3.12.x".
   - *For Fedora/RHEL*: Use `sudo dnf install python3.12` instead.

3. **Install Git**:
   - Run:
     ```
     sudo apt install git
     ```
   - Verify: Run `git --version`.
   - *For Fedora/RHEL*: Use `sudo dnf install git`.

   *Note*: If your distro's repositories don't have Python 3.12, add a PPA (e.g., for Ubuntu: `sudo add-apt-repository ppa:deadsnakes/ppa` then update and install).

Once Python and Git are installed and verified, proceed to the next section. If you encounter errors (e.g., "command not found"), search online for the exact error message + your OS.

### Step 2: Install SKeMa
We recommend creating a **virtual environment**. A virtual environment is like a clean sandbox that keeps all the Python packages for this project separate from your system-wide Python installation.

To do this, open your **terminal**:  
- On **Windows**, you can use Command Prompt, PowerShell, or Anaconda Prompt.  
- On **macOS**, open the Terminal app.  
- On **Linux**, open your terminal emulator of choice.  

When you open a terminal, you start inside a **directory (folder)**. You can move to another directory with the command `cd`. For example:  

```  
cd C:\Users\YourName\Documents  
```  

On macOS/Linux:  

```  
cd /Users/yourname/Documents  
```  

👉 The easiest way to navigate is to open your file explorer, go to the folder you want, then copy its full path and paste it after `cd` on the command line. For more details, look up "basic terminal navigation" online.  

Now, navigate to a directory where you want to download the SKeMa installation files, then run:

```  
python -m venv skema_env  
# On Windows:  
skema_env\Scripts\activate  
# On macOS/Linux:  
source skema_env/bin/activate  

# Clone the repository  
git clone https://github.com/m5ghanba/skema.git  
```  

Each line:  
- `python -m venv skema_env`: Creates a virtual environment named `skema_env` to isolate project dependencies.  
- `skema_env\Scripts\activate` (Windows) or `source skema_env/bin/activate` (macOS/Linux): Activates the virtual environment, ensuring subsequent commands use its isolated Python and packages.  
- `git clone https://github.com/m5ghanba/skema.git`: Downloads the SKeMa repository from GitHub into a new folder named `skema` in your current directory. The working directory is the folder your terminal is currently operating in, which you can check by running `pwd` (macOS/Linux) or `cd` (Windows).

#### Static files  
There are necessary **static files** that need to be downloaded. These are bathymetry and substrate files from the whole coast of British Columbia that `skema` uses when predicting kelp on a Sentinel-2 image.  

- The bathymetry file is a single TIFF raster (`Bathymetry_10m.tif`).  
- There are five substrate TIFF rasters (`NCC_substrate_20m.tif`, `SOG_substrate_20m.tif`, `WCVI_substrate_20m.tif`, `QCS_substrate_20m.tif`, `HG_substrate_20m.tif`), each covering a different region of the BC coast.  
- Place them inside:  

```text  
skema/skema/static/bathy_substrate/  
```

**⚠️ Note**: Static files (bathymetry and substrate) are only required when using the **full model** (`--model-type model_full`). If you plan to use only the **S2-only model** (`--model-type model_s2bandsandindices_only`), you can skip downloading these files.

**Sources**:  
- Canada's DEM/bathymetry model (10m resolution):  
  - Documentation: https://publications.gc.ca/collections/collection_2023/rncan-nrcan/m183-2/M183-2-8963-eng.pdf  
  - Dataset: https://maps-cartes.services.geo.ca/server_serveur/rest/services/NRCan/canada_west_coast_DEM_en/MapServer  

- Shallow substrate model (20m) of the Pacific Canadian coast (Haggarty et al., 2020):  
  https://osdp-psdo.canada.ca/dp/en/search/metadata/NRCAN-FGP-1-b100cf6c-7818-4748-9960-9eab2aa6a7a0  


Now, install SKeMa:  

```bash
cd skema
pip install .
```

Each line:
- `cd skema`: moves into the SKeMa project folder.
- `pip install .`: installs the package and all its dependencies, and makes the skema command available.

If you encounter packaging errors, make sure your pip and build tools are up to date:

```bash
pip install --upgrade pip setuptools wheel
```


#### GPU support  

For GPU users, install CUDA-supported PyTorch that matches your CUDA Toolkit. Check your CUDA version with:  

```bash  
nvcc --version  
```

For CUDA 12.1:  

```bash  
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu121  
```

For CUDA 11.8:  

```bash  
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118  
```

Skip this step if you don't have a GPU.

---

## 🛰️ Usage

To use SKeMa after the initial installation, you must activate its virtual environment each time you start a new session. Navigate to the directory where you downloaded the SKeMa installation files (e.g., path/to/skema) and activate the virtual environment. If your command line prompt shows (base), the virtual environment is not activated; seeing (skema_env) confirms it is activated.

On Windows: ``` cd path/to/skema skema_env\Scripts\activate ```

On Mac: ``` cd path/to/skema source skema_env/bin/activate ```

This will activate the skema_env virtual environment, where SKeMa and its dependencies are installed, ensuring the tool runs correctly.

SKeMa uses Sentinel-2 satellite images, which can be downloaded from the [Copernicus Browser](https://dataspace.copernicus.eu/browser/). To access these images, you need to create a free account on the Copernicus Data Space website:
- Visit [https://dataspace.copernicus.eu/](https://dataspace.copernicus.eu/) and click "Sign Up" to create an account.
- Follow the instructions to register with your email and set a password.
- Once logged in, use the Copernicus Browser to search for and download Sentinel-2 images, which will be provided as `.zip` files.

Now, you can run SKeMa on a new Sentinel-2 image:

```bash  
skema --input-dir path/to/sentinel2/safe/folder --output-filename output.tif  
```

- The first path (`--input-dir`) must be the full path to the `.SAFE` folder.  
  - Sentinel-2 images from the Copernicus Browser come as `.zip` files. Extract them first.  
  - Then, pass the full path to the `.SAFE` folder (e.g., `C:\...\S2C_MSIL2A_20250715T194921_N0511_R085_T09UUU_20250716T001356.SAFE`).  

- The second parameter (`--output-filename`) is the name of the output file (e.g., `output.tif`).  

### Model Types

SKeMa supports two model types:

1. **`model_full`** (default): Uses all available data including Sentinel-2 bands, bathymetry, and substrate information. This model provides the most accurate predictions but requires bathymetry and substrate static files.

2. **`model_s2bandsandindices_only`**: Uses only Sentinel-2 bands and derived spectral indices. This model does not require bathymetry or substrate files, making it suitable for areas outside British Columbia or when static files are unavailable.

To specify the model type, use the `--model-type` flag:

```bash
# Using the full model (default - includes bathymetry and substrate)
skema --input-dir path/to/sentinel2/safe/folder --output-filename output.tif --model-type model_full

# Using S2-only model (no bathymetry/substrate required)
skema --input-dir path/to/sentinel2/safe/folder --output-filename output.tif --model-type model_s2bandsandindices_only
```

If `--model-type` is not specified, the tool defaults to `model_full`.

### Output Files

After running, the tool generates a folder with the same name as the `.SAFE` file. Inside this folder, you'll find:

**For `model_full`:**
1. **`<SAFE_name>_B2B3B4B8.tif`**: a 10 m resolution, 4-band GeoTIFF containing Sentinel-2 bands B02 (Blue), B03 (Green), B04 (Red), and B08 (Near-Infrared).  
2. **`<SAFE_name>_B5B6B7B8A_B11B12.tif`**: a 20 m resolution, 6-band GeoTIFF containing Sentinel-2 bands B05, B06, B07, B8A, B11, and B12.  
3. **`<SAFE_name>_Bathymetry.tif`**: bathymetry data aligned and warped to the Sentinel-2 pixel grid.  
4. **`<SAFE_name>_Substrate.tif`**: substrate classification data aligned and warped to the Sentinel-2 pixel grid.  
5. **`output.tif`** (or the filename you specify): a **binary GeoTIFF**, where kelp is labeled as `1` and non-kelp as `0`.  

**For `model_s2bandsandindices_only`:**
1. **`<SAFE_name>_B2B3B4B8.tif`**: a 10 m resolution, 4-band GeoTIFF containing Sentinel-2 bands B02 (Blue), B03 (Green), B04 (Red), and B08 (Near-Infrared).  
2. **`<SAFE_name>_B5B6B7B8A_B11B12.tif`**: a 20 m resolution, 6-band GeoTIFF containing Sentinel-2 bands B05, B06, B07, B8A, B11, and B12.  
3. **`output.tif`** (or the filename you specify): a **binary GeoTIFF**, where kelp is labeled as `1` and non-kelp as `0`.

---

## ⚙️ Project Structure

```text  
skema/  
├── skema/  
│   ├── cli.py  
│   ├── lib.py  
│   ├── __init__.py  
│   │  
│   └── static/  
│       ├── __init__.py  
│       │  
│       └── bathy_substrate/  
│           ├── __init__.py  
│           ├── Bathymetry_10m.tif  
│           ├── NCC_substrate_20m.tif  
│           ├── SOG_substrate_20m.tif  
│           ├── WCVI_substrate_20m.tif  
│           ├── QCS_substrate_20m.tif  
│           └── HG_substrate_20m.tif  
├── pyproject.toml  
├── setup.py  
├── requirements.txt  
├── README.md  
```

---


## 📜 License
- **Code**: MIT License (see LICENSE file)
- **Model**: The trained model is licensed under **CC-BY-4.0** — please cite the DOI when using it.
