STScI Logo

skyctran images.imcoords


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

NAME

skyctran -- convert astronomical coordinates from one system to another

USAGE

skyctran input output insystem outsystem

PARAMETERS

input
The source of the input coordinates. The options are:
<filename>
The list of input coordinate files. Coordinates may be entered by hand by setting input to "STDIN". A STDIN coordinate list is terminated by typing q or <EOF> (usually <ctrl/d> or <ctrl/z>).
imcursor
If the input file name is equal to the reserved keyword "imcursor" the input coordinates are read from the image cursor and the input coordinate system is the coordinate system of the image specified by the insystem parameter. The coordinate list is terminated by typing q or <EOF> (usually <ctrl/d> or <ctr/z>).
grid
If the input file name is equal to the reserved keyword "grid", an nilng by nilat grid of equally spaced input coordinates is generating spanning the region defined by ilngmin , ilngmax , ilatmin , ilatmax .
output
The list of output coordinate files. The number of output files must be equal to one or the number of input files. Results may be printed on the terminal by setting output to "STDOUT".
insystem, outsystem
The input and output celestial coordinate systems. The options are the following:
<imagename> [wcs]
The celestial coordinate system is the world coordinate system of the image <imagename> and the input or output pixel coordinates may be in the "logical", "tv", "physical" or "world" coordinate systems. If wcs is not specified "logical" is assumed, unless the input coordinates are read from the image cursor, in which case "tv" is assumed. The image celestial coordinate system must be one of the valid FITS celestial coordinate systems: equatorial (FK4, FK4-NO-E, FK5, ICRS, or GAPPT), ecliptic, galactic, or supergalactic.
icrs [equinox] [epoch]
The Internaltion Celestial Refernce System where equinox is a Julian or Besselian epoch e.g. J2000.0 or B1980.0. Equinoxes without the J / j or B / b prefix are treated as Julian epochs. The default value of equinox is J2000.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.
equinox [epoch]
The equatorial mean place post-IAU 1976 (FK5) system if equinox is a Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0 or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes by a B or b. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0. Epoch is the epoch of the observation and may be a Julian epoch, a Besselian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to the epoch type of equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.
fk[equinox] [epoch]
The equatorial mean place post-IAU 1976 (FK5) system where equinox is a Julian or Besselian epoch e.g. J2000.0 or B1980.0. Equinoxes without the J / j or B / b prefix are treated as Julian epochs. The default value of equinox is J2000.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.
fk[equinox] [epoch]
The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the observation. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs. The default value of equinox is B1950.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.
noefk[equinox] [epoch]
The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the observation. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs. The default value of equinox is B1950.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian day. If undefined epoch defaults to equinox.
apparent epoch
The equatorial geocentric apparent place post-IAU 1976 system where epoch is the epoch of observation. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date.
ecliptic epoch
The ecliptic coordinate system where epoch is the epoch of observation. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch values < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian day.
galactic [epoch]
The IAU 1958 galactic coordinate system. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. The default value of epoch is B1950.0.
supergalactic [epoch]
The deVaucouleurs supergalactic coordinate system. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. The default value of epoch is B1950.0.

In all the above cases fields in [] are optional with the defaults as described. The epoch field for fk5, icrs, galactic, and supergalactic coordinate systems is required only if the input coordinates are in the equatorial fk4, noefk4, fk5, or icrs systems and proper motions are defined.

transform = no
If transform = no the computed output coordinates are appended to the input line and the new extended line is written to the output file. If transform = yes the computed output coordinates replace the input coordinates in the input line and the edited line is written to the output file. Transform is always set to "no" if the input is from the unredirected standard input.
lngcolumn = 1, latcolumn = 2
The columns in the input file containing the x/ra/longitude and y/dec/latitude coordinates. Lngcolumn and latcolumn are always 1 and 2 if the input is from the unredirected standard input.
plngcolumn = INDEF, platcolumn = INDEF
The columns in the input file containing the ra and dec proper motions in " / year. If plngcolumn amd platcolumn are INDEF the proper motions are assumed to be undefined. Proper motions are used only if the input coordinate system is equatorial fk4, noefk4, fk5, or icrs. Plngcolumn and platcolumn are always 3 and 4 if the input is from the unredirected standard input.
pxcolumn = INDEF, rvcolumn = INDEF
The columns in the input file containing the parallax and radial velocity in in " and km / sec respectively. If pxcolumn amd rvcolumn are INDEF, the parallax and radial velocities are assumed to be 0.0 and 0.0. Parallaxes and radial velocities are only used if proper motions are defined. Pxcolumn and rvcolumn are always 5 and 6 if the input is from the unredirected standard input.
ilngmin = INDEF, ilngmax = INDEF, ilatmin = INDEF, ilatmax = INDEF
The lower and upper limits of the coordinate grid if input = "grid". Ilngmin and ilngmax default to 1.0, 1.0, 0.0, 0.0, 0.0 and, 2048.0, ncols, 24.0, 360.0, and TWOPI for coordinates in units of INDEF, pixels, hours, degrees, and radians respectively. Ilatmin and ilatmax default to 1.0, 1.0, -90.0, -90.0, -HALFPI and, 2048.0, nlines, 90.0, 90.0, and HALFPI for units of INDEF, pixels, degrees, degrees, and radians respectively.
nilng = 10, nilat = 10
The size of the computed coordinate grid if input = "grid".
ilngunits = "", ilatunits = ""
The units of the input ra/longitude and dec/latitude coordinates. The options are:
hours
Read the sky coordinates in hours.
degrees
Read the sky coordinates in degrees.
radians
Read the sky coordinates in radians.

If the input system is the <imagename> [logical/tv/physical] system, pixel units are assumed regardless of the values of ilngunits or ilatunits. The default ilngunits and ilatunits values are hours and degrees for the equatorial coordinate systems and degrees and degrees for the remaining sky coordinate systems.

ilngformat = "", ilatformat = ""
The output format of the input x/ra/longitude and y/dec/latitude coordinates if input = "grid". The options are discussed in the formats section of the help page below. If the input coordinate system is the <imagename> [logical/tv/physical] system, default formats of %10.3f and %10.3f are assumed regardless of the values of ilngunits and ilatunits. Otherwise default formats of %12.3h, %12.2h, and %13.7g are assumed for input units of "hours", "degrees", and "radians" respectively. For values of input other than "grid" the output formats of the input coordinates are the same as the input formats.
olngunits = "", olatunits = ""
The units of the output ra/longitude and dec/latitude coordinates. The options are:
hours
Output the sky coordinates in hours.
degrees
Output the sky coordinates in degrees.
radians
Output the sky coordinates in radians.

If the output system is the <imagename> [logical/tv/physical] system, pixel units are assumed regardless of the values of olngunits or olatunits. The default olngunits and olatunits values are hours and degrees for the equatorial coordinate systems and degrees and degrees for the remaining sky coordinate systems.

olngformat = "", olatformat = ""
The format of the computed x/ra/longitude and y/dec/latitude coordinates. The options are discussed in the formats section of the help page below. If the output coordinate system is the <imagename> [logical/tv/physical] system, default formats of %10.3f and %10.3f are assumed regardless of the values of olngunits and olatunits. Otherwise default formats of %12.3h, %12.2h, and %13.7g are assumed for output units of "hours", "degrees", and "radians" respectively.
icommands = ""
The default image display cursor.
verbose = yes
Print messages about actions taken by the task on the standard output?

DESCRIPTION

SKYCTRAN converts coordinates in the input files input from the input celestial coordinate system insystem to the output celestial coordinate system outsystem and writes the converted coordinates to the output files output . The input files may be simple text files, the standard input "STDIN", the image display cursor "imcursor", or a user specified coordinate grid. The output files may be simple text files or the standard output "STDOUT". SKYCTRAN may be used to change the units of the input coordinates, e.g. from degrees and degrees to hours and degrees, to precess the coordinates, to convert from one celestial coordinate system to another, e.g. from equatorial to ecliptic coordinates and vice versa, and to locate common objects in images whose fundamental coordinate systems are the same but observed at different epochs, e.g. FK4 B1950.0 and FK4 B1975.0, or different, e.g. equatorial FK4 B1950.0 and galactic.

The input data are read from columns lngcolumn , latcolumn , plngcolumn , platcolumn , pxcolumn , and rvcolumn in the input files and if transform = yes, the converted coordinates are written to the same columns in the output files. If transform = "no", the converted coordinates are appended to the input line creating two additional columns in the output file. If the input file is the unredirected standard input then tranpose is always "no". Comment lines, blanks lines, and lines for which the input coordinates could not be successfully decoded are passed on to the output file without modification.

The input and output celestial coordinate systems insystem and outsystem must be one of the following: equatorial, ecliptic, galactic, or supergalactic. The equatorial systems must be one of: 1) FK4, the mean place pre-IAU 1976 system, 2) FK4-NO-E, the same as FK4 but without the E-terms, 3) FK5, the mean place post-IAU 1976 system, 4) ICRS, the International Celestial Reference System, 5) GAPPT, the geocentric apparent place in the post-IAU 1976 system.

If insystem or outsystem is an image name then the celestial coordinate system is read from the image header. SKYCTRAN assumes that the celestial coordinate system is represented in the image header by the FITS keywords CTYPE, CRPIX, CRVAL, CD (or alternatively CDELT / CROTA), RADECSYS, EQUINOX (or EPOCH), and MJD-WCS (or MJD_OBS or DATE-OBS). USERS SHOULD TAKE NOTE THAT MJD-WCS IS CURRENTLY NEITHER A STANDARD OR PROPOSED FUTS STANDARD KEYWORD. HOWEVER IT OR SOMETHING SIMILAR IS REQUIRED TO SPECIFY THE EPOCH OF THE COORDINATE SYSTEM WHICH MAY BE DIFFERENT FROM THE EPOCH OF THE OBSERVATION.

The first four characters of the values of the ra/longitude and dec/latitude axis CTYPE keywords specify the celestial coordinate system. The permitted CTYPE values are RA--/DEC- for equatorial coordinate systems, ELON/ELAT for the ecliptic coordinate system, GLON/GLAT for the galactic coordinate system, and SLON/SLAT for the supergalactic coordinate system,

If the image celestial coordinate system is equatorial, the value of the RADECSYS keyword specifies the fundamental equatorial system. The permitted values of RADECSYS are FK4, FK4-NO-E, FK5, ICRS, and GAPPT. If the RADECSYS keyword is not present in the image header, the values of the EQUINOX or EPOCH keywords in that order of precedence are used to determine the fundamental equatorial system. EQUINOX or EPOCH contain the epoch of the mean place and equinox for the FK4, FK4-NO-E, FK5, and ICRS systems, e.g 1950.0 or 2000.0. The default equatorial system is FK4 if EQUINOX or EPOCH < 1984.0, FK5 if EQUINOX or EPOCH >= 1984.0, and FK5 if RADECSYS, EQUINOX and EPOCH are undefined. If RADECSYS is defined but EQUINOX and EPOCH are not the equinox defaults to 1950.0 for the FK4 and FK4-NO-E systems and 2000.0 for the FK5 and ICRS systems. The equinox value is interpreted as a Besselian epoch for the FK4 and FK4-NO-E systems and as a Julian epoch for the FK5 and ICRS systems. Users are strongly urged to use the EQUINOX keyword in preference to the EPOCH keyword if they must enter their own values of the the equinox into the image header. The FK4 and FK4-NO-E systems are not inertial and therefore also require the epoch of the observation (the time when the mean place was correct) in addition to the equinox. The input coordinate system epoch of the observation is also required if the input coordinate system is FK4, FK4-NO-E, FK5, or ICRS and proper motions are supplied. The epoch is specified, in order of precedence, by the values of the keywords MJD-WCS or MJD-OBS containing the modified Julian date (JD - 2400000.5) of the coordinate system, or the DATE-OBS keyword containing the date of the observation in the form DD/MM/YY, CCYY-MM-DD, or CCYY-MM-DDTHH:MM:SS.S. As the latter quantity may only be accurate to a day, the MJD-WCS or MJD-OBS specifications are preferable. If both keywords are absent the epoch defaults to the value of equinox. Equatorial coordinates in the GAPPT system require only the specification of the epoch of observation which is supplied via the MJD-WCS, MJD-OBS or DATE-OBS keywords as for the FK4, FK4-NO-E, FK5, and ICRS systems.

If the celestial coordinate system is ecliptic the mean ecliptic and equinox of date are required. They are supplied via the MJD-WCS, MJD-OBS or DATE-OBS keywords as for the equatorial FK4, FK4-NO-E, FK5, ICRS, and GAPPT systems.

If, the output coordinate system is galactic or supergalactic, the input coordinate system is FK4, FK4-NO-E, FK5, or ICRS and proper motions are supplied with the input coordinates, then the output epoch of the observation is also required. This is supplied via the MJD-WCS, MJD-OBS or DATE-OBS keywords as for the equatorial FK4, FK4-NO-E, FK5, ICRS, GAPPT, and ecliptic systems.

USERS NEED TO BE AWARE THAT THE IRAF IMAGE WORLD COORDINATE SYSTEM CURRENTLY (IRAF VERSIONS 2.10.4 PATCH 2 AND EARLIER) SUPPORTS ONLY THE EQUATORIAL SYSTEM (CTYPE (ra axis) = "RA--XXXX" CTYPE (dec axis) = "DEC-XXXX") WHERE XXXX IS THE PROJECTION TYPE, EVEN THOUGH THE SKYCTRAN TASK SUPPORTS GALACTIC, ECLIPTIC, AND SUPERGALACTIC COORDINATES.

USERS SHOULD ALSO REALIZE THAT IMAGE WORLD COORDINATE SYSTEM REPRESENTATIION IN FITS IS STILL IN THE DRAFT STAGE. ALTHOUGH SKYCTRAN TRIES TO CONFORM TO THE CURRENT DRAFT PROPOSAL WHERE NO ADOPTED STANDARDS CURRENTLY EXIST, THE FINAL FITS STANDARD MAY DIFFER FROM THE ONE ADOPTED HERE.

The IRAF builtin world coordinate systems "logical", "tv", "physical", and world are also supported. This means for example that users can begin with cursor coordinates in image 1, use the image header of image 1 to transform the pixel coordinates to the celestial coordinate system of image 1, convert the image 1 celestial coordinates to celestial coordinates in the image 2 celestial coordinate system, and finally transform the celestial coordinate system 2 coordinates to pixel coordinates in image 2, all in one step.

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, rotations, 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.

IF AN ERROR IS ENCOUNTERED WHEN DECODING THE INPUT OR OUTPUT WORLD COORDINATE SYSTEMS, THEN AN ERROR FLAG IS PRINTED IN THE OUTPUT FILE AND ON THE STANDARD OUTPUT IF VERBOSE IS YES, AND THE INPUT COORDINATES ARE COPIED TO THE OUTPUT COORDINATES WITHOUT CHANGE.

Ilngunits , ilatunits , olngunits , and olatunits set the units of the input and output coordinate systems. If the input or output system is the <imagename> [logical/tv/physical] system pixel units are assumed regardless of the values of <i/o>lngunits or <i/o>latunits. The default <i/o>lngunits and <i/o>latunits values are hours and degrees for the equatorial celestial coordinate system and degrees and degrees for the remaining celestial coordinate systems.

The formats of the computed x/ra/longitude and y/dec/longitude coordinates are specified with the olngformat and olatformat parameters. The options are discussed in the formats section of the help page below. If the output coordinate system is the <imagename> [logical/tv/physical], default formats of %10.3f and %10.3f are assumed regardless of the values of olngunits and olatunits. Otherwise default formats of %12.3h, %12.2h, and %g are assumed for output units of "hours", "degrees", and "radians" respectively.

USER COMMANDS

If the input file is STDIN the user can type in the input data by hand and set the input and output coordinate systems, the input and output coordinate units, and the output coordinate format interactively. The available commands are listed below.

	INTERACTIVE KEYSTROKE COMMANDS

The following commands must be followed by a carriage return.

?	Print help
:	Execute colon command
data	Measure object
q	Exit task


	VALID DATA STRING

x/ra/long y/dec/lat [pmra pmdec [parallax radial velocity]]

... x/ra/long y/dec/lat must be in pixels or the input units
... pmra and pmdec must be in " / year
... parallax must be in "
... radial velocity must be in km / sec

	COLON COMMANDS

The following commands must be followed by a carriage return.

:show				Show the input and output coordinate systems
:isystem	[string]	Show / set the input coordinate system
:osystem	[string]	Show / set the output coordinate system
:iunits		[string string]	Show / set the input coordinate units
:ounits		[string string]	Show / set the output coordinate units
:oformat	[string string]	Show / set the output coordinate format

	VALID INPUT AND OUTPUT COORDINATE SYSTEMS

image [logical/tv/physical/world]
equinox [epoch]
noefk4 [equinox [epoch]]
fk4 [equinox [epoch]]
fk5 [equinox [epoch]]
icrs [equinox [epoch]]
apparent epoch
ecliptic epoch
galactic [epoch]
supergalactic [epoch]

	VALID INPUT AND OUTPUT CELESTIAL COORDINATE UNITS
	          AND THEIR DEFAULT FORMATS

hours		%12.3h
degrees		%12.2h
radians		%13.7h

IMAGE CURSOR COMMANDS

In interactive image cursor mode the user can set the input and output coordinate systems, the output coordinate units, and the output coordinate formats. The available commands are listed below.

	INTERACTIVE KEYSTROKE COMMANDS

?	Print help
:	Execute colon command
spbar	Measure object
q	Exit task


	COLON COMMANDS

:show				Show the input and output coordinate systems
:isystem	[string]	Show / set the input coordinate system
:osystem	[string]	Show / set the output coordinate system
:ounits		[string string]	Show / set the output coordinate units
:oformat	[string string]	Show / set the output coordinate format

	VALID INPUT COORDINATE SYSTEMS

image [tv]

	VALID OUTPUT COORDINATE SYSTEMS

image [logical/tv/physical/world]
equinox [epoch]
noefk4 [equinox [epoch]]
fk4 [equinox [epoch]]
fk5 [equinox [epoch]]
icrs [equinox [epoch]]
apparent epoch
ecliptic epoch
galactic [epoch]
supergalactic [epoch]

	VALID OUTPUT COORDINATE UNITS AND THEIR DEFAULT FORMATS

hours		%12.3h
degrees		%12.2h
radians		%13.7g

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 the 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 draft paper "World Coordinate Systems Representations Within the FITS Format" by Hanisch and Wells, available from the iraf anonymous ftp archive and the draft paper which supersedes it "Representations of Celestial Coordinates in FITS" by Greisen and Calabretta available from the nrao anonymous ftp archives.

The spherical astronomy routines employed here are derived from the Starlink SLALIB library provided courtesy of Patrick Wallace. These routines are very well documented internally with extensive references provided where appropriate. Interested users are encouraged to examine the routines for this information. Type "help slalib" to get a listing of the SLALIB routines, "help slalib opt=sys" to get a concise summary of the library, and "help <routine>" to get a description of each routine's calling sequence, required input and output, etc. An overview of the library can be found in the paper "SLALIB - A Library of Subprograms", Starlink User Note 67.7 by P.T. Wallace, available from the Starlink archives.

EXAMPLES

1. Precess the fk4 coordinates typed in by the user to the fk5 system with and without the proper motion values.

	cl> skyctran STDIN STDOUT fk4 fk5

	# Insystem: fk4  Coordinates: equatorial FK4
	#     Equinox: B1950.000 Epoch: B1950.00000000 MJD: 33281.92346
	# Outsystem: fk5  Coordinates: equatorial FK5
	#     Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000

	# Input file: STDIN  Output file: STDOUT

	... not including proper motion
	13:28:43.2 27:18:01.1
	13:28:43.2 27:18:01.1 13:31:03.855  27:02:35.13

	... including proper motion
	13:28:43.2 27:18:01.1 .36 -0.16
	13:28:43.2 27:18:01.1 .36 -0.16 13:31:05.215  27:02:27.37

	... change the output coordinate system to fk5 1975.0 and repeat
	:os fk5 1975.0
	:os

	# Outsystem:  fk5 1975.0  Coordinates: equatorial FK5
	#     Equinox: J1975.000 Epoch: J1975.00000000 MJD: 42413.25000

	13:28:43.2 27:18:01.1
	13:28:43.2 27:18:01.1 13:29:53.564  27:10:17.69

	13:28:43.2 27:18:01.1 .36 -0.16
	13:28:43.2 27:18:01.1 .36 -0.16 13:29:54.244  27:10:13.80

	... type EOF to quit
	<EOF>

2. Precess a list of RAS in hours and DECS in degrees in the FK5 system equinox 1980.0 to equinox 2000.0 and write both the input coordinates and the output coordinates in hours and degrees to the output file.

	cl> skyctran inlist outlist j1980.0 j2000.0 

		... or equivalently ...

	cl> skyctran inlist outlist j1980.0 2000.0

		... or equivalently ...

	cl> skyctran inlist outlist "fk5 1980.0" fk5

Note that if the coordinate system, e.g. fk5, is not specified explicitly then equinoxes < 1984 must be be prefixed by J, or a Besselian rather than a Julian epoch will be assumed.

3. Repeat the previous example but replace the input coordinates with the precessed coordinates in the output file.

	cl> skyctran inlist outlist j1980.0 j2000.0 transform+

4. Precess a list of RAS in hours and DECS in degrees in the FK4 system equinox 1950.0 to equinox 1975.0 and write both the input coordinates and the output coordinates in hours and degrees to the output file. The input and output epochs of observation default to the respective equinox values.

	cl> skyctran inlist outlist 1950.0 1975.0 

		... or equivalently ...

	cl> skyctran inlist outlist b1950.0 b1975.0 

		... or equivalently ...

	cl> skyctran inlist outlist fk4 b1975.0 

		... or equivalently ...

	cl> skyctran inlist outlist fk4 "fk4 1975.0" 

5. Convert a list of RAS in hours and DECS in degrees in the FK4 system equinox 1950.0 to RAS in hours and DECS in degrees in the FK5 system equinox 2000.0, and replace the input coordinates with the output coordinates in the output file. The Besselian epoch of the observation is 1987.25.

	cl> skyctran inlist outlist "b1950.0 1987.25" j2000.0 \
	    transform+

6. Convert a list of RAS in hours and DECS in degrees to RAS in degrees and DECS in degrees, and replace the input coordinates with the output coordinates in the output file. As the input and output coordinate systems and equinoxes are the same no precession is performed.

	cl> skyctran inlist outlist 2000.0 2000.0 olngunits=degrees \
	    transform+

7. Convert a list of RAS in hours and DECS in degrees in the FK4 system, equinox 1950.0, epoch of observation 1987.24, to galactic coordinates, and write both the input and output coordinate to the output file.

	cl> skyctran inlist outlist "b1950.0 1987.25" galactic

8. Convert a list of RAS in hours and DECS in degrees in the FK5 system, equinox 2000.0, to ecliptic coordinates on Julian date 2449879.5, replacing the input coordinates with the converted coordinates in the output file.

	cl> skyctran inlist outlist j2000 "ecliptic 2449879.5" \
	    transform+

9. Display an image and use the cursor and image header coordinate system, equatorial FK4, equinox 1950.0, epoch 1987.25 to print the pixel and galactic coordinates of the marked objects on the image display. Note that the test image dev$wpix has an incorrect value of EPOCH (0.0) that would have confused skyctran and need to be changed.

	cl> imcopy dev$wpix wpix
	cl> hedit wpix epoch 1950.0
	cl> display wpix 1 fi+
	cl> skyctran imcursor STDOUT wpix galactic

10. Convert a list of RAS in hours and DECS in degrees measured in the image created in example 9 to the FK5 equinox 2000.0 coordinate system.

	cl> skyctran inlist outlist "wpix world" j2000.0

		   ... or equivalently ...

	cl> skyctran inlist outlist "b1950.0 1987.25" j2000.0

11. Using an image whose header coordinate system is equatorial FK5 equinox 2000.0 and a different image of the same region whose coordinate system is galactic use the image display and cursor to create a list of tie points in logical pixel coordinates that can be used as input to the registration tasks geomap and geotran. Note that this example and examples 12 and 13 below will not work on iraf system earlier than 2.11 because galactic image header coordinates are not fully supported. They will work however on two images which have equatorial coordinates systems which are precessed with respect to each other.

	cl> display image1

	    ... this is the reference image

	cl> skyctran imcursor outlist image1 "image2 logical"

	    ... mark many widely scattered points on the displayed
		image image1 terminating the input list with 
		<EOF> which is usually <ctrl/z> or <ctrl/d>

12. Repeat example 11 but use a previously prepared list of image1 logical pixel coordinates as input to the task.

	cl> skyctran inlist outlist "image1 logical"\
	    "image2 logical"

13. Repeat example 11 but have skyctran automatically generate a grid of 100 tie points.

	cl> skyctran grid outlist "image1 logical"\
	    "image2 logical"

TIME REQUIREMENTS

BUGS

SEE ALSO

setjd,precess,galactic,xray.xspatial.skypix,stsdas.toolbox.tools.tprecess


Source Code · Search Form · STSDAS