Program:  cosmicslitmask
Where:    aedon.caltech.edu   ~rrg/public_html/science/cosmic/
  or	  anonymous ftp on phobos.caltech.edu  cd /users/map/cosmic

To compile:
In you .cshrc include the pgplot library in your path:
  set path = ( $path /usr/local/vlb/pgplot /usr/local/bin/X11 )
and create the library path:
  setenv LD_LIBRARY_PATH /usr/lang/SC0.0:/usr/openwin/lib:/usr/local/vlb/pgplot
Then to compile,
  f77 -O -o cosmicslitmask cosmicslitmask.f -lpgplot -lX11

Purpose of program:
  To create multislit mask for use on COSMIC.  You should begin with an object
list in the following format:
    col(1)  integer number of object (not necessarily starting at 1)
    col(2)  real xposition/arcsec; E is positive
    col(3)  real yposition/arcsec; N is positive
    col(4)  real width of slit/arcsec
    col(5)  real magnitude of object 
There is no requirement for object numbers or (x,y) positions to be sorted,
nor is there any requirement that (x,y) correspond directly to (E,N), although
this is the default.  In the program you may choose any rotation angle, flip
axes, scale the axes (using a scale in arcsec/pixel) and delete objects, 
so the input list does not have to be your final object list.
  This program can also be used as a general utility for selecting objects
to create a multislit mask on a wide variety of instruments.  It has no
correction for distortions across the FOV, so the output list created by
this program needs to be run into an appropriate software package for each
instrument.

Output:
(1)  the object list:  
     the first line of the output list includes the centroid and the rotation
	angle relative to the input coordinate list.  If using the output of
	this program as the input of a later iteration of the same program,
	you will need to choose the beginning option to skip the 1st line.
     the first four columns of this output are identical
	to the input list, so you can use the output from one iteration of
	the program as the input of a later iteration.  (The only thing that
	has changed in the 2nd/3rd columns is that the coordinates have been
	converted from pixels to arcsec, if this was requested.)
     the output format:
          col(1)  number of object
          col(2)  xposition/arcsec; E is positive (theta=0-->before rotating)
          col(3)  yposition/arcsec; N is positive (theta=0-->before rotating)
          col(4)  width of slit/arcsec
          col(5)  length of slit/arcsec
          col(6)  percentage of the length of slit to find object
                    0% -> top end of slit; 100% -> S end of slit
          col(7)  xposition/arcsec relative to centroid
          col(8)  yposition/arcsec relative to centroid
          col(9)  length of slit/arcsec west of object
          col(10) length of slit/arcsec east of object
     There will also be 3 lines of information at the top of the output
     file.
(2)  pgplot.ps   This is a horizontal pgplot postscript output; to print
	lpr [-Pps] pgplot.ps
     where the [-Pps] is an optional parameter to choose laserprinter "ps"
     (and the brackets are *not* to be typed).
     You may preview this postscript file on your terminal by
	pageview pgplot.ps &
     which can then be ended by quitting from the pageview window.
       The recommmended procedure below requires creating two separate
     pgplot.ps files (one with object number labels, one without); you should
     rename or print the first one before creating the second (as it will 
     write over the previous file).
       This output plot will have N at the top and E at the left for normal
     sky parity, provided that the rotation angle is taken to be 0.  A
     rotation angle of 90 will put N at the left and E at the bottom.

Recommended parameters:
(1)  4x magnification:  this will mostly fill an 8.5"x11" page (default)
(2)  720"x480" FOV (default)

Beginning Options:
(1)  rotation angle.  Zero maintains the (x,y) of the input file (i.e. no
	rotation).  This can also be changed in the interactive options
	below.
(2)  flip x and/or y axes.  The default is that x is positive in the E 
	direction, y is positive in the N direction.  If there is also a
	rotation involved in your (x,y) list, then you account for that
	via the rotation angle, but note that you will also have to calculate
	the effect of this in your (RA,Dec) for the centroid of the mask.
(3)  pixel scale.  Assumed that (x,y) in input list are in arcsec.  Choose
	a different scale (in arcsec/pixel) if this is not the case.
(4)  skip the 1st lines of the input file.  The output of this program has
	the centroid (x0,y0) of the slitmask in the 1st line.  These are
	measured in arcsec, and are relative to x=0,y=0 of the input
	coordinate list.  (By knowing the RA,Dec of 0,0 in the input list,
	you can then calculate the RA,Dec of the slitmask yourself or via
	another program.)  The 2nd line has the rotation angle you have
	used (i.e. option (1)), and the resultant COSMIC base position angle
	corresponding to it.  The 3rd line has column labels.
(5)  size of mask and enlargement factor.  Alan Dressler usually has
	x size of 720" and y size of 480" for COSMIC, with the laser printer 
	plot having a 4x magnification of the true size of the mask.  Use the 
	default unless you are totally sure of what you are doing (and that 
	what you do will work on the instrument).

Interactive Options:
(1)  Change the rotation angle (degrees).  Zero is equivalent to keeping (x,y)
	as they are in the input file.
(2)  Exclude an object.  Enter the object number (1st column of your input
	file).  It will be flagged for the rest of your session, unless you
	unflag it (option 3).
(3)  Include an object.  Enter the object number to unflag a previously 
	flagged object.
(4)  Replot the current working set of objects, rotation angle, and slit
	lengths on the terminal (normally use /xwin for the xwindow).
(5)  Type the object list:  this print to the terminal two tables, one of 
	the currently selected objects, the other of the excluded objects.
(6)  Write an output file.  Use this to create the output object list
	(you are queried for a filename) and the postscript version of
	the multislit mask.  At the end of a session, normally choose this
	option twice:  once with option 1 to label the objects (for reference
	purposes only) and the second time with option 2 for no labelling
	of the objects (for creating the actual mask).
(7)  Edit slit lengths.  The default is to change from one slit to the next
	at half the distance (in x) between the two objects.  You can change
	this position using this option.  You choose the two neighboring 
	objects (first object is the one on the left; the second on the right
	in the plot) and a change in the interface (from the default value;
	note that a change in this number erases the previous value, and is
	*not* incremental) between the two slits.  Choosing a positive number
	(in arcsec) moves the interface to the right; negative moves it to
	the left.
(8)  Include all objects.  Results in all objects from the input list to be 
	included in the current object list.
(9)  Exclude all objects.  Results in all objects from the input list to be 
	excluded in the current object list; thus there are no objects in 
	the current list.
(10) Exit the program, no further output.

Warnings:
(1)  If a slit is < 10", then a warning message will appear on the terminal
	for that object.
(2)  If a slit is < 3" on one or both sides of an object, then a warning 
	message will appear on the terminal for that object.
(3)  If an object's position is outside of the 720" range in x or 480" range
	in y (or your own choice of this size), then a warning message will
	appear on the terminal, and the object will not be included in the
	mask.  You should exclude these objects from your list (interactive
	option #2).
(4)  If an object is > 60" from the mean y-position of the slits, then a
	warning message will appear on the terminal.  The reimaged pixel
	scale is 0.4"/pixel, and the spectral resolution is 3.1 angstrom/pixel,
	so a difference of 1' will correspond to an offset of the center
	of the spectrum of 465 angstrom.

Recommended Procedure:
(1)  compile cosmicslitmask as described above
(2)  create your input object list in format described above
(3)  run cosmicslitmask varying rotation angle, object selection, and alter
	slit lengths or other parameters, as you wish
	(a)  output your (rotated) final object list (for reference purposes)
	(b)  output a hardcopy 4x magnification (default) of the slitmask 
		with object numbers labelled (for your own reference
		purposes) --> pgplot.ps
		print this on the laser printer
	(c)  output a hardcopy 4x magnification (default) of the slitmask
		with no object numbers (for the camera copy to create the
		actual slitmask) --> pgplot.ps
		print this on the laser printer
(4)  take the printout from (3)(c) to a graphics arts facility (see slitmask
	manual for recommendations) that can make a 4x reduction of the
	hardcopy.  You will want the negative---this is the actual multislit
	mask to take to P200.

Error messages:
  One error message that may come up is PGPLOT---polygon has less than 3 
vertices.  This results if your current object list has an object that falls 
outside of the current field-of-view.  In that case, scroll up to the warning 
messages, and determine which objects are outside of the FOV; then use option 
(2) to remove them from the current object list.
  Currently, only /xwin is working on map's environment (not /xt or /xd) for 
the PGPLOT device selection.
  
Written by:
	Mike Pahre
	Caltech
	15th February 1995