Scaffold Mapping Tools: Reusing Scaffolds

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.

Here, we will use the Generic mouse colon scaffold dataset to demonstrate how to load the published scaffold on the Scaffold Mapping Tool and how to generate exports of the scaffold in stl and vtk formats for reuse by other software.

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 as vtk 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.