Index: /trunk/SophyaLib/Manual/piapp.tex
===================================================================
--- /trunk/SophyaLib/Manual/piapp.tex	(revision 2171)
+++ /trunk/SophyaLib/Manual/piapp.tex	(revision 2171)
@@ -0,0 +1,470 @@
+\documentclass[twoside,11pt,francais]{article}
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage[francais]{babel}
+\usepackage{graphicx}
+
+\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{\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.55 (V\_Jul2002) } 
+\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 DPCBASEREP} (or {\tt EROSBASEREP}),
+{\tt EROSCXX} (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
+#  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}
+
+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.
+
+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}
+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 using {\tt Alt<O>} on a 
+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 using {\tt Alt<O>} on a 
+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}
+
+
+\newpage
+\addcontentsline{toc}{section}{Index}
+\printindex
+
+\end{document}
