path: root/pkg/images/imcoords/doc/ccstd.hlp

.help ccstd Oct00 images.imcoords
.ih
NAME
ccstd -- transform pixel and celestial coordinates to standard coordinates
and vice versa
.ih
USAGE
ccstd input output database solutions
.ih
PARAMETERS
.ls input
The input coordinate files. Coordinates may be entered by hand by setting input
to "STDIN".
.le
.ls output
The output coordinate files. The number of output files must be one or equal
to the number of input files. Results may be printed on the terminal by
setting output to "STDOUT".
.le
.ls database
The text database file written by the ccmap task which contains the
desired plate solutions. If database is undefined ccstd computes the
standard coordinates or pixel and celestial coordinates using the current
values of the xref, yref, xmag ymag, xrotation, yrotation, lngref, latref,
and projection parameters.
.le
.ls solutions
The database record containing the desired plate solution. 
The number of records must be one or equal to the number of input coordinate
files. Solutions is either the user name supplied to ccmap, the name of the
image input to ccmap for which the plate solution is valid, or the name of the
coordinate file that the ccmap task used to compute the plate solution.
The quantities stored in solutions always supersede the values of the
parameters xref, yref, xmag, ymag, xrotation, yrotation, lngref, latref,
and projection.
.le
.ls geometry = "geometric"
The type of geometric transformation. The geometry parameter is
only requested if database is defined. The options are:
.ls linear
Transform the pixel coordinates to standard coordinates or vice versa
using the linear part of the plate solution.
only.
.le
.ls geometric
Transform the pixel coordinates to standard coordinates or vice versa
using the full plate solution.
.le
.le
.ls forward = yes
Transform from pixel and celestial coordinates to standard coordinates ? If
forward is "no" then the plate solution is inverted and standard coordinates
are transformed to pixel and celestial coordinates.
.le
.ls polar = no
Convert to and from polar standard coordinates instead of Cartesian standard
coordinates?
.le
.ls xref = INDEF, yref = INDEF
The pixel coordinates of the reference point. If database is undefined
then xref and yref default to 0.0 and 0.0, otherwise these parameters are
ignored.
.le
.ls xmag = INDEF, ymag = INDEF
The x and y scale factors in arcseconds per pixel. If database is undefined
xmag and ymag default to 1.0 and 1.0 arcseconds per pixel, otherwise these
parameters are ignored.
.le
.ls xrotation = INDEF, yrotation = INDEF
The x and y rotation angles in degrees measured counter-clockwise with
respect to the x and y axes. If database is undefined then xrotation and
yrotation are interpreted as the rotation of the coordinates with respect
to the x and y axes and default to 0.0 and 0.0 degrees. For example xrotation
and yrotation values of 30.0 and 30.0 degrees will rotate a point 30 degrees
counter-clockwise with respect to the x and y axes. To flip the x axis
coordinates in this case either set the angles to 210.0 and 30.0 degrees
or leave the angles at 30.0 and 30.0 and set the xmag parameter to a negative
value. If database is defined these parameters are ignored. The ccmap task
computes the x and y rotation angles of the x and y axes, not the rotation
angle of the coordinates. An celestial coordinate system rotated 30 degrees
counter-clockwise with respect to the pixel coordinate system will produce
xrotation and yrotation values o 330.0 and 330.0 or equivalently -30.0 and
-30.0 degrees in the database file not 30.0 and 30.0.
.le
.ls lngref = INDEF, latref = INDEF
The celestial coordinates of the reference point, e.g. the ra and dec
of the reference point for equatorial systems, galactic longitude and
latitude of the reference for galactic systems. If database is undefined
lngref and latref default to 0.0 and 0.0, otherwise these parameters are
ignored.
.le
.ls lngunits = "", latunits = ""
The units of the input or output ra / longitude and dec / latitude coordinates.
The options are "hours", "degrees", "radians" for ra / longitude coordinates,
and "degrees" and "radians" for dec / latitude systems. If lngunits and
latunits are undefined they default to the values in the database records.
If database is undefined then lngunits and latunits default to "hours" and
"degrees" respectively.
.le
.ls projection = "tan"
The sky projection geometry. The options are "tan", "sin", "arc" and
"lin". If database is undefined then the value of the projection parameter
is used, otherwise this parameter is ignored.
.le
.ls xcolumn = 1, ycolumn = 2
The columns in the input coordinate file containing the x and y coordinates
if the \fIforward\fR parameter is "yes", or the corresponding standard
coordinates xi and eta if the forward parameter is "no".
.le
.ls lngcolumn = 3, latcolumn = 4
The columns in the input coordinate file containing the celestial coordinates
if the \fIforward\fR parameter is "yes", or the corresponding standard
coordinates xi and eta if the forward parameter is "no".
.le
.ls lngformat = "", latformat = ""
The default output format of the transformed coordinates in lngcolumn and 
latcolumn. If forward = yes then the default output format is "%10.3f".
Otherwise the defaults are "%12.2h" for output coordinates in hours, "%11.1h"
for output coordinates in degrees, and "%13.7g" for output coordinates in
radians.
.le
.ls xformat = "", yformat = ""
The default output format of the transformed coordinates in xcolumn and
ycolumn. The default is "%10.3f".
.le
.ls min_sigdigits = 7
The minimum precision of the output coordinates.
.le

.ih
DESCRIPTION

CCSTD transforms the list of input coordinates in the
text file \fIinput\fR and writes the transformed
coordinates to the text file \fIoutput\fR. The input coordinates
are read from and the output coordinates written to, the columns
\fIxcolumn\fR, \fIycolumn\fR, \fIlngcolumn\fR, and \fIlatcolumn\fR
in the input and output
files. The format of the output coordinates can be specified using the
\fIxformat\fR, \fIyformat\fR, \fIlngformat\fR and \fIlatformat\fR parameters.
If the output formats are unspecified the coordinates are written  out with
reasonable default formats, e.g. "%10.3f" for standard coordinates,
"%12.2h" and "11.1h" for celestial coordinates in hours or degrees,
and "%13.7g" for celestial coordinates in radians. All the remaining
fields in the
input file are copied to the output file without modification. Blank lines
and comment lines are also passed to the output file unaltered.

The plate solution can either be read from record \fIsolutions\fR
in the database file \fIdatabase\fR written by CCMAP, or specified
by the user via the \fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR,
\fIxrotation\fR, \fIyrotation\fR, \fIlngref\fR, \fIlatref\fR, 
and \fIprojection\fR parameters. \fIlngunits\fR and \fIlatunits\fR
define the units of the input celestial coordinates. If 
undefined they default to the values in the database or to
the quantities "hours" and "degrees" respectively. The standard coordinates
are always written and read in units of arcseconds.

If the \fIforward\fR
parameter is "yes", the input coordinates are assumed to be pixel coordinates
and celestial coordinates. The pixel coordinates are transformed to standard
coordinates using the plate solution, and celestial coordinates are
transformed to standard coordinates using the position of the reference
point \fIlngref\fR, \fIlatref\fR, and the projection specified by
\fIprojection\fR. If \fIforward\fR is "no", then
the input coordinates are assumed to be standard coordinates and 
those in \fIxcolumn\fR and \fIycolumn\fR are transformed to pixel
coordinates by inverting the plate solution, and those in \fIlngcolumn\fR
and \fIlatcolumn\fR are transformed to celestial coordinates using the
position of the reference point and the specified projection.

The plate solution computed by CCMAP has the following form where x and y
are the pixel coordinates and xi and eta are the corresponding fitted standard
coordinates in arcseconds per pixel. The observed standard coordinates are
computed by applying the appropriate sky projection to the celestial
coordinates.


.nf
	 xi = f (x, y)
	eta = g (x, y)
.fi

The functions f and g are either power series, Legendre, or Chebyshev
polynomials whose order and region of validity were set by the user when
CCMAP was run. The plate solution is arbitrary and does not correspond to
any physically meaningful model. However the first order terms can be given
the simple geometrical interpretation shown below.

.nf
	  xi = a + b * x + c * y
	 eta = d + e * x + f * y
	   b = xmag * cos (xrotation)
	   c = ymag * sin (yrotation)
	   e = -xmag * sin (xrotation)
	   f = ymag * cos (yrotation)
	   a = xi0 - b * xref - c * yref = xshift
	   d = eta0 - e * xref - f * yref = yshift
	   xi0 = 0.0
	   eta0 = 0.0
.fi

xref, yref, xi0, and eta0 are the origins of the reference and output
coordinate systems respectively. xi0 and eta0 are both 0.0 by default.
xmag and ymag are the x and y scales in " / pixel, and xrotation and yrotation
are the x and y axes rotation angles measured counter-clockwise from original
x and y axes.

If the CCMAP database is undefined then CCSTD computes a linear plate
solution using the parameters \fIxref\fR, \fIyref\fR, \fIxmag\fR,
\fIymag\fR, \fIxrotation\fR, \fIyrotation\fR, \fIlngref\fR, \fIlatref\fR,
\fIlngunits\fR, \fIlatunits\fR and \fIprojection\fR as shown below. Note
that in this case xrotation and yrotation are interpreted as the rotation
of the coordinates not the rotation of the coordinate axes.

.nf
	  xi = a + b * x + c * y
	 eta = d + e * x + f * y
	   b = xmag * cos (xrotation)
	   c = -ymag * sin (yrotation)
	   e = xmag * sin (xrotation)
	   f = ymag * cos (yrotation)
	   a = xi0 - b * xref - c * yref = xshift
	   d = eta0 - e * xref - f * yref = yshift
	   xi0 = 0.0
	   eta0 = 0.0
.fi

Linear plate solutions are evaluated in the forward and reverse sense
using the appropriate IRAF mwcs system routines. Higher order plate
solutions are evaluated in the forward sense using straight-forward
evaluation of the polynomial terms, in the reverse sense by applying
Newton's method to the plate solution.


.ih
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:
   
.nf
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
.fi

.ih
EXAMPLES

.nf
1. Compute the standard coordinates in arcseconds per pixel given a list of
pixel and equatorial coordinates and the position of the reference point in
pixel and equatorial coordinates.

cl> type coords
13:29:47.297  47:13:37.52  327.50  410.38
13:29:37.406  47:09:09.18  465.50   62.10
13:29:38.700  47:13:36.23  442.01  409.65
13:29:55.424  47:10:05.15  224.35  131.20
13:30:01.816  47:12:58.79  134.37  356.33

cl> ccstd coords STDOUT "" xref=256.5 yref=256.5 lngref=13:29:48.1 \
latref = 47:11:53.4 xcol=3 ycol=4 lngcol=1 latcol=2
  -8.180   104.120    71.000   153.880
-109.087  -164.189   209.000  -194.400
 -95.753   102.854   185.510   153.150
  74.688  -108.235   -32.150  -125.300
 139.745    65.441  -122.130    99.830

2. Repeat the previous example but output the results in polar coordinates.
The first and third columns contain the radius coordinate in arcseconds,
the second and fourth columns contain the position angle in degrees measured
counter-clockwise with respect to the standard coordinates.

cl> ccstd coords STDOUT "" xref=256.5 yref=256.5 lngref=13:29:48.1 \
latref = 47:11:53.4 xcol=3 ycol=4 lngcol=1 latcol=2 polar+
104.441    94.492   169.470    65.231
197.124   236.400   285.434   317.073
140.526   132.952   240.560    39.542
131.504   304.608   129.359   255.609
154.309    25.093   157.740   140.737


3. Compute the plate solution and use it to evaluate the Cartesian and
polar standard coordinates for the input coordinate list used in example 1.

cl> ccmap coords coords.db xcol=3 ycol=4 lngcol=1 latcol=2 inter-
Coords File: coords  Image: 
    Database: coords.db  Record: coords
Refsystem: j2000  Coordinates: equatorial FK5
    Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000
Insystem: j2000  Coordinates: equatorial FK5
    Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000
Coordinate mapping status
    Ra/Dec or Long/Lat fit rms: 0.229  0.241   (arcsec  arcsec)
Coordinate mapping parameters
    Sky projection geometry: tan
    Reference point: 13:29:48.129  47:11:53.37  (hours  degrees)
    Reference point: 318.735  273.900  (pixels  pixels)
    X and Y scale: 0.764  0.767  (arcsec/pixel  arcsec/pixel)
    X and Y axis rotation: 179.110  358.958  (degrees  degrees)


cl> type coords.db
# Mon 10:29:13 24-Nov-97
begin   coords
        xrefmean        318.7460000000001
        yrefmean        273.9320000000001
        lngmean         13.49670238888889
        latmean         47.19815944444444
        coosystem       j2000
        projection      tan
        lngref          13.49670238888889
        latref          47.19815944444444
        lngunits        hours
        latunits        degrees
        xpixref         318.7352667484295
        ypixref         273.9002619912411
        geometry        general
        function        polynomial
        xishift         247.3577084680361
        etashift        -206.1795977453246
        xmag            0.7641733802338992
        ymag            0.7666917500560622
        xrotation       179.1101291109185
        yrotation       358.9582148846163
        wcsxirms        0.2288984454992771
        wcsetarms       0.2411034140453112
        xirms           0.2288984454992771
        etarms          0.2411034140453112
        surface1        11
                        3.      3.
                        2.      2.
                        2.      2.
                        0.      0.
                        134.3700000000001       134.3700000000001
                        465.5000000000002       465.5000000000002
                        62.1    62.1
                        410.3800000000001       410.3800000000001
                        247.3577084680361       -206.1795977453246
                        -0.7640812161068504     -0.011868034832272
                        -0.01393966623835092    0.7665650170136847
        surface2        0


cl> ccstd coords STDOUT coords.db coords xcol=3 ycol=4 lngcol=1 latcol=2
  -8.471   104.146    -8.599   104.517
-109.378  -164.163  -109.188  -164.100
 -96.044   102.880   -96.084   102.598
  74.397  -108.210    74.107  -108.269
 139.454    65.467   139.721    65.376

cl> ccstd coords STDOUT coords.db coords xcol=3 ycol=4 lngcol=1 latcol=2 \
polar+
104.490    94.650   104.870    94.704
197.264   236.325   197.106   236.361
140.744   133.032   140.565   133.122
131.317   304.509   131.202   304.391
154.056    25.148   154.259    25.075

4. Use the previous plate solution to transform the pixel and equatorial
coordinates to standard coordinates but enter the plate solution by hand.

cl> ccstd coords STDOUT "" xref=318.735 yref=273.900 lngref=13:29:48.129 \
latref=47:11:53.37 xmag=.764 ymag=.767 xrot=180.890 yrot=1.042 xcol=3    \
ycol=4 lngcol=1 latcol=2
  -8.475   104.150    -8.599   104.559
-109.382  -164.159  -109.161  -164.165
 -96.048   102.884   -96.064   102.640
  74.393  -108.206    74.092  -108.313
 139.450    65.471   139.688    65.401

cl> ccstd coords STDOUT "" xref=318.735 yref=273.900 lngref=13:29:48.129 \
latref=47:11:53.37 xmag=.764 ymag=.767 xrot=180.890 yrot=1.042 xcol=3    \
ycol=4 lngcol=1 latcol=2 polar+
104.494    94.652   104.912    94.702
197.263   236.324   197.145   236.378
140.750   133.032   140.582   133.105
131.311   304.509   131.230   304.374
154.054    25.150   154.240    25.089

Note that there are minor differences between the results of examples 3 and
4 due to precision differences in the input, and that the angles input
to ccstd in example 4 are the coordinate rotation angles not the axes
rotation angles as printed by ccmap. The difference is exactly 180 degrees
in both cases.

5. Use the plate solution computed in example 3 to convert a list
of standard coordinates into the equivalent pixel and celestial coordinates.

cl> type stdcoords
  -8.471   104.146    -8.599   104.517
-109.378  -164.163  -109.188  -164.100
 -96.044   102.880   -96.084   102.598
  74.397  -108.210    74.107  -108.269
 139.454    65.467   139.721    65.376

cl> ccstd stdcoords STDOUT coords.db coords xcol=3 ycol=4 lngcol=1 latcol=2  \
forward-

13:29:47.30 47:13:37.5   327.499   410.381
13:29:37.41 47:09:09.2   465.500    62.101
13:29:38.70 47:13:36.2   442.010   409.650
13:29:55.42 47:10:05.1   224.350   131.200
13:30:01.82 47:12:58.8   134.370   356.330
.fi

.ih
BUGS

.ih
SEE ALSO
ccmap, ccsetwcs, cctran, finder.tastrom, skyctran
.endhelp