🧠 TractEdit

A Python-based Open-Source Interactive Tool for Virtual Dissection and Manual Refinement of Diffusion MRI Tractography

.trk • .tck • .trx • .vtk • .vtp

AF_clip_v3.3.0.mp4

---

👤 Author

Marco Tagliaferri — PhD Candidate in Neuroscience 🏛️ Center for Mind/Brain Sciences (CIMeC), University of Trento, Italy

If you use TractEdit in your research, please cite:

Tagliaferri, M. (2026). TractEdit: An Open-Source Interactive Tool for Virtual Dissection and Manual Refinement of Diffusion MRI Tractography. Zenodo. https://doi.org/10.5281/zenodo.18118153

BibTeX:

@software{tagliaferri2026tractedit,
  author = {Tagliaferri, Marco},
  title = {TractEdit: An Open-Source Interactive Tool for Virtual Dissection and Manual Refinement of Diffusion MRI Tractography},
  year = {2026},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.18118153},
  url = {https://doi.org/10.5281/zenodo.18118153}
}

📌 A dedicated manuscript is currently in preparation. This section will be updated with the publication reference once available.

---

📋 Table of Contents

• Key Features
• Getting Started
• Keyboard Shortcuts
• Sample Workflow
• Author
• License

✨ Key Features

📂 File I/O

Load & save streamlines in .trk, .tck, .trx, .vtk, .vtp formats with whole-brain support (>5M streamlines)

🖥️ Visualization

• Multi-view: 3D + Axial, Coronal, Sagittal slices
• Anatomical overlay with NIfTI support
• RGB, scalar, or greyscale coloring
• Line or tube rendering

✏️ ROI & Editing Tools

• Drawing: Pencil, Eraser, Sphere, Rectangle modes
• Selection: Sphere-based streamlines selection and deletion with adjustable radius
• Filtering: Include/Exclude logic for ROIs
• Undo/Redo support for streamline deletions and ROI operations

🧠 Advanced Analysis

• FreeSurfer parcellation support with connectivity matrices
• ODF 3D visualization (spherical harmonics)
• Track Density Imaging (TDI)
• Centroid & Medoid calculation

📋 Full Feature List

File Support

• Load & Save streamline bundles (.trk, .tck, .trx, .vtk, .vtp)
• Whole-Brain Tractogram Support: Optimized rendering for large datasets (tested with >5 million streamlines) using stride-based visualization and toggleable "skip"

Visualization

• Multi-View Orthogonal Visualization: Integrated 3D viewer and three linked 2D orthogonal slice views (Axial, Coronal, Sagittal)
• Anatomical Image: Load NIfTI images (.nii, .nii.gz) for anatomical context and interactive slice navigation
• 3D Visualization with VTK and FURY
  • Default orientation (RGB), or scalar-based coloring with dynamic colormap range adjustment, or greyscale
  • Render as Lines or Tubes: Toggle between fast line rendering and high-quality 3D tube rendering via View → Streamline Geometry
  • Interactive RAS coordinate bar for precise navigation

ROI Support

• Multi-Layer Anatomical ROI Support: Load multiple NIfTI images (.nii, .nii.gz) as Region of Interest (ROI) layers
  • Independent visibility toggles and color settings
  • Logical Filtering: Right-click ROIs to set them as exclusion or inclusion ROIs for streamlines

Interactive ROI Drawing Tools

• Pencil Mode (1): Freehand drawing directly on 2D slice views to create custom ROIs
• Eraser Mode (2): Erase portions of ROIs with freehand strokes
• Sphere Mode (3): Draw spherical ROIs on slices
• Rectangle Mode (4): Draw rectangular/cuboid ROIs on slices
• Move ROIs: Hold Ctrl and drag to reposition sphere or rectangle ROIs with real-time preview. Hold Ctrl + scroll to resize
• Undo/Redo Support: Full undo/redo for all ROI drawing operations (Ctrl+Z / Ctrl+Y) if mode enabled, otherwise for streamline deletion

Interactive Editing Tools

• Sphere-based streamline selection (with adjustable radius)
• Streamline deletion and undo/redo support
• Screenshot export

FreeSurfer Parcellation Support

• Load FreeSurfer parcellation/segmentation files (aparc+aseg, aparc.a2009s+aseg, etc.)
• 3D Parcellation Overlay: Visualize connected parcellation regions in 3D with hemisphere-organized tree view
• Region Logic Filters: Set parcellation regions as Include/Exclude filters for streamlines
• Compute Connectivity Matrix: Generate structural connectivity matrices from streamlines and parcellation

ODF Visualization

• Load Spherical Harmonics (SH) coefficient NIfTI files
• ODF Tunnel View: Visualize ODFs masked by the current bundle's spatial extent

Export Options

• Track Density Imaging (TDI): Save density maps of visible streamlines as NIfTI files
• HTML Export (Experimental): Export interactive 3D visualization as self-contained HTML file
• Screenshot export in multiple formats

Bundle Analytics

• Calculate Centroid and Medoid (both AOT-compiled) of the edited bundle with cancellable progress and batched distance computation

UI & Performance

• Theme Support: Light, Dark, and System theme modes with full UI styling
• Streamline Info Display: File name, streamline count, voxel size, bounding box, etc. with vertical data panel and hover details
• Keyboard Shortcuts for fast interaction (see full list below)
• Fast Startup: Splash screen implementation for immediate feedback and optimized library loading
• Background Loading: Non-blocking threaded loading for large streamline bundles and anatomical images
• Memory-Mapped Images: Efficient on-demand slice extraction for large anatomical images without loading full volume into RAM
• Modular Architecture: Refactored codebase with dedicated manager classes (ThemeManager, StateManager, SelectionManager, etc.) for improved maintainability
• Performance Optimizations: AOT-compiled numerical kernels with binary search resampling and parallel batch processing for geometric computations, Numpy vectorizations, debounced UI updates, pre-computed bounding boxes for fast selection, TRX bbox cache on reload (_tractedit_bboxes), and TRX-native save path (select(copy_safe=True) + tbx.save()) to avoid nibabel round-trips
• Reliability: Comprehensive automated test suite (152 tests) ensuring stability of core features

💡 Tips for Large Datasets

📌 While TractEdit supports whole-brain tractograms, rendering density may be automatically reduced for extremely large files to maintain interactivity. You can adjust this manually in the toolbar.

Selection Strategy:

Method	Best For
Sphere Selection	Refining specific bundles or small bundle complexes
ROI Filtering	Whole-brain tractograms (works on entire dataset)
ROI Drawing	Custom regions on anatomical slices
Parcellation Filtering	Anatomically-guided filtering with FreeSurfer

---

Getting Started (Manual Install)

1. Clone the Repository

git clone https://github.com/marcotag93/TractEdit.git
cd TractEdit

2. Install Dependencies

The project dependencies (including PyQt6, VTK, and Nibabel) are defined in pyproject.toml

• Python 3.11 (required)
• PyQt6
• VTK
• FURY
• Nibabel
• NumPy
• trx-python
• Scipy

Note: Python 3.11 is the only officially supported version. Other Python versions may experience compatibility issues with dependency combinations.

Recommend a virtual environment:

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

# Install the app and its dependencies:
pip install .

Note: The install process automatically compiles the AOT numerical extension (optimized computational kernels) for your operating system. Numba is temporarily downloaded as a build-time dependency to compile the extension, but is not installed into your environment — only the compiled binary is kept.

3. Launch the App

The application can now be launched using the tractedit command installed via pip.

tractedit

Command Line Options

# Load files directly
tractedit bundle.trk --anat T1w.nii.gz

# Load multiple ROI files at startup
tractedit bundle.trk --anat T1w.nii.gz --load-roi roi1.nii.gz --load-roi roi2.nii.gz

# Load file creating a spherical ROI at RAS coordinates
tractedit bundle.trk --anat T1w.nii.gz --roi 10,20,30 --radius 5

# Headless format conversion (no GUI)
tractedit input.trk --convert-to output.trx

# Headless density map export (TDI)
tractedit input.trk --density-map output.nii.gz --anat T1w.nii.gz

# Display version and help
tractedit --version
tractedit --help

On certain Linux systems (e.g., Ubuntu on Wayland), you may encounter Qt platform errors. If so, try the xcb workaround below.

QT_QPA_PLATFORM=xcb tractedit

4. Load Sample Data (Optional)

Explore sample_data/ to test TractEdit with example streamline files, anatomical file, ROI files, parcellation file and ODF files.

---

For Developers / Contributors

If you want to contribute or build from source, install the full development stack:

# Install all dependency groups
poetry install --with build,dev,test

# Build the AOT-compiled numerical extension for your OS
# (this step is automatic when using `pip install .`, but
# must be run manually after `poetry install`)
python tractedit_pkg/_numba_aot/build_aot.py

# Run the app
poetry run tractedit

# Run tests
poetry run pytest tests/ -v

Note: The AOT extension produces a platform-specific binary (.pyd on Windows, .so on Linux/macOS) and must be rebuilt after modifying any functions in tractedit_pkg/_numba_aot/build_aot.py. These compiled files are not tracked in git — each developer builds them locally.

Pre-built Executables

No Python setup is required for these versions. Download the latest release for your operating system:

• Windows: Use the .exe file.
• macOS (Apple Silicon): Use the .dmg file.
• Linux (AppImage): Use .AppImage — portable, runs on most Linux distributions without installation. Simply make it executable (chmod +x) and run.
• Linux (Debian/Ubuntu): Use .deb — native package for Debian-based distributions. Install with sudo dpkg -i TractEdit_3.4.5_amd64.deb.

---

Keyboard Shortcuts

Key / Combo	Action
s	Add streamlines at cursor to selection (selection grows only)
Shift+s	Remove streamlines at cursor from selection (selection shrinks only)
i	Invert selection
d	Delete selected streamlines
c	Clear current selection
+ / =	Increase selection sphere radius
-	Decrease selection sphere radius
↑ / ↓	Axial Slice navigation (Z-axis)
← / →	Sagittal Slice navigation (X-axis)
Shift+Scroll	Slice navigation on the 2D panel under cursor
1	Toggle Pencil drawing mode
2	Toggle Eraser drawing mode
3	Toggle Sphere ROI drawing mode
4	Toggle Rectangle ROI drawing mode
Ctrl+↑ / Ctrl+↓	Coronal Slice navigation (Y-axis)
Ctrl+Click	Replace sphere/rectangle ROI (when in mode)
Ctrl+Drag	Move sphere/rectangle ROI (when in mode)
Ctrl+Scroll	Resize sphere/rectangle ROI (when in mode)
Ctrl+s	Save As
Ctrl+z	Undo last deletion / ROI operation
Ctrl+y / Shift+z	Redo last undone deletion / ROI operation
Ctrl+p	Save a screenshot
Esc	Hide selection sphere
Ctrl+q	Quit application

---

Sample Workflow

Step 1: Load Your Data

File → Load          → Load .trk, .tck, .trx, .vtk, or .vtp
File → Load Image    → Add anatomical image (NIfTI)

Step 2: Navigate

• 2D Slices: Click-drag, arrow keys, or Shift+scroll on any 2D panel
• 3D View: Rotate, zoom, pan with mouse

Step 3: Edit (Choose Your Approach)

🎯 Manual Selection +/- adjust radius S to add streamlines Shift+S to remove streamlines I to invert selection D to delete

📂 Load ROIs File → Load ROI Right-click for Include/Exclude

✏️ Draw ROIs 1 Pencil · 2 Eraser 3 Sphere · 4 Rectangle Ctrl+drag to move Include/Exclude

🧠 Parcellation File → Load Parcellation Right-click regions Include/Exclude

Step 4: Finalize & Export

Action	Menu
Change colors	View → Streamline Color
Calculate centroid/medoid	File → Calculate Centroid/Medoid
Save density map	File → Save Density Map
Export HTML	File → Export to HTML
Save bundle	File → Save As

💡 Tip: Use Ctrl+Z / Ctrl+Y for undo/redo at any time!

---

License

This project is licensed under the MIT License. See the LICENSE file for details.