VolumeFigure¶

class VolumeFigure(volume_object, geometry, plane_name=None, slice_index=None, key=None, class_id=None, labeler_login=None, updated_at=None, created_at=None, custom_data=None, **kwargs)[source]¶

Bases: VideoFigure

Figure in volume annotation: geometry (Mask3D/ClosedSurfaceMesh) at a slice or spatial position. Immutable.

Figure in volume annotation.

Parameters:

volume_object¶

Volume object this figure belongs to.

geometry¶

Geometry (Rectangle, Mask3D, ClosedSurfaceMesh, etc.).

plane_name : str, optional¶

Plane name: “axial”, “sagittal”, or “coronal”. Required for non-Mask3D geometries.

slice_index : int, optional¶

Slice index. Required for non-Mask3D geometries.

key : uuid.UUID, optional¶

UUID key. Auto-generated if not provided.

class_id : int, optional¶

Server-side class ID.

labeler_login : str, optional¶

Login of user who created the figure.

updated_at : str, optional¶

Last modification timestamp (ISO format).

created_at : str, optional¶

Creation timestamp (ISO format).

custom_data : dict, optional¶

Custom data.

Raises:

TypeError – If plane_name/slice_index missing for non-Mask3D geometries.

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
geometry = sly.Rectangle(0, 0, 100, 100)
vol_fig = sly.VolumeFigure(volume_obj_heart, geometry, "axial", 7)
print(vol_fig.to_json())

Methods

clone	Makes a copy of VolumeFigure with new fields, if fields are given, otherwise it will use fields of the original VolumeFigure.
from_json	Convert a json dict to VolumeFigure.
from_mask3d	Create a VolumeFigure from Mask 3D geometry.
get_meta	Get a dictionary with metadata associated with volume figure.
key	Figure key.
to_json	Convert the VolumeFigure to a json dict.
validate_bounds	Checks if given image with given size contains a figure.

Attributes

custom_data	Get custom data associated with the VolumeFigure.
frame_index	Property "frame_index" is only available for videos.
geometry	Geometry of the current VideoFigure.
normal	Get a normal vector associated with a plane name.
parent_object	Get a parent VolumeObject object of volume figure.
plane_name	Get a plane name of volume figure.
priority	Priority of the figure (position of the figure relative to other overlapping or underlying figures).
slice_index	Get a slice index of volume figure.
smart_tool_input	Smart Tool parameters that were used for labeling.
status	Labeling status.
video_object	Property "video_object" is only available for videos.
volume_object	Get a parent VolumeObject object of volume figure.

classmethod from_json(data, objects, plane_name, slice_index, key_id_map=None)[source]¶

Convert a json dict to VolumeFigure. Read more about Supervisely format.

Parameters:

data : dict¶

Dict in json format.

objects¶

VolumeObjectCollection object.

plane_name : str¶

Name of the volume plane.

slice_index : int¶

Index of slice to which VolumeFigure belongs.

key_id_map=None¶

KeyIdMap object.

Raises:

RuntimeError – if volume object ID and volume object key are None, if volume object key and key_id_map are None, if volume object with given id not found in key_id_map

Returns:

VolumeFigure object

Return type:

VolumeFigure

Usage Example:

import supervisely as sly

# Create VolumeFigure from json we use data from example to_json(see above)
new_volume_figure = sly.VolumeFigure.from_json(
    data=volume_figure_json,
    objects=sly.VolumeObjectCollection([volume_obj_heart]),
    plane_name="axial",
    slice_index=7
)

classmethod from_mask3d(volume_object, geometry_data, key=None, class_id=None, labeler_login=None, updated_at=None, created_at=None, custom_data=None)[source]¶

Create a VolumeFigure from Mask 3D geometry.

Parameters:

volume_object¶

VolumeObject to which the VolumeFigure belongs.

geometry_data : str or ndarray or bytes¶

Geometry data represented as a path, NumPy array, or bytes.

key : UUID, optional¶

The UUID key associated with the VolumeFigure.

class_id : int, optional¶

The ID of the VolumeObject class to which the VolumeFigure belongs.

labeler_login : str, optional¶

Login of the user who created the VolumeFigure.

updated_at : str, optional¶

The date and time when the VolumeFigure was last modified (ISO 8601 format, e.g., ‘2021-01-22T19:37:50.158Z’).

created_at : str, optional¶

The date and time when the VolumeFigure was created (ISO 8601 format, e.g., ‘2021-01-22T19:37:50.158Z’).

custom_data : dict, optional¶

Custom data associated with the VolumeFigure.

Returns:

A VolumeFigure object created from Mask3D geometry.

Return type:

VolumeFigure

clone(volume_object=None, geometry=None, plane_name=None, slice_index=None, key=None, class_id=None, labeler_login=None, updated_at=None, created_at=None, custom_data=None)[source]¶

Makes a copy of VolumeFigure with new fields, if fields are given, otherwise it will use fields of the original VolumeFigure.

Parameters:

volume_object=None¶

VolumeObject object.

geometry=None¶

Geometry object.

plane_name : str, optional¶

Name of the volume plane.

slice_index : int, optional¶

Index of slice to which VolumeFigure belongs.

key=None¶

The UUID key associated with the VolumeFigure.

class_id : int, optional¶

ID of ObjClass to which VolumeFigure belongs.

labeler_login : str, optional¶

Login of the user who created VolumeFigure.

updated_at : str, optional¶

Date and Time when VolumeFigure was modified last. Date Format: Year:Month:Day:Hour:Minute:Seconds. Example: ‘2021-01-22T19:37:50.158Z’.

created_at : str, optional¶

Date and Time when VolumeFigure was created. Date Format is the same as in “updated_at” parameter.

custom_data : dict, optional¶

Custom data associated with the VolumeFigure.

Returns:

VolumeFigure object

Return type:

VolumeFigure

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
slice_index = 7
plane_name = "axial"
geometry = sly.Rectangle(0, 0, 100, 100)
volume_figure_heart = sly.VolumeFigure(volume_obj_heart, geometry, plane_name, slice_index)

obj_class_lang = sly.ObjClass('lang', sly.Rectangle)
volume_obj_lang = sly.VolumeObject(obj_class_lang)
slice_index_lang = 15
geometry_lang = sly.Rectangle(0, 0, 500, 600)

# Remember that VolumeFigure object is immutable, and we need to assign new instance of VolumeFigure to a new variable
volume_figure_lang = volume_figure_heart.clone(volume_object=volume_obj_lang, geometry=geometry_lang, slice_index=slice_index_lang)
print(volume_figure_lang.to_json())
# Output: {
#     "geometry": {
#         "points": {
#         "exterior": [
#             [0, 0],
#             [600, 500]
#         ],
#         "interior": []
#         }
#     },
#     "geometryType": "rectangle",
#     "key": "2974165267224bf6b677e17ca2304b04",
#     "meta": {
#         "normal": { "x": 0, "y": 0, "z": 1 },
#         "planeName": "axial",
#         "sliceIndex": 15
#     },
#     "objectKey": "dafe3adaacad474ba5163ecebcc57cd0"
# }

get_meta()[source]¶

Get a dictionary with metadata associated with volume figure.

Returns:

Dictionary with metadata associated with volume figure.

Return type:

dict

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.get_meta())
# {'sliceIndex': 7, 'planeName': 'axial', 'normal': {'x': 0, 'y': 0, 'z': 1}}

key()¶

Figure key.

Returns:

Figure key.

Return type:

UUID

Usage Example:

key = video_figure_car.key
print(key) # 158e6cf4f4ac4c639fc6994aad127c16

to_json(key_id_map=None, save_meta=True)[source]¶

Convert the VolumeFigure to a json dict. Read more about Supervisely format.

Parameters:

key_id_map=None¶

KeyIdMap object.

save_meta : bool, optional¶

Save frame index or not.

Returns:

Json format as a dict

Return type:

dict

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
fr_index = 7
geometry = sly.Rectangle(0, 0, 100, 100)
volume_figure_heart = sly.VolumeFigure(volume_obj_heart, geometry, fr_index)
volume_figure_json = volume_figure_heart.to_json(save_meta=True)
print(volume_figure_json)
# Output: {
#     "geometry": {
#         "points": {
#         "exterior": [
#             [0, 0],
#             [100, 100]
#         ],
#         "interior": []
#         }
#     },
#     "geometryType": "rectangle",
#     "key": "158e6cf4f4ac4c639fc6994aad127c16",
#     "meta": {
#         "normal": { "x": 0, "y": 0, "z": 1 },
#         "planeName": "axial",
#         "sliceIndex": 7
#     },
#     "objectKey": "bf63ffe342e949899d3ddcb6b0f73f54",
#     "custom_data": {}
# }

validate_bounds(img_size, _auto_correct=False)[source]¶

Checks if given image with given size contains a figure.

Parameters:

img_size : Tuple[int, int]¶

Size of the image (height, width).

_auto_correct : bool, optional¶

Correct the geometry of a shape if it is out of bounds or not.

:raises OutOfImageBoundsException: if figure is out of image bounds :returns: None :rtype: None

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
slice_index = 7
plane_name = "axial"
geometry = sly.Rectangle(0, 0, 100, 100)
volume_figure_heart = sly.VolumeFigure(volume_obj_heart, geometry, plane_name, slice_index)

im_size = (50, 200)
volume_figure_heart.validate_bounds(im_size)
# raise OutOfImageBoundsException("Figure is out of image bounds")

property custom_data : dict | None¶

Get custom data associated with the VolumeFigure.

Returns:

Custom data associated with the VolumeFigure.

Return type:

dict

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7,
    custom_data={"key": "value"}
)

print(volume_figure_heart.custom_data)
# Output: {'key': 'value'}

property frame_index¶

Property “frame_index” is only available for videos.

property geometry : supervisely.geometry.geometry.Geometry¶

Geometry of the current VideoFigure.

Returns:

Geometry object

Return type:

Geometry

Usage Example:

geometry = video_figure_car.geometry
print(geometry.to_json())
# Output: {
#     "points": {
#         "exterior": [
#             [
#                 0,
#                 0
#             ],
#             [
#                 100,
#                 100
#             ]
#         ],
#         "interior": []
#     }
# }

property normal¶

Get a normal vector associated with a plane name.

Returns:

Dictionary with normal vector associated with a plane name.

Return type:

dict

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.normal)
# Output: {'x': 0, 'y': 0, 'z': 1}

property parent_object : supervisely.volume_annotation.volume_object.VolumeObject¶

Get a parent VolumeObject object of volume figure.

Returns:

VolumeObject object

Return type:

VolumeObject

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.parent_object)
# Output:
# <supervisely.volume_annotation.volume_object.VolumeObject object at 0x7f786a3f8bd0>

property plane_name¶

Get a plane name of volume figure.

Returns:

Plane name of volume figure.

Return type:

str

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.plane_name)
# Output: axial

property priority¶

Priority of the figure (position of the figure relative to other overlapping or underlying figures).

property slice_index¶

Get a slice index of volume figure.

Returns:

Python int number of slice index of volume figure.

Return type:

int

Usage Example:

import supervisely as sly

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.slice_index)
# Output: 7

property smart_tool_input¶

Smart Tool parameters that were used for labeling.

Example:

{

‘crop’: [[85.69912274538524, 323.07711452375236], [1108.5635719011857, 1543.1199742240174]], ‘visible’: True, ‘negative’: [], ‘positive’: [[597, 933], [474.5072466934964, 1381.6437133813354]]

}

property status : supervisely.annotation.label.LabelingStatus¶

Labeling status. Specifies if the VideoFigure was created by NN model, manually or created by NN and then manually corrected.

property video_object¶

Property “video_object” is only available for videos.

property volume_object : supervisely.volume_annotation.volume_object.VolumeObject¶

Get a parent VolumeObject object of volume figure.

Returns:

Parent VolumeObject object of volume figure.

Return type:

VolumeObject

Usage Example:

import supervisely as sly

volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_figure_heart = sly.VolumeFigure(
    volume_obj_heart,
    geometry=sly.Rectangle(0, 0, 100, 100),
    plane_name="axial",
    slice_index=7
)

print(volume_figure_heart.parent_object)
# Output:
# <supervisely.volume_annotation.volume_object.VolumeObject object at 0x7f95f0950b50>