Skip to content

webknossos.annotation.annotation

Annotations can contain annotated data in two forms:

  • skeleton data, as provided by the Skeleton class, and
  • volume annotation layers (or volume layers short), which can be exported as a SegmentationLayer, see export_volume_layer_to_dataset() and temporary_volume_layer_copy().

Usually, annotations should be created manually in the WEBKNOSSOS interface and can be downloaded using Annotation.download(). The downloaded instance is not persisted to disk automatically, please use save() for this purpose. The general purpose file format is .zip files containing an .nml file with meta-information and the skeleton data and also containing inner .zip files for the volume layers. For skeleton-only annotations without volume layers .nml files can be used directly. Both formats are compatible with the WEBKNOSSOS up- and downloads.

To prepare volume annotations in the code for correction of segmentation data in the WEBKNOSSOS interface, please use add_volume_layer() with the fallback_layer argument, referencing a segmentation layer that is available on WEBKNOSSOS (e.g. using the Dataset upload before). Correcting segmentations using fallback layers is much more efficient, adding volume annotation data programmatically is discouraged therefore.

Classes:

Annotation

Methods:

Attributes:

annotation_id class-attribute instance-attribute 

annotation_id: Optional[str] = None

dataset_name property writable 

dataset_name: str

This attribute is a proxy for skeleton.dataset_name.

description property writable 

description: Optional[str]

This attribute is a proxy for skeleton.description.

edit_position class-attribute instance-attribute 

edit_position: Optional[Vector3] = None

edit_rotation class-attribute instance-attribute 

edit_rotation: Optional[Vector3] = None

metadata class-attribute instance-attribute 

metadata: Dict[str, str] = Factory(dict)

name instance-attribute 

name: str

organization_id property writable 

organization_id: Optional[str]

This attribute is a proxy for skeleton.organization_id.

owner_name class-attribute instance-attribute 

owner_name: Optional[str] = None

scale property writable 

scale: Tuple[float, float, float]

Deprecated, please use voxel_size.

skeleton class-attribute instance-attribute 

skeleton: Skeleton = None

task_bounding_box class-attribute instance-attribute 

task_bounding_box: Optional[NDBoundingBox] = None

time class-attribute instance-attribute 

time: Optional[int] = ib(factory=time_since_epoch_in_ms)

user_bounding_boxes class-attribute instance-attribute 

user_bounding_boxes: List[NDBoundingBox] = Factory(list)

username property writable 

username: Optional[str]

Deprecated, use owner_name instead.

voxel_size property writable 

voxel_size: Tuple[float, float, float]

This attribute is a proxy for skeleton.voxel_size.

zoom_level class-attribute instance-attribute 

zoom_level: Optional[float] = None

add_volume_layer 

add_volume_layer(name: str, fallback_layer: Union[Layer, str, None] = None, volume_layer_id: Optional[int] = None) -> None

Adds a volume layer to the annotation, without manual annotations but possibly referring to segmentation data using the fallback_layer. To prepare volume annotations in the code for correction of segmentation data in the WEBKNOSSOS interface, please use the fallback_layer argument, referencing a segmentation layer that is available on WEBKNOSSOS (e.g. using the Dataset upload before). Correcting segmentations using fallback layers is much more efficient, adding volume annotation data programmatically is discouraged therefore.

delete_volume_layer 

delete_volume_layer(volume_layer_name: Optional[str] = None, volume_layer_id: Optional[int] = None) -> None

download classmethod 

download(annotation_id_or_url: str, annotation_type: Union[str, AnnotationType, None] = None, webknossos_url: Optional[str] = None, *, skip_volume_data: bool = False) -> Annotation

download(annotation_id_or_url: str, annotation_type: Union[str, AnnotationType, None] = None, webknossos_url: Optional[str] = None, *, skip_volume_data: bool = False, _return_context: bool) -> Tuple[Annotation, ContextManager[None]]

download(annotation_id_or_url: str, annotation_type: Union[str, AnnotationType, None] = None, webknossos_url: Optional[str] = None, *, skip_volume_data: bool = False, _return_context: bool = False) -> Union[Annotation, Tuple[Annotation, ContextManager[None]]]
  • annotation_id_or_url may be an annotation id or a full URL to an annotation, e.g. https://webknossos.org/annotations/6114d9410100009f0096c640
  • annotation_type is no longer required and therefore deprecated and ignored
  • webknossos_url may be supplied if an annotation id was used and allows to specify in which webknossos instance to search for the annotation. It defaults to the url from your current webknossos_context, using https://webknossos.org as a fallback.
  • skip_volume_data can be set to True to omit downloading annotated volume data. They can still be streamed from WEBKNOSSOS using annotation.get_remote_annotation_dataset().
  • _return_context should not be set.

export_volume_layer_to_dataset 

export_volume_layer_to_dataset(dataset: Dataset, layer_name: str = 'volume_layer', volume_layer_name: Optional[str] = None, volume_layer_id: Optional[int] = None) -> SegmentationLayer

Given a dataset, this method will export the specified volume annotation of this annotation into that dataset by creating a new layer. The largest_segment_id is computed automatically, unless provided explicitly.

volume_layer_name or volume_layer_id has to be provided, if the annotation contains multiple volume layers. Use get_volume_layer_names() to look up available layers.

get_remote_annotation_dataset 

get_remote_annotation_dataset() -> Dataset

Returns a streamed dataset of the annotation as shown in webknossos, incorporating fallback layers and potentially mappings. A mapping is currently only incorporated if it is a pinned agglomerate mapping. After an agglomerate mapping was activated in WEBKNOSSOS, it is pinned as soon as the first volume editing action is done. Note that this behavior might change in the future.

get_remote_base_dataset 

get_remote_base_dataset(sharing_token: Optional[str] = None, webknossos_url: Optional[str] = None) -> RemoteDataset

get_volume_layer_names 

get_volume_layer_names() -> Iterable[str]

get_volume_layer_segments 

get_volume_layer_segments(volume_layer_name: Optional[str] = None, volume_layer_id: Optional[int] = None) -> Dict[int, SegmentInformation]

Returns a dict mapping from segment ids to SegmentInformation. The dict is mutable, changes to the returned instance are saved in the local annotation. Changes in a downloaded annotation that are done online in webknossos are not reflected automatically, the annotation needs to be re-downloaded.

load classmethod 

load(annotation_path: Union[str, PathLike]) -> Annotation

Loads a .nml file or a .zip file containing an NML and possibly also volume layers. Returns the Annotation object.

merge_fallback_layer 

merge_fallback_layer(target: Path, dataset_directory: Path, volume_layer_name: Optional[str] = None, executor: Optional[Executor] = None) -> None

Merge the volume annotation with the fallback layer.

open_as_remote_dataset classmethod 

open_as_remote_dataset(annotation_id_or_url: str, annotation_type: Union[str, AnnotationType, None] = None, webknossos_url: Optional[str] = None) -> Dataset

save 

save(path: Union[str, PathLike]) -> None

Stores the annotation as a zip or nml at the given path.

temporary_volume_layer_copy 

temporary_volume_layer_copy(volume_layer_name: Optional[str] = None, volume_layer_id: Optional[int] = None, read_only: bool = True) -> Iterator[SegmentationLayer]

Given a volume annotation path, create a temporary dataset which contains the volume annotation. Returns the corresponding Layer.

volume_layer_name or volume_layer_id has to be provided, if the annotation contains multiple volume layers.

upload 

upload() -> str

Uploads the annotation to your current webknossos_context.

AnnotationState

Bases: Enum

This Enum contains the state of annotations belonging to tasks. Can be retrieved via Task instances, getting AnnotationInfo from task.get_annotation_infos().

Attributes:

ACTIVE class-attribute instance-attribute 

ACTIVE = 'Active'

CANCELLED class-attribute instance-attribute 

CANCELLED = 'Cancelled'

FINISHED class-attribute instance-attribute 

FINISHED = 'Finished'

INITIALIZING class-attribute instance-attribute 

INITIALIZING = 'Initializing'

AnnotationType

Bases: Enum

Annotations can be of different types which has to be specified when using Annotation.download() with an annotation id.

Attributes:

  • EXPLORATIONAL –

    Explorational annotations are all annotations created without the task system, e.g.

  • TASK –

    The Task type is automatically assigned to all annotations that are instances of a task.

EXPLORATIONAL class-attribute instance-attribute 

EXPLORATIONAL = 'Explorational'

Explorational annotations are all annotations created without the task system, e.g. by uploading an annotation or using the "Create Annotation" Button in the dataset view in webknossos.

TASK class-attribute instance-attribute 

TASK = 'Task'

The Task type is automatically assigned to all annotations that are instances of a task. See also Task.

SegmentInformation

Attributes:

anchor_position instance-attribute 

anchor_position: Optional[Vec3Int]

color instance-attribute 

color: Optional[Vector4]

name instance-attribute 

name: Optional[str]