Scaffold Mapping Tools: Inserting Subject-Specific Vagus (SSV) Scaffolds In Whole-Body Scaffold

This tutorial shows how to use the Scaffold Mapping Tools to insert subject-specific vagus (SSV) scaffolds into a fitted whole body scaffold using the Organ Inserter plugin.

Any number of SSV scaffolds can be inserted into a fitted whole-body scaffold. For demonstration purposes, this tutorial uses vagus scaffolds derived from two subjects (f009, DOI: 10.26275/un0a-zzdl) and f019, DOI: 10.26275/8ekx-tqxe), from the Feinstein collection (DOI: 10.26275/2vva-qmjw). These scaffolds will be inserted into a fitted whole-body scaffold (DOI: 10.26275/bbvg-gj86) using template vagus scaffolds created from a virtual subject M000 (DOI: 10.26275/k7hi-uttf) derived from existing anatomical knowledge in BodyParts3D.

Each SSV scaffold captures the unique geometry and morphology of an individual vagus nerve. Mapping these scaffolds into the whole body scaffold transforms the trunk of each subject-specific vagus nerve to a common reference trunk defined by the template vagus scaffold. This allows vagal anatomy from different subjects to be visualized along the same trunk geometry, even when their length and morphology vary across subjects.

Input	Purpose	DOI for file retrieval
Whole body scaffold	Provides the anatomical framework into which SSV scaffolds are inserted	10.26275/bbvg-gj86
SSV scaffolds	Provides the SSV scaffolds to be inserted	10.26275/tjzi-muqm
Template vagus scaffolds	Provides the common reference path used for transforming the SSV scaffolds	10.26275/tjzi-muqm

By the end of this tutorial, you will learn how to:

configure a workflow to insert SSV scaffolds into a whole body scaffold;
retrieve template scaffolds, organ scaffolds and whole body scaffold data from the SPARC Portal;
visualize subject-specific vagus scaffolds and anatomical landmarks after insertion in the whole body scaffold;
visualize branch origins and orientations;
isolate and compare specific vagal groups across subjects.

Step 1: Create and execute the workflow

Launch MAP Client Mapping Tools from the Start Menu under MAP-Client-mapping-tools vX.Y.Z (X, Y, and Z will be the actual version numbers).

Set up a new workflow named SSV-in-body-tracing on your Desktop by creating a new folder on the Desktop named SSV-in-body-tracing.

Go back to the MAP Client Mapping Tools, go to File → New Workflow (Ctrl+Shift+N). Select the SSV-in-body-tracing directory you just created.

To set up the organ inserter workflow, add the following steps to the workflow area and connect them as shown in Figure 1:

Three Retrieve Portal Data steps
One Organ Inserter step
One Muxer step
One Argon Viewer step
One Argon Scene Exporter step

First Retrieve Portal Data step

Configure the first Retrieve Portal Data by setting its identifier to whole body scaffold as shown in Figure 2.

Second Retrieve Portal Data step

Configure the second Retrieve Portal Data by setting SSV scaffolds as the identifier, as shown in Figure 3.

Third Retrieve Portal Data step

Configure the third Retrieve Portal Data by setting template scaffolds as the identifier, as shown in Figure 4.

Organ Inserter configuration

Click the configuration wheel icon in the Organ Inserter step. The dialog is pre-populated with keywords corresponding to different insertion modes. Keywords are case-insensitive and can be modified by the user.

Why are template scaffolds required?
The SSV filenames retrieved via the Second Retrieve Portal Data step match the common trunk keywords shown in Figure 5 and are therefore processed in the common trunk insertion mode. This mode requires template scaffolds to provide a common reference path for transforming the subject-specific scaffolds.

Figure 5. Organ Inserter pre-set configuration dialog.

Muxer step

Configure the Muxer step as shown in Figure 6.

The connection of ports to the Muxer step allows both the whole body scaffold and output files from the Organ Inserter step to be passed into Argon Viewer for visualization.

Argon Scene Exporter step

Configure the Argon Scene Exporter step by changing Export type to image, the prefix to in-body-SSV and selecting an output directory for saving the image. Set Width and Height to 2048 in order to export a high-resolution image as shown in Figure 7.

Once the workflow is complete, save it (Ctrl+S) and click Execute.

Step 2: Retrieve data from the SPARC Portal

An interface for the Retrieve Portal Data step will open.

Selecting template scaffolds

As indicated by the identifier template scaffold on the top left corner, we will retrieve the template scaffolds for both left and right sides. Enter https://doi.org/10.26275/tjzi-muqm in the Search term field and click Search. The search results will appear in the Search results panel.

To filter the results to scaffold files, enter scaffold-exf in the Filter field and select Mimetype. Click the Filename header to sort the results alphabetically. From the filtered list, locate M000-left_vagus_scaffold.exf and M000-right_vagus_scaffold.exf.

Hold Ctrl while selecting both files, then click Download. This will download the selected scaffold files for use as the template scaffolds.

Once the download is complete and the correct files are listed in the Provided files panel as shown in Figure 8, click Done to proceed.

Figure 8. Retrieving and selecting template scaffolds.

Selecting SSV scaffolds

Next, we will retrieve the SSV scaffolds on both left and right sides. Enter https://doi.org/10.26275/tjzi-muqm in the Search term field and click Search. The search results will show up in the Search results panel.

To filter the results to scaffold files, enter scaffold-exf in the Filter field and select Mimetype. Click the Filename header to sort the results alphabetically.

In this example, we are inserting vagus scaffolds from two subjects (f009 and f019). From the list, locate the following four files:
f009-left_vagus_scaffold.exf
f009-right_vagus_scaffold.exf
f019-left_vagus_scaffold.exf
f019-right_vagus_scaffold.exf

Hold Ctrl while selecting all four files, then click Download. Once the selected files are loaded in the Provided files panel as shown in Figure 9, click Done to proceed.

Figure 9. Retrieving and selecting SSV scaffolds.

Selecting whole body scaffold

Next, we will retrieve a whole-body scaffold fitted to data derived from BodyParts3D. Enter https://doi.org/10.26275/bbvg-gj86 in the Search term field and click Search. The search results will show up in the Search results panel.

To filter the results to scaffold files, enter whole in the Filter field and select Filename. From the list, locate Geometry_Fitter_Wholebody.exf, select the file, then click Download. Once the selected file is loaded in the Provided files panel as shown in Figure 10, click Done to proceed.

Figure 10. Retrieving and downloading the fitted whole body scaffold.

Once all three Retrieve Portal Data steps have been completed, the workflow is now configured to insert the subject-specific scaffolds into the whole-body scaffold. The Organ Inserter does not have a user interface, and the process may take some time to complete. Note that processing time will also increase with the number of scaffolds inserted into the whole-body scaffold. Once processing is complete, the Argon Viewer interface will open automatically.

In the next step, we will use Argon Viewer to visualize the inserted scaffolds and progressively add annotations and branch-level visualizations.

Step 3: Visualize inserted vagus scaffolds

The visualizations in this tutorial progress from a general overview of the inserted vagus scaffolds to increasingly detailed representations of branch organization:

Gross anatomy - visualize overall position and morphology of the inserted vagus scaffolds.
Level markers - visualize anatomical level landmarks along the inserted vagus.
Branch origins and orientations - visualize where branches originate and their initial branching direction
Specific branch groups - isolate anatomically annotated branch groups
Subject highlighting - facilitate comparison between subjects in population studies

Set up view, regions and model sources

Click Add View to add a Layout1 view panel.

Open the Region Editor. Right-click and select Add child region to create three child regions. Double-click each newly created region to rename them whole body, left vagus and right vagus.

Next, right-click left vagus and select Add child region to create two child regions. Rename the newly created regions f009 and f019. Repeat the same steps for right vagus. The resulting region hierarchy should look like Figure 11.

Figure 11. Region hierarchy in Region Editor.

Next, click the Model Sources tab in the top panel. Assign each scaffold file to its corresponding child region by selecting the appropriate region and then clicking the green plus icon, as shown in Figure 12.

Figure 12. Assigning scaffold files in Model Sources.

Visualize the whole body scaffold

We are now ready to generate graphics for the whole body scaffold. To clearly visualize the inserted vagus scaffolds later, first create a translucent tissue material. Open Material Editor from the top panel, double-click tissue and rename it to tissue_translucent. Set Alpha to 0.5 as shown in Figure 13.

Figure 13. Creating a translucent tissue material.

Next, open the Scene Editor and select /whole body from the Region drop-down menu. Add surfaces with the following settings:
Subgroup: skin epidermis outer surface
Boundary mode: boundary
Face: any = face
Material: tissue_translucent

At this stage, the Layout1 panel will still be empty. To display the graphics you have just created, open Sceneviewer Editor and click View All. Adjust the graphics to a comfortable viewing position using left-click to rotate, middle-click to pan and right-click to zoom. From this point onward, any newly added graphic objects should appear in the view panel when they are configured correctly.

Because a translucent material is being used, adjust the scene settings in Sceneviewer Editor by setting Transparency mode to slow. You should be able to derive a visualization as shown in Figure 14.

Figure 14. Creating a visualization of the whole-body scaffold.

Visualize gross vagus anatomy

Next, we can add graphics to visualize the transformed vagus scaffolds from each subject. Select /left vagus/f009 under Region, then add surfaces with the following settings:
Subgroup: epineurium
Material: orange

Repeat these steps for /right vagus/f009, /left vagus/f019 and /right vagus/f019, selecting the appropriate region each time. Use the orange material to represent f009 and the blue material to represent f019 as shown in Figure 15.

Figure 15. Comparison of gross anatomy of inserted vagus scaffolds from f009 (orange) and f019 (blue).

Visualize vagus level markers

Next, we can visualize the vagus level markers along the trunk. To do so, we first need to create a marker coordinates field.

Click Field Editor in the top panel and select /left vagus/f009 from the Region drop-down menu. Add an Embedded field with the following settings as shown in Figure 16:
Source Field 1: coordinates
Embedded Location: marker_location
Name: marker coordinates

Figure 16. Creating a marker coordinates field.

Next, open Scene Editor and select /left vagus/f009 from the Region drop-down menu. Add node points with the following settings:
Subgroup: marker
Coordinates: marker coordinates
Glyph: line
Base size: 50*50*50
Label field: marker_name
Glyph offset: -0.5, 0, 0
Label text offset: 1.25, 0, 0

Repeat the same steps in Field Editor and Scene Editor for /right vagus/f009 to visualize the right vagus level markers. For the right vagus, set Label text offset to -5, 0, 0 to prevent the labels from obscuring the vagus scaffolds as shown in Figure 17.

Figure 17. Visualizing level markers on both left and right sides.

When the vagus level markers are not needed, you can hide them by unchecking points nodes marker in the corresponding region. The markers can be re-enabled by checking the box again when required.

Here, we have plotted the vagal trunks and branches for f009 (in orange) and f019 (in blue). This type of visualization is helpful for a quick overview of the differences in the overall distribution of branches across different subjects. However, it can be quite tricky to identify the branch origin points or orientations, as some branches have only been traced for a short distance.

Visualize vagal branch organization

A more effective visualization is to plot the centroid of the vagal trunk together with normalized vectors indicating the initial direction of each vagal branch. By visualizing normalized branch directions relative to this centroid, branch origins can be compared more easily, even when individual branches differ in length or trajectory.

Before proceeding, we need to turn off visualizations created for the vagus scaffolds. In Scene Editor, uncheck the box next to all graphic objects in /left vagus/f009, /right vagus/f009, /left vagus/f019 and /right vagus/f019. At this stage, only the surface of the whole body scaffold should remain visible in the Layout1 window.

Next, we will set up the vagus trunk centroids. This only needs to be done once for each side using any subject, as the trunks from all different subjects should be transformed to follow the same path as the template vagus scaffold.

Go to Field Editor and use the following settings to set up a field called left vagus nerve centroid in the Region for /left vagus/f009 as shown in Figure 18:
Add …: And
Source Field 1: left vagus nerve
Source Field 2: vagus centroid
Name: left vagus nerve centroid

Figure 18. Creating the left vagus nerve centroid field.

Repeat the same steps for right vagus/f009 to create a right vagus nerve centroid using the corresponding right fields.

As we will be visualizing the origins and initial directions of vagal branches, we first need to create a group called vagus nerve branches.

For each of the vagus sub-regions (/left vagus/f009, /right vagus/f009, /left vagus/f019, /right vagus/f019), create the following field as shown in Figure 19:

Add …: Not
Source Field: left vagus nerve / right vagus nerve
Name: left vagus nerve branches / right vagus nerve branches

Figure 19. Creating a group for the left vagus nerve branches.

Next, as shown in Figure 20, we add a Derivative field for the same regions with the following settings:
Coordinate Field: coordinates
xi index: 1
Name: dx_dxi1

As the derivative of the coordinates field with respect to the first element coordinates (xi1) provides a vector tangent to the branch, the vector dx_dxi1 represents the local direction of the branch.

Figure 20. Creating a derivative field representing the branch direction.

Then, we add a Normalise field as shown in Figure 21 for each of the vagus regions:
Source Field: dx_dxi1
Name: norm_dx_dxi1

Normalising dx_dxi1 removes its magnitude while retaining its direction. This allows it to be used to orient the glyphs later for visualization.

Figure 21. Creating a derivative field representing normalized vectors with branch direction.

Visualize the vagus trunk centroids

To visualize the left vagus trunk centroid, select /left vagus/f009 from the Region drop-down menu and add lines with the following settings:
Subgroup: left vagus nerve centroid
Shape: circle extrusion
Base size: 4*4

Next, select /right vagus/f009 from the Region drop-down menu and create the corresponding graphics for the right vagus trunk centroid. You should derive a visualization as shown in Figure 22.

Figure 22. Visualizing left and right vagus nerve centroids in the whole body scaffold.

Visualize vagus branch orientations

Next, we will add normalized branches for all the samples, starting with f009-left. Select /left vagus/f009 as the Region and add element points with the following settings:
Subgroup: left vagus nerve branches
Material: orange
Glyph: cylinder
Base size: 15*2*2
Scale field: norm_dx_dxi1

Repeat the same steps for /left vagus/f019, /right vagus/f009 and /right vagus/f019, selecting the appropriate left or right vagus nerve branch subgroup and material. Use orange to represent f009 and blue to represent f019.

The resulting visualization should resemble the screenshot shown in Figure 23.

Figure 23. Visualizing branch origins and orientations for left and right vagus with f009 in orange and f019 in blue.

Visualize specific branch groups

While we can now better visualize where branches originate and the direction in which they extend, this visualization still does not provide information about the type of branches. Since all branch data is annotated, we can use their annotation groups to visualize specific groups of vagal branches.

In this example, we will demonstrate how to visualize the superior laryngeal nerve and the cardiovascular branch of cervical vagus nerve from subject f009.

Start by clearing the graphic objects that we made for the vagus nerve branches in the previous steps.

Go to Scene Editor, select /left vagus/f009 from the Region drop-down menu:
Add element points with the following settings to visualize the left superior laryngeal nerve:
Subgroup: left superior laryngeal nerve
Material: magenta
Glyph: cylinder
Base size: 15*2*2
Scale field: norm_dx_dxi1

Next, add another element points graphic to visualize the left cardiovascular branch of the cervical vagus nerve:
Subgroup: left cardiovascular branch of cervical vagus nerve
Material: green
Glyph: cylinder
Base size: 15*2*2
Scale field: norm_dx_dxi1

Repeat the same steps for the right vagus nerve, using corresponding right-sided annotation groups.

We can now visually compare how different groups of branches are distributed along the nerve trunk, as well as how their distributions differ between the left vagus and right vagus, as shown in Figure 24.

Figure 24. Visualizing superior laryngeal nerve in magenta and the cardiovascular branch of the cervical vagus nerve in green for subject f009.

Visualize branch groups across multiple subjects

The same approach can be used to visualize specific branch groups across multiple subjects. For example, Figure 25 shows the distribution of the superior laryngeal nerve (magenta) and cardiovascular branch of cervical vagus nerve (green) for both f009 and f019 samples.

Figure 25. Visualizing superior laryngeal nerve in magenta and the cardiovascular branch of the cervical vagus nerve in green for subjects f009 and f019.

By plotting specific vagal branch groups across multiple subject-specific vagus scaffolds, we now have a means of exploring the spatial distribution of specific vagal branch groups along the nerve trunk and their spatial relationships with target organs.

Target organ scaffolds can also be visualized in the same view if the corresponding organ scaffold file is provided to the Organ inserter step during the configuration of the workflow. This enables us to explore the spatial relationships between the vagal branches and their target organs, thereby providing a useful framework for investigating patterns of innervation across subjects.

Highlight a specific subject

When multiple samples are plotted together, it can be useful to highlight the branches from a specific subject to facilitate the examination of inter-subject differences.

In this example, we will highlight the branches from subject f009. In Scene Editor, select /left vagus/f009 from Region. Add element points with the following settings:

Subgroup: left superior laryngeal nerve / left cardiovascular branch of cervical vagus nerve
Material: gold
Glyph: sphere
Base size: 6*6*6
Scale field: norm_dx_dxi1
Glyph offset: 2, 0.0, 0.0

Repeat the same steps for the corresponding branches on the right vagus, and you should now see that branches from f009 are highlighted with a gold sphere, as shown in Figure 26.

Figure 26. Highlighting the superior laryngeal nerve and the cardiovascular branch of the cervical vagus nerve with gold spheres for subject f009.

Exporting the generated visualization

Once you have successfully generated the visualization required for your publication or presentation, click Done. This will end the workflow, and the visualization displayed in the Layout view will automatically be exported to the directory specified during the Argon Scene Exporter configuration step.

Summary

In this tutorial, we inserted subject-specific vagus scaffolds into a whole body scaffold and progressively visualized their anatomy, level markers, branch origins, orientations, and specific branch groups. These visualizations provide a foundation for further quantitative analysis of vagal branching patterns and their spatial relationships with target organs.