Repository: scalableminds/webknossos-libs

Issue:
Docs: Add Dataset.from_images examples
## Detailed Description
`Dataset.from_images()` and `ds.add_layer_from_images()` could need more love in the docs: The api docs have [super-long signature descriptions](https://docs.webknossos.org/api/webknossos/dataset/dataset.html#Dataset.from_images) which could be improved, and they should be added in examples as well.


Discussion:

Resolving patch:
diff --git a/webknossos/examples/create_dataset_from_images.py b/webknossos/examples/create_dataset_from_images.py
new file mode 100644
--- /dev/null
+++ b/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()
diff --git a/webknossos/examples/image_stack_to_dataset.py b/webknossos/examples/image_stack_to_dataset.py
new file mode 100644
--- /dev/null
+++ b/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()


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
@@ -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: