TractEdit v3.4.0

TractEdit v3.4.0 (March 28, 2026)

---

Key Features

• Unified RAS+ Coordinate System: Align NIfTI handling by preserving the original coordinate system of the anatomical image; data stays in RAS+ orientation unconditionally, and all radiological display transforms are made unconditional across file_io.py, vtk_panel.py, scene_manager.py, drawing.py, and main_window.py.
• Direct VTK Rendering Pipeline: Bypassed FURY's Python-loop-based actor construction for both line and tube rendering modes. A new direct VTK polydata builder combined with vectorized scatter-gather extraction operates only on the rendered subset, eliminating the dominant source of post-load latency on large whole-brain datasets.
• Sphere Selection Redesign: Replaced the ambiguous selection toggle with two explicit modes — S to add streamlines, Shift+S to remove streamlines. Both operations are fully undoable and redoable via Ctrl+Z/Ctrl+Y using lightweight delta-based records that store only the changed index sets.
• Shift+Scroll Slice Navigation: Added slice-by-slice anatomical navigation by holding Shift and scrolling on any 2D panel. The panel under the cursor determines which axis is affected (axial, coronal, or sagittal), while existing scroll zoom and Ctrl+scroll sphere radius adjustment remain unchanged.
• TRX Native Save & Bbox Caching: Added a fast TRX save path that bypasses the nibabel round-trip, with automatic fallback on failure. TRX files saved by TractEdit now embed cached bounding boxes, skipping recomputation on subsequent loads.
• Whole-Brain Memory Safety: Added stride pre-calculation guards across undo, delete, inversion, ROI clearing, and parcellation clearing operations to prevent RAM exhaustion on large whole-brain tractograms. A 200K highlight cap protects against process crashes during selection inversion.

---

Performance Improvements

• Numba AOT Compilation: Replaced Numba JIT with Ahead-Of-Time compilation across 12 numerical kernels and the startup phase.
• Parallel Startup Preloading: Parallelized library preloading during splash screen across two import lanes (VTK+FURY and Nibabel+TRX+SciPy), significantly reducing cold-start wall time.
• PEP 517 Build Backend: Replaced the build backend with a custom wrapper around poetry-core that ensures AOT compilation runs automatically during pip install, fixing the silent skip caused by the Poetry-only build hook.
• Rebuild Guard: Added a monotonic visibility version counter with cached fingerprint state, eliminating redundant VTK actor destroy-and-rebuild cycles on defensive calls.
• Binary Search Resampling: Replaced O(n) linear scans with O(log n) binary search in streamline resampling.
• Batched Medoid Computation: Rewritten medoid distance computation with 5K-row batched processing, cancellation checkpoints, and raised exact-medoid threshold from 8K to 20K streamlines.
• Vectorized VTK/VTP Loading: Replaced the Python cell-parsing loop for .vtk/.vtp loading with VTK 9.x vectorized CSR API and continuous progress feedback.
• ODF Tunnel Optimization: Added a lower-resolution display sphere for ODF tunnel rendering, achieving a 4× polygon reduction and improving 3D rotation responsiveness. Set StaticOn() on the ODF actor mapper to enable VTK internal optimizations.
• O(N_selected) Data Extraction: Optimized selection-highlight and narrow-phase candidate extraction to operate on O(N_selected) data instead of converting the entire tractogram buffer.

---

Minor Improvements

• 3D Camera Initialization: Added automatic camera centering and anterior-facing coronal view after anatomical image loading.
• CLI Anatomical Loading Feedback: Added progress dialog for anatomical image loading via the --anat CLI flag, matching the behavior of the menu-driven loader.
• Optimized Signal Dispatch: Added @pyqtSlot decorators to signal handler methods for optimized PyQt signal dispatch.
• SH Migration: Migrated scipy.special.sph_harm to sph_harm_y with corrected argument ordering and a numerical regression test.
• Data Panel Refactor: Refactored the data panel update logic into 7 focused sub-modules.
• MainWindow Initialization: Added 76 attribute initializations to MainWindow covering previously deferred state.
• Dependency Cleanup: Removed unused pytz dependency.
• Documentation: Added GitHub Code-Graph-RAG visualization in README.

---

Bug Fixes

• Fixed default brightness of anatomical images.
• Fixed missing progress bar during CLI-initiated anatomical image loading.
• Fixed orientation cube disappearing when pressing I to invert selection.
• Fixed undo of whole-brain tractogram restoring at stride=1, risking RAM exhaustion.
• Fixed render stride remaining inflated after large invert-delete operations.
• Fixed bundles failing to render when the skip-disabled flag carried over from a previous session.
• Fixed signal cascade in the data panel caused by unchecked setChecked() calls.
• Fixed unsafe ast.literal_eval() usage; replaced with safe manual string parsing.
• Fixed silent startup failures from uninitialized parcellation state variables.
• Replaced bare except blocks with specific exception types and debug logging across 10 files (~40 instances).
• Added null-safe interactor checks and thread-safe pool creation with clean shutdown handling.
• Added bounds validation for VTK cell sizes on corrupted files and user-facing error dialog for singular affine matrices.
• Added cooperative cancellation to StreamlineLoaderThread, replacing unsafe QThread.terminate() to prevent resource leaks.

---

Testing

• Added 39 test scripts covering undo/redo, selection, filters, parcellation, and stack limits.
• Added 7 pytest scripts for AOT-compiled kernels.
• Added 15 unit tests for TRX bbox cache integrity and 7 for TRX native save.
• Added 7 unit tests for binary search resampling correctness.