Organ Scaffold Maps

Availability of scaffold maps datasets on the SPARC Portal makes it possible for users to not only explore the maps, it also allows export and interoperability of the scaffold maps with other software systems for applications such as schematically locate data points in the scaffold coordinate system or providing a scaffold for computational purposes in other modeling software or environment.

Organ scaffold maps

Beyond the two-dimensional flatmaps, we also look to register SPARC data to three-dimensional organ scaffolds to provide maps in a common coordinate framework enabling disparate data to be integrated in order to improve our understanding of the collective SPARC knowledge.

The process for mapping SPARC data to the organ scaffolds is described in some detail in The SPARC DRC: Building a resource for the autonomic nervous system community, so here we focus on enabling the reuse of the organ scaffolds themselves, as well as specific instances of the scaffolds in a given scaffold map.

Documentation for all the mapping tools is available here. The following are quick links to the specific tools used in the SPARC default organ scaffolds workflow:

• Scaffold Creator
• Argon Viewer
• Argon Scene Exporter

Generic organ scaffolds

Quarterly releases of the generic organ scaffolds are published to the SPARC Portal. In the same manner as the source flatmap anatomical diagrams, the source of these generic scaffolds are archived in PMR and then published to the SPARC Portal in a manner aimed at supporting reuse.

When a generic scaffold is archived in PMR a provenance record is stored in the archive that explicitly states the version of the software used. The provenance record can be used to recreate the environment that the archived data was created with. With the software environment and inputs to the workflow we can reproduce the data published to the SPARC Portal locally.

Generic organ scaffolds are typically exported in reusable STL and VTK formats. These formats are generated with the SPARC default organ scaffolds workflow and they can be found and downloaded directly from the derivative folder of generic organ scaffold datasets. If the dataset lacks STL or VTK files, the missing files can be generated by following the steps given below.

We will use the Generic mouse colon scaffold dataset to demonstrate how to load the published scaffold in the Scaffold Mapping Tool and how to generate exports of the scaffold in STL and VTK formats for reuse by other software.

Scaffold reuse

Scaffold Creator is a plugin to the MAP Client workflow tool that can be used to generate organ scaffolds. Scaffold Creator uses a small number of parameters to configure the generation of a specific instance of an organ scaffold. Common features between organs and/or species are abstracted into reusable templates and then Scaffold Maker, the library behind the plugin, uses the given configuration to generate the desired finite element model from the available templates. The authoritative source for any of the generic organ scaffolds consists of the configuration used to generate it and the specific version of Scaffold Maker used to generate it - this is the information that is archived in PMR, along with the generated finite element model in the internal Scaffold Maker format.

We also archive a visualization configuration of the organ scaffold in PMR which, when combined with the organ scaffold configuration and provenance information defines all the required information to re-create a graphical rendition of the organ scaffold as available on the SPARC Portal.

To make use of an existing organ scaffold first install the Scaffold Mapping Tools following the instructions on installation from the SPARC Portal. The installation will include MAP Client, Scaffold Creator, and Scaffold Maker. Download the SPARC generic scaffold workflow from GitHub- here we refer to that as the workflow directory. Now we can launch the MAP Client application and open the SPARC generic scaffold workflow.

To reuse an organ scaffold from an existing dataset, download the dataset from the SPARC Portal and take the following steps:

• Copy the OrganScaffold-settings.json file from the target dataset to the workflow directory.
  • In some cases the settings file has a different name, for example; mouse_lungs_mesh_settings.json. In this case copy the mouse_lungs_mesh_settings.json to OrganScaffold-settings.json in the workflow directory.
• Copy the ViewCreation-backup-document.json from the target dataset to the workflow directory.
• Configure the output of the webGL and thumbnail Argon Scene Exporter steps to a suitable directory on the local disk. When creating a dataset for the SPARC Portal this is a location under the derivative directory for the dataset.
• Save the workflow.
• Execute the workflow.

When running the SPARC generic scaffold workflow:

There are two user interactive steps: Scaffold Creator (with identifier OrganScaffold), and Argon Viewer (with identifier ViewCreation) and there are also four non-interactive steps for exporting the view with the identifiers STL, VTK, WebGLExport and ThumbnailExport.

The first interface encountered when executing the workflow is the Scaffold Creator interface where modifications to the scaffold are made. In the Scaffold Creator interface we can change species, variant, finite element density, etc. When first executing the workflow, the interface will be configured as per the scaffold from the target dataset. The Done button is used to confirm the organ scaffold configuration and move to the next step of the workflow.

The second interface encountered is the Argon Viewer interface where we can create or modify an existing view of the scaffold. The Argon Viewer documentation explains in detail the functionality of the interface, which will be configured as per the scaffold visualization from the target dataset on first execution. The Done button on this interface finishes the workflow and returns to the initial view of the workflow.

Scaffold publication to the SPARC Portal

As described above, Scaffold Creator is used to generate specific instances of the generic organ scaffolds. To aid the reuse, when publishing the generic organ scaffolds the datasets are enriched with additional data for visualization of the scaffold on the SPARC Portal and common export formats for the underlying finite element models.

In the SPARC generic scaffold workflow we finish the workflow exporting the view. The exported files can be configured to export to the derivative directory of a SPARC dataset. It is usual to export these files to a directory named scaffold in the derivative directory.

There are four types of export formats; STL, VTK, webGL, and thumbnail. The STL and VTK exports the scaffold in STL and VTK format respectively for reuse of the scaffold with other software (see Scaffold Mapping Tools: Reusing Scaffolds). The webGL export is a format that ScaffoldVuer (see below) can consume and render the exported data in the browser. The thumbnail export is a JPEG image which is used to give visual feedback on the exported data without actually loading the data in ScaffoldVuer.

When the correct annotation is stored in the dataset and uploaded to the SPARC Portal the SPARC Portal is able to interpret the exported data and create an interactive view of the organ scaffold in the browser.

Use Scaffold Mapping Tool to export scaffold to VTK file

Step 1: Identify provenance of scaffold.
First, look under Files of the SPARC dataset and in the primary folder, download provenance.json (Figure 1).

In provenance.json, look for the version of MAPClient used for generating this scaffold as shown in Figure 2. Download the same version of Mapping Tools from here.

Start the correct version of Mapping Tools.

Step 2: Create a workflow
You can create a new workflow anywhere but here we will create one on the Desktop.

Using Windows Explorer, or similar, create a new directory on the Desktop and name it Scaffold Export. Create a new folder exports in Scaffold Export.

From the File menu in Mapping Tools select the New > Workflow (CTRL-SHIFT-N) to start a new workflow. Navigate to the Desktop and select the Scaffold Export directory created earlier.

Next, you need to prepare the workflow for execution. Set up the workflow as shown in Figure 3 by dragging the steps highlighted in the red boxes from the step list box onto the workflow panel. Connect the steps as demonstrated in Figure 3.

The next step is to configure the Argon_Scene_Exporter steps. Click on the red wheel icon on the first Argon_Scene_Exporter step. Rename the Identifier to STL. Enter mouseColon under Prefix. For Output directory, select the exports folder in the Scaffold Export folder that you created on the Desktop. Finally, select stl from the drop-down list of Export type. Click OK and make sure that the red wheel icon is now green (Figure 4).

For the second Argon_Scene_Exporter step, we can use it to generate the VTK export of the scaffold. Here, change the Identifier field to VTK. Enter mouseColon as the Prefix, select the same exports folder for Output directory and choose vtk under the Export type drop-down list (Figure 5).

Save the workflow.

At this point the workflow has been created and is ready for executing. Execute the workflow by pressing the Execute button in the lower right corner of the application main window or Ctrl+X.

Step 3: Select the scaffold

Using the Scaffold Creator interface, set the Scaffold type to 3D Colon 1. Set the Parameter set to Mouse 1.

Use the View All and Std. Views button to center the generated scaffold in the viewing panel (Figure 6).

Click the Done button to finalize the settings and move onto the next step in the workflow.

Step 4: Visualize the scaffold
In this step, we create surface visualization for the scaffold.

First, use the Model Sources editor to load the scaffold (Scaffold_Creator.exf) in the root region / by clicking on the green plus icon (Figure 7). The icon switches to a gray minus sign when the scaffold has been successfully loaded in the region.

Note that if you are only interested in generating the VTK export of the scaffold, you can skip the following steps and proceed to click Done.

However, to generate a STL export, we will need to use Add View to create a view window (Figure 8). Steps on how to add views are detailed in Step 1 here.

Next, use the Scene Editor to add surface elements of the scaffold as shown in Figure 9. Addition of surface elements in the Argon Viewer is necessary for the generation of triangulated surfaces defined by the unit normal and vertices in the STL format. More details on how to customize the visualization can be found in Step 4 described here.

Click Done.

Once the workflow has finished executing (returned to its initial state), navigate to the derivative folder (Desktop\Scaffold Export\exports) to view the output files. For the example above, the output files are as follows:

1. mouseColon_root.vtk is the VTK export of the linear mesh representation of the scaffold.
2. mouseColon_zinc_graphics.stl is the STL export of the triangulated representation of the scaffold defined by unit normals and vertices.

These export files can be read into modeling or CAD softwares such as ParaView. Figures 10 and 11 show the mouse colon in VTK and STL formats loaded in ParaView, respectively.

Apart from using scaffolds from SPARC datasets, the Mapping Tools also provides the ability to customize an organ scaffold. This can be done either through adjustment of the parameters in Scaffold Creator or fitting of a generic scaffold to a sample data cloud using the Geometry Fitter. The resultant scaffold can then be visualized using Argon Viewer in the Mapping tool followed by export to VTK or STL formats for further computational or research applications.

Use Python SPARC Client Library to export scaffold to VTK file

Besides using the MAPClient Mapping Tools, if the dataset contains the scaffold_setting.json file, you can also use the Python Sparc Client Library to easily export scaffold maps to the VTK format using straightforward Python code.

Here, we will use the Scaffold map - Mapping of human gastric enteroendocrine cells to demonstrate how to generate exports of the scaffold in VTK formats by using sparc.client.

To determine the existence of the scaffold_setting.json file, look under Files of the SPARC dataset and check the primary folder (Figure 12). It's unnecessary to download the file.

Step 1: Install pre-requisites
Before we start, make sure you have installed the Python SPARC Client library (sparc.client) and the CMLibs Zinc library (cmlibs.zinc). If you haven't installed them yet, use the following commands:

pip install sparc.client
pip install cmlibs.zinc

Step 2: Load modules
To work with the SPARC Client library and CMLibs Zinc, we need to import the required modules. Additionally, you can load modules from other locations by providing a dictionary with configurations and the path to the module. We will also import the 'os' library, which we will use later in the examples to verify the existence of the output file.

# Import the required modules
import os
from sparc.client.zinchelper import ZincHelper
zinc = ZincHelper()

Step 3: Export scaffold asVTK file
To export a scaffold data to VTK format, use the zinc.getscaffold_vtk() function, which automatically handles the data retrieval. Simply provide the dataset_id and specify the output_file where the scaffold data will be saved in VTK format. After the function call, you can verify the existence of the output file using os.path.exists(output_file).

# Given dataset ID and desired output file name
dataset_id = 292
output_file = "scaffold.vtk"
# Use the get_scaffold_vtk() function to export scaffold data to vtk format
zinc.get_scaffold_vtk(dataset_id, output_file)
# Verify the existence of the output file
if os.path.exists(output_file):
	print(f"Scaffold data successfully exported to VTK: {output_file}")
else:
	print("Export to VTK failed. Please check your inputs and try again.")

Once the scaffold data is successfully exported to the VTK format, you can use the output file for visualization and/or modeling purposes. Figures 13 shows the human stomach in VTK formats loaded in ParaView.