Warning: This document is for the development version of smriprep. The main version is master.

smriprep.interfaces.surf module

Handling surfaces.

class smriprep.interfaces.surf.AggregateSurfaces(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Aggregate and group surfaces & morphometrics into left/right pairs.

Optional Inputs:

  • morphometrics (a list of items which are a pathlike object or string representing an existing file) – Input morphometrics.

  • surfaces (a list of items which are a pathlike object or string representing an existing file) – Input surfaces.

Outputs:

  • curv (a list of at most 2 items which are a pathlike object or string representing a file) – Curvature maps.

  • inflated (a list of at most 2 items which are a pathlike object or string representing a file) – Inflated surfaces.

  • midthickness (a list of at most 2 items which are a pathlike object or string representing a file) – Midthickness (or graymid) surfaces.

  • pial (a list of at most 2 items which are a pathlike object or string representing a file) – Pial surfaces.

  • sulc (a list of at most 2 items which are a pathlike object or string representing a file) – Sulcal depth maps.

  • thickness (a list of at most 2 items which are a pathlike object or string representing a file) – Cortical thickness maps.

  • white (a list of at most 2 items which are a pathlike object or string representing a file) – White surfaces.

class smriprep.interfaces.surf.FixGiftiMetadata(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Fix known incompatible metadata in GIFTI files.

Currently resolves:

  • FreeSurfer setting GeometryType to Sphere instead of Spherical

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Freesurfer-generated GIFTI file.

Outputs:

out_file (a pathlike object or string representing a file) – Output file with fixed metadata.

class smriprep.interfaces.surf.MakeRibbon(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Create a binary ribbon mask from white and pial distance volumes.

Optional Inputs:

  • pial_distvols (a list of from 2 to 2 items which are a pathlike object or string representing an existing file) – Pial matter distance volumes.

  • white_distvols (a list of from 2 to 2 items which are a pathlike object or string representing an existing file) – White matter distance volumes.

Outputs:

ribbon (a pathlike object or string representing a file) – Binary ribbon mask.

class smriprep.interfaces.surf.NormalizeSurf(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Normalize a FreeSurfer-generated GIFTI image.

FreeSurfer includes volume geometry metadata that serves as an affine transformation to apply to coordinates, which is respected by FreeSurfer tools, but not other tools, in particular the Connectome Workbench. This normalization thus removes the volume geometry, to ensure consistent interpretation of the coordinate locations. This requires that the GIFTI surface be converted with mris_convert --to-scanner, with which FreeSurfer will apply the volume geometry. Because FreeSurfer does not update the metadata, there is no way to detect programmatically how the file was created, and therefore it is the responsibility of the sender to ensure mris_convert --to-scanner was used.

GIFTI files with midthickness/graymid in the name are also updated to include the following metadata entries:

{
    AnatomicalStructureSecondary: MidThickness,
    GeometricType: Anatomical
}

This interface is intended to be applied uniformly to GIFTI surface files generated from the ?h.white/?h.smoothwm and ?h.pial surfaces, as well as externally-generated ?h.midthickness/?h.graymid files. In principle, this should apply safely to any other surface, although it is less relevant to surfaces that don’t describe an anatomical structure.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Freesurfer-generated GIFTI file.

Optional Inputs:

transform_file (a pathlike object or string representing an existing file) – FSL, LTA or ITK affine transform file.

Outputs:

out_file (a pathlike object or string representing a file) – Output file with re-centered GIFTI coordinates.

smriprep.interfaces.surf.fix_gifti_metadata(in_file: str, newpath: str | None = None) → str[source]

Fix known incompatible metadata in GIFTI files.

Currently resolves:

  • FreeSurfer setting GeometryType to Sphere instead of Spherical

smriprep.interfaces.surf.make_ribbon(white_distvols: list[str], pial_distvols: list[str], newpath: str | None = None) → str[source]
smriprep.interfaces.surf.normalize_surfs(in_file: str, transform_file: str | None, newpath: str | None = None) → str[source]

Update GIFTI metadata and apply rigid coordinate correction.

This function removes volume geometry metadata that FreeSurfer includes. Connectome Workbench does not respect this metadata, while FreeSurfer will apply it when converting with mris_convert --to-scanner and then again when reading with freeview.

For midthickness surfaces, add MidThickness metadata