hedit images fields value
images
Template specifying the images to be edited.
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.
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.
add = no
Change the operation of the editor from update to add new field.
If this option is selected the field list may name only a single field.
delete = no
Change the operation of the editor from update to delete field.
The listed fields are deleted from each image.
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.
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.
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.
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 verify 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.:
cl> hedit m74 title "sky flat"
m74,i_title ("old title" -> "sky flat"):
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 show 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 commiting to an actual edit which modifies the database.
The major editing functions of the hedit task are the following:
update modify the value of a field or fields add add a new field (or modify an old one) delete delete a set of fields
In addition, hedit 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
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.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 fields 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 value 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 value 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 hedit, hselect, and similar tasks is carried out internally by the FMTIO library routine evexpr. For completeness minimal documentation is given here, but the documentation for evexpr 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.
+ - * / arithmetic operators ** exponentiation // string concatenation ! - boolean not, unary negation < <= > >= order comparision (works for strings) == != && || equals, not equals, and, or ?= string equals pattern ? : conditional expression @ reference a variable
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:
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.3.2 intrinsic functions
A number of standard intrinsic functions are recognized within expressions.
The set of functions currently supported is shown below.
The trigonometric functions operate in units of degrees rather than radians.
The min and max 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:
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:
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 the value "$ + 100".
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($))'
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 show
option and use it to undo an edit.
abs acos asin atan atan2 bool cos
exp int log log10 max min mod
nint real sin sqrt str tan
. 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)
EXAMPLES
BUGS
SEE ALSO
This page automatically generated from the iraf .hlp file. If you
would like your local iraf package .hlp files converted into HTML
please contact Dave Mills at NOAO.dmills@noao.edu