nplot.m

classdef nplot < handle
    % NPLOT plots a line profile from one or more multidimensional matrices.
    %
    %  NPLOT(mat)
    % opens a figure that can plot data along all dimensions of mat.
    %
    %  NPLOT(mat1, mat2, ...)
    % opens a figure that can simultaneously plot data along all dimensions of
    % the input matrices mat1, mat2, ...
    %
    %NAME-VALUE PAIRS
    %
    %   NAME        TYPE        DEFAULT         DESCRIPTION
    %
    %   LineStyle   string      []              Allows to specify the line
    %                                           apperance in the same way it is
    %                                           possible with matlabs plot
    %                                           function.
    %   DimLabel    {char}      []              cell array containing character
    %                                           vectors the describe the
    %                                           dimensions of the data and will
    %                                           be shown next to the sliders.
    %   InputNames  {char}      []              cell array containing character
    %                                           vectors that describe the
    %                                           matrices and are shown in the
    %                                           plot-legend.
    %   DimVal      {double}                    Cell array that contains a
    %                                           1D-double array for each
    %                                           dimension in the input data
    %                                           which will be used for the
    %                                           x-axes. Default values are
    %                                           linear indices counting from 1
    %                                           to the dimension size. Leave
    %                                           cell empty for default values.
    %   Color       double      []              defines the color for each
    %                                           of the N input datasets in
    %                                           a Nx3 matrix.
    
    % -------------------------------------------------------------------------
    %   TODO
    % -------------------------------------------------------------------------
    % - show value at indicator position
    % - change the way of mouse-navigation:
    %       left-click, change center for x and y axis
    %       right-click, change width for x- and y-axis
    
    % -------------------------------------------------------------------------
    %   Check name-value pairs and set initial values
    % -------------------------------------------------------------------------
    
    properties (Access = public)
        
        fig
        
    end
    
    
    properties (Access = private)
        
        nMats           % number of input matrices
        nSlider         % number of non-singleton dimensions
        nDims           % number of dimensions
        ston            % cell array for dimensions where a matrix is the only singleton
        valNames        % names of input matrices
        mat             % cell array containing the input matrices
        isComplex       % is one of the inputs complex
        inputNames      % names of the input matrices, shown in legend
        varargin        % all input data is stored in varargin
        p               % input parser
        S               % size of input matrices
        unit            % physical unit of the input data
        minmax
        %minVal          % minVal of all inputData
        %maxVal          % maxVal of all inputData
        
        %% DISPLAYING
        
        % showDim specifies the dimension that is currently displayed on
        % the xaxis
        showDim
        
        % stores the current complex representation mode
        complexMode
        
        % cell array that stores the location information in the input data
        % of each currently shown line profile.
        sel
        
        % index of the currently active dimension for slider scrolling
        % etc...
        activeDim
        
        % label for each dimension
        dimLabel
        
        % values for each dimension
        dimVal
        
        % apperance of plotted lines
        lineStyle
        color
        
        % store currently shown x-data
        currXData
        
        % store currently shown y-data
        currYData
        
        %% GUI elements
        
        sliderPanelHeight    % absolute height of slider panel
        controlPanelWidth    % width of control panel Ü(normalized)
        
        % panels
        pPlot
        pSlider
        pControl
        
        % slider handles
        hSliderLabel
        hSlider
        hIndex
        % locVal handle
        hLocAndVals
        
        % button handles
        hBtnCmp
        
        % plot elements
        hAxis
        hVertLine
        hPlot
        hLine
        
        xaxes
        
        %% external
        bCalledFromExternal
        bUpdateCaller
        hBtnToggleUpdateCaller 
    end


    properties (Constant = true, Hidden = true)
        % max number of letters for variable names in the locVal section
        maxLetters = 6;
    end
    
    
    events
        selChanged
    end
    
    
    methods
        function obj = nplot(varargin)
            % CONSTRUCTOR
            obj.varargin = varargin;
            
            obj.checkInputMatrices();
            
            % The slider for which dimension is initially active?
            obj.activeDim   = 1;
            
            % set the correct default value for complexMode
            if any(obj.isComplex)
                obj.complexMode = 1;
            else
                % if neither input is complex, display the real part of the
                % data
                obj.complexMode = 3;
            end
            
            % per default, update the caller about selection changes
            obj.bUpdateCaller = 1;
            
            % prepare the input parser
            obj.parseNVPs();
            
            obj.prepareXaxes();
            
            obj.initializeGUI();

            % collect/generate names for input matrices
            if contains('InputNames', obj.p.UsingDefaults)
                for idm = 1:obj.nMats
                    obj.inputNames{idm} = inputname(idm);
                end
            end
            obj.setValNames();
            
            % set initial plot-dimension
            obj.changeDimension(obj.hSliderLabel(1))
            
            % -------------------------------------------------------------------------
            % Last step, make figure visible
            % -------------------------------------------------------------------------
            obj.refreshUI()
            set(obj.fig, 'Visible', 'on');
            
            % do not assign to 'ans' when called without assigned variable
            if nargout == 0
                clear obj
            end
        end
        
        
        function delete(obj)
            % DESTRUCTOR
            delete(obj)
        end
        
        
        function checkInputMatrices(obj)
            % how many matrices are in varargin?
            obj.nMats = find(cellfun(@ischar, obj.varargin), 1, 'first') - 1;
            if isempty(obj.nMats)
                % no name value pair was provided
                obj.nMats = numel(obj.varargin);
            end
            
            % define mats in order to suppress warnings
            obj.mat = cell(1, obj.nMats);
            obj.isComplex = zeros(obj.nMats, 1);
            
            % create a fixed loop counter
            N = obj.nMats;
            fixidx = 1;
            for idx = 1:N
                
                % check if this matrix actually has data
                if isempty(obj.varargin{1})
                    obj.nMats = obj.nMats - 1;
                    warning('input matrix no. %d is empty.', idx);
                else
                    obj.isComplex(fixidx) = ~isreal(obj.varargin{1});
                    obj.mat{fixidx} = obj.varargin{1};
                    fixidx = fixidx + 1;
                end
                
                % at the same time, remove matrices from varargin to save space
                obj.varargin(1) = [];
            end

            % get min max values for all input matrices and complex modes
            obj.calculateMinMaxAll();
            
            obj.checkSize()
            
            % number of Sliders
            obj.nSlider   = numel(obj.S);
            
            % number of dimensions
            obj.nDims = numel(obj.S);
        end


        function checkSize(obj)
            s = cellfun(@size, obj.mat, 'UniformOutput', false);
            maxDim = max(cellfun(@numel, s));
            
            for iMat = 1:obj.nMats

                if numel(s{iMat}) < maxDim
                    s{iMat} = [s{iMat} ones(1, maxDim - numel(s{iMat}))];
                end
            end

            % stack dimension sizes
            s_st = cat(1, s{:});

            % make sure the are at most 2 different numbers per column
            % and one must be equal to 1.
            for iCol = 1:maxDim
                u = unique(s_st(:, iCol));
                if numel(u) > 2 || numel(u) == 2 && u(1) ~= 1
                    % there are dimensions where the size differs and
                    % neither of the matrices has a size of one along that
                    % dimension
                    error('Matrix dimensions must agree.')
                end
            end

            obj.S = max(s_st, [] , 1);
            
            for iMat = 1:iMat
                obj.ston{iMat} = find(s{iMat} == 1);
            end
        end

        
        function parseNVPs(obj)
            
            obj.p = inputParser;
            
            % prepare default selector
            obj.sel = num2cell(ceil(obj.S/2));
            
            addParameter(obj.p, 'InputNames',   {},                             @(x) ischar(x) || (iscell(x) && numel(x) == obj.nMats));
            addParameter(obj.p, 'LineStyle',    repmat({'-'}, 1, obj.nMats),    @(x) ischar(x) || (iscell(x) && numel(x) == obj.nMats));
            addParameter(obj.p, 'Color',        [],                             @isnumeric);
            addParameter(obj.p, 'InitSel',      obj.sel,                        @(x) isnumeric(x) && x <= 4);
            addParameter(obj.p, 'ComplexMode',  obj.complexMode,                @(x) isnumeric(x) && x <= 4);
            addParameter(obj.p, 'DimLabel',     strcat(repmat({}, 1, numel(obj.S))), @(x) iscell(x) && numel(x) >= obj.nDims);
            addParameter(obj.p, 'DimVal',       cellfun(@(x) 1:x, num2cell(obj.S), 'UniformOutput', false), @iscell);
            addParameter(obj.p, 'Unit',         repmat({''}, 1, obj.nMats),     @(x) ischar(x) || iscell(x));
            addParameter(obj.p, 'InitDim',      1,                              @isnumeric);
            addParameter(obj.p, 'ExternalCall', 0,                              @(x) (x == 0 || x == 1));
            
            parse(obj.p, obj.varargin{:});
            
            obj.complexMode         = obj.p.Results.ComplexMode;
            obj.inputNames          = obj.p.Results.InputNames;
            obj.lineStyle           = obj.p.Results.LineStyle;
            obj.unit                = obj.p.Results.Unit;
            obj.showDim             = obj.p.Results.InitDim;
            obj.bCalledFromExternal = obj.p.Results.ExternalCall;
            obj.color               = obj.p.Results.Color;

            if ischar(obj.unit)
                obj.unit = {obj.unit};
            end
            if ischar(obj.inputNames)
                obj.inputNames = {obj.inputNames};
            end
                        
            obj.parseDimLabelsVals()
        end
        
        
        function initializeGUI(obj)
            % -------------------------------------------------------------------------
            %   Create Figure and partition into panels
            % -------------------------------------------------------------------------
            
            fWidth0  = 300;
            fHeight0 = 200;
            fWidth   = 1000;
            fHeight  = 800;
            
            
            obj.sliderPanelHeight = (obj.nSlider+1) * 30;%px
            obj.controlPanelWidth = 0.2;
            
            obj.fig = figure( ...
                'Position',             [fWidth0 fHeight0 fWidth fHeight], ...
                'Units',                'pixel', ...
                'ResizeFcn',            @obj.guiResize, ...
                'Visible',              'off', ...
                'WindowScrollWheelFcn', @obj.scrollSlider, ...
                'CloseRequestFcn',      @obj.closeRqst);
            
            % -------------------------------------------------------------------------
            % define the plot panel and slider panel.
            % -------------------------------------------------------------------------
            
            lDiv = 0.2;
            
            obj.pPlot  = uipanel( ...
                'Units',        'pixels', ...
                'Position',     [0 obj.sliderPanelHeight fWidth fHeight-obj.sliderPanelHeight]);
            
            obj.pSlider = uipanel( ...
                'Units',        'pixels', ...
                'Position',     [lDiv*fWidth 0 (1-lDiv)*fWidth obj.sliderPanelHeight]);
            
            obj.pControl = uipanel( ...
                'Units',        'pixels', ...
                'Position',     [0 0 lDiv*fWidth obj.sliderPanelHeight]);
            
            % -------------------------------------------------------------------------
            % initialize elements in pSlider
            % -------------------------------------------------------------------------
            
            % divison of Slider panel width (sum must equal 1) into spaces for
            % [Label Index Slider]
            division = [0.15 0.1 0.75];
            % top and bottom padding in normalized units
            tb_pad = 0.05;
            % reserve area at the bottom for display of current data value
            sliderHeight = (1-2*tb_pad)/(obj.nSlider+1);
            
            for iSlider = 1:obj.nSlider
                obj.hSliderLabel(iSlider) = uicontrol( ...
                    'Parent',           obj.pSlider, ...
                    'Style',            'togglebutton', ...
                    'Units',            'normalized', ...
                    'Position',         [0 ...
                    1-tb_pad-iSlider*sliderHeight ...
                    division(1) ...
                    sliderHeight], ...
                    'String',           obj.dimLabel{iSlider}, ...
                    'FontUnits',        'normalized', ...
                    'FontSize',         0.8, ...
                    'Callback',         {@obj.changeDimension});
                
                obj.hIndex(iSlider) = uicontrol( ...
                    'Parent',           obj.pSlider, ...
                    'Style',            'edit', ...
                    'Units',            'normalized', ...
                    'Position',         [division(1) ...
                    1-tb_pad-iSlider*sliderHeight ...
                    division(2) ...
                    sliderHeight], ...
                    'String',           obj.dimVal{iSlider}{obj.sel{iSlider}}, ...
                    'FontUnits',        'normalized', ...
                    'FontSize',         0.8, ...
                    'Enable',           'on');
                set(obj.hIndex(iSlider), 'Callback', { @obj.editIndex});
                
                if obj.S(iSlider) == 1
                    sliderStep = [0, 0];
                else
                    sliderStep = [1/(obj.S(iSlider)-1) 10/(obj.S(iSlider)-1)];
                end
                
                obj.hSlider(iSlider) = uicontrol( ...
                    'Parent',           obj.pSlider, ...
                    'Style',            'slider', ...
                    'Units',            'normalized', ...
                    'Position',         [sum(division(1:2)) ...
                    1-tb_pad-iSlider*sliderHeight ...
                    division(3) ...
                    sliderHeight], ...
                    'Min',              1, ...
                    'Max',              obj.S(iSlider), ...
                    'Value',            obj.sel{iSlider}, ...
                    'SliderStep',       sliderStep, ...
                    'Callback',         @obj.sliderMove);
                
                addlistener(obj.hSlider(iSlider), ...
                    'ContinuousValueChange', @obj.sliderMove);
            end


            % add loc and val information in last row
            obj.hLocAndVals = uicontrol(... 
                'Parent',               obj.pSlider, ...
                'Style',                'text', ...
                'Units',                'normalized', ...
                'Position',             [0 ...
                1-tb_pad-(iSlider+1)*sliderHeight-tb_pad/2 ...
                1 ...
                sliderHeight], ...
                'String',               '', ...
                'HorizontalAlignment',  'left', ...
                'FontUnits',            'normalized', ...
                'FontSize',             0.8);
            
            % -------------------------------------------------------------------------
            % initialize elements in control panel
            % -------------------------------------------------------------------------
            
            if sum(obj.isComplex > 0)
                obj.hBtnCmp = gobjects(4,1);
                
                obj.hBtnCmp(1) = uicontrol( ...
                    'Parent',               obj.pControl, ...
                    'Style',                'togglebutton', ...
                    'Units',                'normalized',...
                    'Position',             [0 2/3 0.5 1/3], ...
                    'String',               'Magnitude', ...
                    'Callback',             {@obj.toggleComplex},...
                    'FontUnits',            'normalized', ...
                    'Value',                1, ...
                    'FontSize',             0.3);
                
                obj.hBtnCmp(2) = uicontrol( ...
                    'Parent',               obj.pControl, ...
                    'Style',                'togglebutton', ...
                    'Units',                'normalized',...
                    'Position',             [0.5 2/3 0.5 1/3], ...
                    'String',               'Phase', ...
                    'Callback',             {@obj.toggleComplex},...
                    'FontUnits',            'normalized', ...
                    'Value',                0, ...
                    'FontSize',             0.3);
                
                obj.hBtnCmp(3) = uicontrol( ...
                    'Parent',               obj.pControl, ...
                    'Style',                'togglebutton', ...
                    'Units',                'normalized',...
                    'Position',             [0 1/3 0.5 1/3], ...
                    'String',               'real', ...
                    'Callback',             {@obj.toggleComplex},...
                    'FontUnits',            'normalized', ...
                    'Value',                0, ...
                    'FontSize',             0.3);
                
                obj.hBtnCmp(4) = uicontrol( ...
                    'Parent',               obj.pControl, ...
                    'Style',                'togglebutton', ...
                    'Units',                'normalized',...
                    'Position',             [0.5 1/3 0.5 1/3], ...
                    'String',               'imaginary', ...
                    'Callback',             {@obj.toggleComplex},...
                    'FontUnits',            'normalized', ...
                    'Value',                0, ...
                    'FontSize',             0.3);
                
                obj.complexMode = 1;
            end
            
            if obj.bCalledFromExternal
                nLowerRow = 3;
            else
                nLowerRow = 2;
            end
            
            % autoscale button
            uicontrol( ...
                'Parent',               obj.pControl, ...
                'Style',                'togglebutton', ...
                'Units',                'normalized',...
                'Position',             [0 0 1/nLowerRow 1/3], ...
                'String',               'Autoscale', ...
                'Callback',             {@obj.autoscale},...
                'FontUnits',            'normalized', ...
                'Value',                0, ...
                'FontSize',             0.3);
            
            % global scale button
            uicontrol( ...
                'Parent',               obj.pControl, ...
                'Style',                'togglebutton', ...
                'Units',                'normalized',...
                'Position',             [1/nLowerRow 0 1/nLowerRow 1/3], ...
                'String',               'Globalscale', ...
                'Callback',             {@obj.globalscale},...
                'FontUnits',            'normalized', ...
                'Value',                0, ...
                'FontSize',             0.3);
            
            if obj.bCalledFromExternal
                % updateCaller (only if caller exists)
                obj.hBtnToggleUpdateCaller = uicontrol( ...
                    'Parent',               obj.pControl, ...
                    'Style',                'togglebutton', ...
                    'Units',                'normalized',...
                    'Position',             [2/3 0 1/3 1/3], ...
                    'String',               'Update: on', ...
                    'Callback',             {@obj.toggleUpdateCaller},...
                    'FontUnits',            'normalized', ...
                    'Value',                0, ...
                    'FontSize',             0.3);
            end
            
            % -------------------------------------------------------------------------
            % pPlot Elements
            %   INITIALIZE ELEMENTS OF pPlot PANEL HERE
            % -------------------------------------------------------------------------
            
            % scale axis differently when units are provided.
            
            
            obj.hAxis = axes( ...
                'Parent',       obj.pPlot, ...
                'Units',        'normal', ...
                'Position',     [0.05 0.05 0.9 0.9]);
            %set(obj.hAxis, 'ButtonDownFcn', @startDragFcn)
            
            yLabelText{1} = [obj.inputNames{1} ' / ' obj.unit{1}];
            if obj.nMats == 2
                yLabelText{2} = [obj.inputNames{2} ' / ' obj.unit{2}];
            end
            ylabel(yLabelText)
            set(obj.hAxis, 'Position', [0.075 0.05 0.9 0.9]);
            
            hold on
            
            xData = [1 2];
            yData = [-1 1];
            
            obj.hPlot = gobjects(1, obj.nMats);
            
            for iMat = 1:obj.nMats
                obj.hPlot(iMat) = plot(xData, yData, obj.lineStyle{iMat});
                if ~isempty(obj.color)
                     set(obj.hPlot(iMat), 'Color', obj.color(iMat, :))
                end
            end
            
            %obj.hVertLine = plot([1 1], [-1 1]);
            obj.hVertLine = xline(1);
            
            % Limits = getLimits();
            
            % add a legend
            if ~sum(contains('InputNames', obj.p.UsingDefaults))
                legend(obj.inputNames)
            end
            
            hold off
            
        end
        

        function calculateMinMaxAll(obj)

            for ii = 1:obj.nMats
                obj.calculateMinMax(ii)
            end
        end


        function calculateMinMax(obj, idx)

            % real part
            obj.minmax{3}(idx, :) = [min(real(obj.mat{idx}), [], 'all') max(real(obj.mat{idx}), [], 'all')];
            if obj.isComplex(idx)
                % complex modes only when necessary
                obj.minmax{1}(idx, :) = [min(abs(obj.mat{idx}), [], 'all') max(abs(obj.mat{idx}), [], 'all')];
                obj.minmax{2}(idx, :) = [min(angle(obj.mat{idx}), [], 'all') max(angle(obj.mat{idx}), [], 'all')];
                obj.minmax{4}(idx, :) = [min(imag(obj.mat{idx}), [], 'all') max(imag(obj.mat{idx}), [], 'all')];                
            end
        end


        function minmax = getGlobalMinMax(obj)
            % returns global [min max] value for current complex mode and
            % all displayed matrices.

            minmax = [min(obj.minmax{obj.complexMode}(:, 1), [], 'all') max(obj.minmax{obj.complexMode}(:, 2), [], 'all')];

        end


        function prepareXaxes(obj)

            % find axis with values that cannot be converted to numbers
            for ii = 1:numel(obj.dimVal)
                obj.xaxes{ii}.ticklabels = obj.dimVal{ii};
                
                if numel(cell2mat(cellfun(@str2num, obj.dimVal{ii}, 'UniformOutput', false))) ~= numel(obj.dimVal{ii})
                    % some entries in dimVal for this axis cannot be
                    % converted to numbers
                    obj.xaxes{ii}.tickvalues = 1:numel(obj.dimVal{ii});
                else
                    % all enries in dimVal can be converted to numbers
                    obj.xaxes{ii}.tickvalues = cellfun(@str2num, obj.dimVal{ii});
                end
            end
            
        end
        
        
        function refreshUI(obj)
            % refreshUI()
            %
            % called by:    scrollSlider, sliderMove, editIndex, toggleComplex
            
            % check slider values and update slider UI elements
            obj.checkAndRefreshSliders();
            
            % create temporary selector
            tempSel = obj.sel;

            % clear yData cache
            obj.currYData = zeros(obj.nMats, obj.S(obj.showDim));

            % replot data from all inputs
            for idm = 1:obj.nMats

                % create temporary selector
                tempSel = obj.sel;
                % set default line style
                LineStyle = '-';
                
                if isempty(obj.ston{idm})
                    tempSel{obj.showDim} = ':';
                    LineStyle = '-';
                else
                    % use default line style if all ston dimensions are 1
                    % in sel
                    selAtSton = cell2mat(tempSel(obj.ston{idm}));
                    if sum(selAtSton) ~= numel(selAtSton)
                        LineStyle = '--';
                    end
                    
                    tempSel(obj.ston{idm}) = {1};
                    tempSel{obj.showDim} = ':';
                end
                
                obj.currYData(idm, :) = obj.complexPart(obj.mat{idm}(tempSel{:}));
                set(obj.hPlot(idm), ...
                    'YData', obj.currYData(idm, :), ...
                    'XData', obj.xaxes{obj.showDim}.tickvalues, ...
                    'LineStyle', LineStyle);

            end
            
            % reposition vertical line
            set(obj.hVertLine, 'Value', obj.xaxes{obj.showDim}.tickvalues(obj.sel{obj.showDim}))
            
            % inform the calling object, that the selector has changed
            if obj.bUpdateCaller
                notify(obj, 'selChanged')
            end

            % update the locVal string
            obj.locVal()
            
        end
        
        
        function checkAndRefreshSliders(obj)
            % called by:    refreshUI
            
            for iSldr = 1:obj.nSlider
                % check whether slider still in bounds
                obj.sel{iSldr} = max([obj.sel{iSldr}, 1]);
                obj.sel{iSldr} = min([obj.sel{iSldr}, obj.S(iSldr)]);
                obj.sel{iSldr} = round(obj.sel{iSldr});
                
                %set(hIndex(iSldr), 'String', num2str(sliderVals(iSldr)));
                set(obj.hSlider(iSldr), 'Value', obj.sel{iSldr});
                
                set(obj.hIndex(iSldr), 'String', obj.xaxes{iSldr}.ticklabels{obj.sel{iSldr}})
            end
        end


        function setValNames(obj)

            for ii = 1:obj.nMats
                % create default val name
                obj.valNames{ii} = ['val' num2str(ii)];

                % if available, take the name of the input variable
                if ~isempty(obj.inputNames{ii})
                    if numel(obj.inputNames{ii}) > obj.maxLetters
                        obj.valNames{ii} = obj.inputNames{ii}(1:obj.maxLetters);
                    else
                        obj.valNames{ii} = obj.inputNames{ii};
                    end
                    % text is shown using the LaTeX interpreter. We need to
                    % escape underscores
                    obj.valNames{ii} = strrep(obj.valNames{ii}, '_', '\_');
                end
            end

            % to get the number of the displayed characters correct, we
            % need to know howm many '_' are in each name to compensate the
            % result from numel
            usNo = cellfun(@(x) sum(x == '_'), obj.valNames);

            % find number of trailing whitespace
            wsToAdd = max(cellfun(@numel, obj.valNames) - usNo) - (cellfun(@numel, obj.valNames) - usNo);
            ws = cell(1, obj.nMats);
            for ii = 1:obj.nMats
                ws{ii} = repmat(' ', [1, wsToAdd(ii)]);
            end
            obj.valNames = strcat(obj.valNames, ws);
        end
        
        
        function parseDimLabelsVals(obj)
            %% dimension labels
            
            % set default values for dimLabel
            obj.dimLabel = strcat(repmat({'Dim'}, 1, numel(obj.S)), cellfun(@num2str, num2cell(1:obj.nDims), 'UniformOutput', false));
            
            if ~contains('DimLabel', obj.p.UsingDefaults)
                % check number of input labels equals dimensions of image
                if numel(obj.p.Results.DimLabel) ~= obj.nDims
                    warning('Number of DimLabel is not equal to the number of image dimensions.')
                end
                % if cell entry is empty, use default value
                emptyCell = cellfun(@isempty, obj.p.Results.DimLabel);
                obj.dimLabel(~emptyCell) = obj.p.Results.DimLabel(~emptyCell);
            end
            
            %% dimension values
            
            % set default values via size of each dimension
            obj.dimVal = cellfun(@(x) 1:x, num2cell(obj.S), 'UniformOutput', false);
            
            if ~contains('DimVal', obj.p.UsingDefaults)
                % check number of value arrays equals dimensions of image
                if numel(obj.p.Results.DimVal) ~= obj.nDims
                    % allow for trailing singleton dimensions
                    % check for all surplus dimensions in DimVal, that
                    % their size is one.
                    if numel(obj.p.Results.DimVal) > obj.nDims && ~all(cellfun(@numel, obj.p.Results.DimVal(obj.nDims+1:end)))
                        error('Number of elements in DimVal must equal the number of image dimensions.')
                    end
                end
                % if cell entry is empty, use default value
                emptyCell = cellfun(@isempty, obj.p.Results.DimVal);
                obj.dimVal(~emptyCell) = obj.p.Results.DimVal(~emptyCell);
                
                % value array for each dimension must have obj.S entries
                %                 if ~isequal(obj.S, cellfun(@numel, obj.dimVal))
                %                     error('Number of elements in DimVal for dimension(s) %s do not match image size', mat2str(find(obj.S ~= cellfun(@numel, obj.dimVal))))
                %                 end
            end
            
            obj.dimVal = valsToString(obj.dimVal);
        end
        
        
        function out = complexPart(obj, in)
            % complexPart(in)
            % in:     array with (potentially) complex data
            % out:    magnitude, phase, real or imaginary part of in
            %
            % called by:    refreshUI
            %
            % depending on the value in 'complexMode' either the magnitude,
            % phase, real part or imaginary part is returned
            
            switch(obj.complexMode)
                case 1
                    out = abs(in);
                case 2
                    out = angle(in);
                case 3
                    out = real(in);
                case 4
                    out = imag(in);
            end
        end
        
        
        %% functions to control object from external
        
        function setSelector(obj, newSel)
            % setSelector(newSel)
            % newSel:       cell array containing all new selector values
            %
            % Called by:    external
            %
            % Is called from external, when the display of different data
            % is requested.
            
            % perform some input checks
            if numel(newSel) ~= numel(obj.sel)
                error('Size mismatch in data selector')
            end
            
            obj.sel = newSel;
            
            obj.refreshUI();
            
        end
        
        
        function out = getSelector(obj)
            % getSelector(newSel)
            % 
            % Called by:    external
            %
            % Is called from external, to get the current selector
            
            out = obj.sel;
            
        end
        
        
        function setDimension(obj, newDim)
            % source:       index of the new dimension shown along ax-axis
            %
            % Called by:    external or button callback
            %
            % Is called from external or button callback, to change the
            % dimension of the input matrices shown along the x-axis.
            
            % perform some input checks
            if newDim > obj.nDims
                error('Dimension value exceeds number of dimensions')
            end
            
            obj.showDim = newDim;
            
            % change x-axis values
            set(obj.hPlot, 'XData', obj.xaxes{obj.showDim}.tickvalues(:))
            % store x-data cache
            obj.currXData = obj.xaxes{obj.showDim}.tickvalues(:);
            % set axis limits automatically
            xlim(obj.hAxis, 'auto')
            
            % unpress all buttons
            set(obj.hSliderLabel, 'Value', 0);
            
            % press current button
            set(obj.hSliderLabel(obj.showDim), 'Value', 1);
            
            obj.refreshUI()
            
        end


        function setVisibility(obj, layerShown)
            % setVisibility(layerShown)
            % newSel:       array containing logical values for visibility
            %               of each plot
            %
            % Called by:    external
            %
            % Is called from external, to update the visibility of
            % individual plots

            for iMat = 1:obj.nMats
                set(obj.hPlot(iMat), 'Visible', layerShown(iMat))
            end


        end


        function locVal(obj)
            % called by:    refreshUI
            %
            % everytime the UI is refreshed, the string containing the
            % current point and value is refreshed too.

            str = [];
            for idm = 1:obj.nMats
                if idm~=1
                    str = [str '   '];
                end
        
                sel = obj.sel;
                if ~isempty(obj.ston{idm})
                    sel(obj.ston{idm}) = {1};
                end

                val = obj.complexPart(obj.mat{idm}(sel{:}));
                str = [str sprintf('%s = %f', obj.valNames{idm}, val)];
                if  ~strcmp(obj.unit{idm}, '')
                    str = [str ' ' obj.unit{idm}];
                end
            end
            set(obj.hLocAndVals, 'String', str);
        end

        %% functions for button callbacks

        function toggleComplex(obj, source, ~)
            % toggleComplex(source, ~)
            % source:       handle to uicontrol button
            %
            % called by:    uicontrol togglebutton: Callback
            %
            % Is called when one of the 4 complex data buttons is pressed.
            % These buttons are only visible when at least one matrix has
            % complex data.
            % Depending on which button was pressed last, the magnitude, phase,
            % real part or imaginary part of complex data is shown.

            % set all buttons unpreessed
            set(obj.hBtnCmp, 'Value', 0)

            % find the index of the pressed button
            btnIdx = find(source == obj.hBtnCmp);
            obj.complexMode = btnIdx;
            set(obj.hBtnCmp(btnIdx), 'Value', 1)
            
            obj.refreshUI()
        end
        
        
        function autoscale(obj, ~, ~)
            % autoscale(~, ~)
            %
            % called by:    autoscale button
            %
            % set the x- and y-limits such that data fills the axis entirely
            
            set(obj.hAxis, 'XLim', [min(obj.currXData) max(obj.currXData)]);
            % in case of a constant line
            if min(obj.currYData, [], 'all') == max(obj.currYData, [], 'all')
                set(obj.hAxis, 'YLim', [min(obj.currYData, [], 'all')-1 min(obj.currYData, [], 'all')+1]);
            else
                set(obj.hAxis, 'YLim', [min(obj.currYData, [], 'all') max(obj.currYData, [], 'all')]);
            end
        end
        
        
        function globalscale(obj, ~, ~)
            % globalscale(~, ~)
            %
            % called by:    globalscale button
            %
            % set the x- and y-limits to the min and max values of all
            % shown input data
            
            % x limits
            set(obj.hAxis, 'XLim', [min(obj.currXData) max(obj.currXData)]);
            % y limits
            minAndMax = obj.getGlobalMinMax();

            % in case of a constant line
            if minAndMax(1) == minAndMax(2)
                set(obj.hAxis, 'YLim', minAndMax + [-1 1]);
            else
                set(obj.hAxis, 'YLim', minAndMax);
            end
        end
        
        
        function toggleUpdateCaller(obj, ~, ~)
            % toggleUpdateCaller(~, ~)
            %
            % called by:    UpdateCaller button
            %
            % toggle the value of bUpdateCaller
            
            if obj.bUpdateCaller == 0
                obj.bUpdateCaller = 1;
                set(obj.hBtnToggleUpdateCaller , 'String', 'Update: on')
                notify(obj, 'selChanged')
            elseif obj.bUpdateCaller == 1
                obj.bUpdateCaller = 0;
                set(obj.hBtnToggleUpdateCaller , 'String', 'Update: off')
            end
        end
        
        %% functions controlling slider behaviour
        
        function scrollSlider(obj, ~, evtData)
            % scrollSlider(source, evtData)
            % source:       handle to uicontrol slider
            % evtData:      information about slider movement
            %
            % Called by:    figure: WindowScrollWheelFcn
            %
            % Is called, when the figure is active and the user uses the scroll
            % wheel on the mouse. The value of the currently active slider will
            % be incremented or decremented by 1 depending on the direction of
            % the scrolling stored in evtData.
            
            if evtData.VerticalScrollCount < 0
                obj.sel{obj.activeDim} = obj.sel{obj.activeDim} - 1;
            elseif evtData.VerticalScrollCount > 0
                obj.sel{obj.activeDim} = obj.sel{obj.activeDim} + 1;
            end
            obj.refreshUI();
        end
        
        function sliderMove(obj, source, ~)
            % sliderMove(source, evtData)
            % source:       handle to uicontrol slider
            % evtData:      information about slider movement
            %
            % Called by:    uicontrol slider: Callback
            %
            % Is called on each move of the slider and updates the respective
            % value in 'sliderVals'
            
            obj.sel{source == obj.hSlider} = round(source.Value);
            % if you want, you can now change the active slider to the just
            % edited one
            obj.activeDim = find(source == obj.hSlider);
            obj.refreshUI();
        end
        
        function changeDimension(obj, source, ~)
            % source:       handle to uicontrol togglebutton
            % evtData:      ~
            %
            % Called by:    uicontrol togglebutton: Callback
            %
            % Is called when one of the sliderbuttons is pressed in order to
            % change the plot dimension
            
            obj.setDimension( find(obj.hSliderLabel == source) );
        end
        
        
        function editIndex(obj, source, ~)
            % editIndex(source, evtData)
            % source:       handle to uicontrol edit
            % evtData:      unused
            %
            % Called by:    uicontrol edit: Callback
            %
            % Is called, when the user has changed a value in an hIndex
            % element and subsequently presses ENTER. The new value is stored
            % in the slider variable and the slider is set at the appropriate
            % position. The hIndex is disabled afterwards.
            
            s = get(source, 'String');
            set(source, 'String', s);
            
            % get the slider dimension
            dim = find(source == obj.hIndex);
            
            % get the new index
            inSlice = round(str2double(s));
            % find the closest match in the axesValue
            % I = closestMatch(str2double(s), obj.dimVal{indexNo});
            
            % make sure the new value is within reasonable bounds
            inSlice = max([1 inSlice]);
            inSlice = min([inSlice obj.S(dim)]);
            
            obj.sel{dim} = inSlice;
            set(obj.hSlider(dim), 'Value', inSlice);
            % if you want, you can now change the active slider to the just
            % edited one
            obj.activeDim = dim;
            obj.refreshUI();
        end
        
        
        function guiResize(obj, ~, ~)
            % guiResize(varargin)
            % varargin:     unused
            %
            % called by:    figure: ResizeFcn
            %
            % is called when the figure window is resized and makes sure that
            % all elements are scaled correctly. This is only necessary for
            % elements that use 'pixel' units. 'normalized' positions and sizes
            % are adjusted automatically.
            pos     = get(obj.fig, 'Position');
            fWidth  = pos(3);
            fHeight = pos(4);
            
            set(obj.pPlot, ...
                'Position', [0 ...
                obj.sliderPanelHeight ...
                fWidth ...
                fHeight-obj.sliderPanelHeight]);
            set(obj.pSlider, ...
                'Position', [obj.controlPanelWidth*fWidth ...
                0 ...
                (1-obj.controlPanelWidth)*fWidth ...
                obj.sliderPanelHeight]);
            set(obj.pControl, ...
                'Position', [0 ...
                0 ...
                obj.controlPanelWidth*fWidth ...
                obj.sliderPanelHeight]);
        end
        
        
        function closeRqst(obj, ~, ~)
            % closeRqst is called, when the user closes the figure (by 'x' or
            % 'close').           
            
            delete(obj.fig);
            delete(obj)
        end
        
        
    end
end

function str = valsToString(valCell)
% makes sure all entries in dimVals are strings

% initialize output
str = valCell;

% find numeric arrays
numArray = cellfun(@isnumeric, valCell);
if any(numArray)
    % convert matrix to cell
    str(numArray) = cellfun(@num2cell, valCell(numArray), 'UniformOutput', 0);
    % convert numbers to strings
    for ii = find(numArray)
        str{ii} = cellfun(@num2str, str{ii}, 'UniformOutput', 0);
    end
end

% find char arrays
charArray = cellfun(@ischar, valCell);
if any(charArray)
    % convert char to cell
    str(charArray) = cellfun(@(x) {x}, valCell(charArray), 'UniformOutput', 0);
end
end