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.
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.