From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/twodspec/longslit/doc/fitcoords.hlp | 287 +++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 noao/twodspec/longslit/doc/fitcoords.hlp (limited to 'noao/twodspec/longslit/doc/fitcoords.hlp') diff --git a/noao/twodspec/longslit/doc/fitcoords.hlp b/noao/twodspec/longslit/doc/fitcoords.hlp new file mode 100644 index 00000000..a376ee74 --- /dev/null +++ b/noao/twodspec/longslit/doc/fitcoords.hlp @@ -0,0 +1,287 @@ +.help fitcoords Apr00 noao.twodspec.longslit +.ih +NAME +fitcoords -- Fit user coordinates to the image coordinates +.ih +USAGE +fitcoords images fitname +.ih +PARAMETERS +.ls images +List of images containing the feature coordinates to be fit. If the +parameter \fIcombine\fR is yes then feature coordinates from all the images +are combined and fit by a single function. Otherwise the feature coordinates +from each image are fit separately. +.le +.ls fitname = "" +If the input images are combined and fit by a single function then the fit +is stored under this name. If the images are not combined then the +fit for each image is stored under the name formed by appending the image +name to this name. A null prefix is acceptable when not combining but it +is an error if combining a list of images. +.le +.ls interactive = yes +Determine coordinate fits interactively? +.le +.ls combine = no +Combine the coordinates from all the input images and fit them by a single +function? If 'no' then fit the coordinates from each image separately. +.le +.ls database = "database" +Database containing the feature coordinate information used in fitting the +coordinates and in which the coordinate fit is recorded. +.le +.ls deletions = "deletions.db" +Deletion list file. If not null then points whose coordinates match those in +this file (if it exists) are initially deleted from the fit. +If the fitting is done interactively then the coordinates of +any deleted points (after exiting from the interactive fitting) are recorded +in this file. +.le +.ls function = "chebyshev" +Type of two dimensional function to use in fitting the user coordinates. +The choices are "chebyshev" polynomial and "legendre" polynomial. +The function may be abbreviated. If the task is interactive then +the user may change the function later. +.le +.ls xorder = 6 +Order of the mapping function along the first image axis. +The order is the number of polynomial terms. If the task is interactive +then the user may change the order later. +.le +.ls yorder = 6 +Order of the mapping function along the second image axis. +The order is the number of polynomial terms. If the task is interactive +then the user may change the order later. +.le +.ls logfiles = "STDOUT,logfile" +List of files in which to keep logs containing information about +the coordinate fit. If null then no log is kept. +.le +.ls plotfile = "plotfile" +Name of file to contain metacode for log plots. If null then no log plots +are kept. When the fitting is interactive the last graph is recorded in +the plot file and when not interactive a default plot is recorded. +.le +.ls graphics = "stdgraph" +Graphics output device. +.le +.ls cursor = "" +Graphics cursor input. If null the standard graphics cursor is used. +.le +.bp +.ih +CURSOR COMMANDS + +.nf +? List commands +c Print data values for point nearest the cursor +d Delete the point or set of points with constant x, y, or z + nearest the cursor (p, x, y, z,) +f Fit surface +l Graph the last set of points (in zoom mode) +n Graph the next set of points (in zoom mode) +p Graph all features +q Quit +r Redraw a graph +u Undelete the point or set of points with constant x, y, or z + nearest the cursor (p, x, y, z,) +w Window the graph. Type '?' to the "window:" prompt for more help. +x Select data for the x axis (x, y, z, s, r) +y Select data for the y axis (x, y, z, s, r) +z Zoom on the set of points with constant x, y, or z (x, y, z) + Unzoom with p + +:corners Show the fitted values for the corners of the image +:function type Set the function for the fitted surface + (chebyshev, legendre) +:show Show the fitting parameters +:xorder value Set the x order for the fitted surface +:yorder value Set the y order for the fitted surface +.fi +.ih +DESCRIPTION +A two dimensional function of the image coordinates is fitted to the user +coordinates from the specified images; + +.nf + user coordinate = function (column, line) + + or + + z = s (x, y) +.fi + +The coordinates from all the input images may be combined in a single fit or +the coordinates from each image may be fit separately. If the +coordinates from the input images are combined then the fitted function +is recorded in the database under the specified name. If +the coordinates are fit separately the fitted function is recorded under +a name formed by appending the image name to the specified root name. + +When the task is interactive the user is first queried whether to perform +the fitting interactively. The user may answer "yes", "no", "YES", or "NO" +to the query. The lowercase responses apply only to the current fit +and the uppercase responses apply to all remaining fits. When the +fitting is done interactively the user may change the fitted function and +orders iteratively, delete individual coordinates or entire features, +and graph the fit and residuals in a number ways. +The CURSOR COMMANDS section describes the graphics cursor keystrokes +which are available. When selecting data for the graph axes the +follow definitions apply: + +.nf + x Input image column positions + y Input image line positions + z Input user coordinates + s Fitted user coordinates + r Residuals (s - z) +.fi + +A very useful feature is zooming, deleting, or undeleting a subset of data +points. The subsets +are defined as points with the same x, y, or z value as the point indicated +by the cursor when typing (z)oom, (d)elete, or (u)ndelete. + +When a satisfactory coordinate fit has been determined exit with the (q)uit +key. The user is asked if the fit is to be recorded in the database. + +If a deletion list file is specified then the coordinates of any +points deleted interactively are recorded in this file. This file then can +be read by subsequent fits to initially delete points with matching +coordinates. This is generally used when fitting a series of images +non-interactively. + +Information about the fitted function may be recorded. Textual information +is written to the specified log files (which may include the standard +output STDOUT). The last interactive plot or a default non-interactive +plot is written the specified plot file which may be examined and spooled +at a later time. + + +FITCOORDS DATABASE + +The FITCOORDS fits are stored in text files in the subdirectory given by +the "database" parameter. The name of the file is fc where + is the specified fit name. The database text file contains +blocks of lines beginning with a time stamp followed by line with the +"begin" keyword. The value following "begin" is the fit name, which is +often the name of the image used for the fit. If there is more than one +block with the same fit name then the last one is used. + +The "task" keyword will has the value "fitcoords" and the "axis" keyword +identifies the axis to which the surface fit applies. An axis of 1 refers +to the first or x axis (the first dimension of the image) and 2 refers to +the second or y axis. + +The "surface" keyword specifies the number of coefficients for the surface +fit given in the following lines . The surface fit is produced by an IRAF +math package called "gsurfit". The coefficients recorded in the database +are intented to be internal to that package. However the following +describes how to interpret the coefficients. + +The first 8 lines specify: + +.nf + function - Function type (1=chebyshev, 2=legendre) + xorder - X "order" (highest power of x) + yorder - Y "order" (highest power of y) + xterms - Cross-term type (always 1 for FITCOORDS) + xmin - Minimum x over which the fit is defined + xmax - Maximum x over which the fit is defined + ymin - Minimum y over which the fit is defined + ymax - Maximum y over which the fit is defined +.fi + +The polynomial coefficients follow in array order with the x index +varying fastest: + +.nf + C00 + C10 + C20 + ... + C0 + C01 + C11 + C21 + ... + C1 + ... + C +.fi + +The surface fitting functions have the form + +.nf + fit(x,y) = Cmn * Pmn +.fi + +where the Cmn are the coefficients of the polynomials terms Pmn, and the Pmn +are defined as follows: + +.nf +Chebyshev: Pmn = Pm(xnorm) * Pn(ynorm) + + xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin) + ynorm = (2 * y - (ymax + ymin)) / (ymax - ymin) + + P0(xnorm) = 1.0 + P1(xnorm) = xnorm + Pm+1(xnorm) = 2.0 * xnorm * Pm(xnorm) - Pm-1(xnorm) + + P0(ynorm) = 1.0 + P1(ynorm) = ynorm + Pn+1(ynorm) = 2.0 * ynorm * Pn(ynorm) - Pn-1(ynorm) + +Legendre: Pmn = Pm(xnorm) * Pn(ynorm) + + xnorm = (2 * x - (xmax + xmin)) / (xmax - xmin) + ynorm = (2 * y - (ymax + ymin)) / (ymax - ymin) + + P0(xnorm) = 1.0 + P1(xnorm) = xnorm + Pm+1(xnorm) = ((2m+1)*xnorm*Pm(xnorm)-m*Pm-1(xnorm))/(m+1) + + P0(ynorm) = 1.0 + P1(ynorm) = ynorm + Pn+1(ynorm) = ((2n+1)*ynorm*Pn(ynorm)-n*Pn-1(ynorm))/(n+1) +.fi + +Notice that the x and y values are first normalized to the interval -1 to 1 +over the range of the surface as given by the xmin, xmax, ymin, and ymax +elements of the database description. +.ih +EXAMPLES +A number of strong arc lines are identified along one column of an arc +calibration image "arc001". The arc lines are then reidentified at every +20th column. A two dimensional dispersion solution is determined as follows: + + cl> fitcoords arc001 fit. + +The fitting is done interactively and deleted points are recorded. +The fit is recorded under the name fit.arc001. A set of similar arc +calibrations are fit non-interactively, with the same points deleted, +as follows: + + cl> fitcoords arc* interactive=no + +Several stellar spectra are identified at different positions along the slit +and traced to other lines. A fit to the geometric distortion is determined +with the command: + + cl> fitcoords star001,star003,star005 fitname=distortion combine=yes + +In this case the coordinates from all the tracings are combined in a single +fit called distortion. + +The plots in the plot file are spooled to the standard plotting device as +follows: + + cl> gkimosaic plotfile + +\fBGkimosaic\fR is in the \fBplot\fR package. +.ih +SEE ALSO +transform +.endhelp -- cgit