%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% The E3D visualization tool
%
% Interaction with tcl packages
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{S:TCL}

\begin{subsection}{Presentation}
\label{S:TCL:1}

As we explained before, E3D includes a Tcl/Tk interpreter ({\tt
tk\_e3d}), that incorporates the E3D routines to Tcl/Tk. The
interpreter can be invoked to enter in a E3D shell, where the routines
can be run in an interactive way. A complete scriptable enviroment is
defined, for visualizing and analyzing 3D spectra. E.g., the E3D GUI
is a Tcl/Tk/E3D script ({\tt tk\_e3d.tcl}) that uses the new defined
routines. It also defines its own procedures, that can be invoked from
the command prompt on E3D (see previous section). 


We describe here the E3D routines incorporated to Tcl/Tk, there use,
and we explain briefly how to built new scripts using them.


\end{subsection}


\begin{subsection}{The E3D Tcl/TK commands}
\label{S:TCL:2}

The E3D tcl/tk interpreter creates a new tcl/tk object, the Euro3D
enviroment, that can be created by the routine {\tt create\_env}. This
routine requires two entries, the name of the enviroment and the
associated plotting device. E.g.,\\ {\tt create\_env euro3d /XS}\\ The
available devices depend on the PGPLOT installation, although, as
indicated in the Installation Section, E3D requires at least the
following ones:/XTERM,/XWIN,/XSERVER(/XS),/PS,/CPS,/GIF,/XTK.

The /XTK device cannot be directly invoked. It requires
to call the {\tt pgplot} routine, that creates a pgplot imagearea, and then 
call the {\tt device} command over it. E.g.,

{\tt
\#!/usr/local/src/v3d/user/bin/tk\_e3d\\
frame .frame -width 30 -height 30\\
pgplot .frame.pgplot -share true  -width 300 -height 300 -mincolors 256 -maxcolors 12000 -bg black -fg white\\
pack .frame.pgplot  -side left -fill both -expand true\\
pack .frame -side left -fill both -expand true\\
create\_env euro3d [.frame.pgplot device]\\
}

\begin{itemize}


\item {\tt ask\_e3d\_info }\\

It returns the basic parameters of the 3D spectra: the number of
  spectral pixel (maximum), the number of spaxels, the starting
  wavelength, the final wavelength, the wavelength increment per
  spectral pixel, the data minumum and maximun values, the first and
  the last spectra actually defined to be plotted (these last values
  are, by default 0 and 256).

\item {\tt bc },{\tt   USE: bc x }\\
 
  Deprecated
  
\item {\tt clean\_device dev\_id }\\
  
  Indicates not to overplot on the device with identification {\tt dev\_id} 
  the next time to plot on eat, but clear it before plotting.

\item {\tt clean\_server}\\

  Clean the SHM server.

\item  {\tt close\_device dev\_id }\\
  
  Close the device indicated by the index {\tt dev\_id}

\item {\tt correct\_dar }\\

  Correct the data for DAR, differential atmospheric refraction.
  A DAR correction should be defined.

\item  {\tt create\_map i1 i2 [dpix] [square=0/1] }\\

  Creates an interpolated map from the datacube slice defined between
  the spectral indeces {\tt i1} and {\tt i2}. The size of the
  interpolated pixel, {\tt dpix} and if the final map is an square or
  nor not {\tt 0/1} are optional values. See also {\tt set\_grid }.

\item {\tt create\_obj }

  Creates an {\tt object}, i.e., a memory buffer of the currently selected 
  list of spaxels. It returns the index of the saved {\tt object}

\item {\tt create\_slice i1 i2 slice\_index flag }

  Creates a datacube slice, between the spectral indeces {\tt i1} and
{\tt i2}, and tries to allocated it in the slice index {\tt
slice\_index}. The {\tt flag} indicates the kind of slice to be
created, ie, if {\tt flag$>$90} it save the slice from the currently in use, 
in other case, it creates a new slice. See also {\tt plot\_spaxels}.

\item {\tt create\_spec }

  Save the currently used average spectrum in a memory slot. It
  returns the slot index.

\item {\tt div\_spec i1 i2 }

  {\it Deprecated}. Divide the spectrum stored in the memory slot {\tt
  i1} by the spectrum in the memory slot {\tt i2}. It returns the
  memory slot of the result. See {\tt specarith }.

\item  {\tt draw\_raw min max device clean palette bright contra sign first\_spec last\_spec}

  Draw the spectra contained in the 3D file on its RSS format.  It
  requires as parameters the {\tt min} and {\tt max} values to plot,
  the {\it device} index to plot it, the {\tt palette}
  \footnote{currently available: grey, rainbow, heat, iraf, aips},
  brightness ({\tt bright}) and contrast {\tt contra}, an inversion
  parameter ({\tt sign}) and the first and last spectra to be shown
  ({\tt first\_spec} and {\tt last\_spec}).

\item {\tt empirical\_dar index delta\_index }

  Determines the empirical DAR correction, based on the comparison of
  the centroid position of the crosscorrelated databuce slices. 
  It requires the spectral {\tt index} of the slice used as reference, 
  and the spectral indeces width of the datacube slices, {\tt delta\_index}.

\item {\tt encircled\_spax X Y R n }

  It returns the spaxel ID of the {\tt n}th spaxel that lies in a
  distance smaller than {\tt R} arcsec from the position defined by
  the coordinates {\tt X} and {\tt Y}.

\item  {\tt export\_cube filename }

  Export the 3D data to datacube. It regularizes the data into a grid
  defined by {\tt set\_grid} (see below), creating, for each
  monochromatic slice, an interpolated 2D image.

\item  {\tt export\_rss fits\_file pt\_file}

  Export the 3D data to a RSS fits file ({\tt fits\_file}), and a ASCII
  position table ({\tt pt\_file}). E3D uses its own definition of how
  to stored a position table (see ???).

\item {\tt feed\_slice n\_feed list}

  Save the slice {\tt n\_feed} with the data included in the Tcl {\tt list}.

\item  {\tt fit\_single\_line min max device palette bright contra sign Ig D\_Ig fit Wo D\_Wo fit sigma D\_sigma fit Continuum D\_Continuum fit CHISQ\_LIM paint }

  Fits a single emission line to the currently in use average
  spectrum.  The model includes a gaussian plus a constant value for
  the nearby continuum.  It requires the same parameter than {\tt
  draw\_raw} for the resulting plot, plus the initial guess values for
  the fitting, including, for each parameter (Intensity peak, central
  wavelength, sigma of the gaussian function and the continuum value),
  the value(e.g., {\tt Ig}), the range of valid values (e.g.,{\tt
  D\_Ig}), and a flag indicating if to fit this value or not (0 for f



\item {\tt flux\_spax }
\item {\tt guess\_single\_line }
\item {\tt import\_cube }
\item {\tt import\_map }
\item {\tt import\_rss }
\item {\tt import\_spectra }
\item {\tt intensity }
\item {\tt load\_file }
\item {\tt load\_n\_spectra\_sel }
\item {\tt load\_obj }
\item {\tt load\_spec }
\item {\tt load\_spectra\_sel }
\item {\tt mark\_range }
\item {\tt message }
\item {\tt nearest\_spax }
\item {\tt open\_device }
\item {\tt peak\_dar }
\item {\tt plot\_flux\_spax }
\item {\tt plot\_line }
\item {\tt plot\_map }
\item {\tt plot\_scale }
\item {\tt plot\_spaxels }
\item {\tt plot\_spectra }
\item {\tt plot\_spectra\_mem }
\item {\tt pm\_dar }
\item {\tt read\_cont\_map }
\item {\tt read\_vel\_map }
\item {\tt recolor\_image }
\item {\tt release\_raw }
\item {\tt reverse\_obj }
\item {\tt save\_cut }
\item {\tt save\_file }
\item {\tt save\_map }
\item {\tt save\_obj\_file }
\item {\tt save\_PT }
\item {\tt save\_raw }
\item {\tt save\_slice }
\item {\tt save\_spec }
\item {\tt save\_spec\_table }
\item {\tt save\_spectra\_sel }
\item {\tt set\_first\_last }
\item {\tt set\_flag\_spec }
\item {\tt set\_grid }
\item {\tt set\_type\_spec\_rep }
\item {\tt simple\_dar }
\item {\tt skysub }
\item {\tt slicearith }
\item {\tt specarith }
\item {\tt start\_server   }
\item {\tt stats\_spax }
\item {\tt stop\_server   }
\item {\tt sub\_spec }
\item {\tt tcl\_pgptxt }
\item {\tt theoretical\_dar }
\item {\tt zoom\_raw }
\item {\tt
 }*\item {\tt*********************** }




 
 {\tt     div\_spec n\_spec1 n\_spec2,  }
 {\tt     draw\_raw min max device clean palette bright contra sign first\_spec last\_spec,  }
 {\tt     empirical\_dar INDEX\_OF\_COMPARISON\_WAVELENGTH DELTA\_INDEX,  }
 




 {\tt     flux\_spax SPAXEL\_INDEX,  }
 {\tt     guess\_single\_line,  }
 {\tt     import\_cube cube\_fitsfile,      }
 {\tt     import\_map cube\_fitsfile,      }
 {\tt     import\_rss rss\_fitsfile positiontable,      }
 {\tt     import\_spectra spectra\_fitsfile,      }
 {\tt     load\_file filename,      }
 {\tt     load\_obj n\_obj,  }
 {\tt     load\_sepectra\_sel n\_sel,  }
 {\tt     load\_spec n\_spec,  }
 {\tt     message dev\_id message,  }
 {\tt     nearest\_spax X Y,  }
 {\tt     peak\_dar COMP\_INDEX DELTA\_INDEx,  }
 {\tt     plot\_flux\_spax device clean,  }
 {\tt     plot\_map min max device palette bright contra sign n\_map,  }
 {\tt     plot\_scale min max device bright contra sign colormap title top\_min top\_max border,  }
 {\tt     plot\_spaxels min max device i1 i2 palette bright contra sign save fill text\_flag [new\_img] [back\_color] [n\_contours],  }
 {\tt     plot\_spectra\_mem min max device device2 palette bright contra sign [clean],  }
 {\tt     plot\_spectra min max device clean palette bright contra sign i\_spax [SAVE] [NBUFFER],  }
 {\tt     pm\_dar COMP\_INDEX DELTA\_INDEX,  }
 {\tt     read\_vel\_map MAPFILE sistemic\_Angstroms [resolution],  }
 {\tt     read\_vel\_map MAPFILE WIDTH,  }
 {\tt     release\_raw dev\_id,  }
 {\tt     reverse\_obj n\_obj,  }
 {\tt     save\_cut SPECTRA\_FILE,  }
 {\tt     save\_file filename,  }
 {\tt     save\_map n\_map filename,  }
 {\tt       save\_obj\_file n\_obj FILE,  }
 {\tt     save\_PT filename,  }
 {\tt     save\_raw SPECTRA\_FILE,  }
 {\tt     save\_slice n\_slice filename units outputtype[0=fits,1=ascii],  }
 {\tt     save\_spec MAPFILE i\_spax,  }
 {\tt     save\_spec\_table MAPFILE units flag i\_spax,  }
 {\tt     set\_first\_last first last,  }
 {\tt     set\_flag\_spec flag\_spec,  }
 {\tt     set\_grid grid\_func grid\_opt pixel\_size,  }
 {\tt     set\_type\_spec\_rep type save n\_buffer,  }
 {\tt     simple\_dar COMP\_INDEX DELTA\_INDEX,  }
 {\tt     skysub n\_spec,  }
 {\tt     slicearith n\_spec1 command n\_spec2 n3,  }
 {\tt     specarith n\_spec1 command n\_spec2,  }
 {\tt  //     stats\_spax SPAXEL\_INDEX,  }
 {\tt     sub\_spec n\_spec1 n\_spec2,  }
 {\tt    Tcl\_AppendResult(interp, tcl\_pgptxt x y j f text size color width,  }
 {\tt     zoom\_raw pix1 pix2 dev\_id,  }
 {\tt
 } 

 {\tt     intensity x y nx ny  }
 {\tt     mark\_range dev\_id colorindex lweight lstyle text x1 y1 x2 y2 }
 {\tt     open\_device DEVICE }
 {\tt     plot\_line dev\_id colorindex lweight lstyle X\_points Y\_points: Argument Error }
 {\tt     plot\_line dev\_id colorindex lweight lstyle X\_points Y\_points: Argument Error }
 {\tt     recolor\_image PALETTE Dev\_id Bright Constrast SIGN }

\end{itemize}

\end{subsection} 


\begin{subsection}{Examples of Tcl/TK scripts}
\label{S:TCL:3}
  

\end{subsection}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
