Plane¶

class Plane(plane_name, img_size=None, slices_count=None, items=None, volume_meta=None)[source]¶

Bases: FrameCollection

Plane in volume (sagittal, coronal, axial); collection of Slices.

Plane in volume annotation.

Parameters:

plane_name : Union[str, None]¶: One of “sagittal”, “coronal”, “axial”, or None for spatial figures.
img_size : Tuple[int, int] or List[int, int], optional¶: Plane image size (height, width). Inferred from volume_meta if not provided.
slices_count : int, optional¶: Number of slices. Inferred from volume_meta if not provided.
items=None¶: List of Slice objects. Default empty collection.
volume_meta : dict, optional¶: Volume metadata. Required if img_size/slices_count not provided.

Raises:

ValueError – If plane_name invalid or both img_size and volume_meta are None.

Usage Example:

import supervisely as sly

vol, meta = sly.volume.read_nrrd_serie_volume(path)
plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)

Methods

`add`	Add given item to collection.
`add_items`	Add items from given list to collection.
`clone`	Makes a copy of KeyIndexedCollection with new fields, if fields are given, otherwise it will use fields of the original KeyIndexedCollection.
`difference`	Find difference between collection and given list of instances.
`from_json`	Creates a `Plane` instance from a JSON dictionary.
`get`	Get item from collection with given key(name) and set a default if item does not exist.
`get_figures_and_keys`	Get figures from all frames in collection in json format, keys from all figures in frames in collection.
`get_img_size`	Get size of the image for a given plane and volume metadata.
`get_name`	Returns the name of a plane given its normal vector.
`get_normal`	Returns the normal vector of a plane given its name.
`get_slices_count`	Returns the number of slices in the given plane.
`has_key`	Check if given key(item name exist in collection).
`intersection`	Find intersection of given list of instances with collection items.
`items`	Get list of all items in collection.
`keys`	Get list of all keys(item names) in collection.
`merge`	Merge collection and other KeyIndexedCollection object.
`remove_items`	Remove items from collection by given list of keys.
`to_json`	Returns a JSON serializable dictionary representation of the Plane instance.
`validate_figures_bounds`	Validates the figure bounds for all slices in the Plane.
`validate_name`	Validates if the given plane name is valid.

Attributes

`AXIAL`	Axial plane of the volume.
`CORONAL`	Coronal plane of the volume.
`SAGITTAL`	Sagittal plane of the volume.
`figures`	Get figures from all frames in collection.
`img_size`	Get the size of the image in the plane.
`name`	Get the name of the plane.
`normal`	Returns the normal vector of the plane.
`slices_count`	Get the number of slices in the plane.

item_type¶: alias of Slice

classmethod from_json(data, plane_name, objects, img_size=None, slices_count=None, volume_meta=None, key_id_map=None)[source]¶

Creates a Plane instance from a JSON dictionary.

Parameters:

data : dict¶: JSON dictionary representing a Plane instance.
plane_name : str¶: Name of the plane.
objects¶: Objects in the plane.
img_size : Optional[Union[list, tuple]]¶: Size of the image represented by the plane.
slices_count : Optional[int]¶: Number of slices along the plane.
volume_meta : Optional[dict]¶: Metadata of the volume to extract slices from.
key_id_map=None¶: Dictionary mapping object keys to object IDs.

Returns:

A new Plane instance created from the JSON.

Return type:

Plane

Raises:

ValueError – if plane_name is not equal to the “name” field in “data”, or if the “normal” field in “data” is not valid for the given plane, or if both slices_count and volume_meta are None.

Usage Example:

import supervisely as sly

# Create Plane from json we use data from example to_json(see below)
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
new_plane = sly.Plane.from_json(
    data=plane.to_json(),
    plane_name=sly.Plane.AXIAL,
    objects=sly.VolumeObjectCollection([]),
    volume_meta=meta,
)

static get_img_size(name, volume_meta)[source]¶

Get size of the image for a given plane and volume metadata.

Parameters:

name : str¶: Name of the plane.
volume_meta : dict¶: Metadata for the volume.

Returns:

The size of the image for the given plane.

Return type:

List[int]

Raises:

ValueError – if name is not one of “sagittal”, “coronal”, or “axial”.

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
img_size = sly.Plane.get_img_size(plane.name, meta)
print(img_size)
# Output: [512, 512]

static get_name(normal)[source]¶

Returns the name of a plane given its normal vector.

Parameters:

normal : dict¶: A dictionary representing the normal vector of a plane.

Returns:

The name of the plane.

Return type:

str

Usage Example:

import supervisely as sly

print(sly.Plane.get_name({'x': 0, 'y': 0, 'z': 1}))
# Output: axial

static get_normal(name)[source]¶

Returns the normal vector of a plane given its name.

Parameters:

name : str¶: Name of the plane.

Returns:

A dictionary representing the normal vector of the plane.

Return type:

dict

Raises:

ValueError – if name is not one of “sagittal”, “coronal”, or “axial”.

Usage Example:

import supervisely as sly

print(sly.Plane.get_normal(sly.Plane.AXIAL))
# Output: {'x': 0, 'y': 0, 'z': 1}

static get_slices_count(name, volume_meta)[source]¶

Returns the number of slices in the given plane.

Parameters:

name : str¶: Name of the plane.
volume_meta : dict¶: Metadata of the volume to extract slices from.

Returns:

Number of slices in the given plane.

Return type:

int

Raises:

ValueError – if name is not one of “sagittal”, “coronal”, or “axial”.

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
slices_count = sly.Plane.get_slices_count(plane.name, meta)
print(slices_count)
# Output: 139

static validate_name(name)[source]¶

Validates if the given plane name is valid.

Parameters:

name : Union[str, None]¶: Name of the plane.

Raises:

ValueError – if name is not one of “sagittal”, “coronal”, “axial”, or None.

Usage Example:

import supervisely as sly
from supervisely.volume_annotation.plane import Plane
plane_name_1 = "axial"
Plane.validate_name(plane_name_1)

plane_name_2 = "xy"
Plane.validate_name(plane_name_2)
# ValueError: Unknown plane xy, valid names are ['sagittal', 'coronal', 'axial', None]

add(item)¶

Add given item to collection.

Parameters:

item¶: ObjClassCollection, TagMetaCollection or TagCollection object.

Returns:

New instance of KeyIndexedCollection

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
item_dog = sly.ObjClass('dog', sly.Rectangle)
new_collection = collection.add(item_dog)

add_items(items)¶

Add items from given list to collection.

Parameters:

items¶: List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Returns:

New instance of KeyIndexedCollection

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
item_dog = sly.ObjClass('dog', sly.Rectangle)
item_mouse = sly.ObjClass('mouse', sly.Bitmap)
new_collection = collection.add_items([item_dog, item_mouse])

clone(items=None)¶

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

Parameters:

items=None¶: List of ObjClassCollection, TagMetaCollection or TagCollection objects.

Returns:

New instance of KeyIndexedCollection

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

# Remember that KeyIndexedCollection object is immutable, and we need to assign new instance of KeyIndexedCollection to a new variable
new_collection = collection.clone()

difference(other)¶

Find difference between collection and given list of instances.

Parameters:

other¶: List of items to subtract from the collection.

Returns:

KeyIndexedCollection object

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
items = [item_dog, item_turtle]

diff = collection.difference(items)
print(diff.to_json())
# Output: [
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#8A150F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]

get(key, default=None)¶

Get item from collection with given key(name) and set a default if item does not exist.

Parameters:

key : str¶: Name of Frame in collection.
default : Optional[Any]¶: The value that is returned if there is no key in the collection.

Returns:

Frame, Slice or PointcloudEpisodeFrame object

Return type:

KeyObject

Usage Example:

import supervisely as sly

frame_index = 7
geometry = sly.Rectangle(0, 0, 100, 100)
class_car = sly.ObjClass('car', sly.Rectangle)
object_car = sly.VideoObject(class_car)
figure_car = sly.VideoFigure(object_car, geometry, frame_index)

frame = sly.Frame(frame_index, figures=[figure_car])
frame_collection = sly.FrameCollection([frame])

item = frame_collection.get(frame_index)
print(item.to_json())
# Output: {
#     "figures": [
#         {
#         "geometry": {
#             "points": {
#             "exterior": [
#                 [0, 0],
#                 [100, 100]
#             ],
#             "interior": []
#             }
#         },
#         "geometryType": "rectangle",
#         "key": "713968a7d5384709bc5d4e63cd4535f2",
#         "objectKey": "3342e68eff3b44dcb75712499265be55"
#         }
#     ],
#     "index": 7
# }

get_figures_and_keys(key_id_map)¶

Get figures from all frames in collection in json format, keys from all figures in frames in collection.

Parameters:

key_id_map¶: KeyIdMap object.

Returns:

Figures from all frames in collection in json format, keys from all figures in frames in collection

Return type:

Tuple[List[dict], List[str]]

Usage Example:

import supervisely as sly
from supervisely.video_annotation.key_id_map import KeyIdMap

key_id_map = KeyIdMap()

fr_index_1 = 7
geometry = sly.Rectangle(0, 0, 100, 100)
obj_class_car = sly.ObjClass('car', sly.Rectangle)
video_object_car = sly.VideoObject(obj_class_car)
video_figure_car = sly.VideoFigure(video_object_car, geometry, fr_index_1)
frame_1 = sly.Frame(fr_index_1, figures=[video_figure_car])

fr_index_2 = 10
geometry = sly.Rectangle(0, 0, 500, 600)
obj_class_bus = sly.ObjClass('bus', sly.Rectangle)
video_object_bus = sly.VideoObject(obj_class_bus)
video_figure_bus = sly.VideoFigure(video_object_bus, geometry, fr_index_2)
frame_2 = sly.Frame(fr_index_2, figures=[video_figure_bus])

fr_collection = sly.FrameCollection([frame_1, frame_2])
figures, keys = fr_collection.get_figures_and_keys(key_id_map)
print(keys) # [UUID('0ac041b2-314e-4f6b-9d38-704b341fb383'), UUID('88aa1cb3-b1e3-480f-8ace-6346c9a9daba')]

print(figures)
# Output: [
#     {
#         "key": "a8cae05d6b8c4a67b18004130941fdec",
#         "objectKey": "cc9a9475d360481c9753f8ac3c63f8b7",
#         "geometryType": "rectangle",
#         "geometry": {
#             "points": {
#                 "exterior": [
#                     [
#                         0,
#                         0
#                     ],
#                     [
#                         100,
#                         100
#                     ]
#                 ],
#                 "interior": []
#             }
#         },
#         "meta": {
#             "frame": 7
#         }
#     },
#     {
#         "key": "6e00287acc4644dfb21d67406534080b",
#         "objectKey": "cad78d53ffc84e69a28f5f8941be9021",
#         "geometryType": "rectangle",
#         "geometry": {
#             "points": {
#                 "exterior": [
#                     [
#                         0,
#                         0
#                     ],
#                     [
#                         600,
#                         500
#                     ]
#                 ],
#                 "interior": []
#             }
#         },
#         "meta": {
#             "frame": 10
#         }
#     }
# ]

has_key(key)¶

Check if given key(item name exist in collection).

Parameters:

key : str¶: The key to look for in the collection.

Returns:

Is the key in the collection or not

Return type:

bool

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

collection.has_key('cat') # True
collection.has_key('hamster') # False

intersection(other)¶

Find intersection of given list of instances with collection items.

Parameters:

other¶: List of items to intersect with the collection.

Raises:

ValueError – if find items with same keys(item names)

Returns:

KeyIndexedCollection object

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
items = [item_dog, item_turtle]

intersection = collection.intersection(items)
print(intersection.to_json())
# Output: [
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#760F8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]

items()¶

Get list of all items in collection.

Returns:

List of ObjClassCollection, TagMetaCollection or TagCollection objects

Return type:

List[KeyObject]

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
items = collection.items()
print(items)
# Output:
# [<supervisely.annotation.tag_meta.TagMeta object at 0x7fd08eae4340>,
#  <supervisely.annotation.tag_meta.TagMeta object at 0x7fd08eae4370>]

keys()¶

Get list of all keys(item names) in collection.

Returns:

List of collection keys

Return type:

List[str]

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])
keys = collection.keys() # ['cat', 'turtle']

merge(other)¶

Merge collection and other KeyIndexedCollection object.

Parameters:

other¶: Other collection to merge with.

Raises:

ValueError – if item name from given list is in collection but items in both are different

Returns:

KeyIndexedCollection object

Return type:

KeyIndexedCollection

Usage Example:

import supervisely as sly

item_cat = sly.TagMeta('cat', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_cat, item_turtle])

item_dog = sly.TagMeta('dog', sly.TagValueType.NONE)
item_turtle = sly.TagMeta('turtle', sly.TagValueType.ANY_STRING)
other_collection = sly.collection.key_indexed_collection.KeyIndexedCollection([item_dog, item_turtle])

merge = collection.merge(other_collection)
print(merge.to_json())
# Output: [
#     {
#         "name": "dog",
#         "value_type": "none",
#         "color": "#8A6C0F",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "cat",
#         "value_type": "none",
#         "color": "#0F4A8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     },
#     {
#         "name": "turtle",
#         "value_type": "any_string",
#         "color": "#4F0F8A",
#         "hotkey": "",
#         "applicable_type": "all",
#         "classes": []
#     }
# ]

remove_items(keys)¶

Remove items from collection by given list of keys. Creates a new instance of KeyIndexedCollection.

Parameters:

keys : List[str]¶: List of keys(item names) in collection.

Returns:

New instance of KeyIndexedCollection

Return type:

KeyIndexedCollection

to_json(key_id_map=None)[source]¶

Returns a JSON serializable dictionary representation of the Plane instance.

Parameters:

key_id_map=None¶: Dictionary mapping object keys to object IDs.

Returns:

A JSON serializable dictionary representation of the Plane instance.

Return type:

dict

Usage Example:

import supervisely as sly
from supervisely.volume_annotation.plane import Plane
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = Plane(sly.Plane.AXIAL, volume_meta=meta)
print(plane.to_json())
# Output: { "name": "axial", "normal": { "x": 0, "y": 0, "z": 1 }, "slices": [] }

validate_figures_bounds()[source]¶

Validates the figure bounds for all slices in the Plane.

Raises:: ValueError – if any of the slices in the Plane instance have invalid figure bounds.

AXIAL = 'axial'¶: Axial plane of the volume.

CORONAL = 'coronal'¶: Coronal plane of the volume.

SAGITTAL = 'sagittal'¶: Sagittal plane of the volume.

property figures : list[supervisely.video_annotation.video_figure.VideoFigure]¶

Get figures from all frames in collection.

Returns:

List of figures from all frames in collection

Return type:

List[VideoFigure]

Usage Example:

import supervisely as sly

fr_index_1 = 7
geometry = sly.Rectangle(0, 0, 100, 100)
obj_class_car = sly.ObjClass('car', sly.Rectangle)
video_object_car = sly.VideoObject(obj_class_car)
video_figure_car = sly.VideoFigure(video_object_car, geometry, fr_index_1)
frame_1 = sly.Frame(fr_index_1, figures=[video_figure_car])

fr_index_2 = 10
geometry = sly.Rectangle(0, 0, 500, 600)
obj_class_bus = sly.ObjClass('bus', sly.Rectangle)
video_object_bus = sly.VideoObject(obj_class_bus)
video_figure_bus = sly.VideoFigure(video_object_bus, geometry, fr_index_2)
frame_2 = sly.Frame(fr_index_2, figures=[video_figure_bus])

fr_collection = sly.FrameCollection([frame_1, frame_2])
figures = fr_collection.figures

property img_size : tuple[int]¶

Get the size of the image in the plane.

Returns:

Size of the image in the plane.

Return type:

Tuple[int]

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
print(plane.img_size)
# Output: (512, 512)

property name : str | None¶

Get the name of the plane.

Returns:

Name of the plane.

Return type:

Union[str, None]

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
print(plane.name)
# Output: axial

property normal : dict¶

Returns the normal vector of the plane.

Returns:

A dictionary representing the normal vector of the plane.

Return type:

dict

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
print(plane.normal)
# Output: {'x': 0, 'y': 0, 'z': 1}

property slices_count : int¶

Get the number of slices in the plane.

Returns:

Number of slices in the plane.

Return type:

int

Usage Example:

import supervisely as sly
path = "/Users/almaz/Downloads/my volumes/ds11111/Demo volumes_ds1_CTChest.nrrd"
vol, meta = sly.volume.read_nrrd_serie_volume(path)

plane = sly.Plane(sly.Plane.AXIAL, volume_meta=meta)
print(plane.slices_count)
# Output: 139