% <READSCANLOG> - Reads a MS BL scanlog file
%
%   [Data, header] = readscanlog(filename)
%
%   Data    : Contains all the values, which where saved in the 
%             scanlog-file. Data is a m-by-n matrix of doubles, where m is
%             the number of datapoints and n the number of different
%             parameters.
%             Note: The last 6 columns contain the time information. The
%             'timestamp' of the scanlog file is split up to a MATLAB
%             date vector of the form [yyyy, mm, dd, HH, MM, SS], in
%             order to simplify calculations. To get back to a readable
%             time information, use MATLAB's date manipulation functions
%             e.g. mydates = datestr(datenum(Data(:,15:20)), ...
%                                    'yyyy-mm-dd HH:MM:SS')
%   header  : Contains the header information of the scanlog file. 
%             header is a 1-by-n cell-array of strings, the columns of 
%             header correspond to those of Data.      
%
%             myheader = 
% 
%                 Columns 1 through 5
%
%                    'point'    'image'    'Opto'    'CH0'    'corrInt'
%
%             To use e.g. the 'Opto' column, use:
%
%             >> optoColumn = strcmpi(header,'opto');
%             >> opto       = Data(:,optoColumn); 
%
%   filename: Filename (+ path (absolute or relative)) of the scanlog
%             file to be read as string.
%             e.g. '/home/sto/scanlogs/sto_0904_12345_log.dat'
%
%   Note: The number of columns containing numbers may vary (for 
%         historical reasons), but readscanlog.m assumes that the 
%         last column is the timestamp information.
%
%   See also:
%   ---------
%   DATEVEC (Transforms a date-string to a date-vector)
%   DATESTR (Transforms a date-vector to a date-string)


%==========================================================================
% 
% FUNCTION: readscanlog.m 
%           =============
%
% $Date: 2006/10/23 08:57:08 $
% $Author: pauli_s $
% $Revision: 1.1 $
% $Source: /import/cvs/X/PILATUS/X04SA/App/lib/X_PILATUS_X04SA_Matlab/readscanlog.m,v $
%
%
% <READSCANLOG> - Reads a MS BL scanlog file
% 
% Author(s):            R. Herger (RH)
% Co-author(s):         C.M. Schlepuetz (CMS)
%                       P.R. Willmott (PRW)
%                       S.A. Pauli (SAP)
% Address:              Swiss Light Source (SLS)
%                       Paul Scherrer Institute
%                       CH - 5232 Villigen PSI
% Created:              2004/10/27
% 
% Change Log:
% -----------
% 
% 2005/10/27 (RH):
% - start
%
% 2005/10/28 (RH):
% - first running version finished, checked in
%
% 2006/02/10 (RH & PRW): 
% - Corrected while loop for reading data to data file so that the first
%   line is read 
%
% 2006/04/26 (SAP)
% - Old and new Logfiles are now readable
%
% 2006/09/19 (SAP)
% - corrected "orange errors"
%
% 2006/10/13 (SAP)
% - PILATUS I scanlogfiles haven't had the filtersettings as a hexadecimal
% number but as a binary number, therefore I made an extra if statement in
% order both files are readable, all filtersettings are now binary.
%
% 2006/10/19 (SAP)
% - Added helptext
%
% 2006/10/23 (SAP)
% - Check for existence of filename is no done via exist commmand.

%==========================================================================
%  Main function - <readscanlog>
%                  =============

function [Data, header] = readscanlog(filename)

%----------------------
% check input arguments

% are there only 1 input argument1?
error(nargchk(1, 1, nargin))

% is filename of type string?
if(~ischar(filename))
  error(strcat('Invalid input for ''filename'' in function readscanlog.\n', ...
               'Use ''help readscanlog'' for further information.'), ...
               '');
end

%----------------------
% check output argument

% are 2 output argument specified?
error(nargoutchk(2, 2, nargout))


%------------------
% read scanlog file

% check if file exists
if(exist(filename, 'file') == 0);
    eid = sprintf('File:%s:DoesNotExist',  filename);
    error(eid, 'File %s does not exist!', filename);
end;

% open and read the file
[slhandle] = fopen(filename);

% prepare some variables
exit = 0;
[head] = fgetl(slhandle);
[line] = fgetl(slhandle);

% skip repeated first lines, if present
while (exit == 0) 
  cmp = strcmp (head, line);
  if (cmp == 0)
    exit = 1;
  else
    [head] = line;
    [line] = fgetl(slhandle);
  end;
end;

% remove the starting #-sign, if present
hash=strncmp(head, '#', 1);
if (hash == 1)
  head(1) = ' ';
end;

% Create header array using strread
% Specially treated: 'timestamp' -> ['yyyy', 'mm', 'dd', 'HH', 'MM', 'DD'] in
% order to work with MATLAB's date functions (datevec, datestr, datenum)

[token] = strread(head,'%s');
header = [token(~strcmpi(token,'timestamp')); ...
                 {'yyyy';'mm';'dd';'HH';'MM';'SS'}];
 
% Transpose header so that header and data file have the same no. of
% columns
[header] = header';

%------------------
% Create data array

% prepare some variables
Dat = zeros(size(header));
endoffile = 0;
q = 1;

% All numbers are converted from string to doubles. Special treatment is
% done for the filtersettings and the timestamp, because the varied over
% the time.
% The filter settings are of type double, altough its value is binary:
% e.g. filter = 10011, use num2str(filter) to use it as a binary.
% The timestamp information is read out manually and converted to a
% MATLAB date vector. Each entry (yyyy, dd, mm, HH, MM, SS) is
% saved in a new column so that numbers  can be used for calculation
% (e.g. If you want to use the time information for an estimation
% of the radiation damage)
while (endoffile == 0)
    
    % check of the end of file is reached
    if (line == -1);      
        endoffile = 1;
    else

        % transform the string, containing the information of one line in 
        % the scanlogfile to a cell of strings
        token = strread(line,'%s')';
        
        % conditional-statement, if the timestamp in the scanlogfile is 
        % written in a matlab-readable manner or not.
        if size(token{end},2) > 4
            date = datevec(token(end),'yyyy-mm-ddTHH:MM:SS');
            re = 0;
        else
            yyyy = token(end);
            mmm  = token(end-3);
            dd   = token(end-2);
            time = token(end-1);
            datestring = sprintf ('%2s/%2s/%4s %s', ...
                mmm{1}, dd{1}, yyyy{1}, time{1});
            date = datevec(datestring);
            re = 4;
        end;
        
        % look after hexadecimal values (filtersettings)
        x = strmatch('0x',token);

        % if there isn't a hexadecimal value, then the filter-settings were
        % written in a binary-string, so all strings can be transformed to
        % doubles
        if isempty(x)
            Dat(q,1:(numel(token)-re-1)) = ...
                cellfun(@str2double,token(1:(end-re-1)) );

        % if there was a hexadecimal value, then transform it to a binary,
        % and transform all the strings to doubles
        else
            token{x} = strrep(token{x},'0x','');
            Dat(q,1:x-1) = cellfun(@str2double,token(1:x-1));
            Dat(q,x) = cellfun(@(i)str2double(dec2bin(hex2dec(i))),token(x));
            Dat(q,x+1:numel(token)-re-1) = ...
                cellfun(@str2double,token(x+1:end-re-1) );
        end;

        % the last entries for the timestamp
        Dat(q,numel(token)-re:size(header,2)) = date;
        q = q + 1;
    end;
    
    % Get the next line of the scanlogfile
    line = fgetl(slhandle);
end;

% Fill the return variable
[Data] = Dat;

% Close the scanlog file
fclose (slhandle);

% Clear some variables
clear slhandle exit head line cmp hash token remain endoffile x q l;
clear mmm dd time yyyy date Dat;


%==========================================================================
%
%---------------------------------------------------%
% emacs setup:  force text mode to get no help with %
%               indentation and force use of spaces %
%               when tabbing.                       %
% Local Variables:                                  %
% mode:text                                         %
% indent-tabs-mode:nil                              %
% End:                                              %
%---------------------------------------------------%
%
% $Log: readscanlog.m,v $
% Revision 1.1  2006/10/23 08:57:08  pauli_s
% Pilatus I compability, added help text
%
% Revision 1.4  2006/08/17 14:30:57  pauli_s
% corrected orange errors
%
% Revision 1.3  2006/04/26 10:08:23  pauli_s
% old and new scanlogs are now readable
%
% Revision 1.2  2006/02/10 14:48:51  willmott
% corrected while loop for reading data
%
% Revision 1.1  2005/10/28 14:29:48  herger
% matlab function: reads a MS BL scanlog file
%
%
%================================= End of readscanlog.m ===================