Annotation: support empty volumes & make volume location optional (#814)

* support empty volumes in temporary_volume_layer_copy(), make volume locations optional

* rm superflouos import

* update message

* add changelog entries

* use cls for BoundingBox constructors

Author: jstriebel

webknossos/Changelog.md

@@ -17,8 +17,11 @@ For upgrade instructions, please check the respective *Breaking Changes* section
 ### Added
 
 ### Changed
+- Make volume locations optional, allowing to parse segment information in future NML-only annotations. [#814](https://github.com/scalableminds/webknossos-libs/pull/814)
 
 ### Fixed
+- `annotation.temporary_volume_layer_copy()` works also with empty volume annotations. [#814](https://github.com/scalableminds/webknossos-libs/pull/814)
+
 
 
 ## [0.10.19](https://github.com/scalableminds/webknossos-libs/releases/tag/v0.10.19) - 2022-10-18

webknossos/testdata/annotations/empty_volume_annotation.zip

@@ -0,0 +1,24 @@
+<things>
+  <meta name="writer" content="NmlWriter.scala" />
+  <meta name="writerGitCommit" content="d35e587fb59752e1899be99e2d5e046b186a5d6f" />
+  <meta name="timestamp" content="1666187511849" />
+  <meta name="annotationId" content="635000ac0100007800c91264" />
+  <meta name="username" content="Sample User" />
+  <parameters>
+    <experiment name="l4_sample" organization="sample_organization" description="" />
+    <scale x="11.239999771118164" y="11.239999771118164" z="28.0" />
+    <offset x="0" y="0" z="0" />
+    <time ms="1666187436145" />
+    <editPosition x="3581" y="3585" z="1024" />
+    <editRotation xRot="0.0" yRot="0.0" zRot="0.0" />
+    <zoomLevel zoom="1.0" />
+  </parameters>
+  <branchpoints />
+  <comments />
+  <groups />
+  <volume id="0" name="segmentation" fallbackLayer="segmentation" largestSegmentId="2504698"><!--Note that volume data was omitted when downloading this annotation.-->
+    <segments>
+      <segment id="2504698" name="test_segment" created="1666187488227" anchorPositionX="3581" anchorPositionY="3585" anchorPositionZ="1024" />
+    </segments>
+  </volume>
+</things>

webknossos/testdata/annotations/nml_with_volumes.nml

@@ -204,3 +204,39 @@ def check_properties(annotation: wk.Annotation) -> None:
 
         annotation_deserialized = wk.Annotation.load(output_path)
         check_properties(annotation_deserialized)
+
+
+def test_empty_volume_annotation() -> None:
+    a = wk.Annotation.load(TESTDATA_DIR / "annotations" / "empty_volume_annotation.zip")
+    with a.temporary_volume_layer_copy() as layer:
+        assert layer.bounding_box == wk.BoundingBox.empty()
+        assert layer.largest_segment_id == 0
+        assert set(layer.mags) == set(
+            [
+                wk.Mag(1),
+                wk.Mag((2, 2, 1)),
+                wk.Mag((4, 4, 1)),
+                wk.Mag((8, 8, 1)),
+                wk.Mag((16, 16, 1)),
+            ]
+        )
+
+
+@pytest.mark.parametrize(
+    "nml_path",
+    [
+        TESTDATA_DIR / "annotations" / "nml_with_volumes.nml",
+        TESTDATA_DIR / "annotations" / "nml_with_volumes.zip",
+    ],
+)
+def test_nml_with_volumes(nml_path: Path) -> None:
+    if nml_path.suffix == ".zip":
+        with pytest.warns(UserWarning, match="location is not referenced in the NML"):
+            a = wk.Annotation.load(nml_path)
+    else:
+        a = wk.Annotation.load(nml_path)
+    segment_info = a.get_volume_layer_segments("segmentation")
+    assert set(segment_info) == set([2504698])
+    assert segment_info[2504698] == wk.SegmentInformation(
+        name="test_segment", anchor_position=Vec3Int(3581, 3585, 1024), color=None
+    )

webknossos/testdata/annotations/nml_with_volumes.zip

@@ -9,7 +9,9 @@
 
 class Volume(NamedTuple):
     id: int
-    location: str  # path to a ZIP file containing a wK volume annotation
+    location: Optional[
+        str
+    ]  # path to a ZIP file containing a wK volume annotation, may be omitted when using skip_volume_data
     # name of an already existing wK volume annotation segmentation layer:
     fallback_layer: Optional[str]
     # older wk versions did not serialize the name which is why the name is optional:
@@ -39,7 +41,7 @@ def _dump(self, xf: XmlWriter) -> None:
     def _parse(cls, nml_volume: Element) -> "Volume":
         return cls(
             id=int(enforce_not_null(nml_volume.get("id"))),
-            location=enforce_not_null(nml_volume.get("location")),
+            location=nml_volume.get("location"),
             fallback_layer=nml_volume.get("fallbackLayer", default=None),
             name=nml_volume.get("name", default=None),
             segments=[],

webknossos/tests/test_annotation.py

@@ -2,6 +2,7 @@
     Annotation,
     AnnotationState,
     AnnotationType,
+    SegmentInformation,
     open_annotation,
 )
 from webknossos.annotation.annotation_info import AnnotationInfo

webknossos/webknossos/_nml/volume.py

@@ -219,14 +219,7 @@ def load(cls, annotation_path: Union[str, PathLike]) -> "Annotation":
             return cls._load_from_zip(annotation_path)
         elif annotation_path.suffix == ".nml":
             with annotation_path.open(mode="rb") as f:
-                annotation, nml = cls._load_from_nml(annotation_path.stem, f)
-            if len(nml.volumes) > 0:
-                warnings.warn(
-                    "The loaded nml contains references to volume layer annotations. "
-                    + "Those can only be loaded from a zip-file containing the nml and the volume annotation layer zips. "
-                    + "Omitting the volume layer annotations."
-                )
-            return annotation
+                return cls._load_from_nml(annotation_path.stem, f)
         else:
             raise RuntimeError(
                 "The loaded annotation must have the suffix .zip or .nml, but is {annotation_path.suffix}"
@@ -327,12 +320,9 @@ def download(
         _header_value, header_params = cgi.parse_header(content_disposition_header)
         filename = header_params.get("filename", "")
         if filename.endswith(".nml"):
-            annotation, nml = Annotation._load_from_nml(
+            annotation = Annotation._load_from_nml(
                 filename[:-4], BytesIO(response.content)
             )
-            assert (
-                len(nml.volumes) == 0
-            ), "The downloaded NML contains volume tags, it should have downloaded a zip instead."
         else:
             assert filename.endswith(
                 ".zip"
@@ -367,54 +357,66 @@ def open_as_remote_dataset(
 
     @classmethod
     def _load_from_nml(
-        cls, name: str, nml_content: BinaryIO
-    ) -> Tuple["Annotation", wknml.Nml]:
+        cls,
+        name: str,
+        nml_content: BinaryIO,
+        possible_volume_paths: Optional[List[ZipPath]] = None,
+    ) -> "Annotation":
         nml = wknml.Nml.parse(nml_content)
 
-        return (
-            cls(
-                name=name,
-                skeleton=nml_to_skeleton(nml),
-                owner_name=nml.get_meta("username"),
-                annotation_id=nml.get_meta("annotationId"),
-                time=nml.parameters.time,
-                edit_position=nml.parameters.editPosition,
-                edit_rotation=nml.parameters.editRotation,
-                zoom_level=nml.parameters.zoomLevel,
-                task_bounding_box=nml.parameters.taskBoundingBox,
-                user_bounding_boxes=nml.parameters.userBoundingBoxes or [],
-                metadata={
-                    i.name: i.content
-                    for i in nml.meta
-                    if i.name not in ["username", "annotationId"]
-                },
-            ),
-            nml,
+        annotation = cls(
+            name=name,
+            skeleton=nml_to_skeleton(nml),
+            owner_name=nml.get_meta("username"),
+            annotation_id=nml.get_meta("annotationId"),
+            time=nml.parameters.time,
+            edit_position=nml.parameters.editPosition,
+            edit_rotation=nml.parameters.editRotation,
+            zoom_level=nml.parameters.zoomLevel,
+            task_bounding_box=nml.parameters.taskBoundingBox,
+            user_bounding_boxes=nml.parameters.userBoundingBoxes or [],
+            metadata={
+                i.name: i.content
+                for i in nml.meta
+                if i.name not in ["username", "annotationId"]
+            },
         )
+        annotation._volume_layers = cls._parse_volumes(nml, possible_volume_paths)
+        return annotation
 
-    @classmethod
-    def _load_from_zip(cls, content: Union[str, PathLike, BinaryIO]) -> "Annotation":
-        zipfile = ZipFile(content)
-        paths = [ZipPath(zipfile, i.filename) for i in zipfile.filelist]
-        nml_paths = [i for i in paths if i.suffix == ".nml"]
-        assert len(nml_paths) > 0, "Couldn't find an nml file in the supplied zip-file."
-        assert (
-            len(nml_paths) == 1
-        ), f"There must be exactly one nml file in the zip-file, buf found {len(nml_paths)}."
-        with nml_paths[0].open(mode="rb") as f:
-            annotation, nml = cls._load_from_nml(nml_paths[0].stem, f)
+    @staticmethod
+    def _parse_volumes(
+        nml: wknml.Nml, possible_paths: Optional[List[ZipPath]]
+    ) -> List[_VolumeLayer]:
         volume_layers = []
+        layers_with_not_found_location = []
+        layers_without_location = []
         for volume in nml.volumes:
-            fitting_volume_paths = [i for i in paths if str(i.at) == volume.location]
-            assert (
-                len(fitting_volume_paths) == 1
-            ), f"Couldn't find the file {volume.location} for the volume annotation {volume.name or volume.id}"
-            with fitting_volume_paths[0].open(mode="rb") as f:
-                with ZipFile(f) as volume_layer_zipfile:
-                    if len(volume_layer_zipfile.filelist) == 0:
-                        volume_path = None
-                    else:
-                        volume_path = fitting_volume_paths[0]
+            if possible_paths is None:  # when parsing NML files
+                volume_path = None
+                if volume.location is not None:
+                    # This should only happen if a zipped nml
+                    # is unpacked and loaded directly.
+                    layers_with_not_found_location.append(volume)
+                    volume_path = None
+            elif volume.location is None:
+                volume_path = None
+                layers_without_location.append(volume)
+            else:
+                fitting_volume_paths = [
+                    i for i in possible_paths if str(i.at) == volume.location
+                ]
+                if len(fitting_volume_paths) == 1:
+                    with fitting_volume_paths[0].open(mode="rb") as f:
+                        with ZipFile(f) as volume_layer_zipfile:
+                            if len(volume_layer_zipfile.filelist) == 0:
+                                volume_path = None
+                            else:
+                                volume_path = fitting_volume_paths[0]
+                else:
+                    layers_with_not_found_location.append(volume)
+                    volume_path = None
+
             segments = {}
             if volume.segments is not None:
                 for segment in volume.segments:
@@ -435,8 +437,32 @@ def _load_from_zip(cls, content: Union[str, PathLike, BinaryIO]) -> "Annotation"
         assert len(set(i.id for i in volume_layers)) == len(
             volume_layers
         ), "Some volume layers have the same id, this is not allowed."
-        annotation._volume_layers = volume_layers
-        return annotation
+        if len(layers_without_location) > 0:
+            warnings.warn(
+                "Omitting the volume layer annotation data for layers "
+                + f"{[v.name or v.id for v in layers_without_location]}, "
+                + "as their location is not referenced in the NML."
+            )
+        if len(layers_with_not_found_location) > 0:
+            warnings.warn(
+                "Omitting the volume layer annotation data for layers "
+                + f"{[v.name or v.id for v in layers_without_location]}, "
+                + f"as their referenced files {[v.location for v in layers_without_location]} "
+                + "cannot be found."
+            )
+        return volume_layers
+
+    @classmethod
+    def _load_from_zip(cls, content: Union[str, PathLike, BinaryIO]) -> "Annotation":
+        zipfile = ZipFile(content)
+        paths = [ZipPath(zipfile, i.filename) for i in zipfile.filelist]
+        nml_paths = [i for i in paths if i.suffix == ".nml"]
+        assert len(nml_paths) > 0, "Couldn't find an nml file in the supplied zip-file."
+        assert (
+            len(nml_paths) == 1
+        ), f"There must be exactly one nml file in the zip-file, buf found {len(nml_paths)}."
+        with nml_paths[0].open(mode="rb") as f:
+            return cls._load_from_nml(nml_paths[0].stem, f, possible_volume_paths=paths)
 
     def save(self, path: Union[str, PathLike]) -> None:
         """
@@ -716,7 +742,7 @@ def export_volume_layer_to_dataset(
 
         assert (
             volume_zip_path is not None
-        ), "The selected volume layer is empty and cannot be exported."
+        ), "The selected volume layer data is not available and cannot be exported."
 
         with volume_zip_path.open(mode="rb") as f:
             data_zip = ZipFile(f)
@@ -739,8 +765,11 @@ def export_volume_layer_to_dataset(
 
         if largest_segment_id is None:
             max_value = max(
-                view.read().max()
-                for view in best_mag_view.get_views_on_disk(read_only=True)
+                (
+                    view.read().max()
+                    for view in best_mag_view.get_views_on_disk(read_only=True)
+                ),
+                default=0,
             )
             layer.largest_segment_id = int(max_value)
         else:

webknossos/webknossos/annotation/__init__.py

@@ -10,5 +10,7 @@ def infer_bounding_box_existing_files(mag_view: MagView) -> BoundingBox:
     The returned bounding box is measured in Mag(1) voxels."""
 
     return reduce(
-        lambda acc, bbox: acc.extended_by(bbox), mag_view.get_bounding_boxes_on_disk()
+        lambda acc, bbox: acc.extended_by(bbox),
+        mag_view.get_bounding_boxes_on_disk(),
+        BoundingBox.empty(),
     )