cosmo fmri deoblique hdr

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