\section{General Software}

\subsection{Routines for Reading and Saving Data}

\subsubsection{SAVEGEN and RESTGEN} \index{SAVEGEN}
\index{GENX files, reading/writing}

SAVEGEN is a routine available to save variables of any type (including structures).
Some sample calls are shown below.  If no file name is specified, it will use
`save.genx'.
%
\idlinputa{savegen, var1, var2}	
\idlinputb{savegen, var1, var2, var3, var4, var5, file='flare27oct92'}
%
Use RESTGEN to restore the data.  NOTE: It is recommended to use 
SAV\_SDA, SAV\_BDA, SAV\_BSC, and SAV\_HXI whenever possible for standard
SXT, BCS, and HXI data sets.  

\subsubsection{TIFF\_WRITE [IDL-LIB]}
\index{TIFF files, writing}

To write some image data ({\it image}) to a file ({\it outfile}) in TIFF format all
you have to do is type the following for grey scale:
%
\idlinputa{tiff\_write, outfil, image} \index{TIFF\_WRITE}
%
For 256 element (pseudo) color, use:
%
\idlinputa{tiff\_write, outfil, image, red=r, green=g, blue=b} \index{TIFF\_WRITE}
%
where the optional parameters red, green and blue are used to save the
color table characterized by the byte arrays (r, g, b - see TVLCT for
details about obtaining them). 

To make full (24 bit) color TIFF format files see the documentation
for TIFF\_WRITE (i.e. use the DOC\_LIBRARY utility on TIFF\_WRITE).

\subsubsection{MK\_TIFFB}

To make full (24 bit) color TIFF format files to be read on Macintosh
computers use:
%
\idlinputa{mk\_tiffb, outfile, image, r, g, b} \index{MK\_TIFFB}
%
where the required color table is specified by 256 element byte arrays
{\it r, g, b}.  The output TIFF file contains the specified image which has been
flipped vertically for direct display on (most) tiff-readers on the Macintosh
and has a resolution of 100 pixels per inch.  The default output file size
is 774 Kbytes which results from rebinning into image to 508$\times$508 and fits on
the standard double sided Mac floppies (779 Kbytes capacity).  For more
options (such as changing image size which is 508$\times$508 by default, noflip, etc.)
or information on MK\_TIFFB use the DOC\_LIBRARY utility.

\subsubsection{WRT\_FITS [*]}
\index{FITS files, writing}

WRT\_FITS creates a FITS file from an image ({\it data}) by typing: \index{FITS files}
%
\idlinputa{wrt\_fits, outfil, header, data(*,*,n)} \index{WRT\_FITS}
%
where {\it outfil} is the string containing the filename.  {\it header} is optional
input which is the FITS string array ASCII header.  If it is undefined, then
WRT\_FITS will build the minimal header.  The routine RFITS should be used
to read it.  For SXT data, we recommend that you use SXT2FITS which is
described in the next section.

\subsubsection{RFITS}

RFITS reads a standard format FITS file by typing: \index{FITS files}
%
\idlinputa{img = rfits(infil, header=header)} \index{RFITS}
%
where {\it img} is the image, {\it infil} is the input file name, and $head$ is
the string array with the data header in it.  It is possible to use
the $/SCALE$ option to convert the data into some physical units.  For
example, the magnetogram data would be converted to gauss.
%
\idlinputd{img = rfits('/yd0/gbo92\_37/gkm920907.1442', head=head, /scale)}
%

\subsubsection{SAVE [IDL]}

SAVE is an IDL facility that will save variables, etc.  into a file of
your choice.  To save a variables {\it a}, {\it b}, and {\it c} to the default file 
`idlsave.dat', type:
%
\idlinputa{save, a, b, c} \index{SAVE}
%
To save to the file `junk.save', type:
%
\idlinputa{save, a, b, c, filename='junk.save'}
%
To save all variables, type:
%
\idlinputa{save, /all, filename='junk.save'}
%
CAUTION: When restoring the data, the variable names are restored exactly
as they were saved, so if you saved {\it a, b} and {\it c}, then when you restore that
save set, any existing variables {\it a, b} and {\it c} are deleted when the
restore occurs.  A sample command to restore data is:
%
\idlinputd{restore, 'junk.save'} \index{RESTORE} 

\subsubsection{SAVESYS and RESTSYS}\index{system variables}\index{IDL system variables}\index{SAVESYS}\index{RESTSYS}

SAVESYS and RESTSYS provide a simple method for saving and restoring
the state of IDL system variables.  Use of this routine pair will help
programmers avoid global side effects within routines which change
system variables.  In general, the use of these routines should be done
symmetrically within a given routine as the following example dummy code 
segment illustrates.

\begin{verbatim}
        pro junk,a,b,c	       ; function or procedure definition
        savesys,/aplot         ; *** save plot variables with savesys.pro
        <change !x,!y,!z,!p>   ; code which changes IDL system variables
        restsys,/aplot         ; *** restore plot variables with restsys.pro
        return
        end
\end{verbatim}

Another use of restsys.pro is to restore IDL system variables to the startup
state to recover from routines which corrupted the system variables.
%
\idlinputD{2.5}{restsys, /init, /all    }{ ; restore IDL system variables to startup state}

\subsection{Concatenation of Datasets}

\subsubsection{STR\_CONCAT\_TAGS}
\index{structures, concatenating}
\index{concatenating structures}

It is possible to concatenate two structures of same or similar type
by using STR\_CONCAT\_TAGS.  For example, if you wanted to concatenate
the variable {\it index1} and {\it index2}, the command would be:
%
\idlinputd{index\_out = str\_concat\_tags(index1, index2)} \index{STR\_CONCAT\_TAGS} 
%

\subsubsection{STR\_DIFF}
\index{structures, comparing}
\index{comparing structures}

STR\_DIFF will is a boolean function which returns true (1) when differences
are found between the two input structures.  If no
differences are found, it returns false (0).
%
\idlinputa{qdiff = str\_diff(index1, index2)}\index{STR\_DIFF}
\idlinputb{qdiff = str\_diff(index1, index2, /diff}
\idlinputb{qdiff = str\_diff(index1, index2, dtnames=dtnames}
%
where {\it /diff} will only check the tag names. $tnames=tnames$ is an
optional input list of the tag names which should be checked (the default is to check all tags).  
You can get a list of the tags whose values differ by using the
optional keyword output, $dtnames=dtnames$.
STR\_DIFF is not recursive.

\subsubsection{Concatenating Data Arrays}
\index{data arrays, concatenating}
\index{concatenating data arrays}

A sample command for concatenating two 3-D arrays is:
%
\idlinputa{out = [[[in1]],[[in2]]]}
%
If {\it in1} is 100$\times$200$\times$4 and {\it in2} is 100$\times$200$\times$3, then {\it out} would be 100$\times$200$\times$7.
The first two dimensions of {\it in1} and {\it in2} must be identical.  It is possible
to have {\it in2} be 100$\times$200, in which case {\it out} would be 100$\times$200$\times$5.

A sample command for concatenating two 2-D arrays is:
%
\idlinputa{out = [[in1],[in2]]}
%
If {\it in1} was 100$\times$10 and {\it in2} was 100$\times$20, then {\it out} would be 100$\times$30.  In this
case, the first dimension of {\it in1} and {\it in2} must match.

%\subsection{Routines for Data Selection}
\subsection{Routines for Data and Information Extraction}

\subsubsection{The Concept Behind the GT Routines}

A series of GT routines was created so that a single piece of information
can be extracted from a structure, whether the structure was a `roadmap'
or an `index' (the data are saved in a different location).  The routines
also allow for conversions to a string mnemonic or to physical units.  
It is possible to get a list of what the different values are by typing a
command like:
%
\idlinputa{print, gt\_filta()}
%
It is also possible to convert the output value to the string mnemonic by using the
{\it /STRING} switch.  For example:
%
\idlinputa{print, gt\_filta(roadmap, /string)}
%
This command only works for the routines which return a coded value.

\subsubsection{WDEFROI [*]}
\index{light curves, plotting from data cubes}
\index{sub-image extraction}

The WDEFROI function allows the user to select an arbitrarily shaped
region-of-interest (ROI) from a displayed image via the mouse.  
The routine returns either a sub-image or a list of indices to 
the image displayed which defines this sub-image.  If a data 
cube is passed the routine returns either a sub-image data cube
or 2-dimensional list of indices.  NOTE, WDEFROI is not SXT 
specific and thus will also work for ground base images.

Some example calls are:
%
\idlinputa{list = wdefroi( data, zoom=8)}\index{WDEFROI}
\idlinputb{sub\_image = wdefroi( data, zoom=8, /image)}
\idlinputb{list = wdefroi( data, zoom=zoom, /lc, time=time, sub=sub, /logscale)}
%
where,

\vspace{0.2in}\begin{tabular}{lp{10.0cm}}
	INPUT: & { } \\
	data	& {\raggedright Data array for the input image.  If image is 
		a data cube: one needs to specify which image 
		(see the {\it sub} parameter) to display for selecting an ROI.}\\
	{ } & { } \\
\end{tabular}

\begin{tabular}{lp{10.0cm}}
	OPTIONAL INPUT: & { } \\
	zoom	& {\raggedright is the zoom factor used on the displayed image.}\\
	image	& {\raggedright if set will return selected sub-image.}\\
	lc	& {\raggedright if set and a data cube is given, this will allow user 
		to plot light curves of the ROIs.  NOTE: if you pass
		normalized data these light curves will be more
		meaningful.}\\
	time	& {\raggedright time of each image in data cube. This can also be 
		a Yohkoh index data record (e.g. SXT index-data record).}\\
	sub	& {\raggedright is the image index number to use for ROI selection
		if the input data are a data cube.  Note: if you
		do not specify a {\it sub} while using a data cube the
		routine starts STEPPER to allow the user to 
		select an image on-the-fly.}\\
	logscale & {\raggedright if set, will log scale the (decompressed) data for display.}\\
	{ } & { } \\
\end{tabular}

\begin{tabular}{lp{10.0cm}}
	OUTPUT: & { } \\
	sub\_img & {\raggedright  is the returned SUB-image(s) of the selected region
		(when the {\it /image} switch is used).}\\
	list	& {\raggedright is the returned list of selected indices of the 
		input image(s) (default return).}\\
\end{tabular}

(A) PFI Example: An example of selecting a feature from a 64$\times$64 pfi image:
Follow the instructions displayed on the widget.
%
\idlinputa{nimage = wdefroi(data, /image, zoom=8)}
%

(B) FFI Example An example of selecting a small feature from a 512x512 image:
Due to the fact that contouring a large image is a very slow
process do not attempt to contour a 512 $\times$ 512 image directly 
but rather use the ``Box'' and ``select'' features to first isolate
the area of interest before using the ``contour'' feature.  NOTE:
the ``contour'' feature can still be somewhat slow after isolating a 
part of FFI.  Follow the instructions displayed on the widget.
%
\idlinputa{sub\_img = wdefroi(img,/image)	;default zoom is 1}

(C) PFI Data Cube Example: An example of selecting a feature from a cube aligned PFI data set
which has the dimensions of 65x65 by 40 images.  The first line makes a buffer for
the normalized data.  The second line puts the exposure normalized data into {\it dat}.
The last line uses the ``light curve'' option and passes the index information 
for the image times.
%
\idlinputa{dat = fltarr(65,65,40)}
\idlinputb{for i=0,39 do dat(0,0,i) = data(*,*,i)/gt\_expdur(index(i))}
\idlinputb{sub\_img = wdefroi(dat,zoom=7,/image,time=index,/lc)}
%
The function starts the STEPPER routine to allow user to select image.  Once the
user ``quits'' STEPPER the WDEFROI widget will appear.  Select a
``box'' ROI and use the mouse make the selection (use the right mouse
button to finalize the selection).  Use the light curve button to
display a time profile of the total intensity from the selected ROI.
Select ``Exit'' to finalize your selection.  Then run STEPPER on the
newly made SUB-images.	

\subsubsection{CONROI [*]}
\index{sub-image extraction}

Define a contoured region-of-interest of an image using the image
display system and the cursor/mouse.  This function returns a vector
containing the subscripts of pixels inside the contoured region.  Note
that these are `linear' subscripts, not `X, Y' pairs. 
%
\idlinputa{result = conroi( data(*,*,n) )}	\index{CONROI}
\idlinputc{result = conroi( data(*,*,n), zoom=4)} 
%
\subsubsection{PR\_IMAGE}

PR\_IMAGE is used to get a print out and/or the average
count rate in a given area on an image ({\it data(*,*,n)}) by
typing:
%
\idlinputa{pr\_image, data(*,*,n)}	\index{PR\_IMAGE}
\idlinputb{pr\_image, data(*,*,n), size}
%
where {\it size} is the size of the box to be considered
(default is 9$\times$9).  It is a mouse driven program.

\subsection{Routines for Making Time Plots}

\subsubsection{UTPLOT}
\index{time plots, making}

UTPLOT plots any quantity on a
time plot with hours, minutes, and seconds given a
corresponding index array by typing:
%
\idlinputa{utplot, roadmap, gt\_total\_cnts(roadmap, 1)}	
\idlinputb{utplot, index, timehist}	\index{UTPLOT}
\idlinputb{utplot, x, y, ref\_time, xrange=xrange}	
\idlinputb{utplot, x, y, ref\_time, timerange=[index(0), index(100)]}	
\idlinputb{utplot, x, y, ref\_time, timerange=['1-jun-91','5-jun-91']}	
\idlinputb{utplot, x, y, ref\_time}
%
Most typical IDL plotting parameters also apply.  You can overplot other
quantities (timehist2, etc.) by using OUTPLOT. 

\subsubsection{OUTPLOT}
OUTPLOT works just like UTPLOT but does not refresh the
screen so one can plot several different quantities on
the same plot (see UTPLOT first).  An example is:
%
\idlinputd{outplot, index, timehist2} \index{OUTPLOT} 
%
\subsubsection{EUTPLOT}
\index{plots with error bars}
\index{time plots with error bars}

EUTPLOT works like UTPLOT but it over plots vertical error bars on
a plot that was previously made with UTPLOT.  Example calls are:
%
\idlinputA{3}{eutplot,x,y,unc,/unc		}{; unc = +/- uncertainties}
\idlinputb{eutplot,x,low,high}\index{EUTPLOT}
%
where {\tt low = y - unc} and {\tt high = y - unc}.

\subsubsection{PLOT\_LCUR}

PLOT\_LCUR is a low level generic plotting routine used by several other routines.
The routine returns the list of subscripts which are between the times selected
by the user.  The user clicks on the plot with the left button to define a new start time,
the right button to define an end time, and the middle button to exit.  The user can
expand a time range after marking the start/stop times by clicking with the left
button on the box in the lower right corner.  Some of the more simple calls are:
%
\idlinputa{ss = plot\_lcur(roadmap, gt\_sxs1(roadmap))}	\index{PLOT\_LCUR}
\idlinputb{ss = plot\_lcur(index, gt\_sum\_l(index), plotr=a, title=title)}	
\idlinputc{ss = plot\_lcur(index, gt\_sum\_l(index), /nohard)} 
%

\subsubsection{LCUR\_IMAGE}\index{LCUR\_IMAGE}\label{lcur_image}
\index{light curves, plotting from data cubes}

The procedure LCUR\_IMAGE will allow a user to select a portion of an
image and will display a normalized light curve plot.  The region
can be a simple rectangle or a polygon.  LCUR\_IMAGE can be used on
data other than SXT images as long as the {\it index} input has
.TIME and .DAY fields (see ANYTIM2INTS to build a structure).  
Some sample calling sequences are:
%
\idlinputa{lcur\_image, index, data}\index{LCUR\_IMAGE}
\idlinputb{lcur\_image, index, data, lcur}
\idlinputb{lcur\_image, index, data, lcur, uncert, satpix}
\idlinputb{lcur\_image, index, data, xsiz=512}
\idlinputb{lcur\_image, index, data, xsiz=512, /poly}
\idlinputb{lcur\_image, index, data, xsiz=512, /nonorm, subscript=subscript}
%
The data are binned and exposure normalized.  It is possible to mark multiple
locations and to overlay the light curves.  The keyword option {\it /plot6}
will display the multiple plots in six different sub-windows instead of
overlaying the light curves.  The regions being marked are displayed and
labeled so that light curves for a given region can be matched up.  There
are hardcopy options.  If the user passes in the uncertainty {(\it uncert)}
and the saturation map array {\it satpix}, it will mark the points which
have saturated pixels or large uncertainties.  
The {\it xsiz} option will blow up the image to be 512 pixel wide (and 512
pixels tall if it is square) so that the selection of a region is simple.
There are several other options which are described in the program header.

\subsubsection{TPROFILES}
\index{light curves, plotting from data cubes}

TPROFILES will plot the light curve for any pixel in a
data cube (data(x,y,t)).  As you drag the cursor around the image, it updates a light 
curve plot automatically.  It differs from LCUR\_IMAGE since it updates
as the cursor moves (not integrating a box), and plots the intensity versus 
image number, not versus date and time. To use it just type:
%
\idlinputa{tprofiles,data} \index{TPROFILES}
%
The routine is mouse driven and will issue instructions for you.

\subsection{Routines for Image Display and Enhancement}

\subsubsection{STEPPER}

\label{stepper}
STEPPER takes a data cube ({\it data}) and allows a user to step
through the images and to display them as a movie.  If the {\it index}
is passed in to stepper (as shown in 2 of the examples below) it is
possible to chose an option to display light curves.
Some sample calls are:
%
\idlinputa{stepper, data} \index{STEPPER}	
\idlinputb{stepper, data, info\_array}	
\idlinputb{stepper, index, data, xsiz=512}
\idlinputb{stepper, index, data, info\_array}	
%
where {\it info\_array} and {\it xsiz} are optional parameters. {\it xsiz} indicates
the size of the displayed image you want (must be an
integer multiple of the the original array). It is a
window driven program.

The use of the STEPPER routine is described in a little more detail in the
User's Guide.

\subsubsection{XSTEPPER}

XSTEPPER is like stepper but is a widget based program, to run it type:
%
\idlinputa{xstepper, data, info\_array} \index{XSTEPPER}
\idlinputb{xstepper, data}
%
It is a widget driven program with self explanatory instructions.  Some
options include the ability to zoom in on a particular region and the
ability to call XLOADCT from within XSTEPPER.

\subsubsection{XMOVIE}

It is possible to load a data cube into a widget to be ``animated'' using
the routine XMOVIE (which is simply an interface for IDL's XINTERANIMATE).\index{XINTERANIMATE}\index{XMOVIE}
The speed which the frames can be displayed is quite fast.
There are some memory restrictions which do not allow large data cubes.
Some sample calls are:
%
\idlinputa{xmovie, data}
\idlinputb{xmovie, data, ss=ss}
\idlinputb{xmovie, data, 4}
%
The second positional parameter is optional and is the rebinning factor.  This
is quite useful when looking at small 64$\times$64 PFI images.

\subsubsection{OCONTOUR}

OCONTOUR allows you to plot a contour on top of an image
in the same way as you use CONTOUR.
%
\idlinputd{ocontour,image}\index{OCONTOUR} 
%
\subsubsection{UP2, UP4, UP8 [*]}

To re-bin and display an image, you can use the UPn routines.  UP2
will rebin the image to be twice as big and then call TVSCL.  UP4
and UP8 increase the size of the image four and eight times respectively.
A sample call would be:
%
\idlinputd{up8, data(*,*,200)} \index{UP8}\index{UP4}\index{UP2} 
%

\subsubsection{RM\_DARKLIMB [*]}

In order to subtract the limb darkening from H$\alpha$ 
or white light pictures you can call:
%
\idlinputa{img\_out = rm\_darklimb(Haimage)}\index{RM\_DARKLIMB}\index{limb darkening}
%
where {\it Haimage} is the name of the H$\alpha$ image with limb
darkening and {\it img\_out} is the new H$\alpha$ image with limb darkening
removed.  RM\_DARKLIMB
does not work if the image is oblate.  The image should then be viewed
with TVSCL (not TV). 

\subsubsection{GBO\_SCALE2 [*]}

GBO\_SCALE2 can be used for aligning SXT images with each other or with 
other images.  GBO\_SCALE2 takes two images, resizes them and lays them
on top of one another by typing:
%
\idlinputa{outimg=GBO\_SCALE2(trgimg, gboimg)}	\index{GBO\_SCALE2}
\idlinputb{outimg=GBO\_SCALE2(sxtimg, gboimg, index1, sxt=1)}	
\idlinputb{outimg=GBO\_SCALE2(sxtimg1, sxtimg2, index1, index2, sxt=2, /mktv)}
%
which will scale the input image {\it gboimg} and center it to
match a target image {\it trgimg}.  If either of these is an SXT image then
it needs to have its index passed as well, and the SXT keyword should be
set to 1 or 2 appropriately, (i.e., for one or two SXT images). 

GBO\_SCALE2 corrects for different vertical and horizontal diameters. 
The MKTV keyword allows you to plot the result directly.
This should work with general sized images. 

\subsubsection{COMPST [*]}

There is a routine called COMPST that interleaves two images and scales
them to each use half the color table. It does no alignment and requires 
that you have or develop appropriate color tables. The calling sequence is 
%
\idlinputa{imageout= compst(image1, image2)} \index{COMPST}
%
It is currently set up to work with 512x512 images.  It is a good idea
to massage 
the images so that they emphasize the intensity ranges
of interest, e.g., for low-intensity features, a decompressed image gives poor
results.  Creative color tables may also be useful. 

\subsection{Standard IDL Image Display Routines}

\subsubsection{TV [IDL]}

The command TV takes a 2-dimensional variable and displays it directly to
the display (you must have x-windows or a image display device).  There is
no scaling performed on the data.  If the data are not byte type, and there
are values over 255, then wrap-around will occur.  It is probably best to
use TVSCL for these datasets.  To display the first image in the variable
{\it data}, type:
%
\idlinputa{tv, data(*,*,0)} \index{TV}
%
To display the ``i''th dataset, type
%
\idlinputd{tv, data(*,*,i)} 
%
\subsubsection{TVSCL [IDL]}

TVSCL will first perform a linear byte scaling, making the smallest value 0
intensity and the largest value 255.  To display image number 11 in the
variable {\it data}, type:
%
\idlinputd{tvscl, data(*,*,11)} \index{TVSCL} 
%
\subsubsection{CONTOUR [IDL]}

You can contour any given image by typing:
%
\idlinputa{contour,image}	\index{CONTOUR}
\idlinputb{contour, data(*,*,0)}	
\idlinputb{contour, image, levels=[l1,l2,l3,...,ln]}
%
where $levels$ defines the contour levels you want to plot.
{\it levels} is an optional parameter which IDL will
choose for you if you omit them. You can overplot a contour on an
image by using OCONTOUR in the same way.

\subsubsection{XLOADCT [IDL-LIB]}

XLOADCT is a widget driven IDL facility that allows you to change color
tables and manipulate them.  To run it type
%
\idlinputd{xloadct} \index{XLOADCT} \index{color tables} 
%
\subsubsection{LOADCT [IDL-LIB]}

LOADCT will load one of the multiple standard IDL color tables.  To load the
red color table, type:
%
\idlinputd{loadct, 3} \index{LOADCT} \index{color tables} 
%
\subsubsection{TVLCT [IDL]}

TVLCT allows a user to load a color table which he has already defined.
After defining the red, green, and blue intensity profiles, type:
%
\idlinputa{tvlct, red, green, blue}\index{TVLCT}\index{color tables}
%
to load the color table.  If you wish to read the color table which is
currently loaded, type:
%
\idlinputd{tvlct, red, green, blue, /get} 
%
\subsubsection{STRETCH [IDL]}
\index{stretching color tables}
\index{color tables, stretching }

The following command can be used to invert the color table
%
\idlinputd{stretch, 255, 0}\index{STRETCH}

\subsubsection{GAMMA\_CT [IDL]}

The gamma factor for the color table can be adjusted directly using
the routine GAMMA\_CT.  A sample call is:
%
\idlinputd{gamma\_ct, 0.6}\index{GAMMA\_CT}

\subsubsection{MOVIE [IDL-YO]}

The MOVIE routine is an IDL routine that displays an image data
cube (x,y,t).  The data should be byte type.  It is run by typing:
%
\idlinputa{movie,data} \index{MOVIE}
%
You can vary the speed of the movie.  No information is printed with the
image, for that see STEPPER and XSTEPPER.  The standard IDL routine was
modified to make !ORDER default to zero which is the proper orientation
for Yohkoh images.

\subsubsection{PALETTE [IDL-LIB]}

PALETTE is an IDL facility that allows you to create a
new color table. To run it just type:
%
\idlinputa{palette}\index{PALETTE}
%
To save the color table use TVLCT by typing
%
\idlinputa{tvlct,r,g,b,/get} \index{TVLCT}
%
This will save the red, green, and blue vectors in {\it r}, {\it g}, and {\it b}.  To
re-load this color table, type:
%
\idlinputd{tvlct,r,g,b} 
%
\subsubsection{PROFILES [IDL]}
PROFILES enables you to obtain a plot of a row or column
of a two dimensional image by typing
%
\idlinputa{profiles,image} \index{PROFILES}
%
you should have image in the format (size and normalization) that you
wish first.  It is a mouse driven program. 

\subsubsection{ZOOM [IDL-LIB]}

ZOOM takes an image that is already being displayed and displays
the zoomed region in a new window.  The user uses the cursor and clicks
with the left button to chose the center of the region to zoom (the
selected region is displayed each time the left button is clicked).  The
middle button allows the zoom factor to be selected using a menu.  The
right button exits the zoom option (the zoom window is deleted upon
exiting ZOOM).  An example would be:
%
\idlinputa{tvscl, data(*,*,5)}	\index{ZOOM}
\idlinputc{zoom}
%

\subsection{Routines for Image Alignment}

The routines described here can generally be used on SXT or 
ground-based images.

%\subsubsection{SXT\_PREP}
%%
%%See the description of SXT\_PREP on page~\pageref{sxt_prep} for details on aligning SXT images.

\subsubsection{COAL\_IMAGE}
\index{alignment with ground-based images}
\index{ground-based images, aligning to SXT}


COAL\_IMAGE is a medium level routine to perform the scaling,
alignment, and roll two images so they are co-aligned.  Some sample calls are:
%
\idlinputa{data\_out = coal\_image(data, index\_or\_corn, out\_corn, out\_siz)}\index{COAL\_IMAGE}
\idlinputb{data\_out = coal\_image(data, index, out\_corn, out\_siz, index\_out=index\_out)}
\idlinputb{data\_out = coal\_image(img1, corner1, corner2, out\_siz, mag=pix1/pix2)}
%
where the first parameter is the image which is to be changed so that
it is co-aligned with another image.  The second parameter can be
an SXT index or the pixel address of the lower left corner relative to
the sun center for the input image.  The pixel address
is in units of the input image pixel size.  The third parameter is where
you want to shift the image to, it is a two element array of the lower corner 
value (relative to sun center) for the output array in output pixel units.
{\it out\_siz} is the output size of the image, {\it mag} is the
magnification factor required to convert the image to the same scale as
the other image.  The optional input {\it angle=angle} is available to
correct for a roll difference between the two images.

\subsubsection{FIT\_LIMB}

\begin{sloppy}
FIT\_LIMB will find the center and radius of an image, even images with
a partial limb.
FIT\_LIMB is a modified version of SXT\_CENTER which will also work on
non-SXT images.  For non-SXT images, the pixel size must be known.
The algorithm requires a VERY good initial guess to remove bad limb
points. 
Some sample calls are:
%
\idlinputa{fit\_limb, image, x, y, r, pixel\_size=2.5}\index{FIT\_LIMB}
\idlinputb{fit\_limb, image, x, y, r, pixel\_size=3.97, /interactive}
\idlinputb{fit\_limb, image, x, y, r, pixel\_size=2.5, initial=[434,512,403]}
\idlinputb{fit\_limb, image, x, y, r, index=index}
%
where the input is {\it image} which is the solar image.  The outputs 
$x$ and $y$ are the E/W and N/S position
of the sun and $r$ is the solar radius.  
The $x$ and $y$ locations are in full resolution pixels if it
is an SXT image.  It is possible to return the location in the
summed pixels (half resolution or quarter resolution) by using
the option {\it /summed\_pixels}.
The keyword {\it index=index}
should be used for SXT image, and the keyword {\it pixel\_size} should
be used for non-SXT images.  For non-SXT images, the user should specify
an initial guess using the keyword {\it initial} or the \mbox{\it /interactive}
option which will allow the user to click on the sun center location.
There are other options and output (like the oblateness and the phase of the
2nd harmonic) which is described in more detail in the documentation header.
\end{sloppy}

\subsubsection{DSK\_LOCB [*]}

DSK\_LOCB (disk locator) will find the center
coordinates and disk radius of an optical solar image.  
It currently works on white light, H$\alpha$, and magnetogram images, or
anything with a clearly defined edge.  The images are all treated using
a histogram technique.  (There is an old routine called DSK\_LOC
that uses a derivative technique for white light etc., as they
have a high and noisy background).  
A sample call is:
%
\idlinputa{dsk\_locb, image, horzcnt=x0, vertcnt=y0, horzrad=rx, vertrad=ry} \index{DSK\_LOCB}
%
where the keywords return the values of the radius and disk center. 

A complete list of the optional keywords follows:

\vspace{0.2in}\begin{tabular}{ll}
{\tt horzcnt } & {\raggedright horizontal center, floating point}\\
{\tt vertcnt}  & {\raggedright vertical center, floating point}\\
{\tt horzrad}  & {\raggedright horizontal diameter, floating point}\\
{\tt vertrad}  & {\raggedright vertical diameter, floating point}\\
{\tt eastlimb} & {\raggedright east limb, in pixels}\\
{\tt westlimb} & {\raggedright west limb, in pixels}\\
{\tt npole } &   {\raggedright north pole, in pixels}\\
{\tt spole} &    {\raggedright south pole, in pixels}
\end{tabular}

\subsubsection{FIND\_LIMB}

FIND\_LIMB also finds the location of the center of the optical sun and it's
radius.  A sample calling sequence is:
%
\idlinputa{find\_limb, img, x0, y0, r0} \index{FIND\_LIMB}
%
where {\it img} contains the input image and {\it x0,y0,r0 }
receive the output center
location and diameter of the disk. FIND\_LIMB only works on whole images.  Also see FIT\_LIMB.


\subsection{Time Routines and Conventions}
\index{time representations, Yohkoh formats}

There are three time conventions used in the Yohkoh database.

\subsubsection{Internal Representation}
\index{internal time rep, Yohkoh format}
\index{time, internal representation}

The internal representation uses two variables to define the date and
time of an event.  One variable (integer*2) is the number of days since 1-Jan-79 (DS79) and
the other (integer*4) is the number of milliseconds from the start of the day to the event (MSOD). 
Almost all data are saved using this internal representation which uses
a total of 6 bytes. 

The Yohkoh structures use the internal time representation and store the
two values in tags .TIME and .DAY.  The routine GT\_TIME and GT\_DAY will
extract the data in these fields (the routines are needed because the
.TIME and .DAY fields are nested in the .GEN portion of the index structures).

\subsubsection{External Representation}
\index{external time rep, Yohkoh format}
\index{time, external representation}

The external representation uses a 7 element integer array to define the 
time of an event.  This representation uses 14 bytes.

\begin{verbatim}
             (0) = hour 
             (1) = minute
             (2) = second
             (3) = millisec
             (4) = date
             (5) = month
             (6) = year
\end{verbatim}

\subsubsection{String Representation}

The time of an event can also be represented with a string.  The general rules
are:

\IItem
\item The month uses the first three letters of the month (Jan, Feb, Mar...) OR \\
	it can use the month number with the / notation.
\item For the standard convention using the three letters of the month:
	\IItem
	\item The date and year are separated from the month using `-'
	\item The year can come before or after the month (7-Jan-92 or 92-Jan-7)
	\item If the year is not passed, it will use the current year
	\item The year can be two or four digit notation
	\end{itemize}
\item If the month number and / notation is used:
	\IItem
	\item It is assumes YY/MM/DD or DD/MM/YY.  If you
		wish to use MM/DD/YY, then the /MDY switch must be used on
		ANYTIM2INTS, ANYTIM2EX and TIMSTR2EX.
	\item There can be no spaces before or after the /
	\item It must include all three items (date, month, year)
	\item It differentiates between YY/MM/DD and DD/MM/YY by looking
		for the year, which must be greater than 1932 and less
		than 1999.
	\end{itemize}
\item The hour, minutes and seconds are separated by `:'
\item The milliseconds are entered as a fraction of seconds.  For example,
\mbox{`16-Dec-91  02:29:40.819'}
\item There is a space between the date and the time
\item The time can come before or after the date
\end{itemize}

\subsubsection{FMT\_TIM}

The routine FMT\_TIM will take a structure and return a string with the
date and time.  For example, the command:
%
\idlinputa{a = fmt\_tim(roadmap(0))}\index{FMT\_TIM}\index{time}
%
will return the string `16-DEC-91  02:29:40'.  It is
possible to use the /MSEC keyword and get \mbox{`16-DEC-91  02:29:40.819'}
instead.

\subsubsection{FMT\_TIMER}

The routine FMT\_TIMER is like FMT\_TIM, except that FMT\_TIMER is a
procedure which prints the first and last time in the index structure:
%
\idlinputa{fmt\_timer, index}\index{FMT\_TIMER}
{\tt (first, last) = '16-DEC-91  02:29:40', '16-DEC-91  02:29:40'}
%
In this case, the index structure was a scalar, so the first and last
times are the same.  The times can be returned in optional output
variables:
%
\idlinputa{fmt\_timer, index, t1, t2}
%
The {\it t1} and {\it t2} are string variables which can be used in calls to
other routines (such as PLOT\_GOES, for example).


\subsubsection{ANYTIM2INTS}

ANYTIM2INTS takes any of the three representations and returns a 
structure with the internal representation.  The structure has a 
.TIME and a .DAY field.  An example is:
%
\idlinputa{a = anytim2ints('23-jun-92 3:00')}\index{ANYTIM2INTS}\index{time}
%
This routine has an optional keyword input to allow the user to offset
the input time by some number of seconds.  If the input is an array
of times, then the offset can be a scalar value or it can be an array
of offsets which is the same length as the input.  For example,
%
\idlinputa{a = anytim2ints(roadmap, off=60.5)}	
\idlinputb{a = anytim2ints(roadmap, off=off)} 
%
The following command will set up a structure which has 
has the dates of 100 Mondays starting on 7-Jan-91 (since 7-Jan-91 is
a Monday and there are 86400 seconds in a day).  The second example
sets up a 500 element array with times separated by 90 seconds.
%
\idlinputa{dates = anytim2ints('7-jan-91', off=findgen(100)*86400.*7)}
\idlinputc{tt = anytim2ints(!stime, off=findgen(500)*90.)}

\subsubsection{ANYTIM2EX}

ANYTIM2EX takes any of the three representations and returns an
array with the external representation.  If the input is only
one time, then the output is a seven element array.  If it is an array
of `N' elements, then the output is a 7$\times$N array.
%
\idlinputd{b = anytim2ex(roadmap)} \index{ANYTIM2EX} \index{time} 
%
\subsubsection{GT\_DAY}
GT\_DAY is  a function that returns the date from
the index or roadmap structure in a string variable
(other are options available) by typing:
%
\idlinputd{date = gt\_day(index,/string)} \index{GT\_DAY} \index{time} 
%
\subsubsection{GT\_TIME}
GT\_TIME is a function that returns the UT from
the index or roadmap structure in a string variable
(other are options available) by typing:
%
\idlinputd{time = gt\_time(index,/string)} \index{GT\_TIME} \index{time} 
%
\subsubsection{INT2SECARR}
INT2SECARR takes a structure (e.g., roadmap or index)
containing time and will create an array of times (t) in
seconds from some given reference.  If the second parameter is not passed,
then the first time in the input array is used
%
\idlinputa{t = int2secarr(roadmap)}\index{INT2SECARR}\index{time}
%
The example above will produce an array of times with respect to the first time.
%
\idlinputa{t = int2secarr(roadmap, ref\_time)}	
\idlinputc{t = int2secarr(roadmap, '1-sep-91')} 
%

\subsubsection{ANYTIM2DOY}

ANYTIM2DOY takes any of the three representations and returns the
day of year number.
%
\idlinputd{b = anytim2doy(roadmap)} \index{ANYTIM2DOY} \index{time} 
%

\subsubsection{DOY2EX}
\index{day-of-year (DOY)}

DOY2EX takes a day of year and a year and returns the
seven element array containing the date.
%
\idlinputd{daytim = doy2ex(doy, year)}\index{DOY2EX}
%

\subsubsection{EX2DOW}
\index{day-of-week (DOW)}

EX2DOW will take the external representation and return the
day of the week number, 0 for Sunday, 1 for Monday, ...
%
\idlinputd{dow = ex2dow(tarr)}\index{EX2DOW} 
%

\subsubsection{EX2FID}
\index{FID (fileID)}

EX2FID will take the external representation date/time and return a string
with the fileID.
%
\idlinputd{fid = ex2fid(input)} \index{EX2FID} 
%
\subsubsection{TIM2ORBIT}

TIM2ORBIT will take a set of input times and will determine which orbit
and which week the data falls in.  It can also return the number of minutes
into the orbit for an input time.  A sample interactive use of the routine
would be:
%
\idlinputa{tim2orbit,'23-jun-92 6:00',/print} \index{TIM2ORBIT}\index{determining week IDs}\index{week IDs}
%
The item returned for this would be:

\begin{verbatim}
     Input               S/C Day     Night in   FileID    WeekID  D/N    SAA?
   Date     Time        Time  Min Ago  (min)
23-JUN-92  06:00:00   05:13:14 46.77   14.98  920623.0513  92_26  Day
\end{verbatim}

The S/C day started 46.77 minutes earlier, and night will occur in 14.98 minutes
(it is S/C day mode).  The FileID for this time is 920623.0513 and the WeekID
is 92\_26.

Optional Keyword Output Parameters (the number of output elements is the same 
as the input):

\vspace{0.2in}\begin{tabular}{lp{15.0cm}}
{\tt FEM  } & {\raggedright the FEM structure}\\
{\tt FID  } & {\raggedright the FileID for each input time}\\
{\tt WID  } & {\raggedright the WeekID for each input time}\\
{\tt SAA  } & {\raggedright a boolean array, TRUE if in SAA}\\
{\tt SCDAY  } & {\raggedright a boolean array, TRUE if in S/C Day}\\
{\tt TIM2FMS  } & {\raggedright the number of minutes since sunrise}\\
{\tt TIM2NIGHT  } & {\raggedright the number of minutes before sunset}\\
\end{tabular}

\subsubsection{SEL\_TIMRANGE}
Given an array of times, SEL\_TIMRANGE will return the subscripts of the
elements which fall between a set of input times.  The {\it /between}
option should be used when you want all datasets between the start and
stop times, since the default is to return the first entry BEFORE the
start time (this was for historical reasons when accessing the FEM structures).
It is possible to
have a boolean array returned which is the same length as the input.
The array will have a 1 if the input time is in the time range
specified, and a 0 otherwise.  This is useful for using with WHERE 
commands.
%
\idlinputa{ss = sel\_timrange(roadmap, st\_tim, en\_tim)}	\index{SEL\_TIMRANGE}
\idlinputb{ss = sel\_timrange(orbit\_arr, '1-jul-92', '22-jul-92', /between)}	
\idlinputc{ok = sel\_timrange(index, '23-jun-93', '24-jun-93', /boolean)}

\subsubsection{PR\_TIM2WEEK}\index{PR\_TIM2WEEK}
\index{week ID, how to determine}\index{how to determine week ID}

PR\_TIM2WEEK will convert a Yohkoh time into the corresponding week ID
and print a message on the screen.  For example:
%
\idlinputA{3}{pr\_tim2week		}{; Give the current week number}
\idlinputb{pr\_tim2week,'15-nov-91'}
\idlinputb{pr\_tim2week,'15-nov-91',/range}
%
Setting the $/range$ keyword will cause the routine to display the
first and last day of the week.  Short weeks (the first or last
week of the year) are flagged with an asterisk.  PR\_TIM2WEEK
calls ANYTIM2WEEKID to make the conversion.

\subsubsection{PR\_WEEK2TIM}\index{PR\_WEEK2TIM}

PR\_WEEK2TIM will print on the screen the first and last day of a
specified week number (integer) or Yohkoh week ID (string).  For
example:
%
\idlinputA{3}{pr\_week2tim		}{; List current Yohkoh week}
\idlinputb{pr\_week2tim,'91\_46'}
\idlinputB{3}{pr\_week2tim,'91\_46a'	}{; Last letter is optional}
\idlinputB{3}{pr\_week2tim, 4		}{; Week 4 of current year}
\idlinputB{3}{pr\_week2tim, 4, year=93	}{; Week 4 of 1993}
%
Short weeks (the first or last week of the year) are flagged with an
asterisk.  PR\_WEEK2TIM calls WEEKID2EX to make the conversion. 

\subsection{Routines for Windows and Output Devices}

\subsubsection{Making Landscape and Portrait Plots}

The command to have the PostScript plots be in landscape orientation is:
%
\idlinputa{set\_plot,'ps'}	
\idlinputb{device, /land}
%
In order to have the portrait plots take up the full page, there is
an un-official routine called LASER.  The calling sequence is:
%
\idlinputa{set\_plot,'ps'}	
\idlinputc{laser, /portrait}
%
\subsubsection{WDEF}
\index{window, X, how to make}
\index{X-window, how to make}

WDEF creates a window of a set size.  The first example will make a 512$\times$512 window in the
top right hand corner of your screen.  The second example makes a 128$\times$128 window,
and the last example makes a 900$\times$512.
%
\idlinputa{wdef,0}	
\idlinputb{wdef,0,128}	
\idlinputb{wdef,0,900,512} \index{WDEF}
%
Window 1 is in the lower right, 2 is in the upper left, and 3 is in the
lower left (even windows on top, window modulo 4 equaling 0 or 1 is on the
right)

\subsubsection{WSHOW [IDL]}

WSHOW pushes a covered IDL image window to the foreground while
keeping the text window active (this is not necessarily true for cases where the
active window is selected by the location of the cursor). Just type
%
\idlinputd{wshow} \index{WSHOW} 
%
\subsubsection{HARDCOPY}

Dumps the contents of a 'X' screen to a laser printer with either b/w or
color options by simply typing:
%
\idlinputa{hardcopy}	
\idlinputb{hardcopy, /black} \index{HARDCOPY}
%
It is recommended to only use HARDCOPY to get hardcopies for images.
If you want to get a hardcopy of a line plot, then first change the output
device to a PostScript file (idl.ps), re-run the plotting program or plotting 
commands, and then issue the print command.  An example would be:
%
\idlinputa{set\_plot, 'ps'} \index{SET\_PLOT}	
\idlinputb{.run plot\_sot}	
\idlinputb{pprint} \index{PPRINT}	
\idlinputc{set\_plot, 'x'} 
%
\index{laser plots}

\subsubsection{PPRINT}

PPRINT closes and prints an idl.ps file.  An example of how to
use it would be
%
\idlinputA{2.5}{set\_plot,'ps'		}{; opens idl.ps file}	
\idlinputB{2.5}{device, /land		}{; optionally use landscape orientation}	
\idlinputb{.... (your plot commands)}	
\idlinputb{pprint} \index{PPRINT}	
\idlinputb{set\_plot,'x'}
%
This will send the plot to the laser printer.

\subsubsection{SETDISP}
\index{DISPLAY, setting inside IDL}

It is possible to issue the ``setenv DISPLAY'' command from within IDL
by using the routine SETDISP (if the user forgets prior to starting IDL).
A sample call would be:
%
\idlinputd{setdisp, '192.68.162.109:0'}\index{SETDISP}

