Objects.ontology object instance

ObjectInstance Objects

class ObjectInstance()

An object instance is an object that has coordinates and can be placed on one or multiple frames in a label row.

get_events

def get_events() -> List[LabelEvent]

All stored events of this object on an event-based label row, sorted by frame.

Includes delete markers. Use get_ranges() for the ranges the object is present over.

Raises:

• LabelRowError - If the label row is not event-based.

get_ranges

def get_ranges() -> Ranges

The minimal closed ranges this object is present over.

On a frame-based label row these are the frames it is annotated on, run-length encoded. On an event-based row they are the stretches each upsert holds over, closed by the delete that ends them. On a range-only object (audio, text, time range) they are the object’s own ranges.

Raises:

• LabelRowError - If the object’s events end on an upsert with no closing delete.

upsert_event

def upsert_event(coordinates: UpsertEventCoordinates,
                 frame: int,
                 *,
                 overwrite: bool = False,
                 created_at: Optional[datetime] = None,
                 created_by: Optional[str] = None,
                 last_edited_at: Optional[datetime] = None,
                 last_edited_by: Optional[str] = None,
                 confidence: Optional[float] = None,
                 manual_annotation: Optional[bool] = None) -> None

Write a keyframe on an event-based label row: from frame on, the object has these coordinates.

The keyframe holds until the object’s next event, or indefinitely if there is none. A delete marker stored on frame is replaced.

Arguments:

• coordinates - The geometry from frame onward. Must match the ontology object’s shape.
• frame - The frame (nanosecond offset relative to the start of the scene on a continuous scene) the keyframe starts at. Must be >= 0.
• overwrite - Required to replace an upsert already stored on frame.
• created_at - Optionally the creation time. Defaults to now.
• created_by - Optionally the creator. Defaults to the SDK user.
• last_edited_at - Optionally the last edit time. Defaults to now.
• last_edited_by - Optionally the last editor. Defaults to the SDK user.
• confidence - Optionally the confidence. Defaults to 1.0.
• manual_annotation - Optionally whether this was a manual annotation. Defaults to True.

Raises:

• LabelRowError - If the row is not event-based, the coordinates do not match the ontology shape, frame is negative, or an upsert exists on frame and overwrite is False.

delete_event

def delete_event(frame: int) -> None

Write a delete on an event-based label row: from frame on, the object does not exist.

The object reappears at its next upsert, if any. A delete that would terminate nothing (the object is already absent at frame) is not written. Where frame holds the object’s own opening keyframe, that keyframe is removed instead. Deletes left terminating nothing are pruned, and an object with no events left is removed from its label row.

Arguments:

• frame - The frame (nanosecond offset relative to the start of the scene on a continuous scene) the object ends at.

Raises:

• LabelRowError - If the row is not event-based.

remove_event

def remove_event(frame: int) -> None

Erase the event stored on frame on an event-based label row, as if it were never written.

Unlike delete_event(), which adds an event saying the object ends, this removes one. Deletes left terminating nothing are pruned. An object with no events left is removed from its label row.

Arguments:

• frame - The frame of the stored event.

Raises:

• LabelRowError - If the row is not event-based or nothing is stored on frame.

is_assigned_to_label_row

def is_assigned_to_label_row() -> Optional[LabelRowV2]

Checks if the object instance is assigned to a label row.

Returns:

The LabelRowV2 instance if assigned, otherwise None.

object_hash

@property
def object_hash() -> str

A unique identifier for the object instance.

Returns:

The unique object hash.

ontology_item

@property
def ontology_item() -> Object

The ontology object associated with this instance.

Returns:

The ontology object.

feature_hash

@property
def feature_hash() -> str

Feature node hash from the project ontology.

Returns:

The feature node hash.

object_name

@property
def object_name() -> str

Object name from the project ontology.

Returns:

The object name.

get_answer

def get_answer(
    attribute: Attribute,
    filter_answer: Union[str, NumericAnswerValue, Option, Iterable[Option],
                         None] = None,
    filter_frame: Optional[int] = None,
    is_dynamic: Optional[bool] = None
) -> Union[str, NumericAnswerValue, Option, Iterable[Option], AnswersForFrames,
           None]

Get the answer set for a given ontology Attribute. Returns None if the attribute is not yet answered.

For the ChecklistAttribute, it returns None if and only if the attribute is nested and the parent is unselected. Otherwise, if not yet answered it will return an empty list.

Arguments:

• attribute - The ontology attribute to get the answer for.
• filter_answer - A filter for a specific answer value. Only applies to dynamic attributes.
• filter_frame - A filter for a specific frame. Only applies to dynamic attributes.
• is_dynamic - Optionally specify whether a dynamic answer is expected or not. This will throw if it is set incorrectly according to the attribute. Set this to narrow down the return type.

Returns:

If the attribute is static, then the answer value is returned, assuming an answer value has already been set. If the attribute is dynamic, the AnswersForFrames object is returned.

set_answer

def set_answer(answer: Union[str, NumericAnswerValue, Option,
                             Sequence[Option]],
               attribute: Optional[Attribute] = None,
               frames: Optional[Frames] = None,
               overwrite: bool = False,
               manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION) -> None

Set the answer for a given ontology Attribute. This is the equivalent of e.g. selecting a checkbox in the UI after drawing the ObjectInstance. There is only one answer per ObjectInstance per Attribute, unless the attribute is dynamic (check the args list for more instructions on how to set dynamic answers).

Arguments:

• answer - The answer to set.
• attribute - The ontology attribute to set the answer for. If not set, this will be attempted to be inferred. For answers to RadioAttribute or ChecklistAttribute, this can be inferred automatically. For TextAttribute or NumericAttribute, this will only be inferred if there is only one possible TextAttribute or NumericAttribute to set for the entire object instance. Otherwise, a LabelRowError will be thrown.
• frames - Only relevant for dynamic attributes. The frames to set the answer for. If None, the answer is set for all frames that this object currently has set coordinates for (also overwriting current answers). This will not automatically propagate the answer to new frames that are added in the future. If this is anything but None for non-dynamic attributes, this will throw a ValueError.
• overwrite - If True, the answer will be overwritten if it already exists. If False, this will throw a LabelRowError if the answer already exists. This argument is ignored for dynamic attributes.
• manual_annotation - If True, the answer will be marked as manually annotated. This arg defaults to DEFAULT_MANUAL_ANNOTATION.

set_answer_from_list

def set_answer_from_list(answers_list: List[AttributeDict]) -> None

This is a low level helper function and should usually not be used directly.

Sets the answer for the classification from a dictionary.

Arguments:

• answers_list - The list of dictionaries to set the answer from.

delete_answer

def delete_answer(attribute: Attribute,
                  filter_answer: Optional[Union[str, Option,
                                                Iterable[Option]]] = None,
                  filter_frame: Optional[int] = None) -> None

Reset the answer of an attribute as if it was never set.

Arguments:

• attribute - The attribute to delete the answer for.
• filter_answer - A filter for a specific answer value. Delete only answers with the provided value. Only applies to dynamic attributes.
• filter_frame - A filter for a specific frame. Only applies to dynamic attributes.

check_within_range

def check_within_range(frame: int) -> None

Check if the given frame is within the acceptable range.

Arguments:

• frame - The frame number to check.

Raises:

• LabelRowError - If the frame is out of the acceptable range.

set_for_frames

def set_for_frames(coordinates: Coordinates,
                   frames: Frames = 0,
                   *,
                   overwrite: bool = False,
                   created_at: Optional[datetime] = None,
                   created_by: Optional[str] = None,
                   last_edited_at: Optional[datetime] = None,
                   last_edited_by: Optional[str] = None,
                   confidence: Optional[float] = None,
                   manual_annotation: Optional[bool] = None,
                   reviews: Optional[List[dict]] = None,
                   is_deleted: Optional[bool] = None,
                   event_kind: Optional[EventKind] = None) -> None

Place the object onto the specified frame(s).

If the object already exists on the frame and overwrite is set to True, the currently specified values will be overwritten.

Arguments:

• coordinates - The coordinates of the object in the frame. This will throw an error if the type of the coordinates does not match the type of the attribute in the object instance.
• frames - The frames to add the object instance to. Defaults to the first frame for convenience.
• overwrite - If True, overwrite existing data for the given frames. This will not reset all the non-specified values. If False and data already exists for the given frames, raises an error.
• created_at - Optionally specify the creation time of the object instance on this frame. Defaults to datetime.now().
• created_by - Optionally specify the creator of the object instance on this frame. Defaults to the current SDK user.
• last_edited_at - Optionally specify the last edit time of the object instance on this frame. Defaults to datetime.now().
• last_edited_by - Optionally specify the last editor of the object instance on this frame. Defaults to the current SDK user.
• confidence - Optionally specify the confidence of the object instance on this frame. Defaults to 1.0.
• manual_annotation - Optionally specify whether the object instance on this frame was manually annotated. Defaults to True.
• reviews - Should only be set by internal functions.
• is_deleted - Should only be set by internal functions.
• event_kind - Should only be set by internal functions.

get_annotation

def get_annotation(frame: Union[int, str] = 0) -> Annotation

Get the annotation for the object instance on the specified frame.

On an event-based label row this returns a read-only ObjectInstance.ResolvedAnnotation (see its is_virtual and keyframe) resolved from the keyframe holding over the frame; it raises where the object does not exist.

Arguments:

• frame - Either the frame number or the image hash if the data type is an image or image group. Defaults to the first frame.

Returns:

• Annotation - The annotation for the specified frame.

Raises:

• LabelRowError - If the frame is not present in the label row.

copy

def copy() -> ObjectInstance

Create an exact copy of this ObjectInstance.

The new copy will have a new object hash and will not be associated with any LabelRowV2. This is useful for adding the semantically same ObjectInstance to multiple LabelRowV2s.

Returns:

• ObjectInstance - A new ObjectInstance that is a copy of the current instance.

get_annotations

def get_annotations() -> List[Annotation]

Get all annotations for the object instance on all frames it has been placed on.

Returns:

• List[Annotation] - A list of ObjectInstance.Annotation in order of available frames.

Raises:

• LabelRowError - If the label row is event-based.

get_annotation_frames

def get_annotation_frames() -> set[int]

Get all annotations for the object instance on all frames it has been placed on.

Returns:

• List[Annotation] - A list of ObjectInstance.Annotation in order of available frames.

Raises:

• LabelRowError - If the label row is event-based.

remove_from_frames

def remove_from_frames(frames: Frames) -> None

Remove the object instance from the specified frames.

Arguments:

• frames - The frames from which to remove the object instance.

is_valid

def is_valid() -> None

Check if the ObjectInstance is valid.

Raises:

• LabelRowError - If the ObjectInstance is not on any frames.

are_dynamic_answers_valid

def are_dynamic_answers_valid() -> None

Validate if there are any dynamic answers on frames that have no coordinates.

Raises:

• LabelRowError - If there are dynamic answers on frames without coordinates.

Annotation Objects

class Annotation(_ObjectAnnotation)

Represents an annotation for a specific frame of an ObjectInstance. Allows setting or getting data for the ObjectInstance on the given frame number. This is deprecated, we will be using the ObjectAnnotation that this inherits from.

is_deleted

@property
def is_deleted() -> Optional[bool]

This is merely here for backwards compatibility.

Returns:

Optional[List[Dict[str, Any]]]: A list of review dictionaries, if any.

ResolvedAnnotation Objects

class ResolvedAnnotation(Annotation)

A read-only view of an object at a frame on an event-based label row.

The view reads from the upsert keyframe holding over frame. is_virtual is False when an upsert is stored on exactly this frame and True when the frame inherits an earlier keyframe. Writes must go through ObjectInstance.upsert_event, delete_event and remove_event; every setter here raises.

keyframe

@property
def keyframe() -> int

The frame of the stored upsert this view reads from.

is_virtual

@property
def is_virtual() -> bool

True when no upsert is stored on exactly this frame and the view inherits an earlier keyframe.

FrameData Objects

@dataclass
class FrameData()

Data class for storing frame-specific data.

Attributes:

• coordinates Coordinates - The coordinates associated with the frame.
• annotation_metadata _AnnotationMetadata - The frame’s metadata information.

check_coordinate_type

def check_coordinate_type(coordinates: Coordinates, ontology_object: Object,
                          parent: Optional[LabelRowV2]) -> None

Check if the coordinate type matches the expected type for the ontology object.

Arguments:

• coordinates Coordinates - The coordinates to check.
• ontology_object Object - The ontology object to check against.
• parent LabelRowV2 - The parent label row (if any) of the ontology object.

Raises:

• LabelRowError - If the coordinate type does not match the expected type.

AnswerRangeIndex Objects

class AnswerRangeIndex()

Internal range storage for dynamic answers, preserving global answer insertion order.

The attribute index contains sorted, non-overlapping intervals. The answer index maps interval starts to ends so replacing a fragment does not shift a sorted list. All mutations update both indexes together.

assign

def assign(answer: Answer, ranges: Ranges) -> None

Assign an answer over ranges, replacing overlaps and merging equal neighbors.

remove

def remove(
    attribute: Attribute,
    ranges: Optional[Ranges] = None,
    filter_answer: Union[str, NumericAnswerValue, Option, Iterable[Option],
                         None] = None
) -> None

Remove matching answers on selected ranges, or throughout the attribute when omitted.

overlapping

def overlapping(attribute: Attribute, ranges: Ranges) -> Set[Answer]

Find answers whose intervals overlap any selected range.

answers

def answers() -> Iterable[Answer]

Iterate answers in insertion order across all attributes.

ranges_for

def ranges_for(answer: Answer) -> Ranges

Return independent, sorted ranges for a stored answer.

answered_ranges

def answered_ranges() -> Ranges

Return the merged coverage of every stored answer.

copy

def copy() -> AnswerRangeIndex

Copy both indexes together so they share the same copied answer objects.

DynamicAnswerManager Objects

class DynamicAnswerManager()

Manages dynamic answers for different frames of an ObjectInstance.

This class is an internal helper class and should not be interacted with directly by the user.

is_valid_dynamic_attribute

def is_valid_dynamic_attribute(attribute: Attribute) -> bool

Check if the attribute is a valid dynamic attribute.

Arguments:

• attribute Attribute - The attribute to check.

Returns:

• bool - True if the attribute is valid, False otherwise.

delete_answer

def delete_answer(
        attribute: Attribute,
        frames: Optional[Frames] = None,
        filter_answer: Union[str, Option, Iterable[Option],
                             None] = None) -> None

Delete the answer for a given attribute and frames.

Arguments:

• attribute Attribute - The attribute to delete the answer for.
• frames Optional[Frames] - The frames to delete the answer for.
• filter_answer Union[str, Option, Iterable[Option], None] - The specific answer to delete.

set_answer

def set_answer(answer: Union[str, NumericAnswerValue, Option,
                             Iterable[Option]],
               attribute: Attribute,
               frames: Optional[Frames] = None) -> None

Set the answer for a given attribute and frames.

Arguments:

• answer Union[str, Option, Iterable[Option]] - The answer to set.
• attribute Attribute - The attribute to set the answer for.
• frames Optional[Frames] - The frames to set the answer for.

get_answer

def get_answer(attribute: Attribute,
               filter_answer: Union[str, NumericAnswerValue, Option,
                                    Iterable[Option], None] = None,
               filter_frames: Optional[Frames] = None) -> AnswersForFrames

Get answers for a given attribute, filtered by the specified criteria.

Arguments:

• attribute Attribute - The attribute to get the answers for.
• filter_answer Union[str, Option, Iterable[Option], None] - The specific answer to filter by.
• filter_frames Optional[Frames] - The specific frames to filter by.

Returns:

• AnswersForFrames - A list of answers and their associated frames.

answered_ranges

def answered_ranges() -> Ranges

Get the ranges that have answers set, merged across every answer.

get_all_answers

def get_all_answers() -> List[Tuple[Answer, Ranges]]

Get all answers that are set.

Returns:

List[Tuple[Answer, Ranges]]: A list of tuples containing the answer and its associated ranges.

copy

def copy() -> DynamicAnswerManager

Create a deep copy of the DynamicAnswerManager instance.

Returns:

• DynamicAnswerManager - A new instance of DynamicAnswerManager with copied data.

AnswerForFrames Objects

@dataclass
class AnswerForFrames()

Data class for storing an answer and its associated frame ranges.

Attributes:

• answer Union[str, Option, Iterable[Option]] - The answer set for the frames.

• ranges Ranges - The ranges representing the frames where the answer is set.

  The ranges are essentially a run-length encoding of the frames where the unique answer is set. They are sorted in ascending order.

AnswersForFrames

A list of AnswerForFrames objects, representing answers and their associated frame ranges.