|
1 | | -"""Annotations can contain annotated data in two forms: |
2 | | -
|
3 | | - - [skeleton data](/webknossos/skeleton_annotation/index.html), as provided by the `Skeleton` class, and |
4 | | - - [volume annotation layers](/webknossos/volume_annotation/index.html) (or volume layers short), |
5 | | - which can be exported as a `SegmentationLayer`, see `export_volume_layer_to_dataset()` |
6 | | - and `temporary_volume_layer_copy()`. |
7 | | -
|
8 | | -Usually, annotations should be created manually in the WEBKNOSSOS interface and can be downloaded using |
9 | | -`Annotation.download()`. The downloaded instance is not persisted to disk automatically, please use `save()` |
10 | | -for this purpose. The general purpose file format is `.zip` files containing an `.nml` file with |
11 | | -meta-information and the skeleton data and also containing inner `.zip` files for the volume layers. |
12 | | -For skeleton-only annotations without volume layers `.nml` files can be used directly. Both formats |
13 | | -are compatible with the WEBKNOSSOS up- and downloads. |
14 | | -
|
15 | | -To prepare volume annotations in the code for correction of segmentation data in the WEBKNOSSOS interface, |
16 | | -please use `add_volume_layer()` with the `fallback_layer` argument, referencing a segmentation layer that |
17 | | -is available on WEBKNOSSOS (e.g. using the `Dataset` upload before). |
18 | | -Correcting segmentations using fallback layers is much more efficient, adding volume |
19 | | -annotation data programmatically is discouraged therefore. |
| 1 | +"""WEBKNOSSOS annotation module for working with skeleton and volume data. |
| 2 | +
|
| 3 | +This module provides the Annotation class for handling WEBKNOSSOS annotations, which can |
| 4 | +contain two types of data: |
| 5 | +
|
| 6 | + 1. Skeleton Data: Represented by the `Skeleton` class, e.g. for annotating neural pathways |
| 7 | + and structures. |
| 8 | + 2. Volume Annotation Layers: Used for segmentation data, can be exported as |
| 9 | + `SegmentationLayer` objects. |
| 10 | +
|
| 11 | +The module supports various operations including: |
| 12 | + * Loading/saving annotations from/to .nml or .zip files |
| 13 | + * Downloading/uploading annotations from/to WEBKNOSSOS |
| 14 | + * Working with skeleton data and volume layers |
| 15 | + * Exporting volume layers to datasets |
| 16 | +
|
| 17 | +Typical usage Examples: |
| 18 | + ```python |
| 19 | + # Download an annotation from WEBKNOSSOS |
| 20 | + annotation = Annotation.download("annotation_id") |
| 21 | +
|
| 22 | + # Add a volume layer with fallback for efficient processing |
| 23 | + annotation.add_volume_layer( |
| 24 | + name="segmentation", |
| 25 | + fallback_layer="original_segmentation" |
| 26 | + ) |
| 27 | +
|
| 28 | + # Save the annotation locally |
| 29 | + annotation.save("my_annotation.zip") |
| 30 | + ``` |
| 31 | +
|
| 32 | +Notes: |
| 33 | + For volume annotations, using fallback layers is recommended for better performance |
| 34 | + in WEBKNOSSOS. Adding volume annotation data programmatically should be avoided |
| 35 | + when possible. |
| 36 | +
|
| 37 | +See Also: |
| 38 | + * Skeleton documentation: /webknossos/skeleton_annotation/index.html |
| 39 | + * Volume annotation documentation: /webknossos/volume_annotation/index.html |
20 | 40 | """ |
21 | 41 |
|
22 | 42 | import json |
@@ -489,6 +509,40 @@ def open_as_remote_dataset( |
489 | 509 | annotation_type: Union[str, "AnnotationType", None] = None, |
490 | 510 | webknossos_url: Optional[str] = None, |
491 | 511 | ) -> Dataset: |
| 512 | + """Opens an annotation directly as a remote dataset from WEBKNOSSOS. |
| 513 | +
|
| 514 | + This is a convenience method that combines downloading an annotation and converting it |
| 515 | + to a remote dataset in one step. It's useful when you want to work with the annotation |
| 516 | + data as a dataset without storing it locally. |
| 517 | +
|
| 518 | + Args: |
| 519 | + annotation_id_or_url: Either an annotation ID or complete WEBKNOSSOS URL. |
| 520 | + Example URL: https://webknossos.org/annotations/[id] |
| 521 | + annotation_type: ⚠️ Deprecated and no longer required. |
| 522 | + Optional type of annotation (Explorational, Task, etc.). |
| 523 | + webknossos_url: Optional custom WEBKNOSSOS instance URL. |
| 524 | +
|
| 525 | + Returns: |
| 526 | + Dataset: A remote dataset instance representing the annotation. |
| 527 | +
|
| 528 | + Examples: |
| 529 | + ```python |
| 530 | + # Open by ID |
| 531 | + dataset = Annotation.open_as_remote_dataset("5f7d3a...") |
| 532 | +
|
| 533 | + # Open by URL |
| 534 | + dataset = Annotation.open_as_remote_dataset( |
| 535 | + "https://webknossos.org/annotations/5f7d3a..." |
| 536 | + ) |
| 537 | +
|
| 538 | + # Access layers |
| 539 | + layer = dataset.get_layer("segmentation") |
| 540 | + ``` |
| 541 | +
|
| 542 | + Notes: |
| 543 | + This method automatically skips downloading volume data locally for efficiency, |
| 544 | + as the data will be streamed from the remote source. |
| 545 | + """ |
492 | 546 | ( |
493 | 547 | annotation, |
494 | 548 | context, |
@@ -857,7 +911,7 @@ def get_remote_annotation_dataset(self) -> Dataset: |
857 | 911 | # Access layers |
858 | 912 | layer = dataset.get_layer("segmentation") |
859 | 913 | ``` |
860 | | - Note: |
| 914 | + Notes: |
861 | 915 | After an agglomerate mapping was activated in WEBKNOSSOS, it is applied to this method as soon |
862 | 916 | as the first volume editing action is done. Note that this behavior might change |
863 | 917 | in the future. |
@@ -1277,7 +1331,7 @@ def get_volume_layer_segments( |
1277 | 1331 | # Update segment name |
1278 | 1332 | segments[1].name = "Cell A" |
1279 | 1333 | ``` |
1280 | | - Note: |
| 1334 | + Notes: |
1281 | 1335 | Any changes performed on the online version of the annotaiton in webknossos are not |
1282 | 1336 | synced automatically. The annotation needs to be re-downloaded to update segment information. |
1283 | 1337 | """ |
@@ -1350,12 +1404,3 @@ def open_annotation(annotation_path: Union[str, PathLike]) -> "Annotation": |
1350 | 1404 | ), f"Called open_annotation with a path-like, but {annotation_path} does not exist." |
1351 | 1405 | warn_deprecated("open_annotation", "Annotation.download") |
1352 | 1406 | return Annotation.download(annotation_path) |
1353 | | - |
1354 | | - |
1355 | | -def _parse_filename_from_header(value: str) -> str: |
1356 | | - # Adapted from https://peps.python.org/pep-0594/#cgi |
1357 | | - from email.message import Message |
1358 | | - |
1359 | | - m = Message() |
1360 | | - m["content-type"] = value |
1361 | | - return dict(m.get_params() or []).get("filename", "") |
|
0 commit comments