Matthias Pospiech

LaTeX-Einführung

pospiech — Sun, 13 May 2012 17:46:32 +0000

Die folgenden Folien und Übungen wurden in einer zweitägigen Einführung von LaTeX verwendet. Die Zielausrichtung lag auf der Erstellung von einfachen Protokollen mit Ausblicken auf Themen, die bei Bachelor und Masterarbeiten relevant sind.

Note: There is a file embedded within this post, please visit this post to download the file.
Note: There is a file embedded within this post, please visit this post to download the file.

Die Inhalte entsprechen im Wesentlichen denen aus der letzen Einführung.

Der gesamte Umfang beträgt ca. 6 Stunden inklusive der Übungen. Um die maximale Aufmerksamkeitszeitdauer von 3-4 Stunden nicht zu überziehen wurde der Workshop an zwei Tagen mit jeweils drei Stunden durchgeführt.

Beim nächsten Mal würde ich gerne noch die magic comments einführen oder zumindest zeigen. Sie wurden nicht unbedingt benötigt, aber ich habe sie in den Beispieldateien verwendet ohne sie zu erklären.

pcolor and contour plot with different colormaps

pospiech — Sun, 11 Mar 2012 18:25:18 +0000

Matlab does not allow to combine use more than one colormap in a figure. However there are some possibilities to get around this problem, which are presented in this article.

Initilisation and export of figure

For all plots the same initialisation for the data and the figure is used:

% clear command window, figures and all variables
clc; clf; clear all; 
 
%% Common variables
 
FontSize = 12;
FontName = 'MyriadPro-Regular'; % or choose any other font
 
doExportPlot = true;
 
%% Plot variables
SaveDir = '';
 
TITLE = '';
    xLabelText = 'x-values';
    yLabelText = 'y-values';
    zLabelText = 'function values';
 
 
%%
SaveDir = '';
BaseDir = '';
%% Create Data
[x y data] = peaks(1000);
data = data - min(min(data));
data = data / max(max(data));
 
%% start plot
 
% figure dimensions in cm. I choose 1.5 or 2 times 
% the target size typically. If figure is display in
% document much smaller increase the fontsize.
 
figure_width = 14;  
figure_height = 10;
 
% --- setup plot windows
figuresVisible = 'on'; % 'off' for non displayed plots (will still be exported)
hfig = figure(1); clf;
    set(hfig,'Visible', figuresVisible)
 
    set(hfig, 'units', 'centimeters', 'pos', [5 5 figure_width figure_height])   
    set(hfig, 'PaperPositionMode', 'auto');    
    set(hfig, 'Renderer','zbuffer'); 
    set(hfig, 'Color', [1 1 1]); % Sets figure background
    set(gca, 'Color', [1 1 1]); % Sets axes background
 
% --- dimensions and position of plot 
hsp = subplot(1,1,1, 'Parent', hfig);
set(hsp,'Position',[0.12 0.15 0.80 0.8]);
 
colorDepth = 1000;

And the same code is used to style the plot and export the figure:

%%  setup axis plot properties
% shading interp; % interpolate pixels
axis on;      % display axis
axis tight;   % no white borders
 
set(gca, ...
    'Box'         , 'on'      , ...
    'TickDir'     , 'in'      , ...
    'TickLength'  , [.02 .02] , ...
    'XMinorTick'  , 'off'      , ...
    'YMinorTick'  , 'off'     , ...
    'XGrid'       , 'off'     , ...
    'YGrid'       , 'off'     , ...
    'XColor'      , [.0 .0 .0], ...
    'YColor'      , [.0 .0 .0], ...
    'LineWidth'   , 0.6        );
 
%% axis scales
 
% set(gca,'XTick',-15:5:15)
% set(gca,'YTick',-10:5:10)
 
%% label texts
 
% save handles to set up label properties
hTitle = title(TITLE);
hXLabel = xlabel(xLabelText);
hYLabel = ylabel(yLabelText);
 
%% set properties for all handles
set([gca, hTitle, hXLabel, hYLabel], ...
    'FontSize'   , FontSize    , ...
    'FontName'   , FontName);
 
 
%% last 'bug' fixes
 
% bring axis on top again (fix matlab bug)
set(gca,'Layer', 'top');
 
%% export
drawnow
 
doExportPlot = true;
if (doExportPlot)
    IMAGENAME = [SaveDir SaveName]; 
    print(hfig, ['-r' num2str(400)], [IMAGENAME '.png' ], ['-d' 'png']);    
end

Next page: “contour with white lines”

plotyy with unequal tick locations for both datasets

pospiech — Sun, 12 Feb 2012 22:08:08 +0000

In matlab the normal way to create plots with two y-axis is to use the command plotyy.

This works quite simple, and creates equal tick locations for both data sets:

xaxis = 0:0.1:25;
y1 = linspace(12.1712,12.7679, length(xaxis));
y2 = linspace(0.3597,-28.7745, length(xaxis));
 
[AX,H1,H2] = plotyy(xaxis, y1, xaxis, y2);
 
plotstyle; % sets only colors, linestyle and fonts

However for tick that are not equal on both sides the plot looks simply wrong.

[AX,H1,H2] = plotyy(xaxis, y1, xaxis, y2);
 
% axis limits - x axis (min to max)
set(AX, 'XLim', [min(xaxis) max(xaxis)]);
set(AX(2),'XTick',[]);
 
% y1 axis limits 
set(AX(1), 'YLim', [min(y1) max(y1)]);
 
% y2 axis limits 
set(AX(2), 'YLim', [min(y2) max(y2)]);
 
plotstyle;

Unfortunately the web is full of question on how to remove the ticks on the opposite side. But Matlab completely fails at this point. It is simply not supported properly.

The only solution I could find/retrieve in a forum was the following one, which is based on the idea to remove the box property which paints the ticks on the opposite side. But it also removes the surrounding box, which is unwanted.

set(AX(1),'Box','off') % Turn off box of axis 1, which removes its right-hand ticks
set(AX(2),'Box','off') % Turn off box of axis 2, which removes its left-hand ticks

Another idea I found in this thread is to work with dummy axes, but I do not see how to integrate it with my plot function (the plot is empy after I execute this code)

% dummy axes for the box and background color 
ax0 = axes; 
set (ax0, 'Box', 'on', 'Color', 'white', 'XTick', [], 'YTick', []); 
% first axes for left y-axis 
ax1 = axes ('Position', get (ax0, 'Position')); 
set (ax1, 'Box', 'off', 'Color', 'none', 'YAxisLocation', 'left'); 
% second axes for right y-axis assuming common x-axis controlled by ax1 
ax2 = axes ('Position', get (ax0, 'Position')); 
set (ax2, 'Box', 'off', 'Color', 'none', 'XTick', [], 'YAxisLocation', 'right');

Any hints or other solutions are welcome. please use this thread on stackoverflow.com for adding answers on your own.

pcolor plots with publication ready formating

LaTeX-Workshop

pospiech — Mon, 06 Feb 2012 21:15:03 +0000

Die folgenden Folien und Übungen dienten zur eintägigen Einführung von LaTeX für die Erstellung von Bachelor und Masterarbeiten.

Note: There is a file embedded within this post, please visit this post to download the file.
Note: There is a file embedded within this post, please visit this post to download the file.

In einem Tag (Samstag von 10:00-16:00 Uhr) reicht natürlich nicht alle Grundlagen von LaTeX mit den wichtigsten Details vorzustellen. Die Inhalte waren:

LaTeX, Programme, Bedienung des Editors.
Grundlagen: Syntax von Klassen, Befehlen, Umgebungen und Sonderzeichen. Aufbau von LaTeX Dokumenten
Textsatz: Überschriften, Inhaltsverzeichnis, Paragraphen, Listen, Befehle.
Schriften: Stile, Größen, Schriftwahl
Querverweise
Aufteilung komplexer Dokumente
Mathematik: Umgebungen, Typographie, Einheiten, Verweise
Einbindung und Positionierung von Bildern: Gleitumgebungen, Abbildungsverzeichnis, draft Modus, Bildgröße.
Tabellen: Syntax, Linien, Spaltenumbruch, Tabellenumgebung, Schöne Tabellen. Farbe.

Nicht vorgestellt wurde die Erstellung von Literaturverzeichnissen, die in diesem Workshop ausführlich dargestellt wurde. Darüberhinaus sind viele der hier fehlenden Themen in der mehrtägigen Vorlesung zu LaTeX enthalten.

Im Gegensatz zum letzen Einführungsworkshop sind einige Themen dazugekommen. Darunter die Querverweise, die Aufteilung mittels input und include und die Abschnitte zu Bildern und Tabellen sind deutlich erweitert.

Der ganze Umfang sollte 5-6 Stunden inklusive der Übungen einehmen. Bis zur Mittagspause (nach 3 Stunden) waren die Inhalte bis zur Aufteilung durchgenommen worden. Die Aufteilung und die Mathematik haben relativ lange gedauert, da insbesondere die Übung zur Mathematik zu umfangreich war. Damit waren mehr als 4 Stunden vergangen und es zeigte sich, dass die Studenten zu müde für die Abschnitte für Bilder und Tabellen waren. Dies Abschnitte habe ich dann nur noch vorgestellt, aber die Übungen mit einem Umfang von 1-2 Stunden konnten nicht mehr durchgenommen werden. Als Fazit lässt sich somit festhalten, dass mehr als 4 Stunden schwierig umzusetzen sind.

Erstellung von Bachelor und Masterarbeiten mit LaTeX

pospiech — Fri, 09 Dec 2011 07:22:29 +0000

Im Rahmen meiner Lehrverpflichtungen an der Leibniz Universität Hannover habe ich die folgende Vorlesung zur Erstellung von Bachelor und Masterarbeiten mit LaTeX gehalten

Note: There is a file embedded within this post, please visit this post to download the file.
Note: There is a file embedded within this post, please visit this post to download the file.

Die Verlesung richtetete sich an Studenten mit Vorkenntnissen in LaTeX, da die Inhalte hier die speziellen Probleme beim Schreiben von Abschlussarbeiten sein sollten. Effektiv habe ich aber auch grundlegende Kenntnisse wiederholt. Die folgenden Kenntnisse wurde in der Vorlesungsankündigung vorausgesetzt:

Syntax von Klassen, Befehlen, Umgebungen und Sonderzeichen
Grundlegende Pakete für die Präambel (babel, inputenc, graphicx, amsmath, . . .).
Textsatz (Kapitel, Abschnitte, Listen, Paragraphen)
Mathematik: einzeilige Formeln
Einbinden von Bildern
einfache Tabellen

Dementsprechend waren die teilnehmenden Studenten mehrheitlich am Ende ihres Bachelor oder Anfang des Masterstudiums. Die meisten kamen aus meiner Fakultät (Mathematik/Physik), aber es waren auch Informatiker und Lehramtstudenten dabei.

Voraussetzung für den Kurs war eine vollständige Installation von Miktex 2.9 oder TeX Live 2011, sowie der Editor TexStudio. Der Editor selber stellte für keinen der Studenten ein Problem dar. Allerdings ist es empfehlenswert die voreingestellten Optionen anzupassen. Problematisch waren hingegen die Distributionen. Fast alle Studenten hatten nur die Minimalversion von Miktex installiert, die nicht annähernd ausreicht. Und die Installation von TeXLive unter Linux, spezieller Ubunutu ist eine Katastrophe. Die Version der Distribution ist von 2009 und damit für den Kurs nicht verwendbar, da ich siunitx und biblatex verwende. Eine manuelle Installation von der 2011er Version nach der Originalanleitung funktioniert nicht. Man muss auf spezielle Ubunutu Anleitungen zurückgreifen. Effektiv hatte die mehrheit der Studenten zu Beginn der Vorlesung ein nicht verwendbares LaTeX System.

Die Vorlesung umfasste 6 Vorlesungstermine mit jeweils 2-3 Zeitstunden. Die Inhalte waren:

Installation, Vorkenntnisse, Begriffe, Editor (TexStudio)
Kapitel, Überschriften, Paragraphen
Strukturierung des Inhaltes
Verweise
Seitenlayout
Aufteilung komplexer Dokumente
Schriften
Silbentrennung
Literaturverzeichnis (mit biblatex und biber)
Literatur erstellen und verwalten (JabRef)
Mathematik und Einheiten (siunitx)
Abbildungen und Beschriftungen
Tabellen
Fragen und Antworten
sonstiges (tikz/pgf, pgfplots)

Einführung in Bibliographien mit LaTeX, biblatex und biber.

pospiech — Sun, 16 Oct 2011 11:24:25 +0000

Im Rahmen eines Arbeitsgruppenseminars der AG Morgner wurde der folgende Vortrag zur Einführung in Bibliographien mit LaTeX gehalten. Zielpublikum waren Masterstudenten und Doktoranden, die zuvor schon mit Bibtex gearbeitet hatten.

Note: There is a file embedded within this post, please visit this post to download the file.
Note: There is a file embedded within this post, please visit this post to download the file.

pcolor plots with publication ready formating

pospiech — Wed, 01 Jun 2011 06:34:01 +0000

Matlab has many possibilities to create plots even fancy ones. However its defaults are very seldom suitable to use the plots directly for a publication. The following minimal code demonstrates how to generate a pcolor plot for 2D data with x- and y-axis. The data was calculated using the function shown here.

pcolor(xAxis, yAxis, Data2D); 
shading flat; % do not interpolate pixels
colorbar % add colorbar
 
xlabel('x / µm');
ylabel('y / µm');

This however is not optimal. Font and fontsizes are not optimal, the color depth should be higher and tics are not shown anymore. Furthermore the colorbar should have an label as well.

The following code demonstrates a general approach how to solve all these problems and achieve directly a plot output which can be used directly for publications. The followin picture shows the resulting image:

First the environment is set up (not necessary if you just want to plot) and variables for plotting are defined.

% clear command window, figures and all variables
clc; clf; clear all; 
 
%% Common variables
FontSize = 12;
FontName = 'MyriadPro-Regular'; % or choose any other font
 
doExportPlot = true;
languageEnglish = false;

Next, the data for plotting is created. Here a previous shown example is used

%% Calculation
% calculate in single line (fastest method)
xMat = (xAxis' * ones([1 yPoints]))';
yMat = yAxis' * ones([1 xPoints]);
Data2D = Ripple(xMat, yMat);
 
Data2D = Data2D - min(min(Data2D)); % normalize to 0-1
Data2D = Data2D / max(max(Data2D));

Then the plot window is opened and configured. Here a fixed size in cm is used. The z-buffer is used because opengl has rounding errors and should therefore be avoided if not necessary. Furthermore the position of the plot within the window is configured.

%% start plot
 
% figure dimensions in cm. I choose 1.5 or 2 times 
% the target size typically. If figure is display in
% document much smaller increase the fontsize.
 
figure_width = 14;  
figure_height = 10;
 
% --- setup plot windows
figuresVisible = 'on'; % 'off' for non displayed plots (will still be exported)
hfig = figure(1); clf;
    set(hfig,'Visible', figuresVisible)
 
    set(hfig, 'units', 'centimeters', 'pos', [5 5 figure_width figure_height])   
    set(hfig, 'PaperPositionMode', 'auto');    
    set(hfig, 'Renderer','Zbuffer'); 
    set(hfig, 'Color', [1 1 1]); % Sets figure background
    set(gca, 'Color', [1 1 1]); % Sets axes background
 
% --- dimensions and position of plot 
hsp = subplot(1,1,1, 'Parent', hfig);
set(hsp,'Position',[0.15 0.17 0.75 0.80]);

The actual plot is still a few lines:

%% plot
colorDepth = 1000;
colormap(jet(colorDepth));
pcolor(xAxis, yAxis, Data2D);

Now the plot needs to be configured. First the pcolor must not have black lines between each data point (the plot would be black). This is achieved by setting the shading. In case of flat not interpolation is done. This might look nicer, but in case of scientific data is close to cheating. The axis properties are important, because matlab does not care itself about scaling. This means that the x- and y-axis might be square although the axis values have a factor of 1:10. The image ratio is set to the axis ratio by the property ‘image’. Additionally several properties for the figure can be set. Most important are the TickLength and the LineWidth.

%%  setup axis plot properties
% shading interp; % interpolate pixels
shading flat; % do not interpolate pixels
axis on;      % display axis
axis tight;   % no white borders
axis image;   % real x,y scaling
 
set(gca, ...
    'CLim' , [0 1], ...
    'Box'         , 'on'      , ...
    'TickDir'     , 'in'      , ...
    'TickLength'  , [.015 .015] , ...
    'XMinorTick'  , 'off'      , ...
    'YMinorTick'  , 'off'     , ...
    'XGrid'       , 'off'     , ...
    'YGrid'       , 'off'     , ...
    'XColor'      , [.0 .0 .0], ...
    'YColor'      , [.0 .0 .0], ...
    'LineWidth'   , 0.6        );

optionally the axis ticks can be configured

%% axis ticks
set(gca,'XTick',-15:5:15)
set(gca,'YTick',-10:5:10)

Next the axis labels are set up. Here I define them in both german end english. That has the advantage, that I can create the figure easily in both languages. The labels are all set with saving of handles, to be able to configure them later.

%% label texts
TITLE = '';
if (languageEnglish)
    xLabelText = 'x / µm';  
    yLabelText = 'y / µm';
    zLabelText = 'normalized intensity';
else
    xLabelText = 'x / µm';
    yLabelText = 'y / µm';
    zLabelText = 'normierte Intensität';
end
 
% save handles to set up label properties
hTitle = title(TITLE);
hXLabel = xlabel(xLabelText);
hYLabel = ylabel(yLabelText);

The colorbar is still missing. Here a label and ticks are defined, and the TickLength and LineWidth is configured.

%% colorbar
caxis([0 1]);
hcb = colorbar('location','EastOutside');
hcLabel = ylabel(hcb,zLabelText);
set(hcb,'YTickLabel',0:0.2:1, 'Ytick', 0:0.2:1)
set(hcb,'YTickMode','manual')
set(hcb, ...
  'Box'         , 'on'     , ...
  'TickDir'     , 'in'     , ...
  'TickLength'  , [.015 .015] , ...
  'LineWidth'   , 0.6);

Last all handles need to be configured. Basically that means setting up the fonts for all.

%% set properties for all handles
set([gca, hcb, hTitle, hXLabel, hYLabel, hcLabel], ...
    'FontSize'   , FontSize    , ...
    'FontName'   , FontName);

And finally some bugs need to be fixed. fixLabels changes the decimal point character to ‘,’ (see below) and the last line brings the tics to the top again, which are overwritten by matlab.

%% last 'bug' fixes
 
% change decimal point to ',' for german text
if (~languageEnglish)
     fixLabels(gca);
     fixLabels(hcb);
end
% bring axis on top again (fix matlab bug)
set(gca,'Layer', 'top');

fixLabels (not optimal, be nevertheless working):

function fixLabels( axis )
 
xlabels = get(axis, 'XTickLabel');
for k=1:size(xlabels,1)
    xlabels(k,:) = strrep(xlabels(k,:), '.', ',');
end
set(axis, 'XTickLabel', xlabels);
 
ylabels = get(axis, 'YTickLabel');
for k=1:size(ylabels,1)
    ylabels(k,:) = strrep(ylabels(k,:), '.', ',');
end
set(axis, 'YTickLabel', ylabels);
 
set(axis, 'XTickMode', 'manual');
set(axis, 'YTickMode', 'manual');
 
end

In the end we might want to export the plot. Here the printing is done to a png file with a resolution of 400 dpi. Since matlab is not filling the plot window and large white borders might surround the actual plot, the png file is cropped using the crop function by Andrew Bliss.

%% export
drawnow
 
SaveDir = '';
SaveName = 'pcolor-example';
 
if (doExportPlot)
    IMAGENAME = [SaveDir SaveName]; 
    print(hfig, ['-r' num2str(400)], [IMAGENAME '.png' ], ['-d' 'png']);    
    crop([IMAGENAME '.png']);
    display('finished plot export')
end
 
% close(hfig);

Download the complete file: Note: There is a file embedded within this post, please visit this post to download the file.

fast calculation of functions with two variables

pospiech — Tue, 31 May 2011 21:05:40 +0000

If you come from the programming world of C/C++ or java or any other traditional programming languages you might fall into the trap of using for loops for the calculation of functions. This works as expected but it is much slower than what matlab can do. The following example demonstrates this principle (which you should not use if you can)

Data2D = zeros([xPoints yPoints]);
for xi = 1:xPoints
    x = xAxis(xi);
    for yi = 1:yPoints        
        y = yAxis(yi);
        Data2D(xi,yi) = Ripple(x, y);
    end
end

On my computer it takes 10.3 seconds for 1.000.000 datapoints.

If the function depends on a single variable one should use a vector and for two variables one should use matrices instead. The following example demonstrates how to calculate a functions with two variables in a single step:

xMat = (xAxis' * ones([1 yPoints]))';
yMat = yAxis' * ones([1 xPoints]);
Data2D = Ripple(xMat, yMat);

On my computer it takes 0.12 seconds for 1.000.000 datapoints, which is approx 90 times faster.

This is the complete code that was used

% clear command window, figures and all variables
clc; clf; clear all; 
 
%% Definition of calculation constants
 
% calculation of axis
xMax = 15;
xPoints = 1000;
xAxis = linspace(-xMax, xMax, xPoints);
 
yMax = 12;
yPoints = 1000;
yAxis = linspace(-yMax, yMax, yPoints);
 
%% function, here inline since it is rather simple
Ripple = @(x,y) ( (cos(sqrt(x.*x+y.*y) + cos(sqrt(((x+.913*2*pi).*(x+.913*2*pi))+y.*y)) + cos(sqrt(((x-.913*2*pi).*(x-.913*2*pi))+(y.*y))))*4) );
 
%% Calculation
% calculate in single line (fastest method)
xMat = (xAxis' * ones([1 yPoints]))';
yMat = yAxis' * ones([1 xPoints]);
tic;
Data2D = Ripple(xMat, yMat);
display(['calculated ' num2str(xPoints*yPoints) ' datapoints in ' num2str(toc) ' seconds']);
 
Data2D = Data2D / max(max(Data2D)); % normalize

plotting a filled curve

pospiech — Tue, 31 May 2011 20:23:44 +0000

A search on how to fill the area under a curve reveals that such questions are quite often asked. Here is the solution in a function file that I created for simplifying filled curve plots using matlabs fill function.

function handle = filledcurve(x, y, zero, colorspec)
 
if (nargin < 3)
    zero = 0;
end
 
if (nargin < 4)
    colorspec = 'b';
end
 
 
xtemp = [x(1) ; x(:) ; x(end)] ;
ytemp = [zero ; y(:) ; zero ] ;
 
% plot
handle = fill(xtemp,ytemp,colorspec);

fast reading of structured text data with matlab

pospiech — Tue, 31 May 2011 20:18:08 +0000

In the following I present a solution to read data from a textfile which has the number of x-values (columns) in the first line, the number of y-values (rows) in the second line and in all following lines the matrix with size x times y.

The principle reading of the data is achieved by the following code

% open file
display(['reading ' FILENAME]);
fid = fopen(FILENAME, 'r');
fseek(fid, 0, 'bof');
 
% read single line: number of x-values
tline = fgetl(fid);
valueLine = strrep(tline, '#', '');
valueLine = strrep(valueLine, ' ', '');
x = str2double(valueLine);
 
% read single line: number of y-values
tline = fgetl(fid);
valueLine = strrep(tline, '#', '');
valueLine = strrep(valueLine, ' ', '');
y = str2double(valueLine);
 
% read full matrix with size x * y
DATACELL = textscan(fid,'%f',[x,y]);
DATA = DATACELL{1};
 
% convert data to correct matrix format
DATA = reshape(DATA, y, x);
 
% close file
fclose(fid);

This can however be slow, especially for matrices with text-file size of several hundred MB. Since disk space is usually not a limit an time much more expensive than disk space I save the data again in matlabs binary format. If I have to read the file a second time I can read the matlab file instead which is 10-100 times faster. Additionally If the data of the file is requested a second time this can be skipped if the data is kept persistent in the function reading the data. In total this is achieved with the following code:

function [r_Data, r_xsize, r_ysize] = ReadSimulationData(FILENAME)
 
persistent lastImageName;
persistent DATA;
persistent xsize;
persistent ysize;
 
% if this file is equal to last file reuse data
if (not(isempty(lastImageName)) && (strcmp(lastImageName,FILENAME)))
    display(['using ' FILENAME]);
else
    % check if converted matlab file exists
    MatlabDataName = strrep(FILENAME, '.txt', '.mat');
    if (exist(MatlabDataName, 'file'))
        display(['loading ' MatlabDataName]);
        load(MatlabDataName, '-mat', 'DATA', 'xsize', 'ysize');
    else                
        %% read data from file
 
        % open file
        display(['reading ' FILENAME]);
        fid = fopen(FILENAME, 'r');
        fseek(fid, 0, 'bof');
 
        % read single line: number of x-values
        tline = fgetl(fid);
        valueLine = strrep(tline, '#', '');
        valueLine = strrep(valueLine, ' ', '');
        x = str2double(valueLine);
 
        % read single line: number of y-values
        tline = fgetl(fid);
        valueLine = strrep(tline, '#', '');
        valueLine = strrep(valueLine, ' ', '');
        y = str2double(valueLine);
 
        % read full matrix with size x * y
        DATACELL = textscan(fid,'%f',[x,y]);
        DATA = DATACELL{1};
 
        % check if read length is equal
        % to expected length.
        % if not resize x accordingly
        % (typically not necessary)
        lengthdiff = length(DATA) - x*y;
        if (lengthdiff ~= 0)
            x = x + lengthdiff/y;
        end
        % convert data to correct matrix format
        DATA = reshape(DATA, y, x);
 
        % close file
        fclose(fid);
 
        % save last read filename
        lastImageName = FILENAME;        
 
        xsize = x;
        ysize = y;
        display(['saving ' MatlabDataName]);
 
        % save data in binary format
        % this speeds up reading of big matrices
        % enormously
        save(MatlabDataName, 'DATA', 'xsize', 'ysize', '-mat');        
    end
end
 
% copy read, or old persistent data to
% return data values
r_Data = DATA;
r_xsize = xsize;
r_ysize = ysize;
 
return;