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. #
