🧠 TractEdit

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

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

Important

Research Use Only. TractEdit is a research tool for the visualization, virtual dissection, and quality control of diffusion MRI tractography. It is not a medical device, has not been clinically validated, and holds no regulatory clearance (FDA / CE). It must not be used for diagnosis, treatment planning, or neurosurgical guidance.

AF_clip_v3.4.6.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., & Cattaneo, L. (2026). TractEdit: An Open-Source Interactive Tool for Virtual Dissection and Manual Refinement of Diffusion MRI Tractography. Journal of Neural Engineering, 23(4), 046046. https://doi.org/10.1088/1741-2552/ae9346

BibTeX:

@article{Tagliaferri_2026,
  author = {Tagliaferri, Marco and Cattaneo, Luigi},
  title = {{TractEdit}: an open-source interactive tool for virtual dissection and manual refinement of diffusion {MRI} tractography},
  journal = {Journal of Neural Engineering},
  publisher = {IOP Publishing},
  year = {2026},
  month = {aug},
  volume = {23},
  number = {4},
  pages = {046046},
  issn = {1741-2552},
  doi = {10.1088/1741-2552/ae9346},
  url = {https://doi.org/10.1088/1741-2552/ae9346}
}

✨ Key Features

📂 File I/O

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

Save and reopen an editing session from the File menu to resume work in the four-view workspace.

🖥️ Visualization

Multi-view: 3D + Axial, Coronal, Sagittal slices
Affine-aware oblique NIfTI display with bounded previews for large volumes
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
- Oblique acquisitions preserve scanner-RAS geometry. Volumes within the display budget use native voxel data; larger volumes use a strided, smoothed preview with an affine adjusted for the stride.
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 matching 2D/3D 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

Sessions: Save the editing state and reopen it later, including ROI data, undo/redo, filters, selections, ODF tunnel and the four views. See Save and Restore Sessions for the workflow and source-file requirements.
Track Density Imaging (TDI): Save density maps of visible streamlines as NIfTI files
HTML Export (Experimental): Share the visible 3D scene as a self-contained, offline HTML file. Simplified geometry is for viewing, not quantitative analysis.
Screenshot export in multiple formats

Bundle Analytics

Calculate Centroid and Medoid of the edited bundle with AOT distance kernels, bounded historical tie handling.

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
Large-volume previews: Stride NIfTI proxies before float32 conversion for bounded display data. Canonicalization and native-size previews may still materialize the source volume.
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 GIL-releasing parallel batch wrappers for measured large workloads; small workloads stay serial. NumPy vectorizations, debounced UI updates, pre-computed bounding boxes, validated TRX bbox cache reuse (_tractedit_bboxes), proxy-strided previews, and TRX-native saves avoid unnecessary work and format round-trips.
Reliability: Automated regression tests cover core features and scientific data handling.

💡 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  # Short aliases: -v, -V
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

# Rebuild after changing an AOT kernel
python tractedit_pkg/_numba_aot/build_aot.py

# Run the app
poetry run tractedit

# Run tests
poetry run pytest tests/ -v

Note: pip install ., pip install -e ., and poetry install compile the AOT extension automatically. The build produces a platform-specific binary (.pyd on Windows, .so on Linux/macOS); rebuild it after modifying tractedit_pkg/_numba_aot/build_aot.py. Compiled files are not tracked in git.

Automated Build Checks

GitHub Actions checks Python packaging and tests conversion, metadata, TDI geometry and GUI startup in all four packages. AppImage also receives FUSE, ELF and offline Firejail checks on Ubuntu 22.04/24.04. Only build packages are uploaded; releases are published manually.

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_VERSION_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!

Save and Restore Sessions

Use File → Save Session and Open Session… to save and restore edits, ROIs, selections, filters, undo/redo and views in a .tractedit-session file. Keep the original tractogram, anatomy, parcellation and ODF files: sessions reference them rather than embedding them. If moved, locate the matching sources when prompted.

License

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

Name		Name	Last commit message	Last commit date
.github		.github
sample_data		sample_data
tests		tests
tractedit_pkg		tractedit_pkg
.gitattributes		.gitattributes
.gitignore		.gitignore
CITATION.cff		CITATION.cff
LICENSE		LICENSE
README.md		README.md
_tractedit_build.py		_tractedit_build.py
main.py		main.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
tox.ini		tox.ini

Latest commit

History

Folders and files

Repository files navigation