GetPositions

GetPositions - Get position samples.

  USAGE

    positions = GetPositions(<options>)

    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'mode'         'all' gets all position samples, 'clean' discards bad
                    position samples (lights undetected, out of boundaries,
                    too close, etc. - see SETTINGS) (default 'clean')
     'coordinates'  'video' gets position samples in video frame coordinates
                    (e.g., [0..368]x[0..284]), 'normalized' uses normalized
                    values (i.e. [0..1]x[0..1]), 'real' converts pixels to
                    centimeters (default 'normalized')
     'pixel'        size of the video pixel in cm (no default value)
     'discard'      discard position samples when one or more LED is missing
                    ('partial', default) or only when no LEDs are detected
                    ('none', coordinates for missing LEDs are set to NaN)
     'distances'    min and max distances [m M] allowed between LEDs
                    (in pixels, default [0 Inf])
    =========================================================================

  EXAMPLES

    p = GetPositions;
    p = GetPositions('mode','all');

  CUSTOM DEFAULTS

    Properties 'mode', 'coordinates', 'pixel' and 'distances' can have custom
    default values (type 'help <a href="matlab:help CustomDefaults">CustomDefaults</a>' for details).

0001 function positions = GetPositions(varargin)
0002 
0003 %GetPositions - Get position samples.
0004 %
0005 %  USAGE
0006 %
0007 %    positions = GetPositions(<options>)
0008 %
0009 %    <options>      optional list of property-value pairs (see table below)
0010 %
0011 %    =========================================================================
0012 %     Properties    Values
0013 %    -------------------------------------------------------------------------
0014 %     'mode'         'all' gets all position samples, 'clean' discards bad
0015 %                    position samples (lights undetected, out of boundaries,
0016 %                    too close, etc. - see SETTINGS) (default 'clean')
0017 %     'coordinates'  'video' gets position samples in video frame coordinates
0018 %                    (e.g., [0..368]x[0..284]), 'normalized' uses normalized
0019 %                    values (i.e. [0..1]x[0..1]), 'real' converts pixels to
0020 %                    centimeters (default 'normalized')
0021 %     'pixel'        size of the video pixel in cm (no default value)
0022 %     'discard'      discard position samples when one or more LED is missing
0023 %                    ('partial', default) or only when no LEDs are detected
0024 %                    ('none', coordinates for missing LEDs are set to NaN)
0025 %     'distances'    min and max distances [m M] allowed between LEDs
0026 %                    (in pixels, default [0 Inf])
0027 %    =========================================================================
0028 %
0029 %  EXAMPLES
0030 %
0031 %    p = GetPositions;
0032 %    p = GetPositions('mode','all');
0033 %
0034 %  CUSTOM DEFAULTS
0035 %
0036 %    Properties 'mode', 'coordinates', 'pixel' and 'distances' can have custom
0037 %    default values (type 'help <a href="matlab:help CustomDefaults">CustomDefaults</a>' for details).
0038 
0039 % Copyright (C) 2004-2014 by Michaël Zugaro
0040 %
0041 % This program is free software; you can redistribute it and/or modify
0042 % it under the terms of the GNU General Public License as published by
0043 % the Free Software Foundation; either version 3 of the License, or
0044 % (at your option) any later version.
0045 
0046 global DATA SETTINGS;
0047 if isempty(DATA),
0048     error('No session defined (did you forget to call SetCurrentSession? Type ''help <a href="matlab:help Data">Data</a>'' for details).');
0049 end
0050 
0051 % Default values (customizable defaults must be empty at this point)
0052 mode = '';
0053 coordinates = '';
0054 pixel = [];
0055 distances = [];
0056 discard = 'partial';
0057 
0058 if mod(length(varargin),2) ~= 0,
0059     error('Incorrect number of parameters (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0060 end
0061 
0062 % Parse options
0063 for i = 1:2:length(varargin),
0064     if ~ischar(varargin{i}),
0065         error(['Parameter ' num2str(i+1) ' is not a property (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).']);
0066     end
0067     switch(lower(varargin{i})),
0068         case 'mode',
0069             mode = lower(varargin{i+1});
0070             if ~isastring(mode,'clean','all'),
0071                 error('Incorrect value for property ''mode'' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0072             end
0073         case 'coordinates',
0074             coordinates = lower(varargin{i+1});
0075             if ~isastring(coordinates,'video','normalized','real'),
0076                 error('Incorrect value for property ''coordinates'' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0077             end
0078         case 'pixel',
0079             pixel = varargin{i+1};
0080             if ~isdscalar(pixel,'>0'),
0081                 error('Incorrect value for property ''pixel'' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0082             end
0083         case 'discard',
0084             discard = lower(varargin{i+1});
0085             if ~isastring(discard,'partial','none'),
0086                 error('Incorrect value for property ''discard'' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0087             end
0088         case 'distances',
0089             distances = lower(varargin{i+1});
0090             if ~isdvector(distances,'#2','>=0'),
0091                 error('Incorrect value for property ''distances'' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).');
0092             end
0093         otherwise,
0094             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).']);
0095     end
0096 end
0097 
0098 % Customizable defaults (if not already set)
0099 mode = GetCustomDefaults(mode,'mode','clean');
0100 coordinates = GetCustomDefaults(coordinates,'coordinates','normalized');
0101 pixel = GetCustomDefaults(pixel,'pixel',[]);
0102 distances = GetCustomDefaults(distances,'distances',[0 Inf]);
0103 
0104 minDistance = distances(1);
0105 maxDistance = distances(2);
0106 
0107 if strcmp(coordinates,'real') & isempty(pixel),
0108     error(['Missing ''pixel'' property-value pair (type ''help <a href="matlab:help GetPositions">GetPositions</a>'' for details).']);
0109 end
0110 
0111 positions = DATA.positions;
0112 if isempty(positions), return; end
0113 
0114 % Discard positions with incorrect distance between lights
0115 if strcmp(mode,'clean'),
0116     if size(positions,2) == 5,
0117         % Two head lamps
0118         distance = sqrt((positions(:,4)-positions(:,2)).^2+(positions(:,5)-positions(:,3)).^2);
0119         selected = ( ...
0120                 distance >= minDistance ...
0121                 & distance <= maxDistance ...
0122             );
0123         positions = positions(selected,:);
0124     end
0125 end
0126 
0127 % Mark undetects (by convention, values of -1)
0128 if strcmp(discard,'none'),
0129     undetected = all(positions(:,2:end) == -1,2);
0130     partiallyDetected = positions == -1;
0131     positions(partiallyDetected) = NaN;
0132 else
0133     undetected = any(positions(:,2:end) == -1,2);
0134 
0135 end
0136 %  positions(undetected,2:end) = -1; % Make sure all values are -1
0137 good = ~undetected;
0138 
0139 % Clip if necessary (but issue warning)
0140 m = min(positions(good,2:end));
0141 M = max(positions(good,2:end));
0142 if any(m<0)||any(M(1:2:end)>DATA.maxX|M(2:2:end)>DATA.maxY),
0143     warning(['Position data should stay within [0,' num2str(DATA.maxX) ']x[0,' num2str(DATA.maxY) ']. The data will now be clipped accordingly.']);
0144     positions(good,2) = Clip(positions(good,2),0,DATA.maxX);
0145     positions(good,3) = Clip(positions(good,3),0,DATA.maxY);
0146 end
0147 
0148 if strcmp(coordinates,'normalized'),
0149     % Normalize coordinates
0150     maxima = [DATA.maxX DATA.maxY];
0151     positions(good,2:end) = positions(good,2:end) ./ repmat(maxima,sum(good),(size(positions,2)-1)/2);
0152 elseif strcmp(coordinates,'real'),
0153     % Convert to cm
0154     positions(good,2:end) = positions(good,2:end) * pixel;
0155 end
0156 
0157 % Discard undetects
0158 if strcmp(mode,'clean'),
0159     positions(undetected,:) = [];
0160 end