Add example for scaling a skeleton. (#1147)

* Add example and test it.

* Add example to docs and update changelog.

Author: markbader

docs/mkdocs.yml

@@ -107,6 +107,7 @@ nav:
               - webknossos-py/examples/download_segments.md
               - webknossos-py/examples/load_annotation_from_file.md
               - webknossos-py/examples/skeleton_path_length.md
+              - webknossos-py/examples/upsample_skeleton.md
           - Administration Examples:
               - webknossos-py/examples/user_times.md
               - webknossos-py/examples/annotation_project_administration.md

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

@@ -0,0 +1,9 @@
+# Upsample a Skeleton
+
+This example shows how to adapt the `voxel_size` of a skeleton annotation and move the nodes positions according to the scale factor. 
+
+```python
+--8<--
+webknossos/examples/upsample_skeleton.py
+--8<--
+```

webknossos/Changelog.md

@@ -15,6 +15,7 @@ For upgrade instructions, please check the respective _Breaking Changes_ section
 ### Breaking Changes
 
 ### Added
+- Added example for scaling a skeleton. [#1147](https://github.com/scalableminds/webknossos-libs/pull/1147)
 
 ### Changed
 - Added options `--layer-name` and `--mag` for compress command of the CLI. [#1141](https://github.com/scalableminds/webknossos-libs/pull/1141)

webknossos/examples/upsample_skeleton.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import webknossos as wk
+
+INPUT_PATH = Path(__file__).parent.parent / "testdata" / "nmls" / "test_a.nml"
+OUTPUT_PATH = Path(__file__).parent.parent / "testoutput" / "nmls" / "test_a_scaled.nml"
+OUTPUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+FACTOR = wk.Vec3Int(4, 4, 1)
+
+
+def main() -> None:
+    """
+    Scales a skeleton by a given factor. The factor is applied to the voxel size and the node positions.
+
+    This can be usefull when the skeletons are created in a downsampled version and need to be scaled back to the finest mag.
+    """
+    skeleton = wk.Skeleton.load(INPUT_PATH)
+
+    skeleton.voxel_size = (
+        FACTOR[0] * skeleton.voxel_size[0],
+        FACTOR[1] * skeleton.voxel_size[1],
+        FACTOR[2] * skeleton.voxel_size[2],
+    )
+    for tree in skeleton.flattened_trees():
+        for node in tree.nodes:
+            old_pos = node.position
+            node.position = wk.Vec3Int(
+                old_pos[0] * FACTOR[0], old_pos[1] * FACTOR[1], old_pos[2] * FACTOR[2]
+            )
+
+    skeleton.save(OUTPUT_PATH)
+
+
+if __name__ == "__main__":
+    main()

webknossos/tests/test_examples.py

@@ -364,3 +364,12 @@ def test_load_annotation_file() -> None:
 
     with tmp_cwd():
         load_annotation(annotation_file)
+
+
+def test_upsample_skeleton() -> None:
+    import examples.upsample_skeleton as example
+
+    with tmp_cwd():
+        (skeleton,) = exec_main_and_get_vars(example, "skeleton")
+
+        assert skeleton.voxel_size == (16, 16, 35)