Repatch (from linux) of OSX IRAF

1 files changed, 1066 insertions, 0 deletions

diff --git a/pkg/dataio/doc/export.hlp b/pkg/dataio/doc/export.hlp
new file mode 100644
index 00000000..4ef4a492
--- /dev/null
+++ b/pkg/dataio/doc/export.hlp
@@ -0,0 +1,1066 @@
+.help export Oct94 dataio
+.ih
+NAME
+export -- create a binary image file from one or more IRAF images
+
+.ih
+USAGE
+export images binfiles
+
+.ih
+PARAMETERS
+
+.ls images
+The list of input IRAF images to be converted.  The list may contain
+either 2-D images  or 3-D images.
+Any number of 2-D images may be combined to a single output file, only
+one 3-D image (or section) at a time may be converted.  See the \fIBuiltin 
+Formats\fR section for notes about the number of image expressions required 
+for each builtin format and the handling of 3-D image data.  Images greater
+than three dimensions should be converted using image sections.
+.le
+.ls binfiles
+The list of output binary files to create.  If any of the builtin formats
+is selected for conversion the filename will have an extension added
+reflecting the format (if it is not already given).
+.le
+
+.ce
+OUTPUT PARAMETERS
+.ls format = "raw"
+The type of binary file to write.  If the value is "raw" then the input
+images are converted directly to a raw binary raster using the task 
+parameters.  If the value is "list" the pixel values will be written
+to the standard output after evaluation of the \fIoutbands\fR parameter in
+the same format as would appear from the \fILISTPIX\fR task.  Finally,
+the value may include any of the currently supported specific builtin formats:
+
+.nf
+	eps		- Encapsulated PostScript
+	gif		- Compuserve's GIF format
+	imh		- IRAF OIF image
+	miff		- ImageMagick MIFF format image
+	pgm		- PBMPlus PGM format image
+	ppm		- PBMPlus PPM format image
+	ras		- Sun rasterfile format
+	rgb		- SGI RGB format image
+	xwd		- X11 Window dump file
+.fi
+
+If any of these builtin formats is selected one or more of the following 
+parameters may be ignored. See the \fIBuiltin Formats\fR section for notes 
+about the formats supported by this task.
+.le
+.ls outbands = ""
+Output image band expressions to write.  This is a comma-delimited list of 
+expressions or an @-file containing the expressions.  Evaluated expressions 
+do not all need to be the same length since the output image will be padded
+to the maximum size.  See below for more information.
+.le
+.ls verbose = no                    
+Print verbose output to the screen during conversion?
+.le
+
+.ce
+RAW BINARY OUTPUT PARAMETERS
+.ls header = yes
+For raw binary file output only, prepend a header describing how the data 
+are stored?  If set to "no" then no header will be written.  If set to "yes", 
+a standard text header describing how the data were written will be 
+prepended to the output file.  Setting the \fIheader\fR parameter to the 
+reserved string "long" will write the image headers from the IRAF images
+making up the output file in the standard header.  The parameter may also
+be set to a filename that will be prepended to the output file.  This
+parameter is ignored for builtin format output. See below for a description 
+of the header layout.
+.le
+.ls outtype = ""
+Output pixel type if \fIformat\fR is set to "raw" or "list".  This is a 
+string giving the type and size of each pixel, the syntax for the outtype 
+entry is
+.nf
+
+		<type>[<nbytes>]
+where
+    type = b            # byte
+           u            # unsigned (short) integer
+           i            # signed integer
+           r            # ieee floating point
+           n            # native floating point
+
+    nbytes = 1, 2, 4, or 8
+
+.fi
+If no value for \fInbytes\fR is given the smallest size for the given type
+(i.e. 1 byte for 'b', 2 bytes for ints, 4 bytes for floating point) will
+be used.  If no value is entered at all the type of the input image is used, 
+for multiple images used to create a single binary file the type of the first 
+image is used.  This parameter is ignored for builtin format output options.
+.le
+.ls interleave = 0
+Pixel interleave type.  If the \fIoutbands\fR parameter is composite 
+(i.e. a comma-delimited list of expressions) the output file is pixel 
+interleaved and the \fIinterleave\fR parameter is ignored.  If the 
+\fIoutbands\fR parameter is a single expression the file is line-interleaved 
+when the \fIinterleave\fR value is a positive integer.  If the \fIoutbands\fR 
+is an empty string or a single expression the binary file is band interleaved 
+if this parameter is zero.  This parameter is ignored for builtin formats 
+where the pixel storage is predefined.
+.le
+.ls bswap = "no"
+Type of byte-swapping to perform on output. The default is bswap=no which
+may be abbreviated "bswap-" (similarly a value of 'yes' can be abbreviated
+"bswap+").  If disabled no byte-swapping is performed, if set all integers
+are swapped on output relative to the current machine's byte ordering.
+Values of 'i2' or 'i4' will swap only two or four byte integers respectively,
+floating point values remain unswapped.  This parameter may be used by some
+builtin formats that don't have a specified byte order.
+.le
+
+.ih
+DESCRIPTION
+	The \fIexport\fR task will convert one or more images in an
+input list to a binary raster file, a text listing of pixels values,
+or one of several specific file formats.  For general binary
+rasters, various pixel types, data interleaving, and the byte order can be
+specified.  An optional header may be added to the output file.
+Arbitrary arithmetic expressions, using both standard and custom
+functions, may be applied to the images in the
+input list before conversion allowing the user to scale intensity values,
+change image orientation, compute colormaps, or compute output pixel
+values.
+
+	The \fIformat\fR parameter controls the type of output generated:
+if set to \fIraw\fR a binary file described by the \fIouttype\fR, 
+\fIinterleave\fR, and \fIbswap\fR parameters is written with pixel values
+determined from the expressions in the 
+\fIoutbands\fR parameter.  The value of \fIouttype\fR
+defines the output pixel size and type (long or short ints, native or IEEE
+reals, see parameter description for details).  The
+\fIbswap\fR parameter can be used to set the byte order (relative to the
+current machine) of integer values, this 
+parameter is ignored for floating point pixels or builtin
+formats with a specified byte order. The \fIoutbands\fR and \fIinterleave\fR 
+parameters define the pixel storage in the binary file.  For multiple 
+\fIoutbands\fR
+expressions the data are assumed to be pixel interleaved (e.g. written 
+as { {RGB}, {RGB} ...} triplets).  For single expressions, a positive value 
+of \fIinterleave\fR indicates that the data are written in a line-interleaved
+manner (e.g. a line of R, a line of G, ...).  If \fIinterleave\fR is
+zero and \fIoutbands\fR is a single expression 
+then no interleaving is done and the image bands are written sequentially.  
+If \fIoutbands\fR is the null string, all pixels in a single input image 
+will be written to a single output file.
+Error checking is done to make sure the combination of these 
+parameters is correct.  If the \fIheader\fR parameter is "yes" a text header
+describing how the data were written will be prepended to the file, setting
+the \fIheader\fR parameter to the reserved string "long"
+will cause the image header for each input image
+to be saved in the standard header.  The \fIheader\fR parameter may also 
+be the name of a user-defined file to prepend to the output instead of the
+standard header.
+
+	If the \fIformat\fR parameter is set to "list" the pixels values 
+will be written to the screen as an ascii list of pixel coordinates 
+followed by the pixel value.   Pixel coordinates are determined using the
+same interleaving scheme as above, values are determined by evaluating
+each \fIoutbands\fR expression.
+
+	Lastly, the \fIformat\fR parameter may be any of the currently
+supported builtin formats.  See the section on \fIBuiltin Formats\fR for
+more information and the restrictions or requirements of each format.
+
+.ih
+MORE ON OUTBANDS EXPRESSIONS
+	The simplest specification for \fIoutbands\fR is a null string, 
+in which case the image is converted directly (i.e. band storage, 
+pixels converted to output type).  Arbitrary interpreted arithmetic 
+expressions using standard and custom functions and operators are also 
+supported.  If the \fIimages\fR parameter is a list of 3-D images the 
+operand names are the predefined tags b1, b2, ... bN for the bands in each 
+image, the \fIbinfiles\fR parameter must contain an equal number of 
+output files.  To convert multiple 3-D images they must either be sliced 
+to individual 2-D images (or specified as image sections) or stacked into 
+a single image.  If the \fIimages\fR parameter is a list of 2-D images 
+(or sections) the operand names are the predefined tags i1, i2, ... iN for 
+the each image in the input list, the b1, b2, etc names are also recognized.
+For more complex or 
+lengthy expressions the \fIoutbands\fR parameter may alternatively be an
+@-file containing the expressions.  Within this @-file whitespace and
+newline characters are ignored to allow expressions to be indented in a 
+readable manner.
+
+	The image operands determine which input images in the list are
+converted to which output files.  For 3-D input images one IRAF image is
+converted for each output file in the list, for 2-D images multiple images
+may be converted to a single output file.  In the latter case the list 
+pointers are updated automatically to keep track of the images.  For example,
+to convert six images to two output files, the \fIoutbands\fR expression
+should contain three images operands.  The first three images in the list
+will be used in evaluating the expressions for the first output file,
+the last three for the second file.
+
+	The image tags may be reordered in the expression but still refer to 
+e.g. band-1, band-2 and so on.  For example (where rgbim is a 512x512x3 image, 
+and rim, gim, and bim are 512x512 images),
+
+.nf
+cl> export rgbim file outtype="u2" header-                       (1)
+cl> export rgbim file outtype="u2" header- outbands="b3,b2,b1"   (2)
+cl> export rim,gim,bim file outty="u2" outbands="i3,i2,i1"       (3)
+cl> export rim,gim,bim file outty="b" outbands="gray(i1,i2,i3)"  (4)
+.fi
+
+Example (1) converts the input image pixels to a raw binary file of 
+unsigned short integers with no header written as one image band following 
+another.  In example (2) the order of the bands is reversed and the binary 
+file is stored as pixel interleaved BGR triplets of short ints.  
+Example (3) is the same as (2) except that the input images in the list 
+are reordered instead of bands within a single image. When using the image 
+tags the input list is updated to account for this, so it is allowed to have 
+more input images than output binary files.
+In example (4) the three images are converted to a single grayscale image
+before being written as byte data to the binary file.
+More complex and detailed examples are given below.
+
+Individual \fIoutbands\fR expressions are composed of operators and operands
+in general interpreted arithmetic expressions as follows:
+
+\fBOperands\fR
+.nf
+
+	iN		      	    # image list item
+	iN.param		    # image parameter
+	@"param"	    	    # parameter of 3-D image
+	bN		      	    # band within 3-D image
+
+	func()		      	    # function
+	constant	      	    # numeric constant
+.fi
+
+    The 'iN.param' and '@"param"' syntax allows an image header parameter 
+to be accessed.  For example 'i2.otime' refers to the 'otime' image 
+header parameter in the second image of a list and '@"otime"' refers to the 
+current image if the input list contains 3-D images.  They may
+be used in an outbands expression such as
+.nf
+
+    (i1*(i1.otime/i2.otime)),i2,(i3*(i3.otime/i2.otime))	(1)
+    (b1/@"otime")),(b2/@"otime"),(b3/@"otime")			(2)
+
+.fi
+to normalize the output bands by the exposure time value in the second image
+in the first example, or to normalize by the 'otime' keyword of a 3-D image
+in the second example.
+
+    In cases where a constant value is used as an outbands expression an 
+alpha channel (an extra 8-bits of constant intensity) will be created 
+consisting of that value.  For example, writing a 32-bit RGB image with an 
+alpha channel of 255 could be written using
+
+    cl> export rgbim file outtype="b1" outbands="b1,b2,b3,255"
+
+
+\fBOperators\fR
+
+The expression syntax implemented by \fIexport\fR provides the following
+set of operators:
+
+.nf
+
+        ( expr )              	    - grouping
+        + - * /               	    - arithmetic
+        **                    	    - exponentiation
+        //                    	    - concatenate
+        expr ? expr1 : expr2  	    - conditional expression
+    
+        &&                    	    - logical and
+        ||                    	    - logical or
+        !                     	    - logical not
+        <                     	    - less than
+        <=                    	    - less than or equal
+        >                     	    - greater than
+        >=                    	    - greater than or equal
+        ==                    	    - equals
+        !=                    	    - not equals
+	?=                          - substring equals
+.fi
+
+The conditional expression has the value \fIexpr1\fR if \fIexpr\fR is true,
+and \fIexpr2\fR otherwise.  Since the expression is evaluated at every pixel
+this permits pixel-dependent operations such as checking for special pixel
+values, or selection of elements from either of two vectors.  For example,
+the command
+
+        	(i1 <= 0) ? 0 : 1
+
+has the constant value zero if "i1" is less than or equal to zero, 
+and one otherwise, effectively creating a pixel mask of positive pixels.
+Conditional expressions are general expressions and may be nested or used
+anywhere an expression is permitted.
+
+The concatenation operator applies to all types of data, not just
+strings.  Concatenating two vectors results in a vector the 
+combined length of the two input vectors.  An example use of this would
+be to concatenate images side-by-side on output.
+
+
+\fBSpecial Functions\fR
+
+	In addition to the intrinsic functions already provided (see the help
+page for the \fIimexpr\fR task for a list of standard, mathematical and type
+conversion functions) there are a number of custom functions for this task:
+
+.ce
+\fBOutput Functions:\fR
+
+.nf
+       band (args)     	    	  - force band interleaved storage
+       line (args)         	  - force line interleaved storage
+      flipx (args)   	     	  - flip image in X dimension
+      flipy (args)   	     	  - flip image in Y dimension
+
+      block (val,width,height)	  - block fill area with a constant
+.fi
+
+    These functions define how the output data are written. For builtin 
+formats whose normal orientation and storage format is known these functions 
+are ignored (except where noted).  These functions may not be used as arguments to other functions (except where noted) or as single operands
+within expressions (e.g. "255 + flipx(i1)"), however their arguments may
+be expressions or (perhaps output) functions themselves.
+
+.ls band (args)
+Force band storage in the output file regardless of the value of the
+\fIinterleave\fR parameter.  This may be used to specify multiple
+expressions for each band while still forcing band storage (the default
+for multiple expressions is pixel-interleaved storage).  This function
+may be used with some builtin formats to write multiple images to the output
+file as if they were a column of images in the original. This function
+is ignored by builtin formats that do not support this scheme (i.e RGB
+format) and may be used as an argument to the \fIsetcmap()\fR, \fIpsdpi()\fR,
+and \fIpsscale()\fR functions only.
+.le
+.ls line (args)
+Force line storage in the output file regardless of the value of the
+\fIinterleave\fR parameter.  This may be used to specify multiple
+expressions for each band while still forcing line storage (the default
+for multiple expressions is pixel-interleaved storage).  This function
+is ignored by builtin formats that do not support this scheme.
+.le
+.ls flipx (args)
+Flip the image left-to-right on output.  This function may be used as an
+argument to the \fIband()\fR, \fIsetcmap()\fR, \fIpsdpi()\fR, or 
+\fIpsscale()\fR functions only.
+.le
+.ls flipy (args)
+Flip the image top-to-bottom on output.  Certain builtin formats (such as
+GIF, PGM, PPM, RAS and XWD) have their normal orientation already flipped wrt 
+to IRAF and these will automatically be flipped on output.  Using this
+function with those formats cancels the flip action, writing the image in the
+normal IRAF orientation and not the normal format orientation.
+This function may be used as an argument to the \fIband()\fR, \fIsetcmap()\fR,
+\fIpsdpi()\fR, or \fIpsscale()\fR functions only.
+.le
+.ls block (value, width, height)
+Fill an area with a constant value.  This function can be used to fill a
+vertical area between images to provide padding of a constant value.  It
+is similar to the "repl()" intrinsic function which replicates a data element
+a given number of times.
+.le
+
+
+.ce
+\fBScaling Functions:\fR
+.nf
+
+   zscale (arg [,z1, z2 [, nbins]]) - scale to a fixed number of bins
+               zscalem (arg1, arg2) - automatic scaling with filtering
+           gr[ea]y (arg1,arg2,arg3) - RGB to grayscale conversion
+          bscale (arg, zero, scale) - linearly transform intensity scale
+       gamma (arg, gamma [, scale]) - apply a gamma correction
+.fi
+
+        These functions may be used to scale the intensity values of the
+image before output in order to map image datatypes to a specified range.
+The 'args' value may be a list of image operands or expressions.  These 
+functions may be used as arguments to the output functions above
+or as operands within more complex expressions.
+
+.ls zscale (arg [,z1,z2 [,nbins]])
+Scale the pixels in a given range to a specified number of bins.  This
+function will map the input pixels within the range z1 to z2 to one of 
+'nbins' values.  Pixels less than z1 are mapped to the lowest output
+intensity value, pixels greater than z2 are mapped to the highest value.
+If no \fIz1\fR and \fIz2\fR arguments are given appropriate values will
+be computed using the same algorithm and default parameters used by 
+the \fIDISPLAY\fR task (see the help page for more information).
+If no \fInbins\fR value is given 256 bins are assumed.
+
+If the given value of z1 is greater than z2 the mappings will be inverted,
+i.e. larger pixel values will map to the lower bin numbers, smaller pixel
+values will map to larger bin numbers.  For example, to map the dev$pix
+test image to 200 colors such that there are "black" stars on a "white"
+background one could use
+.nf
+
+	zscale (b1, @"i_maxpixval", @"i_minpixval", 200)
+.fi
+.le
+.ls zscalem (arg1, arg2)
+This is a variant of the zscale operand with automatic scale calculation;
+i.e.  zscale (arg).  The first argument is the same as for zscale to select
+the pixel values.  The second argument is a boolean (true or false)
+expression selecting whether a value in the first argument is to be used in
+the calculation.  This allows limiting the automatic scale calculation to
+pixels specified in a mask or to a certain range to exclude extreme or bad
+values that would otherwise perturb the result.  Typical usages might be
+.nf
+
+	zscalem (i1, i2==0)
+	zscalem (i1, i1>0&&i1<10000)
+.fi
+where i1 are the image pixels and i2 would be pixels from the second
+input argument which defines a mask.  Note that you can't just say i2
+for a mask but must use it in an expression resulting in a true or false
+value.  Also note that the result is always in the range 0 to 255.
+.le
+.ls grey (arg1,arg2,arg3) or gray (arg1,arg2,arg3)
+Convert three image operands or expressions to a single grayscale image
+using the standard NTSC equation:
+.nf
+
+	Gray = 0.3 * arg1 + 0.59 * arg2 + 0.11 * arg3
+.fi
+.le
+.ls bscale (arg, zero, scale)
+Linearly transform the intensity scale of the image using the equation
+.nf
+
+	new[i] = (arg[i] - zero) / scale
+
+.fi
+Pixels are scaled in their input datatype prior to converting to the output
+datatype.
+.le
+.ls gamma (arg, gamma [, scale])
+Apply a gamma correction to the pixels.  Pixel values are scaled according to
+the equation
+.nf
+
+	new = scale * [ (old/scale) ** (1.0/gamma) ]
+
+.fi
+If no scale argument is given a value of 255 will be assumed.
+.le
+
+
+    \fIAdditional functions\fR are supported for specific formats:
+
+.nf
+      Function	           Description		    Formats
+      --------	           -----------		    -------
+    cmap (r,g,b [,ncols])  create 8-bit colormap    GIF,RAS,XWD,EPS
+ setcmap (args, [opts])    define a colormap        GIF,RAS,XWD,EPS
+   psdpi (args, dpi)       set dpi for output	    EPS
+ psscale (args, scale)     set scale of output	    EPS
+.fi
+
+	These functions may take as arguments some of the output functions
+named above.  For example, one can specify the dpi resolution of EPS output
+and band storage of images using something like
+.nf
+
+	psdpi(band(args), dpi)
+
+.fi
+
+.ls cmap (arg1,arg2,arg3 [, ncolors])
+Compute an 8-bit colormap from three image operands or expressions using a
+Median-Cut Algorithm and Floyd-Steinberg dithering.  The computed colormap
+is written to the header of the output file.  The resultant image 
+is an 8-bit color index into the computed colormap.  The \fIncolors\fR argument
+specifies the number of desired colors, a default value of 256 will be used
+if not provided.  This function is only
+allowed for builtin formats supporting color lookup tables and may not be
+used within another expression or function.
+.le
+.ls setcmap (args, cmap [, brightness, contrast]) 
+Define the colormap to be used on output.  This function is only supported
+for formats that support colormaps, the \fIargs\fR expressions are used to
+compute the color index values.  The \fIcmap\fR argument may either be the
+filename of a normalized colormap table (such as is used by \fIXImtool\fR)
+or one of the builtin values:
+.nf
+	aips0		- and RGB false color mapping
+	blue		- various shades of blue
+	color		- standard B/W and RGB colormap
+	grayscale	- standard grayscale
+	greyscale	- (alias for above)
+	green		- various shades of green
+	halley		- standard halley mission colormap
+	heat		- temperatures as colors
+	rainbow		- rainbow colors
+	red		- various shades of red
+	staircase	- RGB staircase
+	standard	- RGB ramps
+	overlay		- grayscale with IMDKERN overlay colors
+.fi
+
+Colormap names must be quoted with either single or double quote characters.
+The optional \fIbrightness\fR and \fIcontrast\fR arguments have default 
+values of 0.5 and 1.0 respectively corresponding to the default 
+brightness/contrast scaling of the \fIXImtool\fR display server.  
+If the cmap argument is an empty string the default Grayscale LUT will 
+be used, IRAF logical paths may be used in the filename specification. 
+.le
+.ls psdpi (args, dpi)
+Specify the dots-per-inch resolution of the output image.  The default 
+resolution is 300dpi, this may need to be reset for some printers or if
+the raster rendering produces "bands" in the output.  This function may
+only be used as an argument to the \fIpsscale()\fR function.
+.le
+.ls psscale (args, scale)
+Specify the scale of the output image.  The default value is 1.0 which 
+means that image printed on a 300dpi device is roughly the same size 
+as displayed on a typical 72dpi screen.  Scale values less than one reduce
+the image size on the page, values greater than one increase the size.  The
+scale value will automatically be adjusted if it creates an image that will
+not fit on a 8.5 inch by 11 inch page.  A scale value of 0.25 prints one
+image pixel per 300dpi printer pixel.  This function may
+only be used as an argument to the \fIpsdpi()\fR function.
+.le
+
+.ih
+EXPORT HEADER FORMAT
+	The header prepended to the binary data is ascii text consisting of
+keyword-value pairs, one per line, terminated with a newline after the
+value, beginning with the magic string 
+"format = EXPORT".  Using an ascii header allows the file format to be
+easily determined by the user with a file pager or any program reading 
+the file.
+
+Defined keywords are:
+
+.nf
+	date		    - date file was written (dd/mm/yy)
+	hdrsize		    - size of header (bytes)
+	ncols		    - no. of image columns
+	nrows		    - no. of image rows
+	nbands		    - no. of image bands
+	datatype	    - pixel type (as <type><nbytes>)
+	outbands	    - outband expression list
+	interleave	    - interleave value (same as above)
+	bswap		    - are ints swapped relative to MII format?
+	image1 		    - image names used in creating file
+	  :
+	imageN	
+	header1 '{' <header> '}'  - image headers of above
+	  :
+	headerN	'{' <header> '}'
+	end		    - terminate header
+.fi
+
+If the \fIheader\fR parameter is set to "long" the image headers for 
+each image used in creating the file is included in the output header, 
+otherwise only the image names are included.
+
+A sample (verbose) header might look like:
+
+.nf
+    format = EXPORT
+    date = '19/06/94'
+    hdrsize = 2084
+    nrows = 512
+    ncols = 512
+    nbands = 1
+    datatype = 'i2'
+    outbands = ''
+    interleave = 0
+    bswap = no
+    image1 = "dev$pix"
+    header1 = {
+    IRAF-BPX=                   16  /  DATA BITS/PIXEL
+    IRAFTYPE= 'SHORT   '            /  PIXEL TYPE
+    CCDPICNO=                   53  /  ORIGINAL CCD PICTURE NUM
+    ITIME   =                  600  /  INTEGRATION TIME (SECS)
+    	:   :		:			:
+    }
+    end
+.fi
+
+.ih
+BUILTIN FORMATS
+	While the task provides a way of writing general binary raster
+files there is still a need for converting to specific formats.  
+Implementing most formats is trivial since they usually follow the
+data model and the only "builtin" knowledge of the format is the minimal
+header required.  More complex formats such as GIF and EPS are implemented 
+as special cases.  Note that all of the builtin formats require 8-bit color
+index or 8-bits per color in RGB or RGBA files, users should be careful
+in how the datatype conversion from IRAF image types is handled. In most
+cases this can be handled with the \fIzscale()\fR or \fIzscalem\fR functions.
+
+	For each of the formats listed below the table shows the number
+of \fIoutbands\fR expressions required and the type of output file that
+can be written.  Complete examples for the most common cases are shown in
+the \fIExamples\fR section below.  The columns in the table are defined as
+.nf
+
+    #expr		- number of required \fIoutbands\fR expressions
+    Type		- RGB or 8-bit colormap (index) file
+    bitpix		- number of bits-per-pixel
+    CLT?		- does the file have a colormap?
+    Alpha?		- does the file have an alpha channel?
+    Interleaving	- type of pixel interleaving
+    Notes		- see explanation below each table
+
+.fi
+A general description and specific restrictions or requirements are given for 
+each format.  An error is generated of the input parameters do not meet the 
+requirements of the requested format.  Unless otherwise noted the values of 
+the \fIheader\fR, \fIbswap\fR and \fIinterleave\fR parameters will be ignored.
+The value of \fIouttype\fR will be set internally and is also ignored.
+
+	If the input image is 3-D and no \fIoutbands\fR expressions are
+given, then where supported each band will be written to the output file as 
+a complete image or RGB color component.  For example, a 512x512x3 image 
+will be written as a 512x1536 image with each band comprising one third 
+the height of the output image.  If the output format requires 24-bit pixels 
+then each band of the image will be written as a color component.
+
+	The currently supported builtin formats include:
+
+.ls EPS     - Encapsulated PostScript
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       no    no      none          
+
+.fi
+	The output 8-bit Encapsulated PostScript image
+centered on the page at a default scale of 1.0 at 300dpi (i.e. the image will
+appear on a 300dpi printer about the same size as displayed on a 72dpi 
+screen).  The output scale may be adjusted using 
+the \fIpsscale()\fR function, e.g. to set the output for one image pixel
+per 300 dpi printer pixel use "psscale(b1,0.25)" (one quarter the normal size
+on the page).  The output dpi resolution may be set explicitly with 
+the \fIpsdpi()\fR function, this is sometimes necessary if "bands" appear 
+in the final output image.  Color EPS files may be written as either RGB
+postscript or with a colormap applied to the data (using either the
+\fIcmap()\fR or \fIsetcmap()\fR functions).
+.le
+.ls GIF     - Compuserve's GIF format
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       yes   no      none          1
+    3      index  8       yes   no      none          2
+
+    Notes:
+	1) Colormap generation enabled using \fIsetcmap()\fR or else
+           default grayscale colormap will be used
+	2) use of \fIcmap()\fR required to generate colormap
+
+.fi
+	The output file is a GIF '87 image.  A linear colormap of 256 entries 
+will automatically be generated if only one image or expression is given for
+conversion and no colormap is specified.  
+If three images or expressions are specified a 24-to-8 bit
+conversion can be done using a Median Cut Algorithm and Floyd-Steinberg
+dithering with the required \fIcmap()\fR function.  Since the colormap 
+sizes are limited to 256 entries the maximum pixel value is assumed to 
+be 255, i.e. the output pixel size will be forced to 8-bits or less.
+.le
+.ls IMH     - IRAF image file
+	The output file is an IRAF OIF format image of the specified datatype.
+Writing the image out as another IRAF image may be used to scale or composite
+several images into a new image that can be annotated with the \fITVMARK\fR
+task before writing out the final format.
+.le
+.ls MIFF    - ImageMagick MIFF format image
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       no    no      none
+    1      index  8       yes   no      none          1,2
+    3      rgb    24      no    no      pixel         
+
+    Notes:
+	1) Colormap generation enabled using \fIsetcmap()\fR
+	2) Colormap generation enabled using \fIcmap()\fR
+
+.fi
+	The output file is a Machine Independent File Format image, with or
+without a colormap or as a 24-bit RGB image.  Although MIFF permits 64K
+colors in a colormap the task only supports 256 colors, no compression is
+used in the image.  The maximum pixel value per color is assumed to be 255.
+.le
+.ls PGM     - PBMPlus PGM format image
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       no    no      none
+    3      index  8       no    no      none          1
+
+    Notes:
+	1) Grayscale may be produce with \fIgray()\fR function
+
+.fi
+	The output file is an 8-bit raw (i.e. binary pixels) PGM image.  
+The maximum pixel value is assumed to be 255.
+.le
+.ls PPM     - PBMPlus PPM format image
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    3      rgb    24      no    no      pixel         
+
+.fi
+	The output file is an 24-bit raw (i.e. binary pixels) PPM image. 
+The maximum pixel value per color is assumed to be 255.
+.le
+.ls RAS     - Sun rasterfile format
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       no    no      none
+    1      index  8       yes   no      none          1,2
+    3      rgb    24      no    no      pixel
+    4      rgb    32      no    yes     pixel
+
+    Notes:
+	1) Colormap generation enabled using \fIsetcmap()\fR
+	2) Colormap generation enabled using \fIcmap()\fR
+
+.fi
+	The output file will be a Sun rasterfile.  The header values
+(long integers) may be byte swapped by setting the \fIbswap\fR parameter 
+to "yes" or "i4".  For 32-bit true-color rasterfiles the
+alpha channel should be specified as the first expression.  The maximum 
+pixel value is assumed to be 255.
+.le
+.ls RGB     - SGI RGB format image
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       no    no      none          
+    3      rgb    24      no    no      scanline      
+
+.fi
+	The output file will be an SGI RGB (IRIS) format image.  Although
+this format supports colormaps they are not supported by this task.
+The maximum pixel value is assumed to be 255.
+.le
+.ls XWD     - X11 Window dump file
+.nf
+
+  #expr    Type   bitpix  CLT?  Alpha?  Interleaving  Notes
+  -----    -----  ------  ----  ------  ------------  -----
+    1      index  8       yes   no      none          1,2,3
+    3      rgb    24      no    no      none          
+
+    Notes:
+	1) Linear grayscale colormap automatically generated
+	2) Colormap generation enabled using \fIsetcmap()\fR
+	3) Colormap generation enabled using \fIcmap()\fR
+
+.fi
+	The output file will be an X11 window dump file.
+A linear colormap of 256 entries will automatically be generated if only 
+one image or expression is given for conversion, the \fIsetcmap()\fR function
+may be used to create an alternate colormap.  If three images or expressions 
+are specified a 24-to-8 bit conversion can be done using a Median Cut 
+Algorithm and Floyd-Steinberg dithering if the \fIcmap()\fR function is 
+specified.  Header values (long integers) may be byte swapped by setting the
+task \fIbswap\fR parameter to "yes" or "i4".  The maximum pixel value is 
+assumed to be 255.
+.le
+
+.ih
+COLOR OUTPUT IMAGES
+	In theory the colormaps generated by the \fIcmap()\fR and
+\fIsetcmap()\fR functions could be written in the header for raw binary
+output and the pixel written out as color indices, but since we also
+support color index formats which are recognized widely by other packages 
+there is no need to do this.  Therefore we limit the use of colormaps to 
+the builtin formats which already support it.
+
+	The simplest type of "color" image is the familiar grayscale image.
+Pixel values represent the display gray level, although for some formats a CLT 
+(color lookup table) is required (e.g. GIF) and these pixel values are 
+actually indices into a grayscale colormap.  Most of the conversion done
+with this task will produce a grayscale image of some sort.  For "color 
+index" images the pixel values are indices into a colormap containing the 
+RGB components of the color for a pixel with that value.  Colormaps 
+usually permit at most 256 possible colors implying 8-bit pixels.
+In this task the colormap may be computed either with the \fIcmap()\fR (which 
+does a 24-to-8 bit mapping of the colors) or the \fIsetcmap()\fR function 
+(which computes the colormap from a display lookup table of colors).  
+"True color" images are those which have 24-bits of color (8-bit for each
+component) for each pixel, some true color images also contain an alpha 
+channel (an extra 8-bits of constant intensity) which may or may not be 
+used by the software displaying the image.
+
+	The \fIcmap()\fR function takes three images and computes a colormap
+using Paul Heckbert's Median Cut Algorithm ("Color Image Quantization for
+Frame Buffer Display", SIGGRAPH '82 Proceedings, pg 297) and Floyd-Steinberg 
+dithering technique.  The computed colormap is written to the file header 
+and pixel values are converted to color indices.  By default 256 colors are 
+computed but fewer colors may be requested.  This function is most useful 
+for generating pseudo-color images from three input images taken in different
+filter bands (which is required for some formats like GIF that do not 
+support 24-bit RGB).
+	
+	The \fIsetcmap()\fR function, on the other hand, can be used to
+generate a color image from a single input image and a lookup table such as
+the ones used by displays servers like XImtool.  In this case the pixel
+values are indices into a pre-defined colormap which is normalized between
+zero and one (so that it may be scaled to the desired number of colors).
+The \fIbrightness\fR argument defines the center of the transfer function, the
+default is 0.5 because it in the middle of the normalized range.  The 
+\fIcontrast\fR arguments sets the contrast of the transfer function.  For
+example, the normalized pixel values and default brightness/contrast settings
+will map the pixel values to the corresponding color in the LUT.  Changing
+the brightness to a lower value means that pixel intensities will map to lower
+values in the LUT, doubling the contrast for instance means that the LUT 
+will increment two colors for every unit pixel change.  This is what happens
+when changing a displayed image in IRAF with the mouse by moving the cursor
+left-right (changing the brightness) or up-down (changing the contrast).
+
+	An example use of this function would be if one wanted to convert an 
+IRAF image to a color rasterfile with the same colormap and intensity 
+scaling as was displayed in XImtool.  After adjusting the display the 
+brightness/contrast values could be read from the control panel and the 
+rasterfile generated using
+.nf
+
+        setcmap (b1, "aips0", 0.36, 1.2)
+
+.fi
+where the "aips0" is one of the builtin colormaps and the brightness and
+contrast arguments are those from the ximtool display.  Similarly, the
+expression
+.nf
+
+        setcmap (zscale(i1),"idl15.lut")
+
+.fi
+will save the image with the same intensity scaling and color as would be see
+by displaying it to ximtool using the default DISPLAY task settings,
+normalized XImtool brightness/contrast values and the "idl15.lut" LUT in the
+current directory.
+
+
+.ih
+EXAMPLES
+	The examples below are divided into several categories showing
+typical usage when creating various raw and builtin output files.  Note
+that the output file will have a filename extension added indicating the 
+format when converting to a builtin format.
+
+\fICreating Raw Binary Files\fR
+.nf
+
+List the pixels being one the standard output, apply a linear scale
+function first:
+
+    cl> export dev$pix "" list outbands="bscale(b1,1.0,3.2)"
+
+Convert the dev$pix test image to an 8-bit binary file with a gamma 
+correction, write the standard header:
+
+    cl> export dev$pix bfil raw header+ outty="u1" outbands="gamma(b1,1.8)"
+
+Write the three bands of an IRAF image to a pixel interleaved binary 
+file of short integers, prepend a user-defined header:
+
+    cl> export rgbim bfil raw header="hdr.txt" outty="i2" outban="b1,b2,b3"
+
+Convert three images representing RGB to a 4-color line-interleaved
+file, the IRAF images don't require scaling, create alpha channel:
+
+    cl> export rim,gim,bim bfil raw outty="u1" outban="line(i1,i2,i3,0)"
+
+Write the three bands of an IRAF image to a line-interleaved binary 
+file of short integers:
+
+    cl> export rgbim binfil raw outtype="i2" outbands="line(b1,b2,b3)"
+    cl> export rgbim binfil raw outtype="i2" outbands="" interleave=3
+
+Write the three bands of an IRAF image to a grayscale binary file using 
+a custom conversion formula.  Pixel values are truncated to 8-bits:
+
+    cl> export rgbim grey raw outty="u1" outban="(.2*b1)+(.5*b2)+(.3*b3)"
+
+.fi
+
+\fICreating Specific Formats\fR
+.nf
+
+Convert dev$pix to an 8-bit Sun rasterfile with no colormap, scale the 
+image to 8-bits using the default \fIzscale()\fR intensity mapping:
+
+    cl> export dev$pix dpix ras outbands="zscale(i1)"
+
+Apply various functions to the data before doing the same conversion:
+
+    cl> export dev$pix dpix ras outbands="zscale(log(i1))"
+    cl> export dev$pix dpix ras outbands="zscale(sqrt(i1))"
+
+Convert dev$pix to an 8-bit Sun rasterfile with no colormap, image pixel
+values are truncated to 8-bits:
+
+    cl> export dev$pix dpix ras
+
+Convert three images representing RGB to a 24-bit Sun rasterfile, assume
+the IRAF images don't require intensity scaling:
+
+    cl> export rim,gim,bim rgb ras outbands="i1,i2,i3"
+
+Create a Silicon Graphics RGB format image from a 3-D image:
+
+  cl> export rgbim bdata rgb outbands="b1,b2,b3"
+
+Convert dev$pix to an 8-bit GIF grayscale image, scale the image to map 
+only pixel values between 0 and 320:
+
+  cl> export dev$pix dpix gif outbands="zscale(i1,0.0,320.0)"
+
+Combine three images representing RGB into an 8-bit X11 window dump
+grayscale image:
+
+  cl> export rim,gim,bim gray xwd outbands="gray(i1,i2,i3)"
+
+Convert dev$pix to an Encapsulated PostScript file at half the normal scale 
+and apply a linear transformation to scale the pixel values:
+
+    cl> export dev$pix dpix eps \
+    >>>    outbands="psscale(bscale(i1,0.,0.32), 0.5)"
+
+Convert three images representing RGB to an 8-bit GIF color image with
+a computed colormap:
+
+  cl> export rim,gim,bim rgb gif outbands="cmap(i1,i2,i3)"
+
+Convert dev$pix to a color rasterfile using the builtin "heat" colormap
+and default intensity mapping:
+
+  cl> export dev$pix dpix ras outban='setcmap(zscale(i1),"heat")'
+
+Convert dev$pix to a color rasterfile using the XImtool "idl15.lut" 
+LUT file in the current directory and default intensity mapping:
+
+  cl> copy /usr/local/lib/imtoolcmap/idl15.lut .
+  cl> export dev$pix dpix ras outbands="setcmap(zscale(i1),'idl15.lut')"
+
+
+\fIAdvanced Usage\fR
+
+Given a set of DISPLAY task z1/z2 values of 10 and 320 respectively, and
+brightness/contrast values from XImtool of 0.6 and 1.2 respectively, 
+convert an image to an EPS file with the same appearance:
+
+  im> type expr
+  setcmap ( zscale (i1, 10.0, 320.0), "greyscale", 0.6, 1.2 )
+  im> export dev$pix dpix eps outbands="@expr"
+
+Concatenate two images side-by-side to a PGM file, normalize each image 
+by it's exposure time and apply a default intensity mapping:
+
+  cl> export im1,im2 two pgm \
+  >>>     outbands='(zscale(i1/i1.otime)) // (zscale(i2/i2.otime))'
+
+Convert dev$pix to a color GIF using the XImtool "idl15" LUT with a spec-
+ified brightness/contrast scale.  Map only pixel values between 5 and 300 
+to 201 output intensity values.  This should produce and image identical 
+to what one would get by displaying dev$pix to imtool, setting the same 
+brightness/contrast scale, and selecting the idl15 LUT:
+
+  cl> copy /usr/local/lib/imtoolcmap/idl15.lut .
+  cl> type expr.dat
+	setcmap (
+	    zscale(i1, 5.0, 320.0, 201),
+	    "idl15.lut", 
+	    0.41, 
+	    1.35)
+  cl> export dev$pix dpix gif outbands="@expr.dat"
+
+Combine three images representing RGB to an 8-bit Sun rasterfile with a
+computed colormap.  Scale the intensity value of each image differently.
+
+  cl> type expr.dat
+        cmap (
+            zscale (i1),
+            zscale (i2, 0.0, 1200.0),
+	    zscale (i3, -1.0, 320.0) )
+  cl> export im1,im2,im3 rgb ras outbands="@expr.dat"
+
+Do the same example but apply a gamma correction to the images:
+
+  cl> type expr.dat
+        cmap (
+            gamma (zscale(i1),        2.2),
+            gamma (zscale(i2,0,1200), 2.2),
+	    gamma (zscale(i3,-1,320), 2.2) )
+
+Write four images to a grayscale GIF file such that they are tiled in a 
+2x2 grid:
+
+  cl> export im1,im2,im3,im4 quad gif \
+  >>>        outbands="band( (i1//i2), (i3//i4) )"
+
+Do the same example but create a border of 2 gray pixels around each
+of the images and apply the AIPS0 LUT with brightness/contrast values
+to create a color image:
+
+  cl> copy /usr/local/lib/imtoolcmap/aips0.lut .
+  cl> type expr.dat
+        setcmap (
+            band( 
+                128, 128,
+                (repl (128,2) // i1// repl (128,2) // i2 // repl (128,2)), 
+                128, 128,
+                (repl (128,2) // i3// repl (128,2) // i4 // repl (128,2)),
+                128, 128 ),
+            "aips0.lut",
+            0.54,
+            1.03)
+  cl> export im1,im2,im3,im4 cquad gif outbands="@expr.dat"
+
+.fi
+
+Automatically scale an image ignoring data in a bad pixel mask (bpm), map the
+result to the greyscale part of the "overlay" color map, and apply a
+overlay pattern given by another mask (pattern).
+
+  cl> export dev$pix,bpm,pattern foo gif \
+  >>> outbands = "setcmap(i3==0?(zscalem(i1,i2==0)*200/255.):i3+203,'overlay')"
+
+
+The pattern has values of 1 and 203 is added to get it into the color map
+values of the overlay colors.  The factor of 200/255 is to scale the result
+of zscalem from the range 0-255 to the range 0-200.
+
+.ih
+NOTES
+	This task is new with V2.11.
+
+	(long int headers in RAS and XWD may cause problems on 64-bit 
+machines like the Alpha where host software expects 64-bit values.  Need to
+see if IRAF on the alpha produces 32 or 64-bit longs, either way exchanging
+images may be a problem)
+
+.ih
+BUGS
+	Output of bitmap images is currently not supported.
+.ih
+SEE ALSO
+import, tvmark, imexpr
+.endhelp