Skip to main content

SDK

The fusion_sdk Python package is a client for interacting with Clarity programmatically. It can upload imagery, manage labels, download datasets and model artifacts, and read inference results from scripts and notebooks.

Available on request

The SDK is provisioned to specific customers and is not part of the standard platform package. Contact the Metaspectral team to request the wheel and a service token.

Install the SDK​

The SDK is distributed as a Python wheel named fusion_sdk-<version>-py3-none-any.whl. Install it in a Python 3.10 or newer virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install /path/to/fusion_sdk-<version>-py3-none-any.whl

On Windows, activate the environment with .venv\Scripts\activate.

Create a client​

Set a service token in your environment, then create the production client:

import os

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

sdk = FusionSDKV2(
service_token=os.environ["CLARITY_SERVICE_TOKEN"],
environment=SDKEnvironmentEnum.PROD,
)

FusionSDKV2 requires service_token and accepts optional environment and api_url arguments. Do not embed a service token in source control.

Download examples​

Wheels built from the current SDK source include the updated image, model, and inference download examples below. Older wheels may have examples with hardcoded configuration; use the client setup above and the module examples in that case. Set CLARITY_SERVICE_TOKEN and the relevant IDs (CLARITY_IMAGE_ID and/or CLARITY_MODEL_VERSION_ID) in your environment, then run:

python -m fusion_sdk.implementations_v2.examples.download_image
python -m fusion_sdk.implementations_v2.examples.download_modelversion
python -m fusion_sdk.implementations_v2.examples.download_inference_result

These examples use production. Downloads go beneath ./downloads by default; set CLARITY_DOWNLOAD_DIR to choose another destination. Image downloads request reflectance, so select an image with that processing level available.

Missing SDK attributes​

sdk.image.get(image_id=...) and sdk.model_version.get(model_version_id=...) are the supported download lookup methods. If either raises AttributeError, check the installed package and the code Python actually loaded in the same interpreter or notebook kernel:

import inspect
import sys
from importlib.metadata import version

# Inspect the same sdk object that raised the error.
print("Python:", sys.version, sys.executable)
print("fusion-sdk:", version("fusion-sdk"))
print("Client source:", inspect.getfile(type(sdk)))
print("Image available:", hasattr(sdk, "image"))
module = getattr(sdk, "model_version", None)
if module is not None:
print("Model module source:", inspect.getfile(type(module)))
print("Model get available:", callable(getattr(module, "get", None)))

Share this output with the Metaspectral team to identify the installed build. Install the supplied replacement wheel with the same interpreter:

python -m pip install --upgrade --force-reinstall /path/to/fusion_sdk-<version>-py3-none-any.whl

Restart a running notebook kernel after installation. If the printed source path points to a local checkout or another copy of fusion_sdk, run from a directory where that copy does not shadow the installed wheel.

Modules​

The client exposes five modules. Their get methods return resource objects with data fields and resource-specific actions.

  • Images: upload HSI files, inspect image metadata, attach labels, and download imagery.
  • Folders: traverse folders and download imagery beneath a folder.
  • Dataset versions: download ML datasets, labels, and train/validation/test splits.
  • Model versions: retrieve model versions, inspect inference results, and download model artifacts.
  • Class collections: create and inspect class collections and classes.