diff options
Diffstat (limited to 'pkg/images/imutil/doc/nhedit.hlp')
| -rw-r--r-- | pkg/images/imutil/doc/nhedit.hlp | 499 |
1 files changed, 499 insertions, 0 deletions
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 |