Skip to content
A lightweight, interactive, extensible and cross-platform framework for building, visualizing and analyzing digital reconstructions of neuronal morphology skeletons extracted from microscopy stacks.
Python Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
data
docs Adding the bumpy shading images. Apr 3, 2019
nmv Adding minor updates to be able to reconstruct the soma for strange S… Oct 7, 2019
scripts Adding minor updates to be able to reconstruct the soma for strange S… Oct 7, 2019
.gitignore .gitignore. Oct 3, 2018
.version Version 1.3.1 May 15, 2019
AUTHORS.md Update AUTHORS.md Jun 18, 2019
GPL Fixing the License to GPL not LGPL to match what we promised in the p… Oct 8, 2018
LICENSE Removing the redundant __variable__. Oct 9, 2018
README.md
__init__.py Minor. Mar 23, 2019
neuromorphovis.cfg Adding the connected skeleton rendering mode. Jul 26, 2019
neuromorphovis.py Minor. Jun 18, 2019
neuromorphovis.sh Adding the wire frame shader. May 8, 2019

README.md

NeuroMorphoVis

Say Thanks GitHub Stars

Introduction

NeuroMorphoVis is an interactive, extensible and cross-platform framework for building, visualizing and analyzing digital reconstructions of neuronal morphology skeletons extracted from microscopy stacks. The framework is capable of detecting and repairing several tracing artifacts, allowing the generation of high fidelity surface meshes and high resolution volumetric models for simulation and in silico studies.

Features

NeuroMorphoVis provides four major toolboxes that can be used for

  • Automated analysis of neuronal morphology skeletons that are digitally reconstructed from optical microscopy stacks.
  • An easy context to load broken morphology skeletons and repair them manually.
  • Sketching and building three-dimensional representations of the morphology skeletons using various methods for visual analytics.
  • Automated reconstruction of accurate three-dimensional somata profiles, even with classical morphology skeletons that do not have any three-dimensional data of their somata. This approach uses the physics engine of Blender based on Hooke's law and mass spring models.
  • Automated reconstruction of polygonal mesh models that represent the membranes of the neuronal morphologies based on the piecewise meshing method presented by Abdellah et al., 2017.
  • Fast mesh reconstruction based on skinning and union operators for artistic rendering.
  • Accurate mesh reconstruction with meta balls to create watertight meshes for reaction-diffusion simulations.
  • Automated generation of high quality media for scientific documents and publications using different shading styles and materials.
  • Multiple interfaces: user-friendly graphical user interface, a rich command line interface, editable configuration files and a high level python API for python scripting.
  • Importing morphologies in multiple file formats including SWC, H5 or even from a BBP circuit using GIDs and cell targets.
  • Exporting the reconstructed meshes in several file formats including PLY, OBJ, STL and also as a Blender file (.blend).
  • Parallel batch processing on multi-node visualization clusters using SLURM workload manager.

Interfaces

NeuroMorphoVis is primarily designed as a plug-in in Blender. It comes with a user-friendly GUI and a rich set of command line options. Moreover, the tool is configurable via input configuration files making it possible to link it to web interface or using it on massively parallel visualization clusters for batch production.

The tool is also extensible via its powerful python API that can be imported in Blender console and text browser.

GUI

To make it accessible to end users with minimal programming knowledge or even with no programming experience at all, the core functionality of NeuroMorphoVis is exposed to users via a friendly graphical user interface that would allow them to navigate and adjust the parameters of the different toolboxes seamlessly. A detailed guide to use NeuroMorphoVis from its GUI is available in this user guide.

A screen shot of a neuronal morphology skeleton reconstructed by NeuroMorphoVis and sketched in the 3D view port of Blender. Note that the neurites are tagged with different colors (green for apical dendrite, red for basal dendrites and blue for the axon) and the soma (in orange) is reconstructed as a realistic three-dimensional profile not as a sphere.

Command Line Options

NeuroMorphoVis has a rich command line interface that would make it easy to connect it to a web interface or use it to accomplish multiple tasks in an automated way. A list of all the command line options and their description are available in this user guide.

Configuration Files

Users can easily configure and use NeuroMorphoVis via editable configuration files. Instructions to write and use configurations files are available in this user guide.

Download

NeuroMorphoVis is mainly based on Blender. Blender is a free software and can be downloaded from this page. Blender is released under the GNU General Public License (GPL, or “free software”). The current version is compatible with the following Blender versions:

NeuroMorphoVis can be downloaded as a binary archive bundled within Blender that can be easily extracted and used without installing any further dependencies. The optional dependencies are already shiped within this archive using pip on each respective operating system.

Supported Platforms

A binary package of the current version of NeuroMorphoVis is shipped with Blender version 2.79 for the followign platforms:

  • Ubuntu Release 1.3.1 is available from this link.

  • Red Hat Release 1.3.1 is available from this link.

  • Mac OS Release 1.3.1 is available from this link.

  • Windows Release 1.3.1 is available from this link.

Sample Morphologies

To test the software, a set of sample morphology files (in SWC and H5 formats) are available to download from this link.

How to Use

NeuroMorphoVis can be used from the GUI of Blender. This is the easiest and most recommended approach to use. For systems without an X server, NeuroMorphoVis can be executed in the background mode (similar to blender -b) using the command line interface. For batch processing of multiple morphology files, the editable configuration files are provided. The python API can be also used to write plugins for high quality media production.

GUI

The user guide of the GUI is available in this link. In the following section, we provde a few video tutorials to show how to use the interface seamlessly.

Command Line Interface

The user guide of the command line interface is available in this link.

Configuration Files

The configuration file user guide is available in this link.

Python API

We are currently writing a detailed documentation to use the python API. If you are interested to collaborate with us to extend NeuroMorphoVis to fit your applications, please contact marwan.abdellah@epfl.ch.

Installation

The end users are recommended to download the archives from the links provided in the previous section. But if the users are willing to contribute and extend NeuroMorphoVis, we recommend to install it as described in this installation guide.

Highlights

Features

Neuronal Soma Reconstruction

A demonstration of using the Soma Reconstruction toolbox to reconstruct a three-dimensional profile of the soma of a pyramidal cell morphology using Hooke's law and mass spring models.

Neuronal Morphology Visualization

Using the Morphology Reconstruction toolbox to create a three-dimensional model of a morphology skeleton.

Neuronal Mesh Reconstruction

Using the Mesh Reconstruction toolbox to generate a piecewise watertight mesh model of a given morphology skeleton.

Gallery

Known Bugs or Feature Requests

Please refer to the github issue tracker for fixed and open bugs, and also to report new bugs and to request new features that you need in your research.

Publication & Citation

If you use NeuroMorphoVis for your research, media design or other purposes, please cite our paper NeuroMorphoVis: a collaborative framework for analysis and visualization of neuronal morphology skeletons reconstructed from microscopy stacks using the following entry:

@article{abdellah2018neuromorphovis,
  title={NeuroMorphoVis: a collaborative framework for analysis and visualization of neuronal morphology 
  skeletons reconstructed from microscopy stacks},
  author={Abdellah, Marwan and Hernando, Juan and Eilemann, Stefan and Lapere, Samuel and Antille, 
  Nicolas and Markram, Henry and Sch{\"u}rmann, Felix},
  journal={Bioinformatics},
  volume={34},
  number={13},
  pages={i574--i582},
  year={2018},
  publisher={Oxford University Press}
}

The supplementary material of this paper is also available in this document.

The core algorithms of the soma and mesh reconstruction modules are described in this paper Reconstruction and visualization of large-scale volumetric models of neocortical circuits for physically-plausible in silico optical studies

@article{abdellah2017reconstruction,
  title={Reconstruction and visualization of large-scale volumetric models of neocortical circuits 
  for physically-plausible in silico optical studies},
  author={Abdellah, Marwan and Hernando, Juan and Antille, Nicolas and Eilemann, Stefan and 
  Markram, Henry and Sch{\"u}rmann, Felix},
  journal={BMC bioinformatics},
  volume={18},
  number={10},
  pages={402},
  year={2017},
  publisher={BioMed Central}
}

The applications of NeuroMorhoVis are deomnstrated in the thesis In silico Brain Imaging: Physically-plausible Methods for Visualizing Neocortical Microcircuitry

@phdthesis{abdellah2017insilico:232444,
  title = {In Silico Brain Imaging Physically-plausible Methods for Visualizing 
  Neocortical Microcircuitry},
  author = {Abdellah, Marwan},
  publisher = {EPFL},
  address = {Lausanne},
  pages = {400},
  year = {2017}
}

Acknowledgement

NeuroMorphoVis is developed by the Visualization team at the Blue Brain Project, Ecole Polytechnique Federale de Lausanne (EPFL) as part of Marwan Abdellah's PhD (In silico Brain Imaging: Physically-plausible Methods for Visualizing Neocortical Microcircuitry). Financial support was provided by competitive research funding from King Abdullah University of Science and Technology (KAUST).

License

NeuroMorphoVis is available to download and use under the GNU General Public License (GPL, or “free software”).

Attributions

  • Blender (C) is copyright to Blender Foundation. The Blender Foundation is a non-profit organization responsible for the development of Blender. Blender is released under the GNU Public License, as Free Software, and therefore can be distributed by anyone freely.

  • Slurm, is a free and open-source job scheduler for Linux and Unix-like kernels, used by many of the world's supercomputers and computer clusters. Slurm is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

  • The SWC morphology samples are available from NeuroMorpho.Org. NeuroMorpho.Org is a centrally curated inventory or repository of digitally reconstructed neurons associated with peer-reviewed publications.

  • The H5 morphology samples are available with permissions from the Blue Brain Project, Ecole Polytechnique Federale de Lausanne (EPFL).

Contact

For more information on NeuroMorphoVis, comments or suggestions, please contact:

Marwan Abdellah
Scientific Visualiation Engineer
Blue Brain Project
marwan.abdellah@epfl.ch

Samuel Lapere
Section Manager, Visualization
Blue Brain Project
samuel.lapere@epfl.ch

Should you have any questions concerning press enquiriries, please contact:

Kate Mullins
Communications
Blue Brain Project
kate.mullins@epfl.ch

You can’t perform that action at this time.