Initial commit

1 files changed, 226 insertions, 0 deletions

diff --git a/pkg/proto/doc/suntoiraf.hlp b/pkg/proto/doc/suntoiraf.hlp
new file mode 100644
index 00000000..4e14ffc2
--- /dev/null
+++ b/pkg/proto/doc/suntoiraf.hlp
@@ -0,0 +1,226 @@
+.help suntoiraf Apr92 proto
+.ih
+NAME
+suntoiraf -- convert Sun raster files into IRAF images
+.ih
+USAGE
+suntoiraf input
+.ih
+PARAMETERS
+.ls names
+List of raster files to be converted.  The output image names will be
+the same as the individual input file names with a ".imh" appended
+(assuming that you are using the Old Image Format).  Rasterfiles with
+an extension of `.ras', will have the extension omitted.  The images will
+appear in the same directory as the raster files, typically the \fBUnix\fR
+login directory when the task is used within an imtool R_DISPOSE string.
+.le
+.ls apply_lut = yes
+Apply the lookup table translation to each pixel?  If \fBapply_lut\fR =
+no, the pixel values will be taken directly from the raster file.  If
+\fBapply_lut\fR = yes, an NTSC weighted translation from the rasterfile's
+color lookup table will be applied to each pixel to convert to grayscale.
+.le
+.ls delete = no
+Delete the rasterfile after making the image?  This is useful for making
+automated (Unix or IRAF) scripts for producing photographic or other hardcopy.
+.le
+.ls verbose = yes
+Print informative information while the transformation is occurring?
+.le
+.ls listonly = no
+List the rasterfile header information instead?
+.le
+.ls yflip = yes
+Flip the output image top to bottom?  Rasterfiles are stored in reverse
+vertical order from IRAF images.
+.le
+.ih
+DESCRIPTION
+\fBSuntoiraf\fR will convert Sun raster files into IRAF images.  This is
+useful, for example, to make \fBsolitaire\fR photographic prints or
+other hardcopy from an \fBimtool\fR window (see IMTOOL HINTS, below).
+
+For general use, \fBsuntoiraf\fR will convert non-run-length-encoded
+Sun rasterfiles into IRAF images.  The output image will have the same
+name as the input rasterfile, but with a `.imh' (or other IRAF image
+extension) appended.  If the rasterfile has an extension of `.ras', this
+extension will be omitted from the image name.
+
+If \fBapply_lut\fR = no, the (typically 8 bit) pixel values will be
+copied directly to the output with no interpretation.  If \fBapply_lut\fR
+= yes, the NTSC equalization weighting will be applied to the RGB lookup
+table to convert the color rasterfile to a grayscale image.  The weights
+are 0.299, 0.587, and 0.114 for the red, green, and blue LUT entries,
+respectively.
+
+Various options are available to tailor the operation of the task to
+your (or your script's) precise liking.  If \fBdelete\fR = yes, the
+input raster file will be removed from the disk after the image
+conversion.  This is useful in script applications.  If \fBverbose\fR =
+yes, a running commentary will be presented, otherwise the operation of
+the task is silent except for error messages.  If \fBlistonly\fR = yes,
+the task will report information about each input rasterfile, rather
+than converting it.  If \fByflip\fR = yes, the storage order of the
+lines of the output image will be inverted from the input rasterfile.
+Since the display convention is inverted for rasterfiles relative to
+IRAF images, this will result in an upright output image.  On the other
+hand, if \fByflip\fR = no, the storage order will be preserved at the
+expense of the output orientation appearing inverted.
+.ih
+IMTOOL HINTS
+One possible first step in making a hardcopy is to create the raster files
+from the imtool window.  The recommended way to do this is to select "Imcopy"
+from the imtool frame menu.  If the menu is popped up by positioning the
+cursor on the right hand side of the window frame (and away from the edge
+of the screen), the menu won't overlay the window, possibly contaminating
+the hardcopy.  The resulting raster file will save not only the pixels from
+the imtool buffer but also the lookup table information.
+
+Another way to generate an imtool screendump is to use the <F7> function
+key, but this requires care because of the possibility of catching cursor
+fallout in the solitaire.  If you do use the <F7> function key, position the
+cursor to minimize its visual impact.  The cursor will appear in the
+hardcopy (solitaire) unless it happens to blink out at the moment that
+the hardcopy is made.
+
+A possibly confusing choice is the "Save" option in the imtool setup menu.
+This is inappropriate because no lookup table information is preserved.
+
+Only the portion of the frame buffer that is displayed in the window
+will be snapped - what you see is what you get.
+
+If you have to adjust the contrast and brightness of the image very
+much by using the right mouse button, you may want to redisplay the
+image using a different Z1 and Z2.  This will preserve the grayscale
+resolution in cases in which the "effective" Z1 and Z2 are much
+different than the "actual" Z1 and Z2.
+
+In the setup menu try:
+
+.nf
+    Show colorbar:	No
+    Background color:	black
+.fi
+
+The choice of the background color may have an effect on any graphics
+in the frame.
+
+If you use the \fBimttodmd\fR shell script available at NOAO/Tucson,
+the pixel files for the images will be created in the IRAF directory
+`tmp$', which is typically the UNIX directory `/tmp/'.  If you have
+trouble with this directory filling up, the pixel files may be placed
+into another directory by setting the UNIX environment variable `tmp'
+to the desired pathname:
+
+.nf
+    % setenv tmp '/scr1/v13/pixels/'
+.fi
+
+*before* starting up IMTOOL (IN THE PARENT SHELL OF THE IMTOOL).
+Note that if this is set when IRAF is entered, all IRAF temporary
+files will end up in this directory.
+.ih
+EXAMPLES
+These are rather specific to NOAO/Tucson, but may suggest ways that the
+task may be useful to you.
+
+To configure imtool for one button solitaire operation:
+
+The Unix shell script, "/ursa/iraf/extern/nlocal/lib/imttodmd" (on
+Ursa and its kin) can be used to make imtool solitaire prints.  The
+script may move to /usr/local/bin in the future and would thus be
+available like any other unix command.  Imttodmd is meant to be
+called directly by the imtool.  For example, place these lines in
+your `.login' file:
+
+.nf
+    setenv R_RASTERFILE 'snap.%d'
+    setenv R_DISPOSE '/ursa/iraf/extern/nlocal/lib/imttodmd %s'
+.fi
+
+More recent versions of imtool also allow setting these strings from
+the setup panel.
+
+The parent shell of the imtool must have these variables defined in
+its environment prior to starting imtool.  If you aren't sure what
+this means, the simplest thing to do is to edit these lines into
+your \fB.login\fR, log off of the workstation \fBcompletely\fR, and
+log back into Unix, Sunview, and IRAF.
+
+Pressing <F7> will send snaps directly to the solitaire queue, leaving
+no intermediate files.  Only the windowed portion of the frame buffer
+will be snapped.  The necessary files will twinkle in and out of
+existence in the current working directory of the imtool, typically
+your Unix login directory.  Your windows will be frozen until the
+solitaire is safely on its way, at which time the screen will beep.
+This should take on the order of half a minute for a 512 square
+imtool on a lightly loaded system.  If faster response is needed,
+the script may be run in the background:
+
+.nf
+    setenv R_DISPOSE    '/ursa/iraf/extern/nlocal/lib/imttodmd %s &'
+.fi
+
+Care should be taken in this case to avoid having too many
+(\fBtoo many is typically more than one\fR) background job running
+at once.
+
+
+To make one-button snap files and solitaires:
+
+The \fBimttodmd\fR script has various options for leaving the
+intermediate files around.  To leave the snap images in your
+directory and also make solitaires (i.e., if you are highly
+suspicious by nature) set the variable:
+
+.nf
+    setenv R_DISPOSE    '/ursa/iraf/extern/nlocal/lib/imttodmd -image %s'
+.fi
+
+
+To only make the images, with no solitaire output:
+
+.nf
+    setenv R_DISPOSE    '/ursa/iraf/extern/nlocal/lib/imttodmd -nocrt %s'
+.fi
+
+This will allow you to run a single CRTPICT job after collecting all
+the snap files.
+
+
+To make solitaires from an imtool window, the old way:
+
+Enter this from the UNIX shell, \fBbefore starting suntools\fR:
+
+.nf
+    % setenv R_RASTERFILE "frame.%d"
+.fi
+
+Start suntools, login to iraf and load the noao, tv and local
+packages.  Display an image and press the <F7> function key to
+create a raster file named "frame.N", where N is an index number
+generated by imtool.  This raster file will be appear in your
+\fBUNIX\fR login directory.
+
+Dump the raster files to the solitaire queue:
+
+.nf
+    lo> suntoiraf frame.*
+    lo> crtpict frame.*.i.imh ztrans=min_max z1=5 z2=260
+	(The z1 & z2 values were empirically determined.)
+.fi
+
+*** Don't forget to clean up! ***
+
+.nf
+    lo> imdelete frame.*.i.imh
+    lo> delete frame.*
+.fi
+
+The solitaires should be ready the next day in the basket by the
+main computer lab.
+.ih
+SEE ALSO
+irafil, binfil, and the UNIX man page for imtool
+.endhelp