Download example (#612)

* add download example to docs

* expand doc-string

* add page to index

* add bbox as param

* use mags list

* Update docs/src/webknossos-py/examples/download_image_data.md

Co-authored-by: Jonathan Striebel <[email protected]>

* Update docs/src/webknossos-py/examples/download_image_data.md

Co-authored-by: Jonathan Striebel <[email protected]>

* Update docs/src/webknossos-py/index.md

Co-authored-by: Jonathan Striebel <[email protected]>

* Update webknossos/webknossos/dataset/dataset.py

Co-authored-by: Jonathan Striebel <[email protected]>

* add test to test_examples

* Update docs/src/webknossos-py/examples/download_image_data.md

Co-authored-by: Jonathan Striebel <[email protected]>

* Update test_examples.py

* re-add allowed hosts for test_upload_image_data

* use proper format

* use webknossos.org, bc local wk instance doesn't have dataset

* reformat

Co-authored-by: Jonathan Striebel <[email protected]>
Co-authored-by: Norman Rzepka <[email protected]>

Author: 3 people

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

@@ -0,0 +1,9 @@
+# Download Image Data
+
+Downloads part of a [webknossos dataset](https://webknossos.org/datasets/scalable_minds/l4dense_motta_et_al_demo/view) from [webknossos.org](https://webknossos.org) using [`webknossos_context`](../../api/webknossos/client/context.md#webknossos_context).
+
+```python
+--8<--
+webknossos/examples/download_image_data.py
+--8<--
+```

docs/src/webknossos-py/index.md

@@ -7,6 +7,7 @@ To get started, check out the [installation instructions](installation.md) and t
 * [Intro to Dataset Usage](examples/dataset_usage.md)
 * [How to Upload a Dataset](examples/upload_image_data.md)<br/>
   ![Cell Dataset uploaded to webKnossos](examples/upload_image_data_dataset.jpg){: style="max-width: calc(100%/2 - 1em);"}
+* [How to Download a Dataset](examples/download_image_data.md)
 * [Using a Volume Annotation to Train a Custom Segmenter](examples/learned_segmenter.md)<br/>
   ![Volume Annotation used as Training Data](examples/learned_segmenter_annotation.png){: style="max-width: calc(100%/4 - 1em);"}
   ![Result of the Segmenter on the Skin Dataset](examples/learned_segmenter_result.png){: style="max-width: calc(100%/4 - 1em);"}

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()

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."""

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