VolumeAnnotation¶

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

Bases: object

Annotation for a 3D volume: objects, tags, planes, spatial figures. Immutable.

Annotation for a 3D volume.

Parameters:

volume_meta : dict¶: Volume metadata (dimensions, spacing, origin, etc.).
objects=None¶: Collection of VolumeObjects.
plane_sagittal=None¶: Sagittal plane. Default Plane created if not provided.
plane_coronal=None¶: Coronal plane. Default Plane created if not provided.
plane_axial=None¶: Axial plane. Default Plane created if not provided.
tags=None¶: Collection of VolumeTags.
spatial_figures=None¶: List of VolumeFigures (e.g. Mask3D).
key : uuid.UUID, optional¶: UUID key. Auto-generated if not provided.

Usage Example:

import supervisely as sly

volume, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)

obj_class = sly.ObjClass('brain', sly.Rectangle)
volume_obj = sly.VolumeObject(obj_class)
vol_tag = sly.VolumeTag(sly.TagMeta('brain_tag', sly.TagValueType.ANY_STRING), value='human')
volume_ann = sly.VolumeAnnotation(
    volume_meta,
    sly.VolumeObjectCollection([volume_obj]),
    tags=sly.VolumeTagCollection([vol_tag]),
)

Methods

`add_objects`	Add new objects to a VolumeAnnotation object.
`add_tags`	Add new VolumeTags 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.
`dump_json`	Save the VolumeAnnotation to a json file.
`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.
`remove_objects`	Remove annotation objects from a VolumeAnnotation object.
`remove_tags`	Remove VolumeTags from a VolumeAnnotation object.
`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.

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

Convert a json dict to VolumeAnnotation.

Parameters:

data : dict¶: Volume annotation in json format as a dict.
project_meta¶: Input ProjectMeta object.
key_id_map=None¶: KeyIdMap object.
spatial_geometry_paths : list or dict, optional¶: Optional. Can be either: - a list of file paths to spatial geometry files, where each file name should match either the figure’s id or the hex value of its key, - or a dict mapping figure ids (or keys) to their corresponding geometry file paths. Used to load 3D geometry for spatial figures.

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)

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])

add_tags(tags)[source]¶

Add new VolumeTags to a VolumeAnnotation object.

Parameters:

tags¶: New VolumeTags.

Returns:

A VolumeAnnotation object containing the original and new volume tags.

Return type:

VolumeAnnotation

Usage Example:

import supervisely as sly

path = "/vol_01.nrrd"
_, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)
brain_meta = sly.TagMeta('brain_tag', sly.TagValueType.ANY_STRING)
vol_tag = sly.VolumeTag(brain_meta, value='human')
volume_ann = volume_ann.add_tags([vol_tag])

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=None¶: VolumeObjectCollection object.
plane_sagittal : Plane object, optional¶: Sagittal plane of the volume.
plane_coronal : Plane object, optional¶: Coronal plane of the volume.
plane_axial : Plane object, optional¶: Axial plane of the volume.
tags=None¶: VolumeTagCollection object.
spatial_figures=None¶: 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)

dump_json(path, key_id_map=None)[source]¶

Save the VolumeAnnotation to a json file.

Parameters:

path : str¶: Path to the json file.
key_id_map=None¶: KeyIdMap object.

Returns:

None

Return type:

None

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)
volume_ann.dump_json("/home/admin/work/volumes/vol_01.json")

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()

remove_objects(keys)[source]¶

Remove annotation objects from a VolumeAnnotation object.

Parameters:

keys : List[uuid.UUID] or uuid.UUID¶: List of object keys or single object key.

Returns:

A VolumeAnnotation object containing the original volume objects without the removed objects.

Return type:

VolumeAnnotation

Usage Example:

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)
obj_class_tumor = sly.ObjClass('tumor', sly.Mask3D)
volume_obj_tumor = sly.VolumeObject(obj_class_tumor)
volume_ann = volume_ann.add_objects([volume_obj_heart, volume_obj_tumor])
volume_ann = volume_ann.remove_objects(volume_obj_heart.key())

remove_tags(keys)[source]¶

Remove VolumeTags from a VolumeAnnotation object.

Parameters:

keys : List[uuid.UUID] or uuid.UUID¶: List of VolumeTag keys or single tag key.

Returns:

A VolumeAnnotation object containing the original VolumeTags without the removed VolumeTags.

Return type:

VolumeAnnotation

Usage Example:

import supervisely as sly

path = "/vol_01.nrrd"
_, volume_meta = sly.volume.read_nrrd_serie_volume_np(path)
volume_ann = sly.VolumeAnnotation(volume_meta)
brain_meta = sly.TagMeta('brain_tag', sly.TagValueType.ANY_STRING)
vol_tag = sly.VolumeTag(brain_meta, value='human')
volume_ann = volume_ann.add_tags([vol_tag])
volume_ann = volume_ann.remove_tags(vol_tag.key())

to_json(key_id_map=None)[source]¶

Convert the VolumeAnnotation to a json dict.

Parameters:

key_id_map=None¶: 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 :rtype: None

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 : list[supervisely.volume_annotation.volume_figure.VolumeFigure]¶

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 : supervisely.volume_annotation.volume_object_collection.VolumeObjectCollection¶

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 : supervisely.volume_annotation.plane.Plane¶

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 : supervisely.volume_annotation.plane.Plane¶

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 : supervisely.volume_annotation.plane.Plane¶

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 : list[supervisely.volume_annotation.volume_figure.VolumeFigure]¶

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 : supervisely.volume_annotation.volume_tag_collection.VolumeTagCollection¶

VolumeTag objects.

Returns:

VolumeTagCollection object

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 : dict¶

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