Cef2Waterfall_v1_00(filename,out_choice,datadir,outdir);

%------------------------------------------------------------------------%
%  Program   : CEF 2 WATERFALL                                           %
%------------------------------------------------------------------------%
%  Measurement data analysis software created for                        %
%  the Amateur Radio Club PI4R as part of NVIS-propagation experiments.  %
%                                                                        %
%  Purpose A : To load measurement data from a file in the ITU           %
%              recommended "Common Exchange Format V2.0" into MatLab     %
%              workspace;                                                %
%          B : To display raw data as an RF spectrogram (waterfall).     %
%          C : To save the created graphs in EMF (picture) format.       %
%------------------------------------------------------------------------%
%  MatLab code version:  7.1                                             %
%------------------------------------------------------------------------%
%  External functions used: Cef2Mat v1.06   (see MatLab Central)         %
%------------------------------------------------------------------------%
%  Creation / modification history:                                      %
%  2008-08-26 - v0.01 - B.A.Witvliet - creation                          %
%  2009-01-07 - v1.00 - B.A.Witvliet - adaptation for general use and    %
%                                      publication on MatLab Central     %
%------------------------------------------------------------------------%
%  Conventions:                                                          %
%  - Every new author adds to the modification history, but does never   %
%    erase names of earlier contributors.                                %
%  - Arrays start with a capitol letter, single variables don't.         %                                                   %
%  - Main program names are all capitals, functions names only start     %
%    with a capital.                                                     %
%  - Subprograms are always functions, not scripts.                      %
%  - Global variables are avoided.                                       %
%  - This script may be used freely as long as the author is given       %
%    proper credit.                                                      %
%------------------------------------------------------------------------%

function [err,errmsg] = Cef2Waterfall_v1_00(filename,out_choice,datadir,outdir);

% --------------------
% OUTPUT CHOICES
% --------------------
% choice  result
% 1   save waterfall graph as file
% 2   show waterfall graph on screen
% 3   do both

% ------------------
% ERROR MESSAGES
% ------------------
% err  err_msg
% 0   OK
% 1   File retrieval error (No such file)
% 2   No CEF 2.0 file
% 3   CEF file header could not be read
% 4   CEF file body could not be read
% 5   Filename should be specified without extension
% 6   Invalid output directory


% -----------------------------------------
% PREDEFINITION OF ALL OUTPUT VARIABLES
% -----------------------------------------
err=0; 
err_msg='OK';


% ----------------------------------
% LOAD FILE INTO WORKSPACE
% ----------------------------------

% - Load CEF 2.0 file using external routine -
[Header,Data,err,errmsg] = Cef2Mat_v1_06(filename,datadir); 

% - If no problem encountered while loading file, start processing -
disp(' ');
if err~=0 
    return;
else
    
    % ----------------------------------
    % MULTISCAN PROCESSING
    % ----------------------------------

    % - Get number of scans and process them sequentially -
    for scannr=1:size(Header.FreqStart,2)

        % ----------------------------------
        % DATA SELECTION
        % ----------------------------------
        
        % - Select the receiver amplitude levels for this specific scan -
        Urx=Data.Level(:,:,scannr);  

        % - Get frequency information of this scan and convert to MHz -
        freqstart =Header.FreqStart(scannr)/1000; 
        freqstop  =Header.FreqStop(scannr)/1000;
        nrofpoints=Header.DataPoints(scannr);
        
        % - Create a frequency array -
        stepsize =(freqstop-freqstart)/(nrofpoints-1); 
        Frequency=freqstart:stepsize:freqstop;


        % ----------------------------------
        % DISPLAY RF SPECTROGRAM
        % ----------------------------------

        % - Prepare a fullscreen graph space -
        scrsz = get(0,'ScreenSize');  
        graph=figure('Position',scrsz);     
        hold on;                      
    
        % - Plot RF spectrogram -
        imagesc(Data.GMT,Frequency,Urx');                       
        axis([min(Data.GMT) max(Data.GMT) freqstart freqstop]); 
        colorbar;                                               

        % - Format start and stop timestamp for this measurement -
        startmeas=datestr(min(Data.GMT),31);
        stopmeas =datestr(max(Data.GMT),31);

        % - Create axis markers and labels -
        datetick('x',15);
        xlabel('Time [GMT] \rightarrow');
        ylabel('Frequency [MHz] \rightarrow');
        grid off;

        
        % ----------------------------------
        % CREATE GRAPH TITLE
        % ----------------------------------
        
        % - Get start and stop timestamp -
        startmeas=min(Data.GMT);
        stopmeas =max(Data.GMT);
        
        % - Convert timestamp to string containing date -
        startdate=datestr(startmeas,1);
        stopdate =datestr(stopmeas ,1);
        startdate=strrep(startdate,'-',' ');
        stopdate =strrep(stopdate, '-',' ');
       
        % - Convert timestamp to string containing time -
        starttime=datestr(startmeas,15);
        stoptime =datestr(stopmeas, 15);
        
        % - Differentiate between short and long measurements
        if startdate==stopdate
            period=[startdate '  ' starttime ' - ' stoptime];
        else
            period=[startdate '  ' starttime '  -  ' stopdate '  ' stoptime];
        end;
         
        % - Add graph title -
        title(['Frequency ' num2str(freqstart) ' - ' num2str(freqstop) ' MHz          ' period ' GMT']);
        
        
        
        % ----------------------------------
        % SAVE RF SPECTROGRAM
        % ----------------------------------
        
        % - Save if chosen output option is 1 or 3 -
        if out_choice~=2
            
            % - First test if output directory exists -
            test=size(dir(outdir),1);
            if test==0
                err=6; errmsg='Invalid output directory';
            else

                % ----------------------------------
                % CREATE FILENAME
                % ----------------------------------
        
                % - Get start and stop timestamp -
                startmeas=min(Data.GMT);
                stopmeas =max(Data.GMT);
        
                % - Convert timestamp to string containing date -
                startvec =datevec(startmeas);
                startdate=[num2str(startvec(1)) num2str(startvec(2),'%02.0f') num2str(startvec(3),'%02.0f')];
                starttime=[num2str(startvec(4),'%02.0f') num2str(startvec(5),'%02.0f')];
        
                % - Get start and stop frequency -
                freqstart=num2str(Header.FreqStart(scannr)); 
                freqstop =num2str(Header.FreqStop(scannr));
        
                % - Create constant length frequency strings -
                freqstart=['00000000' freqstart]; len=length(freqstart); freqstart=freqstart(len-7:len);
                freqstop =['00000000' freqstop];  len=length(freqstop);  freqstop =freqstop (len-7:len);

                % - Create filename
                filename=[ startdate '-' starttime '_' freqstart '-' freqstop ];
            
                % - Save graph as file -
                saveas(graph,[outdir '\' filename],'emf');
            end;
        end;
        
        % - Show graph if output option is 2 or 3 -
        if out_choice==1
            close(graph);
        end;
       
        
    end; %{multiscan processing}
end;