OmniCloudMask

https://omnicloudmask.readthedocs.io/en/latest/
Admin
A Python library for cloud and cloud shadow detection in satellite imagery supporting resolutions...
Tokens:16,849
Snippets:217
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install OmniCloudMask from Source

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Install OmniCloudMask directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/DPIRD-DMA/OmniCloudMask.git

```

--------------------------------

### Install OmniCloudMask using uv

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install OmniCloudMask using the uv package manager. Ensure uv is installed and configured.

```bash
uv add omnicloudmask
```

--------------------------------

### Install OmniCloudMask from Source

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install OmniCloudMask directly from its GitHub repository. This is useful for development or when needing the latest unreleased changes.

```bash
pip install git+https://github.com/DPIRD-DMA/OmniCloudMask.git
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/contributing.md.txt

Clone the OmniCloudMask repository and install development dependencies using uv.

```bash
git clone https://github.com/DPIRD-DMA/OmniCloudMask.git
cd OmniCloudMask
uv sync --group dev
```

--------------------------------

### Install OmniCloudMask with Legacy Model Support (uv)

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install the 'legacy' extra for older model support using the uv package manager. Specify the extra using the --extra flag.

```bash
uv add omnicloudmask --extra legacy
```

--------------------------------

### Install OmniCloudMask with Legacy Support (uv)

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Install the 'legacy' extra for OmniCloudMask using uv to support older model versions (1.0-3.0).

```bash
uv add omnicloudmask --extra legacy

```

--------------------------------

### Install OmniCloudMask from PyPI

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Use this command to install the latest stable version of OmniCloudMask from the Python Package Index.

```bash
pip install omnicloudmask
```

--------------------------------

### Install OmniCloudMask with Legacy Model Support (conda)

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install OmniCloudMask and fastai from conda-forge to support legacy models. This command ensures both OmniCloudMask and its fastai dependency are correctly installed.

```bash
conda install conda-forge::omnicloudmask conda-forge::fastai
```

--------------------------------

### Install OmniCloudMask with Legacy Model Support (pip)

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install the 'legacy' extra to support older model versions (1.0-3.0) built with fastai. Use this command with pip.

```bash
pip install omnicloudmask[legacy]
```

--------------------------------

### Build OmniCloudMask Docker Image

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Clone the repository and build the Docker image locally. Ensure Docker and NVIDIA Container Toolkit (for GPU support) are installed.

```bash
git clone https://github.com/DPIRD-DMA/OmniCloudMask
cd OmniCloudMask
docker build -f docker/Dockerfile -t omnicloudmask:local .
```

--------------------------------

### Build OmniCloudMask Docker Image

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Clone the repository and build the Docker image for OmniCloudMask locally. Ensure Docker and NVIDIA Container Toolkit (for GPU support) are installed.

```bash
git clone https://github.com/DPIRD-DMA/OmniCloudMask
cd OmniCloudMask
docker build -f docker/Dockerfile -t omnicloudmask:local .

```

--------------------------------

### Install OmniCloudMask from conda-forge

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Install OmniCloudMask using the conda package manager from the conda-forge channel.

```bash
conda install conda-forge::omnicloudmask

```

--------------------------------

### Install OmniCloudMask from conda-forge

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Install OmniCloudMask using the conda package manager from the conda-forge channel. This is useful for managing Python environments and dependencies.

```bash
conda install conda-forge::omnicloudmask
```

--------------------------------

### Downscale Imagery for Higher Throughput

Source: https://omnicloudmask.readthedocs.io/en/latest/usage.html

Reduce processing time by downscaling imagery, for example, processing Sentinel-2 at 20 m instead of 10 m. This trades some accuracy for significantly improved speed.

```python
from functools import partial
from omnicloudmask import predict_from_load_func, load_s2

loader = partial(load_s2, resolution=20)

pred_paths = predict_from_load_func(scene_paths, loader)


```

--------------------------------

### Specify Model Download Source

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/troubleshooting.md.txt

Use 'google_drive' as an alternative download source if Hugging Face downloads fail.

```python
mask = predict_from_array(
    input_array,
    model_download_source="google_drive",
)
```

--------------------------------

### Handle Model Download Errors

Source: https://omnicloudmask.readthedocs.io/en/latest/troubleshooting.html

Use Google Drive as an alternative download source for models if Hugging Face fails, or specify a local directory for model storage.

```python
mask = predict_from_array(
    input_array,
    model_download_source="google_drive",
)
```

```python
mask = predict_from_array(
    input_array,
    destination_model_dir="/path/to/models",
)
```

--------------------------------

### Format Code with Ruff

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/contributing.md.txt

Use ruff to format the project's code according to established style guidelines.

```bash
ruff format .
```

--------------------------------

### Create a Custom Data Loader

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Implement a custom loader function that returns a numpy array of shape (3, height, width) with Red, Green, and NIR bands, along with a rasterio profile. This is useful for integrating data from various sensors.

```python
import numpy as np
import rasterio as rio
from omnicloudmask import predict_from_load_func

def my_loader(input_path):
    with rio.open(input_path) as src:
        # Read bands in order: Red, Green, NIR
        data = src.read([4, 3, 5])  # adjust band indices for your sensor
        profile = src.profile
    return data, profile

pred_paths = predict_from_load_func(scene_paths, my_loader)
```

--------------------------------

### Run Tests with Pytest

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/contributing.md.txt

Execute the project's test suite using pytest, managed by uv.

```bash
uv run pytest tests/
```

--------------------------------

### Specify Custom Model Directory

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/troubleshooting.md.txt

Manually download models and specify the destination directory to avoid download errors.

```python
mask = predict_from_array(
    input_array,
    destination_model_dir="/path/to/models",
)
```

--------------------------------

### Run OmniCloudMask Docker Container (CPU Only)

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Run the OmniCloudMask Docker container using only CPU resources, exposing the Jupyter Lab port.

```bash
docker run -p 127.0.0.1:8888:8888 omnicloudmask:local

```

--------------------------------

### CPU Inference with Full Precision

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Configure CPU-only inference using full precision (fp32) for optimal performance on CPU systems. Optionally set the number of threads for better performance.

```python
import torch

# Optional: set thread count for better CPU performance
torch.set_num_threads(4)

pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    inference_dtype="fp32",   # important: avoid fp16/bf16 on CPU
    batch_size=1,
    inference_device="cpu",
    mosaic_device="cpu",
)
```

--------------------------------

### Run OmniCloudMask Docker Container with Data Mount

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Run the Docker container with GPU support and mount a local data directory to the container's workspace. This allows persistent data storage and access.

```bash
docker run --gpus all -p 127.0.0.1:8888:8888 -v /path/to/data:/workspace/data omnicloudmask:local
```

--------------------------------

### Run OmniCloudMask Docker Container with GPU

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Run the OmniCloudMask Docker container with GPU support, exposing the Jupyter Lab port.

```bash
docker run --gpus all -p 127.0.0.1:8888:8888 omnicloudmask:local

```

--------------------------------

### Use Multiband GeoTIFF Loader

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Utilize the built-in `load_multiband` function for generic multiband GeoTIFFs. Specify the band order using the `band_order` parameter.

```python
from functools import partial
from omnicloudmask import predict_from_load_func, load_multiband

# Specify band order: [Red, Green, NIR] (1-indexed)
loader = partial(load_multiband, band_order=[4, 3, 5])

pred_paths = predict_from_load_func(scene_paths, loader)
```

--------------------------------

### Run OmniCloudMask Docker Container with Data Mount

Source: https://omnicloudmask.readthedocs.io/en/latest/installation.html

Run the OmniCloudMask Docker container with GPU support, exposing the Jupyter Lab port and mounting a local data directory to the container's workspace.

```bash
docker run --gpus all -p 127.0.0.1:8888:8888 -v /path/to/data:/workspace/data omnicloudmask:local

```

--------------------------------

### Predict with NIR Placeholder

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Use this when your imagery lacks a NIR band. Pass an array of zeros as a placeholder for the NIR channel to maintain model robustness.

```python
import numpy as np
from omnicloudmask import predict_from_array

# red and green are 2D arrays of shape (height, width)
nir_placeholder = np.zeros_like(red)

input_array = np.stack([red, green, nir_placeholder], axis=0)
mask = predict_from_array(input_array)
```

--------------------------------

### Run OmniCloudMask Docker Container (CPU Only)

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Run the Docker container using only CPU resources. This command maps port 8888 for accessing services.

```bash
docker run -p 127.0.0.1:8888:8888 omnicloudmask:local
```

--------------------------------

### Predict with Custom NIR Placeholder Loader

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Adapt your custom data loader to return a zero-filled NIR band if your imagery lacks one. This ensures compatibility with OmniCloudMask's prediction functions.

```python
import numpy as np
import rasterio as rio
from omnicloudmask import predict_from_load_func

def load_rgb_only(input_path):
    with rio.open(input_path) as src:
        red = src.read(1)
        green = src.read(2)
        profile = src.profile
    nir_placeholder = np.zeros_like(red)
    return np.stack([red, green, nir_placeholder], axis=0), profile

pred_paths = predict_from_load_func(scene_paths, load_rgb_only)
```

--------------------------------

### Run OmniCloudMask Docker Container with GPU

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/installation.md.txt

Run the Docker container with GPU support enabled. This command maps port 8888 for accessing services like Jupyter Lab.

```bash
docker run --gpus all -p 127.0.0.1:8888:8888 omnicloudmask:local
```

--------------------------------

### Predict Cloud Mask from Multiband GeoTIFF

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/quickstart.md.txt

Use `predict_from_load_func` with a configured `load_multiband` loader to process multiband GeoTIFF files. Specify the band order using `band_order` to ensure correct Red, Green, and NIR channel assignment.

```python
from functools import partial
from pathlib import Path
from omnicloudmask import predict_from_load_func, load_multiband

scene_paths = [Path("path/to/image.tif")]

# Specify band order: [Red, Green, NIR] (1-indexed)
loader = partial(load_multiband, band_order=[4, 3, 5])

pred_paths = predict_from_load_func(scene_paths, loader)
```

--------------------------------

### Force Inference Device Selection

Source: https://omnicloudmask.readthedocs.io/en/latest/usage.html

Override the default device selection (CUDA > MPS > CPU) by specifying the desired inference device. Useful for testing or specific hardware configurations.

```python
from omnicloudmask import predict_from_array

# Force CPU
mask = predict_from_array(input_array, inference_device="cpu")

# Force CUDA
mask = predict_from_array(input_array, inference_device="cuda")

# Force Apple Silicon MPS
mask = predict_from_array(input_array, inference_device="mps")

```

--------------------------------

### Optimize CPU Inference Speed

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/troubleshooting.md.txt

Use 'fp32' for inference_dtype on CPU and set the PyTorch thread count to match your CPU cores for faster processing.

```python
import torch
torch.set_num_threads(4)  # adjust to your CPU core count
```

--------------------------------

### Predict with Missing NIR Band using predict_from_load_func

Source: https://omnicloudmask.readthedocs.io/en/latest/usage.html

When using a custom loader, return a zero-filled NIR band if it's not present in the imagery. This ensures compatibility with the model.

```python
import numpy as np
import rasterio as rio
from omnicloudmask import predict_from_load_func

def load_rgb_only(input_path):
    with rio.open(input_path) as src:
        red = src.read(1)
        green = src.read(2)
        profile = src.profile
    nir_placeholder = np.zeros_like(red)
    return np.stack([red, green, nir_placeholder], axis=0), profile

pred_paths = predict_from_load_func(scene_paths, load_rgb_only)

```

--------------------------------

### Load Multiband GeoTIFF

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

Use this function to load a multiband GeoTIFF file. Specify the input path and optionally set resampling resolution and band order. The function returns a NumPy array and a rasterio profile.

```python
omnicloudmask.load_multiband(
    input_path,
    resample_res=None,
    band_order=None,
)
```

--------------------------------

### Predict Cloud Mask from Multiband GeoTIFF

Source: https://omnicloudmask.readthedocs.io/en/latest/quickstart.html

Use `predict_from_load_func` with a configured `load_multiband` loader to process multiband GeoTIFF files. Specify the band order using `band_order` (1-indexed).

```python
from functools import partial
from pathlib import Path
from omnicloudmask import predict_from_load_func, load_multiband

scene_paths = [Path("path/to/image.tif")]

# Specify band order: [Red, Green, NIR] (1-indexed)
loader = partial(load_multiband, band_order=[4, 3, 5])

pred_paths = predict_from_load_func(scene_paths, loader)

```

--------------------------------

### Low VRAM Configuration: Offload Mosaicking to CPU

Source: https://omnicloudmask.readthedocs.io/en/latest/usage.html

If GPU memory is insufficient, offload the mosaicking process to the CPU to conserve GPU VRAM. This is useful for systems with limited GPU memory.

```python
pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    inference_dtype="bf16",
    batch_size=1,
    mosaic_device="cpu",  # offload patch mosaicking to CPU
)


```

--------------------------------

### Low VRAM Configuration

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Mitigate GPU memory issues by offloading the mosaicking process to the CPU. This is useful when GPU VRAM is insufficient for the full operation.

```python
pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    inference_dtype="bf16",
    batch_size=1,
    mosaic_device="cpu",  # offload patch mosaicking to CPU
)
```

--------------------------------

### Specify Output Directory

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Direct prediction outputs to a custom directory by providing the desired path to the `output_dir` parameter. This helps organize processed files.

```python
pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    output_dir="/path/to/output",
)
```

--------------------------------

### Reduce GPU Memory Usage

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/troubleshooting.md.txt

Set batch_size to 1 and offload mosaicking to the CPU to reduce GPU memory consumption.

```python
pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    batch_size=1,
    mosaic_device="cpu",
)
```

--------------------------------

### load_multiband

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

Loads a multiband GeoTIFF file. It supports optional resampling and band ordering for specific band extraction (e.g., Red, Green, NIR).

```APIDOC
## load_multiband

### Description
Loads a multiband GeoTIFF file. It supports optional resampling and band ordering for specific band extraction (e.g., Red, Green, NIR).

### Method
```python
omnicloudmask.load_multiband(
    input_path,
    resample_res=None,
    band_order=None,
)
```

### Parameters
#### Path Parameters
- **input_path** (Path or str) - Required - Path to GeoTIFF file

#### Query Parameters
- **resample_res** (float) - Optional - Target resolution for resampling
- **band_order** (list[int]) - Optional - 1-indexed band numbers for Red, Green, NIR. Warns and defaults to `[1, 2, 3]` if not provided

### Returns
- **Tuple** - A tuple containing a NumPy array and a rasterio Profile object.
```

--------------------------------

### Export Confidence Maps

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Generate probability scores instead of binary class predictions by setting `export_confidence=True` and `softmax_output=True`. The output will have an additional channel per class.

```python
mask = predict_from_array(
    input_array,
    export_confidence=True,
    softmax_output=True,  # normalize to probabilities
)
# Output shape: (4, height, width) - one channel per class
```

--------------------------------

### Force Inference Device

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Override the default device selection (CUDA > MPS > CPU) by explicitly setting the inference device. Useful for testing or specific hardware configurations.

```python
from omnicloudmask import predict_from_array

# Force CPU
mask = predict_from_array(input_array, inference_device="cpu")

# Force CUDA
mask = predict_from_array(input_array, inference_device="cuda")

# Force Apple Silicon MPS
mask = predict_from_array(input_array, inference_device="mps")
```

--------------------------------

### Predict Cloud Mask from Numpy Array

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/quickstart.md.txt

Use `predict_from_array` when your image data is already loaded as a numpy array with Red, Green, and NIR bands. The output mask contains values indicating clear, thick cloud, thin cloud, or cloud shadow.

```python
import numpy as np
from omnicloudmask import predict_from_array

# Load your data as (3, height, width) array: Red, Green, NIR bands
input_array = np.random.rand(3, 1024, 1024).astype(np.float32)

# Run prediction
mask = predict_from_array(input_array)

# mask shape: (1, height, width)
# Values: 0=Clear, 1=Thick Cloud, 2=Thin Cloud, 3=Cloud Shadow
```

--------------------------------

### load_s2

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

Load Sentinel-2 L1C or L2A scenes from .SAFE directories. This function supports loading data at specified resolutions and with required bands.

```APIDOC
## load_s2

### Description
Load Sentinel-2 L1C or L2A scenes from `.SAFE` directories.

### Method
`omnicloudmask.load_s2`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input_path** (Path or str) - Required - Path to `.SAFE` directory
- **resolution** (float) - Optional - Default: `10.0` - Output resolution in meters (10-50)
- **required_bands** (list[str]) - Optional - Default: `["B04", "B03", "B8A"]` - Band names to load (Red, Green, NIR). B8A (20 m) is used instead of B08 (10 m) for faster loading due to smaller file size

### Request Example
None

### Response
#### Success Response (200)
Tuple of `(np.ndarray, rasterio.Profile)`.

#### Response Example
None
```

--------------------------------

### Predict with Missing NIR Band using predict_from_array

Source: https://omnicloudmask.readthedocs.io/en/latest/usage.html

Pass an array of zeros for the NIR channel when it's not available. This approach is robust and yields good cloud mask predictions.

```python
import numpy as np
from omnicloudmask import predict_from_array

# red and green are 2D arrays of shape (height, width)
nir_placeholder = np.zeros_like(red)

input_array = np.stack([red, green, nir_placeholder], axis=0)
mask = predict_from_array(input_array)

```

--------------------------------

### GPU Performance Optimization

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Enhance performance on NVIDIA GPUs by increasing batch size and enabling reduced precision (bf16). Compile models for further speedup on large datasets.

```python
from omnicloudmask import predict_from_load_func, load_s2

pred_paths = predict_from_load_func(
    scene_paths=scene_paths,
    load_func=load_s2,
    inference_dtype="bf16",
    batch_size=4,            # increase for GPUs with more VRAM
    compile_models=True,     # faster inference for 10+ scenes
)
```

--------------------------------

### Load Landsat 8 Imagery

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

Load Landsat 8 scenes, specifying the resolution and required bands. The resolution must be 30 meters, and it defaults to loading Red, Green, and NIR bands.

```python
omnicloudmask.load_ls8(
    input_path,
    resolution=30,
    required_bands=None,
)

```

--------------------------------

### Predict Cloud Mask from Landsat 8 Scene Files

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/quickstart.md.txt

Use `predict_from_load_func` with the `load_ls8` function to process Landsat 8 scene files directly. Predictions are automatically saved as GeoTIFFs alongside the input scenes.

```python
from pathlib import Path
from omnicloudmask import predict_from_load_func, load_ls8

scene_paths = [
    Path("path/to/LC08_scene1"),
    Path("path/to/LC08_scene2"),
]

pred_paths = predict_from_load_func(scene_paths, load_ls8)
```

--------------------------------

### Load Sentinel-2 Data

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/api.md.txt

Use this function to load Sentinel-2 L1C or L2A scenes from .SAFE directories. You can specify the output resolution and the required bands for processing.

```python
from pathlib import Path

omnicloudmask.load_s2(
    input_path,
    resolution=10.0,
    required_bands=None,
)
```

--------------------------------

### predict_from_load_func

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/api.md.txt

Predicts cloud masks for multiple scene files using a provided loading function and saves results as GeoTIFFs. It shares most parameters with `predict_from_array` and adds scene path and output directory configurations.

```APIDOC
## predict_from_load_func

### Description
Predict cloud masks for multiple scene files, saving results as GeoTIFFs. This function accepts a list of scene paths and a custom loading function, along with parameters similar to `predict_from_array`.

### Method
`omnicloudmask.predict_from_load_func(
    scene_paths,
    load_func,
    patch_size=1000,
    patch_overlap=300,
    batch_size=1,
    inference_device=None,
    mosaic_device=None,
    inference_dtype=torch.float32,
    export_confidence=False,
    softmax_output=True,
    no_data_value=0,
    overwrite=True,
    apply_no_data_mask=True,
    output_dir=None,
    custom_models=None,
    pred_classes=4,
    destination_model_dir=None,
    model_download_source="hugging_face",
    compile_models=False,
    compile_mode="default",
    model_version=None,
)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scene_paths** (`list[Path]` or `list[str]`) - Required - Paths to scene files or directories.
- **load_func** (`Callable`) - Required - Function that loads scene data (see Data Loaders).
- **patch_size** (`int`) - Optional - Size of patches for inference. Defaults to `1000`.
- **patch_overlap** (`int`) - Optional - Overlap between adjacent patches. Defaults to `300`.
- **batch_size** (`int`) - Optional - Number of patches per batch. Defaults to `1`.
- **inference_device** (`str` or `torch.device`) - Optional - Device for inference (`"cpu"`, `"cuda"`, `"mps"`). Auto-detected if `None`. Defaults to `None`.
- **mosaic_device** (`str` or `torch.device`) - Optional - Device for patch mosaicking. Defaults to `inference_device`.
- **inference_dtype** (`torch.dtype` or `str`) - Optional - Data type. Accepts `torch.float32`, `torch.float16`, `torch.bfloat16` or strings `"fp32"`, `"fp16"`, `"bf16"`. Defaults to `torch.float32`.
- **export_confidence** (`bool`) - Optional - Return confidence maps instead of class predictions. Defaults to `False`.
- **softmax_output** (`bool`) - Optional - Apply softmax to confidence output. Defaults to `True`.
- **no_data_value** (`int` or `float`) - Optional - Value indicating no-data pixels in input. Defaults to `0`.
- **overwrite** (`bool`) - Optional - Overwrite existing prediction files. Defaults to `True`.
- **apply_no_data_mask** (`bool`) - Optional - Mask no-data regions in output. Defaults to `True`.
- **output_dir** (`str` or `Path`) - Optional - Output directory. Defaults to same directory as input.
- **custom_models** (`torch.nn.Module` or `list`) - Optional - Custom model(s) instead of default. Defaults to `None`.
- **pred_classes** (`int`) - Optional - Number of output classes (for custom models). Defaults to `4`.
- **destination_model_dir** (`str` or `Path`) - Optional - Directory to cache downloaded models. Defaults to `None`.
- **model_download_source** (`str`) - Optional - Model source: `"hugging_face"` or `"google_drive"`. Defaults to `"hugging_face"`.
- **compile_models** (`bool`) - Optional - Compile models with torch.compile for faster inference. Defaults to `False`.
- **compile_mode** (`str`) - Optional - torch.compile mode. Defaults to `"default"`.
- **model_version** (`float`) - Optional - Model version (`1.0`, `2.0`, `3.0`, `4.0`). Latest if `None`. Defaults to `None`.

### Request Example
```python
from pathlib import Path

# Define a dummy load_func for demonstration
def my_load_func(path):
    # In a real scenario, this function would load and preprocess scene data
    return np.random.rand(3, 1000, 1000), None # Example: returns array and profile

scene_files = [Path("path/to/scene1.tif"), Path("path/to/scene2.tif")]
# output_paths = omnicloudmask.predict_from_load_func(scene_files, my_load_func)
```

### Response
#### Success Response
- **output_paths** (`list[Path]`) - List of output prediction file paths.

#### Response Example
```python
# Example: [Path("path/to/scene1_mask.tif"), Path("path/to/scene2_mask.tif")]
```
```

--------------------------------

### Check for Lint Errors with Ruff

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/contributing.md.txt

Use ruff to check the codebase for linting errors and style violations.

```bash
ruff check .
```

--------------------------------

### Predict Cloud Mask from Sentinel-2 Scene Files

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/quickstart.md.txt

Use `predict_from_load_func` with the `load_s2` function to process Sentinel-2 scene files directly. Predictions are automatically saved as GeoTIFFs alongside the input scenes.

```python
from pathlib import Path
from omnicloudmask import predict_from_load_func, load_s2

scene_paths = [
    Path("path/to/scene1.SAFE"),
    Path("path/to/scene2.SAFE"),
]

# Predictions saved as GeoTIFFs alongside input scenes
pred_paths = predict_from_load_func(scene_paths, load_s2)
```

--------------------------------

### Predict with Custom Trained Models

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Integrate your own trained PyTorch models using the `custom_models` parameter. Specify the number of output classes with `pred_classes`.

```python
import torch

my_model = torch.load("my_model.pt")

mask = predict_from_array(
    input_array,
    custom_models=my_model,
    pred_classes=4,  # number of output classes
)
```

--------------------------------

### Load Sentinel-2 Imagery

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

Load Sentinel-2 L1C or L2A scenes from .SAFE directories. This function allows specifying the output resolution and the required bands for loading, defaulting to Red, Green, and NIR bands.

```python
omnicloudmask.load_s2(
    input_path,
    resolution=10.0,
    required_bands=None,
)

```

--------------------------------

### Dynamic Z-score Normalization Concept

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/how-it-works.md.txt

This conceptual code illustrates the per-patch, per-channel normalization process. It normalizes each channel of an input patch to have zero mean and unit standard deviation.

```python
# Conceptually, for each patch and channel:
normalized = (patch - patch.mean()) / patch.std()
```

--------------------------------

### Predict with Older Model Versions

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/usage.md.txt

Use older model versions by specifying the `model_version` parameter. Versions 1-3 require the legacy extra.

```python
mask = predict_from_array(input_array, model_version=3.0)
```

--------------------------------

### Predict Cloud Mask from File Paths

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/api.md.txt

This function predicts cloud masks for multiple scenes specified by file paths, using a custom loading function. Results are saved as GeoTIFFs, with options to overwrite existing files and specify an output directory.

```python
import torch
from pathlib import Path
from typing import Callable

omnicloudmask.predict_from_load_func(
    scene_paths,
    load_func,
    patch_size=1000,
    patch_overlap=300,
    batch_size=1,
    inference_device=None,
    mosaic_device=None,
    inference_dtype=torch.float32,
    export_confidence=False,
    softmax_output=True,
    no_data_value=0,
    overwrite=True,
    apply_no_data_mask=True,
    output_dir=None,
    custom_models=None,
    pred_classes=4,
    destination_model_dir=None,
    model_download_source="hugging_face",
    compile_models=False,
    compile_mode="default",
    model_version=None,
)
```

--------------------------------

### Predict Cloud Mask from Scene Files

Source: https://omnicloudmask.readthedocs.io/en/latest/api.html

This function predicts cloud masks for multiple scene files using a provided loading function and saves the results as GeoTIFFs. It allows for custom data loading, output directory specification, and overwriting existing files.

```python
omnicloudmask.predict_from_load_func(
    scene_paths,
    load_func,
    patch_size=1000,
    patch_overlap=300,
    batch_size=1,
    inference_device=None,
    mosaic_device=None,
    inference_dtype=torch.float32,
    export_confidence=False,
    softmax_output=True,
    no_data_value=0,
    overwrite=True,
    apply_no_data_mask=True,
    output_dir=None,
    custom_models=None,
    pred_classes=4,
    destination_model_dir=None,
    model_download_source="hugging_face",
    compile_models=False,
    compile_mode="default",
    model_version=None,
)

```

--------------------------------

### Predict Cloud Mask from Numpy Array

Source: https://omnicloudmask.readthedocs.io/en/latest/_sources/api.md.txt

Use this function to predict a cloud mask directly from a numpy array representing Red, Green, and NIR bands. It supports various configurations for patch processing, device selection, and output formatting.

```python
import torch
import numpy as np

omnicloudmask.predict_from_array(
    input_array,
    patch_size=1000,
    patch_overlap=300,
    batch_size=1,
    inference_device=None,
    mosaic_device=None,
    inference_dtype=torch.float32,
    export_confidence=False,
    softmax_output=True,
    no_data_value=0,
    apply_no_data_mask=True,
    custom_models=None,
    pred_classes=4,
    destination_model_dir=None,
    model_download_source="hugging_face",
    compile_models=False,
    compile_mode="default",
    model_version=None,
)
```
Tokens:
Raw