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) store alongside the data frame. Dict must by 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


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 of 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 of 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

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]) – alpha numeric user-provided id of the annotations to be removed

    • label (Optional[str]) – a string label. Any annotation who’s labels include this label will be removed.

    • labels (Optional[Sequence[str]]) – a list of string label. Any annotation who’s 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 ) – alpha numeric 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)

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.

  • Return type

    Optional[str]

  • Returns

    Full path to file (str)

  • Parameters

    raise_on_error (bool ) –


get_local_mask_source#

get_local_mask_source(raise_on_error=False, mask_id=None)

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.

  • Return type

    Optional[str]

  • Returns

    Full path to file (str)


get_local_masks_source#

get_local_masks_source(raise_on_error=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.

  • Return type

    Dict[str, Optional[str]]

If False (default) on error append None the list of local files and print error to log. :rtype: Dict[str, Optional[str]] :return: 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)

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.

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

} :rtype: Dict[str, (int, str)] :return: dict

  • Return type

    Dict[str, (int, str)]