Initial commit

1 files changed, 480 insertions, 0 deletions

diff --git a/pkg/images/imcoords/doc/ccstd.hlp b/pkg/images/imcoords/doc/ccstd.hlp
new file mode 100644
index 00000000..b24def49
--- /dev/null
+++ b/pkg/images/imcoords/doc/ccstd.hlp
@@ -0,0 +1,480 @@
+.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