ANTsPy Segmentation Fault in `mask_image` Function

[AlanYWu]

Hi! I am using ANTsPy to register the brain, and I found I keep getting segmentation errors. Below is a reproducible issue report. Thank you!

Issue Description

The ants.mask_image() function causes a segmentation fault on macOS ARM64 (Apple Silicon) when used with certain image data. This issue prevents the use of this function in production workflows.

Environment Information

• Platform: macOS-15.5-arm64-arm-64bit (Apple Silicon)
• Python: 3.10.13 (conda-forge)
• ANTsPy: 0.5.4 (pypi)
• ANTs: 2.6.2 (conda-forge)
• NumPy: 2.0.1 (pypi)
• Matplotlib: 3.10.3 (pypi)

Steps to Reproduce

1. Create a conda environment with ANTsPy:

conda create -n ants python=3.10
conda activate ants
conda install -c conda-forge ants
pip install antspyx

2. Run the provided reproduction script:

python ants_segmentation_fault_with_real_data.py

Expected Behavior

The ants.mask_image() function should apply the mask to the image and return a new masked image without causing a segmentation fault.

Actual Behavior

The function causes a segmentation fault (exit code 139) when called with certain image data, particularly with:

• Large images (1024x512x218)
• Images that have been standardized (origin, spacing, direction modified)
• Specific mask values and parameters

Minimal Reproduction Example

import numpy as np
import ants

# Load and standardize images (this triggers the issue)
fixed_image = ants.image_read("JFRCtemplate2010.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/template/JFRCtemplate2010.nrrd
mask = ants.image_read("'JFRCtempate2010.mask130819_Original.nrrd'") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/combinedIndexFiles/JFRCtempate2010.mask130819_Original.nrrd

# Standardize images
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

# This line causes segmentation fault
masked_image = ants.mask_image(image=fixed_image, mask=mask, level=1, binarize=False)

Workaround

A manual numpy-based masking approach works without issues:

# Manual masking workaround
fixed_np = fixed_image.numpy()
mask_np = mask.numpy()
binary_mask = (mask_np == 1).astype(np.uint8)
masked_np = fixed_np * binary_mask

masked_image = ants.from_numpy(
    masked_np,
    origin=fixed_image.origin,
    spacing=fixed_image.spacing,
    direction=fixed_image.direction
)

Additional Notes

• The issue appears to be specific to certain image properties or sizes
• Simple synthetic data (64x64x32) does not reproduce the issue
• The issue occurs consistently with real neuroimaging data
• All other ANTsPy functions work correctly
• The workaround provides identical functionality without the segmentation fault

Impact

This issue affects users working with neuroimaging data on macOS ARM64 systems, particularly when using the mask_image function in automated workflows or scripts.

Files Attached

• ants_segmentation_fault_with_real_data.py: Complete reproduction script
• ants_segmentation_fault_reproducer.py: Minimal reproduction attempt (doesn't trigger the issue)

Request

Please investigate this segmentation fault and provide a fix for the mask_image function on macOS ARM64 systems. The workaround, while functional, is not ideal for production use.

[AlanYWu]

`#!/usr/bin/env python3
"""
Reproducer for ANTsPy segmentation fault using real data

This script reproduces the segmentation fault using the actual data files
that were causing the issue in the original workflow.
"""

import numpy as np
import ants
import gc

def test_with_real_data():
"""Test with the actual data files that caused the segmentation fault"""
print("Loading real data files...")

# Load the actual files that caused the issue
fixed_image = ants.image_read("JFRCtemplate2010.nrrd")
mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd")

print(f"Fixed image: {fixed_image.shape}, {fixed_image.pixeltype}")
print(f"Mask: {mask.shape}, {mask.pixeltype}")

# Standardize images (as done in the original workflow)
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

print("Images standardized")

# Force garbage collection
gc.collect()

print("\nTesting ants.mask_image() with real data...")
try:
    # This should cause segmentation fault
    masked_image = ants.mask_image(image=fixed_image, mask=mask, level=1, binarize=False)
    print("✓ mask_image completed successfully (unexpected)")
    return True
except Exception as e:
    print(f"✗ mask_image failed with exception: {e}")
    return False

def test_manual_workaround_with_real_data():
"""Test manual workaround with real data"""
print("\nTesting manual workaround with real data...")
try:
# Load and standardize again
fixed_image = ants.image_read("input/JFRCtempate2010.nii.gz")
mask = ants.image_read("input/labels.nii.gz")

    fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
    fixed_image.set_origin((0, 0, 0))
    fixed_image.set_spacing((1.0, 1.0, 1.0))
    fixed_image.set_direction(np.eye(3))
    
    mask = ants.image_clone(mask, pixeltype='unsigned char')
    mask.set_origin((0, 0, 0))
    mask.set_spacing((1.0, 1.0, 1.0))
    mask.set_direction(np.eye(3))
    
    # Manual masking
    fixed_np = fixed_image.numpy()
    mask_np = mask.numpy()
    binary_mask = (mask_np == 1).astype(np.uint8)
    masked_np = fixed_np * binary_mask
    
    masked_image = ants.from_numpy(
        masked_np,
        origin=fixed_image.origin,
        spacing=fixed_image.spacing,
        direction=fixed_image.direction
    )
    
    print("✓ Manual masking completed successfully")
    return True
except Exception as e:
    print(f"✗ Manual masking failed: {e}")
    return False

if name == "main":
print("ANTsPy Segmentation Fault Reproducer (Real Data)")
print("=" * 60)

# Test with real data
result1 = test_with_real_data()

# Test workaround with real data
result2 = test_manual_workaround_with_real_data()

print("\n" + "=" * 60)
print("Summary:")
print(f"- Segmentation fault with real data: {not result1}")
print(f"- Workaround with real data: {result2}")

if not result1:
    print("\nISSUE CONFIRMED: ants.mask_image() causes segmentation fault with real data")
    print("WORKAROUND: Use manual numpy-based masking")
else:
    print("\nNo segmentation fault detected with real data") `

[ntustison]

Thanks for providing a script. I'll defer to @cookpa as he'd probably be the best person to diagnose but I'm able to run your script successfully ("unexpectedly") with a direct GitHub installation on a similar platform:

Loading real data files...
Fixed image: (1024, 512, 218), float
Mask: (1024, 512, 218), float
Images standardized

Testing ants.mask_image() with real data...
✓ mask_image completed successfully (unexpected)

[cookpa]

Thanks for providing a script. I'll defer to @cookpa as he'd probably be the best person to diagnose but I'm able to run your script successfully ("unexpectedly") with a direct GitHub installation on a similar platform:

Loading real data files...
Fixed image: (1024, 512, 218), float
Mask: (1024, 512, 218), float
Images standardized

Testing ants.mask_image() with real data...
✓ mask_image completed successfully (unexpected)

That is unexpected. I can reproduce the segmentation fault on Mac x64 running Python 3.10 and antspyx==0.5.4.

[cookpa]

I think the issue is the static cast in ANTs ReadImage, as discussed in #811.

The seg fault goes away if the input images are float

[cookpa]

@ntustison would you mind sharing more details of your Python version, antspyx version, and system? I'd like to understand how it can work on your system, it suggests some kind of different C++ casting behavior on different platforms.

[ntustison]

Sure

• Apple M3 Max
• Python 3.12
• ANTsPy most up-to-date compiled directly from the repo

Let me know if you need to know anything else.

[cookpa]

I tried Python 3.12 and the current HEAD, I'm still seeing the segfault

% cat script_orig.py 
import numpy as np
import ants

# Load and standardize images (this triggers the issue)
fixed_image = ants.image_read("JFRCtemplate2010.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/template/JFRCtemplate2010.nrrd
mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/combinedIndexFiles/JFRCtempate2010.mask130819_Original.nrrd

# Standardize images
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

# This line causes segmentation fault
masked_image = ants.mask_image(image=fixed_image, mask=mask, level=1, binarize=False)

% python -i script_orig.py 
zsh: segmentation fault  python -i script_orig.py
% python --version
Python 3.12.11

[cookpa]

Here's the executable version that produces the same result.

BTW, the test might not be very informative because the mask "JFRCtempate2010.mask130819_Original.nrrd" doesn't contain a label 1, so the output is a blank image. It would be better to mask by existing label(s).

#!/usr/bin/env python

import numpy as np
import ants
import gc

def test_with_real_data():
    """Test with the actual data files that caused the segmentation fault"""
    print("Loading real data files...")

    # Load the actual files that caused the issue
    fixed_image = ants.image_read("JFRCtemplate2010.nrrd")
    mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd")

    print(f"Fixed image: {fixed_image.shape}, {fixed_image.pixeltype}")
    print(f"Mask: {mask.shape}, {mask.pixeltype}")

    # Standardize images (as done in the original workflow)
    fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
    fixed_image.set_origin((0, 0, 0))
    fixed_image.set_spacing((1.0, 1.0, 1.0))
    fixed_image.set_direction(np.eye(3))

    mask = ants.image_clone(mask, pixeltype='unsigned char')
    mask.set_origin((0, 0, 0))
    mask.set_spacing((1.0, 1.0, 1.0))
    mask.set_direction(np.eye(3))

    print("Images standardized")

    # Force garbage collection
    gc.collect()

    print("\nTesting ants.mask_image() with real data...")
    try:
        # This should cause segmentation fault
        masked_image = ants.mask_image(image=fixed_image, mask=mask, level=1, binarize=False)
        print("✓ mask_image completed successfully (unexpected)")
        return True
    except Exception as e:
        print(f"✗ mask_image failed with exception: {e}")
        return False

def test_manual_workaround_with_real_data():
    """Test manual workaround with real data"""
    print("\nTesting manual workaround with real data...")
    try:
        # Load and standardize again
        fixed_image = ants.image_read("input/JFRCtempate2010.nii.gz")
        mask = ants.image_read("input/labels.nii.gz")

        fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
        fixed_image.set_origin((0, 0, 0))
        fixed_image.set_spacing((1.0, 1.0, 1.0))
        fixed_image.set_direction(np.eye(3))

        mask = ants.image_clone(mask, pixeltype='unsigned char')
        mask.set_origin((0, 0, 0))
        mask.set_spacing((1.0, 1.0, 1.0))
        mask.set_direction(np.eye(3))

        # Manual masking
        fixed_np = fixed_image.numpy()
        mask_np = mask.numpy()
        binary_mask = (mask_np == 1).astype(np.uint8)
        masked_np = fixed_np * binary_mask

        masked_image = ants.from_numpy(
            masked_np,
            origin=fixed_image.origin,
            spacing=fixed_image.spacing,
            direction=fixed_image.direction
        )

        print("✓ Manual masking completed successfully")
        return True
    except Exception as e:
        print(f"✗ Manual masking failed: {e}")
        return False

if __name__ == "__main__":
    print("ANTsPy Segmentation Fault Reproducer (Real Data)")
    print("=" * 60)

    # Test with real data
    result1 = test_with_real_data()

    # Test workaround with real data
    result2 = test_manual_workaround_with_real_data()

    print("\n" + "=" * 60)
    print("Summary:")
    print(f"- Segmentation fault with real data: {not result1}")
    print(f"- Workaround with real data: {result2}")

    if not result1:
        print("\nISSUE CONFIRMED: ants.mask_image() causes segmentation fault with real data")
        print("WORKAROUND: Use manual numpy-based masking")
    else:
        print("\nNo segmentation fault detected with real data")

[cookpa]

Here's a script that produces a non-zero output image. Note I also write out the label image because both images have their headers updated, as in the original code.

The script as written below segfaults for me. @ntustison if you have time, could you run this and look at the output?

import numpy as np
import ants

# Load and standardize images (this triggers the issue)
fixed_image = ants.image_read("JFRCtemplate2010.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/template/JFRCtemplate2010.nrrd
mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/combinedIndexFiles/JFRCtempate2010.mask130819_Original.nrrd

# Standardize images
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

# This line causes segmentation fault
masked_image = ants.mask_image(image=fixed_image, mask=mask, level=(3,25), binarize=False)

ants.image_write(masked_image, "masked_image.nrrd")
ants.image_write(mask, "mask_new_header.nrrd")

If I change

mask = ants.image_clone(mask, pixeltype='unsigned char')

to

mask = ants.image_clone(mask, pixeltype='float')

it works

[ntustison]

Sure.

% cat test2.py    
import numpy as np
import ants

# Load and standardize images (this triggers the issue)
fixed_image = ants.image_read("JFRCtemplate2010.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/template/JFRCtemplate2010.nrrd
mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/combinedIndexFiles/JFRCtempate2010.mask130819_Original.nrrd

# Standardize images
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

# This line causes segmentation fault
masked_image = ants.mask_image(image=fixed_image, mask=mask, level=(3,25), binarize=False)

ants.image_write(masked_image, "masked_image.nrrd")
ants.image_write(mask, "mask_new_header.nrrd")

print("Unexpected success.\n")%                                                                                                                   (antsx) ntustison@shai-hulud Desktop % python3 test2.py
Unexpected success.

[ntustison]

I must have deleted some text. This is a full copy-and-paste:

% cat test2.py    
import numpy as np
import ants

# Load and standardize images (this triggers the issue)
fixed_image = ants.image_read("JFRCtemplate2010.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/template/JFRCtemplate2010.nrrd
mask = ants.image_read("JFRCtempate2010.mask130819_Original.nrrd") # This can be downloaded from https://github.com/VirtualFlyBrain/DrosAdultBRAINdomains/blob/master/combinedIndexFiles/JFRCtempate2010.mask130819_Original.nrrd

# Standardize images
fixed_image = ants.image_clone(fixed_image, pixeltype='unsigned char')
fixed_image.set_origin((0, 0, 0))
fixed_image.set_spacing((1.0, 1.0, 1.0))
fixed_image.set_direction(np.eye(3))

mask = ants.image_clone(mask, pixeltype='unsigned char')
mask.set_origin((0, 0, 0))
mask.set_spacing((1.0, 1.0, 1.0))
mask.set_direction(np.eye(3))

# This line causes segmentation fault
masked_image = ants.mask_image(image=fixed_image, mask=mask, level=(3,25), binarize=False)

ants.image_write(masked_image, "masked_image.nrrd")
ants.image_write(mask, "mask_new_header.nrrd")

print("Unexpected success.\n")%                                                                                                                   (antsx) ntustison@shai-hulud Desktop % python3 test2.py
Unexpected success.

(antsx) ntustison@shai-hulud Desktop % 

[cookpa]

It just got formatted funny (scroll right).

Does the output look OK?

[ntustison]

Oh, I see. Thanks.

Segmentaiton looks fine at quick glance but the other image appears to be all 0s in ITK-SNAP.

[cookpa]

Wow, so it's somehow preventing a segfault but just returning bad data. Scary!