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

\documentclass[twoside,10pt]{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}{15cm}
\setlength{\textheight}{20.5cm}
\setlength{\topmargin}{0.cm}
\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{\rond}{$\bullet \ $}
\newcommand{\etoile}{$\star \ $}
\newcommand{\cercle}{$\circ \ $}
\newcommand{\carre}{$\Box \ $}

%%%% Definition des commandes pour l'aide en ligne
\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{\menubar}[1]{\hspace{1mm} \framebox{\it MenuBar::#1} \hspace{1mm}}

\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: 4.3 (V\_Sep2007) } \\
{\bf SOPHYA version=4.2 , PI version= 4.2 }
\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} \footnote{see http://www.sophya.org}
(or {\bf PEIDA++} \footnote{PEIDA++ has been used in EROS software. 
(http://eros.in2p3.fr). It is not maintained anymore.}) 
C++ data analysis class library. 
\par 
{\bf piapp} is a powerful command oriented tool for visualising and analysing data.
Its main features are summarised below:
\begin{itemize}
\item[\rond] Image, multiple 2D and few 3D representations
\item[\rond] Highly interactive graphics, with postscript as export format
\item[\rond] Capability to handle large data sets. Data can be imported and 
exported in different formats: ASCII, PPF and FITS.
\item[\rond] Interactive analysis: 2D/3D distributions, histograms, FFT \ldots 
\item[\rond] Flexible c-shell inspired command interpreter. 
\item[\rond] Possibility to perform more complex operations in C++, on objects
managed by the application through the on-the-fly compilation and execution
of c++ code fragments in piapp. 
\item[\rond] piapp is a multi-threaded program with separate threads for graphics
and command execution, ensuring interactive response, even while heavy 
computation is being performed. In addition, thread safe commands can be executed 
in separate threads, for taking advantage of multi CPU (or CPU-cores) workstations.
\item[\rond] The application can be easily extended through modules which can be
loaded at run time.  
\end{itemize}

\subsection{Acknowlegments}
Many people have contributed to the development SOPHYA and/or the PI library 
and (s)piapp interactive analysis tool.
we are grateful to the following people:

\begin{tabular}{lcl}
Reza Ansari & \hspace{5mm} & (LAL-Univ.Paris Sud, Orsay) \\
Eric Aubourg & & (DAPNIA-CEA/APC, Saclay) \\
Sophie Henrot-Versille & & (LAL-IN2P3/CNRS, Orsay) \\
Alex Kim & & (LBL, Berkeley) \\
Guy Le Meur & & (LAL-IN2P3/CNRS, Orsay) \\
Eric Lesquoy & & (DAPNIA-CEA, Saclay) \\
Christophe Magneville & & (DAPNIA-CEA, Saclay) \\
Bruno Mansoux & & (LAL-IN2P3/CNRS, Orsay) \\
Olivier Perdereau & & (LAL-IN2P3/CNRS, Orsay) \\
Nicolas Regnault & & (LPNHE-IN2P3/CNRS, Paris) \\
Benoit Revenu & & (APC/Univ.Paris 7, Paris) \\
Francois Touze & & (LAL-IN2P3/CNRS, Orsay) \\
\end{tabular}

We thank also the persons who have helped us by useful suggestions, among others : \\
S. Bargot, S. Plasczczynski, C. Renault and D. Yvon.

%%%
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=15cm]{piapp_mainwin.eps}
\caption{piapp main window}
\label{figmainwin}
\end{center}
\end{figure}
\subsection{starting piapp}
 {\bf piapp} can simply be started on the command line in a terminal window 
once the SOPHYA/piapp  environment has been initialised. 
The environment variables {\tt SOPHYABASE} should contain the directory 
where SOPHYA/piapp has been installed. the shared library path 
{\tt LD\_LIBRARY\_PATH} must contain {\tt \$SOPHYABASE /slb} and the 
current directory {\tt .} and the executable search path {\tt PATH} must
contain {\tt \$SOPHYABASE /exe}. Refer to the SOPHYA overview manual 
for more information on SOPHYA directory structure. \\
\par
{\tt (s)piapp -h} provides a brief help of the command line 
arguments. Xtoolkit options can also be specified as command line
arguments. {\bf spiapp} is the name of SOPHYA/piapp executable, 
in order to distinguish it from PEIDA/piapp. 
\begin{verbatim}
csh> spiapp -h
 SophyaInitiator::SophyaInitiator() BaseTools Init
 PIOPersist::Initialize() Starting Sophya Persistence management service 
SOPHYA Version  2.1 Revision 0 (V_Nov2007) -- Nov 24 2007 13:08:58 gcc 3.3 
20030304 (Apple Computer, Inc. build 1495)
 piapp: Interactive data analysis and visualisation program 
 Usage: piapp [-nored] [-doublered] [-termread] [-term] 
              [-hidezswin] [-small] [-nosig] [-nosigfpe] [-nosigsegv] 
              [-tmpdir TmpDirectory] [-help2tex] [-exec file [args]] 
  -nored : Don't redirect stdout/stderr to piapp console
  -doublered : Redirect stdout/stderr to piapp console AND the terminal 
  -termread : Read commands on terminal (stdin)
  -term : equivalent to -nored -termread -small 
  -hidezswin : Hide Zoom/Stat/ColMap window 
  -small : Create small size main piapp window 
  -nosig : Don't catch SigFPE, SigSEGV 
  -nosigfpe -nosigsegv: Don t catch SigFPE / SigSEGV 
  -tmpdir TmpDirectory: defines TMDIR for temporary files 
  -help2tex: Create a LaTeX help file (piahelp.tex)
  -exec file [args] : Execute command file (last option)
\end{verbatim} 
Once {\bf piapp} is started, the main piapp window appears.
It contains the menu bar, an upper part with the zoom and colormap 
widgets for  image displays, memory and CPU usage and a terminal like 
widget (piapp console, see {\bf PIConsole} \myppageref{PIConsole}) 
in the lower part. The figure \ref{figmainwin}
shows an image of the piapp main window.
{\tt stdout/cout, stderr/cerr} are redirected to the piapp console and 
commands can be entered in this widget. It is also possible to keep
the terminal where piapp was started  for {\tt stdout/stderr} (flag {\tt -nored}).
The flag {\tt -term} activate a command reader on the terminal 
It is also possible to have a command reader on  the terminal ({\tt stdin}).  \\[1mm]
The environment variable {\tt PIDEFAFSZFRAC} controls the automatic selection
of font size for drawing axes, as a function of the window size (typical value 0.03 \ldots 0.1).
Check the command {\tt setdefafsz } \myppageref{setdefafsz} and {\tt setaxesatt} 
\myppageref{setaxesatt} for more information. \\[1mm]

\par 
In section 2, we present  a quick tour of {\bf piapp}.  
a brief overview of piapp graphics, supported data formats, interactive
analysis possibilities, the command interpreter and c++ execution 
are presented in the following sections. 
Section \ref{piappcmdref} contains a brief description of all piapp commands 
and help items. Various interactive control windows are described in appendix.

\subsection{DemoPIApp and DemoData}
The directory {\bf DemoPIApp} contains a number of example scripts, such as the 
{\tt demo.pic} and the associated data file {\tt demo.ppf}. It contains 
also examples of loadable modules for piapp. The  DemoPIApp/CONTENT 
file contains a brief description of the different files. \\
The {\bf DemoData} contains a number of data files, in PPF and FITS format, which are 
used for the examples in this document.

\subsection{Warnings/Known problems}
\begin{enumerate} 
\item It might  be necessary to define the environment variable 
{\bf PIXKBMODMASK}, used by the libPI.a to map correctly 
the {\tt <Alt>} key with some X servers (in particular with 
X11 on MacOS X). \\
{\tt csh> setenv PIXKBMODMASK 2 }
However, the default value has been changed in PI/piapp V=4.1 and it should not be
necessary anymore to define PIXKBMODMASK.
%%
\item The output redirection uses unix pipes. On Linux, with commands
producing long outputs, the application may block because of incorrect management
of pipes. If this happens, use piapp with  {\tt -nored} flag. This problem has been 
in principle solved with SOPHYA V=2.1 / piapp V=4.1
\end{enumerate}

\newpage
\section{A Tour of piapp}
\subsection{Interacting with piapp, getting help}
Users interact with piapp through commands entered in the piapp-console
(or the unix terminal), and through the different menus. 
Some of the possibilities of the piapp-console are described
in {\bf PIConsole} help item, in the command reference section \myppageref{PIConsole}.
The description
of the commands in available online using the help command.
An online help window can be displayed by \menubar{File / Help}.
Commands and help items are grouped in categories which can be
selected using the OptionMenu in the Help window.
\begin{verbatim}
Cmd> help func 
Displays a function y=f(x) (Fills a vector with function values)   
 Usage: func f(x) xmin xmax [npt graphic_attributes]               
  Related commands: funcff func2d func2dff   
Cmd> func sin(x)/x 0.1 10 100 'red line=solid,2'
---> Graphic display of the function
\end{verbatim}
The directory {\tt DemoPIApp} contains a number of example
command script and sample data files.

\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{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/Commander}) is included in {\bf piapp} and 
other command interpreters can be inserted in the application 
framework.
This interpreter ({\bf Commander} \myppageref{Commander}) 
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/DataTables, but also for most objects (from SOPHYA) handled 
by piapp. The related commands are grouped under {\bf Expr.Plotting} and 
{\bf pawCmd} and are described in section \ref{tableplot}.

\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 DispObj()}
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); \
...? in = RandomSequence(RandomSequence::Gaussian, 0., 1.); \
...? for(int kk=0; kk<in.Size(); kk++) \
...? in(kk) += 2*sin(kk*0.05); \
...? 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); \
...? int w = 2; \
...? for(int k=w; k<in.Size()-w; k++) \
...?   out(k) = in(Range(k-w, k+w)).Sum()/(2.*w+1.); \
...? 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 section \ref{flycplusplus} and command group {\bf CxxExecutorCmd} 
for more information.

\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}

%%%%%%%%%% Section 3: Graphiques
\newpage
\section{Interactive graphics} 
\label{intgraphics}
%%%
\subsection{Display commands}
Many objects managed by piapp have a default graphic representation. The 
{\bf disp} command  \myppageref{disp} can be used to display the object, while 
other commands like {\bf surf} \myppageref{surf} , {\bf imag} 
or {\bf contour} \myppageref{contour} will try to force a given graphic representation. 

Data from table like objects can be plotted using commands like {\bf nt2d}
\myppageref{nt2d} or {\bf nt3d} \myppageref{nt3d}. Most objects in piapp 
can also be manipulated like table for plotting purposes, using commands
like  {\bf plot2d} \myppageref{plot2d} , {\bf plot3d} \myppageref{plot3d} 
or {\bf n/plot}  \myppageref{nZplot}. These commands are described in section
\ref{tableplot}. 

Commands producing a graphic output have usually an optional argument called \\
{\tt graphic\_attributes} or {\tt gr\_att}. \\
This argument provide a flexible and easy 
way to change and customise the output graphic, as discussed in the paragraphs below.
 
The piapp graphics can be exported in postscript (.ps) or encapsulated postscript 
(.eps) format. The commands {\bf w2ps} \myppageref{w2ps} and 
 {\bf w2eps} \myppageref{w2eps} as well the menu  \menubar{PostScript} can 
 be used to export graphics. \\[2mm]
The examples in the following pages illustrates the usage of some piapp graphic commands. 
% \newpage
\begin{enumerate}
\label{francetopo}
\item Image display. The following example uses the data file francetopo.ppf
which can be found in the {\bf DemoData} directory. This PPF file contains 
a TMatrix$<$int\_2$>$ (short integers) representing  30 arcmin gridded
($\sim$ 1 km N-S $\times$ 0.7 km E-W) elevation (or altitude)
for the area centered on France. It has been made using topographic 
data (DEM: Digital Elevation Model) available from the {\bf N}ational 
{\bf G}eophysical {\bf D}ata {\bf C}enter 
\href{http://www.ngdc.noaa.gov/mgg/topo/}{({\bf NGDC/GLOBE})}
\footnote{NGDC web site: \hspace{5mm} 
http://www.ngdc.noaa.gov/ }.
In section \ref{tableplot}, an example shows how to use this data set to 
create altitude distribution histogram for selected regions.
\begin{verbatim}
#  Open a PPF file containing topographic data for france
#  as a TMatrix<short> 1332x1548 
#  The file is in the directory DemoData/
openppf francetopo.ppf
#  Display the matrix, whit a zoom factor, lut and color map
disp francetopo 'zoom/3 lut=lin,-700,800 colbr128 win' 
w2eps francetopo.eps 
\end{verbatim}
\begin{center}
\includegraphics[width=13cm]{francetopo.eps}
\end{center}

\item Simple 2D graphics with vector displays
\begin{verbatim}
#  Create and initialize two vectors - prevent display : nodisp
Cmd> newvec vva 100 sin(x/10.+0.7)+cos(x/7.+1.4)*1.26 nodisp 
Cmd> newvec vvb 100 sin(x/10.)+cos(x/7.)*1.34 nodisp 
#  Set axe drawing options 
Cmd> setaxesatt 'font=times,bold,16 minorticks tickslen=0.02,0.012'
#  Display the two vectors, with different graphic attributes
Cmd> disp vva 'red line=solid,2 notitle'
#  Define a title for the graphic
Cmd> settitle 'Example-1: 2 vectors'  ' ' 'font=times,bolditalic,18'
Cmd> disp vvb 'blue marker=box,7 same'
#  Save the graphic into an eps file
Cmd> w2eps gr2vec.eps
\end{verbatim}
% \begin{figure}[ht!]
\begin{center}
\includegraphics[width=12cm]{gr2vec.eps}
% \label{g22vec}
\end{center}
%%%
\item Creating a comparison chart using {\bf bargraph}
\begin{verbatim}
#  Representation du PNB (en $, 2003) pour quelques pays
set pays ( Allemagne Espagne France Italie Pays-Bas Suisse UK USA )
set pnbh ( 22670 14430 22010 18960 23960 37930 25250 35060 )
setaxesatt 'font=times,bold,16'
bargraph pnbh pays - 'blue horizontalbars nofill packfrac=0.65 font=helvetica,bold,14'
setaxelabels 'PNB / Hab , $ 2003' ' ' 'font=times,bold,16'
w2eps pnbargraph.eps 
\end{verbatim}
\begin{center}
\includegraphics[width=12cm]{pnbbargraph.eps}
\end{center}
%%%
\item Displaying a matrix as a surface 
\begin{verbatim}
openppf demo.ppf mtx1
setaxesatt 'font=time,bold,16'
surf mtx1 'colbr128 line=solid,1 grey'
w2eps surfcol.eps
\end{verbatim}
\begin{center}
\includegraphics[width=13cm]{surfcol.eps}
\end{center}

\end{enumerate}

%%%%%%%%%%
\subsection{Graphic objects in piapp}
The piapp graphics is handled by the {\bf PI} \footnote {http://www.sophya.org/PI} library,
which provide a large variety of 2D representations, 
few 3D graphics and powerful image display. \\
Currently, all graphic representations, except for image displays, are handled
through {\bf PIDrawers} which are managed by a viewer. A viewer can 
manage several {\bf PIDrawers} objects which correspond then to a multilayer 
graphic display. The viewers are also responsible for managing user
interactions. \\
Image displays are handled through a specific viewer 
{\bf  PIImage} which is also capable of managing PIDrawer objects 
for multi-layer 2D overlay vector graphics. \\[2mm]
%%
Main piapp/PI graphic viewers, windows and drawer objects are described if 
the following sections.

\subsubsection{PIScDrawWdg (2D display)}
The {\bf PIScDrawWdg} handles a set of  of 2-D drawers, managing 
the 2D coordinate  system and interactive zoom. The axes drawing is 
handled by a specialised drawer, number 0, which also manages various added 
graphic elements (text \ldots). The list of various mouse and 
keyboard actions is described in the reference section, under {\bf PIScDrawWdg} \myppageref{PIScDrawWdg} title. In particular, mouse-button-2 can be used 
to zoom on a particular part, {\tt $<$Alt$>$A} activates the coordinates
and axes manipulation window ({\bf PIAxesTools}) and   {\tt $<$Alt$>$G} 
activates the PIDrawer graphic attributes control window ({\bf PIDrawerTools}).
%%%
\subsubsection{PIDraw3DWdg (3D display)}
The {\bf PIDraw3DWdg}  handles a set of of 3-D drawers, managing
interactive camera/object rotation (mouse-button-2) and zoom (mouse-button-2). 
{\tt $<$Alt$>$G} to display/activate  the PIDrawer graphic attributes 
control window ({\bf PIDrawerTools}).
See {\bf PIDraw3DWdg} \myppageref{PIDraw3DWdg} for a complete list of mouse
and keyboard actions.
Drawer 0 handles axes drawing and graphic elements.
%%%
\subsubsection{PIImage (Image Display)}
The display of 2-D arrays $A(i,j)$ as an image is managed by 
the {\bf PIImage} viewer/widget. The PI library interface  {\bf P2DArrayAdapter} is used
to represent a generic 2-D array. The array values are converted into an index, converted 
itself into a color by the use of a color-map or color-table {\bf PIColorMap}. 
$$ \mathrm{LUT:} A(i,j) \longrightarrow idx(i,j) \hspace{5mm} \mathrm{ColorMap:}
 idx(i,j) \longrightarrow col(i,j) $$
Currently index range is 0...255 with color-map having 32 or 128 distinct colors.
PIImage viewers  controls a zoom widget, as well as a global image view widget, and 
a color map view widget. A specific image control window can be activated using 
 {\tt $<$Alt$>$O}.  See {\bf PIImage} \myppageref{PIImage} for 
a complete list of mouse and keyboard actions. A base drawer (number 0) handles
axes drawing and added graphic elements. The colormap with the LUT information 
can also be displayed through a second drawer (PICMapDrawer). The colormap 
display in the main image window is controlled by the {\tt showcmap} graphic option.
%%%
\subsubsection{Windows}
The viewers described above are displayed in differnt kind of windows.
The graphic option {\tt next,win,same,stack,inset} can be used to control the way the
type of windows used, or the way the object is displayed in the window. 
Graphic windows can be divided into several zones
(Command {\bf zone} \myppageref{zone}). 

When an object is diplayed in piapp, a widget (PIWdg) is created which manages 
the drawer or the 2d-array.  The default name for this widget is the displayed 
object name. However, it is possible to specify a name using the graphic attribute: \\
\hspace*{5mm} {\tt wname=WidgetName} \\
It is possible to display multiple objects on a single widget, corresponding
to the superposition of the different drawers. Displaying an object superimposed
on the previously displayed object can be done using the graphic option 
{\tt same}. It is also possible to specify a target widget by its name, through 
the graphic option \\
\hspace*{5mm} {\tt samew=WidgetName} \\
It is also possible to specify the display of the drawer in a specific region
of the last displayed widget using the {\tt inset} option, or 
\hspace*{3mm} {\tt inset=fx1,fx2,fy1,fy2} \\
where {\tt fx1,fx2,fy1,fy2} express X and Y limits, as fractions of the widget size. 
 
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. \\
 
%%% 
\subsubsection{Drawers}
Graphical representation of most objects in piapp is 
handled through objects inheriting from the {\bf PIDrawer class}. A base drawer 
({\bf PIElDrawer}, number 0) is associated to the three viewers presented above,
and manages the axes drawing as well as the added graphic elements 
(text, arrow, \ldots). A drawer management menu 
can be activated using {\tt $<$Alt$>$D}. This menu can be used to move and resize
drawers, or to display a window for changing drawers graphic attributes. 
%%%
\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[] {\bf PIDrawerTools} activated using {\tt $<$Alt$>$G} or 
\menubar{Tools/Show DrawerTools} on any viewer (see page \myppageref{secdrwtools})
\item[] {\bf PIAxesTools} activated using {\tt $<$Alt$>$A} or 
\menubar{Tools/Show AxeTools} on PIScDrawWdg (see page \myppageref{secaxestools})
\item[] {\bf PIImageTools} activated using {\tt $<$Alt$>$O} or 
\menubar{Tools/Show ImageTools} on PIImage
(see page \myppageref{secimagetools})
\item[] {\bf PIHisto2DTools} activated using {\tt $<$Alt$>$O} or through the PIDrawerTools
for an active PIHisto2D drawer. (see page \myppageref{sech2dtools})
\item[] {\bf PIContourTools}  activated using {\tt $<$Alt$>$O} or through the PIDrawerTools
for an active PIContourDrawer  drawer.  (see page \myppageref{secconttools})
\end{itemize}
These control tools are briefly described in appendix.

%%%%%%%%%%
\subsection{Graphic attributes}
Graphic attributes are specified as a set of space separated strings. Use 
quotes to group them into a single argument parsed by the command
interpreter. The options are decoded by the different objects handling the 
graphic (viewer widget, drawer, axe drawer). \\
The complex decoding scheme is usually transparent for piapp users. 
However, there is an ambiguity when 
specifying some of the axes attributes, such as color or the font used for 
drawing the axes. The command {\bf setaxesatt}  (\myppageref{setaxesatt})
should thus be used to specify generic graphic attributes (color, font, line type) for axes. 

\subsection{Complex 2D array display} 
A specific graphic attribute can be specified when displaying 2D arrays 
with complex numbers as their content. By default, the complex arrays are rendered
using the modulus of the complex 
numbers ($\sqrt{\mathrm{real}(z)^2+\mathrm{imag}(z)^2}$), in particular for 
image and surface display {\tt (disp, imag, surf)}. It is however possible to change
this behaviour by specifying the following graphic attributes:
\begin{verbatim}
cdreal : graphic rendering using the real(z)
cdimag : graphic rendering using the imaginary part, imag(z)
cdphase : graphic rendering using the phase, atan2(real,imag)
cdmod : graphic rendering using the module. this is the defaut.
cdmod2 : graphic rendering using the module squared (re^2+im^2)

## Consider a complex matrix cmx
piapp> disp cmx 
# will represent the module(cmx) in grey/color scale
piapp> disp cmx 'cdphase'
# will represent the phase(cmx) in grey/color scale
\end{verbatim}


\subsubsection{PIScDrawWdg}
The {\bf PIScDrawWdg} which handles 2d graphics recognizes the following options: 
\begin{verbatim}
>> To define the 2D axes limits (in user coordinates)
   xylimits=xmin,xmax,ymin,ymax  
>>  To define the default drawing rectangle, in fraction of widget size
  defdrrect=x1,x2,y1,y2  (default: x1=y1=0.1  x2=y2=0.9) 
>> Axes flags :
  linx  logx  : Linear or logarithmic scale for X Axis
  liny logy : Linear or logarithmic scale for Y Axis
  axerl : Set X axis direction  Right to Left (or revax)
  axeud : Set Y axis direction  Up to Down (or revay)
  axelr : AxeDirLtoR   axedu : AxeDirDownUp
>> To change the background color (default=white)
  wbgcol=colname
  
\end{verbatim}
%%%
\subsubsection{PIDraw3DWdg}
The {\bf PIDraw3DWdg} which handles 3d graphics recognizes the following options:
\begin{verbatim}
>> To define the 3D box limits : 
  xyzlimits=xmin,xmax,ymin,ymax,zmin,zmax
  limit3dbox=xmin,xmax,ymin,ymax,zmin,zmax
>> Autoscaling flags (rescaling of X/Y or X/Y/Z axes)
  autoscale3dbox  / noautoscale3dbox
  autoscalexy3dbox / noautoscalexy3dbox
  autoscalez3dbox / noautoscalez3dbox
>> To change the background color (default=white)
  wbgcol=colname
  
\end{verbatim}
%%%
\subsubsection{PIImage}
The {\bf PIImage} which handles image display recognizes the following options: 
\begin{verbatim}
>> Define display zoomfactor 
  zoomxFact     (zoomx2 zoomx3 ... zoomx9 ...)
  zoom/Fact  (zoom/2 zoom/3 ... )
>> LUT (look-up table) definition (pixel value to index conversion)
  lut=type,min,max   (type=lin/log/exp/sqrt/square)
  lut_type=rgb is reserved for true color image display
>> AutoLut selector : define the method for automatic determination 
     of LUT limits (min/max) 
  autolut=alt[,ns[,minp,maxp]] (minp<=pixels<=maxp)
   - autolut=minmax[,Frac] 0<=Frac<=1
   - autolut=meansig[,ns] --> mean +/- ns*sigma  
   - autolut=hispeak[,ns] --> around the peak of pixel values histogram
   - autolut=histail[,ns] --> the tail of pixel values histogram
   - autolut=hisrng[,Frac[,minp,maxp]] 0<=Frac<=1 --> the central pixel values
>> To display the color map with the LUT scale in the main image widget
   showcmap , showcmap=showcmap=no ,  showcmap=top 
   showcmap=no/top/right/bottom/left/horiz/vert 
>> Define color table and reversing color indexing flag
  ColTableName     revcmap
  ==> Standard tables with 32 distinct colors:
          grey32  invgrey32 colrj32  colbr32  colrv32  
  ==> Standard tables with 128 distinct colors:
          grey128  invgrey128  colrj128  colbr128
  ==> Shades of red/green/blue ...
           red32cm  green32cm  blue32cm  yellow32cm 
           orange32cm cyan32cm violet32cm 
  ==> Some of MIDAS color tables :
          midas_pastel  midas_heat  midas_rainbow3
          midas_bluered  midas_bluewhite  midas_stairs8
          midas_stairs9 midas_staircase midas_color
          midas_manycol  midas_idl14  midas_idl15
  ==> Other tables 
          multicol16 multicol64 
  ==> Other tables RGB component color map (lut_type=RGB)
          rgb216cm rgb512cm rgb4096cm rgb32768cm
>> Viewed center position (image/array coordinates)
  imagecenter=xc,yc  
>> Array axes to window axes mapping flags
  invx  invy  exchxy 
>> To change the background color (default=black)
  wbgcol=colname
  
\end{verbatim}
%%% 
\subsubsection{PIGraphicAtt}
The {\bf PIGraphicAtt} Generic graphic attributes (color/font/line \ldots)
decoded by all drawers: 
\begin{verbatim}
>>> color=ColorName - fgcolor=ColorName - bgcolor=ColorName 
   ColorName: black white grey red blue green yellow 
              magenta cyan turquoise navyblue orange 
              siennared purple  limegreen gold violet 
              violetred blueviolet darkviolet skyblue 
              royalblue forestgreen orangered brown 
>>> line=DashType,LineWidth  
   DashType: solid, dash, dotted, dashdotted   Width: 1,2,...
>>> font=FontName,FontAtt,FontSize  
   FontName: courier, helvetica, times, symbol   
   FontAtt: roman, bold, italic, bolditalic  
   FontSize: 6,8,10,12... (pts) - integer 
>>> marker=MarkerType,MarkerSize (MarkerSize: integer 3,5,7... 
   MarkerType: dot, plus, cross, circle, fcircle, box, fbox 
               triangle, ftriangle, star, fstar 
>>> arrow=ArrowType,ArrowSize (ArrowSize: integer 3,5,7... 
   ArrowType: basic, triangle, ftriangle, 
              arrowshaped, farrowshaped
>>> ColorTables: defcmap  grey32  invgrey32  colrj32  colbr32 
                grey128  invgrey128  colrj128  colbr128 
                red32cm  green32cm  blue32cm  yellow32cm 
                orange32cm cyan32cm violet32cm 
                midas_pastel midas_heat midas_rainbow3 midas_bluered
                midas_bluewhite midas_redwhite 
                multicol16 multicol64
                rgb216cm rgb512cm rgb4096cm rgb32768cm
>   revcmap : This flag reverses ColorMap indexing 
------- Old style graphic att ---------- 
>> Lines:  defline normalline thinline thickline dashedline thindashedline 
           thickdashedline dottedline thindottedline thickdottedline 
>> Font Att: deffontatt normalfont boldfont italicfont bolditalicfont  
             smallfont smallboldfont smallitalicfont smallbolditalicfont 
             bigfont bigboldfont bigitalicfont bigbolditalicfont 
             hugefont  hugeboldfont hugeitalicfont hugebolditalicfont 
>> Font Names: deffont courierfont helveticafont timesfont symbolfont  
>> Marker: dotmarker<S>  plusmarker<S>  crossmarker<S> circlemarker <S> 
           fcirclemarker<S> boxmarker<S> fboxmarker<S> trianglemarker<S> 
           ftrianglemarker<S>  starmarker<S>  fstarmarker<S> 
   with <S> = 1 3 5 7 9 , Example fboxmarker5 , plusmarker9 ... 
   
\end{verbatim}
%%%%
\subsubsection{PIElDrawer}
The {\bf PIElDrawer} decodes axe drawing attributes: 
\begin{verbatim}
 >> Axe and grid configuration flags: 
   axesnone  stdaxes defaxes 
   boxaxes boxaxesgrid fineaxes fineaxesgrid 
   centeredaxes finecenteredaxes centeredaxesgrid 
   finecenteredaxesgrid  grid/nogrid 
 >> Centered axes position: axescenter=xc,yc 
 >> Axe ticks/labels (h=horizontal/x, v=vertical/y): 
   labels/nolabels  hlabels/nohlabels vlabels/novlabels 
   ticks/noticks minorticks/nominorticks 
   extticks/intticks/extintticks nbticks=X_NbTicks,Y_NbTicks 
   tickslen=MajorTickLenFrac,MinorTickLenFraC 
>> Axe label font size: 
    autofontsize=FontSizeFrac fixedfontsize 
 >> Up/Down title: title tit notitle notit 
    ... Color/Font/line attributes : 
    
\end{verbatim}
The {\bf PINTuple} handles most 2D plotting : \\
\begin{verbatim}
  sta,stat,stats:            activate   statistic display
  nsta,nstat,nostat,nostats: deactivate statistic display
  statposoff=OffsetX,OffsetY : Position offset for Stats drawing 
      as a fraction of total size 
  connectpoints: The points are connected by a line 
  noconnectpoints (this is the default) 
  colorscale/nocolorscale (Use color scale for weight) 
  sizescale/sizescale=nbins/nosizescale (Use marker size for weight) 
   (and usual color/line/marker/... attribute decoding)
   
\end{verbatim}
%%%
\subsubsection{PIHisto, PIHisto2D}
{\bf PIHisto} and {\bf PIHisto2D} handle1D and 2D histograms display. \\
The following options are recognised by {\bf PIHisto}: \\
\begin{verbatim}
 ---- PIHisto options help info : 
  sta,stat,stats:            activate   statistic display
  nsta,nstat,nostat,nostats: deactivate statistic display
  err / noerr,nerr : draw, do not draw error bars
  autoerr : draw error bars if Marker drawing requested OR Profile histo
  fill / nofill,nfill : fill, do not fill bars with selected color
  statposoff=OffsetX,OffsetY : Position offset for Stats drawing 
       as a fraction of total size 
  ---- HistoWrapper options : 
 hbincont: select bin content as Y value for display (default) 
 hbinerr: select bin error as Y value for display 
 hbinent: select bin entries as Y value for display 
 hscale=value : multiplicative factor for Y value 
 hoffset=value : additive coefficient for Y value 
 hs1: set hscale=1 hoffset=0  (default) 
 hscale=value  : multiplicative factor (in Y) 

\end{verbatim}
The following options are recognised by {\bf PIHisto2D}: \\
\begin{verbatim}
- sta,stat,stats:            activate   statistic display
  nsta,nstat,nostat,nostats: deactivate statistic display
- h2disp=typ[,fracpts]: choose display type
    typ=var: variable size boxes
    typ=hbk: "a la hbook2"
    typ=img: image like (use "h2col" for color map)
    typ=pts: point clouds (fracpts=max possible fraction
             of used pixels per bin [0,1])
- h2scale=lin/log[,logscale]: choose linear or logarithmic scale
- h2dyn=[hmin][,hmax]: choose histogramme range for display
- use general key to define color table (ex: grey32,midas_heat,...)
            (see general graphicatt description)
- use key "revcmap" to reverse color table
- h2frac=[fmin][,fmax]: choose sub-range display [0,1]
  ---- HistoWrapper options : (see HistoWrapper above)

\end{verbatim}
%%%%
\subsubsection{PINTuple3D , PISurfaceDrawer}
The {\bf PINTuple3D} and {\bf PISurfaceDrawer} 
handles basic 3D plotting and can decode the common 3D box options:
\begin{verbatim}
  X/Y,Z axis rescaling option (-> cubic 3D box)  
  rescale=autoscale/ norescale=noautoscale : X/Y and Z axis 
  rescalexy=autoscalexy / norescalexy=noautoscalexy : X/Y  axis 
  rescalexy=autoscalexy / norescalexy=noautoscalexy : Z axis 
\end{verbatim}
The {\bf PINTuple3D} decodes in addition the following options:
\begin{verbatim}
 connectpoints: The points are connected by a line 
  noconnectpoints (this is the default) 
  colorscale/nocolorscale (Use color scale for weight) 
  sizescale/sizescale=nbins/nosizescale (Use marker size for weight) 
  
\end{verbatim}  

\subsubsection{PIContourDrawer}
The {\bf PIContourDrawer} decodes the following options :  \\
\begin{verbatim}
 autolevels : automatic selection of levels and number of contours 
 ncont=nLevel (or nc=NLevel) : sets the number of contour
 lev=v1,v2,v3... (or niv=v1,v2,v3...) set the number and levels of contours
 lstep=nLev,start,step : define incremental levels 
 labon/laboff : display of contour level values on/off 
 linear/bspline/cubicspl=3spl : select contour kind 
 
\end{verbatim}  

\subsubsection{PIBarGraph , PITextDrawer}
{\bf PIBarGraph} is used by the {\tt bargraph} \myppageref{bargraph}
command and has the following graphic options:
\begin{verbatim}
 ---- PIBarGraph options help info : 
  fill/nofill: set bar fill option 
  horizontalbars/verticalbars: set bar orientation 
  packfrac=value : set bar packing fraction (0..1) 
  barvaluelabel/nobarvaluelabel: Use/Don't use bar value as labels 
 --- + Usual colr/line/font  attribute decoding ... 
 \end{verbatim}
The command {\tt textdrawer} \myppageref{textdrawer} uses the 
{\bf PITextDrawer} which has the following options : \\
\hspace*{10mm} {\tt frame,noframe: enable/disable frame drawing}


%%%%%%%%%%%%%%% Section 4 :   I/O
\newpage
\section{Data formats and input-output (I/O)}
The data file formats recognized by piapp are the ones supported by the 
SOPHYA library or its extension.
\begin{itemize}
\item[\bul] ASCII files - Data can be imported from ascii (text) files as
datatables or arrays. These objects can also be exported as text files.
\item[\bul] FITS files - FITS is a popular format used in particular in astronomy. 
\href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}
Data is usually read from FITS files as vectors, images, cubes or tables. 
A subset of SOPHYA objects can be imported or exported in FITS format. 
\item[\bul] PPF (Portable Persistence file Format) is the native SOPHYA 
data format.
\item[\bul] PostScript - All graphic output produced by piapp can be exported
as postscript (.ps) or encapsulated postscript (.eps) files.
\end{itemize}

\subsection{Text files}
Text (or ascii) files can be read into array or datatable objects by spiapp. 

{\bf Arrays :} \\
Arrays can be written to to files in text/ascii format using the {\tt arrtoascii}
  \myppageref{arrtoascii} command. Double precision matrices and vectors 
  can be read from text files using the commands 
  {\tt mtxfrascii}  \myppageref{mtxfrascii} and
    {\tt vecfrascii}  \myppageref{vecfrascii} . \\
The menu-bar command  \menubar{File/Open-ASCII} reads in a text 
file as a matrix. 
\begin{verbatim}
#  Create and initialize a matrix
newmtx arr 250 150 x+3*y 
#  Save the file in the text file arr.txt
arrtoascii arr arr.txt
#  Read the previously created file and fill a matrix
mtxfrascii mxa arr.txt
#  Print and display the matrix 
print mxa
disp mxa zoomx2
\end{verbatim}
It is possible to specify the field separator in the input file, as well as the marker for the comment 
lines. 

{\bf DataTable :} \\
Text files can also be read as a 2-D table (NTuple or DataTable). The table should be 
created using the  {\tt newnt} \myppageref{newnt}  or 
{\tt newdt} \myppageref{newdt} command.  
The command {\tt ntfrascii} \myppageref{ntfrascii} can then be used to append
data from the file to the datatable.

\subsection{PPF}
%%%
PPF (Portable Persistence file Format) is the the native persistence 
format of SOPHYA and thus is fully handled by spiapp.   PPF files can 
be opened through the menu-bar  \menubar{File/Open-PPF}, or through 
the {\tt openppf} \myppageref{openppf}.

If the PPF file contains NameTags, only the objects marked with nametags are read and given 
the corresponding names. Otherwise, all objects are red sequentially, with their names 
formed by the filename followed by a sequence number. It is also possible to force the sequential 
reading specifying the {\tt -s} flag for openppf.

The objects managed in spiapp by the {\bf NamedObjMgr} can be saved to PPF files, with their
names as NameTags. The commands {\tt saveppf} \myppageref{saveppf} or 
 {\tt saveall} \myppageref{saveall} can be used to this end.

\begin{verbatim}
# Create two vectors and two matrices
newvec va1 150 sin(sqrt(x)) 
newvec vb2 150 sin(sqrt(x))*sqrt(x*0.1)
newmtx mxa 250 150 x+2.*y
newmtx mxb 250 150 sin(sqrt(x))*cos(sqrt(y))
# List of the objects in memory 
listobjs
#  Save the two vectors in the file vecab.ppf
saveppf v* vecab.ppf
#  Save the two matrices in the file mxab.ppf
saveppf m* mxab.ppf
\end{verbatim}

\subsection{FITS}
FITS files may contain three types of data structures 
\begin{enumerate}
\item Image or array data structure : {\tt IMAGE\_HDU}
\item Binary table : {\tt BINARY\_TBL}
\item ascii table : {\tt ASCII\_TBL}
\end{enumerate}
The {\bf FitsIOServer} module contain FitsHandler classes which 
can map many SOPHYA classes on FITS data structures.
Generic {\tt IMAGE\_HDU} correspond to the SOPHYA \tcls{TArray}
class, while {\tt BINARY\_TBL} or {\tt ASCII\_TBL} is mapped 
to NTuple or DataTable.

FITS format files can be read through the menu command \menubar{File/Open-Fits},
or using {\tt readfits/openfits} \myppageref{readfits} command. The command 
{\tt rdfitsarr} \myppageref{rdfitsarr} offer additional possibilities for reading 
arrays from FITS IMAGE\_HDU, for example array type conversion.  
Objects can be exported to FITS using the {\tt writefits/savefits} 
\myppageref{writefits} command.

\begin{verbatim}
# Open the PPF file created by the commands above
openppf vecab.ppf
# Export the two vector objects to file vecab.fits
# Note that the '!' forces c-fitsio to overwrite the file, if it exists
writefits v?? !vecab.fits
\end{verbatim}

There are two commands useful 
when analyzing large catalogs (BINARY\_TBL) in FITS format, which avoid reading the whole
table in memory. {\tt swfitstable}\myppageref{swfitstable} reads a specified HDU 
as a {\bf SwFitsDataTable} object which uses the FITS file as swap space.
The {\tt fitsadapt}\myppageref{fitsadapt} can also be used for similar purposes.

The following commands shows how to open a FITS file containing a synchrotron map
of our galaxy. This file contains sky emission at 408 MHz, 
as brightness temperature, represented as a SOPHYA spherical map 
(SphereHEALPix$<$r\_4$>$) in \href{http://healpix.jpl.nasa.gov/}{\bf HEALPix} 
format \footnote{HEALPix home page: \hspace{5mm} http://healpix.jpl.nasa.gov/}.
It has been made, by rebinning, from the Haslam 408 MHz 
all sky survey map, available from the NASA CMB data repository 
\href{http://lambda.gsfc.nasa.gov/}{\bf LAMBDA}
\footnote{LAMBDA web site: \hspace{5mm} http://lambda.gsfc.nasa.gov/}.
\label{syncmap}
\begin{verbatim}
#  Open the fits file : the map is in HEALPix format
readfits syncmap.fits
#  Create a window with the appropriate size
newwin 1 1 800 400
# Display the map, specifying the colormap
disp syncmap 'lut=lin,2,50 midas_bluered'
\end{verbatim}
\begin{figure}[h]
\begin{center}
\includegraphics[width=15cm]{syncmap.eps}
\caption{Synchron map of our Galaxy, displayed in Molleweide projection.
The underlying SOPHYA object is a \tcls{SphereHEALPix} }
\end{center}
\end{figure}

\subsection{Graphic export in postscript}
%%
Postscript a page description language widely used for printing and 
graphic output, developed by Adobe systems. Refer to 
\href{http://www.adobe.com/products/postscript/}{Adobe/PostScript3} 
for more detail.

Piapp graphic output can be exported in postscript (level 2) or
encapsulated postscript format, preserving the full precision 
of vector graphics. 
Postscript (.ps) files my contain several pages, each vue or window
corresponding to one page and are suitable for direct printing. 
An Encapsulated Postscript (.eps) file contains a single page,
corresponding to a window and is suitable for inclusion in 
other document. 

Postscript file can easily be converted to other formats, 
PDF or image formats (jpeg \ldots) using converters like
{\bf ps2pdf} or {\bf imagemagick}.  

The menu items under \menubar{PostScript} can be used to export 
graphics in postscript. The default file name is {\tt pia.ps}
or {\tt pia1.eps} {\tt pia2.eps} \ldots
The following commands can also be used to create postscriot file
from the display in the current graphic window:
\begin{itemize}
\item {\tt w2ps} \myppageref{w2ps} to add the current graphic 
output as a new page to the output postscript file.
The current output postscript file (default = w2ps.ps) 
should be closed before being used. Exiting piapp closes automatically 
all postscript files.
\item {\tt psclosefile} \myppageref{psclosefile} to close the current
output postscript file.
\item {\tt pssetfilename} \myppageref{pssetfilename} To define 
the output postscript file name for the subsequent {\tt w2ps} commands.
\item {\tt w2eps} \myppageref{w2eps} to export the current 
graphic display, in Encapsulated Postscript format to the specified file. 
\begin{verbatim}
# Open the PPF file created by the commands above
openppf vecab.ppf
# Display one of the vectors
setaxesatt 'font=helvetica,bold,18 fixedfontsize'
disp va1 'blue marker=box,5' 
#  Export the graphic to file va1.eps
w2eps va1.eps 
#  The created file can be viewed using gv 
\end{verbatim}
\end{itemize}

\subsection{RGB pixel files} 
Graphics displayed in piapp windows and widgets (in PIImage, PIScDrawWdg, PIDraw3DWdg) 
can be exported in a PI-specific image format coding the RGB (Red/Green/Blue) intensities
of each pixel. The commands {\tt wdg2rgb} \myppageref{ wdg2rgb } and 
 {\tt wdg2rgb} \myppageref{ win2rgb } can be used to export graphics to PI-RGB 
files. The content of PI-RGB  files can be read back and displayed using the 
command {\tt pirgbdisp} \myppageref{pirgbdisp}.
It is also possible to compute  RGB images and save in this format, for example
for creating a false color composite image, from a set of intensity coded images 
in three wavebands. Check the class {\bf PIPixRGBArray} in the file (PI/pipixutils.h) for
more information on PI-RGB format.

The {\bf PIPhoto} add-on package  can be used to convert PI-RGB images to/from
standard image formats (gif, jpeg \ldots). The {\bf PIPhoto} module uses the 
ImageMagick libraries. It contains also a piapp loadable module which extends 
the piapp possibilities through a set of commands for reading, writing and 
manipulating standard image formats in piapp.




%%%%%%%%%%%%%%% Section 5 :   analyse a la paw
\newpage
\section{Tables and Expression Plotting}
\label{tableplot}
A powerful data analysis technic available in piapp is 
2D, 3D plot, and histogramming applied to arbitrary analytical 
expression of table columns.
This analysis technic has been introduced by the popular 
CERN \href{http://paw.web.cern.ch/paw/}{\bf PAW} 
({\bf P}hysics {\bf A}nalysis {\bf Workstation}) 
\footnote{PAW home page : http://paw.web.cern.ch/paw/ } program
and the underlying HBOOK fortran library.
Compared to PAW, piapp extends in many respects this capability,
piapp offers in particular the possibility to manipulate many 
objects as if they where a DataTable, or NTuple. 
There are also additional 2D and 3D representations e.g. 
{\tt plot2de} \myppageref{plot2de},  
{\tt plot2dw} \myppageref{plot2dw},  
{\tt plot2dc} \myppageref{plot2dc} and
{\tt plot3dw} \myppageref{plot3dw}.

\subsection{How does it work ?}

The Expression.Plotting commands in piapp operate on objects through the 
{\bf NTupleInterface} class methods. Some classes like NTuple or BaseDataTable
inherit from NTupleInterface, while for the other classes, the corresponding 
NObjMgrAdapter class exposes an object conforming to NTupleInterface through the 
method : \\
\hspace*{5mm} {\tt  NTupleInterface* NObjMgrAdapter::GetNTupleInterface()} \\
A C file (PIATmp\_xxx/expf\_pia\_dl.c) is created by piapp containing the 
specified expressions, which should conform to the C-language syntax.
In addition to the functions in {\tt math.h} (sin, cos, log \ldots), 
the following functions are defined by piapp and can be used:
\begin{itemize}
\item Flat random number generators: {\tt drand01() , drandpm1() }
\item Gaussian random number generator: {\tt GauRand() }
\item Angle conversion: {\tt deg2rad(double d), rad2deg(double r) }
\item $(\theta,\varphi)$ to Molleweide X,Y projection: \\
\hspace*{5mm}{\tt double tetphi2mollX(double theta, double phi)} \\
\hspace*{5mm}{\tt double tetphi2mollY(double theta)} 
\item Longitude(0..360) deg., Latitude(-90..90) deg. conversion to Molleweide X,Y: \\
\hspace*{5mm}{\tt double longlat2mollX(double longit, double lat) } \\
\hspace*{5mm}{\tt double longlat2mollY(double lat) }
\end{itemize}

The processing steps for an Expression.Plotting in piapp :
\begin{enumerate}
\item Creation of the C-file. 
\item On the fly compilation of the generated file.
\item The resulting shared-object is loaded and linked with the application
\item Loop over the NTupleInterface object rows. The created function is called
with the data from each row
\item The return values are used to fill an histogram, or a matrix/vector or
another NTuple or to produce a 2D or 3D graphic display. 
\end{enumerate}

Although rather complex, the efficiency gain during processing data easily compensates
for the overhead of the compilation step.
  
\subsection{Column/variable names}

When working with real 2-D tables (NTuple, DataTable \ldots), the column names
are the name of the variables which can be used in the C-expressions.
There is an additional variable, called {\tt \_nl}, automatically
provided by piapp, corresponding the table row number, starting from 0.

For the other objects in piapp, the variable names are listed below:
\begin{itemize}
\item[\rond] For 2D table objects {\bf (NTuple,DataTable,\ldots)}:  ColumnNames,\_nl
\item[\rond] For FITS files opened through {\tt fitsadapt} command: FITSColumnNames,\_nl
\item[\rond] For {\bf Histo1D/HProf} objects : i,x,val,err,nb,\_nl
\item[\rond] For {\bf Histo2D} objects : i,j,x,y,val,err,\_nl
\item[\rond] For {\bf HistoErr} objects : i,x,val,err2,nb,\_nl
\item[\rond] For {\bf Histo2DErr} objects : i,j,x,y,val,err2,nb,\_nl
\item[\rond] For {\bf \tcls{TVector}, \tcls{TMatrix} , \tcls{Image} } objects : \\
 \hspace*{10mm}  n,r,c,val,real,imag,mod,phas,\_nl
\item[\rond] For {\bf \tcls{TArray}} objects : n,x,y,z,t,u,val,real,imag,mod,phas,\_nl
\item[\rond] For {\bf GeneralFitData} objects : x0,ex0 x1,ex1 ...  xn,exn  y,ey ,ok,\_nl
\item[\rond] For {\bf \tcls{SphereHEALPix} , \tcls{SphereThetaPhi} , \tcls{SphereECP}
\tcls{LocalMap} } objects : \hspace{10mm} i,k,val,real,imag,mod,phas,teta,phi,\_nl
\end{itemize}  

%%%%%
\subsection{Examples}
The following examples illustrates the use of some Expression Plotting commands
(see the command groups {\bf Expr. Plotting} \myppageref{ExprZZPlotting} and
 {\bf pawCmd} \myppageref{pawCmd}).
The {\bf pawCmd} defines a number of operations with command name and syntax 
similar to the CERN PAW program.
The graphic output from the examples below are shown in the figures 
\ref{exhis2dpl} and \ref{uzcpos}.
\begin{enumerate}
\item 2D plot with error bars \\[1mm]
\begin{verbatim}
# Set the axes attibute (the font used for axes ...)
setaxesatt 'font=helvetica,bold,16 minorticks fixedfontsize'
#  Open the file demo.ppf (in DemoPIApp)
openppf demo.ppf 
print nt21
print nt22 
# 2D plot directly from the NTuple columns (nt2d)
# nt2d DO NOT use a compiled c file
nt2d nt21 x y - - - - 'font=helvetica,bold,16'
# Overlay a plot with scaled error bars from nt22
plot2de nt22 x y ex*0.3 ey*0.5 1 \
  'same marker=box,7 red font=helvetica,bold,16 ' 
\end{verbatim}
\vspace*{4mm}
\item Compute the histogram of pixel values for a \tcls{SphreHEALPix}.
The data come from the synchrotron map (syncmap.fits), described page \pageref{syncmap}.
\begin{verbatim}
# Open the synchrotron map file (HEALPix format spherical map)
# The file can be found in directory DemoData/
readfits syncmap.fits
newwin 1 1 800 400
disp syncmap 'lut=lin,2,50 midas_bluered'
newwin 1 2
# Compute and display the pixel value histogram (brightness temperature)
n/plot syncmap.val val<200 ! ! 'font=helvetica,bold,16 notit'
settitle 'Sky brightness @ 408 MHz' ' ' 'font=helvetica,bold,16'
# display the pixel value histogram in the galactic plane
n/plot syncmap.val val<200&&(fabs(teta-M_PI/2)<0.025) ! ! 'red notit'
settitle '408 MHz - Galactic plane' ' ' 'font=helvetica,bold,16 red'
\end{verbatim}
\vspace*{4mm}
\item Sources (galaxies) distribution over the sky. The data used below (uzc.ppf)
has been extracted from the {\bf U}pdated {\bf Z}wicky {\bf C}atalog of Galaxies,
available from the Harvard-Smithsonian Center For Astrophysics 
\href{http://tdc-www.harvard.edu/uzc/}{CfA/UZC web site}.
\footnote{CfA web site: \hspace{5mm} http://tdc-www.harvard.edu/uzc/} \\[1mm]
%%% 
\begin{verbatim}
#  Keep the synchrotron map
#  Open the Updated Zwicky Catalog of galaxies (in DemoData)
openppf uzc.ppf
zone 1 2
# Draw a longitude-latitude grid in Molleweide projection
mollgrid 5 7 'axesnone black font=helvetica,roman,12 notit'
# Overlay the sources distribution from UZC, for bright objects (mag<14)
plot2d uzc longlat2mollX(ra*15,dec) longlat2mollY(dec) mag<14 \
  'same red marker=circle,5'
# Change the plot title
settitle 'RA-Dec in degrees UZC (Updated Zwicky Catalog)' ' ' \
  'font=helvetica,bold,16 red'
# Display the synchrotron map
disp syncmap 'lut=lin,2,40 grey128'
# Add the source distribution in Galactic coordinates
plot2d uzc longlat2mollX(glong,glat) longlat2mollY(glat) mag<14  \
  'same nsta red marker=circle,5'
\end{verbatim}
%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%
\item Analysis of elevation (altitude) data for france. We use the francetopo.ppf 
data set described page \pageref{francetopo}.
\begin{verbatim}
# open and display the topographic data for france
openppf francetopo.ppf (in DemoData/ directory)
print francetoto
#--- TMatrix<s>(NRows=1332, NCols=1548) ND=2 SizeX*Y*...= 1548x1332 --- 
disp francetopo 'zoom/2 imagecenter=750,700 lut=lin,-700,800 colbr128'
#  Compute the altitude distribution
newh1d altf 0. 4000 100
projh1d altf francetopo val val>0.1 
# Display the histogram overlayed on the topographic map
disp altf 'white line=solid,2 font=helvetica,bold,14 inset=0.1,0.6,0.45,0.9'
# Compute altitude distribution for the massif central (Auvergne)
newh1d altmc 0. 2000 100
# We select the region as a circle of radius 200, centered on x=c=970,y=r=920
set regcut (sqrt((c-970)*(c-970)+(r-920)*(r-920))<200)
projh1d altmc francetopo val (val>0.1)&&$regcut
# Create a new window and display the two histograms
newwin 1 2 
setaxesatt 'font=helvetica,bold,16 fixedfontsize'
disp altf 'notit'
settitle 'Elevation (altitude) distribution over France' ' ' \
  'font=helvetica,bold,16'
disp altmc 'notit'
settitle 'Elevation (altitude) distribution over MassifCentral' ' ' \
  'font=helvetica,bold,16'
\end{verbatim}
\end{enumerate}

\begin{figure}[hp]
\includegraphics[width=15cm]{exhis2dpl.eps}
\caption{
top: 2d plot example with error bars \hspace{5mm}
bottom: Histogram of pixel values from the synchrotron map 
of our galaxy}
\label{exhis2dpl}
\end{figure}

\begin{figure}[p]
\includegraphics[width=15cm]{uzcpos.eps}
\caption{UZC: Updated Zwicky Catalog. \hspace{5mm}
top: The galaxy position distribution in equatorial 
$(\alpha, \delta)$ coordinates. \hspace{5mm}
bottom: Position distribution in Galactic coordinates, superimposed on 
the synchrotron map.}
\label{uzcpos}
\end{figure}

%%%%%%%%%%%%%%% Section 6 :  command interpreter 
\newpage
\section{Command interpreter}
piapp uses the class {\bf PIACmd} which extends slightly the 
SOPHYA class {\bf Commander} as the command interpreter.
{\bf Commander} is a  c-shell inspired, string oriented command 
interpreter.  Although it has many limitations compared to 
c-shell, or Tcl , it provides some interesting possibilities:
\begin{itemize}
\item Extended arithmetic operations (c-like and RPN)
\item Simple and vector variables
\item Script definition 
\item Command execution in separate threads
\item Dynamic Load 
\end{itemize}

We describe below  the {\bf Commander} possibilities, 
as well as the few {\bf PIACmd} extensions. 

\subsection{Variables}
The SOPHYA::Commander interpreter manages non typed set of variables.
Environment variables are also accessible through 
the usual {\tt \$varenvname}, unless shadowed by a Commander 
variable. All Commander variables are vector of strings, and are 
extended as necessary.  {\tt \$varname} is the string formed by all 
the vector elements. Except when performing arithmetic operations,
variables are treated  as strings. 
\par 
An application level set of variables is also managed 
by Commander, through redefinition of \\
{\tt Commander::GetVarApp() / GetVarApp() \ldots } methods.  \\
The {\bf PIACmd} in piapp redefines the {\tt GetVarApp() }
in order to provide an easy access to some of objects attributes or methods, 
managed by {\bf NamedObjMgr} (See below).

\subsubsection{Interpreter/Commander variables}
\begin{itemize}
\item[\rond] {\bf Definition and initialisation of variables }  
\begin{verbatim}
# Notice that the set command has no = sign 
Cmd> set sv StringValue
# Clearing/removing  of a variable : unset or clearvar 
Cmd> unset sv 

# Definition of a multi element variable (vector type)
# Notice that spaces before / after '(' and ')' are mandatory 
Cmd> set vecv ( mot1 mot2 mot3 mot4 mot5 )
# Arithmetic  expression : C language syntax - spaces 
# before/after '=' are mandatory  
Cmd> a = 2+3*sqrt(4)
# The '=' operator can also be used to initialize a variable with a string
Cmd> a = 'Bonjour Madame'
# A vector element can be specified in the left hand side
Cmd> vecv[2] = 'coucou'
# Or using an interpreter variable as index :
Cmd> i = 3
Cmd> vecv[i] = 'Ooohhh' 
\end{verbatim}

On the right hand side, the value of a variable should be accessed using 
the \$ character.  \\
A string can be parsed  into words using {\tt  var2words}
\begin{verbatim}
Cmd> var2words varname wordvarname [separateur]
\end{verbatim}

\item[\rond] {\bf Accessing variable contents } \\
The \$ character is used to access the content of a variable {\tt \$varname} .
Substitution rules : 
The {\tt \$xxx} is replaced by the value of  variable xxx. 
No substitution is performed for strings enclosed in simple quotes {\tt ' ... \$xxx '},
but substitution is done in strings enclosed in double quotes. 
Parenthesis or brackets can be used to specify the variable name, inside a string
without white space: {\tt \${vname} } ou {\tt \$(vname)}.
\begin{verbatim}
Cmd> x = 'Hello'
Cmd> echo $x
# Size of a vector variable : $#vname
Cmd> set vx ( 111 2222 3333 444444 )
Cmd> echo $#vx 
# Accessing vector elements 
Cmd> echo $vx[0] $vx[1] 
#  or using an interpreter variable as index :
Cmd> i = 2
Cmd> echo $vx[i] 
# Special syntax:  $[vname] is replaced by the content
# of a  variable whose name is $vname
Cmd> zzz = 'Commander'
Cmd> xxx = 'zzz'
Cmd> echo '---> $[xxx]= '  $[xxx]
---> $[xxx]= Commander
\end{verbatim}

\par
\end{itemize}

\subsubsection{Special variables}
\begin{itemize}
\item {\tt \$retval} ou {\tt \$retstr}  :  the string specified in the last {\bf return} statement 
\item {\tt \$status} : Return code from the last executed command.
Arguments of scripts (see below) or file executed through {\bf exec} command.
\item {\tt \$\# } : number of arguments, except \$0 
\item {\tt \$0}  : Script or file name  
\item {\tt \$1 \$2 \$3} ....  : Arguments  (for scripts and .pic files (exec))
\end{itemize}

\subsubsection{Environment variables} 
Environment variables can simply be accessed by {\tt \$varenvname}. 
However,  the environment variables have the lowest priority during substitution.
Interpreter's variables have the highest priority, followed 
by the application level variables.

\subsubsection{Objects/Application level variables} 
For some classes managed by NamedObjMgr, 
PIACmd provide acces to some of the attributes of the object by 
{\tt \${objname.attname} }. This mechanism has been implemented in particular for
TArrays, TMatrix/TVector, Histograms, NTuples and DataTables.
In addition, when brackets  are used ($\${vname}$), the priority level between interpreter variables
and application level variable is changed. If {\tt vname} exist at the application level,
{\tt \${vname} }  is replaced by its value, even if an interpreter variable with the 
same name has been defined. 
\begin{itemize}
\item[\rond] Accessing object attributes
\begin{verbatim}
# -------- Example with a Vector
piapp[1] newvec va 12 
piapp[2] echo $va
TVector<d>(12) (nr=12, nc=1) 
# ------- An undefined attribute, such as ? might be 
#           used to get list of valid attributes
piapp[3] echo ${va.?}
TMatrix.Att: rank size/nelts nrow/nrows ncol/ncols sum sumsq norm min ...
#  Compound names, in the form  name.att must be inclosed in
#    braces {name.att}
piapp[4] echo ${va.size}
12 
# -------- Example with an histogram
piapp[8] newh1d his 0. 20. 40
piapp[10] echo ${his.?}
Histo1D: nbin binw mean sigma over under nentries ndata 
                 xmin xmax vmin vmax imin imax 
piapp[11] echo ${his.nbin}
40 
\end{verbatim}

\item[\rond] Accessing object.Info() \\
For objects having an DVList Info() object (TArray/TVector/TMatrix , NTuple, DataTable, SwPPFDataTable, it is possible to access DVList members by the corresponding names : \\
\hspace*{10mm} {\tt \$\{objName.info.varName\} } 
\item[\rond] Getting DataTable rows \\
For NTuple and BaseDataTable objects (DataTable, SwPPFDataTable, SwFitsDataTable), it is 
possible to get a string representation of a given row, by specifying 
\$\{tableName.row\} followed by the row number (starting from 0) : \\
\hspace*{10mm} {\tt \$\{tableName.row.num\} } 
\end{itemize}

 

\subsection{Control structures}

\begin{itemize}
\item[\rond] Enumerated loop:
\begin{verbatim}
foreach f ( w1 w2 w3 ... )
  ...
  echo $f
end
\end{verbatim}

Note that spaces before/after  '(' et and  ')' are mandatory.
An alternative form uses a vector variable name :
\begin{verbatim}
foreach v vecname 
  ...
  echo $v
end
\end{verbatim}

\item[\rond] Integer type loop:
\begin{verbatim}
for i  startInt:endInt[:stepInt]
  ....
  echo $i 
end
\end{verbatim}

\item[\rond] Integer type loop:
\begin{verbatim}
for f  startFloat:endFloat[:stepFloat]
  ....
  echo $f
end
\end{verbatim}

\item[\rond] Loop over lines of a file 
\begin{verbatim}
forinfile line FileName
  ...
  echo $line
end
\end{verbatim}

\item[\rond] The {\tt break} instruction can be used to exit from a loop 

\item[\rond] {\bf if then else} Conditional execution:
\begin{verbatim}
if ( test ) then 
endif

if ( test ) then
 ....
else
 .... 
endif
\end{verbatim}
Note that spaces before/after  '(' et and  ')' are mandatory.

test is in the form {\tt a == b} OR {\tt a != b} OR {\tt a < b}  OR {\tt a > b} 
OR {\tt a <= b} OR {\tt a >= b}. Comparison operators should be delimited 
by spaces.
{\tt ==} et {\tt !=}  make a string comparison, while
{\tt < , > , <= , >=} compare the values obtained after string to double conversion.
\end{itemize}

\subsection{Script definition} 
A script is a sequence of commands. It is very similar to the execution of commands
from a file ({\bf exec filename}). Once a script has been defined, it can be called specifying
specifying the script name followed by its arguments.
\begin{verbatim}
#  Script definition :
defscript scriptname  [description ]
   ....
endscript 

#  Executing the script
Cmd> scriptname arg1 arg2 arg3 ....
\end{verbatim}

The {\tt return} instruction stops the execution and returns from a script, or from a command
file called through {\bf exec}. \\
The commands  {\bf listscript } and  {\bf clearscript scriptname} can be used 
to obtain the list of already defined script, or to clear a script definition.

\subsection{Other built-in commands}
\begin{itemize}
\item[\rond] Instruction {\bf echo } to write the line to cout/stdout
\item[\rond] Instruction {\bf echo2file} to write (append) the line to file ({\tt echo2file filename ....})
\item[\rond] Instruction {\bf sleep nsec} wait for {\tt nsec}  seconds
\item[\rond] Instructions {\bf timingon , timingoff , traceon , traceoff } \\
%
\item[\rond] {\bf exec filename [arg1 arg2 ... ] } to execute command from 
the file named {\tt filename}. {\tt .pic} is the default extension for the interpreter 
command files. 
\item[\rond]  {\bf help} and {help keyword/commandname }
\item[\rond]  {\bf listvars , listcommands } to print the list of defined variables and known
commands
\item[\rond]  An alias for a command by {\bf alias aliasname 'string ' }. Alias substitution
occurs for the first word in a command line. {\bf  listalias} prints the list of all 
defined aliases. 
\item[\rond] Execution control (piapp/PIACmd extension):
It is possible to stop the interpreter execution in a loop, a script or 
a command file by the {\bf stop} command, or using 
 {\tt <Cntrl C>} in the piapp console (PIConsole) \\
\end{itemize} 

\subsection {Command execution in separate threads} 
It is possible to create new threads to execute commands
( for non built-in interpreter commands). The syntax is similar 
to unix shell background tasks: an {\&} should be added at the end
of the command line.  A new thread is then created for the 
execution of the command, if declared as thread safe \\
(see {\tt CmdExecutor::IsThreadable() }. 
\par
Thread management commands:
\begin{itemize}
\item[\rond] {\bf thrlist }Print current list of threads, with the associated command
the thread identifier (integer ThrId) and its status.
\item[\rond] {\bf cleanthrlist } Removes all finished threads from the list.
An automatic cleanup is performed periodically.
\item[\rond] {\bf cancelthr ThId } / {\bf killthr ThId } Stops/kills the thread with 
the identifier ThId. Avoid using theses commands as the cleanup does 
not release some resources associated with 
the thread (memory, mutex \ldots). 
\end{itemize}

Executing commands in a separate thread is useful for CPU or data intensive 
commands. Most {\bf Expr.Plotting} 
(plot2d, plot2dw, plot2de, plot3d, ntloop, fillvec, fillmtx \ldots) 
and some of the {\bf pawCmd} (n/plot n/proj) are thread safe. However, due to the 
current mutex lock management for these Expr.Plotting/pawCmd commands, only one 
such command can run concurrently with other piapp threads. 
Some of the commands in the {\bf CxxExecutorCmd} (
c++exec, c++execfrf, c++create, c++createfrf, c++compile, c++link) are also thread safe.
The same remark concerning lock management applies to these commands, while 
CxxExecutorCmd commands can run in parallel with Expr.Plotting commands.


%%%%%%%%%%%%%%% Section 7 :  c++ execution
\newpage
\section{On the fly C++ execution}
\label{flycplusplus}
Piapp operates on the underlying SOPHYA class library objects.
Obviously, only a small fraction of functionalities in the libraries 
are directly available through the commands. On the fly C++ compilation
and execution in piapp provides an easy access to the whole class library. 

The {\bf NamedObjMgr} class handles most of the communication between different
component of the application, including user c++ code. 
The NamedObjMgr class implements a singleton scheme, where all instances of the
class operate on the same data.
Most operations, in particular directory and object management are thread-safe.
The most usefull NamedObjMgr methods in user code are:
\begin{itemize}
\item Adding an object using its pointer. The object should be created using new. \\
{\tt \small bool NamedObjMgr::AddObj(AnyDataObj* obj, string \& nom, bool crd=false) } 
\item Adding an object using its reference. The Object Adapter is used to Clone
the object. For classes like TArray or Spherical maps, implementing reference sharing,
the cloned object shares its data with the original object.
The Cloned object is then added to the list. \\
{\tt \small bool NamedObjMgr::AddObj(AnyDataObj\& obj, string \& nom, bool crd=false)}
\item Object display methods : \\
{\tt \small NamedObjMgr::DisplayObj(string \& nom, string dopt="")  \\
NamedObjMgr::DisplayImage(string \& nom, \ldots ) \\
NamedObjMgr::DisplayNT(string \& nom, \ldots )} \\
\ldots
\item Access to other parts of the piapp application : \\
{\tt \small PIStdImgApp* NamedObjMgr::GetImgApp() \\
PIACmd* PIStdImgApp::CmdInterpreter() }
\end{itemize}

\subsection{How does it work ?}
When one the {\bf CxxExecutorCmd} \myppageref{CxxExecutorCmd} commands
({\tt c++exec} or {\tt c++execfrf}) is invoked, piapp performs the 
following operations:
\begin{itemize}
\item Create a c++ file, and includes the usual libstc++ and SOPHYA header files
(file named PIATmp\_xxx/cxx\_spiapp.cc)
\item The user code is put in a c++ function: \\
{\small \tt  int usercxx( vector<string> \& args ) }
\item References to all objects present in the current working NamedObjMgr directory
(default=/home) are declared and initialized. Objects in the current directory can 
thus be easily accessed through variables bearing the corresponding object name
in piapp. 
\item The c++ source file is compiled and linked with SOPHYA libraries, 
and any additional library, specified through {\tt c++mylibs} \myppageref{cZZmylibs}).
The compilation and link steps are carried by the SOPHYA class {\b CxxCompilerLinker}.
\item The resulting shared object is loaded by piapp and the function
{\tt usercxx()} is called.
\end{itemize}

To facilitate communication with piapp/NamedObjMgr, two CPP macros are defined:
\begin{itemize}
\item[\rond] {\bf KeepObj(VarName) } where VarName is a user declared 
c++ variable, corresponding to an object inheriting from AnyDataObj.
When this macro is called, the corresponding object is cloned by the object
Adapter and added to the list managed by NamedObjMgr, 
with VarName as the object name. 
\item[\rond] {\bf DispObj(VarName, graphic\_att) } adds the object and
request its display.  
\end{itemize}

\subsection{Examples}

\begin{enumerate}
\item Computation using TimeStamp object. \\[1mm]
%%
$\longrightarrow$ File compdate.cc :
\begin{verbatim}
  TimeStamp now;     // Current date
  TimeStamp y2000(2000,1,1,12,0,0.);  // 1 jan 2000, 12:00 
  cout << " Y2000=" << y2000 << " --> Now: " << now << endl; 
  cout << " From Y2000 to Now= " << now.ToDays() - y2000.ToDays() << " days" << endl;
\end{verbatim}
$\longrightarrow$ piapp commands : \\
{\tt piapp> c++execfrf compdate.cc} \\
$\longrightarrow$ The result : \\
\begin{verbatim}
PIABaseExecutor: Call usercxx( ... )                                
 Y2000= 01/01/2000 12:00:0.0 UT  --> Now:  13/12/2007 14:20:50.0 UT 
 From Y2000 to Now= 2903.1 days                                 
\end{verbatim}
%%%%
\item Working with objects in piapp: \\[1mm]
\begin{verbatim}
#  We create three vectors
newvec va 256 sin(x/5.)
newvec vb 256 cos(x/18.)*exp(-x/150.)
newvec vc 256
#  We call c++exec to make an operation on these vectors
c++exec vc=va+3.*vb;
#  Display the resulting vector
disp vc
\end{verbatim}
%%%
\item Creating and adding new objects \\[1mm]
$\longrightarrow$ File myf\_fft.h :
\begin{verbatim}
inline double myf(double x)
{
return(3*sin(0.2*x)+4*cos(x)+5*sin(4*x+0.25) 
       +3.5*cos(9*x+0.45) + 0.05*x);
}
\end{verbatim}
$\longrightarrow$ File myf\_fft.h :
\begin{verbatim}
TVector<r_8> in(4048);
TVector<r_8> noise(4048);
TVector< complex<r_8> > out;
in = RegularSequence(0., 0.05);
noise = RandomSequence(RandomSequence::Gaussian, 0., 4.);
MathArray<r_8> ma;
ma.ApplyFunctionInPlace(in, myf);
in += noise;
FFTPackServer FFTServ;
cout << " Calling FFT " << endl;
FFTServ.FFTForward(in, out); 
DispObj(in, "");
DispObj(out, "red");
\end{verbatim}
$\longrightarrow$ piapp commands :
\begin{verbatim}
# Remove existing in/out objects
rm in out
# Divide then graphic window in two regions
zone 1 2
#  Compile and execute the c++ code
c++execfrf fft.icc myf_fft.h
listobjs
\end{verbatim}
\end{enumerate}

\subsection{Include files, libraries \ldots}
\begin{itemize}
\item[\rond] The different steps of c++exec or c++execfrf
can be performed by the following commands: {\tt c++create , c++createfrf, 
c++compile, c++link, call}. This is useful when the same code
has to be executed multiple times.
\item[\rond] An interactive editing / c++ execution window can be 
displayed through the menu-bar, \menubar{Tools/CxxExecutorWindow} 
\item[\rond] The {\tt c++import} \myppageref{cZZimport} 
activate inclusion of header files for additional SOPHYA modules, 
such as Samba SkyMap SkyT FitsIOServe \ldots.
\item[\rond] The inclusion of additional header files and libraries 
can be specified using the {\tt c++include} \myppageref{cZZinclude}
and  {\tt c++mylibs} \myppageref{cZZmylibs}.
\item[\rond] A dialog window for changing various c++ compile and link 
options can be displayed by through the menu-bar 
\menubar{Special/CxxExecOption} 
\end{itemize}


%%%%%%%%%%%%%%% Section 8 :  command reference
\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  by \menubar{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{Interactive control windows}
\subsection{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 \menubar{Tools/Show DrawerTools}.
A given drawer can be selected through the DrawerId selector (+ / - buttons)

\vspace*{5mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_drwtools.eps}
\caption{PIDrawerTools}
\label{figdrwtools}
\end{center}
\end{figure}
%%%%
\subsection{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 \menubar{Tools/Show AxesTools}.

\vspace*{5mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_axestools.eps}
\caption{PIAxesTools}
\label{figaxestools}
\end{center}
\end{figure}
%%%%%
\subsection{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
\menubar{Tools/Show ImageTools}.

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

\subsection{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*{5mm}
\begin{figure}[ht!]
\begin{center}
\includegraphics[width=8cm]{piapp_h2dtools.eps}
\caption{PIHisto2DTools}
\label{figh2dtools}
\end{center}
\end{figure}

\subsection{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}. 

\subsubsection{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.  


\subsubsection{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}