% <IMAGEWRITE> - Writes an image (img, tif or edf)
%
%   [<status>] = imagewrite(Im, filename, format, <header>, <colorDepth>)
%
%   status    : Optional output parameter (addition of multiples of 2)
%               0 - saving was not successfull
%               1 - saving was successfull
%               2 - file existed before, but was overwritten
%   Im        : Matrix (= image) of type R(n x m) to save
%               (n, m = 1, 2, ...)
%   filename  : Filename (+ path (absolute or relative)) of the file
%   format    : 'img'           - img format (without header) as .img
%               'tif' or 'tiff' - tif format as .tif with a header of
%                                 4096 bytes
%               'edf'           - edf format as .edf with a header of
%                                 1024 bytes (ESRF standard, but neither 
%                                 unique at the ESRF nor required by
%                                 the data format itself)
%   colorDepth: Color-depth of the image in number of bits
%               (default is 32 bit for PILATUS 2 images)
%               Values can be 8, 16, 32, or 64.
%               e.g. 16 for a 16 bit PILATUS 1 image.
%
%   <argument> depicts an optional argument
%
%   Note: This routine is not meant to create graphical output of pixel
%         data. The intention is to write data in a specific data format
%         with the precision needed (up to 64 bits per pixel are supported)
%         where, in case of tif and edf, you also can store information in
%         the header, e.g., information on the scan or the beamline, etc. 

%==========================================================================
%
% FUNCTION: imagewrite.m
%           ============
%
% $Date: 2006/12/11 12:41:33 $
% $Author: herger $
% $Revision: 1.4 $
% $Source: /import/cvs/X/PILATUS/App/lib/X_PILATUS_Matlab/imagewrite.m,v $
% $Tag: $
%
%
% <IMAGEWRITE> - Writes an image (img, tif or edf)
%
% Author(s):            R. Herger (RH)
% Co-author(s):         C.M. Schlepuetz (CS)
% Address:              Swiss Light Source (SLS)
%                       Paul Scherrer Institute
%                       CH - 5232 Villigen PSI
% Created:              2005/06/29
%
% Change Log:
% -----------
%
% 2005/09/29 (RH):
% - documentation added
% - workaround for format = 'ff': same as 'tif', but with extension _ff.tif
% - checked: Im can be of type R(1 x m) or R(n x 1) for tif, jpg & (e)ps
%
% 2006/02/20 (RH):
% - tif, jpg, etc still do not work
% - but .img can now write uint16, uint32 and double data.
% - workaround for Phil completed
%
% 2006/10/17 (RH):
% - redesign of function: (not working) graphical output routines for jpg,
%   eps and ff are gone. The function can store data in different bit 
%   depths (up to 64 bits). For tif and edf, one can also write a header
%   of a fixed size (might be changed in a later version).
% - tif (header: 4096 bytes) and edf (header: 1024 bytes) can be written
% - tested formats with imagewrite and imageread, and for different bit
%   depths 
%
% 2006/12/11 (RH):
% - added cvs tag information for first release

%==========================================================================
%  Main function - <imagewrite>
%                  ============

function [status] = imagewrite (Im, filename, format, header, colorDepth)


% close handle automatically created by function command
fighandle=gcf;
close(fighandle);

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

% are there 3 or 5 input arguments?
error(nargchk(3, 5, nargin))

% is colorDepth equal to 8, 16, 32, or 64?
if (nargin < 5)
    colorDepth = 32;
end;
if (colorDepth ~= 8 && colorDepth ~= 16 && ...
        colorDepth ~= 32 && colorDepth ~= 64 && ...
        colorDepth ~= -1)
    error(strcat('Invalid input for ''colorDepth'' in function imagewrite.', ...
        '\nUse ''help imagewrite'' for further information.'), ...
        '');
end;

if (nargin < 4)
    header = [];
end;


% check if Im contains only integer values. If not, store Im as double.
if ((colorDepth == -1) || (sum(sum(rem (Im, 1))) > 0))
    colorDepthFormat = 'double';
else
    switch colorDepth
        case 8
            colorDepthFormat = 'uint8';
        case 16
            colorDepthFormat = 'uint16';
        case 32
            colorDepthFormat = 'uint32';
        case 64
            colorDepthFormat = 'uint64';
    end
end

% is Im a n x m matrix (n, m = 1, 2, ...)?
if (ndims(Im)~=2)
    error(strcat('Invalid input for ''Im'' in function imagewrite.\n', ...
        'Use ''help imagewrite'' for further information.'), ...
        '');
end

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

% is format img, tif, tiff or ff?
% compformat is a binary (logical) comparator variable
str2test = lower(format);
if ((strcmp(str2test,'tif') | strcmp(str2test,'tiff') | ...
        strcmp(str2test,'img') |strcmp(str2test,'edf')) ~= 1)
    error(strcat('Invalid input for ''format'' in function imagewrite.\n', ...
        'Use ''help imagewrite'' for further information.'), ...
        '');
end



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

% are 1 or 0 output argument specified?
error(nargoutchk(0, 1, nargout))

% find a the dot in the filename if specified. Cut extension and dot
% (will be added later to assure the same extensions).
dotpos=strfind(filename, '.');
if (~isequal(dotpos, []))
    filename=filename(1:dotpos(end)-1);
end;

% initialize status argument to 0
status=0;

% initialisz length of headers
% Note that the ESRF data format (EDF) header has been arbitrarily
% set to 1024 bytes since this is the most common implementation
% at the ESRF. Nevertheless, the EDF data format can store more than
% one header (and therefore more than one image) of n*512 bytes in
% one file.
% The description of the EDF can be found at:
% http://www.esrf.fr/computing/expg/subgroups/general/format/Format.html
edfheaderlength = 1024;
tifheaderlength = 4096;

%-----------
% write image

% determine the length of the header in bytes (stored in
% headerstruct.bytes) and the size (headerstruct.size)
headerstruct = whos('header');

% prepare the file for data dumping.
% 1. Check if file exists.
% 2. For tif and edf: check header
% 3. Leave the file open for data dump
switch lower(format)

    % check and write tif header
    case {'tif', 'tiff'}
        filename = strcat(filename, '.tif');
        % check if file already exists
        if(exist(filename, 'file')==2)
            wid = sprintf('File:%s:Exists', filename);
            warning(wid, 'File %s exists and will be overwritten!', filename);
            status=status+2;
        end;
        filehandle=fopen(filename, 'w');
        % if header is too long, cut down
        if (headerstruct.bytes > tifheaderlength)
            wid   = sprintf('Header:TooLong');
            part1 = sprintf('Header contains more than %g bytes.', edfheaderlength);
            part2 = sprintf('Actual header length is %g bytes.', headerstruct.bytes);
            part3 = sprintf('Only the first %g bytes of the header will be stored.', edfheaderlength);
            warning(wid, '%s\n%s\n%s', part1, part2, part3);
            headerstring = header(1:tifheaderlength);
        else
            % if header short enough, fill rest with blanks
            endpos = tifheaderlength - headerstruct.size(2);
            headerstring = [header, blanks(endpos)];
        end
        % write header to file
        fwrite(filehandle, headerstring, '*char');

    % check and write edf header
    case 'edf'
        filename=strcat(filename, '.edf');
        % check if file already exists
        if(exist(filename, 'file')==2)
            wid = sprintf('File:%s:Exists', filename);
            warning(wid, 'File %s exists and will be overwritten!', filename);
            status=status+2;
        end;
        filehandle=fopen(filename, 'w');
        % if header is too long, cut down
        if (headerstruct.bytes > edfheaderlength)
            wid   = sprintf('Header:TooLong');
            part1 = sprintf('Header contains more than %g bytes.', edfheaderlength);
            part2 = sprintf('Actual header length is %g bytes.', headerstruct.bytes);
            part3 = sprintf('Only the first %g bytes of the header will be stored.', edfheaderlength);
            warning(wid, '%s\n%s\n%s', part1, part2, part3);
            headerstring = header(1:edfheaderlength);
        else
            % if header short enough, fill rest with blanks
            endpos = edfheaderlength - headerstruct.size(2);
            headerstring = [header, blanks(endpos)];
        end
        % write header to file
        fwrite(filehandle, headerstring, '*char');

    % prepare for an img
    case 'img'
        % check if file already exists
        filename=strcat(filename, '.img');
        if(exist(filename, 'file')==2)
            wid = sprintf('File:%s:Exists', filename);
            warning(wid, 'File %s exists and will be overwritten!', filename);
            status=status+2;
        end;
        filehandle=fopen(filename, 'w');
end

% write the data to the file
fwrite(filehandle, Im', colorDepthFormat);
if(exist(filename, 'file') == 2)
    if (status < 2)
        [status]=status+1;
    end
    % close the file
    fclose(filehandle);
else
    [status]=0;
end;

%==========================================================================
%
%---------------------------------------------------%
% 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: imagewrite.m,v $
% Revision 1.4  2006/12/11 12:41:33  herger
% cvs tag information added
%
% Revision 1.3  2006/10/17 12:54:41  herger
% edf, tif and img can now be written in different bit depths
%
% Revision 1.2  2006/02/20 16:47:31  herger
% JAWA for Phil. Not fully working version.
%
% Revision 1.1  2005/09/29 10:31:37  herger
% matlab function to write an image (tif, jpg, (e)ps, ff)
%
%
%================================= End of imagewrite.m ================