STScI Logo

wcsctran images.imcoords


NAME · USAGE · PARAMETERS · DESCRIPTION · FORMATS · REFERENCES
EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

wcsctran -- use the image WCS to transform between IRAF coordinate systems

USAGE

wcsctran input output image inwcs outwcs

PARAMETERS

input
The list of input coordinate files. The number of input coordinate files must be one or equal to the number of input images. Coordinates may be entered by hand by setting input to "STDIN".
output
The list of output coordinate files. The number of coordinate files must be one or equal to the number of input images. Results may be printed on the terminal by setting output to "STDOUT".
image
The list of input images containing the WCS information.
inwcs, outwcs
The input and output coordinate systems. Coordinates in the input file are assumed to be in the input system. Coordinates are written to the output file in the output system. The options are:
logical
Logical coordinates are pixel coordinates relative to the current image. The logical coordinate system is the coordinate system used by the image input/output routines to access the image data on disk.
tv
Tv coordinates are pixel coordinates used by the ximtool and saoimage display servers. Tv coordinates include the effects of any input image section, but do not include the effects of previous linear transformations. If the input image name does not include an image section, then tv coordinates are identical to logical coordinates. If the input image name does include a section, and the input image has not been linearly transformed or copied from a parent image, tv coordinates are identical to physical coordinates.
physical
Physical coordinates are pixel coordinates invariant with respect to linear transformations of the physical image data. For example, if the current image was created by extracting a section of another image, the physical coordinates of an object in the current image will be equal to the physical coordinates of the same object in the parent image, although the logical coordinates will be different.
world
World coordinates are image coordinates in any units which are invariant with respect to linear transformations of the physical image data. For example, the ra and dec of an object will always be the same no matter how the image is linearly transformed. The default world coordinate system 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.
columns = "2 3 4 5 6 7"
The list of columns separated by whitespace or commas in the input coordinate file containing the coordinate values. The number of specified columns must be greater than or equal to the dimensionality of the input image. The coordinates are read in in the order they are specified in the columns parameter.
units = ""
The units of the input coordinate values, normally degrees for the sky projection coordinate systems and angstroms for spectral coordinate systems. The options are:
hours
Input coordinates specified in hours are converted to decimal degrees by multiplying by 15.0.
native
The internal units of the wcs. No conversions on the input coordinates are performed.

Units conversions are performed only if the input wcs is "world".

formats = ""
The format for the computed output coordinates. If the formats parameter is undefined then: 1) the value of the wcs format attribute is used if the output wcs is "world" and the attribute is defined, 2) %g format is used with the precision set to the maximum of the precision of the input coordinates and the value of the min_sigdigits parameter.
min_sigdigits = 7
The minimum precision of the output coordinates if, the formats parameter is undefined, and the output coordinate system is "world" but the wcs format attribute is undefined.
verbose = yes
Print comment lines to the output file as the task executes.

DESCRIPTION

WCSCTRAN transforms a list of coordinates, read from the input file input , from the coordinate system defined by inwcs to the coordinate system defined by outwcs using world coordinate system information in the input image image header and writes the results to the output file output .

The input coordinates are read from and written to the columns in the input / output file specified by the columns parameter. The units of the input coordinate units are assumed to be the internal units of the coordinate system as defined in the image header, normally degrees for sky projection coordinate systems and angstroms for spectral coordinate systems. For convenience input coordinates in hours are accepted and converted to decimal degrees if the units parameter is set appropriately.

The format of the output units can be set using the formats parameter. If the output formats are unspecified then the output coordinates are written using, 1) the value of wcs format attribute if outwcs = "world" and the attribute is defined, or, 2) the %g format and a precision which is the maximum of the precision of the input coordinates and the value of the min_sigdigits parameter. All remaining fields in the input file are copied to the output file without modification.

WCSCTRAN transforms coordinates from one builtin IRAF coordinate system to another. The builtin coordinate systems are "logical", "physical", and "world". For convenience WCSCTRAN also supports the "tv" coordinate system which is not a builtin IRAF system, but is used by the display server tasks XIMTOOL, SAOIMAGE, and IMTOOL.

The logical coordinate system is the pixel coordinate system of the current image. This coordinate system is the one used by the image input/output routines to access the image on disk. In the logical coordinate system, the coordinates of the pixel centers must lie within the following range: 1.0 <= x[i] <= nx[i], where x[i] is the coordinate in dimension i, nx[i] is the size of the image in dimension i, and the current maximum number of image dimensions is 7. In the case of an image section, the nx[i] refer to the dimensions of the section, not the dimensions of the full image.

The tv coordinate system is the pixel coordinate system used by the display servers XIMTOOL, SAOIMAGE, and IMTOOL. For images which are not image sections the tv and logical coordinate systems are identical. For images which are image sections the tv and physical coordinate systems are identical if the image has not undergone any prior linear transformations such as axis flips, section copies, shifts, scale changes, rotations, etc.

The physical coordinate system is the coordinate system in which the pixel coordinates of an object are invariant to successive linear transformations of the image. In this coordinate system, the pixel coordinates of an object in an image remain the same, regardless of any section copies, shifts, rotatations, etc on the image. For example, an object with the physical coordinates (x,y) in an image would still have physical coordinates (x, y) in an image which is a section of the original image.

The world coordinate system is the default coordinate system for the image. The default world coordinate system is the one named by the environment variable "defwcs" if defined in the user environment (initially it is undefined) and present in the image header; else it is the first world coordinate system defined for the image (the .imh and .hhh image format support only one wcs but the .qp format can support more); else it is the physical coordinate system.

In most cases the number of input coordinates is equal to the number of output coordinates, and both are equal to the dimensions of the input image. In some cases however, the number of output coordinates may be greater or less than the number of input coordinates. This situation occurs if the input image has been dimensionally-reduced, i.e. is a section of a higher-dimensioned parent image, and the input coordinate system or the output coordinate system but not both is "logical" or "tv". For example, if the input image is a 1D line extracted from a a 2D parent image with a sky projection world coordinate system, and the user specifies a transformation from the "logical" to "world" systems, only one input coordinate (column number) is required, but two output coordinates (ra and dec) are produced. If the input and output coordinate systems are reversed, then two input coordinates (ra and dec) are required, but only one output coordinate (column number) is produced. If the number of output coordinates is less than the number of input coordinates, the extra input coordinate columns in the input file are set to INDEF in the output file. If the number of output columns is greater than the number of input columns, the extra coordinate columns are added to the end of the output line.

FORMATS

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 (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. "\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
  
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

\n          insert a newline

REFERENCES

Additional information on IRAF world coordinate systems can be found in the help pages for the WCSEDIT and WCRESET tasks. 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.

EXAMPLES

1. Find the pixel coordinates of a list of objects in an image, given a list of their ras and decs in hh:mm:ss.s and dd:mm:ss format. Limit the precision of the output coordinates to 3 decimal places. In this example, the input ras and decs are assumed to be in columns 1 and 2 of the input coordinate file, and the ras must be converted from hours to decimal degrees.

	im> wcsctran incoords outcoords image world logical units="h n" \
	    formats="%8.3f %0.3f"

2. Repeat the previous example using the same input coordinate list to produce output coordinate lists for a list of input images.

	im> wcsctran incoords @outcoolist @imlist world logical units="h n" \
	    formats="%8.3f %8.3f"

3. Transform pixel coordinates in a photometry file to ra and dec coordinates, writing the output coordinates in hh:mm:ss.ss and dd:mm:ss.s format. The input pixel coordinates are stored in columns 3 and 4 of the input coordinate file.

	im> wcsctran magfile omagfile image logical world col="3 4" \
	    formats="%12.2H %12.1h"

4. Given a set of pixel coordinates in the parent image, find the pixel coordinates of the same objects in an image which is a shifted, rotated and scaled version of the parent image. The input coordinate list is created using the displayed parent image and the rimcursor task. The output coordinate lists is marked on the displayed transformed image using the tvmark task.

	im> display parent 1 fi+
	im> rimcursor > coolist
	im> imlintran parent image 45.0 45.0 1.5 1.5 xin=256 yin=256 \
	    xout=281 yout=263
	im> wcsctran coolist ocoolist image physical logical
	im> display image 2 fi+
	im> tvmark 2 outcoolist

TIME REQUIREMENTS

BUGS

SEE ALSO

wcsreset, wcsedit, rimcursor, listpixels, lintran


Source Code · Search Form · STSDAS