diff options
Diffstat (limited to 'pkg/dataio/doc/export.hlp')
| -rw-r--r-- | pkg/dataio/doc/export.hlp | 1066 |
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 |