SingleFrame
class dataframe.SingleFrame(id=None, source=None, width=None, height=None, timestamp=None, size=None, hash=None, preview_uri=None, preview_uri_timestamp=None, metadata=None, annotations=None, mask_source=None, context_id=None)
Single frame object, representing a single file with meta-data attached
Create an empty SingleFrame and fill in the field from **kwargs
Parameters
id (str ) – UUID representing the frame in the entire system. UUID (A-z,0-9), If int/float automatically convert to string If None, a unique identifier will be created based on the source URI If source is not available, a randomly generated UUID will be used
source (str ) – URI link to the source file of the data frame. (if local file, file:// prefix will be added automatically)
width (int ) – Width (integer) of the data frame. None if not applicable
height (int ) – Height (integer) of the data frame. None if not applicable
timestamp (int ) – Timestamp (integer) of the data frame. Zero/None if not applicable
size (int ) – Size (integer) in bytes of source file. None if not applicable
hash (str ) – Hash (string) of source file content. None if not applicable
preview_uri (str ) – URI link to a visualization preview of the data frame. Usually browser supported format, server from a supported source, can also be direct file link.
preview_uri_timestamp (int ) – Timestamp (or index) (integer) valid for the URI link to a visualization preview of the data frame. (see also preview_uri)
metadata (dict ) – General purpose dictionary (dict) stored alongside the data frame. Dict must be json-able.
annotations (list ) – List of annotations (Annotation object) applicable for this data frame.
mask_source (str ) – URI link (str) to a mask file for this data frame. None if not applicable
context_id (str ) – Context ID. Used for default frames aggregation. If not set then it is filled from the uri of the first source.
preview_uri
property preview_uri
Return type
str
Returns
Interchangeable with preview_source, URI link to a visualization preview of the data frame. (see also preview_uri_timestamp)
preview_uri_timestamp
property preview_uri_timestamp
Return type
int
Returns
Interchangeable with preview_source_timestamp, Timestamp (or index) (integer) valid for the URI link to a visualization preview of the data frame. (see also preview_uri)
mask_source
property mask_source
Return type
str
Returns
URI link (str) to a mask file for this data frame. None if not applicable
If multiple masks are registered, always return the first in the list
masks_source
property masks_source
Return type
Dict
[str
,str
]Returns
Dict of Mask IDS (e.g. “00”, “01” etc.) to URI links (str) to mask files for this data frame.
origin
property origin
Returns the frame’s owner dataset/version information (Dataset is a collection of Versions), including Dataset ID, Dataset Name, Version ID and Version Name. Note: This is an auto-generated read-only property.
Return type
Dict
[str
,str
]
dataset_version_metadata
property dataset_version_metadata
Returns the frame’s owner dataset version meta-data (Read-Only).
Return type
dict
Returns
dict
blob
property blob
Return type
str
Returns
Non-Indexed data (string) stored alongside the frame
sourcedata
property sourcedata
Return type
dict
Returns
General purpose dictionary stored alongside the data frame.
add_annotation
add_annotation(poly2d_xy=None, poly3d_xyz=None, points2d_xy=None, points3d_xyz=None, box2d_xywh=None, box3d_xyzwhxyzwh=None, ellipse2d_xyrrt=None, mask_rgb=None, frame_class=None, id=None, labels=None, confidence=None, metadata=None, kwargs)**
Creates an annotation instance based on the provided arguments and adds it to the single frame’s annotations list.
In case more than one of: poly2d_xy / poly3d_xyz / points2d_xy / points3d_xyz / box2d_xywh / box3d_xyzwhxyzwh / ellipse2d_xyrrt / mask_rgb are provided, an annotation instance will be created for each one. Created annotations will be associated by the provided id. If an ID is not provided, one will be automatically created.
Parameters
poly2d_xy (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – Floating points list (x,y) for single polygon, OR List of Floating points lists for complex polygon.poly3d_xyz (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – Floating points list (x,y,z) for single polygon, OR List of Floating points lists for complex polygon.points2d_xy (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – List of floating points pairs (x,y) for set of key-points,points3d_xyz (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – List of floating points triplets (x,y,z) for set of key-points,box2d_xywh (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – Bounding box, four or five floats for: X,Y,width,height, Optional(angle)box3d_xyzwhxyzwh (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – Bounding box, four floats for: X,Y,width,heightellipse2d_xyrrt (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – List of cx, cy, rx, ry, theta for the ellipsemask_rgb (
Union
[Sequence
[Union
[int
,float
]],Sequence
[Sequence
[Union
[int
,float
]]],None
]) – List of RGB (as [r, g, b]).frame_class (
Optional
[Sequence
[str
]]) – List of strings, frame level labels (classes). It is equivalent to passinglabels
without any specific annotation type.id (
Optional
[str
]) – String representing the specific annotation. Useful for tracking objects. None is a valid option.labels (
Optional
[Sequence
[str
]]) – List of labels (string). If no specific annotation is passed (e.g. polygon, box, etc.) labels will be equivalent to frame_class annotationsconfidence (
Optional
[float
]) – Labeling confidence (float). Optionalmetadata (
Optional
[dict
]) – General purpose dictionary storing multiple field/valueskwargs (In case custom annotation classes are registered , you can use one of the registered annotation type name here to provide the values in order to create an instance of a custom annotation class. ) –
Return type
List
[Annotation
]Returns
Annotation indexed list (int) containing a single value (in case a single instance was added) or multiple values (in case multiple instances were added)
remove_annotation
remove_annotation(index=None, kwargs)**
Remove an annotation from the annotations list. Annotations to remove are selected based on index location in the annotation list.
Parameters
index (
Optional
[int
]) – (int) index of annotation to removekwargs (Dict ) –
Return type
Union
[Annotation
,None
,Sequence
[Annotation
]]Returns
The removed annotation instance, or None
remove_annotations
remove_annotations(id=None, label=None, labels=None)
Remove one or more annotations from the annotations list. Annotations to remove are selected based on their ID and/or labels.
Providing No arguments at all will remove All annotations
An annotation’s ID is NOT a system ID, but a user provided value.
This means an annotation might have an ID value of None.
Parameters
id (
Optional
[str
]) – alphanumeric user-provided ID of the annotations to be removedlabel (
Optional
[str
]) – a string label. Any annotation whose labels include this label will be removed.labels (
Optional
[Sequence
[str
]]) – a list of string labels. Any annotation whose labels exactly match this list will be removed.
Return type
Sequence
[Annotation
]Returns
The removed annotation instances
get_annotations
get_annotations(id=None, index=None)
Retrieve annotation from the annotation list. Select annotation either based on index location in the annotation list, or based on annotation ID (that can be applied to a group of annotations with the same ID)
Parameters
id (str ) – alphanumeric ID of the annotations to be retrieved
index (int ) – index of annotation to remove
Return type
Sequence
[Annotation
]Returns
list of Annotations
id
property id
Return type
Optional
[str
]Returns
UUID representing the frame in the entire system
source
property source
Return type
Optional
[str
]Returns
URI link to the source file of the data frame (if local file file:// is emitted from the source prefix)
width
property width
Return type
Optional
[int
]Returns
Width (integer) of the data frame. If not set, returns None
height
property height
Return type
Optional
[int
]Returns
Height (integer) of the data frame. If not set, returns None
timestamp
property timestamp
Return type
int
Returns
Data frame timestamp (int), or index. Zero (0) if not applicable
size
property size
Return type
Optional
[int
]Returns
Size (integer) in bytes of source file.
hash
property hash
Return type
Optional
[str
]Returns
Hash (string) of source file content.
preview_source
property preview_source
Return type
str
Returns
URI link to a visualization preview of the data frame. (see also preview_uri_timestamp)
context_id
property context_id
Return type
str
Returns
Context ID (string) of the data frame. If not set then it is filled from the source uri
preview_source_timestamp
property preview_source_timestamp
Return type
int
Returns
Timestamp (or index) (integer) valid for the URI link to a visualization preview of the data frame. (see also preview_uri)
metadata
property metadata
Return type
dict
Returns
General purpose dictionary stored alongside the data frame.
annotations
property annotations
Return type
List
[Annotation
]Returns
List of annotations (Annotation object) applicable for this data frame. Note that you can add directly to the list returned by this property.
copy
copy()
Returns a copy of this SingleFrame, with a NEW RANDOM UUID.
Return type
SingleFrame
Returns
SingleFrame object
get_local_source
get_local_source(raise_on_error=False, skip_size_check=False, force_download=False)
Retrieve remote file and returns a link to a local file that can be used directly.
:type raise_on_error: bool
:param raise_on_error: If True raise exception if accessing the file failed.
If False (default) return None on error and print error to log.
Parameters
skip_size_check (
bool
) – If True will return also files size zero bytes.force_download (
bool
) – If True will ignore local cache and download the file.raise_on_error (bool ) –
Return type
Optional
[str
]Returns
Full path to file (str)
get_local_mask_source
get_local_mask_source(raise_on_error=False, mask_id=None, skip_size_check=False, force_download=False)
Retrieve remote mask file and returns a link to a local file that can be used directly.
Parameters
raise_on_error (
bool
) – If True raise exception if accessing the file failed. If False (default) return None on error and print error to log.mask_id (
Optional
[str
]) – If provided return the specific mask_id local file copy.skip_size_check (
bool
) – If True will return also files size zero bytes.force_download (
bool
) – If True will ignore local cache and download the file.
Return type
Optional
[str
]Returns
Full path to file (str)
get_local_masks_source
get_local_masks_source(raise_on_error=False, skip_size_check=False, force_download=False)
Retrieve remote mask files and returns a list of links to a local file that can be used directly.
Parameters
raise_on_error (
bool
) – If True raise exception if accessing the file failed. If False (default) on error append None the list of local files and print error to log.skip_size_check (
bool
) – If True will return also files size zero bytes.force_download (
bool
) – If True will ignore local cache and download the file.
Return type
Dict
[str
,Optional
[str
]]Returns
Dict of mask ID (i.e. “00”, “01” etc.) to full path to file (str)
get_local_preview_source
get_local_preview_source(raise_on_error=False, skip_size_check=False, force_download=False)
Retrieve remote preview file and returns a link to a local file that can be used directly.
Parameters
raise_on_error (
bool
) – If True raise exception if accessing the file failed. If False (default) return None on error and print error to log.skip_size_check (
bool
) – If True will return also files size zero bytes.force_download (
bool
) – If True will ignore local cache and download the file.
Return type
Optional
[str
]Returns
Full path to file (str)
to_dict
to_dict()
Return REST API compliant dictionary
Return type
dict
Returns
API compliant dictionary for use directly with REST-API
SingleFrame.from_dict
classmethod from_dict(singleframe_dict)
Build a SingleFrame from REST API compliant dictionary
Parameters
singleframe_dict (dict ) – a dictionary returned from SingleFrame.to_dict()
Return type
Union[FrameGroup, SingleFrame]
Returns
FrameGroup object built from REST API dictionary
update_source_files_hash
update_source_files_hash(allow_download=False)
Update internal source files hash (SHA2) values updates the self.sourcedata with:
self.sourcedata['hash'] = {
'source': sha2_hash,
'mask_source': [sha2_hash, ...],
'preview_source': sha2_hash,
}
Parameters
allow_download (bool ) – if False(default) only calculate hash for local URL file, otherwise download and update the files content hash
Return type
()
get_source_hash
get_source_hash()
Return a dict of source hash. Example:
{
'source': sha2_hash,
'mask_source': [sha2_hash],
'preview_source': sha2_hash,
}
Return type
Dict[str, (int, str)]
Returns
dict