path: root/pkg/images/imutil/doc/nhedit.hlp

.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