Skip to main content


A SingleFrame contains metadata pointing to raw data, and other metadata and data, which supports experimentation and ClearML Enterprise's Git-like Hyper-Dataset versioning.

Frame Components#

A SingleFrame contains the following components:


Every SingleFrame includes a sources dictionary, which contains attributes of the raw data, including:

  • URI pointing to the source data (image or video)
  • Sources for masks used in semantic segmentation
  • Image previews, which are thumbnails used in the WebApp (UI).

For more information, see Sources.


Each SingleFrame contains a list of dictionaries, where each dictionary includes information about a specific annotation.

Two types of annotations are supported:

  • FrameGroup objects - label for Regions of Interest (ROIs)
  • FrameGroup labels - labels for the entire frame

For more information, see Annotations.


A SingleFrame includes a URI link to a mask file if applicable. Masks correspond to raw data where the objects to be detected in raw data are marked with colors in the masks.

For more information, see Masks.


previews is a dictionary containing metadata for optional thumbnail images that can be used in the ClearML Enterprise WebApp (UI) to view selected images in a Hyper-Dataset. previews includes the uri of the thumbnail image.

For more information, see Previews.


metadata is a dictionary with general information about the SingleFrame.

For more information, see Custom Metadata.

Frame Structure#

The panel below describes the details contained within a frame:

Frame Structure
  • id (string) - The unique ID of this frame.

  • blob (string) - Raw data.

  • context_id (string) - Source URL.

  • dataset (dict) - The Hyper-Dataset and version containing the frame.

    • id - ID of the Hyper-Dataset.
    • version - ID of the version.
  • meta (dict) - Frame custom metadata. Any custom key-value pairs (sources and rois can also contain a meta dictionary for custom key-value pairs associated with individual sources and rois). See Custom Metadata.

  • num_frames

  • rois ([dict]) - Metadata for annotations, which can be Regions of Interest (ROIs) related to this frame's source data, or frame labels applied to the entire frame (not a region). ROIs are labeled areas bounded by polygons or labeled RGB values used for object detection and segmentation. See Annotations.

    • id - ID of the ROI.

    • confidence (float) - Confidence level of the ROI label (between 0 and 1.0).

    • labels ([string])

    • mask (dict) - RGB value of the mask applied to the ROI, if a mask is used (for example, for semantic segmentation). The ID points to the source of the mask.

      • id - ID of the mask dictionary in sources.
      • value - RGB value of the mask.
    • poly ([int]) - Bounding area vertices.

    • sources ([string]) - The id in the sources dictionary which relates an annotation to its raw data source.

  • sources ([dict]) - Sources of the raw data in this frame. For a SingleFrame this is one source. For a FrameGroup, this is multiple sources. See Sources.

    • id - ID of the source.

    • uri - URI of the raw data.

    • width - Width of the image or video.

    • height - Height of the image or video.

    • mask - Sources of masks used in the rois.

      • id - ID of the mask source. This relates a mask source to an ROI.
      • content_type - The type of mask source. For example, image/jpeg.
      • uri - URI of the mask source.
      • timestamp
    • preview - URI of the thumbnail preview image used in the ClearML Enterprise WebApp (UI)

    • timestamp - For images from video, a timestamp that indicates the absolute position of this frame from the source (video). For example, if video from a camera on a car is taken at 30 frames per second, it would have a timestamp of 0 for the first frame, and 33 for the second frame. For still images, set this to 0.

  • saved_in_version - The version in which the frame is saved.

  • saved - The epoch time that the frame was saved.

  • timestamp - For images from video, a timestamp that indicates the absolute position of this frame from the source (video).


A frame that has been connected to the ClearML Enterprise platform is available to view and analyze on the WebApp (UI).

When viewing a frame on the WebApp, all the information associated with it can be viewed, including its frame labels and object annotations, its metadata, and other details.

SingleFrame in the WebApp frame viewer

This image shows a SingleFrame in the ClearML Enterprise WebApp (UI) frame viewer.


SingleFrame details represented in the WebApp
id : "287024"
timestamp : 0
rois : Array[2] [
"label":["tennis racket"],
sources : Array[1] [
dataset : Object
context_id :
saved : 1598982880693
saved_in_version : "6ad8b10c668e419f9dd40422f667592c"
num_frames : 1

For more information about using Frames in the WebApp, see Working with Frames.


Creating a SingleFrame#

To create a SingleFrame, instantiate a SingleFrame class and populate it with:

  • The URI link to the source file of the data frame
  • A preview URI that is accessible by browser, so you will be able to visualize the data frame in the web UI
from allegroai import SingleFrame
frame = SingleFrame(

There are also options to populate the instance with:

  • Dimensions - width and height
  • General information about the frame - metadata
  • A dictionary of annotation objects - annotations
  • A URI link to a mask file for the frame - mask_source

For more information, see the SingleFrame class description.

Adding SingleFrames to a Dataset Version#

Use the DatasetVersion.add_frames method to add SingleFrames to a Dataset version (see Creating snapshots or Creating child versions).

from allegroai import DatasetVersion, SingleFrame
# a frames list is required for adding frames
frames = []
# create a frame
frame = SingleFrame(
# add frame to the Dataset version

Accessing SingleFrames#

To access a SingleFrame, use the DatasetVersion.get_single_frame method.

from allegroai import DatasetVersion
frame = DatasetVersion.get_single_frame(
dataset_name='MyDataset', # OR dataset_id='80ccb3ae11a74b91b1c6f25f98539039'
version_name='SingleFrame' # OR version_id='b07b626e3b6f4be7be170a2f39e14bfb'

To access a SingleFrame, the following must be specified:

  • frame_id, which can be found in the WebApp, in the frame's FRAMEGROUP DETAILS
  • The frame's dataset - either with dataset_name or dataset_id
  • The dataset version - either with version_id or version_name

Updating SingleFrames#

To update a SingleFrame:

frames = []
# get the SingleFrame
frame = DatasetVersion.get_single_frame(
# make changes to the frame
## add a new annotation
poly2d_xy=[154, 343, 209, 343, 209, 423, 154, 423],
metadata={'alive': 'no'},
## add metadata
frame.meta['road_hazard'] = 'yes'
# update the SingeFrame

Deleting Frames#

To delete a SingleFrame, use the DatasetVersion.delete_frames method.

frames = []
# get the SingleFrame
frame = DatasetVersion.get_single_frame(
# delete the SingleFrame