Repository: scalableminds/webknossos-libs

Issue:
Add "download dataset" sample
I think a simple sample for the docs that shows how to download a bounding box of a dataset would be very helpful.


Discussion:

Resolving patch:
diff --git a/webknossos/examples/download_image_data.py b/webknossos/examples/download_image_data.py
new file mode 100644
--- /dev/null
+++ b/webknossos/examples/download_image_data.py
@@ -0,0 +1,31 @@
+import webknossos as wk
+
+
+def main() -> None:
+    # Set the correct dataset name and organization where the dataset is saved on webknossos
+    name = "l4dense_motta_et_al_demo"
+    organization = "scalable_minds"
+
+    # Choose layers and mags to download
+    layers = ["color"]
+    mags = [wk.Mag(1)]
+
+    # Set the bounding box which should be downloaded
+    bbox = wk.BoundingBox([50, 50, 50], [50, 50, 50])
+
+    # Download the datset
+    ds = wk.Dataset.download(
+        dataset_name=name,
+        organization_name=organization,
+        bbox=bbox,
+        layers=layers,
+        mags=mags,
+        webknossos_url="https://webknossos.org",
+    )
+
+    # Check that the layer was downloaded
+    print(f"Layers: {ds.layers}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/webknossos/webknossos/dataset/dataset.py b/webknossos/webknossos/dataset/dataset.py
--- a/webknossos/webknossos/dataset/dataset.py
+++ b/webknossos/webknossos/dataset/dataset.py
@@ -221,6 +221,19 @@ def download(
         exist_ok: bool = False,
         webknossos_url: Optional[str] = None,
     ) -> "Dataset":
+        """Downloads a dataset and returns the Dataset instance.
+
+        The `dataset_name` and `organization_name` specify which dataset to download.
+        The `bbox`, `layers`, and `mags` parameters specify which parts of the dataset to download.
+        If nothing is specified the whole image, all layers, and all mags are downloaded respectively.
+
+        The `path` and `exist_ok` parameter specify where to save the downloaded dataset and whether to overwrite
+        if the `path` exists.
+
+        The `webknossos_url` specifies in which webknossos instance to search for the dataset. By default the
+        configured url from `webknossos_context` is used, using https://webknossos.org as a fallback.
+        """
+
         from webknossos.client._download_dataset import download_dataset
         from webknossos.client.context import _get_context, webknossos_context
 


Test patch:
diff --git a/webknossos/tests/test_examples.py b/webknossos/tests/test_examples.py
--- a/webknossos/tests/test_examples.py
+++ b/webknossos/tests/test_examples.py
@@ -101,6 +101,17 @@ def test_upload_image_data() -> None:
         assert url.startswith("http://localhost:9000/datasets/Organization_X/cell_")
 
 
+@pytest.mark.block_network(allowed_hosts=[".*"])
+@pytest.mark.vcr(ignore_hosts=["webknossos.org", "data-humerus.webknossos.org"])
+def test_download_image_data() -> None:
+    with tmp_cwd():
+        import examples.download_image_data as example
+
+        (ds,) = exec_main_and_get_vars(example, "ds")
+
+        assert list(ds.layers.keys()) == ["color"]
+
+
 class _DummyNearestNeighborClassifier:
     """Faster replacement for a sklearn classifier,
     also removing the need for sklearn as a dependency."""