--- updatedAt: 2026-08-21T03:01:29.000Z agentTools: projectIndex: https://docs.sparc.science/llms.txt --- # 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](https://doi.org/10.26275/un0a-zzdl)) and **f019**, DOI: [10.26275/8ekx-tqxe](https://doi.org/10.26275/8ekx-tqxe)), from the Feinstein collection (DOI: [10.26275/2vva-qmjw](https://doi.org/10.26275/2vva-qmjw)). These scaffolds will be inserted into a fitted whole-body scaffold (DOI: [10.26275/bbvg-gj86](https://doi.org/10.26275/bbvg-gj86)) using template vagus scaffolds created from a virtual subject M000 (DOI: [10.26275/k7hi-uttf](https://doi.org/10.26275/k7hi-uttf)) derived from existing anatomical knowledge in [BodyParts3D](https://lifesciencedb.jp/bp3d/). 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](https://doi.org/10.26275/bbvg-gj86) | | SSV scaffolds | Provides the SSV scaffolds to be inserted | [10.26275/tjzi-muqm](https://doi.org/10.26275/tjzi-muqm) | | Template vagus scaffolds | Provides the common reference path used for transforming the SSV scaffolds | [10.26275/tjzi-muqm](https://doi.org/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. For more information on the different organ insertion modes, please refer to the [organ inserter documentation.](https://abi-mapping-tools.readthedocs.io/en/v1.13.0/mapclientplugins.organinserterstep/docs/index.html)

### 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.

### 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.

### Selecting whole body scaffold Next, we will retrieve a whole-body scaffold fitted to data derived from [BodyParts3D](https://lifesciencedb.jp/bp3d/). 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.

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**.

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**.

### 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**.

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**.

### 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**.

### 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`

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**.

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`

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`

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.

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.

#### 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**.

#### 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**.

### 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**.

### 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.

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**.

### 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.