source: Sophya/trunk/SophyaLib/Manual/piapp.tex@ 2845

\documentclass[twoside,11pt]{article}
% \usepackage[latin1]{inputenc}
% \usepackage[T1]{fontenc}
\usepackage[francais]{babel}
\usepackage{graphicx}

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{latexsym}

\usepackage{palatino}

%  Definition pour Docs Sophya
\usepackage{defsophya}

\usepackage{makeidx}

\usepackage[ps2pdf,bookmarks,bookmarksnumbered,%
              urlcolor=blue,citecolor=blue,linkcolor=blue,%
                pagecolor=blue,%hyperindex,%
                 colorlinks=true,hyperfigures=true,hyperindex=true
           ]{hyperref}

\setlength{\textwidth}{17cm}
\setlength{\textheight}{21.5cm}
\setlength{\topmargin}{0.5cm}
\setlength{\oddsidemargin}{0.cm}
\setlength{\evensidemargin}{0.cm}
\setlength{\unitlength}{1mm}

% \newcommand{\piacommand}[1]{
%  \framebox{\bf \Large #1 } \index{#1} % (Command) 
%}
% \newcommand{\piahelpitem}[1]{
%  \framebox{\bf \Large #1 } \index{#1} (Help item)
%}

\newcommand{\piacommand}[1]{
$\blacksquare$ \hspace{3mm} {\bf \Large #1 } \index{#1} % (Command) 
}

\newcommand{\piahelpitem}[1]{
$\square$ \hspace{3mm} {\bf \Large #1 } \index{#1} (Help item) 
}

\newcommand{\myppageref}[1]{ (p. \pageref{#1} ) }

\makeindex     %  Constitution d'index

\begin{document}
\begin{titlepage}
%  The title page - top of the page with the title of the paper
\titrehp{piapp \\ An interactive data analysis tool}
%  Authors list
\auteurs{
R. Ansari            &  ansari@lal.in2p3.fr       \\
E. Aubourg           &  aubourg@hep.saclay.cea.fr \\
C. Magneville        &  cmv@hep.saclay.cea.fr     \\
O. Perdereau         &  perderos@lal.in2p3.fr     \\
}
% \author{R. Ansari {\tt ansari@lal.in2p3.fr} \\
% E. Aubourg {\tt aubourg@hep.saclay.cea.fr} \\
% C. Magneville {\tt cmv@hep.saclay.cea.fr} 
% }
\vspace{1cm}
\begin{center}
{\bf \Large piapp Version: 3.985 (V\_Mai2005) } 
\end{center}
\titrebp{5}

\end{titlepage}

\newpage
\tableofcontents
\newpage

\section{Introduction}
\index{piapp}
{\bf piapp} (or {\bf spiapp}) is an interactive data analysis 
and visualization  program. It is based on the {\bf PI} GUI library 
and the {\bf SOPHYA}
(or {\bf PEIDA++}) C++ data analysis class library 
\footnote{see http://www.sophya.org}. 
This document contains an overview of piapp possibilities as well as 
a copy of the on-line help (accessible through the menu {\tt File/Help}). 
Once the SOPHYA/piapp (or PEIDA++/piapp) environment 
\footnote{ The environment variables {\tt SOPHYABASEREP} (or {\tt EROSBASEREP}),
{\tt SOPHYACXX} (compiler selector), the shared library path 
{\tt LD\_LIBRARY\_PATH} and the executable search path {\tt PATH} must
be defined}
has been initialized, {\bf piapp} can simply be started on the command
line. {\tt (s)piapp -h} provides a brief help of the command line 
arguments. Xtoolkit options can also be specified as command line
arguments.
\begin{verbatim}
csh> spiapp -h
 PIOPersist::Initialize() Starting Sophya Persistence management service
SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx

 piapp: Interactive data analysis and visualisation program
 Usage: piapp [-nored] [-nosig] [-nosigfpe] [-nosigsegv] [-hidezswin]
              [-tmpdir TmpDirectory] [-help2tex] [-exec file [args]]
  -nored : NoRedirect StdOut/StdErr
  -nosig : Don't catch SigFPE, SigSEGV
  -nosigfpe -nosigsegv: Don t catch SigFPE / SigSEGV
  -hidezswin : Hide Zoom/Stat/ColMap window
  -tmpdir TmpDirectory: defines TMDIR for temporary files
  -help2tex: Create a LaTeX help file (piahelp.tex)
  -exec file [args] : Execute command file
\end{verbatim} 
Once {\bf piapp} is started, a main window, containing the menu bar, 
an upper part containing the zoom and colormap window for 
image displays, memory and CPU usage and a terminal like 
window in the lower part appears. The figure \ref{figmainwin}
shows an image of the piapp main window.
\begin{verbatim}
csh> spiapp 
 PIOPersist::Initialize() Starting Sophya Persistence management service
SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
>>>>> Starting piapp <<<<<
SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
Version: piapp=3.55  PI=3.8  SOPHYA=1.376
 --piapp: Creating Tmp Directory: ./PIATmp_aadrPa/
 PIColorMap::PIColorMap(CMapId id) Allocating ColorMap Grey32 ...
 PIColorMap::PIColorMap(CMapId id) Allocating ColorMap InvGrey32 ...
 PIColorMap::PIColorMap(CMapId id) Allocating ColorMap ColRJ32 ...
 registration of contour commands
 registration of flow chart commands
SOPHYA Version  1.3 Revision 76 (V_Jun2002) -- Jul 31 2002 12:26:37 cxx
  NamedObjMgr::SetTmpDir()+XNTuple::SetSwapPath() ./PIATmp_aadrPa/
\end{verbatim}

C++ code can be executed within the piapp application, easing the 
development and analysis task.
piapp can handle input data in different formats:
\begin{itemize}
\item[\bul] ASCII files (see {\tt ntfrascii} \myppageref{ntfrascii} and 
{\tt newnt} \myppageref{newnt} command)
\item[\bul] FITS format files, through menu {\bf File/Open-Fits}. 
(see also (see {\tt openfits} \myppageref{openfits}) command.
\item[\bul] PPF (Portable Persistence file Format) files through 
menu {\bf File/Open-PPF}. PPF files are the native persistence 
format in Sophya (or PEIDA++). 
\end{itemize}

The next sections present a quick tour of {\bf piapp}.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=16cm]{piapp_mainwin.eps}
\caption{piapp main window}
\label{figmainwin}
\end{center}
\end{figure}


\newpage
\section{A Tour of piapp}
\subsection{the Object Manager (NamedObjMgr)}
The {\bf piapp} application is built around an object manager
(class {\tt NamedObjMgr}) and a graphic application
(class {\tt PIStdImgApp}). Objects inheriting from 
the class {\tt AnyDataObj} can be managed through adapter 
classes (classes inheriting from {\tt NObjMgrAdapter}) by 
the object manager. 
\par
User sees the objects (such as Sophya objects Histo, NTuple,
Arrays, Images, SkyMaps, \ldots) kept in memory, organized 
in a single level tree structure. Four memory directories
are automatically created and can not be removed: \\
\centerline{\bf /home \hspace{10mm} /old \hspace{10mm} /tmp \hspace{10mm} /autoc}
The default working directory (in memory) is {\bf /home}.
Other directories can be created by the user.
\begin{center} 
{\bf Warning:} These are only the directory 
structure managed by the piapp application and do not 
correspond to the file system directories
\end{center}
The window {\bf ObjMgr} shown in figure \ref{figobjmgrw} 
can be used to navigate in the memory directories and 
execute simple operations on objects. This window 
can be displayed using the menu command
Menubar: {\bf Objects/ObjectManager}. 
The button \framebox{\small \bf SetCurObj} can be used to set the value
of the interpreter's variable {\tt cobj} to the selected 
object name. 
Refer to the commands in group {\bf Object Management} 
for more information.

\vspace*{5mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=10cm]{piapp_objmgr.eps}
\caption{The interactive object management window}
\label{figobjmgrw}
\end{center}
\end{figure}

\subsection{command language}
A basic command interpreter ({\bf piacmd}) is included in {\bf piapp} and 
other command interpreters can be inserted in the application 
framework.
This interpreter ({\bf piacmd} \myppageref{piacmd}) 
synthax is close to the c-shell 
(csh) shell script. It is possible to define and use variables
({\tt set} command, {\tt \$varname}), and execute loops 
({\tt foreach,for}), as well as simple tests 
({\tt if test then ... else ... endif}).
Commands from a file (default extension .pic) can be executed 
using the {\tt exec} command.
Long commands can be put on several lines, by ending a line
by the backslash \\ caracter, to signal that the command
continues on the next line.

The command macro below shows a sample piapp session, where 
data from the file {\tt demo.ppf} are displayed.
\begin{verbatim}
#  Trace mode -> On
traceon
#  Deleting all objects in the current directory
delobjs *
#  Opening the PPF file demo.ppf
openppf demo.ppf
# Various displays in a graphic window, divided into 2x2 zones
zone 2 2
#  1D histogram display
disp h1d blue
#  2D histogram display
disp h2d
#  Function display
func sin(x)/x 0.1 10. 200 gold
#  Surface representation of a matrix
surf mtx1 colbr32
# Contour representation of a matrix
contour mtx1 'colrj32 normalline ncont=7'
#  3D representation of points using a PAW like command
n/plot nt31.z%y%x ! ! win
#  3D points superimposed on the previous display
nt3d nt32 x y  z ex ey ez - - 'same fcirclemarker7 red'
\end{verbatim}

\subsection{NTuple vue / PAW like commands}
It is possible to plot various expressions of objects, seen as
a 2D table, with named columns. This possibility exist not only 
for NTuples, but also for most objects (from SOPHYA) handled 
by piapp. See command groups {\bf Expr.Plotting} and 
{\bf pawCmd}

\subsection{C++ execution inside piapp}
For more complex processings, where the full power of C++
and the class libraries are necessary, {\bf piapp} provide 
the possibility of executing C++ code, without the burden 
of having to write a complete program. The objects 
present in the current directory are automatically 
declared. The communication with the piapp application 
is done by the {\bf NamedObjMgr} class. 
Two macros {\tt KeepObj()} and {\tt DisplayObj()}
simplify the task of keeping newly created objects.
In the example below, we first create a noisy signal 
in a vector, and we keep it in the application 
(Notice the use of multiline command) :

\begin{verbatim}
Cmd> c++exec c++exec Vector in(1024); \
Cmd> in = RandomSequence(RandomSequence::Gaussian, 0., 1.); \
Cmd> for(int kk=0; kk<in.Size(); kk++) \
Cmd> in(kk) += 2*sin(kk*0.05); \
Cmd> KeepObj(in);
\end{verbatim}
We can of course display the resulting vector:
\begin{verbatim}
Cmd> disp in 
\end{verbatim}

And, at a subsequent stage, make a low pass filter 
on the vector in:
\begin{verbatim}
Cmd> c++exec Vector out(1024); \
Cmd> int w = 2; \
Cmd> for(int k=w; k<in.Size()-w; k++) \
Cmd>   out(k) = in(Range(k-w, k+w)).Sum()/(2.*w+1.); \
Cmd> KeepObj(out);
\end{verbatim}

We can display the new vector {\tt out} overlayed 
on the previously displayed vector:
\begin{verbatim}
Cmd> disp out 'red same'
\end{verbatim}

See command group {\bf CxxExecutorCmd} for more information,
and the option window activated by the menu: 
{\bf Special/CxxExecOption}.

\subsection{Extending the application}
The {\bf piapp} application can easily be extended by the user.
This is done through shared libraries which can be opened 
and used by the application. 
Two main methods can be used (see  command group 
{\bf ExternalModules}) : 
\begin{itemize}
\item Creation of user functions. A shared library containing 
at least one user function with the following prototype
should be created:
\begin{verbatim}
extern "C" {
  void myfonction(vector<string>& args);
}
\end{verbatim}
The class {\bf NameObjMgr} should be used to communicate with the 
application. The {\tt link} \myppageref{link} and {\tt call} \myppageref{call}
should be used to load and execute user functions. An example of
user function can be found in DemoPIApp/user.cc exlink.pic.

\item Creation of loadable modules: Loadable modules can be 
used to extend the application possibilities in a way totally 
transparent to the user. It is possible to define new commands, 
handling of new object types, additional graphic functionalities
in a loadable module.

The class {\bf CmdExecutor} is the base class for extending piapp.
A shared library should be built, containing two functions,for
the activation and deactivation of the module, with the following
prototype (where {\tt mymodule} is the module's name.
\begin{verbatim}
extern "C" {
  void mymodule_init();
  void mymodule_end();
}
\end{verbatim}

\end{itemize}

\newpage
\section{Interactive graphics}
Display of objects in piapp are managed by {\bf PIDrawers} and three
main viewers:

\begin{itemize}
\item[\bul]  PIScDrawWdg: Handler of 2-D drawers with interactive zoom
(see {\bf PIScDrawWdg} \myppageref{PIScDrawWdg} for more information.
\item[\bul] PIImage: Manages display of a 2-D array (P2DArrayAdapter) as an image 
and controls a zoom widget, as well as a global image view widget, and 
a color map view widget. (see {\bf PIImage} \myppageref{PIImage} for 
 more information.
\item[\bul] PIDraw3DWdg: handler of 3-D drawers with interacive rotation
and zoom. (see {\bf PIDraw3DWdg} \myppageref{PIDraw3DWdg} for more information.
\end{itemize}

\par
Refer to the command reference section on windows ({\bf Windows}
\myppageref{Windows})
for information on the different type of windows used by piapp 
and their properties.

\par
In addition, a number of control windows can be used to examine and 
change view properties of differents viewers and drawers.
\begin{itemize}
\item[] PIDrawerTools (see page \myppageref{secdrwtools})
\item[] PIAxesTools (see page \myppageref{secaxestools})
\item[] PIImageTools (see page \myppageref{secimagetools})
\item[] PIHisto2DTools (see page \myppageref{sech2dtools})
\item[] PIContourTools (see page \myppageref{secconttools})
\end{itemize}


\newpage
\section{piapp command reference}
\label{piappcmdref}
This section contains the description of piapp commands. This information
is available on-line, through the help command, or through a graphic
window, accessible  through the menu {\tt File/Help}.
The help items and command are divided into different sections,
where related commands are grouped. \\[10mm]

% \include{piahelp}
\input{piahelp.tex}

%  La partie des appendix
\appendix

\newpage
\section{DrawerTools} \index{DrawerTools}
\label{secdrwtools}
The {\bf PIDrawerTools}, shown in the figure \ref{figdrwtools} can be 
used to change the graphic attributes (color, font, marker, \ldots)
of the Drawers displayed in 2D displays 
({\bf PIScDrawWdg} \myppageref{PIScDrawWdg}) or 3D displays 
({\bf PIDraw3DWdg} \myppageref{PIDraw3DWdg}), as well in image displays
{\bf PIImage} (\myppageref{PIImage}). The PIDrawerTools can be activated
either using {\tt Alt<G>} on a PIScDrawWdg,PIDraw3DWdg,PIImage, 
or through the menu {\bf Tools/Show DrawerTools}.
A given drawer can be selected through the DrawerId selector.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=7cm]{piapp_drwtools.eps}
\caption{PIDrawerTools}
\label{figdrwtools}
\end{center}
\end{figure}
\newpage

\newpage
\section{AxesTools} \index{AxesTools}
\label{secaxestools}
The {\bf PIAxesTools}, shown in the figure \ref{figaxestools} can be used to 
control and change the setting of axes on 2D displays 
({\bf PIScDrawWdg} \myppageref{PIScDrawWdg}).
The PIAxesTools can be activated
either using {\tt Alt<A>} on a PIScDrawWdg or through 
the menu {\bf Tools/Show AxesTools}.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_axestools.eps}
\caption{PIAxesTools}
\label{figaxestools}
\end{center}
\end{figure}

\newpage
\section{ImageTools} \index{ImageTools}
\label{secimagetools}
The {\bf PIImageTools}, shown in the figure \ref{figimgtools} can be used to 
manipulate a display of type image. Image display are handled by the 
{\bf PIImage} (\myppageref{PIImage}). The PIImageTools can be activated
either using {\tt Alt<O>} on a PIImage, or through the menu 
{\bf Tools/Show ImageTools}.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_imgtools.eps}
\caption{PIImageTools}
\label{figimgtools}
\end{center}
\end{figure}

\newpage
\section{Histo2DTools} \index{Histo2DTools}
\label{sech2dtools}
The {\bf PIHisto2DTools}, shown in the figure \ref{figh2dtools} can be 
used to control and change the display caracteristics of 2D histograms.
PIHisto2DTools can be activated 
either using {\tt Alt<O>} on a PIScDrawWdg, when the active 
drawer is a PIHisto2DDrawer, or through the generic drawer tool 
PIDrawerTools.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_h2dtools.eps}
\caption{PIHisto2DTools}
\label{figh2dtools}
\end{center}
\end{figure}

\newpage
\section{ContourTools} \index{ContourTools}
\label{secconttools}
The {\bf PIContourTools}, shown in the figure \ref{figconttools} can be 
used to control and change the caracteristics of contour displays.
PIContourTools can be activated  
either using {\tt Alt<O>} on a PIScDrawWdg, when the active 
drawer is a PIContDrawer, or through the generic drawer tool 
PIDrawerTools.

\vspace*{10mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=11cm]{piapp_conttools.eps}
\caption{PIContourTools}
\label{figconttools}
\end{center}
\end{figure}



Both drawing options  (e.g. color, line type, fonts...) and contour 
determination parameters (e.g. contour number and levels) are controlled 
by {\bf PIContourTools}. 

\subsection{Drawing options}
The top choices in {\bf PIContourTools} 
concern the color map (left choice) or color (right choice) of the contours.
If a color map has been chosen, it is used to give each contour a color 
(according to its level). If no color map has been chosen, contours may be 
given a color using the left choice box. 

Contour are by default traced by lines. 
Alternatively (or in addition) the user may ask to trace them by markers 
or to put numeric labels (with the contour's level) aside the contour. 
These options are enabled/disabled by the {\tt LineON}, {\tt MarkerON} and {\tt LabelON} 
buttons from {\bf PIContourTools}. 

Options may be recovered ({\tt GetAtt}) or set ({\tt SetAtt})
from/to a drawer. Setting an option which adds to the screen will be immediately visible 
whereas unsetting it requires a {\tt Refresh} to be visible.  


\subsection{Contour options}
The contouring routines in {\tt spiapp} are based on a hack of the {\tt GNUPlot} 
routines. Contours are determined from a grid of values 
using an interpolation scheme. Three schemes may be used
(selected by the left menu) : 
\begin{enumerate}
\item Linear interpolation (default), selected by the  {\tt Int. Lin.} option  
\item A cubic spline algorithm, selected by the  {\tt CubicSpl} option 
\item A 2d BSpline algorihm, selected by the  {\tt B-Spline} option
\end{enumerate}
 
Contour levels and number are automatically 
determined by the program.  They may be specified differently,  
 through command-line options 
(see section \ref{piappcmdref} for the help of the contour/ntcont commands)
or the lower part of the {\bf PIContourTools} window. 

The user may specify one  of the following alternatives : 
\begin{enumerate}
\item the number of contour (their level beeing automatically set). 
To do this, select {\tt LevelNum} in the right menu and enter the contour number 
in the left box below.
\item the levels of the contours, through an array of numerical values 
(e.g. 1,4,6,9,27,4.5 will result in 6 contour lines being drawn, if possible and necessary). 
To do this, select {\tt LevelDisc} and enter the contour number (left box) 
and the values (right box) separated by ``{\tt ,}''.
\item the levels of the contours through an initial (lower) value and an increment.
For this, select {\tt LevelInc} and enter the contour number (left box)
and the initial value and increment in the right box, as above.
\item come back to the default situation, by choosing {\tt LevelAuto}
\end{enumerate}

Once these options are set, it is necessary the the program recomputes 
the contour lines. This is commanded by the {\tt SetParm} button. 


\newpage
\addcontentsline{toc}{section}{Index}
\printindex

\end{document}