The ‘Geti’ class

Introduction

These pages contain the documentation for the main SDK class, Geti.

The Geti class implements convenience methods for common operations that can be performed on the Intel® Geti™ cluster, such as creating a project from a pre-existing dataset, downloading or uploading a project, uploading an image and getting a prediction for it and creating a deployment for a project.

For example, to download a project, simply do:

from geti_sdk import Geti

geti = Geti(
  host="https://0.0.0.0", username="dummy_user", password="dummy_password"
)

geti.download_project_data(project_name="dummy_project")

The Geti class provides a high-level interface for import-export operations in Intel® Geti™ platform. Here is a list of these operations: * Project download

download_project_data() method fetches the project data and creates a local Python object that supports a range of operations with the project.

  • Project upload

    upload_project_data() method uploads the project data from a local Python object to the Intel® Geti™ platform.

  • Batched project download and upload

    download_all_projects() and upload_all_projects() methods download and upload multiple projects at once.

  • Project export

    export_project() method exports the project snapshot to a zip archive. The archive can be used to import the project to another or the same Intel® Geti™ instance.

  • Project import

    import_project() method imports the project from a zip archive.

  • Dataset export

    export_dataset() method exports the dataset to a zip archive.

  • Dataset import

    import_dataset() method imports the dataset from a zip archive as a new project.

For custom operations or more fine-grained control over the behavior, the rest_clients subpackage should be used.

Module contents

class geti_sdk.geti.Geti(host: str | None = None, username: str | None = None, password: str | None = None, token: str | None = None, workspace_id: str | None = None, verify_certificate: bool = True, proxies: Dict[str, str] | None = None, server_config: ServerTokenConfig | ServerCredentialConfig | None = None)

Interact with an Intel® Geti™ server via the REST API.

The Geti class provides methods for project creation, downloading and uploading, as well as project deployment. Initializing the class will establish a HTTP session to the Intel® Geti™ server, and requires authentication.

NOTE: The Geti instance can either be initialized in the following ways:

  1. Using user credentials. This requires: host, username and password to

    be passed as input

  2. Using a personal access token. This requires: host and token to be

    passed as input

  3. Using a ServerTokenConfig

    or ServerCredentialConfig instance that contains the full configuration for the Geti server to communicate with. This requires server_config to be passed as input.

Arguments for either one of these options must be passed, otherwise a TypeError will be raised.

Parameters:

  • host – IP address or URL at which the cluster can be reached, for example ‘https://0.0.0.0’ or ‘https://sc_example.intel.com’

  • username – Username to log in to the cluster

  • password – Password to log in to the cluster

  • token – Personal access token that can be used for authentication

  • workspace_id – Optional ID of the workspace that should be addressed by this Geti instance. If not specified, the default workspace is used.

  • verify_certificate – True to verify the certificate used for making HTTPS requests encrypted using TLS protocol. If set to False, an InsecureRequestWarning will be issued since in this case requests made to the server may be compromised. This should only ever be set to False in a secure network environment.

  • proxies –

    Optional dictionary containing proxy information. For example {

    ’http’: http://proxy-server.com:<http_port_number>, ‘https’: http://proxy-server.com:<https_port_number>

    }, if set to None (the default), no proxy settings will be used.

  • server_config – ServerConfiguration instance holding the full details for the Geti server to communicate with

Project download and upload

download_project_data(project: Project, target_folder: str | None = None, include_predictions: bool = False, include_active_models: bool = False, include_deployment: bool = False, max_threads: int = 10) → Project

Download a project with name project_name to the local disk. All images, image annotations, videos and video frame annotations in the project are downloaded. By default, predictions and models are not downloaded, but they can be included by passing include_predictions=True and include_active_models=True, respectively.

In addition, if include_deployment is set to True, this method will create and download a deployment for the project as well.

This method will download data to the path target_folder, the contents of the folder will be:

images

Folder holding all images in the project, if any

videos

Folder holding all videos in the project, if any

annotations

Directory holding all annotations in the project, in .json format

predictions

Directory holding all predictions in the project, in .json format. If available, this will include saliency maps in .jpeg format. Only created if include_predictions=True

models

Folder containing the active model for the project. This folder contains zip files holding the data for the active models for the tasks in the project, and any optimized models derived from them. Models are only downloaded if include_active_models = True.

deployment

Folder containing the deployment for the project, that can be used for local inference. The deployment is only created if include_deployment = True.

project.json

File containing the project parameters, that can be used to re-create the project.

configuration.json

File containing the configurable parameters for the active models in the project

Downloading a project may take a substantial amount of time if the project dataset is large.

Parameters:

  • project – Project object to download

  • target_folder – Path to the local folder in which the project data should be saved. If not specified, a new directory will be created inside the current working directory. The name of the resulting directory will be the result of the concatenation of the project unique ID (24 characters) and the project name, i.e.: “{project.id}_{project.name}”

  • include_predictions – True to also download the predictions for all images and videos in the project, False to not download any predictions. If this is set to True but the project has no trained models, downloading predictions will be skipped.

  • include_active_models – True to download the active models for all tasks in the project, and any optimized models derived from them. False to not download any models. Defaults to False

  • include_deployment – True to create and download a deployment for the project, that can be used for local inference with OpenVINO. Defaults to False.

  • max_threads – Maximum number of threads to use for downloading. Defaults to 10. Set to -1 to use all available threads.

Returns:

Project object, holding information obtained from the cluster regarding the downloaded project

upload_project_data(target_folder: str, project_name: str | None = None, enable_auto_train: bool = True, max_threads: int = 5) → Project

Upload a previously downloaded Intel® Geti™ project to the server. This method expects the target_folder to contain the following:

images

Folder holding all images in the project, if any

videos

Folder holding all videos in the project, if any

annotations

Directory holding all annotations in the project, in .json format

project.json

File containing the project parameters, that can be used to re-create the project.

configuration.json

Optional file containing the configurable parameters for the active models in the project. If this file is not present, the configurable parameters for the project will be left at their default values.

Parameters:

  • target_folder – Folder holding the project data to upload

  • project_name – Optional name of the project to create on the cluster. If left unspecified, the name of the project found in the configuration in the target_folder will be used.

  • enable_auto_train – True to enable auto-training for all tasks directly after all annotations have been uploaded. This will directly trigger a training round if the conditions for auto-training are met. False to leave auto-training disabled for all tasks. Defaults to True.

  • max_threads – Maximum number of threads to use for uploading. Defaults to 5. Set to -1 to use all available threads.

Returns:

Project object, holding information obtained from the cluster regarding the uploaded project

download_all_projects(target_folder: str, include_predictions: bool = True) → List[Project]

Download all projects in the workspace from the Intel® Geti™ server.

Parameters:

  • target_folder – Directory on local disk to download the project data to. If not specified, this method will create a directory named ‘projects’ in the current working directory.

  • include_predictions – True to also download the predictions for all images and videos in the project, False to not download any predictions. If this is set to True but the project has no trained models, downloading predictions will be skipped.

Returns:

List of Project objects, each entry corresponding to one of the projects found on the Intel® Geti™ server

upload_all_projects(target_folder: str) → List[Project]

Upload all projects found in the directory target_folder on local disk to the Intel® Geti™ server.

This method expects the directory target_folder to contain subfolders. Each subfolder should correspond to the (previously downloaded) data for one project. The method looks for project folders non-recursively, meaning that only folders directly below the target_folder in the hierarchy are considered to be uploaded as project.

Parameters:

target_folder – Directory on local disk to retrieve the project data from

Returns:

List of Project objects, each entry corresponding to one of the projects uploaded to the Intel® Geti™ server.

import_project(filepath: PathLike, project_name: str | None = None) → Project

Import a project from the zip file specified by filepath to the Intel® Geti™ server. The project will be created on the server with the name project_name, if specified, esle with the archive base name. > Note: The project zip archive should be exported from the Geti™ server of the same version.

Parameters:

  • filepath – Path to the file to import the project from

  • project_name – Optional name of the project to create on the cluster. If left unspecified, the name of the archive file will be used.

Returns:

Project object, holding information obtained from the cluster regarding the uploaded project.

export_project(filepath: PathLike, project: Project) → None

Export a project with name project_name to the file specified by filepath. The project will be saved in a .zip file format, containing all project data and metadata required for project import to another instance of the Intel® Geti™ platform.

Parameters:

  • filepath – Path to the file to save the project to

  • project – Project object to export

Dataset export

export_dataset(project: Project, dataset: Dataset, filepath: PathLike, export_format: str | DatasetFormat = 'DATUMARO', include_unannotated_media: bool = False)

Export a dataset from a project to a file specified by filepath. The dataset will be saved in the format specified by export_format.

Parameters:

  • project – Project object to export the dataset from

  • dataset – Dataset object to export

  • filepath – Path to the file to save the dataset to

  • export_format – Format to save the dataset in. Provide on of the following strings: ‘COCO’, ‘YOLO’, ‘VOC’, ‘DATUMARO’ or a corresponding DatasetFormat object.

  • include_unannotated_media – True to include media that have no annotations in the dataset, False to only include media with annotations. Defaults to False.

Project creation from dataset

create_single_task_project_from_dataset(project_name: str, project_type: str, path_to_images: str, annotation_reader: AnnotationReader, labels: List[str | dict] | None = None, number_of_images_to_upload: int = -1, number_of_images_to_annotate: int = -1, enable_auto_train: bool = True, upload_videos: bool = False, max_threads: int = 5) → Project

Create a single task project named project_name on the Intel® Geti™ server, and upload data from a dataset on local disk.

The type of task that will be in the project can be controlled by setting the project_type, options are:

  • classification

  • detection

  • segmentation

  • anomaly_classification

  • anomaly_detection

  • anomaly_segmentation

  • anomaly (new task - anomaly classification)

  • instance_segmentation

  • rotated_detection

If a project called project_name exists on the server, this method will attempt to upload the media and annotations to the existing project.

Parameters:

  • project_name – Name of the project to create

  • project_type – Type of the project, this determines which task the project will perform. See above for possible values

  • path_to_images – Path to the folder holding the images on the local disk. See above for details.

  • annotation_reader – AnnotationReader instance that will be used to obtain annotations for the images.

  • labels – Optional list of labels to use. This will only be used if the annotation_reader that is passed also supports dataset filtering. If not specified, all labels that are found in the dataset are used.

  • number_of_images_to_upload – Optional integer specifying how many images should be uploaded. If not specified, all images found in the dataset are uploaded.

  • number_of_images_to_annotate – Optional integer specifying how many images should be annotated. If not specified, annotations for all images that have annotations available will be uploaded.

  • enable_auto_train – True to enable auto-training for all tasks directly after all annotations have been uploaded. This will directly trigger a training round if the conditions for auto-training are met. False to leave auto-training disabled for all tasks. Defaults to True.

  • upload_videos – True to upload any videos found in the path_to_images folder.

  • max_threads – Maximum number of threads to use for uploading. Defaults to 5. Set to -1 to use all available threads.

Returns:

Project object, holding information obtained from the cluster regarding the uploaded project

create_task_chain_project_from_dataset(project_name: str, project_type: str, path_to_images: str, label_source_per_task: List[AnnotationReader | List[str]], number_of_images_to_upload: int = -1, number_of_images_to_annotate: int = -1, enable_auto_train: bool = True, max_threads: int = 5) → Project

Create a single task project named project_name on the Intel® Geti™ cluster, and upload data from a dataset on local disk.

The type of task that will be in the project can be controlled by setting the project_type, current options are:

  • detection_to_segmentation

  • detection_to_classification

If a project called project_name exists on the server, this method will attempt to upload the media and annotations to the existing project.

Parameters:

  • project_name – Name of the project to create

  • project_type – Type of the project, this determines which task the project will perform. See above for possible values

  • path_to_images – Path to the folder holding the images on the local disk. See above for details.

  • label_source_per_task –

    List containing the label sources for each task in the task chain. Each entry in the list corresponds to the label source for one task. The list can contain either AnnotationReader instances that will be used to obtain the labels for a task, or it can contain a list of labels to use for that task.

    For example, in a detection -> classification project we may have labels for the first task (for instance ‘dog’), but no annotations for the second task yet (e.g. [‘small’, ‘large’]). In that case the label_source_per_task should contain:

    [AnnotationReader(), [‘small’, ‘large’]]

    Where the annotation reader has been properly instantiated to read the annotations for the ‘dog’ labels.

  • number_of_images_to_upload – Optional integer specifying how many images should be uploaded. If not specified, all images found in the dataset are uploaded.

  • number_of_images_to_annotate – Optional integer specifying how many images should be annotated. If not specified, annotations for all images that have annotations available will be uploaded.

  • enable_auto_train – True to enable auto-training for all tasks directly after all annotations have been uploaded. This will directly trigger a training round if the conditions for auto-training are met. False to leave auto-training disabled for all tasks. Defaults to True.

  • max_threads – Maximum number of threads to use for uploading. Defaults to 5. Set to -1 to use all available threads.

Returns:

Project object, holding information obtained from the cluster regarding the uploaded project

import_dataset(filepath: PathLike, project_name: str, project_type: str) → Project

Import a dataset from the zip archive specified by filepath to the Intel® Geti™ server. A new project will be created from the dataset on the server with the name project_name. Please set the project_type to determine the type of the project with one of possible values are:

  • classification

  • classification_hierarchical

  • detection

  • segmentation

  • instance_segmentation

  • anomaly_classification

  • anomaly_detection

  • anomaly_segmentation

  • anomaly (choose this working with SaaS)

  • detection_oriented

  • detection_to_classification

  • detection_to_segmentation

> Note: The dataset zip archive should be exported from the Geti™ server of the same version.

Parameters:

  • filepath – Path to the file to import the dataset from

  • project_name – Name of the project to create on the cluster

  • project_type – Type of the project, this determines which task the project will perform.

Returns:

Project object, holding information obtained from the cluster regarding the uploaded project.

Project deployment

deploy_project(project: Project, output_folder: str | PathLike | None = None, models: Sequence[BaseModel] | None = None, enable_explainable_ai: bool = False, prepare_ovms_config: bool = False) → Deployment

Deploy a project by creating a Deployment instance. The Deployment contains the optimized models for each task in the project, and can be loaded with OpenVINO to run inference locally.

By default, this method creates a deployment using the current active model for each task in the project. However, it is possible to specify a particular model to use, by passing it in the list of models as input to this method.

Parameters:

  • project – Project object to deploy

  • output_folder – Path to a folder on local disk to which the Deployment should be downloaded. If no path is specified, the deployment will not be saved.

  • models – Optional list of models to use in the deployment. This must contain at most one model for each task in the project. If for a certain task no model is specified, the currently active model for that task will be used in the deployment. The order in which the models are passed does not matter

  • enable_explainable_ai – True to include an Explainable AI head in the deployment. This will add an Explainable AI head to the model for each task in the project, allowing for the generation of saliency maps.

  • prepare_ovms_config – True to prepare the deployment to be hosted on a OpenVINO model server (OVMS). Passing True will create OVMS configuration files for the model(s) in the project and a README containing the steps to launch an OVMS container serving the models.

Returns:

Deployment for the project

Media upload and prediction

upload_and_predict_image(project: Project, image: ndarray | Image | VideoFrame | str | PathLike, visualise_output: bool = True, delete_after_prediction: bool = False, dataset_name: str | None = None) → Tuple[Image, Prediction]

Upload a single image to a project on the Intel® Geti™ server, and return a prediction for it.

Parameters:

  • project – Project object to upload the image to

  • image – Image, numpy array representing an image, or filepath to an image to upload and get a prediction for

  • visualise_output – True to show the resulting prediction, overlayed on the image

  • delete_after_prediction – True to remove the image from the project once the prediction is received, False to keep the image in the project.

  • dataset_name – Optional name of the dataset to which to upload the image. The dataset must already exist in the project

Returns:

Tuple containing:

  • Image object representing the image that was uploaded

  • Prediction for the image

upload_and_predict_video(project: Project, video: Video | str | PathLike | Sequence[ndarray] | ndarray, frame_stride: int | None = None, visualise_output: bool = True, delete_after_prediction: bool = False) → Tuple[Video, MediaList[VideoFrame], List[Prediction]]

Upload a single video to a project on the Intel® Geti™ server, and return a list of predictions for the frames in the video.

The parameter ‘frame_stride’ is used to control the stride for frame extraction. Predictions are only generated for the extracted frames. So to get predictions for all frames, frame_stride=1 can be passed.

Parameters:

  • project – Project to upload the video to

  • video – Video or filepath to a video to upload and get predictions for. Can also be a 4D numpy array or a list of 3D numpy arrays, shaped such that the array dimensions represent frames x width x height x channels, i.e. each entry holds the pixel data for a video frame.

  • frame_stride – Frame stride to use. This determines the number of frames that will be extracted from the video, and for which predictions will be generated

  • visualise_output – True to show the resulting prediction, overlayed on the video frames.

  • delete_after_prediction – True to remove the video from the project once the prediction is received, False to keep the video in the project.

Returns:

Tuple containing:

  • Video object holding the data for the uploaded video

  • List of VideoFrames extracted from the video, for which predictions have been generated

  • List of Predictions for the Video

upload_and_predict_media_folder(project: Project, media_folder: str, output_folder: str | None = None, delete_after_prediction: bool = False, skip_if_filename_exists: bool = False, max_threads: int = 5) → bool

Upload a folder with media (images, videos or both) from local disk at path target_folder to the project provided with the project argument on the Intel® Geti™ server. After the media upload is complete, predictions will be downloaded for all media in the folder. This method will create a ‘predictions’ directory in the target_folder, containing the prediction output in json format.

If delete_after_prediction is set to True, all uploaded media will be removed from the project on the Intel® Geti™ server after the predictions have been downloaded.

Parameters:

  • project – Project object to upload the media to

  • media_folder – Path to the folder to upload media from

  • output_folder – Path to save the predictions to. If not specified, this method will create a folder named ‘<media_folder_name>_predictions’ on the same level as the media_folder

  • delete_after_prediction – True to remove the media from the project once all predictions are received, False to keep the media in the project.

  • skip_if_filename_exists – Set to True to skip uploading of an image (or video) if an image (or video) with the same filename already exists in the project. Defaults to False

  • max_threads – Maximum number of threads to use for uploading. Defaults to 5. Set to -1 to use all available threads.

Returns:

True if all media was uploaded, and predictions for all media were successfully downloaded. False otherwise