niworkflows.interfaces.surf module¶

Handling surfaces.

class niworkflows.interfaces.surf.CSVToGifti(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Converts CSV files back to GIfTI, after moving vertices with antsApplyTransformToPoints.

Mandatory Inputs:

gii_file (a pathlike object or string representing an existing file) – Reference GIfTI file.
in_file (a pathlike object or string representing an existing file) – CSV file.

Optional Inputs:

itk_lps (a boolean) – Flip XY axes. (Nipype default value: False)

Outputs:

out_file (a pathlike object or string representing a file) – Output GIfTI file.

class niworkflows.interfaces.surf.CreateSurfaceROI(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Prepare GIFTI shape file for use in cortical masking

Distilled from the FreeSurfer2CaretConvertAndRegisterNonlinear.sh script in DCAN-HCP PostFreeSurfer scripts (as of commit 9291324). The relevant lines are 277-290.

Mandatory Inputs:

hemisphere (‘L’ or ‘R’) – Hemisphere.
thickness_file (a pathlike object or string representing an existing file) – Input GIFTI file.

Optional Inputs:

subject_id (a string) – Subject ID.

Outputs:

roi_file (a pathlike object or string representing a file) – Output GIFTI file.

class niworkflows.interfaces.surf.GiftiNameSource(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Construct a new filename for a GIFTI file.

Construct a new filename based on an input filename, a matching pattern, and a related template, with optionally additional keywords.

This interface is intended for use with GIFTI files, to generate names conforming to Section 9.0 of the GIFTI Standard.

Patterns are expected to have named groups, including one named “LR” that matches “l” or “r”. These groups must correspond to named format elements in the template.

Examples

>>> surf_namer = GiftiNameSource()
>>> surf_namer.inputs.pattern = r'(?P<LR>[lr])h.(?P<surf>\w+).gii'
>>> surf_namer.inputs.template = r'{surf}.{LR}.surf'
>>> surf_namer.inputs.in_file = 'lh.pial.gii'
>>> res = surf_namer.run()
>>> res.outputs.out_name
'pial.L.surf'

>>> func_namer = GiftiNameSource()
>>> func_namer.inputs.pattern = r'(?P<LR>[lr])h.(?P<space>\w+).gii'
>>> func_namer.inputs.template = r'space-{space}.{LR}.func'
>>> func_namer.inputs.in_file = 'rh.fsaverage.gii'
>>> res = func_namer.run()
>>> res.outputs.out_name
'space-fsaverage.R.func'

>>> namer = GiftiNameSource()
>>> namer.inputs.pattern = r'(?P<LR>[lr])h.(?P<space>\w+).gii'
>>> namer.inputs.template = r'space-{space}_density-{density}_hemi-{LR}.func'
>>> namer.inputs.in_file = 'rh.fsaverage.gii'
>>> namer.inputs.template_kwargs = {'density': '10k'}
>>> res = namer.run()
>>> res.outputs.out_name
'space-fsaverage_density-10k_hemi-R.func'

>>> import os
>>> os.unlink('lh.pial.gii')
>>> os.unlink('rh.fsaverage.gii')

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input GIFTI file.
pattern (a string) – Input file name pattern (must capture named group “LR”).
template (a string) – Output file name template.

Optional Inputs:

template_kwargs (a dictionary with keys which are any value and with values which are any value) – Additional template keyword value pairs.

Outputs:

out_name (a string) – (partial) filename formatted according to template.

class niworkflows.interfaces.surf.GiftiSetAnatomicalStructure(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Set AnatomicalStructurePrimary attribute of GIFTI image based on filename.

For files that begin with lh. or rh., update the metadata to include:

{
    AnatomicalStructurePrimary: (CortexLeft | CortexRight),
}

If AnatomicalStructurePrimary is already set, this function has no effect.

Mandatory Inputs:: in_file (a pathlike object or string representing an existing file) – GIFTI file beginning with “lh.” or “rh.”.
Outputs:: out_file (a pathlike object or string representing a file) – Output file with updated AnatomicalStructurePrimary entry.

class niworkflows.interfaces.surf.GiftiToCSV(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Converts GIfTI files to CSV to make them ammenable to use with antsApplyTransformsToPoints.

Mandatory Inputs:: in_file (a pathlike object or string representing an existing file) – GIFTI file.
Optional Inputs:: itk_lps (a boolean) – Flip XY axes. (Nipype default value: False)
Outputs:: out_file (a pathlike object or string representing a file) – Output csv file.

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

Bases: SimpleInterface

Normalize a FreeSurfer-generated GIFTI image.

FreeSurfer includes an offset to the center of the brain volume that is not respected by all software packages. Normalization involves adding this offset to the coordinates of all vertices, and zeroing out that offset, to ensure consistent behavior across software packages. In particular, this normalization is consistent with the Human Connectome Project pipeline (see AlgorithmSurfaceApplyAffine and FreeSurfer2CaretConvertAndRegisterNonlinear), although the the HCP may not zero out the offset.

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 or LTA affine transform file.
Outputs:: out_file (a pathlike object or string representing a file) – Output file with re-centered GIFTI coordinates.

class niworkflows.interfaces.surf.PLYtoGifti(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Convert surfaces from PLY to GIfTI

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input PLY file.
surf_key (a string) – Reference GIfTI file.

Outputs:

out_file (a pathlike object or string representing a file) – Output GIfTI file.

class niworkflows.interfaces.surf.Path2BIDS(pattern=None, **inputs)[source]¶

Bases: SimpleInterface

Extract BIDS entities from paths using a pattern.

Default pattern is given for Gifti surfaces.

>>> Path2BIDS(in_file='_fix_surfs0/rh.pial.surf.gii').run().outputs

extension = .surf.gii
hemi = R
suffix = pial

>>> Path2BIDS(in_file='_fix_surfs0/rh.pial.gii').run().outputs

extension = .gii
hemi = R
suffix = pial

>>> Path2BIDS(in_file='_fix_surfs0/rh.smoothwm_converted.gii').run().outputs

extension = .gii
hemi = R
suffix = smoothwm

>>> Path2BIDS(in_file='_fix_surfs0/rh.smoothwm_converted.func.gii').run().outputs

extension = .func.gii
hemi = R
suffix = smoothwm

>>> Path2BIDS(in_file='lh.sulc_converted.gii').run().outputs

extension = .gii
hemi = L
suffix = sulc

Mandatory Inputs:: in_file (a pathlike object or string representing a file) – Input GIFTI file.
Outputs:: extension (a string)

output_spec¶: alias of _Path2BIDSOutputSpec

class niworkflows.interfaces.surf.PoissonRecon(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]¶

Bases: CommandLine

Wrapped executable: PoissonRecon.

Runs Poisson Reconstruction on a cloud of points + normals given in PLY format. See https://github.com/mkazhdan/PoissonRecon

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input PLY pointcloud (vertices + normals). Maps to a command-line argument: --in %s.

Optional Inputs:

args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})
out_file (a pathlike object or string representing a file) – Output PLY triangular mesh. Maps to a command-line argument: --out %s.

Outputs:

out_file (a pathlike object or string representing an existing file) – Output PLY triangular mesh.

class niworkflows.interfaces.surf.SurfacesToPointCloud(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Converts multiple surfaces into a pointcloud with corresponding normals to then apply Poisson reconstruction

Mandatory Inputs:: in_files (a list of items which are a pathlike object or string representing an existing file) – Input GIfTI files.
Optional Inputs:: out_file (a pathlike object or string representing a file) – Output file name. (Nipype default value: pointcloud.ply)
Outputs:: out_file (a pathlike object or string representing a file) – Output pointcloud in PLY format.

class niworkflows.interfaces.surf.UnzipJoinedSurfaces(from_file=None, resource_monitor=None, **inputs)[source]¶

Bases: SimpleInterface

Unpack surfaces by identifier keys

Optional Inputs:

in_files (a list of items which are a list of items which are a pathlike object or string representing an existing file)

Outputs:

out_files (a list of items which are a list of items which are a pathlike object or string representing an existing file)
surf_keys (a list of items which are a string) – Surface identifier keys.

niworkflows.interfaces.surf.get_gii_meta(in_file)[source]¶

niworkflows.interfaces.surf.load_transform(fname)[source]¶

Load affine transform from file

Parameters:: fname (str or None) – Filename of an LTA or FSL-style MAT transform file. If None, return an identity transform
Returns:: affine
Return type:: (4, 4) numpy.ndarray

niworkflows.interfaces.surf.normalize_surfs(in_file, transform_file, newpath=None)[source]¶

Re-center GIFTI coordinates to fit align to native T1w space.

For midthickness surfaces, add MidThickness metadata

Coordinate update based on: https://github.com/Washington-University/workbench/blob/1b79e56/src/Algorithms/AlgorithmSurfaceApplyAffine.cxx#L73-L91 and https://github.com/Washington-University/Pipelines/blob/ae69b9a/PostFreeSurfer/scripts/FreeSurfer2CaretConvertAndRegisterNonlinear.sh#L147

niworkflows.interfaces.surf.ply2gii(in_file, metadata, out_file=None)[source]¶: Convert from ply to GIfTI

niworkflows.interfaces.surf.pointcloud2ply(vertices, normals, out_file=None)[source]¶: Converts the file to PLY format

niworkflows.interfaces.surf.vertex_normals(vertices, faces)[source]¶: Calculates the normals of a triangular mesh