From 60e78be6f76e1ff148547fd77f90f70716c088e0 Mon Sep 17 00:00:00 2001 From: Mark Bader Date: Thu, 4 May 2023 12:03:06 +0200 Subject: [PATCH] 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 * 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 --- docs/mkdocs.yml | 2 ++ .../examples/create_dataset_from_images.md | 9 +++++ .../examples/image_stack_to_dataset.md | 16 +++++++++ docs/src/webknossos-py/installation.md | 6 ++++ .../examples/create_dataset_from_images.py | 26 +++++++++++++++ webknossos/examples/image_stack_to_dataset.py | 31 +++++++++++++++++ webknossos/tests/test_examples.py | 33 +++++++++++++++++++ 7 files changed, 123 insertions(+) create mode 100644 docs/src/webknossos-py/examples/create_dataset_from_images.md create mode 100644 docs/src/webknossos-py/examples/image_stack_to_dataset.md create mode 100644 webknossos/examples/create_dataset_from_images.py create mode 100644 webknossos/examples/image_stack_to_dataset.py diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f3d294c65..3b092ab76 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/docs/src/webknossos-py/examples/create_dataset_from_images.md b/docs/src/webknossos-py/examples/create_dataset_from_images.md new file mode 100644 index 000000000..6dc517ca9 --- /dev/null +++ b/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<-- +``` diff --git a/docs/src/webknossos-py/examples/image_stack_to_dataset.md b/docs/src/webknossos-py/examples/image_stack_to_dataset.md new file mode 100644 index 000000000..e8d42baf2 --- /dev/null +++ b/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<-- +``` diff --git a/docs/src/webknossos-py/installation.md b/docs/src/webknossos-py/installation.md index b1f5d00aa..28056f45d 100644 --- a/docs/src/webknossos-py/installation.md +++ b/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]" +``` diff --git a/webknossos/examples/create_dataset_from_images.py b/webknossos/examples/create_dataset_from_images.py new file mode 100644 index 000000000..f02b2fa25 --- /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 index 000000000..e8ce7cefa --- /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() diff --git a/webknossos/tests/test_examples.py b/webknossos/tests/test_examples.py index 88f148add..53998573f 100644 --- 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: