function ds_plumb=cosmo_fmri_deoblique(ds)
% de-oblique a dataset
%
% Input:
% ds fmri dataset struct
%
% Output:
%
% Example:
% % start with a simple dataset
% x=cosmo_synthetic_dataset('size','huge','ntargets',1,'nchunks',1);
% % make dataset oblique (manually)
% x.a.vol.mat(1,1)=.8;
% x.a.vol.mat(2,1)=.6;
% y=cosmo_fmri_deoblique(x);
% cosmo_disp(x.a.vol)
% %|| .mat
% %|| [ 0.8 0 0 -3
% %|| 0.6 2 0 -3
% %|| 0 0 2 -3
% %|| 0 0 0 1 ]
% %|| .dim
% %|| [ 20 17 19 ]
% %|| .xform
% %|| 'scanner_anat'
% cosmo_disp(y.a.vol)
% %|| .mat
% %|| [ 1 0 0 -3.2
% %|| 0 2 0 -2.4
% %|| 0 0 2 -3
% %|| 0 0 0 1 ]
% %|| .dim
% %|| [ 20 17 19 ]
% %|| .xform
% %|| 'scanner_anat'
% %
% % other attributes are unchanged:
% assert(isequal({x.samples x.fa x.sa x.a.fdim},...
% {y.samples y.fa y.sa y.a.fdim}));
% %
% % a plump dataset does not change after de-obliqueing
% z=cosmo_fmri_deoblique(y);
% isequal(y,z)
% %|| true
%
% Notes:
% - Using this function changes the location of the voxels in
% world-space, that is world coordinates (x, y, z).
% - This function is intended for AFNI and BrainVoyager, as these
% programs prefer 'plump' (non-oblique) volumes.
% - When using this function, it is recommended to inspect the result
% visually.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
