mars_vol_utils

 collection of useful utility functions for vol structs
 
 tf = mars_vol_utils('is_vol', V)
    Returns 1 if V may be a vol struct (right fields)

 [t,be,sw] = mars_vol_utils('type', V)
    Returns type number for vol struct - see spm_type, spm_vol
    Second output t = 1 if vol seems to be little-endian
    Third output sw = 1 if vol swapped relative to this platform

 V = mars_vol_utils('set_type', V, type_info)
    Sets type of vol struct, using type_info
    type_info can be a number, or a string (see spm_type)
  
 tf = mars_vol_utils('is_swapped', V)
    Returns 1 if V contains data that has opposite endianness from
    current platform (as given by spm_platform('bigendian')

 ver = mars_vol_utils('ver', V)
    Returns version string for vol struct
    '99' if appears to be spm99 format, '5' for spm5

 ver = mars_vol_utils('current_ver')
    Returns '99' if current spm_vols returns 99 vol type, else '5'

 tf = mars_vol_utils('is_swapped_wrong', V)
    Returns 1 if the vol struct V has the different swapping
    information from a fresh mapping from the same file, and thus might
    have to be remapped. 

 V = mars_vol_utils('byte_swap', V)
    Returns new vols for opposite byte ordering to current spec

 V = mars_vol_utils('convert', V, ver)
    Return vol struct(s) V converted to type specified in ver
    If ver not specified, convert to current ver type
 
 V = mars_vol_utils('def_vol', ver)
    Return default structure for type ver
    If ver not specified, use current ver type

 $Id: mars_vol_utils.m 581 2005-06-21 15:40:17Z matthewbrett $

0001 function varargout=mars_vol_utils(varargin)
0002 % collection of useful utility functions for vol structs
0003 %
0004 % tf = mars_vol_utils('is_vol', V)
0005 %    Returns 1 if V may be a vol struct (right fields)
0006 %
0007 % [t,be,sw] = mars_vol_utils('type', V)
0008 %    Returns type number for vol struct - see spm_type, spm_vol
0009 %    Second output t = 1 if vol seems to be little-endian
0010 %    Third output sw = 1 if vol swapped relative to this platform
0011 %
0012 % V = mars_vol_utils('set_type', V, type_info)
0013 %    Sets type of vol struct, using type_info
0014 %    type_info can be a number, or a string (see spm_type)
0015 %
0016 % tf = mars_vol_utils('is_swapped', V)
0017 %    Returns 1 if V contains data that has opposite endianness from
0018 %    current platform (as given by spm_platform('bigendian')
0019 %
0020 % ver = mars_vol_utils('ver', V)
0021 %    Returns version string for vol struct
0022 %    '99' if appears to be spm99 format, '5' for spm5
0023 %
0024 % ver = mars_vol_utils('current_ver')
0025 %    Returns '99' if current spm_vols returns 99 vol type, else '5'
0026 %
0027 % tf = mars_vol_utils('is_swapped_wrong', V)
0028 %    Returns 1 if the vol struct V has the different swapping
0029 %    information from a fresh mapping from the same file, and thus might
0030 %    have to be remapped.
0031 %
0032 % V = mars_vol_utils('byte_swap', V)
0033 %    Returns new vols for opposite byte ordering to current spec
0034 %
0035 % V = mars_vol_utils('convert', V, ver)
0036 %    Return vol struct(s) V converted to type specified in ver
0037 %    If ver not specified, convert to current ver type
0038 %
0039 % V = mars_vol_utils('def_vol', ver)
0040 %    Return default structure for type ver
0041 %    If ver not specified, use current ver type
0042 %
0043 % $Id: mars_vol_utils.m 581 2005-06-21 15:40:17Z matthewbrett $
0044 
0045 nout = max(nargout,1);
0046 varargout = cell(1, nout);
0047 if nargin < 1
0048   error('Need action');
0049 end
0050 Action = lower(varargin{1});
0051 if nargin > 1
0052   V = varargin{2};
0053 end
0054 
0055 switch(Action)
0056 
0057 %=======================================================================
0058 case 'is_vol'             % Returns 1 if this appears to be a vol struct
0059 %=======================================================================
0060 if nargin < 2
0061   error('Need vol struct to check');
0062 end
0063 varargout = {sf_is_vol(V)};
0064   
0065 %=======================================================================
0066 case 'type'                                    % Returns vol type number
0067 %=======================================================================
0068 if nargin < 2
0069   error('Need vol struct to give type');
0070 end
0071 sf_die_no_vol(V);
0072 varargout{:} = sf_type(V);
0073 
0074 %=======================================================================
0075 case 'set_type'                                          % Sets vol type
0076 %=======================================================================
0077 if nargin < 2
0078   error('Need vol struct to set type');
0079 end
0080 sf_die_no_vol(V);
0081 if nargin < 3
0082   error('Need type to set');
0083 end
0084 type_info = varargin{3};
0085 varargout = {sf_set_type(V, type_info)};
0086 
0087 %=======================================================================
0088 case 'is_swapped' % Returns 1 if vol swapped relative to this platform
0089 %=======================================================================
0090 if nargin < 2
0091   error('Need vol struct to check swapping');
0092 end
0093 sf_die_no_vol(V);
0094 [t be sw] = sf_type(V);
0095 varargout = {sw};
0096 
0097 %=======================================================================
0098 case 'ver'                                    % Returns vol type version
0099 %=======================================================================
0100 if nargin < 2
0101   error('Need vol struct to give version');
0102 end
0103 sf_die_no_vol(V);
0104 varargout = {sf_ver(V)};
0105 
0106 %=======================================================================
0107 case 'current_ver'               % Returns vol type from spm_vol on path
0108 %=======================================================================
0109 varargout = {sf_current_ver};
0110 
0111 %=======================================================================
0112 case 'is_swapped_wrong'    % Returns 1 for if vol is incorrectly swapped
0113 %=======================================================================
0114 if nargin < 2
0115   error('Need vol struct to test');
0116 end
0117 sf_die_no_vol(V);
0118 V2 = spm_vol(V.fname);
0119 [t be] = sf_type(V);
0120 [t be2] = sf_type(V2);
0121 varargout = {be ~= be2};
0122 
0123 %=======================================================================
0124 case 'byte_swap'      % return vols with opposite recorded byte ordering
0125 %=======================================================================
0126 if nargin < 2
0127   error('Need vol struct to swap');
0128 end
0129 sf_die_no_vol(V);
0130 switch sf_ver(V)
0131  case '99'
0132   for i = 1:numel(V)
0133     if V(i).dim(4) < 256, scf = 256; else scf = 1/256; end
0134     V(i).dim(4) = V(i).dim(4) * scf;
0135   end
0136  case '5'
0137   for i = 1:numel(V)
0138     V(i).dt(2) = 1-V(i).dt(2);
0139   end
0140  otherwise
0141   error(['Don''t often see those ' sf_ver(V)]);
0142 end
0143 varargout = {V};
0144 
0145 %=======================================================================
0146 case 'convert'              % Returns vols converted to alternative type
0147 %=======================================================================
0148 if nargin < 2
0149   error('Need vol struct to convert');
0150 end
0151 if ~sf_is_vol(V), varargout={V}; return, end
0152 if nargin < 3
0153   ver = sf_current_ver;
0154 else
0155   ver = varargin{3};
0156   if sf_is_vol(ver), ver = sf_ver(ver); end
0157 end
0158 if sf_same_ver(V, ver)
0159   varargout = {V};
0160   return
0161 end
0162 switch sf_ver(V)
0163  case '99'
0164   varargout = {sf_99_to_5(V)};
0165  case '5'
0166   varargout = {sf_5_to_99(V)};
0167  otherwise
0168   error([sf_ver(V) ' is just nuts']);
0169 end
0170 
0171 %=======================================================================
0172 case 'def_vol'                % Returns default vol struct of given type
0173 %=======================================================================
0174 if nargin < 2
0175   ver = sf_current_ver;
0176 else
0177   ver = varargin{2};
0178   if sf_is_vol(ver), ver = sf_ver(ver); end
0179 end
0180 switch ver
0181  case '99'
0182   varargout = {sf_def_vol_99};
0183  case '5'
0184   varargout = {sf_def_vol_5};
0185  otherwise
0186   error([ver ' is unacceptable']);
0187 end
0188 return 
0189  
0190 otherwise
0191   error([Action ' is beyond my range']);
0192 end
0193 return
0194 
0195 % Subfunctions
0196 
0197 function tf = sf_is_vol(V)
0198 % returns 1 if this may be a vol struct
0199 tf = 0;
0200 if ~isstruct(V), return, end
0201 if ~isfield(V, 'dim'), return, end
0202 tf = 1;
0203 return
0204 
0205 function sf_die_no_vol(V)
0206 if ~sf_is_vol(V)
0207   error('I really wanted a vol struct here');
0208 end
0209 return
0210 
0211 function [t, be, sw] = sf_type(V)
0212 % returns type number, big-endian flag, swapped flag
0213 plat_be = spm_platform('bigend');
0214 V = V(1);
0215 if sf_same_ver(V, '5') % spm5 vol type
0216   t = V.dt(1); 
0217   be = V.dt(2);
0218   sw = xor(be, plat_be);
0219 elseif length(V.dim) > 3 % spm99 style type specifier
0220   t = V.dim(4);
0221   sw = (t > 256);
0222   if sw, t = t/256; end
0223   be = xor(plat_be, sw);
0224 else
0225   error('Could not get vol type');
0226 end
0227 return
0228 
0229 function V = sf_set_type(V, type_info)
0230 % set type for V from type_info
0231 switch sf_current_ver
0232  case '99'
0233   if ischar(type_info)
0234     if strcmp(type_info, 'float32'), type_info='float'; end
0235     if strcmp(type_info, 'float64'), type_info='double'; end
0236     type_info = spm_type(type_info);
0237   end
0238  case '5'
0239   if ischar(type_info)
0240     if strcmp(type_info, 'float'), type_info='float32'; end
0241     if strcmp(type_info, 'double'), type_info='float64'; end
0242     type_info = spm_type(type_info);
0243   end
0244  otherwise
0245   error(['Don''t like your type: ' sf_current_ver]);
0246 end
0247 switch sf_ver(V)
0248  case '99'
0249   V.dim(4) = type_info;
0250  case '5'
0251   V.dt(1) = type_info;
0252  otherwise
0253   error(['That''s a funny type: ' sf_ver(V)]);
0254 end
0255 return
0256   
0257 function ver = sf_ver(V)
0258 % returns version string ('99' or '5')
0259 if isfield(V, 'dt')
0260   ver = '5';
0261 else
0262   ver = '99';
0263 end
0264 return
0265 
0266 function ver = sf_current_ver;
0267 % returns version for spm_vol on path
0268 % spm2,99 spm_vol do not accept no args
0269 try
0270   V = spm_vol;
0271   ver = sf_ver(V);
0272 catch
0273   ver = '99';
0274 end
0275 return
0276 
0277 function V = sf_def_vol_99;
0278 V = struct(...
0279     'fname', '',...
0280     'dim', zeros(1,4), ...
0281     'pinfo', [1 0 0]', ...
0282     'mat', eye(4), ...
0283     'n', [], ...
0284     'descrip', '');
0285 return
0286 
0287 function V = sf_def_vol_5;
0288 V = struct('fname', '',...
0289        'dim',   zeros(1,3),...
0290        'dt',    [0 0],...
0291        'pinfo', [1 0 0]',...
0292        'mat',   eye(4),...
0293        'n',     [],...
0294        'descrip', '',...
0295        'private',[]);
0296 return
0297 
0298 function Vo = sf_99_to_5(Vi)
0299 % converts spm99 vols to spm5 vols
0300 d = sf_def_vol_5;
0301 Vo = d; % in case Vi is empty
0302 is_n = isfield(Vi, 'n');
0303 for i = 1:numel(Vi)
0304   OV = Vi(i);
0305   NV = d;
0306   [t be] = sf_type(OV);
0307   NV.fname = OV.fname;
0308   NV.dim = OV.dim(1:3);
0309   NV.dt = [t be];
0310   NV.mat = OV.mat;
0311   NV.pinfo = OV.pinfo;
0312   NV.descrip = OV.descrip;
0313   if is_n, NV.n = [OV.n 1]; end
0314   Vo(i) = NV;
0315 end
0316 Vo = reshape(Vo, size(Vi));
0317 return
0318 
0319 function Vo = sf_5_to_99(Vi)
0320 % converts spm5 vols to spm99 vols
0321 d = sf_def_vol_99;
0322 Vo = d; % in case Vi is empty
0323 for i = 1:numel(Vi)
0324   OV = Vi(i);
0325   NV = d;
0326   [t be sw] = sf_type(OV);
0327   if sw, t = t * 256; end
0328   NV.fname = OV.fname;
0329   NV.dim = [OV.dim(1:3) t];
0330   NV.mat = OV.mat;
0331   NV.pinfo = OV.pinfo;
0332   NV.descrip = OV.descrip;
0333   NV.n = OV.n(1);
0334   Vo(i) = NV;
0335 end
0336 Vo = reshape(Vo, size(Vi));
0337 return
0338 
0339 function tf = sf_same_ver(V, ver)
0340 tf = strcmp(sf_ver(V), ver);
0341 return