VolumeAnnotation¶

class VolumeAnnotation[source]¶

Bases: object

VolumeAnnotation for a single volume. VolumeAnnotation object is immutable.

Parameters

volume_meta : dict: Metadata of the volume.
objects : VolumeObjectCollection, optional: VolumeObjectCollection object.
plane_sagittal : Plane, optional: Sagittal plane of the volume.
plane_coronal : Plane, optional: Coronal plane of the volume.
plane_axial : Plane, optional: Axial plane of the volume.
tags : VolumeTagCollection, optional: VolumeTagCollection object.
spatial_figures : List[VolumeFigure], optional: List of spatial figures associated with the volume.
key : UUID, optional: UUID object.

Usage example

import supervisely as sly

# Simple VolumeAnnotation example
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)
print(volume_ann.to_json())
# Output: {
# {
#     "key": "56107223943346e5900fc256b8dcd7f0",
#     "objects": [],
#     "planes": [
#         { "name": "sagittal", "normal": { "x": 1, "y": 0, "z": 0 }, "slices": [] },
#         { "name": "coronal", "normal": { "x": 0, "y": 1, "z": 0 }, "slices": [] },
#         { "name": "axial", "normal": { "x": 0, "y": 0, "z": 1 }, "slices": [] }
#     ],
#     "spatialFigures": [],
#     "tags": [],
#     "volumeMeta": {
#         "ACS": "RAS",
#         "channelsCount": 1,
#         "dimensionsIJK": { "x": 512, "y": 512, "z": 139 },
#         "directions": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0],
#         "intensity": { "max": 3071.0, "min": -3024.0 },
#         "origin": [-194.238403081894, -217.5384061336518, -347.7500000000001],
#         "rescaleIntercept": 0,
#         "rescaleSlope": 1,
#         "spacing": [0.7617189884185793, 0.7617189884185793, 2.5],
#         "windowCenter": 23.5,
#         "windowWidth": 6095.0
#     }
# }

# More complex VolumeAnnotation example

path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
# VolumeObjectCollection
obj_class = sly.ObjClass('brain', sly.Rectangle)
volume_obj = sly.VolumeObject(obj_class)
objects = sly.VolumeObjectCollection([volume_obj])
# VolumeTagCollection
brain_meta = sly.TagMeta('brain_tag', sly.TagValueType.ANY_STRING)
from supervisely.volume_annotation.volume_tag import VolumeTag
vol_tag = VolumeTag(brain_meta, value='human')
from supervisely.volume_annotation.volume_tag_collection import VolumeTagCollection
volume_tags = VolumeTagCollection([vol_tag])

volume_ann = sly.VolumeAnnotation(volume_meta, objects, volume_tags)
print(volume_ann.to_json())
# Output:
# {
#     "key": "4d4bb69e6fcd40e1a1cb076c07769903",
#     "objects": [
#         {
#         "classTitle": "brain",
#         "key": "22e1082a17f74279b00eed0bfb0ba11d",
#         "tags": []
#         }
#     ],
#     "planes": [
#         { "name": "sagittal", "normal": { "x": 1, "y": 0, "z": 0 }, "slices": [] },
#         { "name": "coronal", "normal": { "x": 0, "y": 1, "z": 0 }, "slices": [] },
#         { "name": "axial", "normal": { "x": 0, "y": 0, "z": 1 }, "slices": [] }
#     ],
#     "spatialFigures": [],
#     "tags": [
#         {
#         "key": "b9de6631d328441796119b4b0039fc61",
#         "name": "brain_tag",
#         "value": "human"
#         }
#     ],
#     "volumeMeta": {
#         "ACS": "RAS",
#         "channelsCount": 1,
#         "dimensionsIJK": { "x": 512, "y": 512, "z": 139 },
#         "directions": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0],
#         "intensity": { "max": 3071.0, "min": -3024.0 },
#         "origin": [-194.238403081894, -217.5384061336518, -347.7500000000001],
#         "rescaleIntercept": 0,
#         "rescaleSlope": 1,
#         "spacing": [0.7617189884185793, 0.7617189884185793, 2.5],
#         "windowCenter": 23.5,
#         "windowWidth": 6095.0
#     }
# }

Methods

`add_objects`	Add new objects to a VolumeAnnotation object.
`clone`	Makes a copy of VolumeAnnotation with new fields, if fields are given, otherwise it will use fields of the original VolumeAnnotation.
`from_json`	Convert a json dict to VolumeAnnotation.
`is_empty`	Check whether volume annotation contains objects or tags, or not.
`key`	Volume annotation key value.
`to_json`	Convert the VolumeAnnotation to a json dict.
`validate_figures_bounds`	Checks if all slices in each plane contains figures.

Attributes

`figures`	VolumeFigure objects.
`objects`	VolumeAnnotation objects.
`plane_axial`	Axial plane of the volume.
`plane_coronal`	Coronal plane of the volume.
`plane_sagittal`	Sagital plane of the volume.
`spatial_figures`	Get a list of spatial figures.
`tags`	VolumeTag objects.
`volume_meta`	Volume meta data.

add_objects(objects)[source]¶

Add new objects to a VolumeAnnotation object.

Parameters

objects : List[VolumeObject] or VolumeObjectCollection: New volume objects.

Returns

A VolumeAnnotation object containing the original and new volume objects.

Return type

VolumeAnnotation

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

path = "/vol_01.nrrd"
_, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)
obj_class_heart = sly.ObjClass('heart', sly.Mask3D)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
volume_ann = volume_ann.add_objects([volume_obj_heart])

clone(volume_meta=None, objects=None, plane_sagittal=None, plane_coronal=None, plane_axial=None, tags=None, spatial_figures=None)[source]¶

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

Parameters

volume_meta : dict: Metadata of the volume.
objects : VolumeObjectCollection, optional: VolumeObjectCollection object.
plane_sagittal : Plane, optional: Sagittal plane of the volume.
plane_coronal : Plane, optional: Coronal plane of the volume.
plane_axial : Plane, optional: Axial plane of the volume.
tags : VolumeTagCollection, optional: VolumeTagCollection object.
spatial_figures : List[VolumeFigure], optional: List of spatial figures associated with the volume.

Usage example

import supervisely as sly

path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)

obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
video_obj_heart = sly.VolumeObject(obj_class_heart)
new_objects = sly.VolumeObjectCollection([volume_obj_heart])
new_volume_ann = volume_ann.clone(objects=new_objects)

classmethod from_json(data, project_meta, key_id_map=None)[source]¶

Convert a json dict to VolumeAnnotation.

Parameters

data : dict: Volume annotation in json format as a dict.
project_meta : ProjectMeta: Input ProjectMeta.
key_id_map : KeyIdMap, optional: KeyIdMap object.

Returns

VolumeAnnotation object

Return type

VolumeAnnotation

Usage example

import supervisely as sly

from supervisely.video_annotation.key_id_map import KeyIdMap

meta = sly.ProjectMeta()
key_id_map = KeyIdMap()

ann_json = {
    "key": "56107223943346e5900fc256b8dcd7f0",
    "objects": [],
    "planes": [
        { "name": "sagittal", "normal": { "x": 1, "y": 0, "z": 0 }, "slices": [] },
        { "name": "coronal", "normal": { "x": 0, "y": 1, "z": 0 }, "slices": [] },
        { "name": "axial", "normal": { "x": 0, "y": 0, "z": 1 }, "slices": [] }
    ],
    "spatialFigures": [],
    "tags": [],
    "volumeMeta": {
        "ACS": "RAS",
        "channelsCount": 1,
        "dimensionsIJK": { "x": 512, "y": 512, "z": 139 },
        "directions": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0],
        "intensity": { "max": 3071.0, "min": -3024.0 },
        "origin": [-194.238403081894, -217.5384061336518, -347.7500000000001],
        "rescaleIntercept": 0,
        "rescaleSlope": 1,
        "spacing": [0.7617189884185793, 0.7617189884185793, 2.5],
        "windowCenter": 23.5,
        "windowWidth": 6095.0
    }
}


ann = sly.VolumeAnnotation.from_json(ann_json, meta, key_id_map)

is_empty()[source]¶

Check whether volume annotation contains objects or tags, or not.

Returns

True if volume annotation is empty, False otherwise.

Return type

bool

Usage exmaple

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)

is_empty = vol_ann.is_empty()

key()[source]¶

Volume annotation key value.

Returns

Key value of VolumeAnnotation object.

Return type

str

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
key = vol_ann.key()

to_json(key_id_map=None)[source]¶

Convert the VolumeAnnotation to a json dict.

Parameters

key_id_map : KeyIdMap, optional: KeyIdMap object.

Returns

Volume annotation in json format as a dict.

Return type

dict

Usage example

import supervisely as sly

from supervisely.video_annotation.key_id_map import KeyIdMap

path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)

print(volume_ann.to_json())
# Output: {
# {
#     "key": "56107223943346e5900fc256b8dcd7f0",
#     "objects": [],
#     "planes": [
#         { "name": "sagittal", "normal": { "x": 1, "y": 0, "z": 0 }, "slices": [] },
#         { "name": "coronal", "normal": { "x": 0, "y": 1, "z": 0 }, "slices": [] },
#         { "name": "axial", "normal": { "x": 0, "y": 0, "z": 1 }, "slices": [] }
#     ],
#     "spatialFigures": [],
#     "tags": [],
#     "volumeMeta": {
#         "ACS": "RAS",
#         "channelsCount": 1,
#         "dimensionsIJK": { "x": 512, "y": 512, "z": 139 },
#         "directions": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0],
#         "intensity": { "max": 3071.0, "min": -3024.0 },
#         "origin": [-194.238403081894, -217.5384061336518, -347.7500000000001],
#         "rescaleIntercept": 0,
#         "rescaleSlope": 1,
#         "spacing": [0.7617189884185793, 0.7617189884185793, 2.5],
#         "windowCenter": 23.5,
#         "windowWidth": 6095.0
#     }
# }

validate_figures_bounds()[source]¶

Checks if all slices in each plane contains figures.

Raises

OutOfImageBoundsException, if figure is out of slices images bounds

Returns

None

Return type

NoneType

Usage Example

import supervisely as sly

plane_axial = sly.Plane(sly.Plane.AXIAL, frames, volume_meta=volume_meta)
volume_ann = sly.VolumeAnnotation(volume_meta, objects, plane_axial=plane_axial)
volume_ann.validate_figures_bounds()

property figures¶

VolumeFigure objects.

Returns

List of VolumeFigure objects from VolumeAnnotation object.

Return type

List[VolumeFigure]

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
figures = vol_ann.figures

property objects¶

VolumeAnnotation objects.

Returns

VolumeObjectCollection object

Return type

VolumeObjectCollection

Usage example

import supervisely as sly

path = "/Users/Downloads/volumes/Demo volumes_ds1_CTChest.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)

# VolumeObjectCollection
obj_class_heart = sly.ObjClass('heart', sly.Rectangle)
volume_obj_heart = sly.VolumeObject(obj_class_heart)
objects = sly.VolumeObjectCollection([volume_obj_heart])
volume_ann = sly.VolumeAnnotation(volume_meta, objects)

print(volume_ann.objects.to_json())
# Output: [
#     {
#         "key": "2b5d70baa5a74d06a525b950b5f2b756",
#         "classTitle": "heart",
#         "tags": []
#     }
# ]

property plane_axial¶

Axial plane of the volume.

Returns

Axial plane of the volume.

Return type

Plane

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
plane_axial = vol_ann.plane_axial

property plane_coronal¶

Coronal plane of the volume.

Returns

Coronal plane of the volume.

Return type

Plane

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
plane_coronal = vol_ann.plane_coronal

property plane_sagittal¶

Sagital plane of the volume.

Returns

Sagittal plane of the volume.

Return type

Plane

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
plane_sagittal = vol_ann.plane_sagittal

property spatial_figures¶

Get a list of spatial figures.

Returns

List of spatial figures from VolumeAnnotation object.

Return type

List[VolumeFigure]

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
spatial_figures = vol_ann.spatial_figures

property tags¶

VolumeTag objects.

Returns

VolumeTagCollection

Return type

VolumeTagCollection

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
tags = vol_ann.tags

property volume_meta¶

Volume meta data.

Returns

Sagittal plane of the volume.

Return type

dict

Usage example

import supervisely as sly
path = "/home/admin/work/volumes/vol_01.nrrd"
volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
vol_ann = sly.VolumeAnnotation(volume_meta)
volume_meta = vol_ann.volume_meta