Code Monkey home page Code Monkey logo

slicermorph's Introduction

SlicerMorph logo

This is the official repository for SlicerMorph project.

Our project aims to enhance the open-source 3D Slicer platform with cutting-edge tools to assist biologists, anthropologists, and morphologists in analyzing 3D data from research imaging modalities. Our ultimate goal is to foster a collaborative community within the 3D Slicer ecosystem to facilitate seamless data exchange and promote the advancement of open science.

SlicerMorph streamlines digital morphology research by enabling effortless data import, visualization, measurement, annotation, and geometric morphometric analysis on 3D data, including volumetric scans (CTs and MRs) and 3D surface scans, all within the 3D Slicer application. Say goodbye to multiple programs, different file formats, and workflows!

SlicerMorph: An open and extensible platform to retrieve, visualize and analyze 3D morphology is now available in Methods in Ecology and Evolution as an open-access paper. A more detailed version of this manuscript that explains all digital anatomy workflows in Slicer is also available as a preprint on Biorxiv.

Installation

Official method of obtaining SlicerMorph is through extension mechanism of 3D Slicer. To obtain SlicerMorph, please first install the latest stable release (at the moment release 32438, v5.6.1) of 3D Slicer and use the Extensions Manager module to search for and install the SlicerMorph extension. After restarting 3D Slicer, all SlicerMorph modules will be available in the application.

How to cite

If you use SlicerMorph in your research, please cite one or more of these publications.

  • SlicerMorph as a general platform for digital morphology: Rolfe, S., Pieper, S., Porto, A., Diamond, K., Winchester, J., Shan, S., … Maga, A. M. (2021). SlicerMorph: An open and extensible platform to retrieve, visualize and analyze 3D morphology. Methods in Ecology and Evolution, 12:1816–1825. https://doi.org/10.1111/2041-210X.13669 (Open access)

  • For CreateSemiLMPatches, ProjectSemiLMs, PseudoLMGenerator: Rolfe, S., Davis, C., & Maga, A. M. (2021). Comparing semi-landmarking approaches for analyzing three-dimensional cranial morphology. American Journal of Physical Anthropology. 175(1):227-237. https://doi.org/10.1002/ajpa.24214

  • For ALPACA: Porto, A., Rolfe, S. M., & Maga, A. M. (2021). ALPACA: A fast and accurate approach for automated landmarking of three-dimensional biological structures. Methods in Ecology and Evolution. 12:2129–2144. http://doi.org/10.1111/2041-210X.13689 (Open access).

  • For MALPACA (Multi-Template ALPACA): Zhang, C., Porto, A., Rolfe, S., Kocatulum, A., & Maga, A. M. (2022). Automated landmarking via multiple templates. PLOS ONE. 17(12). e0278035. https://doi.org/10.1371/journal.pone.0278035 (Open access).

To cite 3D Slicer as a general purpose biomedical visualization platform, please use: Kikinis, R., Pieper, S. D., & Vosburgh, K. G. (2014). 3D Slicer: A Platform for Subject-Specific Image Analysis, Visualization, and Clinical Support. In Intraoperative Imaging and Image-Guided Therapy (pp. 277–289). Springer, New York, NY. https://doi.org/10.1007/978-1-4614-7657-3_19

Follow this link to obtain a list of publications that cite the main SlicerMorph paper (Rolfe et al., 2021)

Updating SlicerMorph

We continuously add new features and functionalities to SlicerMorph packages. To make sure you are using the latest version, go to Extension Manager, click Manage Extensions tab and then use the "Check for updates" function. Once updates are installed, please restart Slicer for changes to take effect. This feature is only available for stable releases. If you are using the preview version, you have to install a newer preview version to obtain the changes introduced to SlicerMorph.

Module Descriptions

Modules in SlicerMorph are organized in three broad categories:

Input/Output Related Modules

  • ImageStacks: A general purpose tool to import non-DICOM image sequences (png/jpg/bmp/tiff) into Slicer. Provides options to specify voxel size, select image quality (preview, half, full resolution), define an ROI for import, load every Nth slice (skip slice), or reverse stack order (to deal with mirroring of the specimen).
  • SkyscanReconImport: Imports an image stack from Bruker/Skyscan reconstruction software (Nrecon) with correct voxel spacing and orientation as a 3D volume. User just needs to point out to the _Rec.log file that is outputted by the Nrecon software. Also possible to process multiple scans through the batch conversion interface (requires all reconstructions to be under a single directory tree)
  • GEVolImport: Utility to import the .VOL files generated by the GE/tome microCT scanners by parsing the associated reconstruction file (.PCR).
  • MorphoSourceImport: A utility to query and download open-access data from MorphoSource. Requires an API key from MorphoSource.

Geometric Morphometrics Related Modules

  • GPA: Performs Generalized Procrustes Analysis (GPA) with conducts principle component analysis (PCA) of GPA aligned shape coordinates, provides graphical output of GPA results and real-time 3D visualization of PC warps either using the landmarks of mean shape, or using a reference model that is transformed into the mean shape. Visualization of 3D shape deformation of the reference model can be exported as video clips. The input into the module is a folder path containing a number of landmark files stored in Slicer’s fcsv format and optionally a 3D model and accompanying set of landmarks to be used as reference model in 3D visualization of PCA results.
  • CreateSemiLMPatches: Provides triangular patches of semi-landmarks that are constrained by three fixed anatomical landmarks. The input into the module is a 3D model and its accompanying set of fixed landmarks, and users generate and visualize the patches by specifying triplets of fixed landmarks that form a triangle.
  • PseudoLMGenerator: This module uses the 3D model’s geometry to create a dense template of pseudo-landmarks. The landmark placement is constrained to the external surface of the mesh. Points sampled on the template are projected to the mesh surface along the surface normals of the template and then filtered to remove those within the sample spacing distance, improving regularity of sampling. This module can be used to generate a large number of points on a 3D model that can serve as a landmark template for additional samples in the dataset.
  • ALPACA: Automated Landmarking through Pointcloud Alignment and Correspondence Analysis. ALPACA provides fast landmark transfer from a 3D model and its associated landmark set to target 3D model(s) through pointcloud alignment and deformable model registration. Unlike the two semi-landmarking methods above, it does not require presence of fixed landmarks. Optimal set of parameters that gives the best correspondence can be investigated (and outcome can be visualized) in single alignment mode, and then applied to a number of 3D models in batch mode. Invoked first time, ALPACA needs your permission to download necessary libraries. Depending on the internet speed, download may take sometime but it is a one-time event.
  • MarkupEditor: A plugin that enables to select and edit subsets of dense semi-landmarks by drawing an arbitrary closedcurve in the 3D viewer using right-click context menus in 3D viewer. Selected landmarks can be removed from the current node or copied into a new fiducial node. Useful to quickly identify and remove outliers from spherical sampling procedure, or group landmarks into anatomical regions for downstream analyses.

Utility Modules

  • ImportFromURL: A simple utility that will download the data from the provided URL into the current Slicer scene.
  • Animator: A basic keyframe-based animation of 3D volumes. Supports interpolation of regions of interests, rotations, and transfer functions for volume rendering. Output can be either as an image sequence of frames or can be compiled into mp4 format.
  • PlaceSemiLMPatches: A utility to apply the generated connectivity table from the CreateSemiLMPatches module to other 3D models with the same set of anatomical landmarks. A new set of semiLandmarks are sampled directly from the new models using the specified connectivity map. Inputs: The connectivity table from CreateSemiLMPatches, a directory with the list of 3D models that semi-landmarks will be placed on, and associated anatomical landmark files (in fcsv format). Both model and its corresponding fcsv file should have the same filename prefix.
  • ProjectSemiLM: A utility to transfer a template of semilandmarks to new 3D models using Thin Plate Splines (TPS) warp. Requires existence a set of corresponding anatomical landmarks in the template and target models. Inputs: a base 3D model with its anatomical landmark and the semi-landmark template sets used as reference; a directory with the list of 3D models that semi-landmarks will be projected on and their associated anatomical landmark files (in fcsv format). Both model and its corresponding fcsv file should have the same filename prefix.
  • MergeMarkups:. A utility to tag and consolidate fixed and semiLM files into a single merged file.
  • MorphologikaLMConverter: Imports a Morphologika formatted landmark file that may contain multiple subjects and exports a Slicer .FCSV landmark file for each individual to a directory specified by the user.
  • IDAVLMConverter: Imports IDAV landmark editor files with header length specified by the user.
  • ImportSurfaceToSegment: Imports a 3D surface model as a segmentation and prompts the user to edit it using the Segment Editor module.
  • SegmentEndoCranium: Automatically segments the endocranial space in a 3D volume of a vertebrate skull. A detailed description of the module and how it works can be found in this tutorial under the automated method.
  • SlicerMorph Preferences: Users can choose to enable specific customizations that include keyboard shortcuts, and optimized settings for working with large 3D datasets using the Application Settings menu of 3D Slicer. See the documentation link for list of SlicerMorph specific keyboard shortcuts and modified settings.
  • FastModelAlign: Allows users to register a 3D model (source) to a target. Support scaling, rigid and affine transforms.

Dependencies

Automatically installed recommended extensions

The following extension is installed automatically with SlicerMorph. Although it is not directly relied on by the modules, it is necessary for many workflows supoorted by SlicerMorph:

Manually installed dependencies

The following extension is required for using the SegmentEndocranium. Installation is prompted on opening this module.

Manually installed recommended extensions

We recommend that the user manually install the following extensions that provide useful convenience functions:

SlicerMorph Tutorials

We have step-by-step module specific tutorials that is useful for people starting with Slicer and SlicerMorph.

3D Morphometrics and Image Analysis Short Course materials

We actively use SlicerMorph to teach a week-long intense short course on 3D Morphometrics and Image analysis. The feedback of the attendees help us prioritize feature development and refinement. We are grateful for the feedback of over 200 participants. Click for contents from the latest workshop, Spring 2022

Important Websites

Funding Acknowledgement

This project is supported by NSF Advances in Biological Informatics (1759883) and NSF/DBI Cyberinfrastructure (2301405) grants to A. Murat Maga.

NSF logo

License

See License.md

slicermorph's People

Contributors

agporto avatar arpinerap avatar chz31 avatar ezgimercan avatar jamesobutler avatar jcfr avatar jmhuie avatar lassoan avatar luzpaz avatar muratmaga avatar oothomas avatar pieper avatar pranjalsahu avatar slicermorph avatar smrolfe avatar stevenagl12 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

slicermorph's Issues

Continue analysis from where we left

Need a mechanism to save the GPA module analysis, reload and continue from where it is left. While analysis is fast for demo sets, it takes a while for larger samples sizes, and customization (labels, etc) are lost.

Heat maps of shape variance

Add ability to create heat maps of shape variance on models across extremes of PC. Suggestion from SlicerMorph office hours 3/25.

ExportAs is not convenient to use

"Export as..." function in Data module right-click menu is not convenient to use, because:

  • last used file extension is not remembered: most of the time, user wants to use the same file extension; it is hard to always choose the correct one, especially when there are many (for example, when exporting a volume)
  • last used output directory is not remembered: most of the time, user wants to use the same output directory as last time; it is quite inconvenient that you need to re-select the directory every time
  • most of the volume output formats are not working (e.g, 2D formats, such as bmp, jpg, png do not work for 3D volumes), not relevant (Analyze, GIPL, MRC, ... are long dead), or duplicate (tif, tiff, TIF, TIFF, png, PNG, jpg, JPG, jpeg, JPEG)
  • export options cannot be specified (compressed/uncompressed, etc.)
  • need a way to specify if user wants the node to be exported in world coordinate system (parent transform hardened) or in the node's coordinate system (without applying the parent transform)
  • nice to have: export all nodes in a subject hierarchy folder with default (or previously used) export settings into a folder

It would be better to display save dialog:

slicer.app.coreIOManager().openDialog("VolumeFile", slicer.qSlicerFileDialog.Write)

with some improvements, such as showing options similarly to how it is done for for reading data:

slicer.app.coreIOManager().openDialog("VolumeFile", slicer.qSlicerFileDialog.Read)

Last "ExportAs" file path could be saved in an attribute the subject hierarchy item, which would save both the folder and file type. But maybe it would be better to save the last used output folder for the node type or for all the node types.

Register GPA layout as an option in layout manager

After choosing one of the predetermined layouts (e.g., chart, or Red slice), we cannot revert our custom layout without clicking a particular button (e.g., plot gpa). This is not trivial to new users. Either have a button in GPA, or register the custom layout with the layout manager (preferred choice).

ExportAs broken functionality in some installations

ExportAs should allow users to save their volumes, markups and models from Data module using the right-click context menu. It appears this functionality works 100% of the time for Markups, if it is invoked within Markups module. However, functionality within Data module seems hit and miss, with no clear indication of why and what platforms are being affected. We have tested on 4-5 windows 10 machines, and 4 of them are not working as intended in Mac, we have 50-50 split. On linux two computers where tested and it works 100%. (Update not correct anymore. At least one Linux system seems affected).

SlicerMOrph preferences

I already made the changes about removing the control stroke for points, toggle persistence and lock (they are now just p, t, and l).

But for some reason cycleEffect doesn't work I am getting this error:
NameError: name 'cycleEffect' is not defined
Traceback (most recent call last):
File "", line 91, in
NameError: name 'cycleEffect' is not defined

mean shape landmark visualized in viewer #2 should the deformed shape's

When a 3D model and corresponding set of landmarks are selected to visualize 3D deformations, and the toggle mean shape landmarks is enabled, the mean landmarks shown in viewer #2 (deformed model) should the deformed mean shape one. Otherwise they just interfere with the visualization and make it harder.

image

button to export warped 3D models

Let's have a button to export the warped 3D model. This would be the reference sample warped to mean shape if the sliders are at (0,0), and then subsequent applied PC values. This button will sit just above the 'create animation' section.

Please make the default export option to the disk (not into the scene), and in PLY format.

VolumeRendering simplification thoughts

PLaceholder for brainstorming a simpler UI for microCT datasets:

There multiple recurring issues that can be easily addressed.

  1. We need a reasonable transfer function automatically calculated. This might be a simple ramp that covers the 90% of the data range.
  2. Current initial guess does an OK job, when the volume is rendered very first time in the scene. Say if you want to generate a new volume property, it starts from this solid rectangle that it you can’t make it anything into (at least not with a lot of work). Even worse, the only way to recover is to reset the scene.
  3. And of course data size…

I kind of like the idea of having a SlicerMorph specific volume rendering module that is integrated to the Data Module (right click on it and show it in 3D. Right now you have to have the right click on the eye icon). Or modify the data module to have specific 3D rendering colume (in addition to 2D visibility).

Example of useless volume property generated when the user manually chooses "Create New VolumeProperty".
The initial:
image
Subsequent ones:
image

Single table and single plot view is not possible

Currently registered layouts do not contain any maximized plot or table views. Consider adding single table and plot view (for maximing viewing area) and also register our custom slicermorph layour.

potential for Data Loss in ImageStacks during back to back to usage

When people are using ImageStacks to convert multiple stacks to volume back to back, it is easy to overwrite previously imported volume when they are not careful.

  1. Import the sample_CT_stack from SlicerMorph Sample data
  2. Keep the volume node none, which create a new one from the file name
    3 Import the image stack
  3. Clear the files from previous stack and get ready to import the next stack
  4. Note that Volume Node points to the volume generated in the previous import operation, and easy to overwrite.

Solution:

  1. Not give user the flexibility to create a volume, and always import data into a new volume node using filenames.
  2. Set the volume node to back to none, right after the import is completed.

My preference would be the second.

improve large volume import workflow

From Murat:

I really would like to see an automated conversion of vector2scalar volume during the data import phase for bmp/jpg/png stacks (tiff doesn’t suffer from this). The way I envision is an extra checkbox in options for people who installed SlicerMorph, if we cannot do it default for everyone. If we can get pass that point, things will be a lot more easy for the folks. What’s happening is they are using 3 times as much memory for volumes that are already fairly big to begin with (almost everyone worked with datasets >1GB, sometimes 5-6GBs), and almost all volumes coming from bruker/skyscan microcts are bmps (which is the default output option in their post-processing software). And there are a lot of data coming from those scanners.

Plotting PCs creates increased CPU activity

With otolith data I see 40 cores being utilized for almost a minutes. Seem excessively high for just plotting...

Sample data path.
/home/kelly/otolith/auto3dgm_test/output_l_s/phase2/aligned_landmarks

ReadLandmark does not apply the LPS2RAS

From an user email during the workshop:

Hi Dr. Maga,

I used a module called ReadLandmarkFile and changed the IDAV Landmark export file to .pts. It was successfully imported! Thank you! Is this the Isaac Landmark reader? And I encountered another problem. The imported landmark cannot correspond to the .ply file after I centered them. It seems they are mirror image of each other. Do you know how to correct this?

I think we just need to LPS2RAS to read them correctly.

ImageStacks file parser implementation

Currently imagestacks uses the order OS provides. THere are reports of cases where MacOS does not seem to sort the files by filenames by defaults, or skips files during selection of large number of files.

A filename parser that will sort filenames will be good to mitigate these issues.

3D point placement bug

To replicate,
Enable 3D rendering for MRHead.nrrd, adjust volume property.
Mouse mouse to 3D rendering window, hit p, see that you cannot create a point without moving the mouse around.
Replicates all the time on latest windows stable.

While this is not a terrible bug, I think we should change the behavior of P keystroke, not to go into Place mode, but actually place the point where the cursor is. It is more convenient (and intuitive) to adjust your rendering first, position your cursor, and create the point at that location.

ImportFromURL works only for volume data currently

Please revise to work with any data type Slicer accepts (3D models, fiducials, transforms, etc) not just models, including zip files. If it is a zip, action should be just unzipping to the temp folder, do not load into the scene.

There is now a preference in the SlicerMorph preferences to set the temp location for both cache and Temp folder the same location.

Setup 3D Visualization menu

How about renaming the section of GPA module from "Setup 3D Visualization" to "Setup Dynamic Visualization", or "Setup Interactive Visualization" Lollipop plots are also 3D.

MarkupEditor

Set the curve setting to linear instead of the default Spline. WIth spline it is not possible to control the shape of the curve.

importing open3d<0.10 crashes Slicer in Linux in latest stable and preview versions

This is a due to an incompatibility with glibc libraries.

It renders ALPACA unusable in most Linux systems including Centos8 or Ubuntu 20.04. We will either have to update the ALPACA to use open3d >=0.10 on all platforms, or disable ALPACA for Linux.

I propose to open a separate development branch for migration to open3d 0.10.0

Export as doesn't function with latest nightly on windows

this is with 4.11.0-2020-07-07 r29207 / dad86b0

  • also Export As still appears only in the Markups.


Loading Slicer RC file [C:/Users/murat/.slicerrc.py]
Volume nodes will be stored uncompressed by default
Segmentation nodes will be stored uncompressed
parent qSlicerScriptedFileWriter (QObject 0x00000212AAA2A870)
Write {'fileName': 'C:/Users/murat/Desktop/C.fcsv', 'nodeID': 'vtkMRMLMarkupsCurveNode1'}
Traceback (most recent call last):
  File "C:/Users/murat/AppData/Roaming/NA-MIC/Extensions-29207/SlicerMorph/lib/Slicer-4.11/qt-scripted-modules/MarkupsFcsv.py", line 58, in write
    self.parent.writtenNodes = [markupNode.GetID()]
AttributeError: 'writtenNodes' does not exist on qSlicerScriptedFileWriter and creating new attributes on C++ objects is not allowed
Could not save C to C:/Users/murat/Desktop/C.fcsv


image

Preview tab layout

Create mock tabbed layout for GPA module for each step of the analysis (as oppose to scrolling down)

ALPACA

Couple usability suggestion for the next version of alpaca

  1. Color the target mesh lighter to make the points more visible (I think this is done, I report it for the posterity).
  2. Implement a new tab to calculate a Slicer affine transform (so that ALPACA can be used as general purpose alignment tool).
  3. For both single and batch processing, give an option to write the setting and re-read them. This will facilitate consistent multiple runs easier.

check the output folder whether it is writable before commencing the analysis

If it is, execute the analysis, if not return an error message about not being able to save results (gpa doesn't work properly if can't save).

`Loaded 44 subjects with 500 landmark points.
9
Scale Factor: 0.14121616650561752

Traceback (most recent call last):
File "/home/maga/.config/NA-MIC/Extensions-28927/SlicerMorph/lib/Slicer-4.11/qt-scripted-modules/GPA.py", line 473, in onLoad
os.makedirs(self.outputFolder)
File "/home/maga/Downloads/Slicer-4.11.0-2020-04-03-linux-amd64/bin/../lib/Python/lib/python3.6/os.py", line 220, in makedirs
mkdir(name, mode)
PermissionError: [Errno 13] Permission denied: '/home/kelly/otolith/41clupeiformes_2/auto3dgm_test/l_s_output/phase2/aligned_landmarks/2020-04-24_13_33_45'`

Accept all model formats in the same dialog box

When loading a reference model for the GPA module, user has to manually switch between vtk, ply, obj and other formats, and sometimes thinks that files are missing. Change the dialog box to include all acceptable model formats at the same time

Re-organize SlicerMorph module structure to match the paper presentation:

Remove the SlicerMorph Labs section, remove the community contributed modules (it is not functional anyways).

I/O modules:
ImageStacks:
SkyscanReconImport:
MorphoSourceImport:

Geometric Morphometrics modules:
Generalized Procrustes Analysis (GPA):
CreateSemiLMPatches:
PseudoLMs:
ALPACA
Auto3Dgm:
LMTemplate:

Convenience Modules (or a better alternative)
Animator:
ImportSurfaceToSegment:
MorphologikaLMConverter:
PlaceSemiLMPatches:
ProjectSemiLMPatches:
VolumeToModel:
SegmentEndoCranium:

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.