STScI Logo

wcsedit images.imcoords



wcsedit -- edit an image world coordinate system parameter


wcsedit image parameter value axes1


The list of images for which the WCS is to be edited. Image sections are ignored. If the image does not exist a data-less image header is first created with the default WCS of dimensionality given by the "wcsdim" 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.
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.
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".
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.
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.
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.
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.
wcsdim = 2
WCS dimensionality when creating a new data-less image header.
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.


WCSEDIT modifies the WCS of an existing image or creates a data-less image header of the dimensionality given by the wcsdim parameter.

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


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 '\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 (, D = no. decimal places)
m       minutes, seconds (or hours, minutes) (
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
%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


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.



Source Code · Search Form · STSDAS