SKYCTRAN (Nov95)                 immatch                SKYCTRAN (Nov95)



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  <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  <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,   or   GAPPT),   ecliptic,   galactic,   or  
            supergalactic.
        
        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 (FK4 system only) 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.
        
        fk5 [equinox] 
            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.
        
        fk4 [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.
        
        noefk4 [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
            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 Julian epochs if the epoch value  <=
            3000.0, otherwise epoch is interpreted as a Julian day.
        
        galactic
            The IAU 1958 galactic coordinate system.
        
        supergalactic
            The deVaucouleurs supergalactic coordinate system.
        
        In  all  the  above  cases  fields  in  [] are optional with the
        defaults as described.
    
    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.
    
    lngcolumn = 1, latcolumn = 2
        The columns in the input file containing the x/ra/longitude  and
        y/dec/latitude coordinates.
    
    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 %11.1h, %11.1h,  and  %g
        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 %11.1h,
        %11.1h,  and  %g  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 coordinates are read from columns lngcolumn and latcolumn
    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.
    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)  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-OBS (or DATE-OBS).
    
    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, 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,  and  FK5  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 system.  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 system.  Users  are  strongly  urged  to  use  the
    EQUINOX  keyword  in  preference  to  the EPOCH keyword is 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 epoch is specified,
    in order of precedence,  by  the  values  of  the  keywords  MJD-OBS
    containing  the  modified  Julian  date  (JD  -  2400000.5)  of  the 
    observation, or the DATE-OBS keyword  containing  the  date  of  the
    observation  in  the  form  DD/MM/YY. As the latter quantity is only
    accurate to a day, the MJD-OBS specification is 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-OBS and DATE-OBS keywords as for the FK4 and FK4-NO-E system.
    
    If the celestial coordinate system is  ecliptic  the  mean  ecliptic
    and  equinox of date are required. They are supplied via the MJD-OBS
    and DATE-OBS keywords as  for  the  equatorial  FK4,  FK4-NO-E,  and
    GAPPT systems.
    
    USERS  NEED  TO BE AWARE THAT THE IRAF IMAGE WORLD COORDINATE SYSTEM
    CURRENTLY (IRAF VERSIONS 2.10.4 PATCH 1 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 \fVERBOSE 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 %11.1h, %11.1h, and %g are
    assumed for  output  units  of  "hours",  "degrees",  and  "radians"
    respectively.
    
    
    
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 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.
    
    2.  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+
    
    3. 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" 
    
    4. 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+
    
    5. 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+
    
    6. 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
    
    7.  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+
    
    8. 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
    
    9.  Convert  a  list of RAS in hours and DECS in degrees measured in
    the image created in example 8 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
    
    10.  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 examples 10 and 11 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>
    
    11. Repeat example 10 but use a previously prepared list  of  image1
    logical pixel coordinates as input to the task.
    
            cl> skyctran inlist outlist "image1 logical"\
                "image2 logical"
    
    12.  Repeat  example  10  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