|
|
|
|
CPPNeuronMesher is a C++ project designed for the geometric analysis and mesh generation of neuron morphologies, providing tools for advanced neuroscience modeling and simulation. The repository features robust CI/CD pipelines, extensive quality checks, and detailed documentation to support reproducibility and collaborative development.
- GitHub Repository: CPPNeuronMesher
- GitHub Pages: CPPNeuronMesher
- Doxygen: API Docs (Doxygen)
Written in the following programming languages:
The badges at the top of this README provide at-a-glance insights into the health, quality, and activity of the project. Build and test status badges (from GitHub Actions and Doctest) show whether the code compiles and passes its tests. Quality and analysis badges from Codacy and SonarCloud summarize code reliability, security, vulnerabilities, bugs, and code smells, while repository statistics badges reveal language usage, code volume, contributor activity, release status, and recent updates. Together, these metrics help users and contributors quickly assess the project's current state and ongoing maintenance.
The CI & Quality badges show the current build status, test results, and automated code quality checks, giving a quick snapshot of whether the project is compiling, passing its tests, and meeting quality standards.
The Detailed Quality badges provide in-depth information about the project’s software health, including reliability, security, vulnerabilities, bugs, and code smells, as assessed by SonarCloud. These metrics help developers and users identify potential risks and areas for improvement in the codebase.
The Repository Statistics badges display key metrics about the project's codebase and activity, such as the main programming language, total languages used, repository size, number of contributors, open pull requests, and the date of the last commit. These badges provide a quick overview of the project's scale, diversity, and recent development activity.
The GitHub Metadata badges highlight important repository details such as the project's license, latest release version, star and fork counts, which indicate popularity and community engagement. These badges help users quickly gauge the project's openness, activity, and level of public interest.
The Static Analysis Summary badges indicate the results of automated code analysis performed by tools like SonarCloud, highlighting overall code quality and whether the project passes essential quality gates. These provide a quick status check for maintainers and users, and you can view the full analysis details on SonarCloud.
This project leverages Windsurf, an AI-powered documentation assistant, to generate high-level summaries and improve code readability across the codebase. Detailed API and internal documentation is generated using Doxygen, providing class references, file structure, and dependency diagrams for the C++ components. Both tools have been integrated to enhance the maintainability, transparency, and navigability of the repository.
CPPNeuronMesher is a C++ toolkit for analyzing neuron geometries and generating computational meshes from neuron morphology data (primarily in the .swc format). The project provides both command-line tools for mesh operations, and a lightweight OpenGL-based 3D viewer for visualizing neuron structures.
Main features include:
- Parsing and analyzing neuron morphologies in
.swcformat. - Automated mesh generation, refinement, and trunk extraction for neuron models.
- A fast, interactive 3D neuron viewer with rotation, zoom, and multiple visualization modes.
- Python bindings (
neurongraphshared library). - Modular CMake build system with continuous integration and quality analysis.
- Example scripts and utilities for advanced mesh and data manipulation.
📘 Project Plan (Windsurf), this link contains the current status and actions with respect to the documentation of the code.
- Features
- Prerequisites
- Build Instructions
- Using the Makefile
- Python Bindings and Notebook
- Running the Tools
- Neuron Viewer
- SWC File Format
- Troubleshooting
- License
- Mesh Generation: Create and refine computational meshes from neuron morphology data.
- Trunk Extraction: Isolate the main trunk or branches of neuron models.
- Batch Refinement: Split and refine neuron sets for large datasets.
- 3D Visualization: Real-time, interactive OpenGL viewer for
.swcfiles. - Python Interoperability: Shared library for Python via
pybind11. - Cross-Platform: Designed for Linux (WSL supported), with modular CMake build.
- Quality & Security: Integrated with SonarCloud and Codacy for code analysis and CI.
- Compiler: C++17 compatible (e.g.,
g++,clang++) - CMake: Version 3.10+
- Dependencies:
tinyxml2(for XML parsing)GLFW(for 3D viewer)GLandGLU(OpenGL core and utilities)X11(if using WSL or X11-based systems)
- Python (for using Python bindings via
pybind11)
sudo apt update
sudo apt install build-essential cmake libtinyxml2-dev libglfw3-dev libglu1-mesa-dev libgl1-mesa-dev x11-utilsFor WSL Users:
- Install an X Server on Windows, like VcXsrv or Xming.
- Launch your X server and allow access from 127.0.0.1.
- Then in your WSL terminal:
export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0
export LIBGL_ALWAYS_INDIRECT=1Clone the repository and build using CMake:
git clone https://github.com/jarosado0911/refactoredCPPNeuronMesher.git
cd refactoredCPPNeuronMesher
mkdir build && cd build
cmake ..
make -j$(nproc)cd scripts/app_neuronviewer
g++ -O3 -std=c++17 -o swc_viewer swc_viewer.cpp -lGL -lGLU -lglfwThis repository includes a top-level Makefile that provides convenient shortcuts for building, testing, cleaning, and installing the project and its Python modules.
makeormake build: Configure and build the project using CMake in the./build/directory. Binaries are placed in./bin/.make clean: Remove thebuild/andbin/directories and all Python cache/egg-info files.make ctest: Build the project and run CTest-based unit tests (legacy test system).make doctest: Build (if necessary) and run all C++ doctests (recommended for full coverage).make all: Run build, doctest, and then clean up intermediate files.make rebuildormake remake: Clean everything, then build from scratch.make install: Install required Python dependencies usingrequirements.txt.make installe: Install the Python package in "editable" development mode.make testpy: Run Python tests inpython_package/test/with pytest.make help: Display all available make targets with a short description.
# Build the project
make
# Run all C++ doctests
make doctest
# Clean the build and binary directories
make clean
# Install Python requirements
make install
# Install the Python package in editable mode (for development)
make installe
# Run Python tests
make testpyFor advanced or troubleshooting usage, consult the help target:
make helpThe Makefile is designed to streamline both C++ and Python development workflows in this repository.
The NeuronGraph class is the central data structure for representing, manipulating, and analyzing neuron morphologies within the toolkit. It models a neuron as a directed graph, where each node represents a structural element (such as a soma or neurite segment) and edges capture the connectivity between these elements. Internally, the class maintains a map of nodes (each keyed by a unique integer identifier and storing 3D position, radius, and type information) and a map of edges (where each node index maps to a list of its child node indices). The NeuronGraph class provides multiple constructors for initializing an empty graph, loading from SWC or UGX morphology files, or directly from a node set. Its extensive API supports reading and writing morphologies, topological sorting, soma detection and manipulation, preprocessing (such as cleaning or normalizing the graph), and various forms of mesh refinement and trunk extraction. Key methods include readFromFile, writeToFile, getNodes, setNodes, preprocess, splitEdges, and getTrunks, among others. The class is designed for both high-level batch processing and fine-grained interactive use, and is fully exposed to Python via pybind11 bindings, making it accessible in scripts, pipelines, or Jupyter notebooks. Typical use cases include loading neuron data, processing or refining its structure, analyzing branches and connectivity, and exporting results for visualization or simulation.
This repository provides Python bindings for its core C++ neuron analysis and meshing functionality through a shared library called neurongraph. The bindings are implemented using pybind11, enabling Python code to directly access high-performance C++ routines for neuron graph construction, file I/O, and mesh operations. These bindings are ideal for users who want to leverage the speed of C++ but prefer the flexibility and interactive environment of Python.
To illustrate the use of these bindings, a Jupyter notebook is provided: Tutorial - NeuronGraph.ipynb. This notebook demonstrates how to import and use the neurongraph module, including constructing neuron graphs, reading morphology files, and performing analyses in Python. The notebook also shows how to integrate with Python scientific libraries such as numpy, trimesh, and pythreejs for advanced analysis and interactive 3D visualization. By following the notebook, users can learn how to harness the full power of the C++ backend within their Python-based computational workflows.
Compiled binaries are placed in the bin/ directory. Main executables include:
- splitrefine: Refines neuron SWC files (mesh subdivision)
- splitrefineset: Batch refinement for a set of neurons
- extracttrunks: Extracts main trunk/branches from SWC files
Example usage:
./bin/splitrefine path/to/input.swc
./bin/splitrefineset path/to/input.swc
./bin/extracttrunks path/to/input.swcOutput is typically written to the output/ directory, with filenames based on the input SWC or a timestamp-based hash.
A lightweight 3D OpenGL-based viewer to render .swc neuron morphology files with interactive features:
- Rotation: Mouse drag
- Zoom: Scroll wheel
- Visualization Modes: Keys
1to6for switching render styles - Colored nodes/edges: By type and radius
- Lighting & Bounding Box: Optional enhancements
./neuronviewer path/to/neuron.swcor from the root directory of the project
./bin/neuronviewer path/to/neuron.swc- 🖱 Left-click + drag: Rotate the neuron
- 🔍 Scroll wheel: Zoom in/out
- 🔢 Number keys (1–6):
1: edges only (uniform)2: edges + uniform nodes3: nodes only (uniform size)4: nodes only (by radius)5: edges by radius6: full enhanced (edges by radius, lighting, etc.)
The standard SWC format is used for neuron morphologies:
# id type x y z radius parent
1 1 0.0 0.0 0.0 1.0 -1
2 3 5.0 0.0 0.0 0.5 1
3 3 10.0 0.0 0.0 0.4 2
...
- Window doesn't appear: Ensure
DISPLAYis set and X server is running. - Blank window: Use
LIBGL_ALWAYS_INDIRECT=1in WSL. - Missing cylinders: May be due to overlapping points or zero-length segments.
- Build errors: Ensure all dependencies are installed and CMake is version 3.10 or newer.
This project is released under the MIT License.
© 2025 James Rosado