Changeset 3429 in Sophya for trunk/SophyaLib/Manual/piapp.tex

Timestamp:

Dec 10, 2007, 12:28:29 AM (18 years ago)

Author:

ansari

Message:

Chapitre V complete sur data formats,I/O + maj piahelp.tex genere par la derniere version de piapp (V=4.1) - Reza 10/12/2007

File:

• trunk/SophyaLib/Manual/piapp.tex (modified) (16 diffs)

trunk/SophyaLib/Manual/piapp.tex

@@ -22 +22 @@
            ]{hyperref}
 
-\setlength{\textwidth}{17cm}
-\setlength{\textheight}{21.5cm}
-\setlength{\topmargin}{0.5cm}
+\setlength{\textwidth}{15cm}
+\setlength{\textheight}{20.5cm}
+\setlength{\topmargin}{0.cm}
 \setlength{\oddsidemargin}{0.cm}
 \setlength{\evensidemargin}{0.cm}
@@ -72 +72 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large piapp Version: 4.1 (V\_Aug2007) } 
+{\bf \Large piapp Version: 4.1 (V\_Nov2007) } 
 \end{center}
 \titrebp{5}
@@ -111 +111 @@
 \end{itemize}
 %%%
-\vspace*{5mm}
-\par
+\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. 
@@ -135 +141 @@
  SophyaInitiator::SophyaInitiator() BaseTools Init
  PIOPersist::Initialize() Starting Sophya Persistence management service 
-SOPHYA Version  2.0 Revision 0 (V_Jul2006) -- Jul 18 2006 12:35:58 gcc 3.3 20030304 (Apple Computer, Inc. build 1495)
-
+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] [-termread] [-term] [-hidezswin] [-small] 
-              [-nosig] [-nosigfpe] [-nosigsegv] 
+ 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 
@@ -166 +173 @@
 {\bf Warning:} 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. 
+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
 
 \par 
@@ -175 +183 @@
 Section \ref{piappcmdref} contains a brief description of all piapp commands 
 and help items. Various interactive control windows are described in appendix.
-
-\vspace*{10mm}
-\begin{figure}[ht!]
-\begin{center}
-\includegraphics[width=16cm]{piapp_mainwin.eps}
-\caption{piapp main window}
-\label{figmainwin}
-\end{center}
-\end{figure}
 
 
@@ -392 +391 @@
 {\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. \\
+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 
@@ -398 +398 @@
 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 paragraph below. 
+\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. \\[1mm]
-The examples below illustrates the usage of some piapp graphic commands.
+ be used to export graphics. \\[2mm]
+The examples in the followwing pages illustrates the usage of some piapp graphic commands. 
+\newpage
 \begin{enumerate}
 \item Image display 
@@ -483 +487 @@
 for multi-layer 2D overlay vector graphics. \\[2mm]
 %%
-Main piapp/PI graphic viewers, windows and drawer objects:
-\begin{itemize}
-\item[\bul]  The {\bf PIScDrawWdg} handles a set of  of 2-D drawers, managing 
+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 
@@ -494 +500 @@
 activates the PIDrawer graphic attributes control window ({\bf PIDrawerTools}).
 %%%
-\item[\bul] The {\bf PIDraw3DWdg}  handles a set of of 3-D drawers, managing
+\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 
@@ -502 +509 @@
 Drawer 0 handles axes drawing and graphic elements.
 %%%
-\item[\bul] The display of 2-D arrays $A(i,j)$ as an image is managed by 
+\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 
@@ -515 +523 @@
 axes drawing and added graphic elements.
 %%%
-\item[\bul] {\bf Windows} 
+\subsubsection{Windows}
 The viewers described above are displayed in differnt kind of windows.
 The graphic option {\tt next,win,same,stack} can be used to control the way the
 type of windows used. Graphic windows can be divided into several zones
-(Command {\bf zone} \myppageref{zone}).
+(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 specified region
+of the last displayed widget \\
+\hspace*{5mm} {\tt same=fx1,fx2,fy1,fy2} \\
+where {\tt fx1,fx2,fy1,fy2} express X and Y limits, as fraction of 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.
+and their properties. \\
+ 
 %%% 
-\item[\bul] {\bf PIDrawer} Graphical representation of most objects in piapp is 
-handled through objects inheriting from the PIDrawer class. A base drawer 
+\subsubsection{Drawers}
+Graphical representation of most objects in piapp is 
+handled through objects inheriting from the {\bf PIDrawer class}. A base drawer 
 (PIElDrawer, number 0) associated to all three above viewers 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. 
-\end{itemize}
-
+%%%
 \par
 In addition, a number of control windows can be used to examine and 
@@ -764 +789 @@
   
 \end{verbatim}  
+\item[\bul]  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}  
+
 \item[\bul]  {\bf PIBarGraph} options : \\
 \begin{verbatim}
@@ -794 +830 @@
 \end{itemize}
 
-\subsection{text files}
-ASCII files (see {\tt ntfrascii} \myppageref{ntfrascii} and 
-{\tt newnt} \myppageref{newnt} command)
-\subsection{FITS and PPF}
-FITS format files, through \menubar{File/Open-Fits}. 
-(see also (see {\tt openfits} \myppageref{openfits}) command.
-PPF (Portable Persistence file Format) files through 
-menu \menubar{File/Open-PPF}. PPF files are the native persistence 
-format in Sophya 
+\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.
+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}
+
 \subsection{Graphic export in postscript}
-See the menu under \menubar{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. 
+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 {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}
 
 %%%%%%%%%%%%%%% Section 5 :   analyse a la paw
@@ -857 +1017 @@
 # 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  
+# 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
@@ -932 +1093 @@
 piapp[3] echo ${va.?}
 TMatrix.Att: rank size/nelts nrow/nrows ncol/ncols sum 
-#  Compound names, in the form  name.att must be inclosed in braces {name.att}
+#  Compound names, in the form  name.att must be inclosed in
+#    braces {name.att}
 piapp[4] echo ${va.size}
 12