wcsedit image parameter value axes1
image
The list of images for which the WCS is to be edited. Image sections are
ignored.
parameter
The WCS parameter to be edited. The WCS parameters recognized by
WCSEDIT are: 1) the FITS WCS
parameters crpix, crval, cd and, 2) the IRAF WCS parameters ltv, ltm, wtype,
axtype, units, label, and format. Only one WCS parameter may be edited at a
time.
value
The new parameter value. The numerical parameters crpix, crval, cd, ltv, and
ltm will not be updated if WCSEDIT is unable to decode the parameter value
into a legal floating point number.
axes1
The list of principal axes for which parameter is to be edited.
Axes1 can
be entered as a list of numbers separated by commas, e.g. "1,2" or as a
range, e.g. "1-2".
axes2
The list of dependent axes for which parameter is to be edited.
Axes2 can
be entered as a list of numbers separated by commas, e.g. "1,2" or as a
range, e.g. "1-2". The axes2 parameter is only required if
parameter is "cd" or "ltm".
wcs = world
The WCS to be edited. The options are: the builtin systems "world" or
"physical", or a named system, e.g. "image" or "multispec". The builtin system
"logical" may not be edited.
world
If wcs is "world" the default WCS is edited. The default WCS
is either 1) the value of the environment variable "defwcs" if
set in the user's IRAF environment (normally it is undefined) and present
in the image header,
2) the value of the "system"
attribute in the image header keyword WAT0_001 if present in the
image header or, 3) the "physical" coordinate system.
physical
If wcs is "physical", WCS is the pixel coordinate system of
the original image, which may be different from the pixel coordinate system
of the current image, if the current image is the result of an
imcopy or other geometric transformation operation. In the "physical"
coordinate system the ltv, ltm and the axis attribute
parameters wtype, axtype, units, label, and format may be edited, but the FITS
parameters crval, crpix, and cd cannot.
name
A user supplied wcs name.
If the named WCS does not exist in the image, a new one of that
name initialized to the identity transform, will be opened for editing, and
the old WCS will be destroyed. This option should only be used for creating
a totally new FITS WCS.
interactive = no
Edit the WCS interactively?
commands =
The interactive editing command prompt.
verbose = yes
Print messages about actions taken in interactive or non-interactive mode?
update = yes
Update the image header in non-interactive mode? A specific command exists
to do this in interactive mode.
In non-interactive mode WCSEDIT replaces the current value of the WCS parameter parameter with the new value value in the headers of images and prints a summary of the new WCS on the terminal. If verbose is "no" the summary is not printed. If verbose is "yes" and update is "no", the result of the editing operation is printed on the terminal but the header is not modified.
The WCS parameter parameter may be one of: crval, crpix, cd, ltv, ltm, wtype, axtype, units, label, or format in either upper or lower case. The WCS array parameters crpix, crval, ltv, wtype, axtype, units, label, and format may be edited for more than one axis at a time by setting axes1 to a range of axes values. The WCS matrix parameters cd and ltm may be edited for more than one axis at a time by setting both axes1 and axes2 to a range of values. In this case, if no axes2 values are entered, axes2 = "", the diagonal elements of the cd and ltm matrices specified by axes1 are edited. A single non-diagonal element of the cd or ltm matrices can be edited by setting axis1 and axis2 to a single number.
The user can create a new WCS from scratch by setting wcs to a name different from the name of the WCS in the image header. A new WCS with the same dimension as the image and initialized to the identity transformation is presented to the user for editing. IF THE USER UPDATES THE IMAGE HEADER AFTER EDITING THE NEW WCS, ALL PREVIOUS WCS INFORMATION IS LOST.
In interactive mode, WCSEDIT displays the current WCS on the terminal if verbose = "yes", and prompts the user for an editing command. The supported editing commands are shown below.
BASIC COMMANDS ? Print the WCSEDIT commands show Print out the current WCS update Quit WCSEDIT and update the image WCS quit Quit WCSEDIT without updating the image WCS PARAMETER DISPLAY AND EDITING COMMANDS crval [value axes1] Show/set the FITS crval parameter(s) crpix [value axes1] Show/set the FITS crpix parameter(s) cd [value axes1 [axes2]] Show/set the FITS cd parameter(s) ltv [value axes1] Show/set the IRAF ltv parameter(s) ltm [value axes1 [axes2]] Show/set the IRAF ltm parameter(s) wtype [value axes1] Show/set the FITS/IRAF axes transform(s) axtype [value axes1] Show/set the FITS/IRAF axis type(s) units [value axes1] Show/set the IRAF units(s) label [value axes1] Show/set the IRAF axes label(s) format [value axes1] Show/set the IRAF axes coordinate format(s)
Below is a list of the WCS parameters as they appear encoded in the in the IRAF image header. Parameters marked with E can be edited directly with WCSEDIT. Parameters marked with U should be updated automatically by WCSEDIT if the proper conditions are met. The remaining parameters cannot be edited with WCSEDIT. A brief description of the listed parameters is given below. For a detailed description of the meaning of these parameters, the user should consult the two documents listed in the REFERENCES section.
WCSDIM WCS dimension (may differ from image) CTYPEn U coordinate type CRPIXn E reference pixel CRVALn E world coords of reference pixel CDi_j E CD matrix CDELTn U CDi_i if CD matrix not used (input only) CROTA2 U rotation angle if CD matrix not used LTVi E Lterm translation vector LTMi_j E Lterm rotation matrix WATi_jjj U WCS attributes for axis I (wtype,axtype,units,label,format) WAXMAPii WCS axis map
The WCSDIM and WAXMAP parameters cannot be edited by WCSEDIT, unless a new WCS is created in which case WCSDIM is set to the dimension of the input image and the axis map is deleted. The FITS parameters CRPIX, CRVAL, and CD define the transformation between the world coordinate system and the pixel coordinate system of the image and may be edited directly. The more general FITS CD matrix notation supersedes the FITS CDELT/CROTA notation if both are present on input, and is used by preference on output. The FITS parameter CTYPE cannot be edited directly by WCSEDIT but is correctly updated on output using the current values of the WCS parameters wtype and axtype parameters, if there was a prexisting FITS header in the image. On input IRAF currently recognizes the following values of the FITS parameter CTYPE: RA---TAN and DEC--TAN (the tangent plane sky projection), RA---SIN and DEC--SIN (the sin sky projection), RA---ARC and DEC--ARC (the arc sky projection), LINEAR, and MULTISPEC, from which it derives the correct values for wtype and axtype.
The LTV and LTM are IRAF parameters which define the transformation between the current image pixel coordinate system and the original pixel coordinate system, if the current image was derived from a previous image by a geometric transformation, e.g. IMCOPY or IMSHIFT. Both parameters may be edited directly by WCSEDIT, but with the exception of resetting the LTV vector to 0 and the LTM matrix to the identity matrix it is not usually desirable to do so. The task WCSRESET can also be used for this purpose.
The WATi_jjj parameters are not directly accessible by WCSEDIT but the five axis attributes which are encoded under these keywords (wtype, axtype, units, label, and format) may be edited. The IRAF WCS code currently recognizes the following values for "wtype": "linear", "tan", "sin", "arc", and "multispec". If "wtype" is not defined or cannot be decoded by the WCS code "linear" is assumed. Axtype should be "ra" or "dec" if wtype is one of the sky projections "tan", "sin" or "arc", otherwise it should be undefined. WCSEDIT will combine the values of "wtype" amd "axtype" on output to produce the correct value of the FITS keyword CTYPE. The "label" and "units" parameter may be set to any string constant. Format must be set to a legal IRAF format as described in the section below.
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:
b boolean (YES or NO)
c single character (c or ' or 'nn')
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. " for newline):
backspace (not implemented)
formfeed
newline (crlf)
carriage return
tab
string delimiter character
character constant delimiter character
backslash character
n 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
insert a newline
Detailed documentation for the IRAF world coordinate system interface MWCS can be found in the file "iraf$sys/mwcs/MWCS.hlp". This file can be formatted and printed with the command "help iraf$sys/mwcs/MWCS.hlp fi+ | lprint". Details of the FITS header world coordinate system interface can be found in the document "World Coordinate Systems Representations Within the FITS Format" by Hanisch and Wells, available from our anonymous ftp archive.
1. Change the default output coordinate formats for an image with a defined FITS tangent plane projection in its header, for the RA axis (axis 1), and the DEC axis (axis 2) to %H and %h respectively. Then display the image and use rimcursor to produce a coordinate list of objects whose coordinates are printed as hh:mm:ss.s and dd:mm:ss.s respectively.
cl> wcsedit image format %H 1 cl> wcsedit image format %h 2 cl> display image 1 cl> rimcursor wcs=world > coordlist ... mark the coordinates
2. Change the default sky projection for an image with a defined tangent plane projection to one with a sin projection. Note that wtype for both axis1 and axis2 must be changed to "sin". Check the results first before doing the actual update.
cl> wcsedit image wtype sin 1-2 update- cl> wcsedit image wtype sin 1-2
3. Change the diagonal elements of the FITS cd matrix to 2.0. The off diagonal elements are 0.0. This is equivalent to resetting the image scale.
cl> wcsedit image cd 2.0 1-2 ""
4. Set the value of the FITS cd matrix elements, cd[2,1] and cd[1,2] to 0.0. This removes any rotation/skew from the WCS definition.
cl> wcsedit image cd 0.0 2 1 cl> wcsedit image cd 0.0 1 2
5. Change the FITS crval value for axis 2.
cl> wcsedit image crval 47.85 2
6. Create a totally new WCS for an image, deleting the previous WCS and set the diagonal elements of the cd matrix to 0.68. 0.68 is the scale of the 36 inch telescope at kpno.
cl> wcsedit image cd 1.5 1-2 wcs="kpno9m"
7. Interactively edit the WCS of an image. with an existing FITS header.
cl> wcsedit image interactive+
... summary of current WCS is printed on terminl
wcsedit: ?
... user types in ? to see list of wcsedit commands
wcsedit: cd 2.0 1-2
... user changes the scale of the WCS
wcsedit: format %0.3f 1-2
... user changes format so the coordinates will be printed
out with 3 decimals of precision by any tasks which
can read the WCS format parameter such as rimcursor
and listpixels
wcsedit: show
... user checks the new wcs
wcsedit: update
... user quits editor and updates the image header
8. Open and edit a new WCS for an image. Any pre-existing WCS will be destroyed, assuming that the default wcs is not "newwcs".
cl> wcsedit image wcs=newwcs intera+ wcsedit: .... wcsedit: .... ... edit in the desired values wcsedit: update ... update the image header.
The IRAF WCS code supports the dimensional reduction of images, for example creating an image with smaller dimensions than its parent, but may not be fully compatible with FITS when this occurs. In this case user may need to fix up an illegal or incorrect WCS with HEDIT or HFIX bypassing the WCS code used by WCSEDIT.
WCSEDIT does not permit the user to edit any parameters encoded in the WATi_jjj keywords other than the five listed: wtype, axtype, units, label, and format. For example WCSEDIT cannot be used to edit the "speci" parameters used by the IRAF spectral reductions code "multispec" format. The spectral reduction code itself should be used to do this, although hfix can be used to fix a serious problem should it arise.