From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- pkg/dataio/doc/Mtio_notes | 12 + pkg/dataio/doc/Rfits_notes | 85 ++++ pkg/dataio/doc/bintxt.hlp | 28 ++ pkg/dataio/doc/export.hlp | 1066 +++++++++++++++++++++++++++++++++++++++++ pkg/dataio/doc/import.hlp | 631 ++++++++++++++++++++++++ pkg/dataio/doc/mtexamine.hlp | 84 ++++ pkg/dataio/doc/rcardimage.hlp | 120 +++++ pkg/dataio/doc/reblock.hlp | 177 +++++++ pkg/dataio/doc/rfits.hlp | 228 +++++++++ pkg/dataio/doc/rtextimage.hlp | 84 ++++ pkg/dataio/doc/t2d.hlp | 70 +++ pkg/dataio/doc/txtbin.hlp | 28 ++ pkg/dataio/doc/wcardimage.hlp | 74 +++ pkg/dataio/doc/wfits.hlp | 237 +++++++++ pkg/dataio/doc/wtextimage.hlp | 100 ++++ 15 files changed, 3024 insertions(+) create mode 100644 pkg/dataio/doc/Mtio_notes create mode 100644 pkg/dataio/doc/Rfits_notes create mode 100644 pkg/dataio/doc/bintxt.hlp create mode 100644 pkg/dataio/doc/export.hlp create mode 100644 pkg/dataio/doc/import.hlp create mode 100644 pkg/dataio/doc/mtexamine.hlp create mode 100644 pkg/dataio/doc/rcardimage.hlp create mode 100644 pkg/dataio/doc/reblock.hlp create mode 100644 pkg/dataio/doc/rfits.hlp create mode 100644 pkg/dataio/doc/rtextimage.hlp create mode 100644 pkg/dataio/doc/t2d.hlp create mode 100644 pkg/dataio/doc/txtbin.hlp create mode 100644 pkg/dataio/doc/wcardimage.hlp create mode 100644 pkg/dataio/doc/wfits.hlp create mode 100644 pkg/dataio/doc/wtextimage.hlp (limited to 'pkg/dataio/doc') diff --git a/pkg/dataio/doc/Mtio_notes b/pkg/dataio/doc/Mtio_notes new file mode 100644 index 00000000..c5fb2fe5 --- /dev/null +++ b/pkg/dataio/doc/Mtio_notes @@ -0,0 +1,12 @@ + +MTIO mods: + + (1) Install error checking in MTOPEN ("errchk open"). + + (2) Attempt to position to a file beyond EOT for reading should not + cause an error, rather EOF should be returned at the first read, + indicating a zero length file (i.e., EOT). + + (3) ZARDMT should zero-fill to an integral number of chars, provided + space is available at end of buffer (see ZARDBF, which I had to + modify to provide zero-fill). diff --git a/pkg/dataio/doc/Rfits_notes b/pkg/dataio/doc/Rfits_notes new file mode 100644 index 00000000..7df78ca5 --- /dev/null +++ b/pkg/dataio/doc/Rfits_notes @@ -0,0 +1,85 @@ + +Notes on RFITS program. + +General Comments -- + The code is well structured, modular, and the identifiers are well + chosen for the most part, with some exceptions. I liked the file list + technique, and have incorporated it into the card image reader I wrote + to test MTIO. + + On the critical side, the code is not sufficiently well commented. + A few comments explaining the general approach are needed; the use + of the record buffer, the placement of unrecognized keywords in the + image header, and so on are important things that can only be derived + at present by a very detailed analysis of the code. Functionally the + program has some serious limitations as noted below. + + +Detailed Comments -- + +On functionality: + + (1) Keywords BUNIT, BLANK, DATE, DATE_OBS, ORIGIN, CRVALn, CRPIXn, + etc., etc. should all be recognized. Many of these have direct + complements in the image header and it is merely a matter of + mapping the value directly. Without doing so we cannot save + and restore IRAF images in FITS tape form without serious loss + of information. + + Our intention is eventually to map nonstandard FITS keywords + by name into the user fields. A similar table driven mapping + of the standard fields might therefore be desirable. This + would also make the reader more robust and easier to modify to + read nonstandard or future (extended) formats. + + (2) Something should be done about indefinite pixels. It is easy to + check for FITS BLANK value and map into the appropriate INDEF. + This function should be encapsulated in a separate procedure, + because it will have to be modified when we add bad pixel lists + to IMIO. + + (3) BITPIX=32 is not really implemented. Eight bits of precision lost + is too much. Also, SIMPLE='F' should not result in an irrecoverable + abort; a subsequent program may be able to recover the data if it + can at least be read into an imagefile. For similar reasons, it + would be best if it were possible to move pixels to disk without + conversion. Doing everything in real forces binary conversion of + the pixels, as well as causing the loss of precision for type long. + + +On coding: + + (1) Error checking is only partially implemented. As a rule, low level + procedures should "errchk" all subprocedures which perform i/o, so + that the higher level procedures can decide whether or not they want + to catch errors (makes code easier to modify, i.e., to add an error + handler in the future). + + (2) The stack should be unchanged upon exit from a procedure. SALLOC is + used improperly in several places (noted on listing). + + (3) The constants defining the FITS standard should be parameterized in + an include file with comments, or in an external lookup table. I do + not know what GROUPS, PCOUNT, GCOUNT are, and I had to think a bit to + figure out what the 11, 29, etc. were. The exact version of the + standard implemented by the program should be defined all in one + place, so that others can see what version of the standard is + implemented without having to read and understand the whole program, + and to make it easier to modify the program to read future and + nonstandard "FITS" files. Also numbers like "11", "29" etc. are + inherently hard to understand. Even "80" may have to be changed + to read a nonstandard or improperly written format. + + (4) Defined expressions should be enclosed in parenthesis to guarantee + that they are evaluated properly. The definitions of SZB_BIT, + SZ_UBYTE, etc. do not work if enclosed in parenthesis. This is + very tricky; if I were to inherit the program, I would have "fixed" + those definitions at first sight by adding parens, just to be safe, + and then the code would no longer work. Use of integer division + in expressions where the operands of unknown size is bad. + + (5) The "8" in the definition of SZB_BIT is machine dependent. I have + added an NBITS_BYTE definition to iraf.h. Do not let machine + dependence creep into code!! + + (6) I have added WRDSWP and ACHTB_ to the system libraries. diff --git a/pkg/dataio/doc/bintxt.hlp b/pkg/dataio/doc/bintxt.hlp new file mode 100644 index 00000000..5d758ee5 --- /dev/null +++ b/pkg/dataio/doc/bintxt.hlp @@ -0,0 +1,28 @@ +.help bintxt Jun86 dataio +.ih +NAME +bintxt -- Convert binary files containing only text to text files +.ih +USAGE +bintxt binary_file text_file +.ih +PARAMETERS +.ls binary_file +Input file name or template, e.g. "file1" or "file*". +.le +.ls text_file +The output file name. If multiple input files the filenumber will +be concatenated onto the output file name. +.le +.ls verbose = yes +Print messages of actions performed? +.le +.ih +EXAMPLES +1. Convert a binary file on disk to a text file on disk. + + cl> bintxt binary_file text_file +.ih +SEE ALSO +txtbin +.endhelp 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 + + [] +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 ) + 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 '{'
'}' - image headers of above + : + headerN '{'
'}' + 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 diff --git a/pkg/dataio/doc/import.hlp b/pkg/dataio/doc/import.hlp new file mode 100644 index 00000000..da8047b7 --- /dev/null +++ b/pkg/dataio/doc/import.hlp @@ -0,0 +1,631 @@ +.help import Oct94 dataio +.ih +NAME +import -- create an IRAF image from an arbitrary binary file +.ih +USAGE +import binfiles images +.ih +PARAMETERS +.ls binfiles +The list of input binary files to be read. +.le +.ls images +The list of output IRAF images to be written. This parameter only needs to +be specified when generating an output image (see the \fIoutput\fR parameter +description). +.le +.ls format = "sense" +The type of format to be processed. In default mode, i.e. \fIsense\fR, +the format database is searched for a format identifier that evaluates +truly for the current binary file, the input file parameters are then +derived from the database entry. A specific format name in the database may +alternatively be given in which case the input params are derived from that +entry in the database. If \fIformat\fR=\fInone\fR the task parameters +are used to describe the input file. +.le + +.ce +INPUT PARAMETERS +.ls dims = "" +The input file dimension string. This is a space or comma delimited string +containing the length of the file in each dimension, e.g. "512,512,3". +.le +.ls pixtype = "" +Input pixel type. This is a comma delimited string giving the type and size +of each pixel, and an optional tag name to be used in the \fIoutbands\fR +expressions. The syntax for the pixtype entry is +.ls [:tag],[:tag],[....] + +where +.nf + type = b # byte (no conversions) + u # unsigned integer + i # signed integer + r # ieee floating point + n # native floating point + x # ignore (skip) + + nbytes = 1, 2, 4, or 8 + + tag is something like 'r','g','b' (color triplets), 'r', + 'i' (complex data), etc. If no tags are given one will + automatically be assigned of the form 'b1', 'b2', etc. + +.fi +.le +.le +.ls interleave = 0 +Pixel interleave type. If the \fIpixtype\fR parameter is a composite then +the input pixel are pixel-interleaved (i.e. each pixel in a band is stored +together, as with RGB triplets) and this parameter is ignored. If +the \fIpixtype\fR is an atomic value and \fIinterleave\fR is a positive +number the image is line interleaved (e.g. a line of 'R', followed by a +line of 'G', and so on). If the \fIpixtype\fR is atomic and \fIinterleave\fR +is zero, the no data interleaving is assumed and each band in the file +is stored sequentially. +.le +.ls bswap = "no" +Type of byte-swapping to perform. By default no byte swapping is done, +if \fIbswap\fR is "yes" then all input values are byte swapped, if \fIbswap\fR +is "i2" then only short integers are byte swapped, if \fIbswap\fR is "i4" then +only long integers are swapped. A combination of "i2,i4" can be used to +swap only integer values, floating point numbers will not be swapped. +.le +.ls hskip = 0 +Number of bytes preceding pixel data to skip. +.le +.ls tskip = 0 +Number of bytes to skip at end of file. +.le +.ls bskip = 0 +Number of bytes between image bands to skip. +.le +.ls lskip = 0 +Number of bytes to skip at font of each line. +.le +.ls lpad = 0 +Number of bytes to skip at end of each line. +.le + +.ce +OUTPUT PARAMETERS +.ls output = "image" +Type of output to generate. Possible values include "none" process the files +but not generate an output image (e.g. to check the parameter values for +correctness), "image" to generate an output image, "list" to generate a +pixel listing of the file as would be produced by the \fILISTPIX\fR task +on the image if were converted (no image is created with this option), +or "info" to print information about the file. The \fIimages\fR parameter +is only used for \fIoutput\fR=image. +.le +.ls outtype = "" +The data type of the output image. May be one of 's' for a short image, 'i' +for an integer image, 'l' for a long image, 'r' for a real image, and 'd' +for a double precision image. If no \fIouttype\fR is specified then the +datatype of the \fIoutbands\fR expression is used. This parameter is only +used when \fIoutput\fR is set to "image". +.le +.ls outbands = "" +Output image band expressions. If no expressions are given then all of the +input pixels will be converted. The number of output bands may be more or +less than the number of input bands. See the \fIOUTBANDS EXPRESSIONS\fR +section for a more complete description of this parameter. +.le +.ls imheader = "" +Image or header keyword data file. If an image is given then the image header +is copied. If a file is given then the FITS format cards are copied. +This only applies to new images. The data file consists of lines +in FITS format with leading whitespace ignored. A FITS card must begin +with an uppercase/numeric keyword. Lines not beginning with a FITS +keyword such as comments or lower case are ignored. The user keyword +output of \fBimheader\fR is an acceptable data file. See \fBmkheader\fR +for further information. +.le + +.ls database = "imcnv$lib/images.dat" +The format database. This may also be a list of files to be searched (e.g. +so that user-defined databases may be included), which will be treated as +a single database. +.le +.ls verbose = yes +Print verbose output during the conversion? +.le +.ls buffer_size = 64 +Number of image lines \fIper band\fR to buffer in memory before writing to +disk. Image buffering can increase task performance by as much as a factor +of 30 for some formats but requires more memory. +.le + +.ih +DESCRIPTION + + The \fIimport\fR task is used to convert arbitrary raster binary +files to IRAF format images. The input format may be specified either +through the task parameters (\fIformat\fR set to 'none'), or as an entry +in a database of known formats (\fIformat\fR set to the name of the entry). +If the format of the image is not known a priori, the database can be +searched and each record will be evaluated for an expression which +identifies the format (\fIformat\fR set to "sense"). The task will +output either an IRAF image, a list of pixel values +in a manner similar to the \fILISTPIX\fR task, or information about the +file format if it is supported in the database. + +.ih +Input File Specification + The input raster is assumed to be at most three dimensional, with +pixels of various sizes that can be interleaved in a variety of ways. +No compression schemes are yet supported, except in the case of builtin +formats where special code has been written to handle to format. +Byte-swapping and floating point conversion of pixels (from IEEE to +native) is also supported. + + The \fIpixtype\fR and \fIinterleave\fR parameters define the pixel +storage in the binary file. \fIPixtype\fR is a comma delimited string, +the elements of which define the type and size of each pixel. An optional +'tag' name may be given to each pixel for use in the \fIoutbands\fR +expressions. If no tag is given one will automatically be assigned. +For composite pixtypes (i.e. when more than one element is listed), the +data are assumed to be pixel interleaved (e.g. stored as { {RGB}, {RGB} ...} +triplets). For atomic (i.e. single) pixtypes, a positive value of +\fIinterleave\fR indicates that the data are stored in a line-interleaved +manner (e.g. a line of R, a line of G, ...). If \fIinterleave\fR is +zero and \fIpixtype\fR is atomic, then no interleaving is done and the +image bands are thought to be stored sequentially. Minimal error +checking is done to make sure the +combination of these parameters is correct. + + The file may contain arbitrary padding around the pixels as +defined by the \fItskip\fR, \fIbskip\fR, \fIlskip\fR, and \fIlpad\fR +parameters, header information may be skipped by setting the \fIhskip\fR +parameter. Additionally, pixels may be ignored on input while still +specifying the full format. +.ih +Output Parameters + Once a format has been found, the task may output an IRAF image +by setting \fIoutput\fR to "image", a list of the pixels in the file +can be written to STDOUT by setting \fIoutput\fR to "list", or information +about the input file can be printed by setting \fIoutput\fR to "info". +If \fIoutput\fR is set to "none" then no output will be generated, this +can be used to check for read errors on the input file to verify task +parameters. The datatype of the output image can be set by specifying +the \fIouttype\fR parameter. + + The \fIoutbands\fR parameter is a list of expressions which are +evaluated to compute the pixels in each band of the output image. Operands +in these expressions consist of numeric constants and the pixtype tags +(either user-supplied tags or the automatic tags), general arithmetic +expressions are supported, which can include any of the special functions +listed below. The simplest expression is the name of a tag itself. +Regardless of the storage of pixels in the input file, each image band is +separated on output unless an expression is given which combines them. +See below for more details on \fIoutbands\fR. + + Header information may be added to an output image by naming +either a keyword file or an existing image header listing in the +\fIimheader\fR parameter. A header keyword data file consists of lines +of FITS format cards. Leading whitespace is ignored. Lines not recognized +as FITS cards are ignored. A valid FITS card is defined as beginning with +a keyword of up to 8 uppercase, digit, hyphen, or underscore characters. If +less than 8 characters the remaining characters are blanks. The +ninth character may be an equal sign but must be immediately followed +by a blank. Such value cards should be in FITS format though no +attempt is made to enforce this. Any other ninth character is also +acceptable and the line will be treated as a comment. Note that this +way of recognizing FITS parameters excludes the case of comments +in which the first 8 characters are blank. The reason for allowing +leading whitespace and eliminating the blank keyword case is so that +the long output of \fBimheader\fR may be used directly as input. + +.ih +OUTBANDS EXPRESSIONS + + The outbands parameter is a comma delimited list of expressions, the +simplest of which is the name of a tag itself (or the default names of the +tags if none are provided in the \fIpixtype\fR param). +The input pixels, regardless of how they are stored in the binary file, +are always stored as separate bands in the output IRAF image. +The outbands expressions will be evaluated to compute the pixels in each +band of the output image. This means that e.g. RGB triplets in an input +file will be separated into different bands in the output image, unless a +single expression is given that combines them. The components named +in \fIpixtype\fR may be eliminated or re-ordered in \fIoutbands\fR to +exclude certain input bands, or to change the channel order. For example +the commands: + +.nf +cl> import file img pixtype="u1:a,u1:r,u1:g,u1:b" outbands="g,r,a" +cl> import file img pixtype="u1,u1,u1,u1" outbands="b3,b2,b1" +.fi + +both convert an input 32-bit image with ARGB components. In the first case +the output image is an IRAF image where the B component has been eliminated +and the channel order reversed. The second case is the same as the first but +uses the automatic tag names. A combination of user-supplied tags and +defaults could also be used. + + General interpreted arithmetic expressions are supported and can +contain any of the standard expression evaluator functions (see +the \fIimexpr\fR help page for more details). Special functions in +expressions also include: +.nf + + flipx (arg) - flip image in X + flipy (arg) - flip image in Y + gr[ea]y (r,g,b) - RGB to grayscale using the NTSC Y formula + red (arg) - get the red component of a colormap image + green (arg) - get the green component of a colormap image + blue (arg) - get the blue component of a colormap image + gamma (arg, gamma) - apply a gamma correction to the image + +.fi +The two flip functions can change the image orientation by reversing the order +of pixels within a line (a flipx() call), or it can flip an image from top- +to-bottom (a flipy() call). The flipping will apply to all bands of the out- +put image even if it was only used in one expression. To reverse the channel +order simply change the order of the tags in the outbands parameter. RGB +images may be converted to a single grayscale image using the NTSC formula: +.nf + + gray = (0.289 * r) + (0.587 * G) + (0.114 * B) + +.fi +Note that a similar grayscale conversion can be done by explicitly defining +a similar equation in \fIoutbands\fR and supplying different coefficients. + + The \fIred()\fR, \fIgreen()\fR, or \fIblue()\fR functions can be used +to get a single color component from a colormap image rather than the +grayscale equivalent of the colormap. For example, to separate an 8-bit +GIF color image into it's RGB components one could specify an outbands +parameter such as +.nf + +cl> import foo.gif bar format=gif outbands="red(b1),green(b1),blue(b1)" + +.fi + + Functions may also be nested in complex expressions such as: + +.nf + flipy (gray(r,g,b)) - convert to grayscale, flip in Y + flipx (flipy (gray (r,g,b))) - convert to grayscale, flip in X & Y + gray (r,g,255) - use constant 255 as the B band + gray (r,g+100,-b) - add constant to G, negate B +.fi + +.ih +FORMAT DATABASE + + The format database is a text file named as a task parameter. +Each record of a database entry is of the form: + +.nf + : + : + keyword = + keyword = + ...and so on +.fi + +A database record begins with the format name at the beginning of a line. +Whitespace at the beginning of a line is considered the continuation of a +previous line. Comments may be inserted in the database using the normal '#' +character, the remainder of the line is considered a comment. Blank lines +and comments are ignored, a record ends at the next line with a format name +at the beginning of the line. The task \fIdatabase\fR parameter +defines the text files to be +scanned as the database. If the parameter is a list of files then each file +in the list will be concatenated to a single database file used by the task. + + The format_name field is a string identifying each entry in the +database, any number of aliases may also be given to identify the same +format possibly known by another name. Supported keywords include: + +.nf + image_id - A boolean expression identifying the image type + id_string - Verbose name of file format + bswap - is file byte-swapped? (See Below) + dims - a whitespace/comma delimited string of dimensions + pixtype - pixel type, size [and tag], may be a composite + interleave - describes how pixels are stored + hskip - # of bytes of header info to skip + tskip - # of bytes of trailing info to skip at end of file + bskip - # of bytes of info to skip between image bands + lskip - # of bytes of info to skip at front of each line + lpad - # of bytes of info to skip at end of each line + error - A condition that would cause a file read error, + returns a string with the error message, otherwise + returns the string "okay" +.fi + +The 'image_id' string is an expression to be evaluated which, if true, +uniquely identifies the file format (such as a comparison to a "magic number"). +The 'id_string' is a verbose name of the format. +The 'error' keywords use the "? :" conditional syntax to +define a boolean expression which, when true, returns an error message and is +used to indicate a condition in a format which isn't supported. The remaining +keywords have the same meaning as the task parameters. Keywords not present +in the database record will take the default parameter value. + + Expressions consist of any valid string that may be evaluated with the +standard system expression evaluator evvexpr(). (See the documentation for this +procedure or the \fIIMEXPR\fR task help page for details of builtin functions +and operators.) Operators within expressions may be boolean, arithmetic, +or the string operators '?=' (substring equality) and '//' (concatenation). +Operands may be the special functions named below, previously defined +keywords, constants (numeric or strings), and the special operands + +.ls $FSIZE +The size of the binary file in bytes. In expressions this operand has an +integer datatype. For formats with variable header sizes this can be used +to determine the size of the header, since the size of the data can be +derived from the image dimensions and subtracted from the total size of the +file. +.le +.ls $FNAME +The name of the binary file. In expressions this operand has a character +datatype. As a last resort for images without any identifying features the +file name may possibly be used to determine the format from a file name +extension. +.le + + +.ih +Special Functions: + + In addition to the intrinsic functions already provided there are a +number of input and utility functions for the database. These are: +.nf + + \fIINPUT FUNCTIONS\fR + + ctocc ([offset]) - convert byte to printable char constant + ctod ([offset]) - convert string to double precision real + ctoi ([offset]) - convert string to integer + ctol ([offset]) - convert string to long + ctor ([offset]) - convert string to single precision real + ctowrd ([offset]) - get 1st white-space delimited word from str + + getstr ([offset,] len) - get a string at offset + getb ([offset]) - get a byte at offset + getu ([offset]) - get an unsigned short int at offset +geti[24] ([offset]) - get a signed int at offset +getr[48] ([offset]) - get an IEEE fp number at offset +getn[48] ([offset]) - get a native fp number at offset + + locate ([offset,] pat) - find an offset to a pattern + line (n) - offset of line N + + \fIUTILITY FUNCTIONS\fR + + skip (nbytes) - move offset by N-bytes + bswap (arg) - byte swap the argument + substr (str, c1, c2) - extract a substring from argument + stridx (test, str) - get 1st occurrence of 'test' w/in 'str' + +parameter (param) - return the current task parameter + default (param) - return the default task parameter + lsb_host () - returns true if host is little-endian + msb_host () - returns true if host is big-endian +.fi + +.ls ctocc ([offset]) [string] +Convert byte at the given offset to printable char constant. +If no offset argument is given the current offset is used. +.le +.ls ctod ([offset]) [double] +Convert string to double precision real. +The function reads a string from +the file and converts it up to the first unrecognized character. +If no offset argument is given the current offset is used. +.le +.ls ctoi ([offset]) [int] +Convert string to integer. +The function reads a string from +the file and converts it up to the first unrecognized character. +If no offset argument is given the current offset is used. +.le +.ls ctol ([offset]) [long] +Convert string to long. +The function reads a string from +the file and converts it up to the first unrecognized character. +If no offset argument is given the current offset is used. +.le +.ls ctor ([offset]) [real] +Convert string to single precision real. +The function reads a string from +the file and converts it up to the first unrecognized character. +If no offset argument is given the current offset is used. +.le +.ls ctowrd ([offset]) [string] +Get 1st white-space delimited word from str, leading whitespace is skipped. +If no offset argument is given the current offset is used. +.le +.ls getstr ([offset,] len) [string] +Get a string at offset. +If no offset argument is given the current offset is used, the length of +the string must be specified. +.le +.ls getb ([offset]) [int] +Get a byte at offset. +If no offset argument is given the current offset is used. +.le +.ls getu ([offset]) [int] +Get an unsigned short integer at offset. +If no offset argument is given the current offset is used. +.le +.ls geti[24] ([offset]) [int] +Get a signed int at offset. +If no offset argument is given the current offset is used. +Long integers values can be read by specifying the function as geti4(), +the names geti() and geti2() return short integers. +.le +.ls getr[48] ([offset]) [real/double] +Get an IEEE floating point number at an optional offset. +If no offset argument is given the current offset is used. +Double precision values can be read by specifying the function as getr8(), +the names getr() and getr4() return single precision real. +.le +.ls getn[48] ([offset]) [real/double] +Get a native floating point number at an optional offset. +If no offset argument is given the current offset is used. +Double precision values can be read by specifying the function as getn8(), +the names getn() and getn4() return single precision real. +.le +.ls locate ([offset,] pat) [int] +Compute an offset. +If no offset argument is given the current offset is used. +.le +.ls line (N) [int] +Offset of line N in bytes. The database is rewound and the offset of the +requested line number is returned, line are delimited by the '\n' character. +.le +.ls skip (nbytes) [int] +Move current offset by N-bytes. The number of bytes skipped is returned as +the function value. +.le +.ls bswap (arg) [type of arg] +Byte swap the argument. +.le +.ls substr (str, first, last) [string] +Extracts a substring from string \fIstr\fR. The first character in +the string is at index 1. +.le +.ls stridx (test, str) [int] +Finds the position of the first occurrence of any character found +in \fItest\fR in the string \fIstr\fR, returning 0 if the match fails. +.le +.ls parameter (param) [param type] +Return the current task parameter. The parameter is specified as a string +containing the name of a task parameter, the type of the returned value is +the parameter type +.le +.ls default (param) [param type] +Return the default task parameter. The parameter is specified as a string +containing the name of a task parameter, the type of the returned value is +the parameter type +.le +.ls lsb_host () [bool] +Returns true if host is little-endian. +This function can be used as the \fIbswap\fR keyword expression for formats +with a specified byte order. +.le +.ls msb_host () [bool] +Returns true if host is big-endian. +This function can be used as the \fIbswap\fR keyword expression for formats +with a specified byte order. +.le + +.ih +BYTE SWAPPING + + The 'bswap' database entry is similar to the task parameter, it may +be used to set byte swapping for the whole file, or for only certain data +types. The value is a string parameter that may be "yes" to byteswap the +whole file, "no" to not swap anything, or a comma delimited string of types +described below to enable swapping for only those values. +.nf + + bswap = { no | yes | i2 i4 } + + no # no swapping (default) + yes # byte swap whole file + i2 # byte swap short ints only + i4 # byte swap long ints only +.fi + + The \fIbswap\fR task parameter applies only to the pixel data, +but the bswap keyword in a database record sets byte-swapping +for the header information: arguments to the input and conversion functions +will be byteswapped prior to being evaluated by the function. The bswap() +special function can be used to negate byteswapping for a particular +argument if it is or is not set by the keyword (the default is no byte +swapping). + +.ih +EXAMPLES +.nf + +Get a list of known input formats: + + cl> import "" "" output=info + +Get a list of known input formats, including those defined by the user: + + cl> import "" "" output=info database="dev$images.dat,mydb.dat" + +Get a list of the file formats of each image in the directory: + + cl> import file* "" format="sense" output=info verbose- + file1.ras Sun rasterfile + file1.eps unknown format + file1.pgm 8-bit PGM file + : : + +Get a list of the file formats of each image in the directory and +print out some information about each file: + + cl> import file* "" format="sense" output=info verbose+ + file1.ras: Sun Rasterfile + Resolution: 320 x 200 + Pixel type: 8-bit unsigned integer + Pixel storage: non-interleaved + Header length: 137 bytes + Byte swapped: no + ... : + +Read a raw 8-bit file of pixels into an unsigned short IRAF image: + + cl> import file img format="none" dims="512,512" pixtype="b1" \ + >>> outtype="u" outbands="b1" + +Read a JPL VICAR image or 8-bit Sun rasterfile: + + cl> import file img format="vicar" + cl> import file img format="sunras" + +Concatenate three separate red, blue, and green images and convert + to a single grayscale image: + + cl> concat pic.[rgb] > rgb + cl> import rgb img format=none dims="640,480,3" \ + >>> pixtype="u1" interleave=0 outbands="gray(b1,b2,b3)" + +Read an 8-bit colormap GIF image and separate the RGB colors into + separate bands in the output image: + + cl> import file.gif img outbands="red(b1),green(b1),blue(b1)" + +Read three 8-bit rasterfiles with 200 byte-headers as if they were + a single image, and combine the images to a single output band: + + cl> concat pix.* > rfiles + cl> import rfiles img dims="512,512,3" pixtype="b1" \ + >>> hskip=200 bskip=200 interleave=0 outbands="gray(b1,b2,b3)" + +Read a FITS image with one header record in which the data bytes + are incorrectly swapped, but the header info is in the right order: + + cl> rfits nite1.fits "" nite1 + File: nite1 1866-A Size = 640x480 + cl> imheader nite1 l+ > imheader.dat # Save the header info + cl> imdel nite1.imh + cl> import nite1.fits nite1 format="none" dims="640,480" \ + >>> bswap+ hskip=2880 pixtype="i2" outtype="s" imheader="imheader.dat" + +.fi + +.ih +BUGS +Bitmap images are not yet supported. Their most logical use would be as +pixel masks but there hasn't been much call for these formats so they may +be implemented at a later time. +.ih +REVISIONS +.ls IMPORT V2.11 +This is a new task in this version. +.le +.ih +SEE ALSO +export. imexpr, hedit, default image database imcnv$lib/images.dat +.endhelp diff --git a/pkg/dataio/doc/mtexamine.hlp b/pkg/dataio/doc/mtexamine.hlp new file mode 100644 index 00000000..15504254 --- /dev/null +++ b/pkg/dataio/doc/mtexamine.hlp @@ -0,0 +1,84 @@ +.help mtexamine Apr84 dataio +.ih +NAME +mtexamine -- examine the structure of magtape or a single disk file +.ih +USAGE +mtexamine tape_file +.ih +PARAMETERS +.ls tape_file +Tape or disk file, e.g. "mta1600[2]", "mta1600" or "data". +.le +.ls file_list = "1-999" +List of tape file numbers or ranges delimited by commas, e.g. "1-3,5-8". +File_list is used only if no file number is given in tape_file. +Files will be read in ascending order, regardless of the order of the list. +Reading will terminate if EOT is reached, thus a list such as "1-999" +may be used to read all the files on the tape. File_list is ignored is input +is a single disk file. +.le +.ls dump_records = no +Dump selected records? +.le +.ls rec_list = "1-999" +List of tape record numbers or ranges to be dumped delimited by whitespace +or commas e.g "1-3,4". +.le +.ls swapbytes = no +Swap bytes? +.le +.ls byte_chunk = 1 +The number of bytes which are considered as one output element. +The maximum number of bytes permitted in byte_chunk is the number of +bytes in a long integer on the host machine. +.le +.ls output_format = "o" +Permitted types are character(c), octal(o), hexadecimal (x), decimal (d) +or unsigned decimal (u). Character dumps are only permitted for byte_chunk = 1. +Unless decimal format is specified, the data are dumped as +unsigned integers. +.le +.ih +DESCRIPTION +By default mtexamine determines the record structure of all files +on a magnetic tape or a single disk file. +Selected files can be dumped by setting the file_list parameter. +Selected records can be dumped by setting the dump_record switch +and entering a record list. The user can select the byte chunk +and the output format for the dump. + +Mtexamine can also be used to dump a single disk file. However the concept +of a block is not well defined for disk files. Mtexamine defines a block +to be one IRAF file io block which is usually some multiple of the machine +block size. +.ih +EXAMPLES +1. Determine the record structure of a magnetic tape and send the result to +the file tapedump. + +.nf + cl> mtexamine mtb1600 > tapedump +.fi + +2. Dump the third tape file in octal bytes on the standard output. + +.nf + cl> mtexamine mtb1600[3] du+ +.fi + +3. Dump the contents of the fifth record of the third tape file in ASCII +characters on the standard output. + +.nf + cl> mtexamine mtb1600[3] du+ re=5 ou=c +.fi +.ih +BUGS +The IRAF magtape i/o routines do not permit data beyond a double EOF +to be accessed. Therefore mtexamine cannot be used to examine tapes with +embedded double EOFs. +.ih +SEE ALSO +rewind, allocate +.endhelp diff --git a/pkg/dataio/doc/rcardimage.hlp b/pkg/dataio/doc/rcardimage.hlp new file mode 100644 index 00000000..910cfc72 --- /dev/null +++ b/pkg/dataio/doc/rcardimage.hlp @@ -0,0 +1,120 @@ +.help rcardimage Jan87 dataio +.ih +NAME +rcardimage -- Convert a card image file into an IRAF text file +.ih +USAGE +rcardimage cardfile file_list textfile +.ih +PARAMETERS +.ls cardfile +The cardimage source file. Cardfile may be either a template specifying a +list of disk files, e.g. card* or a mag tape file specification of the +form mtl*[n], where mt stands for mag tape, l stands for a specific drive, +* stands for the density and [n] is the tape file number. If no tape file +number is specified then the tape file numbers are taken from the +file_list parameter. +.le +.ls file_list +A list of tape file +numbers or ranges delimited by commas, for example +"1,3,5-8", which is used only if the magtape device is specified. +Files will be read in ascending order, regardless of +the ordering of the list. Reading will terminate silently if EOT +is reached, thus a list such as "1-999" may be used to read all +files on a tape. +.le +.ls textfile +Name of the output file. If multiple input files, multiple output +files will be generated by concatenating the tape file number or +disk sequence number onto the textfile string. +.le +.ls card_length = 80 +The number of columns per card in the input card image file. +Must be divisible by the number of bytes per "IRAF character" (2 on most +machines). The task reblock can be used to pad files with odd-sized +cards. +.le +.ls max_line_length = 161 +The maximum line length to be generated. Default is maximum size +of a line permitted by IRAF. +Useful for stripping columns 73-80 from Fortran card image files. +.le +.ls entab = yes +Replace blanks with tabs and blanks. Tabsize is 8. +.le +.ls join = no +Rejoin oversize lines. +.le +.ls contn_string = ">>" +Marker to enable program to recognize oversize lines. +.le +.ls trim = yes +Trim trailing whitespace from each line. +.le +.ls verbose = yes +Output messages listing files created, number of cards +processed, etc. +.le +.ls ebcdic = no +Translate from ebcdic to ascii. +.le +.ls ibm = no +Translate from ibm ebcdic to ascii. +.le +.ls offset = 0 +Integer parameter specifying the tape file number offset. For example if +offset = 100, card_file = "card" and file_list = "1-3", the output file +names will be "card101", "card102" and "card103" respectively, instead of +"card001", "card002" and "card003". +.le + +.ih +DESCRIPTION +Multiple cardimage files are read from disk or tape. +If only the magtape device is specified, +a list of file numbers is requested. In the latter case, output files +have the form root_filename // tape(disk)_file_number. By default, trailing +whitespace is trimmed from each line. + +.ih +EXAMPLES +1. Convert a set of ASCII cardimage files on magnetic tape to IRAF text files, +replacing blanks with tabs and blanks, and trimming whitespace from +the ends of lines. + + cl> rcardimage mtb1600 1-999 textfiles + +2. Convert a set of ASCII cardimage files on disk to IRAF test files. + + cl> rcard card* 1 textfiles + +3. Convert a set of EBCDIC cardimage files on magnetic tape to IRAF text files, +trimming whitespace from the ends of lines but leaving embedded blanks +unchanged. + + cl> rcardimage mtb1600 1-999 textfile en- ebc+ + +4. Convert an odd-blocked (81 bytes per card) rcardimage file on tape to an +IRAF text file by using reblock to write the file to disk and pad the cards +with blanks, followed by rcardimage to convert the file to an IRAF textfile. + + cl> reblock mta[1] cardimage inrecord=81 outrecord=82 \ + padchar=" " + + cl> rcardimage cardimage 1 textfile card_length=82 + +.ih +BUGS +Due to portability considerations The card length in bytes must fill an +integral number of IRAF characters. On most machines this means that the +length of the card must be an even number of bytes . The task should be +generalized to require only that the tape record length be specified +to read odd blocked card image files. + +The size of the output text file lines is currently restricted to 161 +or fewer characters. +.ih +SEE ALSO +wcardimage +.endhelp diff --git a/pkg/dataio/doc/reblock.hlp b/pkg/dataio/doc/reblock.hlp new file mode 100644 index 00000000..dd3a506a --- /dev/null +++ b/pkg/dataio/doc/reblock.hlp @@ -0,0 +1,177 @@ +.help reblock Jan93 dataio +.ih +NAME +reblock -- copy a file to tape or disk with optional reblocking +.ih +USAGE +reblock infiles outfiles file_list +.ih +PARAMETERS +.ls infiles +The input file list or device name, e.g. "mta1600[2]" or "mta800", "file1", +"file1,file2", or "@infiles". +.le +.ls outfiles +The list of output files or device name, e.g. "gemini!mtb", "out1", +"out1,out2", or "@outfiles". +If multiple file output to disk is requested, and the specified number +of output files is 1, the output file names will be generated +by concatenating the tape file number (the input files are on tape) or +a sequence number (the input files are on disk) onto the output file +name. +.le +.ls file_list +List of tape file numbers or ranges delimited by commas, +e.g. "1-3,5_8". +File_list is requested only if the magtape input device is specified. +Files will be read in ascending order regardless of the ordering of the list. +Reading will terminate silently if EOT is reached, thus a list such as +"1-999" may be used to read all files on the tape. +.le +.ls newtape +If the output device is magtape, newtape specifies whether the tape is +blank or contains data. +Newtape is requested only if no tape file number is specified, e.g. "mta1600". +.le +.ls outblock = INDEF +Size of the output block bytes. +In the default case and for disk output, the output block size is set to the +file i/o disk default buffer size. +.le +.ls inrecord = INDEF, outrecord = INDEF +The sizes of the input and output logical records in bytes. +The default input and output record sizes are set equal to +the input and output block sizes respectively. If inrecord > outrecord, +records are trimmed; if inrecord < outrecord, records are padded; if +inrecord = outrecord, records are simply counted. If only one of inrecord or +outrecord is set, the undefined parameter defaults to the value of the +other. +.le +.ls skipn = 0 +The number of input blocks (tape input) or records (disk input, size inrecord) +to be skipped. +.le +.ls copyn = INDEF +The number of input blocks (tape input) or records +(disk input, size inrecord) to be copied. Copyn defaults to a very large number. +.le +.ls byteswap = no +Swap every other byte. For example if byteswap is enabled, bytes 1 2 3 4 5 6 +would become bytes 2 1 4 3 6 5 on output. +.le +.ls wordswap = no +Swap every 4 bytes. For example if byteswap is enabled, bytes 1 2 3 4 5 6 7 8 +would become 4 3 2 1 8 7 6 5 on output. +.le +.ls pad_block = no +If pad_block is set, reblock pads trailing blocks until they are outblock +bytes long, otherwise trailing blocks may be short. +.le +.ls padchar = 0 +Single character used to pad blocks or records. +Padchar is only requested if pad_record or pad_block +is set. If padchar equals one of the digits 0 through nine, records and +blocks are padded with the face value of the character, otherwise the +ASCII value is used. +.le +.ls offset = 0 +The number which added to the tape file number is appended to \fIoutfiles\fR +to produce the output file name. For example if file_list = "1-3", outfiles = +"out" and offset = 100, the three files out101, out102, out103 would +be produced rather than out001, out002 and out003. +.le +.ls verbose = yes +Print messages about files, blocks copied etc. +.le +.ih +DESCRIPTION +REBLOCK is a procedure to copy disk or tape resident files to +disk or tape. Multiple input tape or disk files may be specified. +If multiple files are output to disk, and only one output file name is +specified, the output file names will be +generated by concatenating the tape file number (the input files are on tape) +or a sequence number (the input files are on disk) onto the output file name. +The user may request magnetic tape output to begin at a specific file on +tape, e.g. mta1600[5] in which case file five will be overwritten if it +exists, or at BOT or EOT. If no file number is specified REBLOCK asks +whether the tape is new or old and begin writing at BOT or EOT as +appropriate. + +Before beginning the copy, the user may request reblock to skip +n (default 0) blocks (tape input) or logical records (disk input). +The user can also specify that +only n (default all) blocks (tape input) or records (disk input) +are to be copied. Before the copy the data may be optionally word-swapped +(default no) and/or byte-swapped (default no). If verbose is specified +(default yes) reblock prints the input and output file names, +the number of blocks read and written and the number of records read and +written. + +Reblock +uses the default buffer sizes supplied by mtio and file i/o to determine the +maximum number of bytes which can be read in a single read call. For tapes +this corresponds to the maximum number of bytes per block permitted by the +device. Mtio will not read more than one block per read call. Therefore the +actual number of bytes read will be less than or equal to the mtio buffer size. +For disk files the default buffer size set by IRAF is a multiple of the +disk block size. If the disk file is smaller than one block +or the last block is partially full, the number of bytes read +will be less than the default buffer size. All magtape and disk reads are +done with the file i/o read procedure and a call to fstati determines the number +of bytes actually read. + +If all the defaults are set, a binary copy is performed. +In tape to tape copies the block and record sizes are preserved, +but the density may +be changed by specifying the appropriate output file name e.g. mta800 or +mta1600. +Reblocking occurs in tape to disk transfers, if records, are trimmed, +padded or counted, or if blocks are padded. +If a disk to tape transfer is requested +the output block size will be the default file i/o buffer size. +The last block in a file may be short. If uniform sized blocks are +desired, pad_block must be set, in which case trailing partially filled +blocks will be padded with padchar. + +Logical records are distinguished from blocks (physical records). +The input and output record sizes default to +the size of the input and output blocks respectively. +Logical records may be shorter or longer than the block sizes. + +.ih +EXAMPLES +1. Copy a magnetic tape preserving the record sizes but changing +the density from 800 bpi to 1600 bpi. + +.nf + cl> reblock mtb800 mta1600[1] 1-999 +.fi + +2. Reblock a magnetic tape changing the block size from 4000 bytes to 8000 +bytes and padding the last block. + +.nf + cl> reblock mtb1600 mta1600[1] 1-999 outb=8000 padb+ +.fi + +3. Copy a series of disk fits files to tape + +.nf + cl> reblock @fitsfiles mta[1] outb=28800 +.fi + +4. Trim the records of a disk file. + +.nf + cl> reblock infile outfile inrec=80 outrec=72 +.fi + +5. Pad the records of a disk file with blanks. + +.nf + cl> reblock input output inrec=81 outrec=82 padchar=" " +.fi +.ih +SEE ALSO +t2d +.endhelp diff --git a/pkg/dataio/doc/rfits.hlp b/pkg/dataio/doc/rfits.hlp new file mode 100644 index 00000000..d28690c1 --- /dev/null +++ b/pkg/dataio/doc/rfits.hlp @@ -0,0 +1,228 @@ +.help rfits May97 dataio +.ih +NAME +rfits -- convert image data in FITS files to individual IRAF images +.ih +USAGE +rfits fits_file file_list iraf_file +.ih +PARAMETERS +.ls fits_file +The FITS data source. Fits_file is either a list of disk files or a tape +device specification of the form mt[*][n], where mt is the mag tape +device (e.g. mta), * is an optional density (e.g. 1600), and [n] is an +optional tape file number. If n is specified then only image data in the +nth tape file is read. +.le +.ls file_list +The list of FITS extensions to be read from each disk file or from a single +tape file, or the list of tape files AND FITS extensions to be read from +an entire tape. FITS extensions are numbered from 0 to n, tape files are +numbered from 1 to n. If file_list is "", only the 0th extension is read +from each disk file or from a single tape file, but all the files and +extensions are read from an entire tape. Legal file lists are composed +of a series of file numbers and / or file ranges separated by commas +or whitespace. For example the string + + "1-3,4-8" + +will convert ALL the FITS extensions in files 1 through 8 on tape, +but only FITS extensions 1 through 8 from a disk file or a single tape file. +For the case of disk input, the same FITS extensions must be read from +each input file. For the case of tape input the FITS extensions to be +read from each file must be specified separately. For example the following +string + + "1-10[2-4],15-21[1-10]" + +tells rfits to convert extensions 2 through 4 in tape files 1 through 10 +and extensions 1 through 10 in tape files 15 through 21. Rfits will only +convert extensions which contain image data. Other types of fits data +such as tables will not be converted. +.le +.ls iraf_file +The IRAF file which will receive the FITS image data if the make_image parameter +switch is set. Iraf_file may be a template of output image names or +a single root output image name. In the former case one output image name +must be specified for every input file. In the latter case iraf_file is +a root output image name to which the input file sequence number or tape +file number is appended if the number of input files > 1. For example +reading files 1 and 3 from a FITS tape with a value of iraf_file of "data" +will produce the files data0001 and data0003, whereas reading the same +two files with a value of iraf_file of "data1,data2" will produce the files +data1 and data2. Extension numbers will be appended to the root output +names if appropriate. +.le +.ls make_image = yes +If make_images is "yes" convert the FITS image data to IRAF image data, +otherwise simply print the header information using the long_header or +short_header switches. +.le +.ls long_header = no +If long_header is "yes" the full FITS header is printed on the standard output. +.le +.ls short_header = yes +If short_header is "yes" and long_header is "no", only the output filename, +the title string, and the image dimensions are printed on the standard output. +.le +.ls datatype +The output image data type. Datatype may be s (short integer), i (integer), +u (unsigned integer), l (long integer), r (real), or d (double). Data +truncation may occur if an inappropriate data type is specified. If an +unsupported data type or a null string is supplied then a default data +type is selected based on the value of the fits bitpix, bscale, and bzero +parameters. If the bscale and bzero parameters in the FITS header are +undefined or equal to 1.0 and 0.0 respectively, rfits selects datatype +s or l depending on bitpix. If bscale and bzero are set to 1.0 and 32768.0, +rfits selects datatype, otherwise rfits selects datatype r. +.le +.ls blank = 0. +The IRAF image value assigned to a FITS blank pixel. +.le +.ls scale = yes +If scale is "no" then the data values are read directly from the FITS image +without conversion. Otherwise rfits scales the data before output using +the values of bscale and bzero. +.le +.ls oldirafname = no +If the oldirafname switch is set rfits will attempt to restore the image to +disk with the filename defined by the IRAFNAME parameter in the FITS header. +.le +.ls offset = 0 +An integer parameter specifying the offset to the current tape file +number. For example if offset = 100, iraf_file = "fits" and file_list = "1-3" +then the output file names will be "fits0101", "fits0102" and "fits0103" +respectively rather than "fits0001", "fits0002" and "fits0003". +.le +.ih +DESCRIPTION +FITS data is read from the specified source; either disk or +magnetic tape. The FITS header may optionally be printed on the standard +output as either a full listing or a short description. +The FITS long blocks option is supported. + +At present non-standard FITS files (SIMPLE = F) and files containing +group data are skipped and a warning message is issued. +Image stored in the FITS standard extension IMAGE can be read. +Other standard extensions such as TABLE and BINTABLE are currently ignored. + +A warning message will be issued if the default user area allocated in +memory is too small +to hold all the FITS parameter cards being read in by RFITS. +Since the default user area is 64000 +characters and a single card image is 81 characters long, the normal +user area will hold ~800 complete card images. RFITS will not permit +partial cards to be written. The user can override the default user area +length by setting the environment variable min_lenuserarea (see example +below). +.ih +EXAMPLES +1. Convert all the image data on a mag tape to individual IRAF +images. Allow rfits to select the output datatype and set blanks +to zero. + +.nf + cl> rfits mtb1600 "" images + + or alternatively + + cl> rfits mtb1600 * images +.fi + +2. Convert FITS files on disk to IRAF images. In the first example case the +files specified by fits* are written to images images0001, images0002, etc. +In the second example the fits disk files listed one per line in the text +file fitslist are written to the output images listed one per line in +the file imlist. Note that by using 0 or "" for the file_list parameter +the user has told rfits to read only the primary fits data unit. + +.nf + cl> rfits fits* "" images + + or alternatively + + cl> rfits fits* 0 images + + + cl> rfits @fitslist "" @imlist + + or alternatively + + cl> rfits @fitslist 0 @imlist +.fi + +3. List the contents of a FITS tape on the standard output without creating +any image files. + +.nf + cl> rfits mtb1600 "" images ma- +.fi + +4. Convert FITS files on tape directly to IRAF images without scaling. + +.nf + cl> rfits mtb1600 "" images scal- +.fi + +5. Convert the first three FITS files on tape to IRAF image converting FITS +blank values to -1 in the process. Note that the user will not get what +he or she expects if the output data type is ushort. + +.nf + cl> rfits mta 1-3 images blank=-1 +.fi + +6. Read in a disk FITS file with a header roughly twice the usual IRAF length +of 64000 characters. + +.nf + cl> set min_lenuserarea = 128000 + cl> rfits fitsimage "" image +.fi + +7. Read a FITS tape which has 5 normal fits records (2880 bytes) to a tape +record. Notice that no hidden rfits parameters are required to do this. + +.nf + cl> rfits mta * images +.fi + +8. Convert only the zeroth FITS extension in each of the first 100 files on a +magnetic tape and try to restore the original IRAF image name in the process. + +.nf + cl> rfits mta 1-100[0] images old+ +.fi + +9. Convert the second, third, and fourth FITS extensions in the first 100 +files of a FITS tape and try to restore the original IRAF name in the process. + +.nf + cl> rfits mta "1-100[2-4]" images old+ +.fi + +10. Convert the second, third, and fourth FITS extensions in each of a list of +disk files and restore the original IRAF name in the process. + +.nf + cl> rfits @fitslist "2-4" images old+ +.fi + +11. Convert the second, third, and fourth FITS extensions in the fifth +mag tape file and try to restore the original IRAF name in the process. + +.nf + cl> rfits mta[5] "2-4" images old+ +.fi + +.ih +BUGS +Blank pixels are counted and set to a user determined value, but they are not +records in the output image header. + +Rfits can read image data only. Other FITS data types such as ASCII and +binary tables are skipped. +.ih +SEE ALSO +wfits, reblock, t2d, fits kernel +.endhelp diff --git a/pkg/dataio/doc/rtextimage.hlp b/pkg/dataio/doc/rtextimage.hlp new file mode 100644 index 00000000..f6b8f037 --- /dev/null +++ b/pkg/dataio/doc/rtextimage.hlp @@ -0,0 +1,84 @@ +.help rtextimage Oct93 dataio +.ih +NAME +rtextimage -- convert a text file to an IRAF image +.ih +USAGE +rtextimage input output +.ih +PARAMETERS +.ls input +A list of text files containing image pixels and optional header. Most likely +the output from \fIrcardimage\fR, see examples below. +.le +.ls output +The output IRAF image name. If more than one text file is being +read, the ordinal of the text file in \fBinput\fR +is appended to \fIoutput\fR to generate a unique image name. +.le +.ls otype = "" +The data type of the output IRAF image pixels. If left unset and the IRAFTYPE +keyword is found in the FITS header, output pixels will be of type IRAFTYPE. +If IRAFTYPE appears more than once in the FITS header, the last value of +IRAFTYPE is used. If left unset and the IRAFTYPE keyword is not provided in +the FITS header, the output data type is determined from the pixels themselves. +.le +.ls header = yes +If \fBheader\fR = yes, \fIrtextimage\fR will attempt to read a FITS +header at the beginning of each text file. +.le +.ls pixels = yes +Read the pixel values from the input text file. If no then the +output image is initialized to zero pixel values. +.le +.ls nskip = 0 +The number of lines to skip before reading pixels. This is used to +skip over a non-standard header and is important only when \fBheader\fR = no. +.le +.ls dim = "" +A string listing the dimension of each axis. The number of dimensions listed +equals the number of image dimensions. This information must be entered unless +it can be read from a FITS header. +.le +.ih +DESCRIPTION +Text files are converted to IRAF images files with procedure +\fBrtextimage\fR. The text file consists of an optional header optionally +followed by the pixel values. If no pixel values are read the image is +initialized to all zero pixel values. If pixel values a given they are +read in FITS order, that is, the leftmost subscript varies most rapidly. +The number of image dimensions and the length of each dimension must either +be read from a FITS header or supplied by the user. Internally, +\fBrtextimage\fR determines the format (integer or floating point) of the +pixels in the text file by reading the first one and assuming all others +are the same. +.ih +EXAMPLES +1. Read a file written by \fIwtextimage\fR from the magtape file "mta[1]" into +the IRAF image "picture". + + cl> rcard mta[1] | rtext out=picture + +2. Read a series of text files with no headers preceding the pixels. The +text files were previously read from tape with task \fBrcardimage\fR. +The two dimensional images are 512 by 320 pixels, and will be named +crab001, crab002, crab003, etc. + + cl> rtext text.* crab header- dim=512,320 + + +3. Read a file with a non-standard header. The header is 5 cardimages long. + + cl> rcard mta[5] | rtext out=spect.1 head- nskip=5 dim=1024 +.ih +TIME REQUIREMENTS +Task \fIrtextimage\fR requires about 145 cpu seconds to write a 512 square +image (integer or real) from a text file. +.ih +BUGS +The text file being read cannot have lines longer than SZ_LINE characters +(see hlib$iraf.h). +.ih +SEE ALSO +rcardimage, wtextimage +.endhelp diff --git a/pkg/dataio/doc/t2d.hlp b/pkg/dataio/doc/t2d.hlp new file mode 100644 index 00000000..5d36334c --- /dev/null +++ b/pkg/dataio/doc/t2d.hlp @@ -0,0 +1,70 @@ +.help t2d May89 dataio +.ih +NAME +t2d -- copy files from tape to disk quickly +.ih +USAGE +t2d input ofroot +.ih +PARAMETERS +.ls input +Tape file or device name, e.g. "mta1600[1]" or "mta" +.le +.ls files +List of tape file numbers or ranges delimited by commas, e.g. "1-3,5-8". +`Files' is requested only if no file number is given in `input'. +Files will be read in ascending order, regardless of the order of the list. +Reading will terminate if EOT is reached, thus a list such as "1-999" +may be used to read all the files on the tape. +.le +.ls ofroot +Root name to give output files. A three digit sequence number will be appended +to this root name for each file written if a file list is used. If the file +number is specifically given in the 'input' parameter, the output file will +be named this root without an appended sequence number. +.le +.ls verbose = yes +Flag to signal program that it should produce verbose output. This means +progress reports. +.le +.ls errignore = yes +Flag to signal program that tape records that give read errors should be +considered to have zero length. If set to 'no', error records are considered +to be the same length as all the other records on the tape. +.le +.ih +DESCRIPTION +T2d reads files from tape and puts them into disk files. No formatting is +performed so the bits and bytes are in the same order on disk as they were +on tape. The program uses double buffering and asynchronous i/o to speed +things up as much as possible. + +When read errors are encountered one of two things can happen. Depending +on the value of the parameter 'errignore', the error record is either +thrown out or considered valid data. If 'errignore' is 'no' when an error +is found, the input buffer is validated to the most recent 'good record' +length and written to disk. If 'errignore' is 'yes' when an error is +found, the input buffer is disposed of for that record. +.ih +EXAMPLES +1. To read the second image from mta at 1600 bpi, store the image into +"image" and see verbose output the command would be: + +.nf + cl> t2d mta1600[2] image +.fi + +2. To read all the files on mtb at the default speed of 1600 bpi and put +the disk files in root001, root002, root003, etc. and turn off verbose +output, the command would be: + +.nf + cl> t2d mtb root v- +.fi + +The program will prompt the user and ask for the list of files to be read +to which the response would be "1-999". +.ih +SEE ALSO +reblock +.endhelp diff --git a/pkg/dataio/doc/txtbin.hlp b/pkg/dataio/doc/txtbin.hlp new file mode 100644 index 00000000..c519125f --- /dev/null +++ b/pkg/dataio/doc/txtbin.hlp @@ -0,0 +1,28 @@ +.help txtbin Jun86 dataio +.ih +NAME +txtbin -- convert text files to binary files +.ih +USAGE +txtbin text_file binary_file +.ih +PARAMETERS +.ls text_file +Input file name or template, e.g. "abc" or "abc.*". +.le +.ls binary_file +Output file name. If multiple input files the file_number will be +added to the output file name. +.le +.ls verbose = "yes" +Print messages about files processed? +.le +.ih +EXAMPLES +1. Convert a text file on disk to a binary file on disk. + + cl> txtbin text_file binary_file +.ih +SEE ALSO +bintxt +.endhelp diff --git a/pkg/dataio/doc/wcardimage.hlp b/pkg/dataio/doc/wcardimage.hlp new file mode 100644 index 00000000..650f78ed --- /dev/null +++ b/pkg/dataio/doc/wcardimage.hlp @@ -0,0 +1,74 @@ +.help wcardimage Jun86 dataio +.ih +NAME +wcardimage -- convert IRAF text files to card image files +.ih +USAGE +wcardimage infiles outfiles +.ih +PARAMETERS +.ls textfile +A character string identifying the file (s) on disk to be processed. +The string acts as a "template" so that multiple files can be pro- +cessed. +.le +.ls cardfile +Name of the output tape device of the form "mta800" or "mta800[#]" +or name of disk file (s). EOT and BOT are acceptable tape file numbers. +The file number will be appended to +the output file name in the case of multiple file disk output. +.le +.ls new_tape +Specifies whether the output tape is blank or contains data. +.le +.ls contn_string = ">>" +Character string which will be inserted at the beginning of +card image lines which have been split from a single text line. +.le +.ls verbose = yes +Print messages of actions performed? +.le +.ls detab = yes +Remove tabs? +.le +.ls card_length = 80 +Number of columns per card. +.le +.ls cards_per_blk = 50 +Number of card images per physical record. +.le +.ls ebcdic = no +Translate ascii characters to ebcdic? +.le +.ls ibm = no +Translate ascii characters to ibm ebcdic? +.le +.ih +DESCRIPTION +If multiple file disk output is requested, ".crd" is appended to the input +file name. Oversize lines are split and prefixed by the string ">>". +.ih +EXAMPLES +1. Convert a set of IRAF text files to a set of blocked ASCII cardimage files +on tape, replacing tabs with blanks and prefixing the leftover portions +of oversize lines with ">>". + +.nf + + cl> wcardimage files* mtb1600[1] +.fi + +2. Convert a set of IRAF text files to a set of blocked EBCDIC cardimage files +on tape, replacing tabs with blanks and prefixing the leftover portions +of oversize lines with ">>". + + cl> wcardimage files* mtb1600[1] eb+ +.ih +BUGS +The card_length in bytes must be an integral number of chars. +At present WCARDIMAGE can only handle lines with less than or equal to +161 characters. +.ih +SEE ALSO +rcardimage +.endhelp diff --git a/pkg/dataio/doc/wfits.hlp b/pkg/dataio/doc/wfits.hlp new file mode 100644 index 00000000..67d6f3c3 --- /dev/null +++ b/pkg/dataio/doc/wfits.hlp @@ -0,0 +1,237 @@ +.help wfits May97 dataio +.ih +NAME +wfits -- convert individual IRAF image files to FITS image data +.ih +USAGE +wfits iraf_files fits_files +.ih +PARAMETERS +.ls iraf_files +The input IRAF image file(s), e.g. "image.imh" or "*.imh". +.le +.ls fits_files +The output FITS files. +Magnetic tape output is assumed if the first two characters of fits_files +are "mt", otherwise the disk output is assumed. Tape output will begin +at the file number specified in fits_files, e.g. file 5 if fits_files = +"mtb1600[5]", and the data in file 5 and succeeding files will be overwritten. +If no tape file number is specified in fits_files, the newtape parameter +is queried, and tape output will begin at BOT (beginning of tape) if +newtape = yes, otherwise at EOT (end of tape, after the double EOF). +Requesting a tape write at EOT on a blank tape may cause tape runaway. +In the case of disk output, fits_files may be either a file name template +or a root filename. In the former case there must be one output FITS file +name for every input image. In the latter case fits_files is a root name +and a sequence number will be appended to fits_files if the number of +input images > 1. +.le +.ls newtape +Boolean parameter specifying whether an output tape is blank or already +contains data. Newtape is requested only if no tape file number is specified in +fits_files, e.g. fits_files = "mtb1600". +.le +.ls bscale +The FITS bscale parameter, defined as p = i * bscale + bzero, where +p and i are the physical and tape data values respectively. +The bscale parameter is only requested if the scale switch is on +and the autoscale switch is off. +.le +.ls bzero +The FITS bzero parameter (see bscale for a definition). +Bzero is only requested if the scale switch is on and the autoscale +switch is off. +.le +.ls fextn = "fits" +The output fits file extension. If fextn is defined, an extension of +the form ".fextn", e.g. ".fits" is added to the output fits file name. +Fextn should be chosen to be compatible with one of the permitted fits +kernel extensions. +.le +.ls extensions = no +By default wfits writes each input image to a separate disk or tape FITS +file. If \fIextensions\fR is "yes", then wfits will write all the images in +the input image list to a single disk or tape FITS file using the FITS +standard IMAGE extension to write images other than the first. Extension +numbering is 0 indexed. The first image will be written to extension 1 if +\fIglobal_header\fR is "yes", or to extension 0 if \fIglobal_hdr\fR is "no". +.le +.ls global_hdr = yes +Write a short global header to the 0th extension of the output FITS file +if \fIextensions\fR is "yes". +.le +.ls make_image = yes +By default wfits writes the FITS image(s) to the output destination. +If the make_image switch is turned off, wfits prints the FITS headers +on the standard output and no output file is created. In this way the +output FITS headers can be examined before actually writing a FITS tape. +.le +.ls long_header = no +If this switch is set the full FITS header will be printed on the standard +output for each IRAF image converted. +.le +.ls short_header = yes +If this switch is set only a short header, listing the files processed and +their dimensions will be printed on the standard output. +The long_header switch must be turned off. +.le +.ls bitpix = 0 +A bitpix of 8, 16, or 32 will produce either an unsigned byte, +twos-complement 16 bit integer, or twos-complement 32 bit integer FITS +image. If bitpix is -32 or +-64 IEEE real or double precision floating point FITS images are produced. +If bitpix is set to 0 (the default), wfits will choose one of 8, +16, 32, -32 or -64 based on the data type of the IRAF image. +For example a short integer and real image will default to bitpix 16 and +-32 respectively. +Users should be wary or overriding the default value of bitpix as loss +of precision in their data may result. In this case wfits will issue a +warning message and an estimate of the maximum loss of precision to be +expected. +.le +.ls blocking_factor = 0 +The tape blocking factor for FITS. +Wfits normally writes \fIblocking_factor\fR * 2880 byte records, +where \fIblocking_factor\fR is an integer from 1 to 10. +If \fIblocking_factor\fR = 0, wfits uses the default FITS blocking +factor specified for the device by the "fb" parameter in the +file dev$tapecap, or 1 if the "fb" parameter is not present. For +devices which support variable block sizes, e.g. 9-track tapes, exabytes +and dats, "fb" is normally set to 10. +The user may override this value by setting \fIblocking_factor\fR +>= 1 or <= 10. If the device does not support variable block sizes, e.g. +various types of cartridge drives, blocks of the size defined for the +device by the "bs" parameter in the dev$tapecap file are written +and \fIblocking_factor\fR is ignored. +.le +.ls scale = yes +If the scale switch is set, the IRAF image will be scaled before output. +Two types of scaling are available. The scaling parameters bscale and +bzero may be entered by the user (autoscale = no), or the program can +calculate the appropriate bscale and bzero factors (autoscale = yes). +If the scale switch is turned off, the IRAF image data is converted +directly to integers of the specified bitpix with possible loss of +precision. +.le +.ls autoscale = yes +If the autoscale switch is set, wfits calculates the appropriate bscale and +bzero factors based on the IRAF image data type, and the maximum and minimum +values of the data. +.le +.ih +DESCRIPTION +IRAF data is read from disk and written to the specified destination, +either disk or magnetic tape. The FITS header may optionally be printed +on the standard output as either a full listing or a short description, +with or without creating an output image file. If a the default value +of bitpix (default = 0) is entered, wfits will select the appropriate +bitpix value based on the precision of the IRAF data. Otherwise the +user value is used and loss of precision is possible. Two data scaling +options are available. In autoscale mode wfits calculates the appropriate +scaling factors based on the maximum and minimum data values in the +IRAF image and the FITS bits per pixel. Alternatively the scaling factors +can be entered directly. If no scaling is requested the IRAF data values +will be converted directly to FITS integers or floating point values +with possible loss of precision. +.ih +EXAMPLES +1. Convert a list of IRAF image files to a list of FITS image files on a blank +magnetic tape, allowing wfits to select the appropriate bitpix +and scaling parameters. + +.nf + cl> wfits iraf_file* mtb1600[1] +.fi + +2. Convert a list of IRAF image files to FITS image files on disk, +allowing wfits to select the appropriate bitpix and scaling parameters. +In the first example below the images specified by the template are written +to files fits001, fits002, etc. In the second the list of input images +specified one per line in the text file imlist are written to the +files specified one per line in the text file fitslist. + +.nf + cl> wfits iraf_file* fits + + cl> wfits @imlist @fitslist +.fi + +3. Convert an IRAF image file to a 32 bits per pixel FITS file with no +scaling and append to a tape already containing data. + +.nf + cl> wfits iraf_file mtb1600[EOT] bi=32 sc- +.fi + +4. Convert an IRAF image to a 16 bit FITS image on disk, and specify +bscale and bzero explicitly in the process. + +.nf + cl> wfits iraf_file fits_file bi=16 au- bs=4.0 bz=0.0 +.fi + +5. Print the FITS headers on the standard output. + +.nf + cl> wfits iraf_file* ma- +.fi + +6. Create a disk file called headers containing the FITS headers for a list +of IRAF image files. + +.nf + cl> wfits iraf_file* ma- > headers +.fi + +7. Write a FITS tape with 14400 bytes per record (5 2880 FITS records per +tape block) on a 9-track tape. + +.nf + cl> wfits images* mtb[1] block=5 +.fi + +8. Write a FITS Exabyte tape with a blocking factor of 1 (1 2880 FITS record +per block). Note that wfits will normally by default write a 28000 ( +10 2880 FITS logical records per block) byte record. + +.nf + cl> wfits images* mtb[1] block=1 +.fi + +9. Write a list of images to a single tape file using the FITS standard +extension IMAGE. Users who are planning on reading their data with +local FITS readers should check that those local readers support the +FITS IMAGE extension before selecting this option. + +.nf + cl> wfits *.imh mtb[1] block=1 extensions+ +.fi + +10. Repeat the previous example but do not write a global header. + +.nf + cl> wfits *.imh mtb[1] block=1 extensions+ global- +.fi + +.ih +BUGS +WFITS does not attempt to recover from write errors. When an error is +detected, WFITS issues an error message and attempts to write a double +EOF at the end of the last good record. In this case the last file on +the tape will be a partial file. IF WFITS is not successful in writing +the double EOF, the message "Cannot close magtape file (name)" will be +issued. Problems occur as some drives permit the double EOF to be +written after the physical end of tape and some do not. Similarly +some drives can read a double EOF after end of tape and some cannot. Depending +on operating system and device driver, an attempt to read or write past +end of tape may or may not be distinguishable from a normal write error. + +Blank pixel values are not correctly handled. + +Attempting to write at EOT on a blank tape will at best result in numerous +error messages being issued and at worst result in tape runaway depending +on the driver. +.ih +SEE ALSO +rfits, reblock, fits kernel +.endhelp diff --git a/pkg/dataio/doc/wtextimage.hlp b/pkg/dataio/doc/wtextimage.hlp new file mode 100644 index 00000000..6dd67ff8 --- /dev/null +++ b/pkg/dataio/doc/wtextimage.hlp @@ -0,0 +1,100 @@ +.help wtextimage Oct93 dataio +.ih +NAME +wtextimage -- convert an IRAF image to a text file +.ih +USAGE +wtextimage input output +.ih +PARAMETERS +.ls input +An IRAF image file name or template of file names to be converted. +.le +.ls output +Name or root_name of output text file. If more than one IRAF image +is being converted, the ordinal of the file in the input file list +is appended to \fIoutput\fR to generate a unique output file name. +.le +.ls header = yes +This parameter determines whether or not a descriptive header precedes +the pixels written to the text file. When \fIheader = no\fR, only +pixels values are converted; no header information is included in the +output. +.le +.ls pixels = yes +This parameter determines whether or not to write the pixels to the +text file. This can be set to no to only write out the header. +.le +.ls format = "" +Output format for each pixel. If not set by the user, the appropriate output +pixel format is determined by the image data type. +Acceptable formats are chosen from "W.D[defgz]" where w is the field width and +d specifies the precision. Fortran formats of the form [iefgz]W.D are also +acceptable. If a field width of 0 is specified, (e.g., 0.6g), +output will be free format with each output line containing as many pixels as +will fit on the line. This is the most space efficient format but requires +that the reader program be able to handle free format (list directed) input. +.le +.ls maxlinelen = 80 +The maximum number of characters output per line of text; \fBmaxlinelen\fR +must not exceed 322 characters. (Note that tasks \fIrtextimage\fR and +\fIwcardimage\fR cannot read lines of text greater than 161 characters.) +.le +.ih +DESCRIPTION +IRAF images are converted to text files with procedure \fBwtextimage\fR. +The text file written consists of an optional header optionally followed by +the pixel values. The pixels are output in FITS order, that is, the +leftmost subscript varies most rapidly. The image header is written in the +"keyword = value / comment" format of FITS. +.ih +EXAMPLES +1. Write a text file from an image section of dev$pix. The default maximum +linelength of 80 is used; an output format is specified. The header portion +of the output text is as follows: +.ls +.nf +BITPIX = 8 / 8-bit ASCII characters +NAXIS = 2 / Number of Image Dimensions +NAXIS1 = 10 / Length of axis +NAXIS2 = 10 / Length of axis +ORIGIN = 'NOAO-IRAF: WTEXTIMAGE' / +IRAF-MAX= 31431. / Max image pixel (out of date) +IRAF-MIN= 33. / Min image pixel (out of date) +IRAF-B/P= 16 / Image bits per pixel +IRAFTYPE= 'SHORT INTEGER ' / Image datatype +OBJECT = 'NGC 4147 B 1800 ' / +FILENAME= 'DEV$PIX[1:10,1:10]' / IRAF filename +FORMAT = '11I7 ' / Text line format +DATA-TYP= ' object ( 0 )' / object,dark,comp,etc. +ITIME = 1800 / integration time secs +UT = '11:23:13' / universal time +ZD = '24: 5: 0' / zenith distance +DATE-OBS= '15/02/1985' / dd/mm/yy observation +ST = '13:38:31' / sidereal time +RA = '12: 9:20' / right ascension +DEC = '18:35:35' / declination +EPOCH = .0 / epoch of RA and DEC +CAM-TEMP= -104.95 / camera temperature, deg C +DEW-TEMP= -192.96 / dewar temp, deg C +HISTORY1= 'bt= 590 bp= 0 cr= 0 dk= 0 ' +HISTORY2= 'ff= 55 fg= 0 sc= .000 bi= 51 ' +COMMENT = 'ngc 4147 b 1800' +F1POS = 2 / filter bolt I position +F2POS = 0 / filter bolt II position +END +.fi +.le + +2. Write a series of text files from the IRAF images having root name +"reduced". One text file is written for each image. + + cl> wtext reduced.* txt +.ih +TIME REQUIREMENTS +It takes almost 10 cpu minutes to convert a 512 square image of real pixels. +A 512 square image of integer pixels takes about 3 cpu minutes. +.ih +SEE ALSO +wcardimage, rtextimage, noao.onedspec.wspectext +.endhelp -- cgit