diff options
Diffstat (limited to 'pkg/images/imutil/doc')
24 files changed, 3394 insertions, 0 deletions
diff --git a/pkg/images/imutil/doc/chpix.hlp b/pkg/images/imutil/doc/chpix.hlp new file mode 100644 index 00000000..9104b254 --- /dev/null +++ b/pkg/images/imutil/doc/chpix.hlp @@ -0,0 +1,64 @@ +.help chpixtype Jun88 images.imutil +.ih +NAME +chpixtype -- change the pixel type of an image +.ih +USAGE +chpixtype input output newpixtype +.ih +PARAMETERS +.ls input +The list of input images. +.le +.ls output +The list of output images. If the output image list is the same as the input +image list then the original images are overwritten. +.le +.ls newpixtype +The pixel type of the output image. The options are: "ushort", "short", +"int", "long", "real", "double" and "complex". +.le +.ls oldpixtype = "all" +The pixel type of the input images to be converted. By default all the +images in the input list are converted to the pixel type specified by +newpixtype. The remaining options are "ushort", "short", "int", "long", +"real", "double" and "complex" in which case only those images of the +specified type are converted. +.le +.ls verbose = yes +Print messages about actions performed. +.le + +.ih +DESCRIPTION + +The list of images specified by \fIinput\fR and pixel type \fIoldpixtype\fR +are converted to the pixel type specified by \fInewpixtype\fR and written +to the list of output images specified by \fIoutput\fR. + +Conversion from one pixel type to another is direct and may involve both +loss of precision and dynamic range. Mapping of floating point numbers +to integer numbers is done by truncation. Mapping of complex numbers +to floating point or integer numbers will preserve the real part of the +complex number only. + +.ih +EXAMPLES + +1. Convert a list of images to type real, overwriting the existing images. + + im> chpixtype nite1*.imh nite1*.imh real + +2. Convert only those images in imlist1 which are of type short to type real. + Imlist1 and imlist2 are text files containing the list of input and + output images respectively. The image names are listed 1 per line. + + im> chpixtype @imlist1 @imlist2 real old=short +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imarith +.endhelp diff --git a/pkg/images/imutil/doc/hedit.hlp b/pkg/images/imutil/doc/hedit.hlp new file mode 100644 index 00000000..3871d8e7 --- /dev/null +++ b/pkg/images/imutil/doc/hedit.hlp @@ -0,0 +1,375 @@ +.help hedit Apr01 images.imutil +.ih +NAME +hedit - edit or view an image header or headers +.ih +USAGE +hedit images fields value +.ih +PARAMETERS +.ls images +Template specifying the images to be edited. +.le +.ls fields +Template specifying the fields to be edited in each image. The template is +expanded independently for each image against the set of all fields in the +image header. +.le +.ls value +Either a string constant or a general expression (if the first character is +a left parenthesis) to be evaluated to compute the new value of each field. +A single expression is used for all fields. The special value "." causes the +value of each field to be printed rather than edited. +.le +.ls add = no +Change the operation of the editor from update to add new field. If the +field already exists it is edited. If this option is selected the field +list may name only a single field. The add switch takes precedence +over the addonly and delete switches. +.le +.ls addonly = no +Change the operation of the editor from update to add a new field. If the +field already exists it is not changed. If this option is selected the field +list may name only a single field. The addonly switch takes precedence over +the delete switch. +.le +.ls delete = no +Change the operation of the editor from update to delete field. +The listed fields are deleted from each image. +.le +.ls verify = yes +Interactively verify all operations which modify the image database. +The editor will describe the operation to be performed, prompting with the +new value of the parameter in the case of a field edit. Type carriage +return or "yes" to complete the operation, or enter a new value explicitly +as a string. Respond with "no" if you do not wish to change the value of +the parameter. +.le +.ls show = yes +Print a record of each operation which modifies the database upon the standard +output. Old values are given as well as new values, making it possible to +undo an edit operation. +.le +.ls update = yes +Enable updating of the image database. If updating is disabled the edit +operations are performed in memory but image headers will not be updated +on disk. +.le +.ih +DESCRIPTION + +1. Basic Usage + + The most basic functions of the image header editor are modification and +inspection of the fields of an image header. Both the "standard" and +"user" fields may be edited in the same fashion, although not all standard +fields are writable. For example, to change the value of the standard field +"title" of the image "m74" to "sky flat" we would enter the following command. + + cl> hedit m74 title "sky flat" + +If \fIverify\fR mode is selected the editor will print the old value of the +field and query with the new value, allowing some other value to be entered +instead, e.g.: + +.nf + cl> hedit m74 title "sky flat" + m74,i_title ("old title" -> "sky flat"): +.fi + +To accept the new value shown to the right of the arrow, type carriage +return or "yes" or "y" followed by carriage return. To continue without +changing the value of the field in question enter "no" or "n" followed by +carriage return. To enter some other value merely type in the new value. +If the new value is one of the reserved strings, e.g., "yes" or "no", +enter it preceded by a backslash. If verification is enabled you will +also be asked if you want to update the header, once all header fields +have been edited. This is your last chance to change your mind before +the header is modified on disk. If you respond negatively the image header +will not be updated, and editing will continue with the next image. +If the response is "q" the editor will exit entirely. + +To conveniently print the value of the field "title" without modifying the +image header, we repeat the command with the special value ".". + + cl> hedit m74 title . + +To print (or edit) the values of all header fields a field template may be +given. + + cl> hedit m74 * . + +To print (or edit) the values of only a few fields the field template may +be given as a list. + + cl> hedit m74 w0,wpc . + +To print the value of one or more fields in a set of images, an image template +may be given. Both image templates and field templates may be given if +desired. + + cl> hedit n1.* exp . + +Abbreviations are not permitted for field names, i.e., the given template +must match the full field name. Currently, field name matches are case +insensitive since image headers are often converted to and from FITS headers, +which are case insensitive. + + +2. Advanced Usage + + The header editor is capable of performing global edits on entire image +databases wherein the new value of each field is computed automatically at +edit time and may depend on the values of other fields in the image header. +Editing may be performed in either batch or interactive mode. An audit trail +may be maintained (via the \fIshow\fR switch and i/o redirection), permitting +restoration of the database in the event of an error. Trial runs may be made +with updating disabled, before committing to an actual edit which modifies the +database. + +The major editing functions of the \fIhedit\fR task are the following: + +.nf + update modify the value of a field or fields + addonly add a new field + add add a new field or modify an old one + delete delete a set of fields +.fi + +In addition, \fIhedit\fR may be used merely to inspect the values of the header +fields, without modification of the image database. + + +2.1 Standard header fields + + The header editor may be used to access both the standard image header +fields and any user or application defined fields. The standard header fields +currently defined are shown below. There is no guarantee that the names and/or +usage of these fields will not change in the future. + + +.ks +.nf + i_ctime int create time + i_history string history comments + i_limtime int time when min,max last updated + i_maxpixval real maximum pixel value + i_minpixval real minimum pixel value + i_mtime int time of last modify + i_naxis int number of axes (dimensionality) + i_naxis[1-7] int length of each axis + i_pixfile string pathname of pixel storage file + i_pixtype int pixel datatype code + i_title string title string +.fi +.ke + + +The standard header field names have an "i_" prefix to reduce the possibility +of a name collision with a user field name, and to distinguish the two classes +of parameters in templates. The prefix may be omitted provided the simple +name is unique. + + +2.2 Field name template + + The form of the field name list or template parameter \fIfields\fR is +equivalent to that of a filename template except that "@listfile" is not +supported, and of course the template is expanded upon the field name list +of an image, rather than upon a directory. Abbreviations are not permitted +in field names and case is not significant. Case is ignored in this context +due to the present internal storage format for the user parameters (FITS), +which also limits the length of a user field name to 8 characters. + + +2.3 Value expression + + The \fIvalue\fR parameter is a string type parameter. If the first +character in the string is a left parenthesis the string is interpreted as +an algebraic expression wherein the operands may be constants, image header +variables (field names), special variables (defined below), or calls to +intrinsic functions. The expression syntax is equivalent to that used in +the CL and SPP languages. If the value string is not parenthesized it is +assumed to be a string constant. The \fIvalue\fR string will often contain +blanks, quotes, parenthesis, etc., and hence must usually be quoted to avoid +interpretation by the CL rather than by the header editor. + +For example, the command + + cl> hedit m74 title "title // ';ss'" + +would change the title to the literal string constant "title // ';ss'", +whereas the command + + cl> hedit m74 title "(title // ';ss')" + +would concatenate the string ";ss" to the old title string. We require +parenthesis for expression evaluation to avoid the need to doubly quote +simple string constant values, which would be even more confusing for the +user than using parenthesis. For example, if expressions did not have to +be parenthesized, the first example in the basic usage section would have +to be entered as shown below. + + cl> hedit m74 title '"sky flat"' # invalid command + +Expression evaluation for \fIhedit\fR, \fIhselect\fR, and similar tasks +is carried out internally by the FMTIO library routine \fBevexpr\fR. +For completeness minimal documentation is given here, but the documentation +for \fIevexpr\fR itself should be consulted if additional detail is required +or if problems occur. + + +2.3.1 operators + + The following operators are recognized in value expressions. With the +exception of the operators "?", "?=", and "@", the operator set is equivalent +to that available in the CL and SPP languages. + + +.nf + + - * / arithmetic operators + ** exponentiation + // string concatenation + ! - boolean not, unary negation + < <= > >= order comparison (works for strings) + == != && || equals, not equals, and, or + ?= string equals pattern + ? : conditional expression + @ reference a variable +.fi + + +The operators "==", "&&", and "||" may be abbreviated as "=", "&", and "|" +if desired. The ?= operator performs pattern matching upon strings. +For example, the boolean expression shown below will be true whenever the +field "title" contains the substring "sky". + + (title ?= '*sky*') + +The conditional expression operator '?', which is patterned after a similar +operator in C, is used to make IF ELSE like decisions within an expression. +The syntax is as follows: + + <bool_expr> '?' <true_expr> ':' <false_expr> + +e.g., the expression + + ((a > b) ? 1 : 0) + +has the value 1 if A is greater than B, and 0 otherwise. The datatypes +of the true and false expressions need not be the same, unlike a compiled +language. Note that if the parenthesis are omitted ambiguous forms of +the expression are possible, e.g.: + + (a > b) ? 1 : a + 1 + +could be interpreted either as + + ((a > b) ? 1 : a) + 1 +or as + (a > b) ? 1 : (a + 1) + +If the parenthesis are omitted the latter interpretation is assumed. + +The operator @ must be used to dereference variables that have names with +funny (non-alphanumeric) characters in them, forcing the variable name to +be given as a string constant. For example, the value of the expression + + @"co-flag" + +is the value of the variable "co-flag". If the variable were referenced +directly by name the "-" would be interpreted as the subtraction operator, +causing an unknown variable reference (e.g., to "co"). +The operand following the @ may be any string valued expression. +The @ operator is right associative, hence the construct "@@param" is the +value of the parameter named by the value of the parameter "param". + +An expression may contain operands of datatypes bool, int, real, and string. +Mixed mode expressions are permitted with automatic type coercion. Most type +coercions from boolean or string to other datatypes are illegal. The boolean +constants "yes" and "no" are predefined and may be used within expressions. + + +2.3.2 intrinsic functions + + A number of standard intrinsic functions are recognized within expressions. +The set of functions currently supported is shown below. + + +.nf + abs acos asin atan atan2 bool cos + exp int log log10 max min mod + nint real sin sqrt str tan +.fi + + +The trigonometric functions operate in units of degrees rather than radians. +The \fImin\fR and \fImax\fR functions may have any number of arguments up +to a maximum of sixteen or so (configurable). The arguments need not all +be of the same datatype. + +A function call may take either of the following forms: + +.nf + <identifier> '(' arglist ')' +or + <string_expr> '(' arglist ')' +.fi + +The first form is the conventional form found in all programming languages. +The second permits the generation of function names by string valued +expressions and might be useful on rare occasions. + + +2.3.3 special operands + + As noted earlier, expression operands may be constants, variables (header +fields), function calls, or references to any of the special variables. +The following special variables are recognized within expressions: + + +.nf + . A string constant, used to flag printing + $ The value of the "current field" + $F The name of the "current field" + $I The name of the "current image" + $T The current clock time (an integer value) +.fi + + +These builtin variables are especially useful for constructing context +dependent expressions. For example, the value of a field may be incremented +by 100 by assigning it the value "$ + 100". + +.ih +EXAMPLES +1. Globally edit the database "n1", setting the value of the string parameter +"obs" to "sky" if "s-flag" is 1, to "obj" otherwise. + + cl> hedit n1.* obs '(@"s-flag" == 1 ? "sky" : "obj")' + +2. Globally edit the same database, replacing the value of the parameter +"variance" by the square root of the original value. + + cl> hedit n1.* var '(sqrt(var))' + +3. Replace the values of the fields A and B by the absolute value of the +original value: + + cl> hedit n1.* a,b '(abs($))' + +.ih +BUGS +The internal storage format is currently FITS card image, hence field names +are limited to 8 characters with no case sensitivity. String values are +limited to 63 characters. There is an upper limit on the number of fields +in a header but it is quite large - assume it is 1024 or so. Global operations +on databases are currently quite slow because the individual records (image +headers) are stored in separate files. + +A task is needed which would take the audit trail produced by the \fIshow\fR +option and use it to undo an edit. +.ih +SEE ALSO +hselect, imgets, imheader +.endhelp diff --git a/pkg/images/imutil/doc/hselect.hlp b/pkg/images/imutil/doc/hselect.hlp new file mode 100644 index 00000000..d94f240b --- /dev/null +++ b/pkg/images/imutil/doc/hselect.hlp @@ -0,0 +1,103 @@ +.help hselect May85 images.imutil +.ih +NAME +hselect - extract keyword values from images satisfying a selection expression +.ih +USAGE +hselect images fields expr +.ih +PARAMETERS +.ls images +Images forming the set from which selected images are to be drawn. +.le +.ls fields +Comma separated list of keywords or keyword patterns to be extracted +from each selected image. The list elements are matched against the +set of keywords in the header except for those beginning with "$" which +are special values or explicit checks for keywords that might be missing. +.le +.ls expr +The boolean expression to be used as the selection criteria. The expression +is evaluated independently for each image. +.le +.ls missing = "INDEF" +Output value for missing keywords. Note that this will only occur when the +fields are specified with leading "$". +.le +.ih +DESCRIPTION +The function of \fIhselect\fR is to extract keyword values from a subset +of images satisfying a boolean selection expression. The resultant table +of keyword values is output in list form, suitable for further analysis +or for use to generate a list of images to be processed by another task. + +The form of the boolean expression \fIexpr\fR is fully documented in the +manual page for the \fIhedit\fR task. In the case of \fIhselect\fR task, +however, the expression need not be parenthesized to be evaluated as an +expression. + +The keywords whose values are to be output are specified by the \fIfields\fR +parameter. This is a comma delimited list of keywords and patterns. The +keywords and patterns are matched against the set of keywords in the image. +Of particular importance is that explicit keywords, that is without any +wildcard, are matched against the header and so if the keyword is not in the +header then the keyword value is not output. If one wants to explicitly +output a place holder for a missing keyword use a leading $; e.g. $mykey. +If the keyword is absent then the value given by the \fImissing\fR +parameter will be output. This is useful when scanning the output. + +In addition to escaping the keyword matching, the leading $ character is +also used to select special values such as "$I" for the name of the current +image. See \fBhedit\fR for more on the special values and pattern syntax. +.ih +EXAMPLES +1. Compute the mean exposure time for all the images in a database. Note that +the argument "yes" is a trivial case of a general boolean expression and +hence need not be quoted. + + cl> hselect n1.* exp yes | average + +2. Print the name, length of axes 1 and 2, and title of all two dimensional +images in a database. + + +.nf + cl> hselect n1.* $I,naxis[12],title 'naxis == 2' + n1.0001 512 512 quartz + n1.0002 512 512 "dome flat" + n1.0005 384 800 "ngc 3127 at 45 degrees" + cl> +.fi + + +3. Produce an image name list for use to drive another task. The selection +criterion is all images for which the value of the parameter "q-flag" +has the value 1. Note carefully the use of quotes. If the @ operator +is unfamiliar read the manual page for \fIhedit\fR. + + cl> hselect n1.* $I '@"q-flag" == 1' > imlist + +If the parameter "q-flag" were instead named "qflag", the following +simpler expression would suffice. + + cl> hselect n1.* $I 'qflag == 1' > imlist + +4. Scan a set of keyword and allow for missing keywords. + +.nf + cl> hselect pix $I,$exptime,$airmass yes missing=INDEF | + >>> scan (s1, x, y) +.fi + +Note that when checking for missing values the missing value must be +of the appropriate type or else you need to use string variables or +nscan to check. The default missing value is "INDEF" which can be +scanned into both string and numerical variables. +.ih +BUGS +Since individual image headers are currently stored as separate files, +selection from a large database is quite slow. +.ih +SEE ALSO +hedit, imgets, imheader +.endhelp diff --git a/pkg/images/imutil/doc/imarith.hlp b/pkg/images/imutil/doc/imarith.hlp new file mode 100644 index 00000000..00c913e8 --- /dev/null +++ b/pkg/images/imutil/doc/imarith.hlp @@ -0,0 +1,218 @@ +.help imarith Sep86 images.imutil +.ih +NAME +imarith -- binary image arithmetic +.ih +USAGE +imarith operand1 op operand2 result +.ih +PARAMETERS +.ls operand1, operand2 +Lists of images and constants to be used as operands. +Image templates and image sections are allowed. +.le +.ls op +Operator to be applied to the operands. The allowed operators +are "+", "-", "*", "/", "min", and "max". +.le +.ls result +List of resultant images. +.le +.ls title = "" +Title for the resultant images. If null ("") then the title is taken +from operand1 if operand1 is an image or from operand2 otherwise. +.le +.ls divzero = 0. +Replacement value for division by zero. When the denominator is zero +or nearly zero the result is replaced by this value. +.le +.ls hparams = "" +List of header parameters to be operated upon. This is primarily +used for adding exposure times when adding images. +.le +.ls pixtype = "", calctype = "" +Pixel datatype for the resultant image and the internal calculation datatype. +The choices are given below. They may be abbreviated to one character. +.ls "" +\fICalctype\fR defaults to the highest precedence operand datatype. If the +highest precedence datatype is an integer type and the operation is +division then the calculation type will be "real". If the highest +precedence operand is type "ushort", \fIcalctype\fR will default to +"long". \fIPixtype\fR defaults to \fIcalctype\fR. Users who want type +"ushort" images on output will need to set \fIpixtype\fR to "ushort" +explicitly. +.le +.ls "1", "2" +The pixel datatype of the first or second operand. +.le +.ls "short", "ushort", "integer", "long", "real", "double" +Allowed IRAF pixel datatypes. +.le +.le +.ls verbose = no +Print the operator, operands, calculation datatype, and the resultant image +name, title, and pixel datatype. +.le +.ls noact = no +Like the verbose option but the operations are not actually performed. +.le +.ih +DESCRIPTION +Binary image arithmetic is performed of the form: + + operand1 op operand2 = result + +where the operators are addition, subtraction, multiplication, +division, and minimum and maximum. The division operator checks for +nearly zero denominators and replaces the ratio by the value specified +by the parameter \fIdivzero\fR. The operands are lists of images and +numerical constants and the result is a list of images. The number of +elements in an operand list must either be one or equal the number of +elements in the resultant list. If the number of elements is one then +it is used for each resultant image. If the number is equal to the +number of resultant images then the elements in the operand list are +matched with the elements in the resultant list. The only limitation +on the combination of images and constants in the operand lists is that +both operands for a given resultant image may not be constants. The +resultant images may have the same name as one of the operand images in +which case a temporary image is created and after the operation is +successfully completed the image to be replaced is overwritten by the +temporary image. + +If both operands are images the lengths of each axis for the common +dimensions must be the same though the dimensions need not be the +same. The resultant image header will be a copy of the operand image +with the greater dimension. If the dimensions are the same then image +header for the resultant image is copied from operand1. The title of +the resultant image may be changed using the parameter \fItitle\fR. +The pixel datatype for the resultant image may be set using the +parameter \fIpixtype\fR. If no pixel datatype is specified then the +pixel datatype defaults to the calculation datatype given by the +parameter \fIcalctype\fR. The calculation datatype defaults to the +highest precedence datatype of the operand images or constants except +that a division operation will default to real for integer images. +The precedence of the datatypes, highest first, is double, +real, long, integer, and short. The datatype of a constant operand is +either short integer or real. A real constant has a decimal point. + +Arithmetic on images of unequal dimensions implies that the operation +is repeated for each element of the higher dimensions. For example +subtracting a two dimensional image from a three dimensional image +consists of subtracting the two dimensional image from each band of the +three dimensional image. This works for any combination of image +dimensions. As an extreme example dividing a seven dimensional image +by a one dimension image consists of dividing each line of each plane +of each band ... by the one dimensional image. + +There are two points to emphasize when using images of unequal +dimensions. First, a one dimensional image operates on a line +of a two or higher dimension image. To apply a one dimensional image +to the columns of a higher dimensional image increase the image +dimensionality with \fBimstack\fR, transpose the resultant image, +and then replicate the columns with \fBblkrep\fR (see the EXAMPLE +section). The second point of confusion is that an image with a +size given by \fBimheader\fR of [20,1] is a two dimensional image +while an image with size of [20] is a one dimensional image. To +reduce the dimensionality of an image use \fBimcopy\fR. + +In addition to operating on the image pixels the image header parameters +specified by the list \fIhparams\fR are also operated upon. The operation +is the same as performed on the pixels and the values are either the +values associated with named header parameters or the operand constant +values. The primary purpose of this feature is to add exposure times +when adding images. + +The verbose option is used to record the image arithmetic. The output +consists of the operator, the operand image names, the resultant image +name and pixel datatype, and the calculation datatype. +.ih +EXAMPLES +1. To add two images and the exposure times: + +.nf + cl> imarith ccd1 + ccd2 sum + >>> hparams="itime,otime,ttime,exposure" +.fi + +2. To subtract a constant from an image and replace input image by the +subtracted image: + + cl> imarith m31 - 223.2 m31 + +Note that the final pixel datatype and the calculation datatype will be at +least of type real because the constant operand is real. + +3. To scale two exposures, divide one by the other, and extract the central +portion: + +.nf + cl> imarith exp1[10:90,10:90] * 1.2 temp1 + cl> imarith exp2[10:90,10:90] * 0.9 temp2 + cl> imarith temp1 / temp2 final title='Ratio of exp1 and exp 2' + cl> imdelete temp1,temp2 +.fi + +Note that in this example the images temp1, temp2, and final will be +of real pixel datatype (or double if either exp1 or exp2 are of pixel +datatype double) because the numerical constants are real numbers. + +4. To divide two images of arbitrary pixel datatype using real arithmetic +and create a short pixel datatype resultant image: + +.nf + cl> imarith image1 / image2 image3 pixtype=real \ + >>> calctype=short title="Ratio of image1 and image2" +.fi + +5. To divide several images by calibration image using the image pixel type of +the numerator images to determine the pixel type of the calibration images +and the calculation arithmetic type: + +.nf + cl> imarith image1,image2,image3 / calibration \ + >>> image1a,image2a,image3a pixtype=1 calctype=1 +.fi + +The same operation can be done in place with image template expansion by: + +.nf + cl> imarith image* / calibration image* pixtype=1 calctype=1 +.fi + +6. To subtract a two dimensional bias from stacked observations (multiple +two dimensional observations stacked to form a three dimensional image): + + cl> imarith obs* - bias obs*//b + +Note that the output observations obs101b, ..., will be three dimensional. + +7. To divide a 50 x 50 image by the average column: + +.nf + cl> blkavg img avcol 50 1 + cl> blkrep avcol avcol 50 1 + cl> imarith img / avcol flat +.fi + +8. To subtract a one dimensional image from the lines of a two dimensional +image: + + cl> imarith im2d - im1d diff + +9. To subtract a one dimensional image from the columns of a two dimensional +image: + +.nf + cl> imstack im1d imcol + cl> imtranspose imcol imcol + cl> blkrep imcol imcol 100 1 + cl> imarith im2d - imcol diff +.fi + +Note the need to make a two dimensional image with each column +replicated since a one dimensional image will operate on the lines +of a two dimensional image. +.ih +SEE ALSO +blkrep, imdivide, imfunction, imstack, imtranspose +.endhelp diff --git a/pkg/images/imutil/doc/imcopy.hlp b/pkg/images/imutil/doc/imcopy.hlp new file mode 100644 index 00000000..1128c587 --- /dev/null +++ b/pkg/images/imutil/doc/imcopy.hlp @@ -0,0 +1,91 @@ +.help imcopy Oct84 images.imutil +.ih +NAME +imcopy -- copy images +.ih +USAGE +imcopy input output +.ih +PARAMETERS +.ls input +Images to be copied. +.le +.ls output +Output images or directory. +.le +.ls verbose = yes +Print each operation as it takes place? +.le +.ih +DESCRIPTION +Each of the input images, which may be given as a general image template +including sections, is copied to the corresponding output image list, +which may also be given as an image template, or the output directory. +If the output is a list of images then the number of input images must be +equal to the number of output images and the input and output images are paired +in order. If the output image name exists and contains a section then the +input image (provided it is the same size as the section) will be copied +into that section of the input image. If the output image name does not +have a section specification and if it is the same as the input image name +then the input image is copied to a temporary file which replaces the input +image when the copy is successfully concluded. Note that these are the only +cases where clobber checking is bypassed; that is, if an output image name +is not equal to the input image name or a subsection of an existing image +and the file already exists then a clobber error will occur if +clobber checking is in effect. + +The verbose options prints for each copy lines of the form: +.nf + +input image -> output image +.fi +.ih +EXAMPLES +1. For a simple copy of an image: + + cl> imcopy image imagecopy + +2. To copy a portion of an image: + + cl> imcopy image[10:20,*] subimage + +3. To copy several images: + + cl> imcopy image1,image2,frame10 a,b,c + +4. To trim an image: + + cl> imcopy image[10:20,*] image + +In the above example the specified section of the input image replaces the +original input image. To trim several images using an image template: + + cl> imcopy frame*[1:512,1:512] frame* + +In this example all images beginning with "frame" are trimmed to 512 x 512. + +5. To copy a set of images to a new directory: + +.nf + cl> imcopy image* directory + or + cl> imcopy image* directory$ + or + cl> imcopy image* osdirectory +.fi + +where "osdirectory" is an operating system directory name (i.e. /user/me +in UNIX). + +6. To copy a section of an image in an already existing image of + sufficient size to contain the input section. + +.nf + cl> imcopy image[1:512,1:512] outimage[257:768,257:768] +.fi + +.ih +BUGS +The distinction between copying to a section of an existing image +and overwriting a input image is rather inobvious. +.endhelp diff --git a/pkg/images/imutil/doc/imdelete.hlp b/pkg/images/imutil/doc/imdelete.hlp new file mode 100644 index 00000000..54d926fe --- /dev/null +++ b/pkg/images/imutil/doc/imdelete.hlp @@ -0,0 +1,55 @@ +.help imdelete Dec85 images.imutil +.ih +NAME +imdelete -- delete a list of images +.ih +USAGE +imdelete images +.ih +PARAMETERS +.ls images +List of images to be deleted. +.le +.ls go_ahead +Delete the image? +.le +.ls verify = no +Verify the delete operation for each image. +.le +.ls default_action = yes +The default action for the verify query. +.le +.ih +DESCRIPTION +IMDELETE takes as input a list of IRAF images specified by \fIimages\fR and +deletes both the header and pixel files. In \fIverify\fR mode IMDELETE +queries the user for the appropriate action to be taken for each IRAF image. + +If the \fIimages\fR parameter is a URL, it will be accessed and put into +the file cache, then immediately deleted. To simply remove a file from +the cache, use the \fIfcache\fR command instead. +.ih +EXAMPLES +1. Delete a list of images + +.nf + cl> imdelete fits* +.fi + +2. Delete a list of images using verify + +.nf + cl> imdel fits* ver+ + cl> Delete file \fI'fits1'\fR ? (yes): yes + cl> Delete file \fI'fits2'\fR ? (yes): yes + cl> Delete file \fI'fits3'\fR ? (yes): yes +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imcopy, fcache +.endhelp diff --git a/pkg/images/imutil/doc/imdivide.hlp b/pkg/images/imutil/doc/imdivide.hlp new file mode 100644 index 00000000..2f104029 --- /dev/null +++ b/pkg/images/imutil/doc/imdivide.hlp @@ -0,0 +1,65 @@ +.help imdivide Sep86 images.imutil +.ih +NAME +imdivide -- image division with zero checking and rescaling +.ih +USAGE +imdivide numerator denominator resultant +.ih +PARAMETERS +.ls numerator +Numerator image. +.le +.ls denominator +Denominator image. +.le +.ls resultant +Resultant image. This image will be of datatype real. +.le +.ls title = '*' +Title for resultant image. The special character '*' defaults the title +to that of the numerator image. +.le +.ls constant = 0 +The constant value for the zero division constant option. +.le +.ls rescale = norescale +After the image division the resultant image may be rescaled with the following +options: +.ls norescale +Do not rescale the resultant image. +.le +.ls mean +Scale the resultant image to the specified mean value. +.le +.ls numerator +Scale the resultant image to have the same mean value as the numerator image. +.le +.le +.ls mean = 1 +The mean value used rescale the resultant image under 'mean' option of +\fIrescale\fR. +.le +.ls verbose = no +Print the means of each image? +.le +.ih +DESCRIPTION +The \fInumerator\fR image is divided by the \fIdenominator\fR image to +form the \fIresultant\fR image. The division is checked for division by +zero and replaces the result with the value of the parameter \fIconstant\fR. +After the division the resultant image may be rescaled. +The rescaling option is selected with \fIrescale\fR. The options are +not to rescale, rescale to the specified \fImean\fR value, and rescale to +the mean of the numerator. The means of the three images are calculated +and may be printed with the verbose option. +.ih +EXAMPLES +1. To divide a object image by a flat field and then rescale the division +back to the mean of the object image: + + cl> imdivide object image final rescale=numerator +.ih +SEE ALSO +imarith +.endhelp diff --git a/pkg/images/imutil/doc/imexpr.hlp b/pkg/images/imutil/doc/imexpr.hlp new file mode 100644 index 00000000..76886d95 --- /dev/null +++ b/pkg/images/imutil/doc/imexpr.hlp @@ -0,0 +1,447 @@ +.help imexpr Dec01 images.imutil +.ih +NAME +imexpr -- General image expression evaluator +.ih +USAGE +imexpr expr output [a b c ...] +.ih +PARAMETERS +.ls expr +The expression to be evaluated. This may be the actual expression, or the +string "@file" in which case the expression is taken from the named file. +The input operands (i.e., numeric constants, images, or image header +parameters) are referred to in the expression symbolically using the letters +"a" through "z". +.le +.ls output +The output image. A section may be given to write into a section of an +existing image. +.le +.ls a - z +The input operands referenced by the expression. The value of an operand +may be an image name or section, a numeric constant, or a reference to an +image header parameter of the form \fIoperand.param\fR, where \fIoperand\fR +is one of the other input operands "a" through "z", corresponding to an input +image (for example, "a.itime" is the parameter "itime" from the image +assigned to operand "a"). An example of an input image operand is +"a=dev$pix". +.le +.ls dims = "auto" +The dimensions of the output image. If the special value \fIauto\fR is +given the output image dimensions are computed based on the input operands +and the expression being evaluated. Otherwise the value is a list of axis +lengths, e.g., "512,512". +.le +.ls intype = "int" +The minimum datatype for an input image operand. If the special value +\fIauto\fR is given the operand type will be the same as the pixel type of +the image. Otherwise one of the values "short", "int", "long", "real", +or "double" should be given. The program will promote the type of the +input operand to the type specified if the actual type is less precise +than the value of \fIintype\fR, otherwise the type of the input operand +is not changed. For example, if \fIintype\fR is "int" (the default), +short integer input operands will be promoted to integer but int, long, +real or double operands will be unaffected. Setting \fIintype\fR to real +will force the expression to be evaluated in floating point. +.le +.ls outtype = "auto" +The pixel type of the output image. If set to the special value \fIauto\fR +the output image will be the same type as the expression being evaluated. +If set to \fIref\fR the output image will have the same type as the +"reference" input image (see below), regardless of the expression type. +If an explicit type is specified such as "short", "ushort", "int", "real", +an image of the indicated type will be created. +.le +.ls refim = "auto" +The reference image to be used to pass the WCS and other image header +attributes to the output image. If set to \fIauto\fR the program will +compute the best reference image, which is the first input image +with the highest number of dimensions. To force a particular input image +to be the reference image the value should be set to the name of an input +operand ("a", "b", etc.). The named operand must refer to an image. +.le +.ls bwidth = 0 +The boundary width in pixels for boundary extension. Boundary extension +is enabled by setting this value to a positive nonzero value. Boundary +extension is needed when an input image section references out of bounds. +.le +.ls btype = "nearest" +The type of boundary extension, chosen from the list "constant", "nearest", +"reflect", "wrap", or "project". +.le +.ls bpixval = 0. +The boundary pixel value if \fIbtype\fR="constant". +.le +.ls rangecheck = yes +If range checking is enabled then the program will check for illegal +operations such as divide by zero or the square root or logarithm of a +negative value, substituting a constant value (zero) if such an operation +is detected. This may be necessary to avoid aborting the entire operation +because of a few bad pixels in an image. A conditional expression may be +used to detect such pixels and perform any special processing. +.le +.ls verbose = yes +Enable or disable informative messages. If enabled, the program will echo +the expression to be evaluated after all expansions have been performed, +and percent-done messages will be printed as the expression is evaluated. +.le +.ls exprdb = "" +The file name of an optional expression database. An expression database +may be used to define symbolic constants or a library of custom function +macros. +.le +.ih +DESCRIPTION +\fIimexpr\fR evaluates an image expression and writes the result to the +output image. Images may be any dimension or size and any datatype except +complex (complex images may be read but only the real part will be used). + +If the input images are not all the same size the computation will be +performed over the largest area which is common to all images. If the +images are not all the same dimension the lesser dimension operands will be +iteratively combined with the higher dimension ones. For example, when +both a one and two dimensional image are used in the same expression, +the vector (one dimensional image) will be applied to all lines of the +two dimensional image. + +Evaluation of the image expression is carried out one line at a time. This +is efficient and permits operations on arbitrarily large images without +using excessive memory, but does not allow 2D or higher operations to be +performed within the expression (e.g., transpose). The entire expression is +evaluated once for each line of the output image. + + +\fBOperands\fR + +Input operands are represented symbolically in the input expression using +the symbols "a" through "z", corresponding to \fIimexpr\fR task parameters. +Use of symbolic operands allows the same expression to be used with different +data sets, simplifies the expression syntax, and allows a single input image +to be used several places in the same expression. + +Three classes of input operands are recognized: images, image parameters, and +numeric constants. + +.nf + dev$pix[*,55] image operand + a.itime image parameter + 1.2345 numeric constant +.fi + +Since the input operands are CL parameters they may be set on the command +line, or entered in response to parameter prompts when the task executes and +evaluates the input expression. For example, + +.nf + cl> imexpr "a - a/b" pix + operand a: dev$pix[*,55] + operand b: a.itime +.fi + +would evaluate the expression shown, storing the result in the output image +"pix". + +Operands may also be specified directly in the expression, with the +exception of image operands. For example, + + cl> imexpr "a - a / a.itime" + +is equivalent to the earlier example. + +If the input operand is not a simple identifier (a simple name like "itime" +containing only alphanumeric characters, underscore, ".", or "$") then it +is necessary to quote the operand name and precede it with an "@", e.g., + + cl> imexpr 'a - a / @"a.i-time"' + +Finally, there is a special builtin type of operand used to represent the +image pixel coordinates in an image expression. These operands have the +special reserved names "I", "J", "K", etc., up to the dimensions of the +output image. The names must be upper case to avoid confusion to with the +input operands "i", "j", "k" and so on. + +.nf + I X coordinate of pixel (column) + J Y coordinate of pixel (line) + K Z coordinate of pixel (band) +.fi + +An example of the use of the pixel coordinate operands is the generation of +multidimensional analytic functions. + + +\fBOperators\fR + +The expression syntax implemented by \fIimexpr\fR provides the following +set of operators: + +.nf + ( expr ) grouping + + - * / arithmetic + ** exponentiation + // concatenate + expr ? expr1 : expr2 conditional expression + @ "name" get operand + + && logical and + || logical or + ! logical not + < less than + <= less than or equal + > greater than + >= greater than or equal + == equals + != not equals + ?= substring equals + + & bitwise and + | bitwise or + ^ bitwise exclusive or + ~ bitwise not (complement) +.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 + + (a < 0) ? 555 : b / a + +has the constant value 555 if "a" is less than zero, and "b / a" otherwise. +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. + +The substring equals operator "?=", used for string comparisons, is like +"==" but checks for the presence of a substring, rather than exact equality +of the two strings. + + +\fBFunctions\fR + +Where it makes sense all intrinsic functions support all datatypes, with +some restrictions on \fIbool\fR and \fIchar\fR. Arguments may be scalars or +vectors and scalar and vector arguments may be mixed in the same function +call. Arguments are automatically type converted upon input as necessary. +Some functions support a variable number of arguments and the details of +the the operation to be performed may depend upon how many arguments are +given. + +Functions which operate upon vectors are applied to the \fIlines\fR of an +image. When applied to an image of dimension two or greater, these +functions are evaluated separately for every line of the multidimensional +image. + +Standard Intrinsic Functions + +.nf + abs (a) absolute value + max (a, b, ...) maximum value + min (a, b, ...) minimum value + mod (a, b) modulus + sqrt (a) square root +.fi + +Mathematical or trigonometric functions + +.nf + acos (a) arc cosine + asin (a) arc sine + atan (a [,b]) arc tangent + atan2 (a [,b]) arc tangent + cos (a) cosine + cosh (a) hyperbolic cosine + exp (a) exponential + log (a) natural logarithm + log10 (a) logarithm base 10 + sin (a) sine + sinh (a) hyperbolic sine + tan (a) tangent + tanh (a) hyperbolic tangent +.fi + +The trigonometric functions operate in units of radians. The \fIdeg\fR and +\fIrad\fR intrinsic functions (see below) can be used to convert to and from +degrees if desired. + +Type conversion functions + +.nf + bool (a) coerce to boolean + short (a) coerce to short + int (a) truncate to integer + nint (a) nearest integer + long (a) coerce to long (same as int) + real (a) coerce to real + double (a) coerce to double + str (a) coerce to string +.fi + +The numeric type conversion functions will convert a string to a number if +called with a character argument. The \fIstr\fR function will convert any +number to a string. + +Projection functions + +.nf + len (a) length of a vector + hiv (a) high value of a vector + lov (a) low value of a vector + mean (a [, ksigma]) mean of a vector + median (a) median of a vector + stddev (a [, ksigma]) standard deviation + sum (a) sum of a vector +.fi + +The projection functions take a vector as input and return a scalar value as +output. The functions \fImean\fR and \fIstddev\fR, used to compute the mean +and standard deviation of a vector, allow an optional second argument which +if given causes a K-sigma rejection to be performed. + +Miscellaneous functions + +.nf + deg (a) radians to degrees + rad (a) degrees to radians + median (a, b, c [, d [, e]]) vector median of 3-5 vectors + repl (a, n) replicate + sort (a) sort a vector + shift (a, npix) shift a vector +.fi + +The \fImedian\fR function shown here computes the vector median of several +input vectors, unlike the projection median which computes the median value +of a vector sample. \fIsort\fR sorts a vector, returning the sorted vector +as output (this can be useful for studying the statistics of a sample). +\fIshift\fR applies an integral pixel shift to a vector, wrapping around at +the endpoints. A positive shift shifts data features to the right (higher +indices). + +The \fIrepl\fR (replicate) function replicates a data element, returning a +vector of length (n * len(a)) as output. For example, this can be used to +create a dummy data array or image by replicating a constant value. + + +\fBThe Expression Database\fR + +The \fIimexpr\fR expression database provides a macro facility which can be +used to create custom libraries of functions for specific applications. A +simple example follows. + +.nf + # Sample IMEXPR expression database file. + + # Constants. + SQRTOF2= 1.4142135623730950488 + BASE_E= 2.7182818284590452353 + PI= 3.1415926535897932385 + GAMMA= .57721566490153286061 # Euler's constant + + # Functions. + div10(a) ((a) / 10) + divz(a,b) ((abs(b) < .000001) ? 0 : a / b) + + div(a,b) (div10(b) / a) + sinx (cos(I / 30.0)) + sinxy(a,b) (cos (I / a) + cos (J / b)) +.fi + +The complete syntax of a macro entry is as follows: + + <symbol>['(' arg-list ')'][':'|'='] replacement-text + +The replacement text may appear on the same line as the macro name or may +start on the next line, and may extend over multiple input lines if +necessary. If so, continuation lines must be indented. The first line +with no whitespace at the beginning of the line terminates the macro. +Macro functions may be nested. Macro functions are indistinguishable from +intrinsic functions in expressions. + + +\fBIMEXPR and Pixel Masks\fR + +Although \fIimexpr\fR has no special support for pixel masks, it was +designed to work with masks and it is important to realize how these can be +used. IRAF image i/o includes support for a special type of image, the +pixel mask or ".pl" type image. Pixel masks are used for things such as +region identification in images - any arbitrary region of an image can be +assigned a constant value in a mask to mark the region. Masks can then be +used during image analysis to identify the subset of image pixels to be +used. An image mask stored as a ".pl" file is stored in compressed form and +is typically only a few kilobytes in size. + +There are many ways to create masks, but in some cases \fIimexpr\fR itself +can be used for this purpose. For example, to create a boolean mask with +\fIimexpr\fR merely evaluate a boolean expression and specify a ".pl" file +as the output image. For example, + + cl> imexpr "a > 800" mask.pl + +will create a boolean mask "mask.pl" which identifies all the pixels in an +image with a value greater than 800. + +An example of the use of masks is the problem of combining portions of two +images to form a new image. + + cl> imexpr "c ? a : b" c=mask.pl + +This example will select pixels from either image A or B to form the output +image, using the mask assigned to operand C to control the selection. +.ih +EXAMPLES +1. Copy an image, changing the datatype to real (there are better ways to +do this of course). + + cl> imexpr a pix2 a=pix outtype=real + +2. Create a new, empty image with all the pixels set to 0. + + cl> imexpr "repl(0,512)" pix dim=512,512 + +3. Create a 1D image containing the sinc function. + + cl> imexpr "I == 10 ? 1.0 : sin(I-10.0)/(I-10)" sinc dim=20 + +4. Create a new image containing a simple test pattern consisting of a 5 +element vector repeated 100 times across each image line. + + cl> imexpr "repl((9 // 3 // 3 // 11 // 11), 100)" patt dim=500,500 + +5. Subtract the median value from each line of an image. + + cl> imexpr "a - median(a)" medimage + +6. Compute the HIV (low value) projection of an image. The result is a +transposed 1D image. + + cl> imexpr "hiv(a)" hvector + +7. Swap the left and right halves of an image. + +.nf + cl> imexpr "a // b" pix swapimage + operand a: dev$pix[256:512,*] + operand b: dev$pix[1:255,*] +.fi + +8. Create a circular mask of a given radius about a user-defined center. + +.nf + cl> type expr + (sqrt((I-b)**2 + (J-c)**2) <= d) + cl> imexpr @expr mask.pl b=256 c=256 d=100 dims=512,512 +.fi + +.ih +BUGS +The input and output images cannot be the same. +No support for type complex yet, or operations like the fourier transform. +.ih +SEE ALSO +imarith, imfunction, imcombine +.endhelp diff --git a/pkg/images/imutil/doc/imfunction.hlp b/pkg/images/imutil/doc/imfunction.hlp new file mode 100644 index 00000000..6cdef58e --- /dev/null +++ b/pkg/images/imutil/doc/imfunction.hlp @@ -0,0 +1,130 @@ +.help imfunction Aug91 images.imutil +.ih +NAME +imfunction -- Apply a function to the image pixel values +.ih +USAGE +imfunction input output function +.ih +PARAMETERS +.ls input +The input image list. +.le +.ls output +Output image list. The number of output images must match the number of +input images. If the output image list equals the input image list +the input images are overwritten. +.le +.ls function +Function to be applied to the input pixels. The options are: +.ls log10 +Take the logarithm to base 10 of an image. Negative and zero-valued +pixels will be assigned the value -MAX_EXPONENT. +.le +.ls alog10 +Taken the antilogarithm to base 10 of the image. Positive out-of-bounds +pixel values will be assigned the value MAX_REAL, negative out-of-bounds +pixel values will be assigned the value 0.0. +.le +.ls ln +Take the natural logarithm of an image. Negative and zero-valued pixels +will be assigned the value - ln (10.) * MAX_EXPONENT. +.le +.ls aln +Take the antilogarithm to base e of an image. Positive out-of-bounds pixel +values will be assigned the value MAX_REAL, negative out-of-bounds +pixel values will be assigned the value 0.0 +.le +.ls sqrt +Take the square root of an image. Negative pixel values will be assigned +the value 0.0. +.le +.ls square +Take the square of an image. +.le +.ls cbrt +Take the cube root of an image. +.le +.ls cube +Take the cube of an image. +.le +.ls abs +Take the absolute value of an image. +.le +.ls neg +Take the negative of an image. +.le +.ls cos +Take the cosine of an image. +.le +.ls sin +Take the sine of an image. +.le +.ls tan +Take the tangent of an image. +.le +.ls acos +Take the arc-cosine of an image. The output pixels will lie between +0.0 and PI. +.le +.ls asin +Take the arc-sine of an image. The output pixels will lie between -PI/2 +and +PI/2. +.le +.ls atan +Take the arc-tangent of an image. The output pixels will lie between +-PI/2 and +PI/2. +.le +.ls hcos +Take the hyperbolic cosine of an image. Positive or negative +out-of-bounds pixels will be assigned the value MAX_REAL. +.le +.ls hsin +Take the hyperbolic sine of an image. Positive and negative out-of-bounds +pixel values will be assigned the values MAX_REAL and -MAX_REAL respectively. +.le +.ls htan +Take the hyperbolic tangent of an image. +.le +.ls reciprocal +Take the reciprocal of an image. Zero-valued pixels will be assigned +the output value 0.0 +.le +.le +.ls verbose = yes +Print messages about actions taken by the task? +.le + +.ih +DESCRIPTION + +The selected function \fIfunction\fR is applied to the pixel values of all +the input images \fIinput\fR to create the pixel values of the output +images \fIoutput\fR. The number of output images must equal the number of +input images. If the output image name is the same as the input image name +the input image will be overwritten. + +If the input image is type real or double the output image will +be of type real or double respectively. If the input image is type +ushort then the output image will be type real. If the input image is one of +the remaining integer data types, then the output image will be type +real, unless function is "abs" or "neg", in which case the output +data type will be the same as the input data type. + +Values of the machine dependent constants MAX_REAL and MAX_EXPONENT can be +found in the file "hlib$mach.h". + +.ih +EXAMPLES + +1. Take the logarithm of the pixel values of images in1 and in2 and write +the results to out1 and out2. + +.nf + cl> imfunction in1,in2 out1,out2 log10 +.fi + +.ih +SEE ALSO +imarith,imreplace +.endhelp diff --git a/pkg/images/imutil/doc/imgets.hlp b/pkg/images/imutil/doc/imgets.hlp new file mode 100644 index 00000000..12fa2a74 --- /dev/null +++ b/pkg/images/imutil/doc/imgets.hlp @@ -0,0 +1,70 @@ +.help imgets Jan85 images.imutil +.ih +NAME +imgets -- get the value of an image header parameter as a string +.ih +USAGE +imgets image param +.ih +PARAMETERS +.ls image +Name of the image to be accessed. +.le +.ls param +Name of the parameter whose value is to be returned. +.le +.ls value = "" +The value of the parameter, returned as a string. +.le +.ih +DESCRIPTION +The value of the parameter \fIparam\fR of the image \fIimage\fR is returned +as a string in the output parameter \fIvalue\fR. The CL type coercion +functions \fIint\fR and \fIreal\fR may be used to decode the returned +value as an integer or floating point value. Both standard image header +parameters and special application or instrument dependent parameters may be +accessed. If the parameter cannot be found a warning message is printed and +the value "0" is returned. Parameter names are case sensitive. + +The following standard image header parameters may be accessed with +\fBimgets\fR: + +.nf + i_pixtype pixel type (short, real, etc.) + i_naxis number of dimensions + i_naxis[1-7] length of the axes (x=1,y=2) + i_minpixval minimum pixel value or INDEF + i_maxpixval maximum pixel value or INDEF + i_title image title string + i_pixfile pixel storage file name +.fi + +This task is most useful for image parameter access from within CL scripts. +The task \fBimheader\fR is more useful for just looking at the image header +parameters. +.ih +EXAMPLES +1. Fetch the instrument parameter "HA" (hour angle) from the image header of +the image "nite1.1001", and compute and print the hour angle in degrees: + +.ks +.nf + cl> imgets nite1.1001 HA + cl> = real(imgets.value) * 15.0 + 42.79335 +.fi +.ke + +2. Print the number of pixels per line in the same image. + +.ks +.nf + cl> imgets nite1.1001 i_naxis1 + cl> = int(imgets.value) + 1024 +.fi +.ke +.ih +SEE ALSO +imheader, hedit, hselect +.endhelp diff --git a/pkg/images/imutil/doc/imheader.hlp b/pkg/images/imutil/doc/imheader.hlp new file mode 100644 index 00000000..c32feb0a --- /dev/null +++ b/pkg/images/imutil/doc/imheader.hlp @@ -0,0 +1,62 @@ +.help imheader Jun97 images.imutil +.ih +NAME +imheader -- list header parameters for a list of images +.ih +USAGE +imheader [images] +.ih +PARAMETERS +.ls images +List of IRAF images. +.le +.ls imlist = "*.imh,*.fits,*.pl,*.qp,*.hhh" +The default IRAF image name template. +.le +.ls longheader = no +Print verbose image header. +.le +.ls userfields = yes +If longheader is set print the information in the user area. +.le +.ih +DESCRIPTION +IMHEADER prints header information in various formats for the list of IRAF +images specified by \fIimages\fR, or by the default image name template +\fIimlist\fR. If \fIlongheader\fR = no, the image name, +dimensions, pixel type and title are printed. If \fIlongheader\fR = yes, +information on the create and modify dates, image statistics and so forth +are printed. Non-standard IRAF header information can be printed by +setting \fIuserfields\fR = yes. + +.ih +EXAMPLES + +1. Print the header contents of a list of IRAF fits images. + +.nf + cl> imheader *.fits +.fi + +2. Print the header contents of a list of old IRAF format images in verbose +mode. + +.nf + cl> imheader *.imh lo+ +.fi + +3. Print short headers for all IRAF images of all types, e.g. imh, fits etc +in the current directory. + +.nf + cl> imheader +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imgets, hedit, hselect +.endhelp diff --git a/pkg/images/imutil/doc/imhistogram.hlp b/pkg/images/imutil/doc/imhistogram.hlp new file mode 100644 index 00000000..970f07fc --- /dev/null +++ b/pkg/images/imutil/doc/imhistogram.hlp @@ -0,0 +1,111 @@ +.help imhistogram Nov89 images.imutil +.ih +NAME +imhistogram -- print or plot the histogram of an image +.ih +USAGE +imhistogram image +.ih +PARAMETERS +.ls image +The name of the image or image subsection whose histogram is to be calculated. +.le +.ls z1 = INDEF, z2 = INDEF +The minimum and maximum histogram intensity. The image minimum and maximum +pixel values are used by default. +.le +.ls binwidth = INDEF +The resolution of the histogram in counts. If \fIbinwidth\fR is not defined, +the parameter \fInbins\fR determines the histogram resolution. +.le +.ls nbins = 512 +The number of bins in, or resolution of, the histogram. +The \fInbins\fR parameter is overridden if \fIbinwidth\fR is defined. +.le +.ls autoscale = yes +In the case of integer data, automatically adjust \fInbins\fR and +\fIz2\fR to avoid aliasing effects. +.le +.ls top_closed = no +Include z2 in the top bin? Each bin of the histogram is a subinterval +that is half open at the top. \fITop_closed\fR decides whether those +pixels with values equal to z2 are to be counted in the histogram. If +\fBtop_closed\fR is yes, the top bin will be larger than the other bins. +.le +.ls hist_type = "normal" +The type of histogram to plot or list. The choices are "normal", +"cumulative", "difference", or "second_difference". The two +"difference" options are calculated as forward differences, i.e., +diff[n] = hist[n+1] - hist[n]. +.le +.ls listout = no +List instead of plot the histogram? The list is never log scaled. +.le +.ls plot_type = "line" +The plot vector type. The options are "line" and "box". +.le +.ls logy = yes +Use log scaling on the y-axis of the plot? +.le +.ls device = "stdgraph" +The output graphics device. +.le +.ih +DESCRIPTION +\fIimhistogram\fR calculates the histogram of the IRAF image +\fIimage\fR using the parameters \fInbins\fR, \fIz1\fR and \fIz2\fR. +If either \fIz1\fR or \fIz2\fR is undefined the image minimum or +maximum is used. If \fIlistout\fR = no, the histogram is plotted on +the graphics device \fIdevice\fR in the vector mode specified by +\fIplot_type\fR. The plot may be log scaled if \fIlogy\fR = yes (the +default). If \fIlistout\fR = yes, the histogram is listed on the +standard output. + +In addition to producing the "normal" histogram, the task will also +calculate cumulative and marginal (forward difference) histograms +depending on the choice of the \fIhist_type\fR parameter (choices +are: "normal", "cumulative", "difference", and "second_difference"). +The plot will be labeled by the type of histogram as well as the image +name and title and the binning parameters. + +Each bin of the histogram is defined to be half open at the top. This +results in an ambiguity deciding whether those pixels with z=z2 are +included in the topmost bin. This decision is left to the user via the +\fItop_closed\fR parameter. This is usually only important with integer +images and histograms with few bins. +.ih +EXAMPLES +1. Output the histogram of an image to a file. + + cl> imhist M51.imh li+ nbins=100 > fits1.hst + +2. Plot the histogram of another image between the values 0 and 2000. + + cl> imhist M31.imh nbins=100 z1=0. z2=2000. + +3. Ditto, but set the histogram resolution explicitly to avoid +smoothing the histogram. + + cl> imhist M31.imh nbins=100 z1=0 z2=2000 nbins=2001 + +4. Plot the cumulative histogram. This is most useful for images with +fairly flat "normal" histograms. + + cl> imhist R50.imh hist=cum +.ih +BUGS +If the resolution of the histogram (number of bins) is a non-integral multiple +of the intensity resolution of the data (number of possible intensity values), +then \fIaliasing\fR can occur. The effect is to cause periodic zero dropouts +(for an oversampled histogram) or excess-valued bins (for a slightly +undersampled histogram). The \fIautoscaling\fR feature, if enabled, will +adjust the histogram parameters to avoid such aliasing effects for integer +data. This is not possible for floating point data, however, in which case +aliasing is certainly possible and can only be avoided by manually adjusting +the histogram parameters. One should also be aware that \fIsmoothing\fR of +the histogram will occur whenever the data range exceeds the histogram +resolution. +.ih +SEE ALSO +listpixels, plot.graph, proto.mkhistogram +.endhelp diff --git a/pkg/images/imutil/doc/imjoin.hlp b/pkg/images/imutil/doc/imjoin.hlp new file mode 100644 index 00000000..0c5d8245 --- /dev/null +++ b/pkg/images/imutil/doc/imjoin.hlp @@ -0,0 +1,70 @@ +.help imjoin Jan97 images.imutil +.ih +NAME +imjoin -- join images along a specified axis +.ih +USAGE +imjoin input output join_dimension +.ih +PARAMETERS +.ls input +The list of input images to be joined. The input images must have the +same dimensionality and the same size along all dimensions but the join +dimension. +.le +.ls output +The output combined image. +.le +.ls join_dimension +The image dimension along which the input images will be joined. +.le +.ls pixtype = "" +The output image pixel type. The options are in order of increasing +precedence "s" (short), "u" (unsigned short), "i" (integer), +"l" (long integer), "r" (real), "d" (double), and "x" (complex). +If the output image pixel type is not specified, it defaults to highest +precedence input image datatype. +.le +.ls verbose = yes +Print messages about actions taken by the task ? +.le + +.ih +DESCRIPTION + +IMJOIN creates a single output image \fIoutput\fR by joining a list of input +images \fIinput\fR along a specified dimension \fIjoin_dimension\fR. IMJOIN +can be used to create a single long 1-dimensional image from a list of shorter +1-dimensional images, or to piece together a set of 3-dimensional images into +larger 3-dimensional images along either the x, y, or z directions. The input +images must all have the same number of dimensions and the same size along +all dimensions by the join dimension. The output image inherits the +world coordinates system if any of the first input image. + +.ih +EXAMPLES + +.nf +1. Join a list of 1-dimensional spectra into a single long output spectrum. + + cl> imjoin @inlist output 1 + +2. Join three datacubes along the z direction. + + cl> imjoin c1,c2,c3 c123 3 + +.fi + +.ih +TIMINGS + +.ih +BUGS + +On some systems there are limitations on the number of input images that +can be joined in a single execution of IMJOIN. + +.ih +SEE ALSO +imstack, imslice, imtile +.endhelp diff --git a/pkg/images/imutil/doc/imrename.hlp b/pkg/images/imutil/doc/imrename.hlp new file mode 100644 index 00000000..dbba949b --- /dev/null +++ b/pkg/images/imutil/doc/imrename.hlp @@ -0,0 +1,50 @@ +.help imrename Apr89 images.imutil +.ih +NAME +imrename -- rename one or more images +.ih +USAGE +imrename oldnames newnames +.ih +PARAMETERS +.ls oldnames +An image template specifying the names of the images to be renamed. +.le +.ls newnames +Either an image template specifying the new names for the images, +or the name of the directory to which the images are to be renamed (moved). +.le +.ls verbose = no +If verbose output is enabled a message will be printed on the standard output +recording each rename operation. +.le +.ih +DESCRIPTION +The \fBimrename\fR task renames one or more images. The ordinary \fIrename\fR +task cannot be used to rename images since an image may consist of more than +one file. +.ih +EXAMPLES +1. Rename the image "pix" to "wfpc.1". + + cl> imrename pix wfpc.1 + +2. Rename all the "nite1*" images as "nite1_c". + + cl> imrename nite1.*.imh nite1%%_c%.*.imh + +3. Move the images in logical directory "dd" to the current directory. + + cl> imrename dd$*.imh . + +4. Move the pixel files associated with the images in the current directory +to a subdirectory "pix" of the current directory. + +.nf + cl> reset imdir = HDR$pix/ + cl> imrename *.imh . +.fi +.ih +SEE ALSO +imcopy, imdelete, imheader +.endhelp diff --git a/pkg/images/imutil/doc/imreplace.hlp b/pkg/images/imutil/doc/imreplace.hlp new file mode 100644 index 00000000..80e9f12c --- /dev/null +++ b/pkg/images/imutil/doc/imreplace.hlp @@ -0,0 +1,72 @@ +.help imreplace Dec97 images.imutil +.ih +NAME +imreplace -- replace pixels in a window by a constant +.ih +USAGE +imreplace images value lower upper +.ih +PARAMETERS +.ls images +Images in which the pixels are to be replaced. +.le +.ls value +Replacement value for pixels in the window. +.le +.ls imaginary = 0. +Replacement value for pixels in the windoe for the imaginary part of +complex data. +.le +.ls lower = INDEF +Lower limit of window for replacing pixels. If INDEF then all pixels +are above \fIlower\fR. For complex images this is the magnitude +of the pixel values. For integer images the value is rounded up +to the next higher integer. +.le +.ls upper = INDEF +Upper limit of window for replacing pixels. If INDEF then all pixels +are below \fIupper\fR. For complex images this is the magnitude +of the pixel values. For integer images the value is rounded down +to the next lower integer. +.le +.ls radius = 0. +Additional replacement radius around pixels which are in the replacement +window. If a pixel is within this distance of a pixel within the replacement +window it is also replaced with the replacement value. Distances are +measured between pixel centers which are have integer coordinates. +.le +.ih +DESCRIPTION +The pixels in the \fIimages\fR between \fIlower\fR and \fIupper\fR, +and all other pixels with a distance given by \fIradius\fR, +are replaced by the constant \fIvalue\fR. The special value INDEF in +\fIlower\fR and \fIupper\fR corresponds to the minimum and maximum +possible pixel values, respectively. + +For complex images the replacement value is specified as separate +real and imaginary and the thresholds are the magnitude. For +integer images the thresholds are used as inclusive limits +so that, for example, the range 5.1-9.9 affets pixels 6-9. +.ih +EXAMPLES +1. In a flat field calibration which has been scaled to unit mean replace +all response values less than or equal to 0.8 by 1. + + cl> imreplace calib 1 upper=.8 + +2. Set all pixels to zero within a section of an image. + + cl> imreplace image[1:10,5:100] 0 +.ih +REVISIONS +.ls IMREPLACE V2.11.1 +A replacement radius to replace additional pixels was added. +.le +.ls IMREPLACE V2.11 +The lower value is now rounded up for integer images so that a range +like 5.1-9.9 affects pixels 6-9 instead of 5-9. +.le +.ih +SEE ALSO +imexpr +.endhelp diff --git a/pkg/images/imutil/doc/imslice.hlp b/pkg/images/imutil/doc/imslice.hlp new file mode 100644 index 00000000..368240d0 --- /dev/null +++ b/pkg/images/imutil/doc/imslice.hlp @@ -0,0 +1,58 @@ +.help imslice Feb90 images.imutil +.ih +NAME +imslice -- slice an image into images of lower dimension +.ih +USAGE +imslice input output slicedim +.ih +PARAMETERS +.ls input +The list of input images to be sliced. The input images must have a +dimensionality greater than one. +.le +.ls output +The root name of the output images. For each n-dimensional input +image m (n-1)-dimensional images will be created, where m is the +length of the axis to be sliced. The sequence number m will +be appended to the output image name. +.le +.ls slice_dimension +The dimension to be sliced. +.le +.ls verbose = yes +Print messages about actions taken. +.le +.ih +DESCRIPTION +The n-dimensional images \fIinput\fR are sliced into m (n-1)-dimensional +images \fIoutput\fR, where m is the length of the axis of the input +image to be sliced. A sequence number from 1 to m is appended to output +to create the output image name. +.ih +EXAMPLES +1. Slice the 3-D image "datacube" into a list of 2D images. A list of +images called plane001, plane002, plane003 ... will be created. + +.nf + im> imslice datacube plane 3 +.fi + +2. Slice the list of 2-D images "nite1,nite2,nite3" into a list of 1-D images. +A new list of images nite1001, nite1002, ..., nite2001, nite2002, ..., +nite3001, nite3002 will be created. + +.nf + im> imslice nite1,nite2,nite3 nite1,nite2,nite3 2 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +If the image to be sliced is an image section, the images slices will +refer to the section not the original image. +.ih +SEE ALSO +imstack, imcopy +.endhelp diff --git a/pkg/images/imutil/doc/imstack.hlp b/pkg/images/imutil/doc/imstack.hlp new file mode 100644 index 00000000..e3eeccd9 --- /dev/null +++ b/pkg/images/imutil/doc/imstack.hlp @@ -0,0 +1,56 @@ +.help imstack Apr92 images.imutil +.ih +NAME +imstack -- stack images into an image of higher dimension +.ih +USAGE +imstack images output +.ih +PARAMETERS +.ls images +List of images to be stacked. +.le +.ls output +Name of output image created. +.le +.ls title = "*" +Title of output image. If "*" then the title defaults to that of +the first input image. +.le +.ls pixtype = "*" +Pixel datatype of output image. If "*" then the pixel datatype defaults to +that of the first input image. +.le +.ih +DESCRIPTION + +The input \fIimages\fR are stacked to form an \fIoutput\fR image having one +higher dimension than the input images, and a length of that dimension equal +to the number of input images. The input images must all be of the same +dimension and size. + +The output image inherits the world coordinate system (WCS) of the first +input image. If the dimension of the input image WCS is greater than or +equal to the dimension of the output image, the input WCS is copied to the +output image WCS without modification. Otherwise the input image WCS +dimension is incremented by 1 and copied to the output image WCS, the input +WCS coordinate transformations for each input image axis are copied to the +output image WCS without modification, and the new output image axis is +assigned a WCS type of 'linear' and the identity transformation. + +.ih +EXAMPLES + +1. Stack a set of four two dimensional images: + + cl> imstack image* image.3d + +2. To stack a section of images: + + cl> imstack image*[1:10,1:10] newimage +.ih +BUGS +.ih +SEE ALSO +imslice +.endhelp diff --git a/pkg/images/imutil/doc/imstat.hlp b/pkg/images/imutil/doc/imstat.hlp new file mode 100644 index 00000000..ed5183d9 --- /dev/null +++ b/pkg/images/imutil/doc/imstat.hlp @@ -0,0 +1,121 @@ +.help imstatistics Feb01 images.imutil +.ih +NAME +imstatistics -- compute and print image pixel statistics +.ih +USAGE +imstatistics images +.ih +PARAMETERS +.ls images +The input images or image sections for which pixel statistics are to be +computed. +.le +.ls fields = "image,npix,mean,stddev,min,max" +The statistical quantities to be computed and printed. +.le +.ls lower = INDEF +The minimum good data limit. All pixels are above the default value of INDEF. +.le +.ls upper = INDEF +The maximum good data limit. All pixels are above the default value of INDEF. +.le +.ls nclip = 0 +The maximum number of iterative clipping cycles. By default no clipping is +performed. +.le +.ls lsigma = 3.0 +The low side clipping factor in sigma. +.le +.ls usigma = 3.0 +The high side clipping factor in sigma. +.le +.ls binwidth = 0.1 +The width of the histogram bins used for computing the midpoint (estimate +of the median) and the mode. +The units are in sigma. +.le +.ls format = yes +Label the output columns and print the result in fixed format. If format +is "no" no column labels are printed and the output is in free format. +.le +.ls cache = no +Cache the image data in memory ? This can increase the efficiency of the +task if nclip > 0 or either of the midpt and mode statistics are computed. +.le +.ih +DESCRIPTION +The statistical quantities specified by the parameter \fIfields\fR are +computed and printed for each image in the list specified by \fIimages\fR. +The results are printed in tabular form with the fields listed in the order +they are specified in the fields parameter. The available fields are the +following. + +.nf + image - the image name + npix - the number of pixels used to do the statistics + mean - the mean of the pixel distribution + midpt - estimate of the median of the pixel distribution + mode - the mode of the pixel distribution + stddev - the standard deviation of the pixel distribution + skew - the skew of the pixel distribution + kurtosis - the kurtosis of the pixel distribution + min - the minimum pixel value + max - the maximum pixel value +.fi + +The mean, standard deviation, skew, kurtosis, min and max are computed in a +single pass through the image using the expressions listed below. +Only the quantities selected by the fields parameter are actually computed. + +.nf + mean = sum (x1,...,xN) / N + y = x - mean + variance = sum (y1 ** 2,...,yN ** 2) / (N-1) + stddev = sqrt (variance) + skew = sum ((y1 / stddev) ** 3,...,(yN / stddev) ** 3) / (N-1) + kurtosis = sum ((y1 / stddev) ** 4,...,(yN / stddev) ** 4) / (N-1) - 3 +.fi + +The midpoint and mode are computed in two passes through the image. In the +first pass the standard deviation of the pixels is calculated and used +with the \fIbinwidth\fR parameter to compute the resolution of the data +histogram. The midpoint is estimated by integrating the histogram and +computing by interpolation the data value at which exactly half the +pixels are below that data value and half are above it. The mode is +computed by locating the maximum of the data histogram and fitting the +peak by parabolic interpolation. + +.ih +EXAMPLES +1. To find the number of pixels, mean, standard deviation and the minimum +and maximum pixel value of a bias region in an image. + +.nf + cl> imstat flat*[*,1] + # IMAGE NPIX MEAN STDDEV MIN MAX + flat1[*,1] 800 999.5 14.09 941. 1062. + flat2[*,1] 800 999.4 28.87 918. 1413. +.fi + +The string "flat*" uses a wildcard to select all images beginning with the +word flat. The string "[*,1]" is an image section selecting row 1. + +2. Compute the mean, midpoint, mode and standard deviation of a pixel +distribution. + +.nf + cl> imstat m51 fields="image,mean,midpt,mode,stddev" + # IMAGE PIXELS MEAN MIDPT MODE STDDEV + M51 262144 108.3 88.75 49.4 131.3 +.fi + +.ih +BUGS +When using a very large number of pixels the accumulation of the sums +of the pixel values to the various powers may +encounter roundoff error. This is significant when the true standard +deviation is small compared to the mean. +.ih +SEE ALSO +.endhelp diff --git a/pkg/images/imutil/doc/imsum.hlp b/pkg/images/imutil/doc/imsum.hlp new file mode 100644 index 00000000..a6eb07a5 --- /dev/null +++ b/pkg/images/imutil/doc/imsum.hlp @@ -0,0 +1,132 @@ +.help imsum Sep87 images.imutil +.ih +NAME +imsum -- sum, average, or median images +.ih +USAGE +imsum input output +.ih +PARAMETERS +.ls input +Input images. +.le +.ls output +Output image. +.le +.ls title = "" +Image title for the output image. If null ("") then the title of the +first image is used. +.le +.ls hparams = "" +List of image header parameters to be summed or averaged. This feature +is only used when summing or averaging and no correction is made for +rejected pixels. It is primarily used to sum exposure times. +.le +.ls pixtype = "" +Pixel datatype for the output image. The pixel datatypes are "double", +"real", "long", "integer", "ushort", and "short" in order of precedence. +If null ("") then the calculation type is used. +The datatypes may be abbreviated to a single character. +.le +.ls calctype = "" +Calculation type. The calculation types are "double", "real", "long", +"integer", and "short" in order of precedence. If null ("") then the +highest precedence datatype of the input images is used. +If there is a mixture of "short" and "ushort" images then the highest +precedence datatype will be "int". +The calculation types may be abbreviated to a single character. +.le +.ls option = "sum" +Output options are "sum", "average", or "median". The "median" of an +even number of images takes pixel nimages/2 + 1, where nimages is the +number of images. +.le +.ls low_reject = 0 +If the option is sum or average then when this parameter +is less than 1 reject this fraction of low pixels from the sum or average +otherwise reject this number of low pixels from the sum or average. +.le +.ls high_reject = 0 +If the option is sum or average then when this parameter +is less than 1 reject this fraction of high pixels from the sum or average +otherwise reject this number of high pixels from the sum or average. +.le +.ls verbose = no +Print a log of the operation? +.le +.ih +DESCRIPTION +The input images are summed, averaged, or medianed pixel by pixel and the +result recorded in the output image. All input images must be the same +size but not necessarily of the same pixel datatype. For the sum or average +option a selected fraction or number of pixels may be rejected. The output +option "average" divides the sum by the number of pixels in the sum. The +pixel datatype of the output image may be selected or defaulted to the +calculation datatype. The calculation type may be selected or defaulted +to the highest precedence datatype of the input images. Note that a +mixture of "short" and "ushort" images has a highest precedence datatype +of "int". If all the image pixel datatypes are the same and agree with the +calculation type then this operation is maximally efficient. However, +beware of integer overflows with images of datatype short or ushort. A log +of the task name, the input image names, the output image name, the output +pixel datatype, the output option, and the pixel rejection parameters is +printed when the verbose parameter is yes. + +In addition to summing the pixels the specified image header parameters may +be summed or averaged. This is primarily used for summing image exposure +times. No correction is made for rejected pixels. +.ih +EXAMPLES +1. To sum three images: + + im> imsum frame1,frame2,frame3 sum hparams="itime,exposure" + +2. To make a median image of a set of images: + + im> imsum obs* median option=median + +where '*' is a template wildcard. + +3. To reject the lowest and highest 2 pixels and average the rest: + + im> imsum obs* avg option=average low=2 high=2 +.ih +REVISIONS +.ls IMSUM V2.11 +Now allows "ushort" data types. +.le +.ih +TIME REQUIREMENTS +The following timings are for 512 x 512 short images in which the output +image is also short and the calculation type is short. + +.nf + OPERATION CPU(sec) + 1. Sum of 3 7.4 + 2. Average of 3 13.0 + 3. Median of 3 9.9 + 4. Sum of 5 13.0 + 5. Median of 5 23.0 + 6. Sum of middle 3 of 5 45.5 + 7. Median of 7 77.8 +.fi +.ih +NOTES +Any number of images may be used. However, there is a maximum number of +images which may be open at one time. If the number of images +(of dimension >= 2) exceeds this maximum and median or pixel rejection is +used then the performance of this task will suffer due to the need to +repeatedly open and close the excess images. The maximum number is a +configurable parameter in the include file "imsum.h". + +This task has been largely replaced by the task \fBimcombine\fR. It is +still available but may be removed in the future. \fBImcombine\fR is +specially designed to deal with the case of large numbers of images. +.ih +BUGS +It is an error for the output image to have the same name as an +existing image. Beware of integer overflows when summing short images. +.ih +SEE ALSO +imcombine +.endhelp diff --git a/pkg/images/imutil/doc/imtile.hlp b/pkg/images/imutil/doc/imtile.hlp new file mode 100644 index 00000000..b3a26924 --- /dev/null +++ b/pkg/images/imutil/doc/imtile.hlp @@ -0,0 +1,151 @@ +.help imtile Jan97 images.imutil +.ih +NAME +imtile -- mosaic a list of same size images into a tile pattern +.ih +USAGE +imtile input output nctile nltile +.ih +PARAMETERS +.ls input +The list of input image tiles to be mosaiced. The image tile list is assumed +to be ordered by row, column, or in a raster pattern. If the image tile list +is not in order then the files or sections tasks plus the editor must be used +to construct an ordered image tile list. The images in the input list must +all be the same size. +.le +.ls output +The name of the output image. +.le +.ls nctile +The number of image tiles to be placed along a row of the output image. +.le +.ls nltile +The number of image tiles to be placed along a column of the output image. +.le +.ls trim_section = "[*,*]" +The section of the input image tiles to be inserted into the output image. +Trim_section can be used to flip and / or trim the individual image tiles +before adding them to the mosaic. For example if we want to flip each +image tile around the y axis before adding it to the mosaic, then +\fItrim_section\fR should be set to "[*,-*]". +.le +.ls missing_input = "" +The list of missing image tiles. For example if image tiles 3 to 5 and +10 from a sequence of image tiles are missing then \fImissing_input\fR = +"3-5,10". This parameter uses the IRAF ranges syntax. The number of missing +image tiles plus the number of input image tiles must equal \fInctile\fR * +\fInltile\fR. +.le +.ls start_tile = "ll" +The position of the first input image tile placed in the output image mosaic. +The four options are "ll" for lower left corner, "lr" for lower right corner, +"ul" for upper left corner and "ur" for upper right corner. +.le +.ls row_order = yes +Add the input image tiles to the output image in row order. If row_order is +"no" then column order is used instead. +.le +.ls raster_order = no +Add the input image tiles to the output image in a raster pattern or return +to the start of a column or a row before adding a new image tile ? +.le +.ls median_section = "" +The section of each input image tile used to compute the median value. If +\fImedian_section\fR is the null string then the medians are not computed. +If \fImedian_section\fR is "[*,*]" the entire input image tile is used to +compute the median. +.le +.ls subtract = no +Subtract the median value from each input image tile before placing the +tile in the output image? +.le +.ls ncols = INDEF +The number of columns in the output image. If \fIncols\fR is INDEF then +the program will compute the number of columns using the size of the input +image tiles, \fInctile\fR, and \fIncoverlap\fR. +.le +.ls nlines = INDEF +The number of lines in the output image. If \fInlines\fR is INDEF then +the program will compute the number of lines using the size of the input +image tiles, \fInltile\fR and \fInloverlap\fR. +.le +.ls ncoverlap = -1 +The number of columns between adjacent tiles in the output image. A negative +value specifies the amount of column space between adjacent tiles. A positive +value specifies the amount of column overlap on adjacent tiles. +.le +.ls nloverlap = -1 +The number of lines between adjacent tiles in the output image. A negative +value specifies the amount of lines space between adjacent tiles. A positive +value specifies the amount of line overlap on adjacent tiles. +.le +.ls ovalue = 0.0 +The output image pixel value in regions undefined by the list of input +image tiles. +.le +.ls opixtype = "r" +The pixel type of the output image. The options are "s" (short integer), +"i" (integer), "u" (ushort), "l" (long integer), "r" (real) and +"d" for double precision. +.le +.ls verbose = yes +Print messages about the progress of the task? +.le + +.ih +DESCRIPTION + +IMTILE takes the list of same size input images (image tiles) specified by +\fIinput\fR and combines them into a tiled output image mosaic \fIoutput\fR. +The order in which the input image tiles are placed in the output image is +determined by the parameters \fIstart_tile\fR, \fIrow_order\fR and +\fIraster_order\fR. The orientation of each individual image tile in the +output image is set by the \fItrim_section\fR parameter. + +IMTILE uses the input image tile size, the number of image tiles, the +\fIncoverlap\fR and \fRnloverlap\fI parameters, and the \fInctile\fR and +\fInltile\fR parameters to compute the size of the output image. An image +of size larger than the minimum required can be specified by setting the +\fIncols\fR and \fInlines\fR parameters. The pixel type of the output +image is specified by the \fIopixtype\fR parameter and undefined +regions of the output image are assigned the value \fIovalue\fR. + +The median of a section of each input image tile is computed by setting +the \fImedian_section\fR parameter, and the computed median is subtracted +from the input image tiles if the \fIsubtract\fR parameter is set to "yes". +Task action messages will be printed on the standard output +if \fIverbose\fR is set to yes. + +.ih +EXAMPLES + +1. Mosaic a list of 64 images onto an 8 by 8 grid in column order +starting in the upper right hand corner. Allow one blank column and row +between each subraster. + +.nf + cl> imtile @imlist mosaic 8 8 ncoverlap=-1 nloverlap=-1 \ + start_tile="ur" row- +.fi + +2. Mosaic a list of 62 images onto an 8 by 8 grid in column order +starting in the upper right hand corner. Allow one blank column and row +between each subraster. Subrasters 3 and 9 in the sequence do not exist +and are to be replaced in the output image with an unknown value of -1.0. + +.nf + cl> imtile @imlist mosaic 8 8 nxoverlap=-1 nyoverlap=-1 \ + start_corner="ur" row- missing_input="3,9", ovalue=-1.0 +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +.ih +SEE ALSO +imcombine +.endhelp diff --git a/pkg/images/imutil/doc/listpixels.hlp b/pkg/images/imutil/doc/listpixels.hlp new file mode 100644 index 00000000..48ea89eb --- /dev/null +++ b/pkg/images/imutil/doc/listpixels.hlp @@ -0,0 +1,191 @@ +.help listpixels Apr92 images.imutil +.ih +NAME +listpixels -- print the pixel values for a list of images +.ih +USAGE +listpixels images +.ih +PARAMETERS +.ls images +Images or list of image sections whose pixels are to be printed. +.le +.ls wcs = "logical" +The world coordinate system to be used for coordinate output. The following +standard systems are defined. +.ls logical +Logical coordinates are image pixel coordinates relative to the input +image. For example the pixel coordinates of the lower left corner +of an image section will always be (1,1) in logical units regardless of +their values in the original image. +.le +.ls physical +Physical coordinates are image pixel coordinates with respect to the original +image. For example the pixel coordinates of the lower left corner +of an image section will be its coordinates in the original image, +including the effects of any linear transformations done on that image. +Physical coordinates are invariant with respect to transformations +of the physical image matrix. +.le +.ls world +World coordinates are image pixel coordinates with respect to the +current default world coordinate system. For example in the case +of spectra world coordinates would most likely be in angstroms. +The default world coordinate system is the system named by the environment +variable \fIdefwcs\fR if defined in the user environment and present in +the image world coordinate system description, else it is the first user +world coordinate system defined for the image, else physical coordinates +are returned. +.le + +In addition to these three reserved world coordinate system names, the names +of any user world coordinate system defined for the image may be given. +.le +.ls formats = "" +The default output formats for the pixel coordinates, one format +per axis, with the individual formats separated by whitespace . +If formats are undefined, listpixels uses the formatting options +stored with the WCS in the image header. If the WCS formatting options +are not stored in the image header, then listpixels uses a default +value. +.le +.ls verbose = no +Print a title line for each image whose pixels are to be listed. +.le +.ih +DESCRIPTION +The pixel coordinates in the world coordinates system specified by +\fIwcs\fR and using the formats specified by \fIformats\fR are +printed on the standard output on the standard output followed by +the pixel value. +.ih +FORMATS +A format specification has the form "%w.dCn", where w is the field +width, d is the number of decimal places or the number of digits of +precision, C is the format code, and n is radix character for +format code "r" only. The w and d fields are optional. The format +codes C are as follows: + +.nf +b boolean (YES or NO) +c single character (c or '\c' or '\0nnn') +d decimal integer +e exponential format (D specifies the precision) +f fixed format (D specifies the number of decimal places) +g general format (D specifies the precision) +h hms format (hh:mm:ss.ss, D = no. decimal places) +m minutes, seconds (or hours, minutes) (mm:ss.ss) +o octal integer +rN convert integer in any radix N +s string (D field specifies max chars to print) +t advance To column given as field W +u unsigned decimal integer +w output the number of spaces given by field W +x hexadecimal integer +z complex format (r,r) (D = precision) + + +Conventions for w (field width) specification: + + W = n right justify in field of N characters, blank fill + -n left justify in field of N characters, blank fill + 0n zero fill at left (only if right justified) +absent, 0 use as much space as needed (D field sets precision) + + +Escape sequences (e.g. "\n" for newline): + +\b backspace (not implemented) +\f formfeed +\n newline (crlf) +\r carriage return +\t tab +\" string delimiter character +\' character constant delimiter character +\\ backslash character +\nnn octal value of character + +Examples + +%s format a string using as much space as required +%-10s left justify a string in a field of 10 characters +%-10.10s left justify and truncate a string in a field of 10 characters +%10s right justify a string in a field of 10 characters +%10.10s right justify and truncate a string in a field of 10 characters + +%7.3f print a real number right justified in floating point format +%-7.3f same as above but left justified +%15.7e print a real number right justified in exponential format +%-15.7e same as above but left justified +%12.5g print a real number right justified in general format +%-12.5g same as above but left justified + +%h format as nn:nn:nn.n +%15h right justify nn:nn:nn.n in field of 15 characters +%-15h left justify nn:nn:nn.n in a field of 15 characters +%12.2h right justify nn:nn:nn.nn +%-12.2h left justify nn:nn:nn.nn + +%H / by 15 and format as nn:nn:nn.n +%15H / by 15 and right justify nn:nn:nn.n in field of 15 characters +%-15H / by 15 and left justify nn:nn:nn.n in field of 15 characters +%12.2H / by 15 and right justify nn:nn:nn.nn +%-12.2H / by 15 and left justify nn:nn:nn.nn + +\n insert a newline +.fi +.ih +EXAMPLES +1. List the pixels of an image on the standard output. + +.nf + cl> listpix m81 +.fi + +2. List a subraster of the above image in logical coordinates. + +.nf + cl> listpix m81[51:55,151:155] + 1. 1. ... + 2. 1. ... + 3. 1. ... + 4. 1. ... + 5. 1. ... + 1. 2. ... + .. .. ... +.fi + +3. List the same subraster in physical coordinates. + +.nf + cl> listpix m81[51:55,151:155] wcs=physical + 51. 151. ... + 52. 151. ... + 53. 151. ... + 54. 151. ... + 55. 151. ... + 51. 152. ... + ... .... ... +.fi + +4. List a spectrum that has been dispersion corrected in angstrom units. + +.nf + cl> listpix n7027 wcs=world +.fi + +5. List the RA and DEC coordinates in hms and dms format and pixels value +for an image section where axis 1 is RA and axis 2 is DEC. + +.nf + cl> listpix m51 wcs=world formats="%H %h" +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imheader, imgets, imhistogram +.endhelp diff --git a/pkg/images/imutil/doc/minmax.hlp b/pkg/images/imutil/doc/minmax.hlp new file mode 100644 index 00000000..6e3f39b2 --- /dev/null +++ b/pkg/images/imutil/doc/minmax.hlp @@ -0,0 +1,84 @@ +.help minmax May91 images.imutil +.ih +NAME +minmax -- compute the minimum and maximum pixel values of an image +.ih +USAGE +minmax images +.ih +PARAMETERS +.ls images +Image template specifying the images to be examined. +.le +.ls force = no +Force recomputation of the minimum and maximum pixel and pixel values even if +they are noted as up to date in the image header. +.le +.ls update = yes +Update the image header with the new values (requires write permission). +.le +.ls verbose = yes +Print the image name, minimum value, and maximum value of each image +processed. +.le +.ls minval = INDEF +Set to the minimum pixel value of the last image processed. +If the pixel type of the last input image was complex, this is the real +part of the minimum value. +.le +.ls maxval = INDEF +Set to the maximum pixel value of the last image processed. +If the pixel type of the last input image was complex, this is the real +part of the maximum value. +.le +.ls iminval = INDEF +Set to the minimum imaginary part of the pixel value of the last image +processed. Only used if the pixel type of the last input image was complex. +.le +.ls imaxval = INDEF +Set to the maximum imaginary part of the pixel value of the last image +processed. Only used if the pixel type of the last input image was complex. +.le +.ls minpix = "" +Set to the minimum pixel specification of the last image processed. +.le +.ls maxpix = "" +Set to the maximum pixel specification of the last image processed. +.le +.ih +DESCRIPTION + + The \fIminmax\fR task computes the minimum and maximum pixel and pixel +values of +each of the images or image sections listed in the image template \fIimages\fR. +If the \fIforce\fR option is set the extreme values will be recomputed by +physical examination of the data, otherwise the image is examined only if the +extreme values stored in the image header are flagged as invalid. +The minimum and maximum pixel will be printed only if the force option +is enabled or if the image minimum and maximum is out of date. +If the \fIupdate\fR option is set the image header will be updated with the +newly computed values. Updating is not allowed when a section is used to +compute the new values. +.ih +EXAMPLES +1. Compute and print the minimum and maximum values of the images \fIimage1\fR +and \fIimage2\fR, updating the image header with the new values when done. + +.nf + cl> minmax image1,image2 +.fi + +2. Force update the minimum and maximum values in the image headers of all +images matching the template in the background, without printing the computed +values on the terminal. + + cl> minmax nite1.* force+ verbose- & +.ih +BUGS +The minimum and maximum pixel values are stored in the image header as values +of type real, hence some precision may be lost for images of type long integer +or double precision floating. +.ih +SEE ALSO +imheader, hedit +.endhelp diff --git a/pkg/images/imutil/doc/nhedit.hlp b/pkg/images/imutil/doc/nhedit.hlp new file mode 100644 index 00000000..27efffcc --- /dev/null +++ b/pkg/images/imutil/doc/nhedit.hlp @@ -0,0 +1,499 @@ +.help nhedit Aug08 images.imutil +.ih +NAME +nhedit - edit or view an image header interactively or using a command file +.ih +USAGE +.nf +nhedit images fields value comment +.fi +.ih +PARAMETERS +.ls images +Template specifying the images to be edited. +.le +.ls fields +Template specifying the fields to be edited in each image. The template is +expanded independently for each image against the set of all fields in the +image header. Special values for fields includes 'default_pars' that works only +with a command file; 'add_blank' to add a blank field value with a string as +value; 'add_textf' to add a text file content to the header. See description +for more details. +.le +.ls value +Either a string constant or a general expression (if the first character is +a left parenthesis) to be evaluated to compute the new value of each field. +With the rename switch the value is the new field name (keyword). +A single expression is used for all fields. The special value "." causes the +value of each field to be printed rather than edited. +.le +.ls comment +String constant for the comment section of the header card. This value will +replace the existing comment of a header or clear it if is empty (""). +The special value "." causes the field to be printed rather than edited. +.le +.ls comfile = "" +Alternate command file. If specified, the \fIfields\fR, \fIvalue\fR, and +\fIcomment\fR parameters are ignored and commands are taken from the named +file. See below for a detailed discussion and examples. +.le +.ls after = "" +Insert the new field after the named "pivot keyword". If this keyword +does not exist in the header, the new keyword is added to the end of the +image header. +.le +.ls before = "" +Insert the new field before the named "pivot keyword". If this keyword +does not exist in the header, the new keyword is added to the end of the +image header. +.le +.ls add = no +Change the operation of the editor from update to add new field. If the +field already exists it is edited. If this option is selected the field +list may name only a single field. The add switch takes precedence +over the addonly, delete, and rename switches. +.le +.ls addonly = no +Change the operation of the editor from update to add a new field. If the +field already exists it is not changed. If this option is selected the field +list may name only a single field. The addonly switch takes precedence over +the delete and rename switches. +.le +.ls delete = no +Change the operation of the editor from update to delete field. +The listed fields are deleted from each image. This takes precedence +or the rename switch. +.le +.ls rename = no +Change the operation of the editor from update field to rename field. +The listed fields are renamed in each image if they exist. The value +is parameter specifies the new keyword name. There is +no error if the field does not exist. The comment value is ignored +since this operation only affects the field name. +.le +.ls verify = yes +Interactively verify all operations which modify the image database. +The editor will describe the operation to be performed, prompting with the +new value of the parameter in the case of a field edit. Type carriage +return or "yes" to complete the operation, or enter a new value explicitly +as a string. Respond with "no" if you do not wish to change the value of +the parameter. +.le +.ls show = yes +Print a record of each operation which modifies the database upon the standard +output. Old values are given as well as new values, making it possible to +undo an edit operation. +.le +.ls update = yes +Enable updating of the image database. If updating is disabled the edit +operations are performed in memory but image headers will not be updated +on disk. +.le +.ih +DESCRIPTION + +1. Basic Usage + + The most basic functions of the image header editor are modification and +inspection of the fields of an image header. Both the "standard" and +"user" fields may be edited in the same fashion, although not all standard +fields are writable. For example, to change the value of the standard field +"title" of the image "m74" to "sky flat" and enter a comment field we +would enter the following command. + + cl> nhedit m74 title "sky flat" "comment field" + +If \fIverify\fR mode is selected the editor will print the old value of the +field and query with the new value, allowing some other value to be entered +instead, e.g.: + +.nf + cl> nhedit m74 title "sky flat" "comment field" + m74,i_title ("old title" -> "sky flat"): +.fi + +To accept the new value shown to the right of the arrow, type carriage +return or "yes" or "y" followed by carriage return. To continue without +changing the value of the field in question enter "no" or "n" followed by +carriage return. To enter some other value merely type in the new value. +If the new value is one of the reserved strings, e.g., "yes" or "no", +enter it preceded by a backslash. If verification is enabled you will +also be asked if you want to update the header, once all header fields +have been edited. This is your last chance to change your mind before +the header is modified on disk. If you respond negatively the image header +will not be updated, and editing will continue with the next image. +If the response is "q" the editor will exit entirely. + +To conveniently print the value of the field "title" without modifying +the image header, we repeat the command with the special value "." and "." +for the comment portion. + + cl> nhedit m74 title . . + +To print (or edit) the values of all header fields a field template may be +given. + + cl> nhedit m74 * . . + +To print (or edit) the values of only a few fields the field template may +be given as a list. + + cl> nhedit m74 w0,wpc . . + +To print the value of one or more fields in a set of images, an image template +may be given. Both image templates and field templates may be given if +desired. + + cl> nhedit n1.* exp . . + +Abbreviations are not permitted for field names, i.e., the given template +must match the full field name. Currently, field name matches are case +insensitive since image headers are often converted to and from FITS headers, +which are case insensitive. + + +2. Advanced Usage + + The header editor is capable of performing global edits on entire image +databases wherein the new value of each field is computed automatically at +edit time and may depend on the values of other fields in the image header. +Editing may be performed in either batch or interactive mode. An audit trail +may be maintained (via the \fIshow\fR switch and i/o redirection), permitting +restoration of the database in the event of an error. Trial runs may be made +with updating disabled, before committing to an actual edit which modifies the +database. + +The major editing functions of the \fInhedit\fR task are the following: + +.nf + update modify the value of a field or fields + addonly add a new field + add add a new field or modify an old one + delete delete a set of fields + rename rename a set of fields +.fi + +In addition, \fInhedit\fR may be used merely to inspect the values of the header +fields, without modification of the image database. + +2.1 Special header fields + +.ks +.nf + add_blank Add blank keyword field with optional comment + ex: nhedit add_blank " this is a comment with no kw" + add_textf Add the content of a text file into the header + ex: nhedit add_textf "my_text.txt" add+ +.fi +.ke + +All keyword addition can be inserted after or before an existent keyword; use +the 'after' and 'before' parameter. + +2.2 Input commands from a command file. + +All header editing command can be put together in a text file and run it as: + +nhedit file*.fits comfile=command_file.txt + +2.3 Standard header fields + + The header editor may be used to access both the standard image header +fields and any user or application defined fields. The standard header fields +currently defined are shown below. There is no guarantee that the names and/or +usage of these fields will not change in the future. + + +.ks +.nf + i_ctime int create time + i_history string history comments + i_limtime int time when min,max last updated + i_maxpixval real maximum pixel value + i_minpixval real minimum pixel value + i_mtime int time of last modify + i_naxis int number of axes (dimensionality) + i_naxis[1-7] int length of each axis + i_pixfile string pathname of pixel storage file + i_pixtype int pixel datatype code + i_title string title string +.fi +.ke + + +The standard header field names have an "i_" prefix to reduce the possibility +of a name collision with a user field name, and to distinguish the two classes +of parameters in templates. The prefix may be omitted provided the simple +name is unique. + + +2.4 Field name template + + The form of the field name list or template parameter \fIfields\fR is +equivalent to that of a filename template except that "@listfile" is not +supported, and of course the template is expanded upon the field name list +of an image, rather than upon a directory. Abbreviations are not permitted +in field names and case is not significant. Case is ignored in this context +due to the present internal storage format for the user parameters (FITS), +which also limits the length of a user field name to 8 characters. + + +2.5 Value expression + + The \fIvalue\fR parameter is a string type parameter. If the first +character in the string is a left parenthesis the string is interpreted as +an algebraic expression wherein the operands may be constants, image header +variables (field names), special variables (defined below), or calls to +intrinsic functions. The expression syntax is equivalent to that used in +the CL and SPP languages. If the value string is not parenthesized it is +assumed to be a string constant. The \fIvalue\fR string will often contain +blanks, quotes, parenthesis, etc., and hence must usually be quoted to avoid +interpretation by the CL rather than by the header editor. + +For example, the command + + cl> nhedit m74 title "title // ';ss'" "." + +would change the title to the literal string constant "title // ';ss'", +whereas the command + + cl> nhedit m74 title "(title // ';ss')" "." + +would concatenate the string ";ss" to the old title string. We require +parenthesis for expression evaluation to avoid the need to doubly quote +simple string constant values, which would be even more confusing for the +user than using parenthesis. For example, if expressions did not have to +be parenthesized, the first example in the basic usage section would have +to be entered as shown below. + + cl> nhedit m74 title '"sky flat"' # invalid command + +Expression evaluation for \fInhedit\fR, \fIhselect\fR, and similar tasks +is carried out internally by the FMTIO library routine \fBevexpr\fR. +For completeness minimal documentation is given here, but the documentation +for \fIevexpr\fR itself should be consulted if additional detail is required +or if problems occur. + + +2.5.1 operators + + The following operators are recognized in value expressions. With the +exception of the operators "?", "?=", and "@", the operator set is equivalent +to that available in the CL and SPP languages. + + +.nf + + - * / arithmetic operators + ** exponentiation + // string concatenation + ! - boolean not, unary negation + < <= > >= order comparison (works for strings) + == != && || equals, not equals, and, or + ?= string equals pattern + ? : conditional expression + @ reference a variable +.fi + + +The operators "==", "&&", and "||" may be abbreviated as "=", "&", and "|" +if desired. The ?= operator performs pattern matching upon strings. +For example, the boolean expression shown below will be true whenever the +field "title" contains the substring "sky". + + (title ?= '*sky*') + +The conditional expression operator '?', which is patterned after a similar +operator in C, is used to make IF ELSE like decisions within an expression. +The syntax is as follows: + + <bool_expr> '?' <true_expr> ':' <false_expr> + +e.g., the expression + + ((a > b) ? 1 : 0) + +has the value 1 if A is greater than B, and 0 otherwise. The datatypes +of the true and false expressions need not be the same, unlike a compiled +language. Note that if the parenthesis are omitted ambiguous forms of +the expression are possible, e.g.: + + (a > b) ? 1 : a + 1 + +could be interpreted either as + + ((a > b) ? 1 : a) + 1 +or as + (a > b) ? 1 : (a + 1) + +If the parenthesis are omitted the latter interpretation is assumed. + +The operator @ must be used to dereference variables that have names with +funny (nonalphanumeric) characters in them, forcing the variable name to +be given as a string constant. For example, the value of the expression + + @"co-flag" + +is the value of the variable "co-flag". If the variable were referenced +directly by name the "-" would be interpreted as the subtraction operator, +causing an unknown variable reference (e.g., to "co"). +The operand following the @ may be any string valued expression. +The @ operator is right associative, hence the construct "@@param" is the +value of the parameter named by the value of the parameter "param". + +An expression may contain operands of datatypes bool, int, real, and string. +Mixed mode expressions are permitted with automatic type coercion. Most type +coercions from boolean or string to other datatypes are illegal. The boolean +constants "yes" and "no" are predefined and may be used within expressions. + + +2.5.2 intrinsic functions + + A number of standard intrinsic functions are recognized within expressions. +The set of functions currently supported is shown below. + + +.nf + abs acos asin atan atan2 bool cos + exp int log log10 max min mod + nint real sin sqrt str tan +.fi + + +The trigonometric functions operate in units of degrees rather than radians. +The \fImin\fR and \fImax\fR functions may have any number of arguments up +to a maximum of sixteen or so (configurable). The arguments need not all +be of the same datatype. + +A function call may take either of the following forms: + +.nf + <identifier> '(' arglist ')' +or + <string_expr> '(' arglist ')' +.fi + +The first form is the conventional form found in all programming languages. +The second permits the generation of function names by string valued +expressions and might be useful on rare occasions. + + +2.5.3 special operands + + As noted earlier, expression operands may be constants, variables (header +fields), function calls, or references to any of the special variables. +The following special variables are recognized within expressions: + + +.nf + . A string constant, used to flag printing + $ The value of the "current field" + $F The name of the "current field" + $I The name of the "current image" + $T The current clock time (an integer value) +.fi + + +These builtin variables are especially useful for constructing context +dependent expressions. For example, the value of a field may be incremented +by 100 by assigning it the value "$ + 100". + +.ih +EXAMPLES + +1. Globally edit the database "n1", setting the value of the string parameter +"obs" to "sky" if "s-flag" is 1, to "obj" otherwise. + + cl> nhedit n1.* obs '(@"s-flag" == 1 ? "sky" : "obj")' "Observation value" + +2. Globally edit the same database, replacing the value of the parameter +"variance" by the square root of the original value. + + cl> nhedit n1.* var '(sqrt(var))' "Variance value" + +3. Replace the values of the fields A and B by the absolute value of the +original value: + + cl> nhedit n1.* a,b '(abs($))' 'Absolute value' + +4. Add a blank field with a comment after a given field (K5DX). + + cl> nhedit file.fits add_blank "INSTRUMENT DESCRIPTION " after=k5dx add+ + + Notice the use of the special field value 'add_blank' which will be +replaced by a blank keyword in the header. + +5. Add HISTORY card before a given keyword + +.nf + cl> nhedit file.fits history \ + "History text from column 9 to 80, no quotes" before=wcsdim add+ + +.fi +6. Run a command file through the first 50 extensions +.nf + + cl> for(i=1;i<51;i=i+1) { + nhedit("mymef["//i//"]",comfile="home$hh.in") + } + +.fi +7. Add a text file to the header. This will be put as HISTORY lines with +text appropriately split when long lines are encountered. Start putting the +text after the keyword KEYWN. +.nf + + cl> nhedit add_textf "mytext_file.tx" after=KEYWN add+ + + +.fi +8. Run nhedit through all the extensions in a MEF file. Assuming it is 6, then: +.nf + + cl> for(i=1;i<7;i=i+1) + nhedit("mymef.fits["//i//"]",comfi="home$myheader.txt") + +.fi +9. Run several fits files with the same set of header commands from the file +"hdrc.txt". + + cl> nhedit file*.fits commfile=hdrc.txt + +As an example the 'hdrc.txt' content can be: (Notice the 'default_pars' command) + +.nf +# +# Sample command file for nhedit task. +# +# Establish the default parameters for the rest of the commands. + +default_pars upda+ add+ show- veri- + +# Notice the use of commas if you desire. +"DETECTOR" 'Newfirm', "comment string" +ONELE 'A' "comment to A" +# +# Now delete a keyword +ONELE1 del+ show+ +add_blank " /blank keyw" + +# add a boolean value T +ONELE1 '(1==1)', "comment to A" + + "DETSIZE", '[1:2048,1:2048]' + "ENVTEM", 1.5600000000000E+01 + +# Add a field with string value 'T' +ONELEi2 'T' + +bafkeyw1 123.456 "comment to key1" before="WCSDIM" addonly+ show- +add_blank "COMMENT FOR A BLANK" after="FR-SCALE" add+ show- +history "this is a hist to append" add+ show- +history "this is a hist 22 after trim pkey" after="TRIM" add+ show- +comment "this is a comment" after="FR-SCALE" add+ show- +# END OF HDRC.TXT FILE + +.fi +.ih +SEE ALSO +hselect, hedit, mkheader, imgets, imheader +.endhelp diff --git a/pkg/images/imutil/doc/sections.hlp b/pkg/images/imutil/doc/sections.hlp new file mode 100644 index 00000000..13579b62 --- /dev/null +++ b/pkg/images/imutil/doc/sections.hlp @@ -0,0 +1,119 @@ +.help sections Dec85 images.imutil +.ih +NAME +sections -- expand an image template +.ih +USAGE +sections images +.ih +PARAMETERS +.ls images +Image template or list of images. There is no check that the names are +images and any name may be used. The thing which distinguishes an image +template from a file template is that the special characters '[' and +']' are interpreted as image sections rather than a character class +wildcard unless preceded by the escape character '!'. To explicitly +limit a wildcard template to images one should use an appropriate +extension such as ".imh". +.le +.ls option = "fullname" +The options are: +.ls "nolist" +Do not print list. +.le +.ls "fullname" +Print the full image name for each image in the template. +.le +.ls "root" +Print the root name for each image in the template. +.le +.ls "section" +Print the section for each image in the template. +.le +.le +.ls nimages +The number of images in the image template. +.le +.ih +DESCRIPTION +The image template list \fIimages\fR is expanded and the images are printed +one per line on the standard output unless the "nolist" option is given. +Other options allow selection of a portion of the image name. The number +of images in the list is determined and stored in the parameter \fInimages\fR. + +This task is used for several purposes: +.ls (1) +To verify that an image template is expanded as the user desires. +.le +.ls (2) +To create a file of image names which include image sections. +.le +.ls (3) +To create a file of new image names using the concatenation feature of the +image templates. +.le +.ls (4) +To determine the number of images specified by the user in a command language +script. +.le + +There is no check that the names are images and any name may be used. +The thing which distinguishes an \fIimage template\fR from a \fIfile +template\fR is that the special characters '[' and ']' are interpreted +as image sections rather than a character class wildcard unless +preceded by the escape character '!'. To explicitly limit a wildcard +template to images one should use an appropriate extension such as ".imh". +.ih +EXAMPLES +1. Calculate and print the number of images in a template: + +.nf + cl> sections fits*.imh opti=no + cl> = sections.nimages + cl> 7 +.fi + +2. Expand an image template: + +.nf + cl> sections fits*![3-9].imh[1:10,*] + fits003.imh[1:10,*] + fits004.imh[1:10,*] + <etc.> +.fi + +Note the use of the character class escape, image section appending, +and explicit use of the .imh extension. + +3. Create a new list of image names by adding the suffix "new": + +.nf + cl> sections jan18???//new + jan18001new + jan18002new + <etc.> +.fi + +Note the use of the append syntax. Also there is no guarantee that the +files are actually images. + +4. Subtract two sets of images: + +.nf + cl> sections objs*.imh[100:200,300:400] > objslist + cl> sections skys*.imh[100:200,300:400] > skyslist + cl> sections %objs%bck%* > bcklist + cl> imarith @objslist - @skyslist @bcklist +.fi + +Note the use of the substitution syntax. + +.ih +TIME REQUIREMENTS +.ih +BUGS +The image list is not sorted. +.ih +SEE ALSO +files +.endhelp |