\section{Communication with the Outer World}

\subsection{From CLASS}

Some \class\ commands directly produce \gildas\ images.  {\tt
  ANALYSE$\backslash$CUBE} produces a spectral line data cube, {\tt
  ANALYSE$\backslash$STRIP} an image (either position-velocity, or
continuum map). Command {\tt ANALYSE$\backslash$TABLE} produces a
pseudo-table which can further be processed to produce a spectral line
data cube using \texttt{MAP$\backslash$XY\_MAP}.

For spectra, tables can be produced by commands {\tt
  ANALYSE$\backslash$GREG}, {\tt ANALYSE$\backslash$PRINT}.

\subsection{From a Program}

A complete and efficient use of the \gildas\ format from a program is
beyond the scope of this chapter : refer to the programmer's guide for
that.  There is however a simple and easy-to-use subroutine that accepts a
Fortran array and writes a \gildas\ image. The price for simplicity is that
only minimal header information is written: many useful stuff like World
coordinates, Blanking value, and so on, will be missing. With this
restriction, you can simply write a Fortran array in \gildas\ format using
the routine {\tt GDF\_IMAGE}.

\begin{verbatim}
     SUBROUTINE GDF_IMAGE(NAME,NX,NY,NZ,NT,Z,ERROR)

Where the arguments are
     NAME   C*(*)   the GILDAS file name
     NX     I       the number of pixels in the first dimension
     NY     I       the number of pixels in the second dimension
     NZ     I       the number of pixels in the third dimension
     NT     I       the number of pixels in the fourth dimension
     Z      R*4     the array of dimensions NZ,NY,NZ,NT
     ERROR  L       a logical error flag (Output)
\end{verbatim}

If you need more complete information, refer to the programmers guide.  You
may also later modify the file header using command {\tt HEADER} in
GRAPHIC, or through the \sic\ variables defined by commands {\tt DEFINE
  HEADER} or {\tt DEFINE IMAGE}.

\subsection{From other Packages: the ACCEPT command}

The {\tt ACCEPT} command in \sic\ often allows to directly read files from
other packages provided one knows the file structure.  Here is an example
of how to read a bitmap from a PostScript file.
\begin{verbatim}
SIC\DEFINE INTEGER A[314,590] J
SIC\ACCEPT A /ARRAY IC348.TXT /FORMAT "(8(36Z2.2,/),26Z2.2)"
SIC\DEFINE IMAGE B TEST.GDF REAL /LIKE A
FOR I 1 TO B%DIM[2]
LET J B%DIM[2]+1-I
LET B[J] A[I]
NEXT
\end{verbatim}
We assume you have extracted (using a standard text editor) the bitmap in a
intermediate file (here IC348.TXT), and taken the sizes (here 314 by 590)
from the PostScript description. The format specifier is generic, except
for the exact padding required to read one bitmap row at a time. 

\subsection{From and To other Packages: FITS}

For astronomical applications, conversion from other data formats can be
done through FITS format. The FITS image must reside on disk.

Disk FITS conversion can be a non-trivial task is the input FITS file
has a complex structure. Several tools are thus available
\begin{itemize}

\item {\tt FITS\_GILDAS} (FITS to \gildas ) and {\tt GILDAS\_FITS} (\gildas\ to FITS) Tasks
can process simple FITS files

\item {\tt VECTOR$\backslash$FITS FitsFile.fits FROM|TO GildasImage.gdf}  \\
provide a command line equivalent to the above tasks. Since FITS keywords are not fully normalized, although a standard subset is recommended, this command supports keyword redefinition. If you
receive a tape with source name coded as {\tt SOURCE} (instead of {\tt
  OBJECT}), all you need to do is to define a \sic\ symbol named {\tt
  SOURCE} with translation {\tt OBJECT}. This is done simply by typing the
command
\begin{verbatim}
    SIC\SYMBOL SOURCE OBJECT
\end{verbatim}
This trick does not work with the {\tt FITS\_GILDAS} task.

\item \texttt{SIC$\backslash$DEFINE FITS Var FitsFile} is similar to DEFINE IMAGE, and will create
a SIC structure which will copy the FITS file content. The LET command can be then used to copy (part of) this structure into an Image variable if needed, and thus convert to the image format.
It only works on existing FITS file however, and cannot be used to create a FITS file from
a SIC structure.

\item \texttt{SIC$\backslash$DEFINE IMAGE} will automatically attempt to convert a FITS file into
the Gildas equivalent, using the same method as FITS\_GILDAS. This will work transparently
on simple FITS images (with no FITS XTENSION).
\end{itemize}
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "gildas-intro"
%%% End:
