freesurfer / surfa

Python utilities for medical image and surface-based analysis

Surfa

Surfa is a collection of Python utilities for medical image analysis and mesh-based surface processing. It provides tools that operate on 3D image arrays and triangular meshes with consideration of their representation in a world (or scanner) coordinate system. While broad in scope, surfa is developed with particular emphasis on neuroimaging applications. To install, run:

pip install surfa

Note: The above command should run smoothly and require no further steps, but if your system does not have a c compiler installed it will throw an error. To resolve this potential issue, review the suggested steps in the compiling section.

Documentation

The surfa documentation and API reference is currently a work-in-progress, and any additions are welcome. The documentation source code lives under the docs subdirectory.

Development

Pull requests are always welcome! For local development of the codebase, be sure to build the .pyx files in the package before importing:

python setup.py  build_ext --inplace

Feel free to open an issue if you encounter a bug or have a feature request.

Citation

Surfa was originally built in part for the development of learning-based cortical surface reconstruction and it is a derivation of the FreeSurfer software suite. If you find this package useful in your analysis, please cite:

Hoopes et al. "TopoFit: Rapid Reconstruction of Topologically-Correct Cortical Surfaces." Medical Imaging with Deep Learning (2021)

Fischl. "FreeSurfer." NeuroImage vol. 62,2 (2012)

surfa's Issues

Install on windows

Is there any way to install surfa on Windows?

Distribute via conda as well?

Distributing surfa via conda would be cool! — I have surfa as a prerequisite for this project and surfa is the only package that is not conda-installable...

image.conform issue

HI,

I was in the win10 system and tried to conform MRI data with the command:
conformed = image.conform(voxsize=1.0, dtype='float32', method='nearest', orientation='LIA').crop_to_bbox()
Unfortunately, it returned "ValueError: Buffer dtype mismatch, expected 'int_t' but got 'long long'". Did you face this issue before?

Geometry awareness when applying deformations

Right now when applying a displacement field as a transform, like image.transform(disp=disp), the geometry of the displacement is not taken into account, i.e. the transformed output image retains the original geometry of the image. It's probably better to have the output be in the space of the displacement field. So essentially, if disp is a framed image, then we should preprocess either by resampling the source image to disp.geom or by recomputing the displacement vectors to account for the geometry shift. The latter is a better option since it minimizes resampling error. We should prob add a generic function to manipulate warps in this way.

hardcoded pixdim[0] doesn't follow standard

While debugging a different issue I noticed that the output of SynthStrip, which uses surfa internally, wrote out a qform that was inconsistent with the sform (the head was upside-down when using the qform orientation).

This line hardcodes pixdim[0] to be 1:
https://github.com/freesurfer/surfa/blob/master/surfa/io/framed.py#L486

But the nifti header documentation says:

N.B.: Method 2 uses a factor 'qfac' which is either -1 or 1; qfac is
stored in the otherwise unused pixdim[0].

It would be better to write the identical transform to both the qform and sform since it's not always known which one the receiving software will use.

Numpy has no attribute 'int' error during resampling

Looks like numpy got rid of np.int in v1.24.0, so resampling calls might provoke:

AttributeError: module 'numpy' has no attribute 'int'

Quick solution is to downgraded numpy to 1.23.3, but I'll put in a fix soon.