diff options
Diffstat (limited to 'pkg/xtools/doc/xtextns.hlp')
| -rw-r--r-- | pkg/xtools/doc/xtextns.hlp | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/pkg/xtools/doc/xtextns.hlp b/pkg/xtools/doc/xtextns.hlp new file mode 100644 index 00000000..f03f69ae --- /dev/null +++ b/pkg/xtools/doc/xtextns.hlp @@ -0,0 +1,115 @@ +.help xt_extns Mar07 xtools +.ih +NAME +.nf +xt_extns -- Expand an MEF into a list of image extensions +.fi +.ih +SYNOPSIS +.nf +int procedure xt_extns (files, index, extname, extver, lindex, lname, lver, + dataless, ikparams, err, imext) + +char files[ARB] #I List of MEF files +char index[ARB] #I Range list of extension indexes +char extname[ARB] #I Patterns for extension names +char extver[ARB] #I Range list of extension versions +int lindex #I List index number? +int lname #I List extension name? +int lver #I List extension version? +int dataless #I Include dataless image headers? +char ikparams[ARB] #I Image kernel parameters +int err #I Print errors? +int imext #O Image extensions? +.fi +.ih +DESCRIPTION +A list, \fIfiles\fR, of regular images and multi-extension FITS (MEF) +files is returned as a list of images. In addition a flag, \fIimext\fR, +is set indicating if image extensions are present. + +In order handle regular and MEF extension images in the same way one must +understand that all images in IRAF may be addressed with a numeric index +while those that are "regular" images may also be addressed without +an index. Non-FITS format images are considered to have an index of 1. +For example, an image in the IRAF format may be addressed +as pix.imh, pix, pix.imh[1], and pix[1]. FITS files start with index 0 +in order that index 1 may be used to refer to the first extension. +So a plain FITS image, say foo.fits may also be addressed as foo, foo[0], +or foo.fits[0]. If a FITS file has both a primary (index 0) image and +extensions then the zero index must be explicitly used. + +For regular images the index range must include 0 for FITS images (or +primary images in FITS files with extensions) and 1 for non-FITS images. +In the resulting list, the index notation is dropped unless it is required; +i.e. in a FITS file with both a primary image and extensions. + +The input set of candidate images may be filtered by index, extension +name, extension version, and whether images are dataless. + +\fIindex\fR is a range list (see \fBranges\fR) of indices to be applied +to each input file for identifying images. If a null string is +specified then all index values bet + +\fIindex\fR is a range list (see \fBranges\fR) of indices to be applied +to each input file for identifying images. If a null string is +specified then all non-negative index values are examined. + +\fIextname\fR is a comma delimited list of patterns for extension names. +If no list (a null string) or the string "*" is specified then no +filtering on the extension name is done. For a description of pattern +matching syntax see \fBmatch\fR. Extension names are those specified +by the EXTNAME keyword. For the purpose of explicit pattern matching +strings a missing EXTNAME keyword is treated as the extension name "none". +To include a comma in a pattern you must escape it by preceding it with +'\', however, a comma in an extension name may cause other problems +because IRAF image extension syntax using the extension name does not +allow commas or whitespace. Each pattern has '^' and '$' prepended +and appended respectively which means the pattern must match the entire +extension name. A common mistake is that '*' in a pattern is different +than '*' in a file template. In this case use '?*'. + +The reasons for a list of patterns matching the entire extension name +are to allow intuitive explicit lists of names, such as "im1,im11,im13", +and to deal with names which are difficult to unambiguously specify with +a single pattern. + +\fIextver\fR is a range list for extension version numbers. If no +list is given then no filtering on extension versions is performed. +See \fBranges\fR for more on range lists. + +\fIdataless\fR is a boolean parameter that selects whether to filter out +dataless images. Dataless images are uncommon except for a class of MEF +files where the primary image is used only for global inherited header +keywords. This parameter may be used to include this global header in +expansions of this type of MEF files. + +The output of the list of selected images for FITS image extensions may +be expressed either with the index notation (e.g. name[3]) or extension +name and/or extension version (e.g. name[im3], name[im5,2]). This is +controlled by the \fIlindex\fR, \fIlname\fR and \fIlver\fR boolean +parameters. If the extension name and or version number are selected +then that format is used even if \flindex\fR is also selected. If +there is no extension name or extension version then the index is used +even if \fIlindex\fR is not selected. Also remember that for regular +images where an index or extension sections is not required none will +be used. + +The output names may also include additional "image kernel" information. +Different image types, currently mostly for FITS images, have parameters +that may be specified in the image kernel section. The \fIikparams\fR +string may be used to add these additional parameters within the +kernel section part of the name. + +Finally, the input files, including MEF files, in the input file list +may include "image sections". During processing image sections are +stripped and then appended on the output. For example, name[1:10,1:10] +might expand to name[im1][1:10,1:10], name[im2][1:10,1:10], etc. + +\fIerr\fR may be used to print error messages when a particular image +index fails to be opened. Typically this would be to find nonexistent +or read-protected images and files. +.ih +SEE ALSO +mscextensions, imextensions, match, ranges +.endhelp |