Skip to main content

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.

info

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,height

    • ellipse2d_xyrrt (Union[Sequence[Union[int, float]], Sequence[Sequence[Union[int, float]]], None]) – List of cx, cy, rx, ry, theta for the ellipse

    • mask_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 passing labels 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 annotations

    • confidence (Optional[float]) – Labeling confidence (float). Optional

    • metadata (Optional[dict]) – General purpose dictionary storing multiple field/values

    • kwargs (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 remove

    • kwargs (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.

info

Providing No arguments at all will remove All annotations

info

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 removed

    • label (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