% !TeX encoding = UTF-8 Unicode
% !TeX root = manual.tex
% !TeX spellcheck = en_GB


\chapter{\texttt{m}-package}

\section{\texttt{plotm}}\label{plotm}
This function is a wrapper function to various graphics functions of Matlab.


% plotm( data, [options])
% Wrapper function which calls stem/plot/plot3 depending on the dimension of varargin{1}
% Also handles interval data
%
% Input:
%   data        dim x N array
%   [options]   everything which can be parsed by plot/plot2/plot3
%               if dim=1, stem is called instead of plot
%
% Options:
%   'box',val               Plots the hypercube of dimension val with volume 1
%   'rotate',val            (experimental) Rotates the current plot by 360 degree in steps of val degree.
%
% Options for 1-dim:
%   'height',val            scalar or 1x2 vector, default=[0 1],
%                           determines the length of the lines to be plotted
%                               scalar: Line goes from 0 to val
%                               vector: Line goes from val(1) to val(2) 
%
% Options for 2-dim:
%       'hull'              Plots also the convex hull
%       'boundary',val      (experminental) Plots also the boundary 
%                               val<= 1: computed with boundary
%                               val>1: points which have less neighbours are computed
%
% Options for 3-dim:
%       'contour'           Plots contour lines
%       'resolution',val    scalar, default depends on the input
%                           determines the resolution
%                               If val==0, the points are plotted
%                               otherwise val determines the resolution of the interpolated grid
%
% Info:
%   1-dim data:
%       Each point is plotted as a dot at height 1. 
%       The height can be changed by Option <'height',val>
%       To change the marker, the option <'Marker','something'> should be used
%
%   2-dim/3-dim data 
%       A point cloud is plotted
%
% E.g.: clf; hold on; clear all; load trimesh3d; plotm([x y z]','resolution',500); plotm([x y z]','resolution',0); view(3); plotm('rotate',0);
%       plotm(randn(2,40),'.-')
%       plotm(randn(1,40),'height',4);
%
% See also: surfm, plot, plot3, stem
%
% Written by: tommsch, 2016

% XX Write plotm4, using the commented out code below
% XX make plotm plot sequences
% XX hull for 3d plot

\subsection*{Syntax}
\begin{param}
    \item[{plotm( data, [options])}]
\end{param}

\subsection*{Input}
\begin{param}
    \item[data] One of the following:
    \begin{param}
        \item[dim x N vector] where $\texttt{dim}=1,2,3$.
        \item[sequence]
        \item[cell array of 1x2 vectors]
    \end{param}
\end{param}

\subsection*{Options}
\begin{param}

\item['box',int]        Plots the hypercube of dimension \texttt{int} with volume 1
\item['rotate',double]  Rotates the current plot by 360 degree in steps of \texttt{rotate} degrees.
\item[\textbullet] Most Matlab options which are passed as \emph{Name-Value} pairs should work, 
in particular Matlab linespecs.
\end{param}

\subsubsection*{Options for 1-dimensional plot}
\begin{param}
\item['height',val]     scalar or $1\times 2$ vector, \defval{\texttt{[0,1]}}\\
                        Determines the length of the lines to be plotted.
    \begin{param}                        
    \item[scalar] Line goes from 0 to \text{val}
    \item[vector] Line goes from \text{val(1)} to \texttt{val(2)}
    \end{param}                        
\end{param}

\subsubsection*{Options for 2-dimensional plot}
\begin{param}                        
   
\item['hull']              Plots the convex hull
\item['boundary',val]      scalar, \defval{\texttt{[]}}\\
                           Plots the boundary 
    \begin{param}
    \item[val>0]           Boundary is computed using a Delaunay triangulation
    \item[-1<=val<=0]      Boundary is computed with the Matlab function "boundary"
    \item[-inf<val<-1]     only points near the boundary are plotted    
    \end{param}                               

\end{param}

\subsubsection*{Options for 3-dimensional plot}
If no option of the ones below are given, the algorithm decides by itself what to plot.
\begin{param}      

\item['resolution',val]    scalar, \defval{depends on the input}
                           Determines the resolution
\begin{param}                           
       \item[0]      The points are plotted
       \item[scalar] Determines the resolution of the interpolated grid
\end{param}        
\item['contour']           Plots contour lines
\item['surface']           Plots a surface
\item['point']             Plots a point cloud
\end{param}

\subsection*{Example Usage}
\begin{param}
\item[{plotm(randn(1,40))}] 
\item[{hold on; plotm(randn(2,40),'.-','box',2)}]
\item[{plotm(randn(3,40),'resolution',0,'MarkerSize',100)}]
\item[{hold on; plotm(randn(3,40),'resolution',100,'surface','contour'); view(3);}]
\item[{plotm({[1 2];[4 6];[7 8]})}]
\item[{plotm(sequence(randn(20),[0;0]),'rotate',10)}]
\item[{plotm(sequence(randn(20,1),[0]))}]
\end{param}

\subsection*{Note}
\begin{itemize}
    \item More options may be added, and some options may be removed in the future.
\end{itemize}


\section{\texttt{parsem}}\label{parsem}
This function is meant to parse \texttt{varargin}.


%%%%%%%%%%%%%%%%%%%
% EOF
%%%%%%%%%%%%%%%%%%%