Annotation streaming: annotation.get_remote_annotation_dataset() (#794)

* update generated client

* add annotation.get_annotation_dataset()

* add changelog entry

* minor wording change in docs example

* added docstring

* minor fix

* update some snapshots

* Update webknossos/webknossos/annotation/annotation.py

* extend doc string with details about mappings

* remove unused code

* use the new get_annotation_dataset method in the learned_segmenter example

* fix learned_segmenter example

* rename to get_remote_annotation_dataset

* minor fix

* fix sizes for test

Co-authored-by: Philipp Otto <[email protected]>
Co-authored-by: Philipp Otto <[email protected]>

Author: jstriebel

docs/src/webknossos-py/examples/zarr_and_dask.md

@@ -1,6 +1,6 @@
 # Zarr and Dask interoperability
 
-This example shows how to access the underlying [Zarr](https://zarr.dev) array of a [remote datasets](../../api/webknossos/dataset/dataset.md#RemoteDataset). Using the Zarr array allows to use other libraries, such as [Dask](https://www.dask.org/) for parallel processing.
+This example shows how to access the underlying [Zarr](https://zarr.dev) array of a [remote dataset](../../api/webknossos/dataset/dataset.md#RemoteDataset). Accessing the Zarr array allows to use other libraries, such as [Dask](https://www.dask.org/) for parallel processing.
 
 ```python
 --8<--

webknossos/Changelog.md

@@ -15,6 +15,8 @@ For upgrade instructions, please check the respective *Breaking Changes* section
 ### Breaking Changes
 
 ### Added
+- Added `annotation.get_remote_annotation_dataset()` to get a streamed annotation dataset, which also reflects fallback layers or applied mappings. [#794](https://github.com/scalableminds/webknossos-libs/pull/794)
+- Added direct access to an underlying Zarr array with the `MagView.get_zarr_array()` method. [#792](https://github.com/scalableminds/webknossos-libs/pull/792)
 
 ### Changed
 

webknossos/examples/learned_segmenter.py

@@ -19,19 +19,19 @@ def main() -> None:
         "https://webknossos.org/annotations/616457c2010000870032ced4"
     )
 
-    # Step 1: Download the training data annotation from webKnossos to our local computer
+    # Step 1: Read the training data from the annotation and the dataset's color
+    # layer (the data will be streamed from webKnossos to our local computer)
     training_data_bbox = annotation.user_bounding_boxes[0]  # type: ignore[index]
     time_str = strftime("%Y-%m-%d_%H-%M-%S", gmtime())
     new_dataset_name = annotation.dataset_name + f"_segmented_{time_str}"
-    dataset = annotation.get_remote_base_dataset(
-        webknossos_url="https://webknossos.org"
-    )
+    with wk.webknossos_context("https://webknossos.org"):
+        dataset = annotation.get_remote_annotation_dataset()
 
-    with annotation.temporary_volume_layer_copy() as volume_annotation_layer:
-        mag = volume_annotation_layer.get_finest_mag().mag
-        volume_annotation_data = volume_annotation_layer.mags[mag].read(
-            absolute_bounding_box=training_data_bbox
-        )
+    volume_mag_view = dataset.layers["Volume"].get_finest_mag()
+    mag = volume_mag_view.mag
+    volume_annotation_data = volume_mag_view.read(
+        absolute_bounding_box=training_data_bbox
+    )
 
     color_mag_view = dataset.layers["color"].mags[mag]
 
@@ -62,7 +62,7 @@ def main() -> None:
     assert segmentation.max() < 256
     segmentation = segmentation.astype("uint8")
 
-    # Step 5: Bundle everying a webKnossos layer and upload to wK for viewing and further work
+    # Step 5: Bundle everything as a webKnossos layer and upload to wK for viewing and further work
     with TemporaryDirectory() as tempdir:
         new_dataset = wk.Dataset(
             tempdir, voxel_size=dataset.voxel_size, name=new_dataset_name
@@ -79,7 +79,7 @@ def main() -> None:
         segmentation_layer.downsample(sampling_mode="constant_z")
 
         remote_ds = new_dataset.upload(
-            layers_to_link=[dataset.layers["color"]]
+            layers_to_link=[annotation.get_remote_base_dataset().layers["color"]]
             if "PYTEST_CURRENT_TEST" not in os.environ
             else None
         )

webknossos/local_wk_setup.sh

@@ -1,7 +1,7 @@
 function export_vars {
     export WK_TOKEN=1b88db86331a38c21a0b235794b9e459856490d70408bcffb767f64ade0f83d2bdb4c4e181b9a9a30cdece7cb7c65208cc43b6c1bb5987f5ece00d348b1a905502a266f8fc64f0371cd6559393d72e031d0c2d0cabad58cccf957bb258bc86f05b5dc3d4fff3d5e3d9c0389a6027d861a21e78e3222fb6c5b7944520ef21761e
     export WK_URL=http://localhost:9000
-    export DOCKER_TAG=master__18939
+    export DOCKER_TAG=master__19264
 }
 
 function ensure_local_test_wk {

webknossos/tests/cassettes/test_annotation/test_annotation_from_url.yaml

@@ -15,10 +15,10 @@ interactions:
     method: GET
     uri: http://localhost:9000/api/annotations/570ba0092a7c0e980056fe9b/info
   response:
-    content: '{"modified":0,"state":"Active","id":"570ba0092a7c0e980056fe9b","name":"","description":"","viewConfiguration":null,"typ":"Explorational","task":null,"stats":{"edgeCount":28965,"nodeCount":28967,"treeCount":2,"branchPointCount":0},"restrictions":{"allowAccess":true,"allowUpdate":true,"allowFinish":true,"allowDownload":true},"formattedHash":"56fe9b","annotationLayers":[{"tracingId":"ae417175-f7bb-4a34-8187-d9c3b50143ae","typ":"Skeleton","name":"Skeleton"}],"dataSetName":"2012-06-28_Cortex","organization":"Organization_X","dataStore":{"name":"localhost","url":"http://localhost:9000","isForeign":false,"isScratch":false,"isConnector":false,"allowsUpload":true},"tracingStore":{"name":"localhost","url":"http://localhost:9000"},"visibility":"Internal","settings":{"allowedModes":["orthogonal","oblique","flight"],"branchPointsAllowed":true,"somaClickingAllowed":true,"volumeInterpolationAllowed":true,"mergerMode":false,"resolutionRestrictions":{}},"tracingTime":null,"teams":[],"tags":["2012-06-28_Cortex","skeleton"],"user":{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isAnonymous":false,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}]},"owner":{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isAnonymous":false,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}]},"meshes":[],"contributors":[],"othersMayEdit":false}'
+    content: '{"modified":0,"state":"Active","id":"570ba0092a7c0e980056fe9b","name":"","description":"","viewConfiguration":null,"typ":"Explorational","task":null,"stats":{"edgeCount":28965,"nodeCount":28967,"treeCount":2,"branchPointCount":0},"restrictions":{"allowAccess":true,"allowUpdate":true,"allowFinish":true,"allowDownload":true},"formattedHash":"56fe9b","annotationLayers":[{"tracingId":"ae417175-f7bb-4a34-8187-d9c3b50143ae","typ":"Skeleton","name":"Skeleton"}],"dataSetName":"2012-06-28_Cortex","organization":"Organization_X","dataStore":{"name":"localhost","url":"http://localhost:9000","isScratch":false,"isConnector":false,"allowsUpload":true},"tracingStore":{"name":"localhost","url":"http://localhost:9000"},"visibility":"Internal","settings":{"allowedModes":["orthogonal","oblique","flight"],"branchPointsAllowed":true,"somaClickingAllowed":true,"volumeInterpolationAllowed":true,"mergerMode":false,"resolutionRestrictions":{}},"tracingTime":null,"teams":[],"tags":["2012-06-28_Cortex","skeleton"],"user":{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isAnonymous":false,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}]},"owner":{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isAnonymous":false,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}]},"meshes":[],"contributors":[],"othersMayEdit":false}'
     headers:
       content-length:
-      - '1876'
+      - '1858'
       content-type:
       - application/json
       date: Mon, 01 Jan 2000 00:00:00 GMT

webknossos/tests/cassettes/test_examples/test_learned_segmenter.yaml

@@ -15,12 +15,12 @@ interactions:
     method: GET
     uri: http://localhost:9000/api/buildinfo
   response:
-    content: '{"webknossos":{"name":"webknossos","ciTag":"","commitHash":"da26494924d437fcf5f88adf76c696c47d99d27d","ciBuild":"18939","scalaVersion":"2.12.15","version":"18939","sbtVersion":"1.6.2","datastoreApiVersion":"2.0","commitDate":"Fri
-      Aug 12 08:54:15 2022 +0000"},"webknossos-wrap":{"builtAtMillis":"1640035836569","name":"webknossos-wrap","commitHash":"8b842648702f469a3ffd90dc8a68c4310e64b351","scalaVersion":"2.12.7","version":"1.1.15","sbtVersion":"1.4.1","builtAtString":"2021-12-20
-      21:30:36.569"},"schemaVersion":85,"token":"xxxsecrettokenxxx","localDataStoreEnabled":true,"localTracingStoreEnabled":true}'
+    content: '{"webknossos":{"name":"webknossos","ciTag":"","commitHash":"495fc485de1062d338ad89f2e3203b6c07c917cd","ciBuild":"19264","scalaVersion":"2.12.15","version":"19264","sbtVersion":"1.6.2","datastoreApiVersion":"2.0","commitDate":"Mon
+      Sep 5 15:28:01 2022 +0200"},"webknossos-wrap":{"builtAtMillis":"1640035836569","name":"webknossos-wrap","commitHash":"8b842648702f469a3ffd90dc8a68c4310e64b351","scalaVersion":"2.12.7","version":"1.1.15","sbtVersion":"1.4.1","builtAtString":"2021-12-20
+      21:30:36.569"},"schemaVersion":87,"token":"xxxsecrettokenxxx","localDataStoreEnabled":true,"localTracingStoreEnabled":true}'
     headers:
       content-length:
-      - '611'
+      - '610'
       content-type:
       - application/json
       date: Mon, 01 Jan 2000 00:00:00 GMT

webknossos/tests/cassettes/test_generated_client/test_annotation_info.yaml

@@ -15,7 +15,7 @@ interactions:
     method: GET
     uri: http://localhost:9000/api/user
   response:
-    content: '{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isActive":true,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}],"experiences":{"abc":5},"lastActivity":1660299029040,"isAnonymous":false,"isEditable":true,"organization":"Organization_X","novelUserExperienceInfos":{},"selectedTheme":"auto","created":1460379469000,"lastTaskTypeId":null,"isSuperUser":true}'
+    content: '{"id":"570b9f4d2a7c0e4d008da6ef","email":"[email protected]","firstName":"user_A","lastName":"BoyA","isAdmin":true,"isDatasetManager":true,"isActive":true,"teams":[{"id":"570b9f4b2a7c0e3b008da6ec","name":"team_X1","isTeamManager":true},{"id":"59882b370d889b84020efd3f","name":"team_X3","isTeamManager":false},{"id":"59882b370d889b84020efd6f","name":"team_X4","isTeamManager":true}],"experiences":{"abc":5},"lastActivity":1662737231110,"isAnonymous":false,"isEditable":true,"organization":"Organization_X","novelUserExperienceInfos":{},"selectedTheme":"auto","created":1460379469000,"lastTaskTypeId":null,"isSuperUser":true}'
     headers:
       content-length:
       - '630'

webknossos/tests/cassettes/test_generated_client/test_build_info.yaml

@@ -15,19 +15,19 @@ interactions:
     method: GET
     uri: https://webknossos.org/api/datasets/scalable_minds/l4dense_motta_et_al_demo
   response:
-    content: '{"name":"l4dense_motta_et_al_demo","dataSource":{"id":{"name":"l4dense_motta_et_al_demo","team":"scalable_minds"},"dataLayers":[{"name":"color","category":"color","boundingBox":{"topLeft":[128,128,128],"width":5445,"height":8380,"depth":3285},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint8","adminViewConfiguration":{"intensityRange":[80,180]}},{"name":"predictions","category":"color","boundingBox":{"topLeft":[0,0,0],"width":5632,"height":8704,"depth":3584},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint24","adminViewConfiguration":{"isDisabled":true}},{"name":"segmentation","category":"segmentation","boundingBox":{"topLeft":[128,128,128],"width":5445,"height":8380,"depth":3285},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint32","largestSegmentId":2504697,"adminViewConfiguration":{}}],"scale":[11.24,11.24,28]},"dataStore":{"name":"webknossos.org","url":"https://data-humerus.webknossos.org","isForeign":false,"isScratch":false,"isConnector":false,"allowsUpload":true},"owningOrganization":"scalable_minds","allowedTeams":[],"isActive":true,"isPublic":true,"description":"Segmentation
+    content: '{"name":"l4dense_motta_et_al_demo","dataSource":{"id":{"name":"l4dense_motta_et_al_demo","team":"scalable_minds"},"dataLayers":[{"name":"color","category":"color","boundingBox":{"topLeft":[128,128,128],"width":5445,"height":8380,"depth":3285},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint8","adminViewConfiguration":{"intensityRange":[80,180]}},{"name":"predictions","category":"color","boundingBox":{"topLeft":[0,0,0],"width":5632,"height":8704,"depth":3584},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint24","adminViewConfiguration":{"isDisabled":true}},{"name":"segmentation","category":"segmentation","boundingBox":{"topLeft":[128,128,128],"width":5445,"height":8380,"depth":3285},"resolutions":[[1,1,1],[2,2,1],[4,4,2],[8,8,4],[16,16,8],[32,32,16],[64,64,32],[128,128,64],[256,256,128],[512,512,256],[1024,1024,512]],"elementClass":"uint32","largestSegmentId":2504697,"adminViewConfiguration":{}}],"scale":[11.24,11.24,28]},"dataStore":{"name":"webknossos.org","url":"https://data-humerus.webknossos.org","isScratch":false,"isConnector":false,"allowsUpload":true},"owningOrganization":"scalable_minds","allowedTeams":[],"isActive":true,"isPublic":true,"description":"Segmentation
       created with [Voxelytics](https://scalableminds.com/voxelytics) by [scalable
       minds](https://scalableminds.com).\n\n \n\nRaw SBEM data and segmentation ground
       truth by Max Planck Institute for Brain Research. As published in *Dense connectomic
       reconstruction in layer 4 of the somatosensory cortex* by A Motta, M Berning,
       KM Boergens, B Staffler, M Beining, S Loomba, P Hennig, H Wissler, M Helmstaedter
       in *Science* on 24 October 2019. [10.1126/science.aay3134](https://science.sciencemag.org/content/early/2019/10/23/science.aay3134)\n","displayName":"L4
-      Mouse Cortex Demo","created":1597232436055,"isEditable":false,"lastUsedByUser":1010101010101,"logoUrl":"https://static.webknossos.org/logos/scalableminds.svg","sortingKey":1597232436055,"details":null,"isUnreported":false,"isForeign":false,"jobsEnabled":true,"tags":["demo","l4dense"],"publication":null}'
+      Mouse Cortex Demo","created":1597232436055,"isEditable":false,"lastUsedByUser":1010101010101,"logoUrl":"https://static.webknossos.org/logos/scalableminds.svg","sortingKey":1597232436055,"details":null,"isUnreported":false,"jobsEnabled":true,"tags":["demo","l4dense"],"publication":null}'
     headers:
       connection:
       - keep-alive
       content-length:
-      - '2274'
+      - '2238'
       content-type:
       - application/json
       date: Mon, 01 Jan 2000 00:00:00 GMT