compare_nifti_images#

qx_utilities.general.img.compare_nifti_images(file1, file2, ndifflines=10)#

compare_nifti_images file1=<path to first NIFTI file> file2=<path to second NIFTI file> [ndifflines=10]

Performs a detailed comparison of two NIFTI image files, analyzing their headers, extensions, and data arrays. The comparison is presented in a structured, tabular format highlighting differences.

Parameters

--file1 (str):

The path to the first NIFTI file to compare. Can be .nii or .nii.gz format. Supports both NIfTI-1 and NIfTI-2 formats.

--file2 (str):

The path to the second NIFTI file to compare. Can be .nii or .nii.gz format. Supports both NIfTI-1 and NIfTI-2 formats.

--ndifflines (int, default 10):

Maximum number of diff lines to display when comparing textual extensions. If set to -1, all diff lines are printed. This helps manage output length when extensions have many differences.

Comparison Process:

The function performs comparison in the following order:

  1. File Hash Comparison:

    • Computes SHA-256 hash of both complete files

    • If hashes match, files are identical and comparison stops

    • If hashes differ, proceeds with detailed analysis

  2. Header Comparison:

    • Opens both files and reads NIfTI headers

    • Compares each header field individually

    • Reports field name, value from file1, and value from file2 for any fields that differ

    • Handles both NIfTI-1 (348 byte) and NIfTI-2 (540 byte) headers

  3. Extension Comparison:

    • Compares the number of extensions in each file

    • Identifies extensions present in one file but not the other

    • For matching extension codes:

      • Compares extension hashes (SHA-256)

      • If hashes match, reports extensions as identical

      • If hashes differ and extension is text:

        • Performs line-by-line diff

        • Displays rows that differ between files (limited by ndifflines)

      • If hashes differ and extension is binary:

        • Reports that extensions differ

        • Lists the size of each extension

  4. Data Comparison:

    • Checks if data dimensionality matches (shape of arrays)

    • If dimensions differ, reports the difference

    • If dimensions match:

      • Computes SHA-256 hash over the data arrays

      • Reports whether data is identical or different

      • Does not load entire data into memory for large files

Output Format:

Results are displayed in structured tables using separators and alignment:

  • Section headers clearly mark each comparison stage

  • Differences are shown in columnar format with field names

  • Extension comparisons show code, type, and content differences

  • Visual separators improve readability

Returns

None. Results are printed to standard output.

Notes

  • Supports both compressed (.nii.gz) and uncompressed (.nii) files

  • Handles both NIfTI-1 and NIfTI-2 formats automatically

  • Extension text detection uses UTF-8 decoding; binary extensions are those that cannot be decoded as UTF-8

  • File hashing is performed in chunks to handle large files efficiently

  • Data hashing is also performed in chunks without loading entire arrays into memory

Example Use:
from qx_utilities.general.img import compare_nifti_images
compare_nifti_images('subject1_bold.nii.gz', 'subject2_bold.nii.gz')

compare_nifti_images(
    file1='/data/orig/T1w.nii',
    file2='/data/processed/T1w.nii'
)

# Show all diff lines for text extensions
compare_nifti_images(
    file1='file1.nii',
    file2='file2.nii',
    ndifflines=-1
)