### Install Fusion SDK

Source: https://docs.fusion.metaspectral.com/sdk

Install the Fusion SDK using pip after creating and activating a virtual environment. Replace the placeholder path with the actual path to the downloaded wheel file.

```bash
python -m venv .venv
source .venv/bin/activate            # on Windows: .venv\Scripts\activate  
pip install /path/to/fusion_sdk-<version>-py3-none-any.whl  
```

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

### Get Folder and Download Imagery

Source: https://docs.fusion.metaspectral.com/sdk-folders

Retrieves a specific folder by its ID and demonstrates how to list images within it and download the folder contents recursively.

```python
folder = sdk.folder.get(folder_id=19)  
  
# List the imagery directly under the folder  
for image in folder.images:  
    print(image.id, image.name)  
  
# Download the folder and all subfolders  
folder.download(folder_path="/local/downloads", recursive=True)  

```

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

### Get and Inspect Dataset Version

Source: https://docs.fusion.metaspectral.com/sdk-dataset-versions

Retrieve a specific dataset version, print training image IDs and class index map, and inspect the first label's mask shape. This is useful for understanding the structure and content of a dataset version.

```python
dataset_version = sdk.dataset_version.get(dataset_version_id=2929)
  
print("Train images:", dataset_version.train_image_ids)
print("Class index map:", dataset_version.class_id_to_index_map)
  
# Inspect an individual label mask  
first_label = dataset_version.labels[0]
print(first_label.class_name, first_label.mask.shape)
  
dataset_version.download(folder_path="/local/downloads/datasets")
```

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

### Initialize Fusion SDK Client

Source: https://docs.fusion.metaspectral.com/sdk

Create an instance of the FusionSDKV2 client using your service token and the desired environment. Ensure you have the necessary imports for SDKEnvironmentEnum and FusionSDKV2.

```python
from fusion_sdk.implementations_v2.common.enums import SDKEnvironmentEnum  
from fusion_sdk.implementations_v2.FusionSDKV2 import FusionSDKV2  

sdk = FusionSDKV2(  
    service_token="<your-service-token>",  
    environment=SDKEnvironmentEnum.PROD,  
)  
```

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

### Upload, Attach Shapefiles, and Download Hyperspectral Image

Source: https://docs.fusion.metaspectral.com/sdk-images

This snippet demonstrates uploading a hyperspectral image with specific processing levels and GeoTIFF source, attaching shapefiles, and then downloading the image. Ensure the SDK is configured and necessary file paths are valid.

```python
from fusion_sdk.models.data_source_enum import DataSourceEnum
from fusion_sdk.models.hsi_processing_level_enum import HsiProcessingLevelEnum

image = sdk.image.upload(
    file_paths=[
        "/path/to/METADATA.XML",
        "/path/to/SPECTRAL_IMAGE.TIF",
    ],
    name="imported_enmap",
    folder_id=19,
    processing_level=HsiProcessingLevelEnum.RADIANCE,
    geotiff_source=DataSourceEnum.ENMAP,
)

image.upload_shapefiles(
    workspace_id=8,
    shapefile_paths=["/path/to/polygon.shp", "/path/to/polygon.shx"],
)

image.download(folder_path="/local/downloads")

```

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

### Default Pipeline for Source Data

Source: https://docs.fusion.metaspectral.com/spectral-explorer-filter-masks

Illustrates the default processing flow for source data, showing how image masks are utilized.

```text
image data -> image masks used in processing -> downstream products
```

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

### Create and Inspect a Class Collection

Source: https://docs.fusion.metaspectral.com/sdk-class-collections

Use this snippet to create a new class collection, add classes to it, and then iterate through the classes to print their IDs and names. Ensure the SDK is initialized before use.

```python
collection = sdk.class_collection.create_class_collection(name="Land cover")  

collection.create_class(name="Water")  
collection.create_class(name="Vegetation")  

for cls in collection.get_classes():  
    print(cls.id, cls.name)  

```

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

### Fetch and Download Model, Inspect Inference Results, and List Models by Date Range

Source: https://docs.fusion.metaspectral.com/sdk-model-versions

This snippet demonstrates fetching a specific model version, downloading its artifacts, iterating through its inference results to retrieve and print classified data, and listing models trained within a specified date range while excluding drafts. It requires importing datetime and ThresholdingModeEnum.

```python
from datetime import datetime
from fusion_sdk.models.thresholding_mode_enum import ThresholdingModeEnum

# Fetch a single model
model = sdk.model_version.get(model_version_id=38)
model.download(folder_path="/local/downloads/models")

# Inspect inference results
for inference_result in model.inference_results:
    classified = inference_result.get_data(
        threshold_start=0.2,
        threshold_end=0.8,
        threshold_mode=ThresholdingModeEnum.CLASSIFY,
    )
    print(inference_result.image_id, classified.shape)

# List models trained in a date range
recent = sdk.model_version.get_by_date_range(
    model_trained_after=datetime(2025, 1, 1),
    model_trained_before=datetime(2025, 12, 31),
    exclude_draft=True,
)
```

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

### Dataset Finalization Pipeline

Source: https://docs.fusion.metaspectral.com/datasets-filter-masks

Illustrates the standard pipeline for dataset finalization, showing how image data is processed through image masks to create dataset samples.

```text
image data -> image masks used in processing -> dataset samples
```

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

### sdk.image.upload

Source: https://docs.fusion.metaspectral.com/sdk-images

Imports Hyperspectral Imaging (HSI) files into a specified folder, supporting GeoTIFF sources and processing levels.

```APIDOC
## upload(file_paths, name, folder_id, geotiff_source, processing_level)

### Description
Import HSI files into a folder. Supports GeoTIFF sources (e.g. ENMAP) and processing levels such as `RADIANCE` and `REFLECTANCE`.

### Method
POST (assumed based on 'upload' operation)

### Endpoint
`/images/upload` (assumed based on common REST patterns for upload operations)

### Parameters
#### Request Body
- **file_paths** (list of strings) - Required - A list of paths to the HSI files to upload (e.g., metadata and spectral image files).
- **name** (string) - Required - The desired name for the imported image.
- **folder_id** (integer) - Required - The ID of the folder where the image should be imported.
- **processing_level** (string) - Optional - The processing level of the HSI data (e.g., `RADIANCE`, `REFLECTANCE`).
- **geotiff_source** (string) - Optional - The source format of the GeoTIFF data (e.g., `ENMAP`).

### Request Example
```json
{
  "file_paths": [
    "/path/to/METADATA.XML",
    "/path/to/SPECTRAL_IMAGE.TIF"
  ],
  "name": "imported_enmap",
  "folder_id": 19,
  "processing_level": "RADIANCE",
  "geotiff_source": "ENMAP"
}
```

### Response
#### Success Response (200)
- **ImageResource** - An object representing the uploaded hyperspectral image.
```

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

### sdk.class_collection.create_class_collection(name)

Source: https://docs.fusion.metaspectral.com/sdk-class-collections

Creates a new class collection with the specified name.

```APIDOC
## create_class_collection(name)

### Description
Creates a new class collection with the specified name.

### Method
```
create_class_collection(name)
```

### Parameters
#### Path Parameters
- **name** (string) - Required - The name for the new class collection.
```

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

### FolderResource.download()

Source: https://docs.fusion.metaspectral.com/sdk-folders

Downloads the contents of a folder, optionally including all subfolders recursively. This method allows for bulk downloading of imagery.

```APIDOC
## FolderResource.download(folder_path, recursive)

### Description
Downloads the contents of a folder, optionally including all subfolders recursively. This method allows for bulk downloading of imagery.

### Method
```
POST
```

### Endpoint
```
/folders/{folder_id}/download
```

### Parameters
#### Path Parameters
- **folder_id** (int) - Required - The unique identifier for the folder to download.

#### Query Parameters
- **folder_path** (string) - Required - The local path where the folder contents should be saved.
- **recursive** (boolean) - Optional - If True, downloads all subfolders and their contents. Defaults to False.

### Request Example
```python
folder.download(folder_path="/local/downloads", recursive=True)
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the download process has started or completed.

#### Response Example
```json
{
  "message": "Download initiated for folder ID 19."
}
```
```

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

### sdk.image.get

Source: https://docs.fusion.metaspectral.com/sdk-images

Fetches a single hyperspectral image using its unique identifier.

```APIDOC
## get(image_id)

### Description
Fetch a single image as an `ImageResource`.

### Method
GET (assumed based on 'fetch' operation)

### Endpoint
`/images/{image_id}` (assumed based on common REST patterns for fetching resources by ID)

### Parameters
#### Path Parameters
- **image_id** (string) - Required - The unique identifier of the image to fetch.

### Response
#### Success Response (200)
- **ImageResource** - An object representing the fetched hyperspectral image.
```

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

### sdk.image.get_by_ids

Source: https://docs.fusion.metaspectral.com/sdk-images

Fetches multiple hyperspectral images using a list of their unique identifiers.

```APIDOC
## get_by_ids(image_ids)

### Description
Fetch many images at once.

### Method
GET (assumed based on 'fetch' operation)

### Endpoint
`/images?ids={image_ids}` (assumed based on common REST patterns for fetching multiple resources by IDs)

### Parameters
#### Query Parameters
- **image_ids** (list of strings) - Required - A list of unique identifiers for the images to fetch.

### Response
#### Success Response (200)
- **list of ImageResource** - A list of objects representing the fetched hyperspectral images.
```

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

### sdk.model_version.get

Source: https://docs.fusion.metaspectral.com/sdk-model-versions

Fetches a single model version by its ID.

```APIDOC
## sdk.model_version.get

### Description
Fetches a single model version using its unique identifier.

### Method
`get(model_version_id)`

### Parameters
#### Path Parameters
- **model_version_id** (int) - Required - The ID of the model version to retrieve.

### Response
#### Success Response
- Returns a `ModelVersionResource` object representing the requested model version.
```

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

### sdk.model_version.get_by_date_range

Source: https://docs.fusion.metaspectral.com/sdk-model-versions

Lists model versions trained within a specified date range.

```APIDOC
## sdk.model_version.get_by_date_range

### Description
Lists model versions that were trained within a given date range. Optionally excludes draft models.

### Method
`get_by_date_range(model_trained_after, model_trained_before, exclude_draft=False)`

### Parameters
#### Query Parameters
- **model_trained_after** (datetime) - Required - The start date for the training period.
- **model_trained_before** (datetime) - Required - The end date for the training period.
- **exclude_draft** (bool) - Optional - If True, excludes draft model versions from the results. Defaults to False.

### Response
#### Success Response
- Returns a list of `ModelVersionResource` objects trained within the specified date range.
```

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

### sdk.class_collection.get(id)

Source: https://docs.fusion.metaspectral.com/sdk-class-collections

Fetches a class collection by its unique identifier.

```APIDOC
## get(id)

### Description
Fetches a class collection by its unique identifier.

### Method
```
get(id)
```

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the class collection to fetch.
```

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

### sdk.folder.get(folder_id)

Source: https://docs.fusion.metaspectral.com/sdk-folders

Retrieves a specific folder resource using its ID. This method returns a FolderResource object which contains details about the folder and its contents.

```APIDOC
## sdk.folder.get(folder_id)

### Description
Retrieves a specific folder resource using its ID. This method returns a FolderResource object which contains details about the folder and its contents.

### Method
```
GET
```

### Endpoint
```
/folders/{folder_id}
```

### Parameters
#### Path Parameters
- **folder_id** (int) - Required - The unique identifier for the folder.

### Response
#### Success Response (200)
- **FolderResource** - An object representing the folder with its properties and associated imagery.

### Request Example
```python
folder = sdk.folder.get(folder_id=19)
```

### Response Example
```json
{
  "id": 19,
  "name": "Example Folder",
  "images": [
    {
      "id": 101,
      "name": "image1.jpg"
    },
    {
      "id": 102,
      "name": "image2.png"
    }
  ]
}
```
```

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

### sdk.dataset_version.get

Source: https://docs.fusion.metaspectral.com/sdk-dataset-versions

Retrieves a specific dataset version resource using its ID. This method allows access to dataset labels, image IDs, and class mappings.

```APIDOC
## sdk.dataset_version.get(dataset_version_id)

### Description
Retrieves a specific dataset version resource using its ID. This method allows access to dataset labels, image IDs, and class mappings.

### Method
GET (conceptual)

### Endpoint
/dataset_versions/{dataset_version_id}

### Parameters
#### Path Parameters
- **dataset_version_id** (int) - Required - The unique identifier for the dataset version.

### Response
#### Success Response (200)
- **DatasetVersionResource** - An object containing information about the dataset version, including train/validation/test splits, class mappings, and labels.

### Request Example
```python
dataset_version = sdk.dataset_version.get(dataset_version_id=2929)
```

### Response Example
```json
{
  "train_image_ids": [1, 2, 3],
  "class_id_to_index_map": {"car": 0, "person": 1},
  "labels": [
    {
      "mask": "[[0, 1], [1, 0]]",
      "image_id": 1,
      "class_id": 0,
      "class_name": "car",
      "image_height": 100,
      "image_width": 100
    }
  ]
}
```
```