.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
