Plane¶

Bases: supervisely.video_annotation.frame_collection.FrameCollection

A class representing a plane in medical image data.

Parameters

plane_name : Union[str, None]: Name of the plane, should be one of “sagittal”, “coronal”, “axial”, or None for spatial figures.
img_size : Optional[Union[Tuple[int, int], None]]: Size of the plane image
slices_count : Optional[Union[int, None]]: Number of slices in the plane.
items : Oprional[List[Slice]]: List of Slice objects representing the slices in the plane.
volume_meta : Optional[dict]: Metadata of the volume.

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.name) # axial

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 supervisely.volume_annotation.slice.Slice

add(item)¶

Add given item to collection.

Parameters

item : KeyObject: 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[KeyObject]: 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 : List[KeyObject], optional: 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

key : List[KeyObject]: List of ObjClassCollection, TagMetaCollection or TagCollection objects.

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": []
#     }
# ]

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 : VolumeObjectCollection: 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 : Optional[KeyIdMap]: Dictionary mapping object keys to object IDs.

Returns

A new class: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,
)

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)
pprint(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: KeyIdMap object.

Returns

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

Return type

Tuple[list, list]

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
#         }
#     }
# ]

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

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

key : List[KeyObject]: List of ObjClassCollection, TagMetaCollection or TagCollection objects.

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

key : KeyIndexedCollection: KeyIndexedCollection object.

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 : Optional[KeyIdMap]: 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.

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]

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

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

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

property figures¶

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¶

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¶

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¶

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¶

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