单帧

一个SingleFrame包含指向原始数据的元数据，以及其他元数据和数据，这些数据支持实验和ClearML Enterprise的类似Git的超数据集版本控制。

框架组件

一个SingleFrame包含以下组件：

来源
注释
口罩
预览
元数据
Context ID

来源

每个 SingleFrame 都包含一个 sources 字典，其中包含原始数据的属性，包括：

指向源数据（图像或视频）的URI
Mask source for semantic segmentation
图像预览，这是在WebApp（用户界面）中使用的缩略图。

欲了解更多信息，请参阅Sources。

注释

每个SingleFrame包含一个字典列表，其中每个字典包含有关特定注释的信息。

支持两种类型的注释：

FrameGroup 对象 - 用于标记感兴趣区域（ROIs）的标签
FrameGroup 标签 - 整个框架的标签

欲了解更多信息，请参阅Annotations。

口罩

如果适用，SingleFrame可以包含指向掩码文件的URI链接。掩码对应于原始数据，其中要检测的对象在掩码中用颜色或不同的不透明度级别标记。

欲了解更多信息，请参阅Masks。

预览

previews 是一个包含可选缩略图图像元数据的字典，这些缩略图可以在 ClearML Enterprise WebApp（UI）中使用，以查看在超数据集中选择的图像。previews 包括缩略图图像的 uri。

欲了解更多信息，请参阅Previews。

元数据

metadata 是一个包含有关 SingleFrame 的一般信息的字典。

欲了解更多信息，请参阅自定义元数据。

上下文ID

Frames的context_id属性有助于将SingleFrames和FrameGroups分组。当未明确定义context_id时，将使用帧的源URI代替。

当你向服务器查询帧时（例如使用DataView.get_iterator()），返回的帧会根据它们的context_id进行分组，并在它们的上下文组中根据timestamp进行排序。

使用WebApp的数据集版本框架浏览器的“按URL分组”选项，为具有相同上下文ID的所有框架显示单个预览。点击预览以按时间戳顺序在框架查看器中查看上下文组的框架。这在处理视频时非常有用。您可以为所有视频帧赋予相同的上下文ID，然后按顺序查看它们。

框架结构

下面的面板描述了frame中包含的详细信息：

id (string) - 此框架的唯一ID。
blob (字符串) - 原始数据。
context_id (string) - 源URL。
dataset (dict) - 包含帧的超数据集和版本。
- id - 超数据集的ID。
- version - 版本的ID。
meta (dict) - 框架自定义元数据。任何自定义键值对（sources 和 rois 也可以包含一个元数据字典，用于与单个源和感兴趣区域关联的自定义键值对）。参见自定义元数据。
num_frames
rois ([dict]) - 注释的元数据，可以是与此帧源数据相关的感兴趣区域（ROIs），或应用于整个帧的帧标签（不是区域）。ROIs是由多边形或用于对象检测和分割的标记RGB值界定的标记区域。参见注释。
- id - ROI的ID。
- confidence (float) - ROI标签的置信度（介于0和1.0之间）。
- labels ([string])
  - 对于FrameGroup 对象（感兴趣区域），这些是应用于ROI的标签。
  - 对于FrameGroup 标签，这是应用于整个帧的标签。
- mask (dict) - 如果使用了掩码（例如，用于语义分割），则应用于ROI的掩码的RGB值。 ID指向掩码的来源。
  - id - 掩码字典在sources中的ID。
  - value - 掩码的RGB值。
  信息
  mask 字典已弃用。掩码标签及其相关的像素值现在存储在数据集版本的元数据中。请参阅 Masks。
- poly ([int]) - 边界区域的顶点。
- sources ([string]) - sources 字典中的 id，用于将注释与其原始数据源关联。
sources ([dict]) - 此框架中原始数据的来源。对于SingleFrame，这是一个来源。对于FrameGroup，这是多个来源。参见Sources。
- id - 源的ID。
- uri - 原始数据的URI。
- width - 图像或视频的宽度。
- height - 图像或视频的高度。
- masks - 可用掩码列表。
  - id - 掩码ID
  - content_type - 掩码类型。例如，image/jpeg。
  - uri - 掩码URI
  - timestamp
- preview - 用于ClearML企业版WebApp（UI）中的缩略图预览图像的URI
- timestamp - 对于来自视频的图像，这是一个时间戳，表示此帧在源（视频）中的绝对位置。例如，如果从汽车上的摄像头以每秒30帧的速度拍摄视频，第一帧的时间戳将为0，第二帧的时间戳将为33。对于静态图像，将此设置为0。
saved_in_version - 保存帧的版本。
saved - 帧保存的纪元时间。
timestamp - 对于来自视频的图像，表示此帧在源（视频）中的绝对位置的时间戳。

WebApp

已连接到ClearML企业平台的框架可以在WebApp（UI）上查看和分析。

在WebApp上查看帧时，可以查看与之相关的所有信息，包括其帧标签和对象注释、元数据以及其他详细信息。

这张图片展示了ClearML企业版WebApp（用户界面）中的单帧视图帧查看器。

id : "287024"
timestamp : 0
rois : Array[2] [
    {   
        "label":["tennis racket"],
        "poly":[174,189,149,152,117,107,91,72,68,45,57,33,53,30,49,32,48,34,46,35,46,37,84,92,112,128,143,166,166,191,170,203,178,196,179,194,-999999999,194,238,204,250,212,250,221,250,223,249,206,230,205,230],
        "confidence":1,
        "sources":["default"],
        "id":"f9fc8629d99b4e65aecacedd32ac356e"
    },
    {
        "label":["person"],
        "poly":[158,365,161,358,165,335,170,329,171,321,171,307,173,299,172,292,171,277,171,269,170,260,170,254,171,237,177,225,172,218,167,215,164,207,167,205,171,199,174,196,183,193,188,192,192,192,202,199,207,200,232,187,238,182,240,178,244,172,245,169,245,166,241,163,235,164,233,159,239,150,240,146,240,134,237,137,231,141,222,142,217,136,216,130,215,123,215,116,224,102,229,99,233,96,245,108,256,92,272,84,292,87,309,92,319,101,328,121,329,134,327,137,325,140,331,152,327,155,323,159,324,167,320,174,319,183,327,196,329,232,328,243,323,248,315,254,316,262,314,269,314,280,317,302,313,326,311,330,301,351,299,361,288,386,274,410,269,417,260,427,256,431,249,439,244,448,247,468,249,486,247,491,245,493,243,509,242,524,241,532,237,557,232,584,233,608,233,618,228,640,172,640,169,640,176,621,174,604,147,603,146,609,151,622,144,634,138,638,128,640,49,640,0,640,0,636,0,631,0,630,0,629,37,608,55,599,66,594,74,594,84,593,91,593,99,571,110,534,114,523,117,498,116,474,113,467,113,459,113,433,113,427,118,412,137,391,143,390,147,386,157,378,157,370],
        "confidence":1,
        "sources":["default"],
        "id":"eda8c727fea24c49b6438e5e17c0a846"
    }
    ]
sources : Array[1] [
    {
        "id":"default",
        "uri":"https://s3.amazonaws.com/allegro-datasets/coco/train2017/000000287024.jpg",
        "content_type":"image/jpeg",
        "width":427,
        "height":640,
        "timestamp":0
    }
    ]
dataset : Object 
    {
        "id":"f7edb3399164460d82316fa5ab549d5b",
        "version":"6ad8b10c668e419f9dd40422f667592c"
    }
context_id : https://s3.amazonaws.com/allegro-datasets/coco/train2017/000000287024.jpg
saved : 1598982880693
saved_in_version : "6ad8b10c668e419f9dd40422f667592c"
num_frames : 1

有关在WebApp中使用Frames的更多信息，请参阅使用Frames。

用法

创建一个单帧

要创建一个SingleFrame，实例化一个SingleFrame类并用以下内容填充它：

数据框源文件的URI链接
一个可以通过浏览器访问的预览URI，因此您将能够在Web UI中可视化数据框

from allegroai import SingleFrame

frame = SingleFrame(
    source='s3://my/bucket/path_to_file.jpg',
    width=None, 
    height=None, 
    preview_uri='s3://my/bucket/path_to_file.jpg',
    metadata=None, 
    annotations=None,  
    mask_source=None,
)

Previewing Frames in non-AWS S3-like services

为了使ClearML UI能够显示存储在非AWS S3类似服务（例如MinIO）中的帧，请确保preview_uri链接使用s3://前缀，并在URL中明确指定端口号（例如s3://my_address.com:80/bucket/my_image.png）。

此外，请确保在WebApp中提供云存储访问权限设置 > 配置 > Web App 云访问。在主机字段中输入:。

还有以下选项可以用来填充实例：

尺寸 - width 和 height
关于框架的一般信息 - metadata
注释对象的字典 - annotations
指向帧的掩码文件的URI链接 - mask_source

欲了解更多信息，请参阅SingleFrame类描述。

向数据集版本添加SingleFrames

使用 DatasetVersion.add_frames() 向数据集版本添加单帧（参见创建快照或创建子版本）。已经是数据集版本一部分的帧只会被更新。

使用upload_retries参数设置在上传失败时应重试上传帧的次数，然后将帧标记为失败并继续上传下一帧。该方法返回未成功注册或上传的帧列表。

from allegroai import DatasetVersion, SingleFrame

# a frames list is required for adding frames
frames = []

# create a frame
frame = SingleFrame(
    source='s3://my/bucket/path_to_file.jpg',
    width=512, 
    height=512, 
    preview_uri='s3://my/bucket/path_to_file.jpg',
    metadata={'alive':'yes'}, 
)

frames.append(frame)

# add frame to the Dataset version
myDatasetversion.add_frames(frames)

访问 SingleFrames

要访问SingleFrame，请使用DatasetVersion.get_single_frame()：

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

要访问SingleFrame，必须指定以下内容：

frame_id，可以在WebApp中的框架的框架组详情中找到
框架的数据集 - 使用 dataset_name 或 dataset_id
数据集版本 - 使用 version_id 或 version_name

更新单帧

更新一个SingleFrame：

通过调用DatasetVersion.get_single_frame()访问SingleFrame
对框架进行更改
使用DatasetVersion.update_frames()更新DatasetVersion中的帧

frames = []                

# get the SingleFrame
frame = DatasetVersion.get_single_frame(
    frame_id='dcd81d094ab44e37875c13f2014530ae', 
    dataset_name='MyDataset', 
    version_name='SingleFrame'
)
    
# make changes to the frame
## add a new annotation
frame.add_annotation(
    poly2d_xy=[154, 343, 209, 343, 209, 423, 154, 423],
    labels=['tire'], 
    metadata={'alive': 'no'}, 
    confidence=0.5
)
        
## add metadata
frame.meta['road_hazard'] = 'yes'
    
# update the SingeFrame
frames.append(frame)
myDatasetVersion.update_frames(frames)                

删除帧

要删除一个SingleFrame，请使用DatasetVersion.delete_frames()：

frames = []                

# get the SingleFrame
frame = DatasetVersion.get_single_frame(
    frame_id='f3ed0e09bf23fc947f426a0d254c652c', 
    dataset_name='MyDataset', 
    version_name='FrameGroup'
)

# delete the SingleFrame
frames.append(frame)
myDatasetVersion.delete_frames(frames)

框架组件​

来源​

注释​

口罩​

预览​

元数据​

上下文ID​

框架结构​

WebApp​

用法​

创建一个单帧​

向数据集版本添加SingleFrames​

访问 SingleFrames​

更新单帧​

删除帧​