TractEdit v3.4.5

TractEdit v3.4.5 (April 8, 2026)

---

Key Features

• Streamline Selection Decoupled from Undo/Redo: Removed SELECTION_CHANGE from the ActionType enum and its dispatch branches in perform_undo() and perform_redo(), so sphere selection changes (S / Shift+S) no longer occupy undo/redo slots. Removed save_selection_change_for_undo(), _undo_selection_action(), and _redo_selection_action() from StateManager, and removed the two save_selection_change_for_undo() calls in SelectionManager.apply_selection(), making streamline highlighting purely transient with no stack side effects.
• Lowered Auto-Skip Threshold: Reduced AUTO_SKIP_THRESHOLD from 250,000 to 150,000 streamlines in utils.py, activating skip protection earlier for large tractograms.
• Unified Skip-Force Boundary: Unified the skip-force boundary to >= across both _should_force_auto_skip_for_undo_redo() (state_manager) and _apply_filters_with_skip_protection() (roi_manager), ensuring consistent behaviour on undo, ROI mode changes, ROI removal, and clear-all-ROIs. _auto_calculate_skip_level() is now called only for tractograms at or above the threshold on undo; for smaller tractograms the user's skip preference is preserved and skip is not recalculated.

---

Bug Fixes

• Fixed ROI drawing in sphere and rectangle modes where the mouse release event was not properly detected by the interactor's OnLeftButtonUp handler, causing the ROI to drag indefinitely when the cursor was still held at finalization.
• Fixed ROI drawing cleanup and mode-switching issues when transitioning between sphere and rectangle drawing modes.
• Added isinstance(act, vtk.vtkProp) guards to all four actor-handling methods to skip metadata entries stored alongside actual actors.
• Fixed stale inversion state bleeding between TRX file sessions: _close_bundle() and on_finished() now reset _inversion_active, _inversion_keeper_indices, and remove the cyan contour actor from the VTK scene before loading new data.
• Removed dead if self.tractogram_data: block from _trigger_load_streamlines() that incorrectly cleared ROI states and reset _skip_user_disabled on cancelled load operations; all post-load state setup is now handled exclusively by on_finished().

---

Testing

• Updated test_state_manager.py to reflect the new 150K threshold and >= semantics: the "small" boundary test uses range(149999) and the "large" boundary test uses range(150000).

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.

TractEdit v3.3.0

TractEdit v3.3.0 (January 13, 2026)

---

Key Features

• Smart ROI Auto-fill: Introduced a new Auto-fill capability for Drawing ROIs with persistent state handling in Settings. This allows the application to automatically detect and fill voxel space during the ROI drawing mode.
• Inverse Selection: Implemented functionality to invert the current streamline selection, now accessible via the 'i' keyboard shortcut. This enables rapid exclusion workflows where selecting what you don't want is easier than selecting what you do.

---

Minor Improvements

• Enhanced Menu Navigation: Refactored the main UI navigation by promoting the "Shortcuts" list from the Help submenu to a top-level menu item.

---

Bug Fixes

• Fixed VTK/Qt cleanup conflicts occurring during the application closing phase on MacOS by extending the immediate exit workaround to prevent hangs or crashes.
• Fixed cross-platform path resolution issues affecting the Numba JIT compilation cache, ensuring smoother performance across different operating systems.
• Fixed a bug where the visibility toggle icon failed to render correctly for specific datasets loaded in the Data Panel.
• Fixed spacing and alignment artifacts within the input field of the "Skip" feature.
• Fixed minor graphic artifacts

TractEdit v3.2.5

TractEdit v3.2.5 (January 3, 2026)

Linux Release

TractEdit is now available for Linux as standalone packages!
This release includes official AppImage and .deb package distributions with automatic display server detection—preferring native rendering and gracefully falling back to XCB when needed.

---

Key Features

• Comprehensive Test Suite: Added a full pytest-based test suite with tox.ini configuration, covering 88 tests across the codebase to ensure stability and facilitate future development.
• Startup Performance Optimization: Implemented cache=True for all Numba-decorated functions and added warmup_numba_functions() pre-compilation during app startup (displayed as "Optimizing performance..." on splash screen). This eliminates the ~1-3 second delay previously occurring on first file load, ensuring consistent loading times regardless of file size or load order.
• Poetry for dependencies and build: Switched to Poetry and added a poetry-based lock file. Added a hook file for Pyinstaller to fix a Numpy ImportError during linux build.
• Accelerated Medoid Calculation: Fixed freezing at 40% progress when processing large streamline bundles (50k+) by implementing an approximate medoid algorithm using random sampling. Reduces complexity from O(N²) to O(N×k), cutting distance calculations from 1.25 billion to 75 million and memory usage from 20GB to 600MB for 50k streamlines.
• Optimized Selection Tools: Overhauled streamline selection and deletion performance for sphere tool (s and d shortcuts). Added SelectionManager caching to eliminate O(n log n) re-sorting, JIT-compiled parallel copying, incremental selection tracking via _last_selected_indices, and QTimer-based debouncing via schedule_highlight_update() to batch rapid selections into single actor rebuilds.
• Batch Parallel Resampling: Added _resample_batch_numba function that processes all streamlines simultaneously using Numba prange, replacing the sequential Python loop for ~10-20x speedup during medoid resampling phase.
• ODF Tunnel View: Added a new ODF tunnel visualization in the data panel, including right-click context menu options to show or hide it.
• Interactive 2D Ruler: Added a zoom-based ruler overlay to all 2D panels for precise measurement reference.
• Theme Support: Added a "Settings" menu with Light, Dark, and System theme options.

---

Minor Improvements

• Added CLI option --load-roi to load a ROI file at application startup.
• Added pre-import of nibabel.streamlines and trx.trx_file_memmap modules during splash screen to eliminate first-bundle loading delay.
• Added cache=True to ROI intersection Numba function in roi_manager.py to prevent recompilation on every app restart.
• Added warmup_selection_numba_functions() to pre-compile sphere/box selection Numba functions during startup.
• Added invalidate_visible_cache() method to allow external callers to force cache rebuilds upon visibility changes.
• Added PEP8-compliant comment blocks throughout the main sections of the codebase.
• Added documentation comments regarding anatomical image flip corrections to enforce radiological convention over the neurological convention (VTK/Fury default).

---

Bug Fixes

• Fixed a segmentation fault (core dump) on Linux occurring during application shutdown.
• Fixed a bug related to loading uint8 or uint16 ROI data.
• Fixed issues with very high-resolution (100µm) anatomical images and improved downsampling quality.
• Fixed a bug preventing the reset of drawing modes after replacing an anatomical image.
• Fixed a bug affecting sphere ROI drawing in the sagittal view.
• Fixed a color change issue occurring when 3 is pressed without a loaded or drawn ROI image.
• Fixed inverted Yes/No button placement in the "Close App" and "Replace Image" dialogs.

TractEdit v3.0.1

TractEdit v3.0.1 (December 23, 2025)

MacOS Release

TractEdit is now available for macOS!
This release includes the first official DMG distribution, built natively for Apple Silicon with full feature parity with the Windows version.

---

Key Features

• Core Architecture & Standard Workflow: Performed a comprehensive refactoring of the main code structure to support the full standard workflow: whole-brain tractogram analysis, FreeSurfer filtering, and sphere-based selection/refining. Added full support for .vtk and .vtp file formats.
• Deep FreeSurfer Integration: Implemented loading for FreeSurfer parcellations with Numba-optimized intersection matrix computation. Added vectorized 3D visualization for connected regions with include/exclude filtering effects and input toggles.
• Advanced Interactive ROIs: Introduced interactive Sphere and Rectangle ROI tools with full 2D/3D synchronization and modifier keys for precise resizing, moving, and placing. Users can now load existing ROIs, modify them using new drawing tools (pencil, rubber, brush), and save the changes.
• Performance & Headless Operations: Added a "Faster Render" mode for massive speed increases during 3D movement and Numba-optimized algorithms for medoid calculation (10x speedup), narrow-phase ROI intersection, and sphere selection. Implemented a full suite of CLI flags (--convert-to, --density-map, --anat, --roi, --radius, --version, --help) for headless operations.

---

Minor Improvements

• Added an HTML viewer export function with compressed streamlines.
• Implemented a "Replace Bundle" functionality to swap datasets without clearing the T1w reference.
• Added a hidden toolbar menu for sphere radius that appears only in sphere mode.
• Enabled drag-and-drop interaction for 2D ROI elements and shortcuts (1-4) for tool selection.
• Optimized format conversion during saving to maximize header preservation using T1w metadata.
• Improved loading logic to allow T1w image loading before the bundle.
• Massively improved the speed, accuracy, and stability of ROI movements.
• Fixed rendering failures for specific bundles by casting TRX float16 streamlines to float32.
• Fixed bottlenecks during ROI rasterization in high-resolution images.
• Fixed ROI filtering issues in axial/coronal panels and data panel debouncing.
• Fixed ROI loading representation as 3D contours and sphere resize/move interaction bugs.
• Removed unused and debugging wrapper functions.

TractEdit v2.1.5

TractEdit v2.1.5 (December 11, 2025)

Key Features

• High-Performance Core Refactoring: Refactored the streamline rendering and selection logic to replace iterative Python loops with vectorized VTK and NumPy operations. Selection now uses a high-performance vectorized approach with pre-calculated bounding boxes (optimized via Numba jIT), allowing the tool to query 100% of the dataset instantly and decoupling selection accuracy from the visual rendering stride.
• Asynchronous I/O & Memory Optimization: Refactored file I/O to use asynchronous loading with QThread, moving heavy file reading and processing off the main GUI thread. Enforced float32 precision for streamline data.
• Advanced Visualization: Implemented support for ODF/Glyph visualization mapped to the single bundle and added a new mode for rendering streamlines as tubes.
• Density Map (TDI): Implemented the ability to generate and save a Density Map (TDI) of the currently edited bundle directly from the interface.

Minor improvements

• Overhauled the scalar data visualization pipeline to explicitly strip alpha channels and use a robust vectorized method for mapping single-value metrics to vertices.
• Optimized ROI processing using a broad-phase box filter to rapidly filter streamlines.
• Implemented an opacity slider bar for all data types in the data panel.
• Improved UX with better highlighting of selected data names in the data panel and progress bars.
• Added a comprehensive list of keyboard shortcuts to the Help menu.
• Fixed scalar data per-vertex mapping in .trx bundles.
• Fixed bugs preventing the switch between different scalar views or color schemes.
• Fixed XCB compatibility issues for Linux systems.
• Fixed bugs associated with the "Clear All" function.

TractEdit v2.1.0

TractEdit v2.1.0 (December 7, 2025)

Key Features

• Whole-Brain Tractogram Support: Enabled support for whole-brain tractogram (tested with 2 million SIFT2 streamlines) and optimized rendering for large datasets using stride-based visualization to avoid processing the entire dataset.
• Improved Rendering: Implemented a toggleable skip rendering feature with an internal feature that automatically calculates the optimal skip percentage based on streamline count to ensure fluid performance.
• Startup Optimization: Introduced a logo splash screen with a loading indicator to defer heavy imports, significantly improving the perceived startup speed of the application.
• Progress Feedback: Integrated a cancelable progress dialog during bundle loading and an embedded progress bar in the 3D viewport for heavy operations (e.g., ROI inclusion/exclusion in whole-brain tractograms) to prevent interface freezing.

Minor improvements

• Refactored the library import sequence to optimize application load times.
• Disabled the legacy VTK-based level-of-detail system in favor of the new skip rendering feature.
• Replaced .ico and .png logo files
• Fixed scaling issues with the application icon on Windows platforms.
• Fixed a visual bug in loading ROI

TractEdit v2.0.1

TractEdit v2.0.1 (December 6, 2025)

Key Features

• ROI Filters: Implemented support for multiple independent Region of Interest (ROI) images (.nii/.nii.gz) in separate layers, including multi-selection loading. Introduced a logical filtering system with right-click options: View-only, Select, Include, and Exclude.
• Data Panel: Implemented a vertical data panel to control options, information, visibility, and features of anatomical images and tractograms, as well as the ROI-based filtering system.
• Centroid/Medoid: Implemented functionalities to calculate the centroid and/or the medoid of the edited bundle (with a safety limit for tractograms >100k streamlines and a progress bar with cancellation option).
• Sphere optimized: Optimized the sphere-based streamline selection and deletion, using bounding box and segment intersection.

Minor improvements

• Added an interactive RAS coordinate bar at the right-bottom of the main window.
• Improved affine transformations to preserve voxel resolution.
• Implemented persistent (sustained) zoom in 2D panels, and right-click "Reset Zoom" option.
• Added hover tooltips providing details on loaded data in the data panel.
• Added a "Clear All" button.
• Refactored parse_numeric_tuple_from_string and other helper functions to improve readability.
• Replaced standard print statements with a structured logging system.
• Fixed a bug causing the crosshair to disappear in the 2D sagittal plane panel when navigating the right hemisphere.
• Fixed the Anterior-Posterior labels in the 2D sagittal plane.
• Fixed greyscale color flickering issues.
• Fixed visual bugs related to ROI spatial mapping.
• Fixed flickering artifacts while moving the crosshair between slices.
• Updated the application icon.

TractEdit v1.3.0

TractEdit v1.3.0 (November 6, 2025)

This release introduces major architectural changes, implementing a multi-view orthogonal visualization, and enhancing memory efficiency for managing streamline data.

Key Features

• Multi-View Visualization: Implemented a new multi-window layout that includes a main 3D view and three orthogonal 2D slice views (Axial, Coronal, Sagittal) for displaying anatomical images.
• Interactive Slice Navigation: Enabled mouse-based (click-drag) and keyboard-based navigation (Up/Down, Ctrl+Up/Ctrl+Down, Left/Right) within the 2D views to change slice positions.
• Scalar Colormap Control: Added a dedicated toolbar with sliders and spinboxes to dynamically adjust the minimum and maximum display range of the colormap when coloring streamlines by scalar data.
• Fine Streamline Selection: Improved the precision of the sphere-based streamlines selection

Architectural & Code Improvements

• Non-Destructive Editing: Refactored the core data model in file_io.py and main_window.py to use a persistent streamline data object (tractogram_data) and a separate set of visible_indices. This allows deletions, undo/redo, and saving to be performed without modifying the original data structure, improving memory efficiency for large datasets.
• Code Quality: Replaced the bash script with a .toml file, added Python type hints across the modules.
• UI/Rendering: Added a persistent 3D orientation cube, 2D orientation labels, and dynamic 2D crosshair to aid spatial context.

TractEdit v1.2.1

TractEdit v1.2.1 (November 5, 2025)

This release provides fix for the color modes, set the color mode by orientation as default, and min/max toolbars to adjust scalar values visualization.

• Scalar mode: Adjust values by min/max toolbars;
• Bug fix: Resolved issues with scalar values handler
• Color mode by orientation: Set color by orientation as default mode