Add examples for Dataset functions in documentation. (#901)

* Add example for Dataset functions in documentation.

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

Co-authored-by: Tom Herold <[email protected]>

* Add examples to mkdocs.yml and resolve issues.

* Add tests to ensure correct behaviour of examples.

* Refine markdown of image stack to dataset example.

* Format test_example.py with black version 23.1.0.

---------

Co-authored-by: Tom Herold <[email protected]>

docs/mkdocs.yml

@@ -80,6 +80,8 @@ nav:
         - webknossos-py/examples/dataset_usage.md
         - webknossos-py/examples/upload_tiff_stack.md
         - webknossos-py/examples/upload_image_data.md
+        - webknossos-py/examples/create_dataset_from_images.md
+        - webknossos-py/examples/image_stack_to_dataset.md
         - webknossos-py/examples/download_image_data.md
         - webknossos-py/examples/download_tiff_stack.md
         - webknossos-py/examples/remote_datasets.md

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

@@ -0,0 +1,9 @@
+# Create Dataset from Images
+
+This example shows how to [convert a folder of images into a new dataset](../../api/webknossos/dataset/dataset.md#Dataset.from_images).
+
+```python
+--8<--
+webknossos/examples/create_dataset_from_images.py
+--8<--
+```

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

@@ -0,0 +1,16 @@
+# Image Stack to Dataset
+
+This example shows how to [create a new WEBKNOSSOS dataset from a stack of images](../../api/webknossos/dataset/dataset.md#Dataset.from_images), e.g. Tiff, JPEG, etc files.
+
+There are a few assumptions we made about the images used for this example:
+
+- all images have the same size
+- they have the same dtype (e.g. `uint8` or `float`)
+- they are greyscale images from microscopy / MRI / CT scan, therefore the category is `color`
+- masks and segmentations are not included yet
+
+```python
+--8<--
+webknossos/examples/image_stack_to_dataset.py
+--8<--
+```

docs/src/webknossos-py/installation.md

@@ -10,3 +10,9 @@ You can install it from [pypi](https://pypi.org/project/webknossos/), e.g. via p
 ```bash
 pip install webknossos
 ```
+
+For extended file format conversation support it is necessary to install the optional dependencies:
+
+```bash
+pip install "webknossos[all]"
+```

webknossos/examples/create_dataset_from_images.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from webknossos import Dataset
+from webknossos.dataset import COLOR_CATEGORY
+
+INPUT_DIR = Path(__file__).parent.parent / "testdata" / "tiff"
+OUTPUT_DIR = Path("testoutput/my_tiff_dataset")
+
+
+def main() -> None:
+    """Convert a folder of image files to a WEBKNOSSOS dataset."""
+    dataset = Dataset.from_images(
+        input_path=INPUT_DIR,
+        output_path=OUTPUT_DIR,
+        voxel_size=(11, 11, 11),
+        layer_category=COLOR_CATEGORY,
+        compress=True,
+    )
+
+    print(f"Saved {dataset.name} at {dataset.path}.")
+
+    # dataset.upload()
+
+
+if __name__ == "__main__":
+    main()

webknossos/examples/image_stack_to_dataset.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from webknossos import Dataset
+from webknossos.dataset import COLOR_CATEGORY
+
+INPUT_FILES = (
+    Path(__file__).parent.parent / "testdata" / "tiff" / "test.0000.tiff",
+    Path(__file__).parent.parent / "testdata" / "tiff" / "test.0001.tiff",
+)
+OUTPUT_FOLDER = Path("testoutput/tiff_dataset")
+
+
+def main() -> None:
+    """Convert a list of images into a WEBKNOSSOS dataset and directly add them as a new layer."""
+    dataset = Dataset(
+        dataset_path=OUTPUT_FOLDER,
+        voxel_size=(11, 11, 11),
+        name="My_new_dataset",
+        exist_ok=False,
+    )
+    dataset.add_layer_from_images(
+        images=INPUT_FILES,
+        layer_name="test",
+        category=COLOR_CATEGORY,
+    )
+
+    # dataset.upload()
+
+
+if __name__ == "__main__":
+    main()

webknossos/tests/test_examples.py

@@ -72,6 +72,39 @@ def test_dataset_usage() -> None:
     assert data_in_mag2_subset.shape == (3, 256, 256, 16)
 
 
+def test_create_dataset_from_images() -> None:
+    with tmp_cwd():
+        import examples.create_dataset_from_images as example
+
+        (dataset,) = exec_main_and_get_vars(example, "dataset")
+        assert dataset.voxel_size == (11, 11, 11)
+        assert len(dataset.layers) == 1
+        assert dataset.get_layer("tiff").get_finest_mag().read().shape == (
+            1,
+            265,
+            265,
+            257,
+        )
+        assert dataset.get_layer("tiff").dtype_per_channel == "uint8"
+
+
+def test_image_stack_to_dataset() -> None:
+    with tmp_cwd():
+        import examples.image_stack_to_dataset as example
+        from webknossos.dataset import COLOR_CATEGORY
+
+        (dataset,) = exec_main_and_get_vars(example, "dataset")
+        assert len(dataset.layers) == 1
+        assert dataset.get_layer("test").category == COLOR_CATEGORY
+        assert dataset.get_layer("test").get_finest_mag().read().shape == (
+            1,
+            265,
+            265,
+            2,
+        )
+        assert dataset.get_layer("test").dtype_per_channel == "uint8"
+
+
 @pytest.mark.block_network(allowed_hosts=[".*"])
 @pytest.mark.vcr(ignore_hosts=["webknossos.org", "data-humerus.webknossos.org"])
 def test_apply_merger_mode() -> None: