cosmo map2surface hdrΒΆ

function s=cosmo_map2surface(ds, fn, varargin)
% maps a dataset structure to AFNI/SUMA NIML dset or BV SMP file
%
% s=cosmo_map2surface(ds, output, ...)
%
% Inputs:
%   ds                  dataset struct with surface-based data
%   output              String, indicating either the output format or the
%                       filename.
%                       - If output starts with a '-', then it must be one
%                         of:
%                           '-niml_dset'    AFNI NIML
%                           '-bv_smp'       BrainVoyager surface map
%                           '-gii'          GIFTI
%                       - otherwise it must be a string indicating a file
%                         name, and end with one of
%                           '.niml.dset'    AFNI NIML
%                           '.smp'          BrainVoyager surface map
%                           '.gii'          GIFTI
%  'encoding', e        Optional encoding for AFNI NIML or GIFTI. Depending
%                       on the output format, supported values for e are:
%                       - NIML:  'ascii', 'binary',
%                                'binary.lsbfirst', 'binary.msbfirst'
%                         (the 'binary' option uses the machine's native
%                         format with either the least or most significant
%                         byte first)
%                       - GIFTI: 'ASCII', 'Base64Binary',
%                                'GZipBase64Binary'
%                       The encoding argument is ignored for BrainVoyager
%                       output.
%  'format', f          Optional format to be used for output, if the
%                       output argument empty; one of 'niml_dset', 'bv_smp'
%                       or 'gii'.
%
% Output:
%   s                   Structure containing the surface based data based
%                       on the output format; either a struct with
%                       NIML data, an xff object, or a GIFTI object.
%
% Examples:
%     % (this example requires the AFNI Matlab toolbox)
%     cosmo_skip_test_if_no_external('afni');
%     %
%     ds=cosmo_synthetic_dataset('type','surface');
%     %
%     % convert to AFNIML NIML format
%     % (to store a file to disc, use a filename as the second argument)
%     niml=cosmo_map2surface(ds,'-niml_dset');
%     cosmo_disp(niml);
%     %|| .node_indices
%     %||   [ 0         1         2         3         4         5 ]
%     %|| .data
%     %||   [   2.03     0.584     -1.44    -0.518      1.19     -1.33
%     %||     -0.892      1.84    -0.262      2.34    -0.204      2.72
%     %||     -0.826      1.17     -1.92     0.441    -0.209     0.148
%     %||       1.16    -0.848      3.09      1.86      1.76     0.502
%     %||       1.16      3.49     -1.37     0.479    -0.955      3.41
%     %||      -1.29    -0.199      1.73    0.0832     0.501     -0.48 ]
%
% Notes:
%   - this function is intended for datasets with surface data, i.e. with
%     one or more values associated with each surface node. It does not
%     support anatomical surface meshes that contain node coordinates and
%     faces. To read and write such anatomical meshes, consider the surfing
%     toolbox, github.com/nno/surfing
%   - To load surface datasets, use cosmo_surface_dataset
%
% Dependencies:
%   - for Brainvoyager files (.smp), it requires the NeuroElf
%     toolbox, available from: http://neuroelf.net
%   - for AFNI/SUMA NIML files (.niml.dset) it requires the AFNI
%     Matlab toolbox, available from: https://github.com/afni/AFNI
%
% See also: cosmo_surface_dataset
%
% #   For CoSMoMVPA's copyright information and license terms,   #
% #   see the COPYING file distributed with CoSMoMVPA.           #