diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..ed88099 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_images/category.png b/docs/_images/category.png new file mode 100644 index 0000000..4fed3d0 Binary files /dev/null and b/docs/_images/category.png differ diff --git a/docs/_images/configuration.png b/docs/_images/configuration.png new file mode 100644 index 0000000..b8f92aa Binary files /dev/null and b/docs/_images/configuration.png differ diff --git a/docs/_images/new-connection.png b/docs/_images/new-connection.png new file mode 100644 index 0000000..e478bb5 Binary files /dev/null and b/docs/_images/new-connection.png differ diff --git a/docs/_images/optimize-alignment.png b/docs/_images/optimize-alignment.png new file mode 100644 index 0000000..218ed06 Binary files /dev/null and b/docs/_images/optimize-alignment.png differ diff --git a/docs/_images/segmentation-stitcher-annotation.png b/docs/_images/segmentation-stitcher-annotation.png new file mode 100644 index 0000000..1016a52 Binary files /dev/null and b/docs/_images/segmentation-stitcher-annotation.png differ diff --git a/docs/_images/segmentation-stitcher-display.png b/docs/_images/segmentation-stitcher-display.png new file mode 100644 index 0000000..99c3731 Binary files /dev/null and b/docs/_images/segmentation-stitcher-display.png differ diff --git a/docs/_images/segmentation-stitcher-interface.png b/docs/_images/segmentation-stitcher-interface.png new file mode 100644 index 0000000..e034d72 Binary files /dev/null and b/docs/_images/segmentation-stitcher-interface.png differ diff --git a/docs/_images/segmentation-stitcher-workflow.png b/docs/_images/segmentation-stitcher-workflow.png new file mode 100644 index 0000000..2d0402b Binary files /dev/null and b/docs/_images/segmentation-stitcher-workflow.png differ diff --git a/docs/_images/transformation.png b/docs/_images/transformation.png new file mode 100644 index 0000000..d4121f5 Binary files /dev/null and b/docs/_images/transformation.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..efd7d65 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,38 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'mapclientplugins.scaffoldcreator' +copyright = '2022, University of Auckland' +author = 'University of Auckland' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'nature' + +# -- Options for EPUB output +epub_show_urls = 'footnote' + +# If true, enable figure numbering +numfig = True \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..69b0ba7 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,203 @@ +Segmentation Stitcher +===================== + +Overview +-------- + +The **Segmentation Stitcher** tool provides an interface for stitching anatomical segmentations, +enabling users to seamlessly combine multiple segmentation files into one file. + +This document describes how to set up and use the **Segmentation Stitcher** user interface in the Mapping Tools. +The actual work is done by the underlying *segmentationstitcher* library which can run it without a user interface, +together with the *Zinc library* which handles model representation and computation. + +Workflow Connections +-------------------- + +The workflow connections for **Segmentation Stitcher** are shown in :numref:`fig-segmentation-stitcher-workflow`: + +.. _fig-segmentation-stitcher-workflow: + +.. figure:: _images/segmentation-stitcher-workflow.png + :width: 50% + :align: center + + **Segmentation Stitcher** workflow connections. + +The tool has 1 input on the left: + +1. A list of *Zinc library* compatible EX file, use **Multiple_File_Chooser** to read from files. + +It produces 1 outputs, which may be piped to other workflow steps: + +1. A connected Zinc EX file. + +Whether you use the output in a further workflow step or not, on completion of the workflow step the connected segmentation output is written to a file in the workflow +folder under the same name as the step with extension ``.exf``. + +Background +---------- +The Segmentation Stitcher utilizes a network organization system that governs how different anatomical structures can connect. +Understanding these connectivity rules is essential for effective segmentation stitching. + +There are five groups for connecting, each with distinct characteristics. +Upon initial execution, each mesh element is automatically assigned to a category based on predefined rules. +Users can later modify these assignments in the `Annotations`_ tab. + +The Network groups 1 and 2, defined during the initial `Configure`_, serve as the core categories of the connection system. +These groups typically separating main structures like nerve trunks and plexuses from smaller structures like fascicles, +ensuring organized and controlled stitching within their respective domains. +During configuration, users define keywords for each group, and networks matching these keywords are automatically assigned to the appropriate network group. + +Graphics that not assigned to Network group 1 or 2, and has an anatomical term are automatically placed in the General group by the first run. +This category often serves as a default for segments that do not require specialized handling. +For example, graphics such as contours, which are not meant to connect with any other elements, can be included in the output but will not be stitched to anything else. + +The Exclude category is reserved for graphics that should remain isolated from the connection process. +These graphics are hidden from visualization to maintain workspace clarity and will not be exported in the final output. +Initially, any network that does not matching the criteria for Network groups 1 or 2, and lacks an anatomical term is automatically placed in this category. + +The Independent networks occupy a unique position in the system. These networks, which begin as an empty set by default, can only form connections with themselves. +This isolation makes them ideal for handling distinct anatomical structures that shouldn't intermingle with other networks. + +Instructions +------------ +Configure +^^^^^^^^^ +The configuration dialog for **Segmentation Stitcher** allows you to set up network grouping: + +.. _fig-configuration: + +.. figure:: _images/configuration.png + :width: 50% + :align: center + + **Segmentation Stitcher** step configuration dialog. + +In the configuration dialog, you can: + +1. Set a unique identifier for this step + +2. Define keywords for network group 1 (typically for main structures like vagus, nerve, trunk, branch, plexus) + +3. Define keywords for network group 2 (typically for fascicles) + +Segmented networks annotated with any of these comma-separated keywords are initially assigned to the respective network group, allowing them to be stitched together. +It's only run the very first time, and never used again. + +Main Interface +^^^^^^^^^^^^^^ + +The main interface of the **Segmentation Stitcher** shows loaded segments in the Control Panel and an interactive 3D view of the segmentations: + +.. _fig-segmentation-stitcher-interface: + +.. figure:: _images/segmentation-stitcher-interface.png + :align: center + + **Segmentation Stitcher** interface showing vagus. + +On the left side, the Control Panel provides access to all necessary tools and settings. +The *Segments* box lists all the loaded segments, each with a checkbox indicating whether it is currently be displayed. + +While the other side is a **Sceneviewer Widget**, which provides an interactive 3D visualization of the segmentations being worked on. +Detailed documentation for this widgets can be found at +`Sceneviewer Widget Documentation `_. + +The *View All* button conservatively resets the view to see the whole model (esp. if coordinate field is changed), +while *Std. Views* cycles between standard orthographic views of the graphics. + +Connections +^^^^^^^^^^^ +The Connections panel allows users to create new connections between segments and manage existing ones. +Effective stitching begins with precise positioning. +Before creating a new connection, users can select a segment from the Segments list and hold the 'A' key to perform various transformations: +using the left mouse button to rotate, using the middle mouse button to translate, and using the right mouse button to scale. + +Below the segments list, there are two editbox for rotation and translation provide precise control over segment positioning. +When a segment is moved using the mouse, these values update automatically. + +.. _fig-transformation: + +.. figure:: _images/transformation.png + :width: 50% + :align: center + + Segment transformation. + +After positioning the two segments that need to be connected close to each other, click the "New..." button to create a new connection. +In the dialog that appears (as shown in :numref:`fig-new-connection`), select the two segments to connect. +Note that Segment 2 will be adjusted to align with Segment 1 when using "Optimize Alignment…". +If the same segment file is selected for both Segment 1 and Segment 2, no connection will be created, as a segment file cannot connect to itself. +Once the correct segments are selected, click OK to create the connection. + +.. _fig-new-connection: + +.. figure:: _images/new-connection.png + :width: 50% + :align: center + + New connection dialog. + +To manage connections: + - Select connections in the list to work with them + - Click "Delete..." to remove selected connections + - Use "Optimize Alignment..." to automatically align the second segment in each selected connection with the first segment + +.. _fig-optimize-alignment: + +.. figure:: _images/optimize-alignment.png + :width: 50% + :align: center + + Optimize Alignment. + +The tool's "Optimize Alignment" feature utilizes advanced non-linear optimization to precisely align connected segments. +It analyzes the mean direction and radius of connection endpoints to determine the optimal transformation. +During this process, the transformation of the second segment in the selected connection is adjusted to align its network endpoints with those of the first segment. +This process can be repeated multiple times for further refinement. + +Alignment accuracy can be enhanced using Align Weights in the `Annotations`_ tab. These weights act as influence factors in the optimization process, +allowing users to prioritize certain connections over others. +For example, when connecting major nerve trunks, users can assign higher weights to these primary connections while giving lower weights to smaller branch connections, ensuring a structured and precise alignment. + +Display +^^^^^^^ +The settings in the *Display* tab can be changed at any time to turn on or off graphics as for several other mapping tools. +Users can toggle various visual elements, from basic axes and marker points to specific network group displays. +Each network group can be customized with radius and transparency settings, while end points can be visualized with different combinations of lines, +tips, and radius indicators. A global radius scale control allows fine-tuning of the overall visualization thickness. +This tab only control the visibility of specific graphic classes and do not affect any other aspects of the segmentation process. + +.. _fig-segmentation-stitcher-display: + +.. figure:: _images/segmentation-stitcher-display.png + :align: center + + **Segmentation Stitcher** display tab. + +Annotations +^^^^^^^^^^^ +The *Annotation* tab, shown in :numref:`fig-segmentation-stitcher-annotation`, +allows users to assign a Category and set the Align Weight, both of which influence the optimization process. + +.. _fig-segmentation-stitcher-annotation: + +.. figure:: _images/segmentation-stitcher-annotation.png + :align: center + + **Segmentation Stitcher** annotations tab. + +By the first run, all the segmentation elements are automatically assigned to one of five predefined categories, +as shown in :numref:`fig-category`. These categories help organize the connection system and ensure proper segmentation stitching. +Users can manually change the assigned category by selecting the segmentation element from the Name dropdown and modifying the Category field. + +.. _fig-category: + +.. figure:: _images/category.png + :align: center + + Category Selection in the Annotations Tab. + +At the Align Weight field, you can enter an Align Weight value to specific segmentation elements. +Or check "Set by category" to applies the entered weight to all elements in the selected category. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..3d64bb3 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd