MRtrix 3.0.5 release

Announcements
1

We are pleased to announce the immediate release of MRtrix 3.0.5.

This is a bug fix release – this should not affect ongoing studies, other than in exceptionally rare circumstances. We recommend users upgrade as soon as practical, using the instructions provided on our downloads pages (for precompiled packages), or the usual procedure for installations from source.

See the full changelog below for details.

All the best from the MRtrix3 team!

1 Like
2

Full changelog

Bug fixes

Build

  • configure: strip FSL from PATH
    On many people’s systems, PATH includes the location ${FSLDIR}/bin. It is possible that this may have been due to FreeSurfer configuration, though we have not performed an exhaustive post mortem. This directory however contains a lot more than just FSL commands. Indeed, it includes a compiler and linker, of a specific version in use by FSL. Where this was the case, MRtrix3’s configure would attempt to utilise the compiler and linker bundled with FSL rather than that otherwise expected for the user’s system. This could then lead to various compilation issues. To rectify this, MRtrix3’s configure will now attempt to detect whether the programs it has found in PATH may belong to FSL, and issue a suitable warning.

DICOM

Specific commands

  • dwi2tensor: fix operation with -iter 1
    Previously, if one attempted to do a tensor fit (whether rank 2 or 4), with the default iteratively reweighted least squares, but manually specified -iter 1, then the result would actually be erroneously identical to what is obtained with -iter 0, in that the singular derivation of new weights based on the initial ordinary least squares was not performed.

  • dwifslpreproc: Fix for PE direction, but not readout time, in header
    Makes dwifslpreproc robust in the scenario where the phase encoding information in the image header doesn’t include the total readout time.

  • fod2fixel: Fix -fmls_lobe_merge_ratio
    This option is likely not in use by anybody other than myself, not only because it is esoteric but also because nobody reported the fact that it wasn’t working.

  • mrcalc: Support -config option
    Attempting to use -config option (which is available in all MRtrix3 commands) would fail in mrcalc because it by necessity handles the user’s command-line inputs differently.

  • mrview: fix tsf custom colour
    Fixes attempting to colour a tractogram using a TSF but with a fixed colour rather than a colour map.

  • population_template: Fix aggregation weights import
    Aggregation weights can be utilised to produce a template that is suitably unbiased by modulating the contribution of each image to the template instead of selecting a strict subset of such. The functionality was however broken.

  • tckmap: Erroneous streamline upsampling on Mac
    Could have led to memory allocation issues or command stalling.

  • voxel2mesh: Fix -blocky
    If using the blocky option, the output mesh was erroneously duplicating vertices at voxel corners rather than re-using existing ones, and therefore not actually using triangles to form a singular closed surface.

Multiple commands

  • App::get_matches(): Fix buffer overrun
    Fixes a memory issue in the command-line interface parsing code. I have only noticed this causing assertion failures when running in debug mode, and do not recall noticing any erroneous software behaviour arising from it.

  • Python 3.12 compatibility (PR1; PR2)
    A Python module used internally by MRtrix3 was deprecated in Python 3.12, leading to unhanded exceptions. 3.0.5 should work under Python 3.12 without issue.

  • More robust bvecs/bvals compatibility
    There are various circumstances in which communication of bvecs & bvals data between MRtrix3 and FSL could fail. This includes vectors with [0 0 0] direction (which MRtrix3 handles as best it can but FSL may not like), and FSL tools giving NaN vectors for b=0 images. A set of changes should hopefully make this more robust in both directions.
    (Thanks @araikes for report!)

  • DWI metadata fixes
    There are multiple types of metadata in DWI that embed orientation information. This includes acquisition details such as slice encoding direction, phase encoding direction, slice timing, diffusion sensitisation direction. We additionally represent fibre orientation estimates in various ways; and we encode this information in different ways; and we apply myriad manipulations to those data and presume that this information remains faithful. And also MRtrix3 will interpret some images differently to the way in which they are stored on disk. It is therefore somewhat predictable that there are ways in which this can go wrong.
    I was forced to invest an insane amount of effort in acquiring data and devising a test suite so that I could properly diagnose exactly those circumstances in which MRtrix3 corrupts such data. You can see those efforts at this repository.
    They key use cases where 3.0.4 and earlier were at risk of corrupting one or more of these pieces of metadata, which should now be rectified:

    • Anyone using RealignTransform: false in their configuration file.
    • Acquisitions that are approximately sagittal.
    • Any analysis that relies on interpretation of relative timing of slices between volumes.
      (In some scenarios the slice order was erroneously reversed; this shouldn’t be consequential for FSL eddy since it models within-volume motion independently per volume, and so the motion estimates should just be reversed and inconsistent between volumes but nevertheless corrected appropriately)

  • Fix tck writer when a single streamline exceeds the buffer size
    In the exceptionally abnormal use case where a single streamline was more than 16MB in size, a memory error would occur.
    (Thanks @FEHildesheim for report!)

  • Tolerance for dw_scheme differences on header merge
    If running a command that combines multiple input images, where the diffusion gradient tables are almost but not quite identical (eg. maybe one has undergone some operation that has degraded floating-point precision), previously the whole gradient table would be discarded; now it should be preserved.

  • PNG: Fix check for too few axes, memory, orientations
    MRtrix3 commands can handle PNG images as per any other neuroimaging format. This is most powerful when combined with the multi-file numbered image capability. There were however crashes with certain usages, and the robustness of mapping 3D volumetric axes to 2D image axes was not adequately robust.

  • Fix missing boolean types in full usage
    If anyone out there happens to be making use of the undocumented __print_full_usage__ function, boolean command-line arguments will now be appropriately flagged as such.

  • ProgressBar: Simple update method where stderr is pipe
    The MRtrix3 dynamic progress bars that are emitted by many commands are supposed to be replaced with a much simpler static one whenever that feedback is being sent to something that can’t update dynamically. This was however not working in many instances, leading to text log files with lots of duplication and funny symbols. Hopefully this is now resolved.

  • Mesh::load_vtk() always open files in binary mode
    Fixes loading of VTK files on Windows.

  • Python: show correct version in symlinked scripts
    In particular fixes the version reported in the help page on Mac.

Containers

Documentation

Refinements

Build

DICOM handling

Specific commands

Multiple commands

  • fsl.check_first(): Refine
    Python scripts that internally execute FSL’s run_first_all should now do a better job of detecting when FIRST has completed execution in order to check whether all requested sub-cortical structures were segmented successfully, including if SGE is utilised.
    (Thanks Matthew Glasser for report & testing!)

  • Pipe image format: Revise error message
    Gives a (hopefully) more interpretable error message for the command attempting to send data down a pipe if that piped image cannot be suitably received.

  • Python: Include full commands in log file
    The log file created in the scratch directory of every MRtrix3 Python script will now show the full command executed in those scenarios where the feedback provided to the user at the terminal is simplified.

  • Python: tweak execute to work with VS Code

  • VTK surface format changes

    • Binary VTK exports will now default to single-precision rather than double-precision, halving file size.
    • Binary VTK exports will now be big-endian regardless of system; this is a not-well-documented expectation of that format.
    • VTK import should now be more robust to endianness of input data.

    (Thanks @neurolabusc for report!)

  • WSL: Delayed writeback to host
    If running MRtrix3 in WSL, and writing an output image to a host Windows system drive rather than the WSL container, then MRtrix3 will now use the same process as what it does for network file systems (since that’s essentially what WSL is doing): the output image will be created in RAM, and only written to the output file system at completion. This should be faster, but comes at the expense that attempting to handle images that are larger than your system’s free memory could become problematic.

Other

1 Like