Warning: This document is for an old version of smriprep. The main version is master.

smriprep.interfaces.workbench module

class smriprep.interfaces.workbench.CreateSignedDistanceVolume(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -create-signed-distance-volume.

Create signed distance volume from surface

Computes the signed distance function of the surface. Exact distance is calculated by finding the closest point on any surface triangle to the center of the voxel. Approximate distance is calculated starting with these distances, using dijkstra’s method with a neighborhood of voxels. Specifying too small of an exact distance may produce unexpected results.

The NORMALS winding method uses the normals of triangles and edges, or the closest triangle hit by a ray from the point. This method may be slightly faster, but is only reliable for a closed surface that does not cross through itself. All other methods count entry (positive) and exit (negative) crossings of a vertical ray from the point, then counts as inside if the total is odd, negative, or nonzero, respectively.

Command help string:

CREATE SIGNED DISTANCE VOLUME FROM SURFACE

wb_command -create-signed-distance-volume
   <surface> - the input surface
   <refspace> - a volume in the desired output space (dims, spacing, origin)
   <outvol> - output - the output volume

   [-roi-out] - output an roi volume of where the output has a computed
      value
      <roi-vol> - output - the output roi volume

   [-fill-value] - specify a value to put in all voxels that don't get
      assigned a distance
      <value> - value to fill with (default 0)

   [-exact-limit] - specify distance for exact output
      <dist> - distance in mm (default 5)

   [-approx-limit] - specify distance for approximate output
      <dist> - distance in mm (default 20)

   [-approx-neighborhood] - voxel neighborhood for approximate calculation
      <num> - size of neighborhood cube measured from center to face, in
         voxels (default 2 = 5x5x5)

   [-winding] - winding method for point inside surface test
      <method> - name of the method (default EVEN_ODD)

   Computes the signed distance function of the surface.  Exact distance is
   calculated by finding the closest point on any surface triangle to the
   center of the voxel.  Approximate distance is calculated starting with
   these distances, using dijkstra's method with a neighborhood of voxels.
   Specifying too small of an exact distance may produce unexpected results.
   Valid specifiers for winding methods are as follows:

   EVEN_ODD (default)
   NEGATIVE
   NONZERO
   NORMALS

   The NORMALS method uses the normals of triangles and edges, or the
   closest triangle hit by a ray from the point.  This method may be
   slightly faster, but is only reliable for a closed surface that does not
   cross through itself.  All other methods count entry (positive) and exit
   (negative) crossings of a vertical ray from the point, then counts as
   inside if the total is odd, negative, or nonzero, respectively.
Mandatory Inputs:

  • ref_file (a pathlike object or string representing an existing file) – NIfTI volume in the desired output space (dims, spacing, origin). Maps to a command-line argument: %s (position: 1).

  • surf_file (a pathlike object or string representing an existing file) – Input surface GIFTI file (.surf.gii). Maps to a command-line argument: %s (position: 0).

Optional Inputs:

  • approx_limit (a float) – Distance for approximate output in mm. Maps to a command-line argument: -approx-limit %f. (Nipype default value: 20.0)

  • approx_neighborhood (an integer) – Size of neighborhood cube measured from center to face in voxels, default 2 = 5x5x5. Maps to a command-line argument: -approx-neighborhood %d. (Nipype default value: 2)

  • 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: {})

  • exact_limit (a float) – Distance for exact output in mm. Maps to a command-line argument: -exact-limit %f. (Nipype default value: 5.0)

  • fill_value (a float) – Value to put in all voxels that don’t get assigned a distance. Maps to a command-line argument: -fill-value %f. (Nipype default value: 0.0)

  • out_file (a pathlike object or string representing a file) – Name of output volume containing signed distances. Maps to a command-line argument: %s (position: 2).

  • out_mask (a pathlike object or string representing a file) – Name of file to store a mask where the out_file has a computed value. Maps to a command-line argument: -roi-out %s.

  • winding_method (‘EVEN_ODD’ or ‘NEGATIVE’ or ‘NONZERO’ or ‘NORMALS’) – Winding method for point inside surface test. Maps to a command-line argument: -winding %s. (Nipype default value: EVEN_ODD)

Outputs:

  • out_file (a pathlike object or string representing a file) – Name of output volume containing signed distances.

  • out_mask (a pathlike object or string representing a file) – Name of file to store a mask where the out_file has a computed value.

class smriprep.interfaces.workbench.SurfaceAffineRegression(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-affine-regression.

REGRESS THE AFFINE TRANSFORM BETWEEN SURFACES ON THE SAME MESH

wb_command -surface-affine-regression

<source> - the surface to warp <target> - the surface to match the coordinates of <affine-out> - output - the output affine file

Use linear regression to compute an affine that minimizes the sum of squares of the coordinate differences between the target surface and the warped source surface. Note that this has a bias to shrink the surface that is being warped. The output is written as a NIFTI ‘world’ matrix, see -convert-affine to convert it for use in other software.

>>> sar = SurfaceAffineRegression()
>>> sar.inputs.in_surface = 'sub-01_hemi-L_sulc.shape.gii'
>>> sar.inputs.target_surface = 'tpl-fsaverage_hemi-L_den-164k_sulc.shape.gii'
>>> sar.cmdline  
'wb_command -surface-affine-regression     sub-01_hemi-L_sulc.shape.gii     tpl-fsaverage_hemi-L_den-164k_sulc.shape.gii     sub-01_hemi-L_sulc.shape_xfm'
Mandatory Inputs:

  • in_surface (a pathlike object or string representing an existing file) – Surface to warp. Maps to a command-line argument: %s (position: 0).

  • target_surface (a pathlike object or string representing an existing file) – Surface to match the coordinates of. Maps to a command-line argument: %s (position: 1).

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_affine (a pathlike object or string representing a file) – The output affine file. Maps to a command-line argument: %s (position: 2).

Outputs:

out_affine (a pathlike object or string representing a file) – The output affine file.

class smriprep.interfaces.workbench.SurfaceApplyAffine(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-apply-affine.

APPLY AFFINE TRANSFORM TO SURFACE FILE

wb_command -surface-apply-affine

<in-surf> - the surface to transform <affine> - the affine file <out-surf> - output - the output transformed surface

[-flirt] - MUST be used if affine is a flirt affine

<source-volume> - the source volume used when generating the affine <target-volume> - the target volume used when generating the affine

For flirt matrices, you must use the -flirt option, because flirt matrices are not a complete description of the coordinate transform they represent. If the -flirt option is not present, the affine must be a nifti ‘world’ affine, which can be obtained with the -convert-affine command, or aff_conv from the 4dfp suite.

>>> np.savetxt('affine.txt', np.eye(4), delimiter=' ')



>>> saa = SurfaceApplyAffine()
>>> saa.inputs.in_surface = 'sub-01_hemi-L_sphere.surf.gii'
>>> saa.inputs.in_affine = 'affine.txt'
>>> saa.cmdline  
'wb_command -surface-apply-affine     sub-01_hemi-L_sphere.surf.gii     affine.txt     sub-01_hemi-L_sphere.surf_xformed.surf.gii'

>>> os.unlink('affine.txt')
Mandatory Inputs:

  • in_affine (a pathlike object or string representing an existing file) – The affine file. Maps to a command-line argument: %s (position: 1).

  • in_surface (a pathlike object or string representing an existing file) – The surface to transform. Maps to a command-line argument: %s (position: 0).

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: {})

  • flirt_source (a pathlike object or string representing an existing file) – Source volume (must be used if affine is a flirt affine). Maps to a command-line argument: -flirt %s (position: 3). Requires inputs: flirt_target.

  • flirt_target (a pathlike object or string representing an existing file) – Target volume (must be used if affine is a flirt affine). Maps to a command-line argument: %s (position: 4). Requires inputs: flirt_source.

  • out_surface (a pathlike object or string representing a file) – The output transformed surface. Maps to a command-line argument: %s (position: 2).

Outputs:

out_surface (a pathlike object or string representing a file) – The output transformed surface.

class smriprep.interfaces.workbench.SurfaceApplyWarpfield(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-apply-warpfield.

APPLY WARPFIELD TO SURFACE FILE

wb_command -surface-apply-warpfield

<in-surf> - the surface to transform <warpfield> - the INVERSE warpfield <out-surf> - output - the output transformed surface

[-fnirt] - MUST be used if using a fnirt warpfield

<forward-warp> - the forward warpfield

NOTE: warping a surface requires the INVERSE of the warpfield used to warp the volume it lines up with. The header of the forward warp is needed by the -fnirt option in order to correctly interpret the displacements in the fnirt warpfield.

If the -fnirt option is not present, the warpfield must be a nifti ‘world’ warpfield, which can be obtained with the -convert-warpfield command.

>>> saw = SurfaceApplyWarpfield()
>>> saw.inputs.in_surface = 'sub-01_hemi-L_sphere.surf.gii'
>>> saw.inputs.warpfield = 'sub-01_desc-warped_T1w.nii.gz'
>>> saw.cmdline  
'wb_command -surface-apply-warpfield     sub-01_hemi-L_sphere.surf.gii     sub-01_desc-warped_T1w.nii.gz     sub-01_hemi-L_sphere.surf_warped.surf.gii'
Mandatory Inputs:

  • in_surface (a pathlike object or string representing an existing file) – The surface to transform. Maps to a command-line argument: %s (position: 0).

  • warpfield (a pathlike object or string representing an existing file) – The INVERSE warpfield. Maps to a command-line argument: %s (position: 1).

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: {})

  • fnirt_forward_warp (a pathlike object or string representing an existing file) – The forward warpfield (must be used if fnirt warpfield). Maps to a command-line argument: -fnirt %s (position: 3).

  • out_surface (a pathlike object or string representing a file) – The output transformed surface. Maps to a command-line argument: %s (position: 2).

Outputs:

out_surface (a pathlike object or string representing a file) – The output transformed surface.

class smriprep.interfaces.workbench.SurfaceModifySphere(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-modify-sphere.

CHANGE RADIUS AND OPTIONALLY RECENTER A SPHERE

wb_command -surface-modify-sphere

<sphere-in> - the sphere to modify <radius> - the radius the output sphere should have <sphere-out> - output - the output sphere

[-recenter] - recenter the sphere by means of the bounding box

This command may be useful if you have used -surface-resample to resample a sphere, which can suffer from problems generally not present in -surface-sphere-project-unproject. If the sphere should already be centered around the origin, using -recenter may still shift it slightly before changing the radius, which is likely to be undesirable.

If <sphere-in> is not close to spherical, or not centered around the origin and -recenter is not used, a warning is printed.

>>> sms = SurfaceModifySphere()
>>> sms.inputs.in_surface = 'sub-01_hemi-L_sphere.surf.gii'
>>> sms.inputs.radius = 100
>>> sms.cmdline  
'wb_command -surface-modify-sphere     sub-01_hemi-L_sphere.surf.gii 100 sub-01_hemi-L_sphere.surf_mod.surf.gii'
Mandatory Inputs:

  • in_surface (a pathlike object or string representing an existing file) – The sphere to modify. Maps to a command-line argument: %s (position: 0).

  • radius (an integer) – The radius the output sphere should have. Maps to a command-line argument: %d (position: 1).

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_surface (a pathlike object or string representing a file) – The modified sphere. Maps to a command-line argument: %s (position: 2).

  • recenter (a boolean) – Recenter the sphere by means of the bounding box. Maps to a command-line argument: -recenter (position: 3).

Outputs:

out_surface (a pathlike object or string representing a file) – The modified sphere.

class smriprep.interfaces.workbench.SurfaceResample(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-resample.

RESAMPLE A SURFACE TO A DIFFERENT MESH.

Example

>>> from smriprep.interfaces.workbench import SurfaceResample
>>> surface_resample = SurfaceResample()
>>> surface_resample.inputs.surface_in = 'sub-01_hemi-L_midthickness.surf.gii'
>>> surface_resample.inputs.current_sphere = 'sub-01_hemi-L_sphere.surf.gii'
>>> surface_resample.inputs.new_sphere = 'tpl-fsLR_hemi-L_den-32k_sphere.surf.gii'
>>> surface_resample.inputs.method = 'BARYCENTRIC'
>>> surface_resample.cmdline  
'wb_command -surface-resample sub-01_hemi-L_midthickness.surf.gii     sub-01_hemi-L_sphere.surf.gii tpl-fsLR_hemi-L_den-32k_sphere.surf.gii     BARYCENTRIC sub-01_hemi-L_midthickness.surf_resampled.surf.gii'
Mandatory Inputs:

  • current_sphere (a pathlike object or string representing an existing file) – A sphere surface with the mesh that the input surface is currently on. Maps to a command-line argument: %s (position: 1).

  • method (‘ADAP_BARY_AREA’ or ‘BARYCENTRIC’) – The method name. Maps to a command-line argument: %s (position: 3).

  • new_sphere (a pathlike object or string representing an existing file) – A sphere surface that is in register with <current-sphere> and has the desired output mesh. Maps to a command-line argument: %s (position: 2).

  • surface_in (a pathlike object or string representing an existing file) – The surface file to resample. Maps to a command-line argument: %s (position: 0).

Optional Inputs:

  • correction_source (‘area_surfs’ or ‘area_metrics’) – Specify surfaces or vertex area metrics to do vertex area correction based on. Maps to a command-line argument: -%s (position: 5).

  • current_area (a pathlike object or string representing an existing file) – A relevant surface with <current-sphere> mesh. Maps to a command-line argument: %s (position: 6). Requires inputs: correction_source.

  • new_area (a pathlike object or string representing an existing file) – A relevant surface with <new-sphere> mesh. Maps to a command-line argument: %s (position: 7). Requires inputs: correction_source.

  • surface_out (a string or os.PathLike object) – The output surface file. Maps to a command-line argument: %s (position: 4).

Outputs:

surface_out (a pathlike object or string representing a file) – The output surface file.

class smriprep.interfaces.workbench.SurfaceSphereProjectUnproject(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -surface-sphere-project-unproject.

COPY REGISTRATION DEFORMATIONS TO DIFFERENT SPHERE.

Example

>>> from smriprep.interfaces.workbench import SurfaceSphereProjectUnproject
>>> sphere_project = SurfaceSphereProjectUnproject()
>>> sphere_project.inputs.sphere_in = 'sub-01_hemi-L_sphere.surf.gii'
>>> sphere_project.inputs.sphere_project_to = 'tpl-fsLR_hemi-L_den-32k_sphere.surf.gii'
>>> sphere_project.inputs.sphere_unproject_from = 'lh.sphere.reg.surf.gii'
>>> sphere_project.cmdline  
'wb_command -surface-sphere-project-unproject sub-01_hemi-L_sphere.surf.gii     tpl-fsLR_hemi-L_den-32k_sphere.surf.gii lh.sphere.reg.surf.gii     sub-01_hemi-L_sphere.surf_unprojected.surf.gii'
Mandatory Inputs:

  • sphere_in (a pathlike object or string representing an existing file) – A sphere with the desired output mesh. Maps to a command-line argument: %s (position: 0).

  • sphere_project_to (a pathlike object or string representing an existing file) – A sphere that aligns with sphere-in. Maps to a command-line argument: %s (position: 1).

  • sphere_unproject_from (a pathlike object or string representing an existing file) – <sphere-project-to> deformed to the desired output space. Maps to a command-line argument: %s (position: 2).

Optional Inputs:

sphere_out (a string or os.PathLike object) – The output sphere. Maps to a command-line argument: %s (position: 3).

Outputs:

sphere_out (a pathlike object or string representing a file) – The output sphere.