Giter VIP home page Giter VIP logo

bluebrain / neuromorphovis Goto Github PK

View Code? Open in Web Editor NEW
126.0 10.0 26.0 136.35 MB

A lightweight, interactive, extensible and cross-platform framework for building, visualizing and analyzing digital reconstructions of neuronal morphology skeletons extracted from microscopy stacks.

Home Page: https://portal.bluebrain.epfl.ch/

License: GNU General Public License v3.0

Python 98.03% Shell 1.97%
neurons morphologies soma-reconstruction mesh-reconstruction morphology-analysis morphology-visualization blender-addon media-production neural-modeling simulation-based-neuroscience

neuromorphovis's Introduction

DOI

Introduction

Features

  • 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.
  • Dendrogram visualization and rendering.
  • Visualization of spines and synapses for neuronal morphologies of digitally reconstructed BBP circuits using BluePy.
  • 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.
  • Accurate mesh reconstruction with metaballs to handle morphologies with irregular and small branching angles.
  • Watertight mesh reconstruction using voxelization based remeshing (in Blender 3.0 onwards) for reaction-diffusion simulations.
  • Automated generation of high quality media for scientific documents and publications using different shading styles and materials.
  • High fidelity mesh reconstruction based on Skin modifiers as presented by Abdellah et al., 2019.
  • Robust mesh reconstruction of synthetic astroglial cells using Metaballs and implicit geometries Abdellah et al., 2021
  • Fast mesh reconstruction of spiny neuronal morohologies based on union operators for rendering transparent meshes Abdellah et al., 2022.
  • 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, Neurolucida ASCII format 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.

News

  • 06.2023: New logo release.
  • 05.2023: Release 1.9.0
  • 05.2023: Blender 2.79 and 2.8 are no longer supported by NeuroMorphoVis.
  • 04.2023: Implementation of the Voxelization-based remeshing to create watertight mesh models of neurons and astrocytes.
  • 03.2023: Adding the Synaptics panel to NeuroMorphoVis.
  • 09.2022: Paper, Generating high fidelity surface meshes of neocortical neurons using skin modifiers, in EG Computer Graphics and Visual Computing (CGVC) 2022, more information.
  • 04.2020: Release 1.4.5
  • 09.2019: Paper: Generating High Fidelity Surface Meshes of Neocortical Neurons using Skin Modifiers, in EG Computer Graphics and Visual Computing (CGVC) 2019, more information.
  • 05.2019: Release 1.3.1
  • 03.2019: Release 1.3.0
  • 10.2018: Release 1.0.0
  • 07.2018: NeuroMorphoVis' core paper is published in Oxford Bioinformatics, more information.

Package Details

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

Nevertheless, it is recommended to avoid version 2.79 and use version 3.5.

NeuroMorphoVis can be downloaded as a binary archive bundled within Blender that can be easily extracted and used out-of-the-box. The optional dependencies are already shiped within this archive using pip on each respective platform. This package (released every minor version update of the software) is recommended for Windows users or those who cannot use the Terminal. Otherwise, users can just download an installation script that will automatically install the entire package to a user-specified directory. This script does not require sudo permissions.

Installation

NeuroMorphoVis can be installed to a user-specified directory from a Unix (Linux or macOSX) terminal. Installation procedures are available in this page.

Downloading Package

NeuroMorphoVis packages are available for Ubuntu, RedHat, macOSX and Windows from the releases page. After downloading the package, users can load NeuroMorphoVis into Blender as explained in this page.

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 yellow) 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.

Gallery

Known Bugs or Feature Requests

Please refer to the github issue tracker for fixed and open bugs. User can also report any bugs and request new features needed for their research. We are happy to provide direct support .

Publications & 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 mesh generation algorithm with skin modifiers is described in this paper Generating High Fidelity Surface Meshes of Neocortical Neurons using Skin Modifiers

@inproceedings{abdellah2019generating,
  booktitle={Computer Graphics and Visual Computing (CGVC)},
  editor={Vidal, Franck P. and Tam, Gary K. L. and Roberts, Jonathan C.},
  title={Generating High Fidelity Surface Meshes of Neocortical Neurons using Skin Modifiers},
  author={Abdellah, Marwan and Favreau, Cyrille and Hernando, Juan and Lapere, Samuel and Schürmann, Felix},
  year={2019},
  publisher={The Eurographics Association},
  isbn={978-3-03868-096-3},
  doi={10.2312/cgvc.20191257}
}

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}
}

Publications that use or mention NeuroMorphoVis

An exhaustive list of all the publications that use or mention NeuroMorphoVis is available in this Wiki page.

Acknowledgement & Funding

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 funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government’s ETH Board of the Swiss Federal Institutes of Technology, and 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”). The code is open sourced with approval from the open sourcing committee and principal coordinators of the Blue Brain Project in December 2019.

Copyright (c) 2016-2023 Blue Brain Project/EPFL

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

  • The analysis plots are created based on Matplotlib and Seaborn. Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python and Seaborn is a Python data visualization library based on matplotlib. It provides a high-level interface for drawing attractive and informative statistical graphics. Matplotlib only uses BSD compatible code, and its license is based on the PSF license. Seaborn uses BSD license.

  • The analysis distributions are gathered into a single PDF using PyPDF2. PyPDF2 is a pure-python PDF library capable of splitting, merging together, cropping, and transforming the pages of PDF files. PyPDF2 uses the BSD License.

  • The table of contents for all the user documentation pages are generated with markdown-toc.

Contact

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

Marwan Abdellah
Scientific Visualiation Expert
Visualization Team, Computing Division
Blue Brain Project
[email protected]
marwan-abdellah.com

Navigation

neuromorphovis's People

Contributors

alex4200 avatar haitham-shaban avatar jplanasc avatar markovg avatar marwan-abdellah avatar orena1 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  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

neuromorphovis's Issues

Using the Branching by Angles for SWC files is not correct.

If the end users selects the branching by Angles, for example in the Morphology Toolbox, when loading SWC files, the skeleton is not drawn and the following error is given:

line 242, in label_primary_and_secondary_sections_based_on_angles
    angle = parent_vector.angle(child_vector)
ValueError: Vector.angle(other): zero length vectors have no valid angle

Hide the BBP morphology loader if Brion cannot be imported.

To avoid confusion for external users or collaborators, hide the loading BBP circuit option if Brion is not installed on the system. Perform this step during an initialization step.

try:
    import brion
    BRION_COULD_BE_IMPORTED
catch:
    BRION_COULD_NOT_BE_IMPORTED

Exposing the skeleton editing feature in the user interface

To allow the users to manually add some fixes to the morphology skeleton, the skeleton must be sketched as a connected acyclic graph, where each node can be represented as a vertex and the the user can move or rotate this vertex. Using poly-lines cannot guarantee this implementation, so it is better to start from a single vertex at the origin and then extrude it along the skeleton.

The feature should be exposed to the user in the morphology analysis panel.

User Feedback

Soma Toolbox

Method: it's a bit unclear what are the complex and arbor methods, maybe a few words on what's under the hood or what's each method specificity would be useful

Base Color and Material: it seems that the color is taken in consideration only when the material is "Lambert Ward"

Subdivisions: of what? Also the default (5) seems to be the only one that gives satisfying results (lower: odd shapes, higher: too long to compute)

Simulation steps: Does not seem to affect the work, also the timeline at the bottom always goes up to 100

Quick Rendering Options: I've selected Resolution: 3600 and it was not quick. For a future version, a loading bar would be nice.

Meshes: export to OBJ is nice!

Morphology Toolbox

When reconstructed, some facets of the soma seem to be coplanar/overlapping with some facets of the dendrite and axons. Even though it makes sense in term of reconstruction, it might be better for visual purpose to truncate the axons/dendrite at the edge of the soma. EDIT: I later saw the option Arbor to Soma: All Disconnected but then we have gaps between soma and dendrites.

No option to save morphs in OBJ?

360 sequences are exported fine but only as a lit of png. Having an additional mp4 would be nice.

Count Zero-radii Samples

Some morphologies have zero radii. These samples cause issues and mesh reconstruction artifacts. It is therefore better to verify if the morphology has no samples with zero-radii before reconstructing it. It would be also nice to add in the analysis panel an item that should their number and distribution.

Computing morphology volume and surface area.

The scientists have requested a new feature in the analysis toolbox to allow them to compute the volumes and surface area of the following:

  • Each segment in the morphology
  • Each section in the morphology
  • Total volume and surface area of each neurite in the morphology
  • Total volume and surface area of the entire morphology
  • Volume and surface area of the soma based on the sphere simplification or from the 3d mesh reconstructed from the soma toolbox.

NameError: name 'materials' is not defined

Using the Articulated Sections style to sketch the morphology in the Morphology Toolbox tab seems to have an issue. The morphology is not drawn and we get the following error:

Traceback (most recent call last):
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/interface/ui/morphology_panel.py", line 417, in execute
    nmv.interface.ui_reconstructed_skeleton = builder.draw_morphology_skeleton()
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/builders/skeleton/skeleton_builder.py", line 943, in draw_morphology_skeleton
    bevel_object=bevel_object))
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/builders/skeleton/skeleton_builder.py", line 620, in draw_morphology_as_articulated_sections
    material_list=self.articulation_materials)
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/builders/skeleton/skeleton_builder.py", line 255, in draw_section_terminals_as_spheres
    section_terminal_sphere = self.draw_section_terminal_as_sphere(root)
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/builders/skeleton/skeleton_builder.py", line 212, in draw_section_terminal_as_sphere
    name='joint_%d' % section.id, color=self.options.morphology.articulation_color)
  File "/home/abdellah/.config/blender/2.79/scripts/addons/NeuroMorphoVis/neuromorphovis/geometry/object/sphere.py", line 81, in create_uv_sphere
    sphere_material = materials.create_default_material(name='sphere_color', color=color)
NameError: name 'materials' is not defined

location: <unknown location>:-1
location: <unknown location>:-1

Implementing a watertight meshing algorithm for the morphologies.

Some users have requested to implement a meshing technique that can generate watertight meshes. Considering the complexity and the severe artefacts of the morphologies in general, mesh extrusion from simple geometry cannot be used. There are two solutions to implement this: either a volumetric-based (for example octree) reconstruction or a field-based method (like meta balls and meta objects).
Moreover, it would be appreciated if the artifacts of the morphologies are repaired before the reconstruction of the mesh and the soma profile was quite realistic.

One button to export them all.

Replace the export buttons with a drop down menu with all the options and a single button to export the mesh. This would make the UI less cluttered.

Adding Developer Documentation

The current Developer Documentation is quite limited. It must be improved to get further collaborators and contributors.

Mesh Reconstruction

This project would be concerned with all the new feature requests or bugs reported for the Mesh Reconstruction Toolbox panel in NeuroMorphoVis.

SWC reader cannot show morphology files that have jumps in the indices of the samples.

Normal SWC files are assumed to index the samples in an incremental order, for example

2 3 -3.01 -9.03 -18.36 1.005 1
3 3 -3.68 -9.37 -18.36 1.005 2
4 3 -4.01 -10.04 -18.36 1.005 3
5 3 -5.69 -10.71 -18.36 1.005 4
6 3 -6.02 -11.71 -18.36 1.005 5
7 3 -6.69 -12.05 -18.36 1.005 6
8 3 -7.03 -12.38 -18.36 1.005 7
9 3 -7.36 -13.05 -18.36 1.005 8
10 3 -8.03 -13.72 -18.36 1.005 9
11 3 -8.36 -14.39 -18.36 1.005 10
12 3 -8.7 -15.06 -18.36 1.005 11
13 3 -9.37 -15.39 -18.36 1.005 12
14 3 -9.7 -15.73 -18.36 1.005 13
15 3 -10.04 -16.4 -18.36 1.005 14
16 3 -10.71 -16.73 -18.36 1.005 15
17 3 -11.04 -17.4 -18.36 1.005 16
18 3 -11.71 -17.73 -18.36 1.005 17
19 3 -12.04 -18.07 -18.36 1.005 18
20 3 -13.38 -19.07 -18.36 1.005 19

However, SWC files can be manually modified and the order of the indices can change. This issue must be handled, otherwise, the entire morphology skeleton cannot be sketched.

One button to render them all.

To make the UI less cluttered, replace the thee rendering buttons [Front, Side, Top] by a drop down menu and single button to render the selected view.

  • Rendering Option
    ++ Select View [Front, Side, Top] - Render

Exporting the documentation to a PDF.

The current documentation is written in Markdown files. It would be nice to compile it into a PDF as well, upload it to the repository and add another panel in the UI of NeuroMorphoVis to load the documentation directly.

Compiled Blender install not working on MacOS

When opening the application, I get the following error message:
“blender” is damaged and can’t be opened. You should move it to the Trash.

Blender itself works from its own download page, but it is not clear how to add the add-on from this repository. Is blender looking for me to point to a .py file that has all the code for the add-on?

Updating the Soma Toolbox panel.

For consistency, change the order of the Colors & Materials section with the Soft Body Parameters one. The current layout sounds confusing to the testers.

Handle morphologies with no basal dendrites.

During the testing phase, I have discovered some morphologies with no basal dendrites. Therefore, we must check if the basal dendrites are None or not before operating on a NoneType.
If this not solved, we will keep getting the following error:

    for dendrite in self.dendrites:
TypeError: 'NoneType' object is not iterable

Hidden issue when loading an SWC file

When we load an SWC morphology file, the last sample in the list is not integrated in the morphology skeleton, and therefore the reconstructed object is not right. This severe issue must be fixed.

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.