Home > phiwave > @slover > slover.m

slover

PURPOSE ^

class constructor for slice overlay (slover) object

SYNOPSIS ^

function [o, others] = slover(params, others, varargin)

DESCRIPTION ^

 class constructor for slice overlay (slover) object
 FORMAT [o, others] = slover(params, others, varargin)

 Inputs  
 params    - either: 
             - action string implementing class methods (see below)
             - array of image names / vol structs to display
             - structure with some fields for object (see below)
 others    - structure, containing extra fields for object (or children)
 varargin  - maybe some other parameters for action calls (see below)

 Outputs
 o       - slover object
 others  - any unrecognized fields from params, others

 Object fields are:
  - img - array of structs with information for images to display
        - img structs contain fields
             type - one of {'truecolour' 'split', 'contour'};
                   truecolour - displays transparent (see prop) image 
                      overlaid with any previous
                   split - in defined area, replaces image present (SPM
                      type activation display)
                   contour - contour map of image overlaid.  See help
                      for contours function in matlab
             vol - vol struct info (see spm_vol)
                   can also be vol containing image as 3d matrix
                   set with add_blobs method
             cmap - colormap for this image
             nancol - color for NaN. If scalar, this is an index into
                    the image cmap.  If 1x3 vector, it's a colour
             prop - proportion of intensity for this cmap/img 
             func - function to apply to image before scaling to cmap
                    (and therefore before min/max thresholding. E.g. a func of
                    'i1(i1==0)=NaN' would convert zeros to NaNs
             range - 2x1 vector of values for image to distribute colormap across
                    the first row of the colormap applies to the first
                    value in 'range', and the last value to the second
                    value in 'range'
             outofrange - behavior for image values to the left and
                    right of image limits in 'range'.  Left means
                    colormap values < 1, i.e for image values <
                    range(1), if (range(1)<range(2)), and image values >
                    range(1) where (range(1)>range(2)). If missing,
                    display min (for Left) and max (for Right) value from colormap. 
                    Otherwise should be a 2 element cell array, where
                    the first element is the colour value for image values
                    left of 'range', and the second is for image values
                    right of 'range'.  Scalar values for
                    colour index the colormap, 3x1 vectors are colour
                    values.  An empty array attracts default settings
                    appropriate to the mode - i.e. transparent colour (where 
                    img(n).type is truecolour), or split colour.  Empty cells
                    default to 0. 0 specifies that voxels with this
                    colour do not influence the image (split =
                    background, true = black)
            hold  - resampling order for image (see spm_sample_vol) -
                    default 1
            background - value when resampling outside image - default
                    NaN
            linespec - string, applies only to contour map,
                    e.g. 'w-' for white continuous lines
            contours - vector, applies to contour map only, defines 
                    values in image for which to show contours 
                    (see help contours)
            linewidth - scalar, width in points of contour lines
            
 - transform - either - 4x4 transformation to apply to image slice position,
             relative to mm given by slicedef, before display
               or     - text string, one of axial, coronal, sagittal
                        These orientations assume the image is currently
                        (after its mat file has been applied) axially
                        oriented
 - slicedef - 2x3 array specifying dimensions for slice images in mm
             where rows are x,and y of slice image, and cols are neg max dim,
             slice separation and pos max dim
 - slices   - vector of slice positions in mm in z (of transformed image)
 - figure    - figure handle for slice display figure
               The object used for the display is attached as 'UserData'
               to this figure
 - figure_struct - stored figure parameters (in case figure dies and
               needs to be recreated)
 - refreshf  - flag - if set or empty, refresh axis info for figure
             else assume this is OK
 - clf       - flag, non zero -> clear figure before display.  Redundant
               if refreshf == 0
 - resurrectf - if not zero, and figure (above) does not exist, will
               attempt to recreate figure with same area properties.
               Otherwise painting will give an error.
 - userdata  - flag, non zero -> attaches object to figure when ploting,
               for use by callbacks (default is 1)
 - area      - struct with fields
                  position - bottom left, x size y size 1x4 vector of
                      area in which to display slices
                  units    - one of
                    inches,centimeters,normalized,points,{pixels}
                  halign - one of left,{center},right
                  valign - one of top,{middle},bottom
 - xslices  - no of slices to display across figure (defaults to an optimum)
 - cbar      - if empty, missing, no colourbar.  If an array of integers, then 
             indexes img array, and makes colourbar for each cmap for
             that img.  Cbars specified in order of appearance L->R
 - labels - struct can be:
                  - empty (-> default numerical labels)
                  - 'none' (string) (no labels) 
                  - or contain fields:
                  colour - colour for label text 
                  size - font size in units normalized to slice axes 
                  format - if = cell array of strings =
                  labels for each slice in Z.  If is string, specifies
                  sprintf format string for labelling in distance of the
                  origin (Xmm=0, Ymm=0) of each slice from plane containing
                  the AC, in mm, in the space of the transformed image
 - callback - callback string for button down on image panels. THe
              following examples assume that you have the 'userdata'
              field set to 1, giving you access to underlying object
              To print to the matlab window the equivalent position in
              mm of the position of a mouse click on one of the image
              slices, set callback to:
                   'get_pos(get(gcf, ''UserData''))'
              To print the intensity values of the images at the clicked point: 
                   ['so_obj = get(gcf, ''UserData''); ' ...
                    'point_vals(so_obj, get_pos(so_obj))'] 
 - printstr - string for printing slice overlay figure window, e.g.
              'print -dpsc -painters -noui' (the default)
 - printfile - name of file to print output to; default 'slices.ps'

 Action string formats:
 FORMAT [cmap warnstr] = slover('getcmap', cmapname)
 Gets colormap named in cmapname string

 FORMAT [mx mn] = slover('volmaxmin', vol)
 Returns maximum and minimum finite values from vol struct 'vol'

 FORMAT vol = slover('blobs2vol', XYZ, vals, mat)
 returns (pseudo) vol struct for 3d blob volume specified
 in matrices as above

 FORMAT vol = slover('matrix2vol', mat3d, mat)
 returns (pseudo) vol struct for 3d matrix 
 input matrices as above

 FORMAT obj = slover('basic_ui' [,dispf])
 Runs basic UI to fetch some parameters, does display, returns object
 If optional dispf parameter = 0, supresses display
 
 $Id: slover.m,v 1.2 2005/05/06 22:59:56 matthewbrett Exp $

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function [o, others] = slover(params, others, varargin)
0002 % class constructor for slice overlay (slover) object
0003 % FORMAT [o, others] = slover(params, others, varargin)
0004 %
0005 % Inputs
0006 % params    - either:
0007 %             - action string implementing class methods (see below)
0008 %             - array of image names / vol structs to display
0009 %             - structure with some fields for object (see below)
0010 % others    - structure, containing extra fields for object (or children)
0011 % varargin  - maybe some other parameters for action calls (see below)
0012 %
0013 % Outputs
0014 % o       - slover object
0015 % others  - any unrecognized fields from params, others
0016 %
0017 % Object fields are:
0018 %  - img - array of structs with information for images to display
0019 %        - img structs contain fields
0020 %             type - one of {'truecolour' 'split', 'contour'};
0021 %                   truecolour - displays transparent (see prop) image
0022 %                      overlaid with any previous
0023 %                   split - in defined area, replaces image present (SPM
0024 %                      type activation display)
0025 %                   contour - contour map of image overlaid.  See help
0026 %                      for contours function in matlab
0027 %             vol - vol struct info (see spm_vol)
0028 %                   can also be vol containing image as 3d matrix
0029 %                   set with add_blobs method
0030 %             cmap - colormap for this image
0031 %             nancol - color for NaN. If scalar, this is an index into
0032 %                    the image cmap.  If 1x3 vector, it's a colour
0033 %             prop - proportion of intensity for this cmap/img
0034 %             func - function to apply to image before scaling to cmap
0035 %                    (and therefore before min/max thresholding. E.g. a func of
0036 %                    'i1(i1==0)=NaN' would convert zeros to NaNs
0037 %             range - 2x1 vector of values for image to distribute colormap across
0038 %                    the first row of the colormap applies to the first
0039 %                    value in 'range', and the last value to the second
0040 %                    value in 'range'
0041 %             outofrange - behavior for image values to the left and
0042 %                    right of image limits in 'range'.  Left means
0043 %                    colormap values < 1, i.e for image values <
0044 %                    range(1), if (range(1)<range(2)), and image values >
0045 %                    range(1) where (range(1)>range(2)). If missing,
0046 %                    display min (for Left) and max (for Right) value from colormap.
0047 %                    Otherwise should be a 2 element cell array, where
0048 %                    the first element is the colour value for image values
0049 %                    left of 'range', and the second is for image values
0050 %                    right of 'range'.  Scalar values for
0051 %                    colour index the colormap, 3x1 vectors are colour
0052 %                    values.  An empty array attracts default settings
0053 %                    appropriate to the mode - i.e. transparent colour (where
0054 %                    img(n).type is truecolour), or split colour.  Empty cells
0055 %                    default to 0. 0 specifies that voxels with this
0056 %                    colour do not influence the image (split =
0057 %                    background, true = black)
0058 %            hold  - resampling order for image (see spm_sample_vol) -
0059 %                    default 1
0060 %            background - value when resampling outside image - default
0061 %                    NaN
0062 %            linespec - string, applies only to contour map,
0063 %                    e.g. 'w-' for white continuous lines
0064 %            contours - vector, applies to contour map only, defines
0065 %                    values in image for which to show contours
0066 %                    (see help contours)
0067 %            linewidth - scalar, width in points of contour lines
0068 %
0069 % - transform - either - 4x4 transformation to apply to image slice position,
0070 %             relative to mm given by slicedef, before display
0071 %               or     - text string, one of axial, coronal, sagittal
0072 %                        These orientations assume the image is currently
0073 %                        (after its mat file has been applied) axially
0074 %                        oriented
0075 % - slicedef - 2x3 array specifying dimensions for slice images in mm
0076 %             where rows are x,and y of slice image, and cols are neg max dim,
0077 %             slice separation and pos max dim
0078 % - slices   - vector of slice positions in mm in z (of transformed image)
0079 % - figure    - figure handle for slice display figure
0080 %               The object used for the display is attached as 'UserData'
0081 %               to this figure
0082 % - figure_struct - stored figure parameters (in case figure dies and
0083 %               needs to be recreated)
0084 % - refreshf  - flag - if set or empty, refresh axis info for figure
0085 %             else assume this is OK
0086 % - clf       - flag, non zero -> clear figure before display.  Redundant
0087 %               if refreshf == 0
0088 % - resurrectf - if not zero, and figure (above) does not exist, will
0089 %               attempt to recreate figure with same area properties.
0090 %               Otherwise painting will give an error.
0091 % - userdata  - flag, non zero -> attaches object to figure when ploting,
0092 %               for use by callbacks (default is 1)
0093 % - area      - struct with fields
0094 %                  position - bottom left, x size y size 1x4 vector of
0095 %                      area in which to display slices
0096 %                  units    - one of
0097 %                    inches,centimeters,normalized,points,{pixels}
0098 %                  halign - one of left,{center},right
0099 %                  valign - one of top,{middle},bottom
0100 % - xslices  - no of slices to display across figure (defaults to an optimum)
0101 % - cbar      - if empty, missing, no colourbar.  If an array of integers, then
0102 %             indexes img array, and makes colourbar for each cmap for
0103 %             that img.  Cbars specified in order of appearance L->R
0104 % - labels - struct can be:
0105 %                  - empty (-> default numerical labels)
0106 %                  - 'none' (string) (no labels)
0107 %                  - or contain fields:
0108 %                  colour - colour for label text
0109 %                  size - font size in units normalized to slice axes
0110 %                  format - if = cell array of strings =
0111 %                  labels for each slice in Z.  If is string, specifies
0112 %                  sprintf format string for labelling in distance of the
0113 %                  origin (Xmm=0, Ymm=0) of each slice from plane containing
0114 %                  the AC, in mm, in the space of the transformed image
0115 % - callback - callback string for button down on image panels. THe
0116 %              following examples assume that you have the 'userdata'
0117 %              field set to 1, giving you access to underlying object
0118 %              To print to the matlab window the equivalent position in
0119 %              mm of the position of a mouse click on one of the image
0120 %              slices, set callback to:
0121 %                   'get_pos(get(gcf, ''UserData''))'
0122 %              To print the intensity values of the images at the clicked point:
0123 %                   ['so_obj = get(gcf, ''UserData''); ' ...
0124 %                    'point_vals(so_obj, get_pos(so_obj))']
0125 % - printstr - string for printing slice overlay figure window, e.g.
0126 %              'print -dpsc -painters -noui' (the default)
0127 % - printfile - name of file to print output to; default 'slices.ps'
0128 %
0129 % Action string formats:
0130 % FORMAT [cmap warnstr] = slover('getcmap', cmapname)
0131 % Gets colormap named in cmapname string
0132 %
0133 % FORMAT [mx mn] = slover('volmaxmin', vol)
0134 % Returns maximum and minimum finite values from vol struct 'vol'
0135 %
0136 % FORMAT vol = slover('blobs2vol', XYZ, vals, mat)
0137 % returns (pseudo) vol struct for 3d blob volume specified
0138 % in matrices as above
0139 %
0140 % FORMAT vol = slover('matrix2vol', mat3d, mat)
0141 % returns (pseudo) vol struct for 3d matrix
0142 % input matrices as above
0143 %
0144 % FORMAT obj = slover('basic_ui' [,dispf])
0145 % Runs basic UI to fetch some parameters, does display, returns object
0146 % If optional dispf parameter = 0, supresses display
0147 %
0148 % $Id: slover.m,v 1.2 2005/05/06 22:59:56 matthewbrett Exp $
0149   
0150 myclass = 'slover';
0151 
0152 % Default object structure
0153 defstruct = struct('img', [], ...
0154            'transform', 'axial', ...
0155            'slicedef', [], ... 
0156            'slices', [], ...
0157            'figure', [], ...
0158            'figure_struct', [], ...
0159            'refreshf', 1, ...
0160            'clf', 1, ...
0161            'resurrectf', 1, ...
0162            'userdata', 1, ...
0163            'area', [], ...
0164            'xslices', [], ...
0165            'cbar', [], ...
0166            'labels', [], ...
0167            'callback', ';', ...
0168            'printstr', 'print -dpsc -painters -noui', ...
0169            'printfile', 'slices.ps');
0170 
0171 if nargin < 1
0172   o = class(defstruct, myclass);
0173   others = [];
0174   return
0175 end
0176 if nargin < 2
0177   others = [];
0178 end
0179 
0180 % parse out string action calls (class functions)
0181 if ischar(params)
0182   switch params
0183    case 'getcmap'
0184     if nargin < 2
0185       error('Need colormap name');
0186     end
0187     o = pr_getcmap(others);
0188     return
0189    case 'volmaxmin'
0190     if nargin < 2
0191       error('Need volume to calculate max/min');
0192     end
0193     [o others] = pr_volmaxmin(others);
0194     return
0195    case 'blobs2vol'
0196     if nargin < 4
0197       error('Need XYZ, vals, mat');
0198     end
0199     o = pr_blobs2vol(others, varargin{:});
0200     return
0201    case 'matrix2vol'
0202     if nargin < 3
0203       error('Need matrix and mat');
0204     end
0205     o = pr_matrix2vol(others, varargin{:});
0206     return
0207    case 'basic_ui'
0208     o = pr_basic_ui(others, varargin{:});
0209     if ~isempty(o), o = paint(o); end
0210     return
0211   end
0212   
0213   % if not action string, must be filename(s)
0214   params = spm_vol(params);
0215 end    
0216 
0217 % Could these just be image vol structs?
0218 if isfield(params, 'fname')
0219   for i = 1:prod(size(params))
0220     obj.img(i).vol = params(i);
0221   end
0222   params = obj;
0223 end
0224 
0225 % Deal with passed objects of this (or child) class
0226 if isa(params, myclass)
0227   o = params;
0228   % Check for simple form of call
0229   if isempty(others), return, end
0230 
0231   % Otherwise, we are being asked to set fields of object
0232   [p others] = mars_struct('split', others, defstruct);
0233   o = mars_struct('ffillmerge', o, p);
0234   return
0235 end
0236 
0237 % fill params with defaults, parse into fields for this object, children
0238 params = mars_struct('fillafromb', params, others);
0239 [params, others] = mars_struct('ffillsplit', defstruct, params);
0240 
0241 % set the slover object
0242 o  = class(params, myclass);
0243 
0244 % refill with defaults
0245 o = fill_defaults(o);
0246 
0247 return

Generated on Wed 06-Jul-2005 18:07:21 by m2html © 2003