.. AUTO-GENERATED FILE -- DO NOT EDIT!

interfaces.freesurfer.utils
===========================


.. _nipype.interfaces.freesurfer.utils.ApplyMask:


.. index:: ApplyMask

ApplyMask
---------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L472>`__

Wraps command **mri_mask**

Use Freesurfer's mri_mask to apply a mask to an image.

The mask file need not be binarized; it can be thresholded above a given
value before application. It can also optionally be transformed into input
space with an LTA matrix.

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                input image (will be masked)
        mask_file: (an existing file name)
                image defining mask space
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                input image (will be masked)
        invert_xfm: (a boolean)
                invert transformation
        mask_file: (an existing file name)
                image defining mask space
        mask_thresh: (a float)
                threshold mask before applying
        out_file: (a file name)
                final image to write
        subjects_dir: (an existing directory name)
                subjects directory
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        use_abs: (a boolean)
                take absolute value of mask before applying
        xfm_file: (an existing file name)
                LTA-format transformation matrix to align mask with input
        xfm_source: (an existing file name)
                image defining transform source space
        xfm_target: (an existing file name)
                image defining transform target space

Outputs::

        out_file: (an existing file name)
                masked image

.. _nipype.interfaces.freesurfer.utils.ExtractMainComponent:


.. index:: ExtractMainComponent

ExtractMainComponent
--------------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L1104>`__

Wraps command **mris_extract_main_component**

Extract the main component of a tesselated surface

Examples
~~~~~~~~

>>> from nipype.interfaces.freesurfer import ExtractMainComponent
>>> mcmp = ExtractMainComponent(in_file='lh.pial')
>>> mcmp.cmdline
'mris_extract_main_component lh.pial lh.maincmp'

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                input surface file
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                input surface file
        out_file: (a file name)
                surface containing main component
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        out_file: (an existing file name)
                surface containing main component

.. _nipype.interfaces.freesurfer.utils.MRIMarchingCubes:


.. index:: MRIMarchingCubes

MRIMarchingCubes
----------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L945>`__

Wraps command **mri_mc**

Uses Freesurfer's mri_mc to create surfaces by tessellating a given input volume

Example
~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> mc = fs.MRIMarchingCubes()
>>> mc.inputs.in_file = 'aseg.mgz'
>>> mc.inputs.label_value = 17
>>> mc.inputs.out_file = 'lh.hippocampus'
>>> mc.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        label_value: (an integer)
                Label value which to tesselate from the input volume. (integer, if
                input is "filled.mgz" volume, 127 is rh, 255 is lh)
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        connectivity_value: (an integer, nipype default value: 1)
                Alter the marching cubes connectivity: 1=6+,2=18,3=6,4=26
                (default=1)
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        label_value: (an integer)
                Label value which to tesselate from the input volume. (integer, if
                input is "filled.mgz" volume, 127 is rh, 255 is lh)
        out_file: (a file name)
                output filename or True to generate one
        subjects_dir: (an existing directory name)
                subjects directory
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        surface: (an existing file name)
                binary surface of the tessellation

.. _nipype.interfaces.freesurfer.utils.MRITessellate:


.. index:: MRITessellate

MRITessellate
-------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L890>`__

Wraps command **mri_tessellate**

Uses Freesurfer's mri_tessellate to create surfaces by tessellating a given input volume

Example
~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> tess = fs.MRITessellate()
>>> tess.inputs.in_file = 'aseg.mgz'
>>> tess.inputs.label_value = 17
>>> tess.inputs.out_file = 'lh.hippocampus'
>>> tess.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        label_value: (an integer)
                Label value which to tesselate from the input volume. (integer, if
                input is "filled.mgz" volume, 127 is rh, 255 is lh)
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        label_value: (an integer)
                Label value which to tesselate from the input volume. (integer, if
                input is "filled.mgz" volume, 127 is rh, 255 is lh)
        out_file: (a file name)
                output filename or True to generate one
        subjects_dir: (an existing directory name)
                subjects directory
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        tesselate_all_voxels: (a boolean)
                Tessellate the surface of all voxels with different labels
        use_real_RAS_coordinates: (a boolean)
                Saves surface with real RAS coordinates where c_(r,a,s) != 0

Outputs::

        surface: (an existing file name)
                binary surface of the tessellation

.. _nipype.interfaces.freesurfer.utils.MRIsConvert:


.. index:: MRIsConvert

MRIsConvert
-----------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L827>`__

Wraps command **mris_convert**

Uses Freesurfer's mris_convert to convert surface files to various formats

Example
~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> mris = fs.MRIsConvert()
>>> mris.inputs.in_file = 'lh.pial'
>>> mris.inputs.out_datatype = 'gii'
>>> mris.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                File to read/convert
        out_datatype: ('ico' or 'tri' or 'stl' or 'vtk' or 'gii' or 'mgh' or
                 'mgz')
                These file formats are supported: ASCII: .ascICO: .ico, .tri GEO:
                .geo STL: .stl VTK: .vtk GIFTI: .gii MGH surface-encoded 'volume':
                .mgh, .mgz
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        annot_file: (an existing file name)
                input is annotation or gifti label data
        args: (a string)
                Additional parameters to the command
        dataarray_num: (an integer)
                if input is gifti, 'num' specifies which data array to use
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        functional_file: (an existing file name)
                input is functional time-series or other multi-frame data (must
                specify surface)
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                File to read/convert
        label_file: (an existing file name)
                infile is .label file, label is name of this label
        labelstats_outfile: (a file name)
                outfile is name of gifti file to which label stats will be written
        normal: (a boolean)
                output is an ascii file where vertex data
        origname: (a string)
                read orig positions
        out_datatype: ('ico' or 'tri' or 'stl' or 'vtk' or 'gii' or 'mgh' or
                 'mgz')
                These file formats are supported: ASCII: .ascICO: .ico, .tri GEO:
                .geo STL: .stl VTK: .vtk GIFTI: .gii MGH surface-encoded 'volume':
                .mgh, .mgz
        out_file: (a file name)
                output filename or True to generate one
        parcstats_file: (an existing file name)
                infile is name of text file containing label/val pairs
        patch: (a boolean)
                input is a patch, not a full surface
        rescale: (a boolean)
                rescale vertex xyz so total area is same as group average
        scalarcurv_file: (an existing file name)
                input is scalar curv overlay file (must still specify surface)
        scale: (a float)
                scale vertex xyz by scale
        subjects_dir: (an existing directory name)
                subjects directory
        talairachxfm_subjid: (a string)
                apply talairach xfm of subject to vertex xyz
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        vertex: (a boolean)
                Writes out neighbors of a vertex in each row
        xyz_ascii: (a boolean)
                Print only surface xyz to ascii file

Outputs::

        converted: (an existing file name)
                converted output surface

.. _nipype.interfaces.freesurfer.utils.MakeAverageSubject:


.. index:: MakeAverageSubject

MakeAverageSubject
------------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L1072>`__

Wraps command **make_average_subject**

Make an average freesurfer subject

Examples
~~~~~~~~

>>> from nipype.interfaces.freesurfer import MakeAverageSubject
>>> avg = MakeAverageSubject(subjects_ids=['s1', 's2'])
>>> avg.cmdline
'make_average_subject --out average --subjects s1 s2'

Inputs::

        [Mandatory]
        subjects_ids: (a list of items which are a string)
                freesurfer subjects ids to average
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        out_name: (a file name, nipype default value: average)
                name for the average subject
        subjects_dir: (an existing directory name)
                subjects directory
        subjects_ids: (a list of items which are a string)
                freesurfer subjects ids to average
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        average_subject_name: (a string)
                Output registration file

.. _nipype.interfaces.freesurfer.utils.SampleToSurface:


.. index:: SampleToSurface

SampleToSurface
---------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L123>`__

Wraps command **mri_vol2surf**

Sample a volume to the cortical surface using Freesurfer's mri_vol2surf.

You must supply a sampling method, range, and units.  You can project
either a given distance (in mm) or a given fraction of the cortical
thickness at that vertex along the surface normal from the target surface,
and then set the value of that vertex to be either the value at that point
or the average or maximum value found along the projection vector.

By default, the surface will be saved as a vector with a length equal to the
number of vertices on the target surface.  This is not a problem for Freesurfer
programs, but if you intend to use the file with interfaces to another package,
you must set the ``reshape`` input to True, which will factor the surface vector
into a matrix with dimensions compatible with proper Nifti files.

Examples
~~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> sampler = fs.SampleToSurface(hemi="lh")
>>> sampler.inputs.source_file = "cope1.nii.gz"
>>> sampler.inputs.reg_file = "register.dat"
>>> sampler.inputs.sampling_method = "average"
>>> sampler.inputs.sampling_range = 1
>>> sampler.inputs.sampling_units = "frac"
>>> res = sampler.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        hemi: ('lh' or 'rh')
                target hemisphere
        mni152reg: (a boolean)
                source volume is in MNI152 space
                mutually_exclusive: reg_file, reg_header, mni152reg
        projection_stem: (a string)
                stem for precomputed linear estimates and volume fractions
                mutually_exclusive: sampling_method
        reg_file: (an existing file name)
                source-to-reference registration file
                mutually_exclusive: reg_file, reg_header, mni152reg
        reg_header: (a boolean)
                register based on header geometry
                mutually_exclusive: reg_file, reg_header, mni152reg
                requires: subject_id
        sampling_method: ('point' or 'max' or 'average')
                how to sample -- at a point or at the max or average over a range
                mutually_exclusive: projection_stem
                requires: sampling_range, sampling_units
        source_file: (an existing file name)
                volume to sample values from
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        apply_rot: (a tuple of the form: (a float, a float, a float))
                rotation angles (in degrees) to apply to reg matrix
        apply_trans: (a tuple of the form: (a float, a float, a float))
                translation (in mm) to apply to reg matrix
        args: (a string)
                Additional parameters to the command
        cortex_mask: (a boolean)
                mask the target surface with hemi.cortex.label
                mutually_exclusive: mask_label
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        fix_tk_reg: (a boolean)
                make reg matrix round-compatible
        float2int_method: ('round' or 'tkregister')
                method to convert reg matrix values (default is round)
        frame: (an integer)
                save only one frame (0-based)
        hemi: ('lh' or 'rh')
                target hemisphere
        hits_file: (a boolean or an existing file name)
                save image with number of hits at each voxel
        hits_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or
                 'analyze4d' or 'spm' or 'afni' or 'brik' or 'bshort' or 'bfloat' or
                 'sdt' or 'outline' or 'otl' or 'gdf' or 'nifti1' or 'nii' or
                 'niigz')
                hits file type
        ico_order: (an integer)
                icosahedron order when target_subject is 'ico'
                requires: target_subject
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        interp_method: ('nearest' or 'trilinear')
                interpolation method
        mask_label: (an existing file name)
                label file to mask output with
                mutually_exclusive: cortex_mask
        mni152reg: (a boolean)
                source volume is in MNI152 space
                mutually_exclusive: reg_file, reg_header, mni152reg
        no_reshape: (a boolean)
                do not reshape surface vector (default)
                mutually_exclusive: reshape
        out_file: (a file name)
                surface file to write
        out_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or
                 'analyze4d' or 'spm' or 'afni' or 'brik' or 'bshort' or 'bfloat' or
                 'sdt' or 'outline' or 'otl' or 'gdf' or 'nifti1' or 'nii' or
                 'niigz')
                output file type
        override_reg_subj: (a boolean)
                override the subject in the reg file header
                requires: subject_id
        projection_stem: (a string)
                stem for precomputed linear estimates and volume fractions
                mutually_exclusive: sampling_method
        reference_file: (an existing file name)
                reference volume (default is orig.mgz)
        reg_file: (an existing file name)
                source-to-reference registration file
                mutually_exclusive: reg_file, reg_header, mni152reg
        reg_header: (a boolean)
                register based on header geometry
                mutually_exclusive: reg_file, reg_header, mni152reg
                requires: subject_id
        reshape: (a boolean)
                reshape surface vector to fit in non-mgh format
                mutually_exclusive: no_reshape
        reshape_slices: (an integer)
                number of 'slices' for reshaping
        sampling_method: ('point' or 'max' or 'average')
                how to sample -- at a point or at the max or average over a range
                mutually_exclusive: projection_stem
                requires: sampling_range, sampling_units
        sampling_range: (a float or a tuple of the form: (a float, a float, a
                 float))
                sampling range - a point or a tuple of (min, max, step)
        sampling_units: ('mm' or 'frac')
                sampling range type -- either 'mm' or 'frac'
        scale_input: (a float)
                multiple all intensities by scale factor
        smooth_surf: (a float)
                smooth output surface (mm fwhm)
        smooth_vol: (a float)
                smooth input volume (mm fwhm)
        source_file: (an existing file name)
                volume to sample values from
        subject_id: (a string)
                subject id
        subjects_dir: (an existing directory name)
                subjects directory
        surf_reg: (a boolean)
                use surface registration to target subject
                requires: target_subject
        surface: (a string)
                target surface (default is white)
        target_subject: (a string)
                sample to surface of different subject than source
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        vox_file: (a boolean or a file name)
                text file with the number of voxels intersecting the surface

Outputs::

        hits_file: (an existing file name)
                image with number of hits at each voxel
        out_file: (an existing file name)
                surface file
        vox_file: (an existing file name)
                text file with the number of voxels intersecting the surface

.. _nipype.interfaces.freesurfer.utils.SmoothTessellation:


.. index:: SmoothTessellation

SmoothTessellation
------------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L1011>`__

Wraps command **mris_smooth**

This program smooths the tessellation of a surface using 'mris_smooth'

.. seealso::

    SurfaceSmooth() Interface
        For smoothing a scalar field along a surface manifold

Example
~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> smooth = fs.SmoothTessellation()
>>> smooth.inputs.in_file = 'lh.hippocampus.stl'
>>> smooth.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        curvature_averaging_iterations: (an integer, nipype default value:
                 10)
                Number of curvature averaging iterations (default=10)
        disable_estimates: (a boolean)
                Disables the writing of curvature and area estimates
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        gaussian_curvature_norm_steps: (an integer)
                Use Gaussian curvature smoothing
        gaussian_curvature_smoothing_steps: (an integer)
                Use Gaussian curvature smoothing
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                Input volume to tesselate voxels from.
        normalize_area: (a boolean)
                Normalizes the area after smoothing
        out_area_file: (a file name)
                Write area to ?h.areaname (default "area")
        out_curvature_file: (a file name)
                Write curvature to ?h.curvname (default "curv")
        out_file: (a file name)
                output filename or True to generate one
        smoothing_iterations: (an integer, nipype default value: 10)
                Number of smoothing iterations (default=10)
        snapshot_writing_iterations: (an integer)
                Write snapshot every "n" iterations
        subjects_dir: (an existing directory name)
                subjects directory
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        use_gaussian_curvature_smoothing: (a boolean)
                Use Gaussian curvature smoothing
        use_momentum: (a boolean)
                Uses momentum

Outputs::

        surface: (an existing file name)
                Smoothed surface file

.. _nipype.interfaces.freesurfer.utils.Surface2VolTransform:


.. index:: Surface2VolTransform

Surface2VolTransform
--------------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L426>`__

Wraps command **mri_surf2vol**

Use FreeSurfer mri_surf2vol to apply a transform.

Examples
~~~~~~~~

>>> from nipype.interfaces.freesurfer import Surface2VolTransform
>>> xfm2vol = Surface2VolTransform()
>>> xfm2vol.inputs.source_file = 'lh.cope1.mgz'
>>> xfm2vol.inputs.reg_file = 'register.mat'
>>> xfm2vol.inputs.hemi = 'lh'
>>> xfm2vol.inputs.template_file = 'cope1.nii.gz'
>>> xfm2vol.inputs.subjects_dir = '.'
>>> xfm2vol.cmdline
'mri_surf2vol --hemi lh --volreg register.mat --surfval lh.cope1.mgz --sd . --template cope1.nii.gz --outvol lh.cope1_asVol.nii --vtxvol lh.cope1_asVol_vertex.nii'
>>> res = xfm2vol.run()# doctest: +SKIP

Inputs::

        [Mandatory]
        hemi: (a string)
                hemisphere of data
        reg_file: (an existing file name)
                tkRAS-to-tkRAS matrix (tkregister2 format)
                mutually_exclusive: subject_id
        source_file: (an existing file name)
                This is the source of the surface values
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        hemi: (a string)
                hemisphere of data
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        mkmask: (a boolean)
                make a mask instead of loading surface values
        projfrac: (a float)
                thickness fraction
        reg_file: (an existing file name)
                tkRAS-to-tkRAS matrix (tkregister2 format)
                mutually_exclusive: subject_id
        source_file: (an existing file name)
                This is the source of the surface values
        subject_id: (a string)
                subject id
                mutually_exclusive: reg_file
        subjects_dir: (a string)
                freesurfer subjects directory defaults to $SUBJECTS_DIR
        surf_name: (a string)
                surfname (default is white)
        template_file: (an existing file name)
                Output template volume
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        transformed_file: (a file name)
                Output volume
        vertexvol_file: (a file name)
                Path name of the vertex output volume, which is the same as output
                volume except that the value of each voxel is the vertex-id that is
                mapped to that voxel.

Outputs::

        transformed_file: (an existing file name)
                Path to output file if used normally
        vertexvol_file: (a file name)
                vertex map volume path id. Optional

.. _nipype.interfaces.freesurfer.utils.SurfaceSmooth:


.. index:: SurfaceSmooth

SurfaceSmooth
-------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L246>`__

Wraps command **mri_surf2surf**

Smooth a surface image with mri_surf2surf.

The surface is smoothed by an interative process of averaging the
value at each vertex with those of its adjacent neighbors. You may supply
either the number of iterations to run or a desired effective FWHM of the
smoothing process.  If the latter, the underlying program will calculate
the correct number of iterations internally.

.. seealso::

    SmoothTessellation() Interface
        For smoothing a tessellated surface (e.g. in gifti or .stl)

Examples
~~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> smoother = fs.SurfaceSmooth()
>>> smoother.inputs.in_file = "lh.cope1.mgz"
>>> smoother.inputs.subject_id = "subj_1"
>>> smoother.inputs.hemi = "lh"
>>> smoother.inputs.fwhm = 5
>>> smoother.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        hemi: ('lh' or 'rh')
                hemisphere to operate on
        in_file: (a file name)
                source surface file
        subject_id: (a string)
                subject id of surface file
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        cortex: (a boolean, nipype default value: True)
                only smooth within $hemi.cortex.label
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        fwhm: (a float)
                effective FWHM of the smoothing process
                mutually_exclusive: smooth_iters
        hemi: ('lh' or 'rh')
                hemisphere to operate on
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (a file name)
                source surface file
        out_file: (a file name)
                surface file to write
        reshape: (a boolean)
                reshape surface vector to fit in non-mgh format
        smooth_iters: (an integer)
                iterations of the smoothing process
                mutually_exclusive: fwhm
        subject_id: (a string)
                subject id of surface file
        subjects_dir: (an existing directory name)
                subjects directory
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        out_file: (an existing file name)
                smoothed surface file

.. _nipype.interfaces.freesurfer.utils.SurfaceSnapshots:


.. index:: SurfaceSnapshots

SurfaceSnapshots
----------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L578>`__

Wraps command **tksurfer**

Use Tksurfer to save pictures of the cortical surface.

By default, this takes snapshots of the lateral, medial, ventral,
and dorsal surfaces.  See the ``six_images`` option to add the
anterior and posterior surfaces.

You may also supply your own tcl script (see the Freesurfer wiki for
information on scripting tksurfer). The screenshot stem is set as the
environment variable "_SNAPSHOT_STEM", which you can use in your
own scripts.

Node that this interface will not run if you do not have graphics
enabled on your system.

Examples
~~~~~~~~

>>> import nipype.interfaces.freesurfer as fs
>>> shots = fs.SurfaceSnapshots(subject_id="fsaverage", hemi="lh", surface="pial")
>>> shots.inputs.overlay = "zstat1.nii.gz"
>>> shots.inputs.overlay_range = (2.3, 6)
>>> shots.inputs.overlay_reg = "register.dat"
>>> res = shots.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        hemi: ('lh' or 'rh')
                hemisphere to visualize
        subject_id: (a string)
                subject to visualize
        surface: (a string)
                surface to visualize
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        annot_file: (an existing file name)
                path to annotation file to display
                mutually_exclusive: annot_name
        annot_name: (a string)
                name of annotation to display (must be in $subject/label directory
                mutually_exclusive: annot_file
        args: (a string)
                Additional parameters to the command
        colortable: (an existing file name)
                load colortable file
        demean_overlay: (a boolean)
                remove mean from overlay
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        hemi: ('lh' or 'rh')
                hemisphere to visualize
        identity_reg: (a boolean)
                use the identity matrix to register the overlay to the surface
                mutually_exclusive: overlay_reg, identity_reg, mni152_reg
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        invert_overlay: (a boolean)
                invert the overlay display
        label_file: (an existing file name)
                path to label file to display
                mutually_exclusive: label_name
        label_name: (a string)
                name of label to display (must be in $subject/label directory
                mutually_exclusive: label_file
        label_outline: (a boolean)
                draw label/annotation as outline
        label_under: (a boolean)
                draw label/annotation under overlay
        mni152_reg: (a boolean)
                use to display a volume in MNI152 space on the average subject
                mutually_exclusive: overlay_reg, identity_reg, mni152_reg
        orig_suffix: (a string)
                set the orig surface suffix string
        overlay: (an existing file name)
                load an overlay volume/surface
                requires: overlay_range
        overlay_range: (a float or a tuple of the form: (a float, a float) or
                 a tuple of the form: (a float, a float, a float))
                overlay range--either min, (min, max) or (min, mid, max)
        overlay_range_offset: (a float)
                overlay range will be symettric around offset value
        overlay_reg: (a file name)
                registration matrix file to register overlay to surface
                mutually_exclusive: overlay_reg, identity_reg, mni152_reg
        patch_file: (an existing file name)
                load a patch
        reverse_overlay: (a boolean)
                reverse the overlay display
        screenshot_stem: (a string)
                stem to use for screenshot file names
        show_color_scale: (a boolean)
                display the color scale bar
        show_color_text: (a boolean)
                display text in the color scale bar
        show_curv: (a boolean)
                show curvature
                mutually_exclusive: show_gray_curv
        show_gray_curv: (a boolean)
                show curvature in gray
                mutually_exclusive: show_curv
        six_images: (a boolean)
                also take anterior and posterior snapshots
        sphere_suffix: (a string)
                set the sphere.reg suffix string
        stem_template_args: (a list of items which are a string)
                input names to use as arguments for a string-formated stem template
                requires: screenshot_stem
        subject_id: (a string)
                subject to visualize
        subjects_dir: (an existing directory name)
                subjects directory
        surface: (a string)
                surface to visualize
        tcl_script: (an existing file name)
                override default screenshot script
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        truncate_overlay: (a boolean)
                truncate the overlay display

Outputs::

        snapshots: (an existing file name)
                tiff images of the surface from different perspectives

.. _nipype.interfaces.freesurfer.utils.SurfaceTransform:


.. index:: SurfaceTransform

SurfaceTransform
----------------

`Link to code <http://github.com/nipy/nipype/tree/b1b78251dfd6f3b60c6bc63f79f86b356a8fe9cc/nipype/interfaces/freesurfer/utils.py#L331>`__

Wraps command **mri_surf2surf**

Transform a surface file from one subject to another via a spherical registration.

Both the source and target subject must reside in your Subjects Directory,
and they must have been processed with recon-all, unless you are transforming
to one of the icosahedron meshes.

Examples
~~~~~~~~

>>> from nipype.interfaces.freesurfer import SurfaceTransform
>>> sxfm = SurfaceTransform()
>>> sxfm.inputs.source_file = "lh.cope1.nii.gz"
>>> sxfm.inputs.source_subject = "my_subject"
>>> sxfm.inputs.target_subject = "fsaverage"
>>> sxfm.inputs.hemi = "lh"
>>> sxfm.run() # doctest: +SKIP

Inputs::

        [Mandatory]
        hemi: ('lh' or 'rh')
                hemisphere to transform
        source_annot_file: (an existing file name)
                surface annotation file
                mutually_exclusive: source_file
        source_file: (an existing file name)
                surface file with source values
                mutually_exclusive: source_annot_file
        source_subject: (a string)
                subject id for source surface
        target_subject: (a string)
                subject id of target surface
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        hemi: ('lh' or 'rh')
                hemisphere to transform
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        out_file: (a file name)
                surface file to write
        reshape: (a boolean)
                reshape output surface to conform with Nifti
        reshape_factor: (an integer)
                number of slices in reshaped image
        source_annot_file: (an existing file name)
                surface annotation file
                mutually_exclusive: source_file
        source_file: (an existing file name)
                surface file with source values
                mutually_exclusive: source_annot_file
        source_subject: (a string)
                subject id for source surface
        source_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or
                 'analyze4d' or 'spm' or 'afni' or 'brik' or 'bshort' or 'bfloat' or
                 'sdt' or 'outline' or 'otl' or 'gdf' or 'nifti1' or 'nii' or
                 'niigz')
                source file format
                requires: source_file
        subjects_dir: (an existing directory name)
                subjects directory
        target_ico_order: (1 or 2 or 3 or 4 or 5 or 6 or 7)
                order of the icosahedron if target_subject is 'ico'
        target_subject: (a string)
                subject id of target surface
        target_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or
                 'analyze4d' or 'spm' or 'afni' or 'brik' or 'bshort' or 'bfloat' or
                 'sdt' or 'outline' or 'otl' or 'gdf' or 'nifti1' or 'nii' or
                 'niigz')
                output format
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        out_file: (an existing file name)
                transformed surface file
