diff options
Diffstat (limited to 'pkg/images/immatch/doc')
| -rw-r--r-- | pkg/images/immatch/doc/geomap.hlp | 435 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/geotran.hlp | 320 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/geoxytran.hlp | 408 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/gregister.hlp | 265 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/imalign.hlp | 316 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/imcentroid.hlp | 257 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/imcombine.hlp | 1471 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/linmatch.hlp | 699 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/psfmatch.hlp | 595 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/skymap.hlp | 642 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/skyxymatch.hlp | 406 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/sregister.hlp | 779 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/wcscopy.hlp | 80 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/wcsmap.hlp | 619 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/wcsxymatch.hlp | 314 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/wregister.hlp | 761 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/xregister.hlp | 707 | ||||
| -rw-r--r-- | pkg/images/immatch/doc/xyxymatch.hlp | 468 |
18 files changed, 9542 insertions, 0 deletions
diff --git a/pkg/images/immatch/doc/geomap.hlp b/pkg/images/immatch/doc/geomap.hlp new file mode 100644 index 00000000..525e70b8 --- /dev/null +++ b/pkg/images/immatch/doc/geomap.hlp @@ -0,0 +1,435 @@ +.help geomap Jan01 images.immatch +.ih +NAME +geomap -- compute one or more spatial transformation functions +.ih +USAGE +geomap input database xmin xmax ymin ymax +.ih +PARAMETERS +.ls input +The list of text files containing the pixel coordinates of control points in +the reference and input images. The control points are listed +one per line with xref, yref, xin, and yin in columns 1 through 4 respectively. +.le +.ls database +The name of the text file database where the computed transformations will +be stored. +.le +.ls xmin, xmax, ymin, ymax +The range of reference coordinates over which the computed coordinate +transformation is valid. If the user is working in pixel units these limits +should normally be set to the values of the column and row limits of the +reference image, e.g xmin = 1.0, xmax = 512, ymin= 1.0, ymax = 512 for +a 512 x 512 image. The minimum and maximum xref and yref values in \fIinput\fR +are used if xmin, xmax, ymin, or ymax are undefined. +.le +.ls transforms = "" +An optional list of transform record names. If transforms is undefined +the database record(s) are assigned the names of the +individual text files specified by \fIinput\fR. +.le +.ls results = "" +Optional output files containing a summary of the results including a +description of the transform geometry and a listing of the input coordinates, +the fitted coordinates, and the fit residuals. The number of results files +must be one or equal to the number of input files. If results is "STDOUT" the + results summary is printed on the standard output. +.le +.ls fitgeometry = "general" +The fitting geometry to be used. The options are the following. +.ls shift +X and y shifts only are fit. +.le +.ls xyscale +X and y shifts and x and y magnification factors are fit. Axis flips are +allowed for. +.le +.ls rotate +X and y shifts and a rotation angle are fit. Axis flips are allowed for. +.le +.ls rscale +X and y shifts, a magnification factor assumed to be the same in x and y, and a +rotation angle are fit. Axis flips are allowed for. +.le +.ls rxyscale +X and y shifts, x and y magnifications factors, and a rotation angle are fit. +Axis flips are allowed for. +.le +.ls general +A polynomial of arbitrary order in x and y is fit. A linear term and a +distortion term are computed separately. The linear term includes an x and y +shift, an x and y scale factor, a rotation and a skew. Axis flips are also +allowed for in the linear portion of the fit. The distortion term consists +of a polynomial fit to the residuals of the linear term. By default the +distortion term is set to zero. +.le + +For all the fitting geometries except "general" no distortion term is fit, +i.e. the x and y polynomial orders are assumed to be 2 and the cross term +switches are assumed to be "none", regardless of the values of the +\fIxxorder\fR, \fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and +\fIyxterms\fR parameters set by the user. +.le +.ls function = "polynomial" +The type of analytic surface to be fit. The options are the following. +.ls legendre +Legendre polynomials in x and y. +.le +.ls chebyshev +Chebyshev polynomials in x and y. +.le +.ls polynomial +Power series in x and y. +.le +.le +.ls xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2 +The order of the polynomials in x and y for the x and y fits respectively. +The default order and cross term settings define the linear term in x +and y, where the 6 coefficients can be interpreted in terms of an x and y shift, +an x and y scale change, and rotations of the x and y axes. The "shift", +"xyscale", "rotation", "rscale", and "rxyscale", fitting geometries +assume that the polynomial order parameters are 2 regardless of the values +set by the user. If any of the order parameters are higher than 2 and +\fIfitgeometry\fR is "general", then a distortion surface is fit to the +residuals from the linear portion of the fit. +.le +.ls xxterms = "half", yxterms = "half" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is max (xxorder - 1, xyorder - 1) for the x fit and +max (yxorder - 1, yyorder - 1) for the y fit. +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is max (xxorder - 1, xyorder - 1) for the x fit and +max (yxorder - 1, yyorder - 1) for the y fit. +.le + +The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting +geometries, assume that the cross term switches are set to "none" +regardless of the values set by the user. If either of the cross terms +parameters are set to "half" or "full" and \fIfitgeometry\fR is "general" +then a distortion surface is fit to the residuals from the linear +portion of the fit. +.le +.ls maxiter = 0 +The maximum number of rejection iterations. The default is no rejection. +.le +.ls reject = 3.0 +The rejection limit in units of sigma. +.le +.ls calctype = "real" +The precision of the coordinate transformation calculations. The options are +real and double. +.le +.ls verbose = yes +Print messages about actions taken by the task ? +.le +.ls interactive = yes +In interactive mode the user may interact with the fitting process, e.g. +change the order of the fit, reject points, display the data, etc. +.le +.ls graphics = "stdgraph" +The graphics device. +.le +.ls cursor = "" +The graphics cursor. +.le +.ih +DESCRIPTION + +GEOMAP computes the transformation required to map the reference coordinate +system to the input coordinate system. The coordinates of points in common +to the two systems are listed in the input text file(s) \fIinput\fR +one per line in the following format: "xref yref xin yin". + +The computed transforms are stored in the text database file \fIdatabase\fR +in records with names specified by the parameter \fItransforms\fR. If the +transforms parameter is undefined the records are assigned the name of +the input coordinate files. + +The computed transformation has the form shown below, where the reference +coordinates must be defined in the coordinate system of the reference image +system if the user intends to resample an image with gregister or geotran, or +transform coordinates from the reference coordinate system to the input +image coordinate system. + +.nf + xin = f (xref, yref) + yin = g (xref, yref) +.fi + +If on the other hand the user wishes to transform coordinates from the +input image coordinate system to the reference coordinate system then he or she +must reverse the roles of the reference and input coordinates as defined above, +and compute the inverse transformation. + + +The functions f and g are either a power series polynomial or a Legendre or +Chebyshev polynomial surface of order \fIxxorder\fR and \fIxyorder\fR in x +and \fIyxorder\fR and \fIyyorder\fR in y. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xxterms = "none", xyterms = "none" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a13' * yref ** 2 + +xxterms = "half", xyterms = "half" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a22 * xref * yref + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a22' * xref * yref + a13' * yref ** 2 + +xxterms = "full", xyterms = "full" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a31 * xref ** 2 + + a12 * yref + a22 * xref * yref + a32 * xref ** 2 * yref + + a13 * yref ** 2 + a23 * xref * yref ** 2 + + a33 * xref ** 2 * yref ** 2 + yin = a11' + a21' * xref + a31' * xref ** 2 + + a12' * yref + a22' * xref * yref + a32' * xref ** 2 * yref + + a13' * yref ** 2 + a23' * xref * yref ** 2 + + a33' * xref ** 2 * yref ** 2 +.fi + +If the \fBfitgeometry\fR parameter is anything other than "general", the order +parameters assume the value 2 and the cross terms switches assume the value +"none", regardless of the values set by the user. The computation can be done in +either real or double precision by setting \fIcalctype\fR. Automatic pixel +rejection may be enabled by setting \fmaxiter\fR > 0 and \fIreject\fR to some +number greater than 0. + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the region of +validity of the fit in the reference coordinate system and must be set by +the user. These parameters can be used to reject out of range data before the +actual fitting is done. + +GEOMAP may be run interactively by setting \fIinteractive\fR = yes and +inputting commands by the use of simple keystrokes. +In interactive mode the user has the option of changing the +fit parameters and displaying the data graphically until a satisfactory +fit has been achieved. The available keystroke commands are listed +below. + +.nf +? Print options +f Fit the data and graph with the current graph type (g, x, r, y, s) +g Graph the data and the current fit +x,r Graph the x fit residuals versus x and y respectively +y,s Graph the y fit residuals versus x and y respectively +d,u Delete or undelete the data point nearest the cursor +o Overplot the next graph +c Toggle the constant x, y plotting option +t Plot a line of constant x, y through the nearest data point +l Print xshift, yshift, xmag, ymag, xrotate, yrotate +q Exit the interactive curve fitting +.fi + +The parameters listed below can be changed interactively with simple colon +commands. Typing the parameter name alone will list the current value. + +.nf +:show List parameters +:fitgeometry Fitting geometry (shift,xyscale,rotate, + rscale,rxyscale,general) +:function [value] Fitting function (chebyshev,legendre, + polynomial) +:xxorder :xyorder [value] X fitting function xorder, yorder +:yxorder :yyorder [value] Y fitting function xorder, yorder +:xxterms :yxterms [n/h/f] X, Y fit cross terms type +:maxiter [value] Maximum number of rejection iterations +:reject [value] Rejection threshold +.fi + +The final fit is stored in a simple text file in a format suitable for use +by the GREGISTER or GEOTRAN tasks. + +If \fIverbose\fR is "yes", various pieces of useful information are printed +to the terminal as the task proceeds. If \fIresults\fR is set to a file name +then the input coordinates, the fitted coordinates, and the residuals of +the fit are written to that file. + +The transformation computed by the "general" fitting geometry is arbitrary +and does not correspond to a physically meaningful model. However the computed +coefficients for the linear term can be given a simple geometrical geometric +interpretation for all the fitting geometries as shown below. + +.nf + fitting geometry = general (linear term) + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + + fitting geometry = shift + xin = a + xref + yin = d + yref + + fitting geometry = xyscale + xin = a + b * xref + yin = d + f * yref + + fitting geometry = rotate + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/-1 + b = f, c = -e or b = -f, c = e + + fitting geometry = rscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const + b = f, c = -e or b = -f, c = e + + fitting geometry = rxyscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const +.fi + +The coefficients can be interpreted as follows. Xref0, yref0, xin0, yin0 +are the origins in the reference and input frames respectively. Orientation +and skew are the rotation of the x and y axes and their deviation from +perpendicularity respectively. Xmag and ymag are the scaling factors in x and +y and are assumed to be positive. + +.nf + general (linear term) + xrotation = rotation - skew / 2 + yrotation = rotation + skew / 2 + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + shift + xrotation = 0.0, yrotation = 0.0 + xmag = ymag = 1.0 + b = 1.0 + c = 0.0 + e = 0.0 + f = 1.0 + a = xin0 - xref0 = xshift + d = yin0 - yref0 = yshift + + xyscale + xrotation 0.0 / 180.0 yrotation = 0.0 + b = + /- xmag + c = 0.0 + e = 0.0 + f = ymag + a = xin0 - b * xref0 = xshift + d = yin0 - f * yref0 = yshift + + rscale + xrotation = rotation + 0 / 180, yrotation = rotation + mag = xmag = ymag + const = mag * mag + b = mag * cos (xrotation) + c = mag * sin (yrotation) + e = -mag * sin (xrotation) + f = mag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + rxyscale + xrotation = rotation + 0 / 180, yrotation = rotation + const = xmag * ymag + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift +.fi + + +.ih +EXAMPLES +1. Compute the linear transformation between coordinate systems. + A record called "m51.coo" will be written in the database + file "database". + + +.nf + cl> geomap m51.coo database 1. 512. 1. 512. +.fi + +2. Compute the 3rd order transformation in x and y between two + coordinate systems. A record called "m51.coo" will be written in + the database file "database". This record supersedes the one + of the same name written in example 1. + +.nf + cl> geomap m51.coo database 1. 512. 1. 512. xxo=4 xyo=4 \ + >>> yxo=4 yyo=4 xxt=full yxt=full inter- +.fi + +3. Register a 500 by 500 image of m51 to an 800 by 800 image of the same +field taken with a different instrument, and display the original +800 by 800 image and the transformed image. Use the default fitting parameters. + +.nf + cl> geomap m51.coo database 1.0 800.0 1.0 800.0 + cl> gregister m51.500 m51.500.out database m51.coo + cl> display m51.800 1 fi+ + cl> display m51.500.out 2 fi+ +.fi + +4. Use the above transform to transform a list of object pixel coordinates +in the m51.800 image to their pixel coordinates in the m51.500 system. + +.nf + cl> geoxytran m51.800.xy m51.500.xy database m51.coo +.fi + +5. Transform object pixel coordinates in the m51.500 image to their +pixel coordinates in the m51.800 image. Note that to do this the roles +of the reference and input coordinates defined in example 3 must be +reversed and the inverse transform must be computed. + +.nf + cl> fields m51.coo 3,4,1,2 > m51.coo.inv + cl> geomap m51.coo.inv database 1.0 512.0 1.0 512.0 + cl> geoxytran m51.512.xy m51.800.xy database m51.coo.inv +.fi + +6. Compute 3 different transforms, store them in the same database file, +and use them to transform 3 different images. Use the original image names as +the database record names. + +.nf + cl> geomap coo1,coo2,coo3 database 1. 512. 1. 512. \ + >>> transforms=im1,im2,im3 + cl> gregister im1,im2,im3 im1.out,im2.out,im3.out database \ + >>> im1,im2,im3 +.fi + +.ih +BUGS + +The user should be aware that for high order fits the "polynomial" basis +functions become very unstable. Switching to the "legendre" or "chebyshev" +polynomials and/or going to double precision will usually cure the problem. + +.ih +SEE ALSO +imshift, magnify, rotate, imlintran, gregister, geotran, geoxytran +.endhelp diff --git a/pkg/images/immatch/doc/geotran.hlp b/pkg/images/immatch/doc/geotran.hlp new file mode 100644 index 00000000..e3ad15f7 --- /dev/null +++ b/pkg/images/immatch/doc/geotran.hlp @@ -0,0 +1,320 @@ +.help geotran Dec98 images.immatch +.ih +NAME +geotran -- geometrically transform a list of images +.ih +USAGE +geotran input output database transforms +.ih +PARAMETERS +.ls input +List of images to be transformed. +.le +.ls output +List of output images. If the output image name is the same as the input +image name the input image is overwritten. The output image may be a section +of an existing image. The number of output images must equal the number +of input images. +.le +.ls database +The name of the text file containing the coordinate transformation (generally +the database file produced by GEOMAP). +If database is the null string then GEOTRAN will perform a linear +transformation based the values of xin, yin, xout, yout, xshift, yshift, +xmag, ymag, xrotation and yrotation. If all these parameters have their +defaults values the transformation is a null transformation. If the geometric +transformation is linear xin, yin, xout, yout, xshift, yshift, xmag, ymag, +xrotation and yrotation can be used to override the values in the database +file. +.le +.ls transforms +The list of record name(s) in the file \fIdatabase\fR containing the +desired transformations. +This record name is usually the name of the text file input to geomap +listing the reference and input coordinates of the control points. +The number of records must be 1 or equal to the number of input images. +The record names may be listed in a text file 1 record per line. +The transforms parameter is only +requested if database is not equal to the null string. +.le +.ls geometry = "geometric" +The type of geometric transformation. The geometry parameter is +only requested if database is not equal to the null string. The options are: +.ls linear +Perform only the linear part of the geometric transformation. +.le +.ls geometric +Compute both the linear and distortion portions of the geometric correction. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum x and y reference values of the output image. +If a database file has been defined xmin, xmax, ymin and ymax +efault to the minimum and maximum values set by +GEOMAP and may be less than but may not exceed those values. +.le +.ls xscale = 1.0, yscale = 1.0 +The output picture x and y scales in units of +x and y reference units per output pixel, +e.g arcsec / pixel or Angstroms / pixel if the reference coordinates +are arcsec or Angstroms. If the reference coordinates are in pixels +then xscale and yscale should be 1.0 to preserve the scale of the reference +image. +If xscale and yscale are undefined (INDEF), xscale and yscale default to the +range of the reference coordinates over the range in pixels. +Xscale and yscale override the values of ncols and nlines. +.le +.ls ncols = INDEF, nlines = INDEF +The number of columns and lines in the output image. Ncols and nlines default +to the size of the input image. If xscale or yscale are defined ncols or nlines +are overridden. +.le +.ls xsample = 1.0, ysample = 1.0 +The coordinate surface subsampling factor. The coordinate surfaces are +evaluated at every xsample-th pixel in x and every ysample-th pixel in y. +Transformed coordinates at intermediate pixel values are determined by +bilinear interpolation in the coordinate surfaces. If the coordinate +surface is of high order setting these numbers to some reasonably high +value is strongly recommended. +.le +.ls interpolant = "linear" +The interpolant used for rebinning the image. +The choices are the following. +.ls nearest +Nearest neighbor. +.le +.ls linear +Bilinear interpolation in x and y. +.le +.ls poly3 +Third order polynomial in x and y. +.le +.ls poly5 +Fifth order polynomial in x and y. +.le +.ls spline3 +Bicubic spline. +.le +.ls sinc +2D sinc interpolation. Users can specify the sinc interpolant width by +appending a width value to the interpolant string, e.g. sinc51 specifies +a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to +the nearest odd number. The default sinc width is 31 by 31. +.le +.ls lsinc +Look-up table sinc interpolation. Users can specify the look-up table sinc +interpolant width by appending a width value to the interpolant string, e.g. +lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user +supplied sinc width will be rounded up to the nearest odd number. The default +sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup +table sinc by appending the look-up table size in square brackets to the +interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc +look-up table interpolant with a pixel resolution of 0.05 pixels in x and y. +The default look-up table size and resolution are 20 by 20 and 0.05 pixels +in x and y respectively. +.le +.ls drizzle +2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y +by appending a value between 0.0 and 1.0 in square brackets to the +interpolant string, e.g. drizzle[0.5]. The default value is 1.0. +The value 0.0 is increased internally to 0.001. Drizzle resampling +with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel +rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no) if +xmag and ymag are > 1.0. +.le +.le +.ls boundary = "nearest" +The choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a user supplied constant value. +.le +.ls reflect +Generate a value by reflecting about the boundary of the image. +.le +.ls wrap +Generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0.0 +The value of the constant for boundary extension. +.le +.ls fluxconserve = yes +Preserve the total image flux. The output pixel values are multiplied by +the Jacobian of the coordinate transformation. +.le +.ls xin = INDEF, yin = INDEF +The x and y coordinates in pixel units in the input image which will map to +xout, yout in the output image. If the database file is undefined these +numbers default to the center of the input image. +.le +.ls xout = INDEF, yout = INDEF +The x and y reference coordinates in the output image which correspond +to xin, yin in the input image. If the database file is undefined, xout and +yout default to the center of the output image reference coordinates. +.le +.ls xshift = INDEF, yshift = INDEF +The shift of the input origin in pixels. If the database file is undefined +then xshift and yshift determine the shift of xin, yin. +.le +.ls xmag = INDEF, ymag = INDEF +The scale factors of the coordinate transformation in units of input pixels +per reference coordinate unit. If database is undefined xmag and ymag +default to 1.0; otherwise xmag and ymag default to the values found +by GEOMAP. If the database file is not null then xmag and ymag override +the values found by GEOMAP. +.le +.ls xrotation = INDEF, yrotation = INDEF +The rotation angles in degrees of the coordinate transformation. +Positive angles are measured counter-clockwise with respect to the x axis. +If database +is undefined then xrotation and yrotation default to 0.0; otherwise +xrotation and yrotation default to the values found by GEOMAP. +If database is not NULL then xrotation and yrotation override the values +found by GEOMAP. +.le +.ls nxblock = 512, nyblock = 512 +If the size of the output image is less than nxblock by nyblock then +the entire image is transformed at once. Otherwise the output image +is computed in blocks of nxblock by nxblock pixels. +.le +.ls verbose = yes +Print messages about the progress of the task ? +.le +.ih +DESCRIPTION + +GEOTRAN corrects an image for geometric distortion using the coordinate +transformation determined by GEOMAP. The transformation is stored as the +coefficients of a polynomial surface in record \fItransforms\fR, +in the text file \fIdatabase\fR. +The coordinate surface is sampled at every \fIxsample\fR and \fIysample\fR +pixel in x and y. +The transformed coordinates at intermediate pixel values are +determined by bilinear interpolation in the coordinate surface. If +\fIxsample\fR and \fIysample\fR = 1, the coordinate +surface is evaluated at every pixel. Use of \fIxsample\fR and \fIysample\fR +are strongly recommended for large images and high order coordinate +surfaces in order to reduce the execution time. + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the range of +reference coordinates represented in the output picture. These numbers +default to the minimum and maximum x and y reference values used by GEOMAP, +and may not exceed those values. +The scale and size of the output picture is determined as follows. + +.nf + ncols = ncols (inimage) + if (xscale == INDEF) + xscale = (xmax - xmin ) / (ncols - 1) + else + ncols = (xmax - xmin) / xscale + 1 + + nlines = nlines (inimage) + if (yscale == INDEF) + yscale = (ymax - ymin ) / (nlines - 1) + else + nlines = (ymax - ymin) / yscale + 1 +.fi + +The output image gray levels are determined by interpolating in the input +image at the positions of the transformed output pixels. If the +\fIfluxconserve\fR switch is set the output pixel values are multiplied by +the Jacobian of the transformation. +GEOTRAN uses the routines in the 2-D interpolation package. + +The linear portion of the transformation may be altered after the fact +by setting some or all of the parameters \fIxin\fR, \fIyin\fR, \fIxout\fR, +\fIyout\fR, \fIxshift\fR, \fIyshift\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, +\fIyrotation\fR. +Xin, yin, xshift, yshift, xout and yout can be used to redefine the shift. +Xmag, and ymag can be used to reset the x and y scale of the transformation. +Xrotation and yrotation can be used to reset the orientation of the +transformation. + +The output image is computed in \fInxblock\fR by \fInyblock\fR pixel sections. +If possible users should set these numbers to values larger than the dimensions +of the output image to minimize the number of disk reads and writes required +to compute the output image. If this is not feasible and the image rotation is +small, users should set nxblock to be greater than the number of columns in +the output image, and nyblock to be as large as machine memory will permit. + +If the CL environment variable \fInomwcs\fR is "no" then the world +coordinate system of the input image will be modified in the output image +to reflect the effects of the \fIlinear\fR portion of the geometric +transformation operation. +Support does not yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that GEOTRAN is capable of +performing. + +.ih +TIMINGS +It requires approximately 70 and 290 cpu seconds to correct a 512 by 512 +square image for geometric distortion using a low order coordinate surface +and bilinear and biquintic interpolation respectively (Vax 11/750 fpa). + +.ih +EXAMPLES + +1. Register two images by transforming the coordinate system of the input +image to the coordinate system of the reference image. The size of the +reference image is 512 by 512. The output image scale will be 1.0 and +its size will be determined by the xmin, xmax, ymin, ymax parameters set +in the task GEOMAP. The file "database" containing the record "m51.coo" +was produced by GEOMAP. + +.nf + cl> geomap m51.coo database 1.0 512.0 1.0 512.0 + cl> geotran m51 m51.tran database m51.coo +.fi + +2. Repeat the above command but set the output image scale to 2.0 reference +images pixels per output image pixel. + +.nf + cl> geomap m51.coo database 1.0 512.0 1.0 512.0 + cl> geotran m51 m51.tran database m51.coo xscale=2.0 yscale=2.0 +.fi + +3. Repeat the previous command using an output scale of +2 reference units per pixel and bicubic spline interpolation with no +flux correction. + +.nf + cl> geomap m51.coo database 1.0 512.0 1.0 512.0 + cl> geotran m51 m51.tran database m51.coo xscale=2. yscale=2. \ + >>> inter=spline3 flux- +.fi + +4. Register a list of 512 by 512 pixel square images using the set of +transforms computed by GEOMAP. The input images, output images, and coordinate +lists / transforms are listed in the files inlist, outlist and reclist +respectively. + +.nf + cl> geomap @reclist database 1. 512. 1. 512. + cl> geotran @inlist @outlist database @reclist +.fi + +5. Mosaic 3 512 square images into a larger 512 by 1536 square images after +applying a shift to each input image. + +.nf + cl> geotran image1 outimage[1:512,1:512] "" ncols=512 nlines=1536 \ + xshift=5.0 yshift=5.0 + cl> geotran image2 outimage[1:512,513:1024] "" xshift=10.0 yshift=10.0 + cl> geotran image3 outimage[1:512,1025:1536] "" xshift=15.0 yshift=15.0 +.fi + +.ih +BUGS +Support does not yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that GEOTRAN is capable of +performing. + +.ih +SEE ALSO +imshift, magnify, rotate, imlintran, geomap, geoxytran, gregister +.endhelp diff --git a/pkg/images/immatch/doc/geoxytran.hlp b/pkg/images/immatch/doc/geoxytran.hlp new file mode 100644 index 00000000..69e8565c --- /dev/null +++ b/pkg/images/immatch/doc/geoxytran.hlp @@ -0,0 +1,408 @@ +.help geoxytran Apr95 images.immatch +.ih +NAME +geoxytran -- geometrically transform a list of coordinates +.ih +USAGE +geoxytran input output database transforms +.ih +PARAMETERS +.ls input +The list of input coordinate files to be transformed. +.le +.ls output +The list of output transformed coordinate files. The number of output files must +be one or equal to the number of input files. +.le +.ls database +The name of the text database file written by the geomap task which +contains the desired spatial transformation. +If database is undefined geoxytran computes +a linear transformation using the current +values of the xref, yref, xout, yout, xshift, yshift, xmag, ymag, xrotation, +and yrotation parameters. +.le +.ls transforms +The database record containing the desired spatial transformation. +The number of records must be one or equal to the number of input coordinate +files. Transforms is usually the name of the coordinate file that the +geomap task used to compute the spatial transformation. +If defined the values of xref, yref, xout, yout, xshift, yshift, xmag, ymag, +xrotation, and yrotation will supersede the computed values in the +database file. +.le +.ls geometry = "geometric" (linear|geometric) +The type of geometric transformation. The geometry parameter is +only requested if database is defined. The options are: +.ls linear +Perform only the linear part of the spatial transformation. +.le +.ls geometric +Compute both the linear and distortion portions of the spatial transformation. +.le +.le +.ls direction = "forward" (forward|backward) +The transformation direction may be "forward" or "backward". The forward +direction directly evaluates the database solution. The backward +direction iteratively determines the coordinate which evaluates to the +specified coordinate. +.le +.ls xref = INDEF, yref = INDEF +The x and y coordinates of the reference origin. +If the database file is undefined xref and +yref default to [0.0,0.0]. Otherwise xref and yref +default to the mean of minimum and maximum x and y values +[(xmin + xmax) / 2.0, (ymin + ymax) / 2.0] computed by geomap. +.le +.ls xmag = INDEF, ymag = INDEF +The x and y scale factors in input units +per reference unit. If database is undefined xmag and ymag +default to [1.0, 1.0]. Otherwise xmag and ymag default to the values computed +by geomap. +.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, 0.0]. For example xrotation and yrotation values of +[30.0, 30.0] will rotate a point 30 counter-clockwise with respect +to the x and y axes. Otherwise xrotation and yrotation default to the +values computed by geomap. Geomap computes the x and y rotation angles +of the x and y axes, not the rotation angle of the coordinates. An output +coordinate system rotated 30 degrees counter-clockwise with respect +to the reference coordinate system will produce xrotation and yrotation +values of [330.0,330.0] or equivalently [-30.0,-30.0] in the database file +not [30.0,30.0]. +.le +.ls xout = INDEF, yout = INDEF +The x and y coordinates of the output origin. +If the database file is undefined xout and +yout default to [0.0,0.0]. +If database is defined xout and yout +default to the position that the reference origin [xref,yref] +occupies in the transformed system. +.le +.ls xshift = INDEF, yshift = INDEF +The x and y shift of the reference origin in output units. +If the database file is undefined xshift and yshift default to [0.0,0.0]. +If the database file is defined xshift and yshift default to the +values computed by geomap. If defined xshift and yshift take precedence over +the x and y shifts determined from xref, yref, xout and yout. +.le +.ls xcolumn = 1, ycolumn = 2 +The columns in the input coordinate file containing the x and y coordinates. +.le +.ls calctype = "real" +The precision of the coordinate transformation calculations. The options +are "real" and "double". Note that this only applies to a "forward" +transformation. The "backward" transformation is done iteratively and +is always calculated in double precision to get the best convergence. +.le +.ls xformat = "", yformat = "" +The default output format for the computed x and y coordinates. If +xformat and yformat are undefined geoxytran outputs the coordinates +using the maximum of the precision of the input coordinates +and the value of the \fImin_sigdigits\fR parameter. +.le +.ls min_sigdigits = 7 +The minimum precision of the output x and y coordinates. +.le + +.ih +DESCRIPTION + +GEOXYTRAN applies a coordinate transformation to a list of reference +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, columns +\fIxcolumn\fR and \fIycolumn\fR in the input and output +files. The format of the output coordinates can be specified using the +\fIxformat\fR and \fIyformat\fR parameters. If the output formats +are unspecified the coordinates are written out with a precision +which is the maximum of the precision of the input coordinates +and the value of the \fImin_sigdigits\fR parameter. All 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 coordinate transformation either be read from record \fItransforms\fR +in the database file \fIdatabase\fR computed by GEOMAP, or specified +by the user via the \fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR, +\fIxrotation\fR, \fIyrotation\fR, \fIxout\fR, \fIyout\fR, \fIxshift\fR, +and \fIyshift\fR parameters. + +The transformation computed by GEOMAP has the following form. + +.nf + xout = f (xref, yref) + yout = g (xref, yref) +.fi + +The functions f and g are either a power series polynomial or a Legendre +or Chebyshev polynomial surface whose order and region of validity were +set by the user when GEOMAP was run. The computed transformation 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 + xout = a + b * xref + c * yref + yout = d + e * xref + f * yref + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = x0 - b * xref0 - c * yref0 = xshift + d = y0 - e * xref0 - f * yref0 = xshift +.fi + +Xref0, yref0, x0, and +y0 are the origins of the reference and output coordinate systems +respectively. xmag and ymag are the x and y scale factors in output units +per reference unit and xrotation and yrotation are the rotation angles measured +counter-clockwise of the x and y axes. + +The linear portion of the GEOMAP transformation may be altered after the fact +by setting some or all of the parameters \fIxref\fR, \fIyref\fR, \fIxout\fR, +\fIyout\fR, \fIxshift\fR, \fIyshift\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, +and \fIyrotation\fR. If defined these parameters will replace the corresponding +values in the GEOMAP database file. +Xref, yref, xshift, yshift, xout and yout can be used to redefine the shift +where xshift and yshift take precedence over xref, yref, xout and yout. +Xmag, and ymag can be used to reset the scale of the transformation. +Xrotation and yrotation can be used to redefine the orientation of the +transformation. Note that xrotation and yrotation are interpreted as +the rotation of the coordinate axes not the coordinates. +The default values of these parameters are. + +.nf + xref = (xmin + xmax) / 2.0 + yref = (ymin + ymax) / 2.0 + xout = f (xref,yref) + yout = g (xref,yref) + xshift = xshift (database) = xout - f(xref,yref) + yshift = yshift (database) = yout - g(xref,yref) + xmag = xmag (database) + ymag = ymag (database) + xrotation = xrotation (database) + yrotation = yrotation (database) +.fi + +If the GEOMAP database is undefined then GEOXYTRAN performs a linear +transformation on the input coordinates using the parameters +\fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, +\fIyrotation\fR, \fIxout\fR, \fIyout\fR, \fIxshift\fR, and +\fIyshift\fR as shown below. Note that in this case xrotation and +yrotation are interpreted as the rotation of the coordinates +themselves not the coordinate axes. + +.nf + xout = a + b * xref + c * yref + yout = d + e * xref + f * yref + b = xmag * cos (xrotation) + c = -ymag * sin (yrotation) + e = xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xo - b * xref0 - c * yref0 = xshift + d = yo - e * xref0 - f * yref0 = xshift +.fi + + +.ih +Forward vs. Backward Transformations + +The transformation direction is specified by the \fIdirection\fR parameter +which may take the values "forward" or "backward". The forward transformation +is a direct evaluation of the database solution. The backward +transformation is an iterative evaluation to obtain the coordinate which +evaluates to the desired coordinate. + +When the same solution is used with \fBgeotran\fR to transform an image +to another image matching the "reference" image is needed to obtain +coordinates in the transformed image. This is because the transformation +is produced with \fBgeomap\fR to map "reference" coordinates to the +image which is subsequently transformed. Therefore, if you have coordinates +in the image which has been transformed then you should use the "backward" +transformation to get coordinates for the transformed image. But if you +have standard coordinates from the reference image being matched then you +would use the "forward" transformation. If you are not sure then you can +use \fBtvmark\fR to overlay the results to find which direction produces +the desired coordinates. + +Because the backward transformation is performed iteratively it can be +slow. If higher speeds are desired, such as when evaluating a very +large number of coordinates, one might create a transformation solution +that can be evaluated in the forward direction. This is done by +using \fBgeomap\fR with the reference and target coordinates reversed. + +.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 transformation from the reference system to the output +system and then evaluate the transformation for both the input list and +the list of unknowns. + + cl> type rtran + + 1.0000 1.0000 184.1445 -153.0376 + 512.0000 1.0000 684.0376 184.1445 + 512.0000 512.0000 346.8555 684.0376 + 1.0000 512.0000 -153.0380 346.8555 + + cl> geomap rtran rtran.db 1.0 512.0 1.0 512.0 intera- + + cl> type rtran.db + + # Tue 14:53:36 18-Apr-95 + begin rtran + output rtran.db + xrefmean 256.5 + yrefmean 256.5 + xmean 265.4999 + ymean 265.5 + xshift 183.826 + yshift -154.6757 + xmag 1.180001 + ymag 1.179999 + xrotation 326. + yrotation 326. + surface1 11 + 3. 3. + 2. 2. + 2. 2. + 0. 0. + 1. 1. + 512. 512. + 1. 1. + 512. 512. + 183.826 -154.6757 + 0.9782647 0.6598474 + -0.6598479 0.9782643 + surface2 0 + + cl> geoxytran rtran STDOUT rtran.db rtran + + 184.1444 -153.038 184.1445 -153.0376 + 684.0377 184.1444 684.0376 184.1445 + 346.8554 684.0375 346.8555 684.0376 + -153.038 346.8555 -153.038 346.8555 + + cl> geoxytran unknowns unknowns.tran rtran.db rtran + + +2. Evaluate the backward transformation to take coordinates from the +output system to the reference system. In this example we use the +output of the first example to illustrate getting back the coordinates +used in the original geomap input. + + cl> geoxytran rtran STDOUT rtran.db rtran dir=forward |\ + >>> geoxytran STDIN STDOUT rtran.db rtran dir=backward + 0.999798 0.9997257 184.1445 -153.0376 + 512. 0.9999674 684.0376 184.1445 + 512. 512. 346.8555 684.0376 + 0.999918 512.0001 -153.0380 346.8555 + + +3. Evaluate the transform computed in example 1 for the same list of +unknowns but modify the transformation slightly by setting xmag +and ymag to 1.18 and 1.18 exactly. + + cl> geoxytran unknowns unknowns.tran rtran.db rtran xmag=1.18 \ + ymag=1.18 + + +4. Evaluate the same transformation for the same unknowns as before +using the linear transformation parameters not the transform computed +by geomap. Note that the angle is the negative of the one defined +in the database file. + + cl> geoxytran unknowns unknowns.tran "" xmag=1.18 ymag=1.18 \ + xrot=34 yrot=34 xshift=183.826 yshift=-154.6757 +.fi + +.ih +BUGS + +.ih +SEE ALSO +geomap, lists.lintran, geotran, gregister +.endhelp diff --git a/pkg/images/immatch/doc/gregister.hlp b/pkg/images/immatch/doc/gregister.hlp new file mode 100644 index 00000000..73dff3d4 --- /dev/null +++ b/pkg/images/immatch/doc/gregister.hlp @@ -0,0 +1,265 @@ +.help gregister Dec98 images.immatch +.ih +NAME +gregister -- transform a list of images from one coordinate system to another +.ih +USAGE +gregister input output database transforms +.ih +PARAMETERS +.ls input +List of images to be transformed. +.le +.ls output +List of output images. +.le +.ls database +The name of the text file database produced by GEOMAP containing the coordinate +transformation(s). +.le +.ls transforms +The list of the database record(s) containing the transformations. +The number of transforms must be 1 or the same as the number of input +images. Transforms is usually the name of the +text file input to GEOMAP which lists the reference and input +coordinates of the control points. +.le +.ls geometry = "geometric" +The type of geometry to be applied: The choices are: +.ls linear +The linear part, shifts, scales and rotations are computed. +.le +.ls geometric +The full transformation is computed. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum x and y reference values of the output image. +Xmin, xmax, ymin and ymax default to minimum and maximum values set in GEOMAP, +and may not extend beyond the bounds of those parameters. +.le +.ls xscale = 1.0, yscale = 1.0 +The output x and y scales in units of reference x and y +units per pixel, e.g "/ pixel or Angstroms / pixel if the reference +coordinates +are arc-seconds or Angstroms. If the reference coordinates are in pixels +then xscale and yscale should be 1.0 to preserve the scale of the reference +image. The default is set for pixel coordinates. +If xscale and yscale are undefined (INDEF), xscale and yscale default to the +range of the reference coordinates over the range in pixels. +Xscale and yscale override the values of ncols and nlines. +.le +.ls ncols = INDEF, nlines = INDEF +The number of columns and lines in the output image. Ncols and nlines default +to the size of the input image. If xscale or yscale are defined ncols or nlines +are overridden. +.le +.ls xsample = 1.0, ysample = 1.0 +The coordinate surface subsampling factor. The coordinate surfaces are +evaluated at every xsample-th pixel in x and every ysample-th pixel in y. +Transformed coordinates at intermediate pixel values are determined by +bilinear interpolation in the coordinate surfaces. +.le +.ls interpolant = "linear" +The choices are the following. +.ls nearest +Nearest neighbor. +.le +.ls linear +Bilinear interpolation in x and y. +.le +.ls poly3 +Third order polynomial in x and y. +.le +.ls poly5 +Fifth order polynomial in x and y. +.le +.ls spline3 +Bicubic spline. +.le +.ls sinc +2D sinc interpolation. Users can specify the sinc interpolant width by +appending a width value to the interpolant string, e.g. sinc51 specifies +a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to +the nearest odd number. The default sinc width is 31 by 31. +.le +.ls lsinc +Look-up table sinc interpolation. Users can specify the look-up table sinc +interpolant width by appending a width value to the interpolant string, e.g. +lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user +supplied sinc width will be rounded up to the nearest odd number. The default +sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup +table sinc by appending the look-up table size in square brackets to the +interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc +look-up table interpolant with a pixel resolution of 0.05 pixels in x and y. +The default look-up table size and resolution are 20 by 20 and 0.05 pixels +in x and y respectively. +.le +.ls drizzle +2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y +by appending a value between 0.0 and 1.0 in square brackets to the +interpolant string, e.g. drizzle[0.5]. The default value is 1.0. +The value 0.0 is increased internally to 0.001. Drizzle resampling +with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel +rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no) if +xmag and ymag are > 1.0. +.le +.le +.ls boundary = "nearest" +The boundary extension choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a constant value. +.le +.ls reflect +Generate value by reflecting about the boundary. +.le +.ls wrap +Generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0. +The value of the constant for boundary extension. +.le +.ls fluxconserve = yes +Preserve the total image flux. The output pixel values are multiplied by +the Jacobian of the coordinate transformation. +.le +.ls nxblock = 512, nyblock = 512 +If the dimensions of the output image are less than nxblock and nyblock +then the entire image is transformed at once. Otherwise blocks of size +nxblock by nyblock are transformed one at a time. +.le +.ls verbose = yes +Print messages about the progress of the task ? +.le +.ih +DESCRIPTION + +GREGISTER corrects an image for geometric distortion using the coordinate +transformation computed by GEOMAP. The transformation is stored as the +coefficients of a polynomial surface in record \fItransforms\fR, +in the text file \fIdatabase\fR. +The coordinate surface is sampled at every \fIxsample\fR and \fIysample\fR +pixel in x and y. +The transformed coordinates at intermediate pixel values are +determined by bilinear interpolation in the coordinate surface. If +\fIxsample\fR and \fIysample\fR = 1, the coordinate +surface is evaluated at every pixel. Use of \fIxsample\fR and \fIysample\fR +are strongly recommended for large images and high order coordinate +surfaces in order to reduce the execution time. + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the range of +reference coordinates represented in the output picture. These numbers +default to the minimum and maximum x and y reference values used by GEOMAP, +and may not exceed these values. +The scale and size of the output picture is determined as follows. + +.nf + ncols = ncols(input) + if (xscale == INDEF) + xscale = (xmax - xmin ) / (ncols - 1) + else + ncols = (xmax - xmin) / xscale + 1 + + nlines = nlines(input) + if (yscale == INDEF) + yscale = (ymax - ymin ) / (nlines - 1) + else + nlines = (ymax - ymin) / yscale + 1 +.fi + +The output image gray levels are determined by interpolating in the input +image at the positions of the transformed output pixels. If the +\fIfluxconserve\fR switch is set the output pixel values are multiplied by +the Jacobian of the transformation. GREGISTER uses the routines in the +2-D interpolation package. + +The output image is computed in \fInxblock\fR by \fInyblock\fR pixel sections. +If possible users should set these numbers to values larger than the dimensions +of the output image, in order to minimize the number of disk reads and writes +required to compute the output image. If this is not feasible and the image +rotation is small users should set nxblock to be greater than the number of +columns in the output image, and nyblock to be as large as machine memory +will permit. + +If the environment variable \fInomwcs\fR is "no" then the world coordinate +system of the input image is modified in the output image to reflect the +effects of the \fIlinear\fR portion of the registration operation. +Support does not yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that GREGISTER is capable +of performing. + +.ih +TIMINGS +It requires approximately 70 and 290 cpu seconds to correct a 512 by 512 +square image for geometric distortion using a low order coordinate surface +and bilinear and biquintic interpolation respectively (Vax 11/750 far). + +.ih +EXAMPLES +.ls 4 1. +Transform an image to the reference coordinate system of a 512 by 512 pixel +square image. The output image will have the same scale and size as the +reference image if the reference coordinates are in pixels. + +.nf +cl> geomap coords database 1.0 512.0 1.0 512.0 +cl> gregister input output database coords +.fi +.le +.ls 4 2. +Repeat the previous example but rescale the output image. The scale of the +output image will be 2.5 reference units per pixel and its size will be +determined by the xmin, xmax, ymin, ymax parameters (1.0, 512.0, 1.0, 512.0). + +.nf +cl> geomap coords database 1.0 512.0 1.0 512.0 +cl> gregister input output database coords xscale=2.5 yscale=2.5 +.fi +.le +.ls 4 3. +Correct an image for 3rd order geometric distortion using an output scale of 2 +reference units per pixel unit and bicubic spline interpolation with no flux +correction. + +.nf +cl> geomap coords database 1.0 512.0 1.0 512.0 xxorder=4 xyorder=4 \ +xxterms=yes yxorder=4 yyorder=4 yxterms=yes +cl> gregister input output database coords xscale=2. yscale=2. \ +>>> inter=spline3 flux- +.fi +.le +.ls 4 4. +Transform three images using 3 different transformation records stored +in the database file. + +.nf +cl> geomap coord1,coord2,coord3 database 1. 512. 1. 512. +cl> gregister im1,im2,im3 imout1,imout2,imout3 database \ +>>> coord1,coord2,coords3 +.fi +.le +.ls 4 5. +Repeat the above example using the textfiles inlist, outlist, reclist which +contain the list of input images, list of output images and list of coordinate +files respectively. + +.nf +cl> geomap @reclist database 1. 512. 1. 512. +cl> gregister @inlist @outlist database @reclist +.fi +.le + +.ih +BUGS +Support does yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that GREGISTER is capable +of performing. + +.ih +SEE ALSO +imshift, magnify, rotate, imlintran, geomap, geotran, geoxytran +.endhelp diff --git a/pkg/images/immatch/doc/imalign.hlp b/pkg/images/immatch/doc/imalign.hlp new file mode 100644 index 00000000..c63be5bc --- /dev/null +++ b/pkg/images/immatch/doc/imalign.hlp @@ -0,0 +1,316 @@ +.help imalign Feb90 images.immatch +.ih +NAME +imalign -- register a list of images by computing relative object shifts +.ih +USAGE +imalign input reference coords output +.ih +PARAMETERS +.ls input +The input images to be shifted and trimmed. The input image list should +contain the reference image so that its borders are +used in the computation of the overlap region. +.le +.ls reference +The reference image to which the input images will be aligned. +.le +.ls coords +A text file containing the reference image coordinates of the registration +objects to be centered in each image, one object per line with the x and y +coordinates in columns one and two respectively. +.le +.ls output +The output images. +.le +.ls shifts = "" +A text file containing the initial estimate for each image of the +shift in each axis relative to the reference image. These +estimates are used to modify the coordinates of the registration +objects prior to centering. The format of the file is one image per +line with the x and y shifts in columns one and two respectively. +The sense of the shifts is such that: \fIXshift=Xref-Xin\fR and +\fBYshift=Yref-Yin\fR. If \fIshifts\fR is null, a coarse centering +pass will be made to attempt to determine the initial shifts. +.le +.ls boxsize = 7 +The size in pixels of the box to use for the final centering, during +which all the sources in \fIcoords\fR are recentered in each image +using the initial estimate of the relative shift for each image. +Care should be taken to choose an appropriate value for this parameter, +since it is highly data dependent. +.le +.ls bigbox = 11 +The size in pixels of the box to use for coarse centering. The coarse +pass through the centering algorithm is made with the box centered at +the nominal position of the first source in the coordinate list. +Coarse centering is performed only if the shifts file is undefined. +Care should be taken to choose an appropriate value for this parameter, +since it is highly data dependent. Large values should be suspect until +the final results are checked to see that the centering did not converge +on the wrong coordinates, although the usual result for an inappropriate +\fIbigbox\fR size is that the algorithm fails to converge and the task +aborts. +.le +.ls negative = no +Are the features negative ? +.le +.ls background = INDEF +The absolute reference level for the marginal centroid calculation. +If background is INDEF, this is set to the mean value (between the +thresholds) of the individual sources. +.le +.ls lower = INDEF +The lower threshold for the data. Individual pixels less than this +value will be given zero weight in the centroids. +.le +.ls upper = INDEF +The upper threshold for the data. Individual pixels greater than this +value will be given zero weight in the centroids. +.le +.ls niterate = 3 +The maximum number of centering iterations to perform. The centering +will halt when this limit is reached or when the desired Itolerance +is achieved. +.le +.ls tolerance = 0 +The tolerance for convergence of the centering algorithm. This is the +integral shift of the centering box from one iteration to the next. +.le +.ls maxshift = INDEFR +The maximum permitted difference between the predicted shift and the +the computed shift for each object. Objects with shifts greater than +maxshift are ignored. If maxshift is undefined no shift checking is done. +.le +.ls shiftimages = yes +If shiftimages is yes, the IMSHIFT task will be used to align the +images. If shiftimages is no, the images will not be aligned, but +the coordinates will still be centered. +.le +.ls interp_type = "spline3" +The interpolation function used by the IMSHIFT task. +.le +.ls boundary_type = "constant" +The boundary extension type used by the IMSHIFT task. +.le +.ls constant = 0. +The constant used by the IMSHIFT task if \fIboundary_type\fR is "constant". +.le +.ls trimimages = yes +If trimimages is yes, the output images will be trimmed to +include only the region over which they all overlap. The +trim section that is actually used may differ slightly from that +reported by IMCENTROID, due to a correction applied to compensate for +the boundary extension "contamination" near the edges of the images. +.le +.ls verbose = yes +Print the centers, shifts, and trim section? +.le +.ih +DESCRIPTION +IMALIGN measures the X and Y axis shifts between a list of input images +\fIinput\fR and a reference image \fIreference\fR, registers the +input images to the reference image using the computed shifts, +and trims the input images to a common overlap region. +The task is meant to address the class of two dimensional image +registration problems in which the images have the same pixel scale, +are shifted relative to each other by simple x and y translations, and contain +enough high signal / noise, pointlike sources in common to compute good +average positions. The basic operation of the task is to find centers +for the list of registration objects or features in the coordinate +frame of each image and then to subtract the corresponding centers +found in the reference image. The shifts of the registration objects +are averaged for each image. + +IMALIGN is a simple script front end for IMCENTROID, which computes the +shifts, IMSHIFT, which shifts the images, and +IMCOPY, which performs the trimming. + +A list of the X and Y coordinates of the registration objects should be +provided via the \fIcoords\fR parameter. The registration objects do not +all have to be common to each frame; only that subset of the +objects that is contained within the bounds of a given image will be +centered. Only the objects that are common to both the given image and +the reference will be used to calculate the shifts. The coordinates +must be measured in the frame of the reference image. If coarse +centering is to be done, which is to say, if no \fIshifts\fR file is +provided, then the first registration source should be separated from +other sources by at least the maximum expected relative shift. + +An initial estimate of the shifts between each of the input images and +the reference image is required for the centering algorithm (a marginal +centroid) to work. This estimate can be explicitly supplied in the file +\fIshifts\fR (\fIXshift=Xref-Xin\fR and \fIYshift=Yref-Yin\fR) or can +be generated from the images by measuring the relative shift of the +first source listed in the coords file for each image. This coarse +centering pass requires that the first source be detached from other +sources and from the border of each image, by a distance that is at +least the maximum shift between the reference and input image. This +source should be pointlike and have a high signal to noise ratio. The +value of the \fIbigbox\fR parameter should be chosen to include the +location of the source in each of the images to be aligned while +excluding other sources. Large values of \fIbigbox\fR should be held +suspect until the final convergence of the centering algorithm is +verified, although given a small value for the \fItolerance\fR, the +quality of the final centers is independent of the estimate for the +initial shifts. Better convergence may also be obtained by increasing +the \fIniterate\fR parameter, although the default value of three +should work for most cases. \fINiterate\fR should be kept small to +avoid runaway. + +The \fIboxsize\fR parameter controls the size of the centering box for +the fine centering passes and should be chosen so as to exclude sky +background and other sources while including the wings of the point +spread function. The sense of the shifts that are calculated is +consistent with the file supplied to the \fIshifts\fR parameter and +with that used with the IMSHIFT task. + +If \fIshiftimages\fR is yes the images will actually be shifted using +the IMSHIFT task. Note that if \fIinterp_type\fR is "nearest" the +effect on the images is the same as if the shifts were rounded to +integral values. In this case, the pixels will be shifted without +interpolation. This can be used for data in which it is more important +to preserve the pixel values than it is to achieve perfect +registration. + +If \fItrimimages\fR is yes, the output images will be trimmed to +include only the region over which they all overlap. The trim section +that is actually used may differ slightly from that reported by +IMCENTROID. A one or two pixel correction may be applied to each edge +to compensate for the boundary extension "contamination" due to +multi-pixel (e.g., \fIinterp_type\fR = poly5) interpolation near the +edges of the images. + +IMALIGN may be used with a set of \fIimages\fR which vary in size. +This can result in vignetting of the calculated overlap region because +of the nature of the IMSHIFT task to preserve the size of an input +image. To visualize this, imagine a large reference image and a single +small image to be aligned to it, both containing the same registration +object which is at the center of each image. IMALIGN will cause the +small image to be shifted such that the object is positioned at the same +pixel location as in the reference. In performing the shift, a large +fraction of the area of the small image may be shifted outside of its +own borders, whereas the physical overlap of the large and small images +includes ALL of the pixels of the small image. In the case of such +vignetting, IMALIGN will print a warning message and refuse to proceed +with the trimming although the vignetting will occur whether or not the +images are trimmed. Note that the vignetting will not occur if the +small image is used as the \fIreference\fR. + +The vignetting message may also be printed if the \fIimages\fR are all +the same size but the \fIreference\fR is not included in the list. +This will occur if the sense of the measured shifts in a coordinate are +all positive or all negative since in this case the border of the +\fIreference\fR would have provided one of the limits to the trim +section. The reality of this vignetting depends on your point of view. + +Trimming will also not be performed if the entire overlap region vanishes. + +Note that many of these difficulties are due to the intrinsically fuzzy +nature of the process of image registration. This all leads to a few +"rules of thumb": + +.nf + o Include the reference image in the input image list + + o Use the smallest image as the reference image + + o Choose the reference image such that the input images are + scattered to either side in the shifts in each axis + + o Align images that are the same size, OR + + o Pad dissimilar sized images with blanks to + the largest size and disable trimming +.fi +.ih +CENTERING ALGORITHM +The algorithm is a "marginal" centroid in which the fit for each axis +is performed separately upon a vector created by collapsing the +centering box perpendicular to that axis. The centroid is calculated +with respect to the level specified by \fIbackground\fR. If +\fIbackground\fR is INDEF, the reference level for each source in each +image is the local mean for those pixels that lie between the +\fIlower\fR and \fIupper\fR thresholds. The thresholds are set to the +local data minimum or maximum if \fIlower\fR or \fIupper\fR, +respectively, are INDEF. If \fInegative\fR is yes, than the marginal +vector will be inverted before being passed to the centroid algorithm. + +The maximum number of centering iterations and the tolerance for +convergence are controlled by \fIniterate\fR and \fItolerance\fR. Note +that the tolerance is an integer value that represents the maximum +movement of the centering box between two successive iterations. The +default value of 0 requires that the centroid lie within the center +pixel of the centering box which is \fIboxsize\fR in extent (note that +\fIboxsize\fR must be an odd number). This should normally be the case +for bright, circularly symmetric point sources in images with a flat +sky background. If the registration sources are not circular symmetric +try increasing the tolerance gingerly. A sky level that varies across +the image should be removed before processing. The centering and +calculation of the shifts may be performed with \fIshiftimages\fR = no +(or directly with IMCENTROID) and the calculated shifts applied to the +images directly with IMSHIFT. + +.ih +EXAMPLES +1. Align three images to the first using the list of registration star +coordinates in the file "x1.coords". + +.nf + cl> imalign x1,x2,x3 x1 x1.coords x1.out,x2.out,x3.out +.fi + +2. Align a list of images contained in the file "imlist", overwriting the +original images with the shifted and trimmed images: + +.nf + cl> imalign @imlist x1 x1.coords @imlist +.fi + +3. Align the images leaving the output images the same size as the input +images: + +.nf + cl> imalign @imlist x1 x1.coords @outlist trimimages- +.fi + +4. Perform the centering but not the shifts: + +.nf + cl> imalign @imlist x1 x1.coords shiftimages- +.fi + +5. Perform the centering, but don't calculate the shifts at all, +and don't shift the image. + +.nf + pr> imalign @imlist "" x1.coords shiftimages- +.fi + +.ih +BUGS +The images being shifted must be in the current directory. + +The coarse centering portion of the algorithm can be fooled if the +first source on the list is not well separated from other sources, or +if the first source has a low signal to noise ratio, or if there is a +complicated shape to the background. + +The task can produce output images that do not contain the entire +overlap region. This can only occur if the images are of varying sizes. +This behavior is caused by the action of the IMSHIFT task to preserve the +size of an input image, thus implicitly "trimming" the image. A work +around is to use IMCOPY to place the images into subsections of blank +images that are the size (in each dimension) of the largest image(s) +and use IMALIGN with \fItrimimages\fR set to no. The borders of the output +images can be trimmed manually. This is discussed above in more detail. + +If \fIimages\fR does not contain the \fIreference\fR and \fItrimimages\fR +is set to yes then the set of shifted and trimmed images may no longer +be aligned to the reference. This occurs because any place holder +pixels at the bottom and left edges of the images will be trimmed off. +This is also discussed above. +.ih +SEE ALSO +imcentroid, center, imshift, geomap, geotran +.endhelp diff --git a/pkg/images/immatch/doc/imcentroid.hlp b/pkg/images/immatch/doc/imcentroid.hlp new file mode 100644 index 00000000..c284d9be --- /dev/null +++ b/pkg/images/immatch/doc/imcentroid.hlp @@ -0,0 +1,257 @@ +.help imcentroid Jan97 images.immatch +.ih +NAME +imcentroid -- center sources in images, optionally find shifts + +.ih +USAGE +imcentroid input reference coords + +.ih +PARAMETERS + +.ls input +The list of images within which sources are to be centered. If a +\fIreference\fR image is specified, imcentroid will calculate the mean +X and Y shifts between the centered sources within each image and those +same sources within the reference image. The input image list +should normally include the reference image so that its borders are +used in the calculation of the overlap region. +.le +.ls reference = "" +The reference image to which the input images will be aligned. If +a reference image is specified the mean X and Y shifts between each of +the input images and the reference image will be calculated, otherwise +only the centers for the individual sources will be reported. +.le +.ls coords +A text file containing the coordinates of the registration objects to +be centered in each image, one object per line with the x and y +coordinates in columns one and two respectively. These coordinates +should be measured in the frame of the reference image. +.le +.ls shifts = "" +A text file containing the initial estimate for each image of the +shift in each axis relative to the reference image. These +estimates are used to modify the coordinates of the registration +objects prior to centering. The format of the file is one image per +line with the fractional x and y shifts in columns one and two +respectively. The sense of the shifts is such that: +Xshift =Xref - Xin and shift= Yref - Yin. If shifts is undefined, +a coarse centering pass will be made to attempt to determine +the initial shifts. +.le +.ls boxsize = 7 +The size in pixels of the box to use for the final centering, during +which all the sources in the coords file are recentered in each image +using the initial estimate of the relative shift for each image. +Care should be taken to choose an appropriate value for this parameter, +since it is highly data dependent. +.le +.ls bigbox = 11 +The size in pixels of the box to use for coarse centering. The coarse +pass through the centering algorithm is made with the box centered at +the nominal position of the first source in the coordinate list. +Coarse centering is performed only if the shifts file is undefined. +Care should be taken to choose an appropriate value for this parameter, +since it is highly data dependent. Large value should be suspect until +the final results are checked to see that the centering did not converge +on the wrong coordinates, although the usual result for an inappropriate +bigbox size is that the algorithm fails to converge and the task +aborts. +.le +.ls negative = no +Are the features negative ? +.le +.ls background = INDEF +The absolute reference level for the marginal centroid calculation. +If background is INDEF, this is set to the mean value (between the +thresholds) of the individual sources. +.le +.ls lower = INDEF +The lower threshold for the data. Individual pixels less than this +value will be given zero weight in the centroids. +.le +.ls upper = INDEF +The upper threshold for the data. Individual pixels greater than this +value will be given zero weight in the centroids. +.le +.ls niterate = 3 +The maximum number of centering iterations to perform. The centering +will halt when this limit is reached or when the desired tolerance +is achieved. +.le +.ls tolerance = 0 +The tolerance for convergence of the centering algorithm. This is the +integral shift of the centering box from one iteration to the next. +.le +.ls maxshift = INDEFR +The maximum permitted difference between the predicted shift and the +the computed shift for each object. Objects with shifts greater than +maxshift are ignored. If maxshift is undefined no shift checking is done. +.le +.ls verbose = yes +Print the centers for the individual objects ? If verbose is no +only the shifts relative to the reference coordinates will be reported. +If no reference image is supplied, verbose is automatically set to yes. +.le + +.ih +DESCRIPTION + +IMCENTROID measures the X and Y coordinates of a list of sources in a +list of images and finds the mean X and Y shifts between the input +images \fIinput\fR and a \fIreference\fR image, where the shifts are +defined as the shifts that should be added to the input image coordinates to +convert them into the reference coordinates. The task is meant to +address the class of two dimensional image registration problems in +which the images have the same pixel scale, are shifted relative to +each other by simple translations in each axis, and contain enough high +signal-to-noise, pointlike sources in common to form good average +positions. The basic operation of the task is to find centers for the +list of registration objects in the coordinate frame of each image and +then to subtract the corresponding centers found in the reference +image. The shifts of the objects are averaged for each image. + +A list of the X and Y coordinates of the registration objects should be +provided in the coordinates file \fIcoords\fR. The registration objects do not +all have to be common to each frame, rather only that subset of the +objects that is contained within the bounds of a given image will be +centered. Only the objects that are common to both the given image and +the reference will be used to calculate the shifts. The coordinates +should be measured in the frame of the reference image\fIreference\fR. +If coarse centering is to be done, which is to say, if no \fIshifts\fR file is +provided, then the first registration source should be separated from +other sources by at least the maximum expected relative shift. + +An initial estimate of the shifts between each of the input images +\fIinput\fR and the reference image \fIreference\fR is required for the +centering algorithm (a marginal centroid) to work. This estimate can be +explicitly supplied in the text file \fIshifts\fR where Xshift = Xref -Xin +and Yshift = Yref -Y in, or can be generated from the images by measuring +the relative shift of the first source listed in the coordinates file +\fIcoords\fR for each input image. This coarse +centering pass requires that the first source be detached from other +sources and from the border of each image by a distance that is at +least the maximum shift between the reference and input image. This +source should be pointlike and have a high signal to noise ratio. The +value of the \fIbigbox\fR parameter should be chosen to include the +location of the source in each of the images to be aligned while +excluding other sources. Large values of \fIbigbox\fR should be held +suspect until the final convergence of the centering algorithm is +verified, although given a small value for the \fItolerance\fR, the +quality of the final centers is independent of the estimate for the +initial shifts. Better convergence may also be obtained by increasing +the \fIniterate\fR parameter, although the default value of three +should work for most cases. \fINiterate\fR should be kept small to +avoid runaway. + +The \fIboxsize\fR parameter controls the size of the centering box for +the fine centering pass and should be chosen so as to exclude sky +background and other sources while including the wings of the point +spread function. The sense of the shifts that are calculated is +consistent with the file supplied to the \fIshifts\fR parameter and +with that used with the IMSHIFT task. + +IMCENTROID may be used with a set of input images which vary in size. +This can result in vignetting of the calculated overlap region because +of the nature of tasks such as IMSHIFT to preserve the size of an input +image. To visualize this, imagine a large reference image and a single +small image to be aligned to it, both containing the same registration +object which is at the center of each image. IMCENTROID will cause the +coordinate system of the small image to be shifted such that the object +will be positioned at the same pixel location as in the reference. If +the shift is performed, a large fraction of the area of the small image +may be shifted outside of its own borders, whereas the physical overlap +of the large and small images includes ALL of the pixels of the small +image. In the case of such vignetting, IMCENTROID will print a warning +message and both the vignetted and unvignetted trim sections. Note +that the vignetting will not occur if the small image is used as the +reference image. + +The vignetting message may also be printed if the input images are all +the same size but the reference image is not included in the list. +This will occur if the sense of the measured shifts in a coordinate are +all positive or all negative since in this case the border of the +reference image would have provided one of the limits to the trim +section. The reality of this vignetting depends on your point of view. + +Note that many of these difficulties are due to the intrinsically fuzzy +nature of the process of image registration. This all leads to a few +guidelines: + +.nf + o Include the reference image in the input image list + + o Use the smallest image as the reference image + + o Choose the reference image such that the input images + are scattered to either side in the shifts in each axis + + o Align images that are the same size, OR + + o Pad dissimilar sized images with blanks to the largest size +.fi + +.ih +CENTERING ALGORITHM + +The algorithm is a "marginal" centroid in which the fit for each axis +is performed separately upon a vector created by collapsing the +centering box perpendicular to that axis. The centroid is calculated +with respect to the level specified by \fIbackground\fR. If +\fIbackground\fR is INDEF, the reference level for each source in each +image is the local mean for those pixels that lie between the +\fIlower\fR and \fIupper\fR thresholds. The thresholds are set to the +local data minimum or maximum if \fIlower\fR or \fIupper\fR, +respectively, are INDEF. If \fInegative\fR is yes, than the marginal +vector will be inverted before being passed to the centroid algorithm. + +The maximum number of centering iterations and the tolerance for +convergence are controlled by \fIniterate\fR and \fItolerance\fR. Note +that the tolerance is an integer value that represents the maximum +movement of the centering box between two successive iterations. The +default value of 0 requires that the centroid lie within the center +pixel of the centering box which is \fIboxsize\fR in extent (note that +\fIboxsize\fR must be an odd number). This should normally be the case +for bright, circularly symmetric point sources in images with a flat +sky background. If the registration sources are not circular symmetric +try increasing the tolerance gingerly. If the sky background is not +flat, but varies across the image, it can be removed before processing. + +.ih +EXAMPLES + +1. Calculate the shifts between three images using the first image +as a reference image and the list of registration star coordinates in +the file "x1.coords". + +.nf + cl> imcentroid x1,x2,x3 x1 x1.coords +.fi + +2. Calculate the shifts between a list of images contained in the file +"imlist": + +.nf + pr> imcentroid @imlist x1 x1.coords +.fi + +3. Perform the centering, but don't calculate the shifts, i.e., don't +supply a reference image. Note that the \fIinput\fR list of shifts, +or a coarse centering pass are still needed: + +.nf + pr> imcentroid @imlist "" x1.coords +.fi + +.ih +BUGS +The coarse centering portion of the algorithm can be fooled if the +first source on the list is not well separated from other sources, or +if the first source has a low signal to noise ratio, or if there is a +complicated shape to the background. +.ih +SEE ALSO +imalign, imshift, xregister, geomap, geotran +.endhelp diff --git a/pkg/images/immatch/doc/imcombine.hlp b/pkg/images/immatch/doc/imcombine.hlp new file mode 100644 index 00000000..720fe785 --- /dev/null +++ b/pkg/images/immatch/doc/imcombine.hlp @@ -0,0 +1,1471 @@ +.help imcombine Aug01 images.immatch +.ih +NAME +imcombine -- Combine images using various algorithms +.ih +USAGE +imcombine input output +.ih +PARAMETERS +.ls input +List of input images to combine. If the \fIproject\fR parameter is "no" +then all input images must have the same dimensionality though they may +be of different sizes. Otherwise each input image is handled separately +and they may have different dimensionalities. +.le + + +When the \fIproject\fR parameter is "no" all the input images are combined +into a single output file. In this case the following parameters specify +only a single file name. Otherwise each input image is combined by +projecting (combining across) the highest dimension to produce a lower +dimensional image. For this type of combining there is one output for each +input and so the following parameters specify matching lists. + +.ls output +Output combined image(s). If there are fewer than 100 input images the +names of the input images are recorded in header keywords IMCMBnnn. +.le +.ls headers = "" (optional) +Optional output multiextension FITS file(s). The extensions are dataless +headers from each input image. +.le +.ls bpmasks = "" (optional) +Optional output bad pixel mask(s) with good values of 0 and bad values of +1. Output pixels are marked as bad when no input pixels contributed to the +output pixel. The file name is also added to the output image header under +the keyword BPM. +.le +.ls rejmask = "" (optional) +Optional output mask file(s) identifying rejected or excluded pixels. The +pixel mask is the size of the output image but there is one extra dimension +with length equal to the number of input images. Each element of the +highest dimension is a mask corresponding to an input image with values of +1 for rejected or excluded pixels and values of 0 for pixels which were +used. The order of the masks is the order of the input images and image +header keywords, indexed by the pixel coordinate of the highest dimension +identify the input images. Note that the pixel positions are in the output +pixel coordinate system. +.le +.ls nrejmasks = "" (optional) +Optional output pixel mask(s) giving the number of input pixels rejected or +excluded from the input images. +.le +.ls expmasks = "" (optional) +Optional output exposure mask(s) giving the sum of the exposure values of +the input images with non-zero weights that contributed to that pixel. +Since masks are integer, the exposure values may be scaled to preserve +dynamic range and fractional significance. The scaling values are given in +the header under the keywords MASKSCAL and MASKZERO. Exposure values are +computed from the mask values by scale * value + zero where scale is the +value of the MASKSCAL keyword and zero is the value of the MASKZERO +keyword. +.le +.ls sigma = "" (optional) +Optional output sigma image(s). The sigma is the standard deviation, +corrected for a finite population, of the input pixel values (excluding +rejected pixels) about the output combined pixel values. +.le + +.ls imcmb = "$I" (optional) +A keyword in the input images that is copied +to one of the IMCMBnnn keywords in the output image. A null string +does not set the IMCMBnnn keywords nor deletes any existing keywords. +Any other value will delete existing keywords before creating new ones. +The special value "$I" specifies the basename of the input image name. +If a keyword is specified that does not exist in the input image(s) then +no ICMB keyword will be produced; it is not a error for the keyword to +not exist. +.le +.ls logfile = "STDOUT" (optional) +Optional output log file. If no file is specified then no log information is +produced. The special filename "STDOUT" prints log information to the +terminal. +.le + +.ls combine = "average" (average|median|lmedian|sum|quadrature|nmodel) +Type of combining operation performed on the final set of pixels (after +offsetting, masking, thresholding, and rejection). The choices are: + +.nf + average - weighted average + median - median + lmedian - median except use the lower value if only two + sum - (weighted) sum + quadrature - weighted quadrature average + nmodel - weighted quadrature average of noise model values +.fi + +The details of each choice is given in the DESCRIPTION. +Note that if weights are used then the weighted "sum" is the same as +the weighted "average" since the weights are normalized to unit total weight. +The "lmedian" option is intended for minimizing the effects of cosmic rays +when there are more than two images but some pixels may only have two +contributing images. The "quadrature" and "nmodel" options are used +for error propagation either with input sigma images (quadrature) or where the +pixel sigmas may be computed by the noise model used by this task (nmodel). +.le +.ls reject = "none" (none|minmax|ccdclip|crreject|sigclip|avsigclip|pclip) +Type of rejection operation performed on the pixels remaining after offsetting, +masking and thresholding. The algorithms are described in the +DESCRIPTION section. The rejection choices are: + +.nf + none - No rejection + minmax - Reject the nlow and nhigh pixels + ccdclip - Reject pixels using CCD noise parameters + crreject - Reject only positive pixels using CCD noise parameters + sigclip - Reject pixels using a sigma clipping algorithm + avsigclip - Reject pixels using an averaged sigma clipping algorithm + pclip - Reject pixels using sigma based on percentiles +.fi + +.le +.ls project = no +Project (combine) across the highest dimension of the input images? If +"no" then all the input images are combined to a single output image. If +"yes" then the highest dimension elements of each input image are combined to +an output image and optional pixel list and sigma images. Each element of +the highest dimension may have a separate offset. +.le +.ls outtype = "real" (none|short|ushort|integer|long|real|double) +Output image pixel datatype. The pixel datatypes are "double", "real", +"long", "integer", unsigned short "ushort", and "short" with highest +precedence first. If "none" is specified then the highest precedence +datatype of the input images is used. When there is a mixture of +short and unsigned short images the highest precedence become integer. +The datatypes may be abbreviated to a single character. +.le +.ls outlimits = "" +Output region limits specified as pairs of whitespace separated values. +The first two numbers are the limits along the first output image dimension, +the next two numbers are the limits along the second dimension, and so on. +If the higher dimension limits are not specified they default to the full +range. Therefore, if no limits are specified then the full output is +created. Note that the output size is computed from all the input images +including offsets if specified and the coordinates are relative to that +size. +.le +.ls offsets = "none" (none|wcs|world|physical|grid|<filename>) +Integer offsets to add to each image axes. The options are: +.ls "none" +No offsets are applied. +.le +.ls "wcs" or "world" +The world coordinate system (wcs) in the image is used to derive the +offsets. The nearest integer offset that matches the world coordinate +at the center of the first input image is used. +.le +.ls "physical" +The physical coordinate system defined by the IRAF LTM/LTV keywords +define the offsets. +.le +.ls "grid" +A uniform grid of offsets is specified by a string of the form + +.nf + grid [n1] [s1] [n2] [s2] ... +.fi + +where ni is the number of images in dimension i and si is the step +in dimension i. For example "grid 5 100 5 100" specifies a 5x5 +grid with origins offset by 100 pixels. +.le +.ls <filename> +The offsets are given in the specified file. The file consists +of one line per image with the offsets in each dimension forming the +columns. +.le +.le +.ls masktype = "none" +Type of pixel masking to use. The choices are + +.nf + none - No pixel masking + goodvalue - good pixels defined by maskvalue parameter + badvalue - bad pixels defined by maskvalue parameter + novalue - pixels with no value defined by maskvalue parameter + goodbits - good pixels defined by maskvalue parameter + badbits - bad pixels defined by maskvalue parameter +.fi + +Except for "none", these choices use the mask specified by the header +keyword BPM. To use a different keyword to specify the mask the syntax +is + +.nf + !<keyword> [goodvalue|badvalue|novalue|goodbits|badbits] +.fi + +where if the optional second word is missing the default is "goodvalue". + +If "none" (or "") no pixel masking is done +even if an image has an associated pixel mask. The masking defines +pixels to be used (good) and not used (bad). The types use the +"maskvalue" parameter to define a single value (either as a number or +set of bits) for good or bad and all other values are treated as the +opposite; i.e. bad or good respectively. + +The "novalue" choice uses 0 as the good value and all other values are +bad. However, the "maskvalue" parameter defines a mask value for pixels +with no value such as occurs from rebinning at the edges or stacking where +there is no overlap at all. The distinction pixels is that when a final pixel +has no overlapping data because all input pixels have a "no value" flag +the blank value is output while if there is no good data then pixels which +are have other than the "no value" flag are combined as if they were good +to produce a representative output value. An output mask will have a +value of 0 for pixels where at least one good input value was present, +a value of 1 when there was no overlapping data, and a value of 2 when +bad data was used. +.le +.ls maskvalue = 0 +Mask value used with the \fImasktype\fR parameter. If the mask type +selects good or bad bits the value may be specified using IRAF notation +for decimal, octal, or hexadecimal; i.e 12, 14b, 0cx to select bits 3 +and 4. +.le +.ls blank = 0. +Output value to be used when there are no pixels for combining after any +rejection. +.le + +.ls scale = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Multiplicative image scaling to be applied. The choices are none, multiply +by the reciprocal of the mode, median, or mean of the specified statistics +section, multiply by the reciprocal of the exposure time in the image header, +multiply by the values in a specified file, or multiply by a specified +image header keyword. When specified in a file the scales must be one per +line in the order of the input images. +.le +.ls zero = "none" (none|mode|median|mean|@<file>|!<keyword>) +Additive zero level image shifts to be applied. The choices are none, add +the negative of the mode, median, or mean of the specified statistics +section, add the values given in a file, or add the values given by an +image header keyword. When specified in a file the zero values must be one +per line in the order of the input images. File or keyword zero offset +values do not allow a correction to the weights. +.le +.ls weight = "none" (none|mode|median|mean|exposure|@<file>|!<keyword>) +Weights to be applied during the final averaging. The choices are none, +the mode, median, or mean of the specified statistics section, the exposure +time, values given in a file, or values given by an image header keyword. +When specified in a file the weights must be one per line in the order of +the input images and the only adjustment made by the task is for the number of +images previously combined. In this case the weights should be those +appropriate for the scaled images which would normally be the inverse +of the variance in the scaled image. +.le +.ls statsec = "" +Section of images to use in computing image statistics for scaling and +weighting. If no section is given then the entire region of the input is +sampled (for efficiency the images are sampled if they are big enough). +When the images are offset relative to each other one can precede the image +section with one of the modifiers "input", "output", "overlap". The first +interprets the section relative to the input image (which is equivalent to +not specifying a modifier), the second interprets the section relative to +the output image, and the last selects the common overlap and any following +section is ignored. +.le +.ls expname = "" +Image header keyword to be used with the exposure scaling and weighting +options. Also if an exposure keyword is specified that keyword will be +added to the output image using a weighted average of the input exposure +values. +.le + +.ce +Algorithm Parameters +.ls lthreshold = INDEF, hthreshold = INDEF +Low and high thresholds to be applied to the input pixels. This is done +before any scaling, rejection, and combining. If INDEF the thresholds +are not used. +.le +.ls nlow = 1, nhigh = 1 (minmax) +The number of low and high pixels to be rejected by the "minmax" algorithm. +These numbers are converted to fractions of the total number of input images +so that if no rejections have taken place the specified number of pixels +are rejected while if pixels have been rejected by masking, thresholding, +or non-overlap, then the fraction of the remaining pixels, truncated +to an integer, is used. +.le +.ls nkeep = 1 +The minimum number of pixels to retain or the maximum number to reject +when using the clipping algorithms (ccdclip, crreject, sigclip, +avsigclip, or pclip). When given as a positive value this is the minimum +number to keep. When given as a negative value the absolute value is +the maximum number to reject. The latter is in addition to pixels +missing due to non-overlapping offsets, bad pixel masks, or thresholds. +.le +.ls mclip = yes (ccdclip, crreject, sigclip, avsigcliip) +Use the median as the estimate for the true intensity rather than the +average with high and low values excluded in the "ccdclip", "crreject", +"sigclip", and "avsigclip" algorithms? The median is a better estimator +in the presence of data which one wants to reject than the average. +However, computing the median is slower than the average. +.le +.ls lsigma = 3., hsigma = 3. (ccdclip, crreject, sigclip, avsigclip, pclip) +Low and high sigma clipping factors for the "ccdclip", "crreject", "sigclip", +"avsigclip", and "pclip" algorithms. They multiply a "sigma" factor +produced by the algorithm to select a point below and above the average or +median value for rejecting pixels. The lower sigma is ignored for the +"crreject" algorithm. +.le +.ls rdnoise = "0.", gain = "1.", snoise = "0." (ccdclip, crreject) +Readout noise in electrons, gain in electrons/DN, and sensitivity noise as +a fraction. These parameters are used with the "ccdclip" and "crreject" +algorithms as well as with the "nmodel" combining option. The values may +be either numeric or an image header keyword which contains the value. +The noise model for a pixel is: + +.nf + variance in DN = (rdnoise/gain)^2 + DN/gain + (snoise*DN)^2 + variance in e- = (rdnoise)^2 + (gain*DN) + (snoise*(gain*DN))^2 + = rdnoise^2 + Ne + (snoise * Ne)^2 +.fi + +where DN is the data number and Ne is the number of electrons. Sensitivity +noise typically comes from noise introduced during flat fielding. +.le +.ls sigscale = 0.1 (ccdclip, crreject, sigclip, avsigclip) +This parameter determines when poisson corrections are made to the +computation of a sigma for images with different scale factors. If all +relative scales are within this value of unity and all relative zero level +offsets are within this fraction of the mean then no correction is made. +The idea is that if the images are all similarly though not identically +scaled, the extra computations involved in making poisson corrections for +variations in the sigmas can be skipped. A value of zero will apply the +corrections except in the case of equal images and a large value can be +used if the sigmas of pixels in the images are independent of scale and +zero level. +.le +.ls pclip = -0.5 (pclip) +Percentile clipping algorithm parameter. If greater than +one in absolute value then it specifies a number of pixels above or +below the median to use for computing the clipping sigma. If less +than one in absolute value then it specifies the fraction of the pixels +above or below the median to use. A positive value selects a point +above the median and a negative value selects a point below the median. +The default of -0.5 selects approximately the quartile point. +See the DESCRIPTION section for further details. +.le +.ls grow = 0. +Radius in pixels for additional pixel to be rejected in an image with a +rejected pixel from one of the rejection algorithms. This applies only to +pixels rejected by one of the rejection algorithms and not the masked or +threshold rejected pixels. +.le + +.ce +Environment Variables + +.ls imcombine_maxmemory (default = 250000000) +This task tries to use the maximum possible memory for efficiency when +dealing with lots of data and is designed to reduce memory usage if +memory allocation fails. However, there may be cases where this adjustment +fails so this variable allows forcing the task to stay within a smaller +allocation. This variable is in bytes and the default is the amount +generally returned by the system. It is large because of virtual memory +functionality. If problems are encountered one should try setting this +variable to a smaller size until, hopefully, the out of memory errors +disappear. +.le +.ls imcombine_option (default = 1) +This environment variable is used to select certain experimental or +diagnostic options. If this variable has the value 1, the default when the +variable is undefined, then when the number of images exceeds the number of +files that can be kept open under IRAF (currently this means more than 4000 +images) the images are closed and opened as needed. This is in contrast to +the previous method, when the variable has the value 0, which first builds +a single stacked image of a higher dimension from the input images. This +method requires the images all have the same size and also that there be +sufficient disk space for the stacked image and that the image be less +than 2Gb in size. +.le +.ih +DESCRIPTION +A set of images or the highest dimension elements (for example +the planes in an image cube) are combined by weighted averaging, medianing, +or summing. Pixels may be rejected from the combining by using pixel +masks, threshold levels, and rejection algorithms. The images may be +scaled, before rejections, multiplicatively, additively, or both based on +image statistics, image header keywords, or text files. The images may be +combined with integer pixel coordinate offsets, possibly determined using +the world coordinate system of the images, to produce an image bigger than +any of the input images. + +The input images to be combined are specified by a list. If the +\fBproject\fR parameter is "yes" then the highest dimension elements of +each input image are combined to make an output image of one lower +dimension. There is no limit to the number of elements combined in this +case. If \fBproject\fR is "no" then the entire input list is combined to +form a single output image. In this case the images must all have the +same dimensionality but they may have different sizes. There is a software +limit of approximately 4000 images which may be open +simultaneously. To combine more than this number the program may either +create a temporary stacked image, requiring the images to be of the same +size, or repeatedly open and close the images. See the "Environment +Variables" in the PARAMETERS section. + +The output image header is a copy of the first image in the combined set. +In addition, the number of images combined is recorded under the keyword +NCOMBINE. The value of a keyword in the input images, where the +keyword is specified by the parameter \fIimcmb\fR, is written to an +indexed keyword IMCMBnnn. The purpose of the ICMBnnn keywords is to +identify the contributors to the output image. One common choice is +the input image name though other identifiers may be used. + +If a bad pixel mask is created, the name of the mask will be included in the +output image header under the keyword BPM. The output pixel type is set by +the parameter \fIouttype\fR. If left blank then the input datatype of +highest precision is used. If there is a mixture of short and unsigned +short images then the highest precision is integer. + +In addition to one or more output combined images there are some optional +output files which may be specified as described in the OPTIONAL OUTPUT +section. + +An outline of the steps taken by the program is given below and the +following sections elaborate on the steps. + +.nf +o Check the input images and stack them if needed +o Set the input image offsets and the final output image size. +o Set the input image scales and weights possibly by computing + image statistics +o Write the log file and optional header output +.fi + +For each output image line: + +.nf +o Get input image lines that overlap the output image line +o Reject masked pixels +o Reject pixels outside the threshold limits +o Reject pixels using the specified algorithm +o Reject neighboring pixels along each line +o Combine remaining pixels using the weighted average or median +o Compute sigmas of remaining pixels about the combined values +o Write the output image line and other optional images. +.fi + +OPTIONAL OUTPUTS + +There are various additional outputs that may be produced by providing +the filenames. + +.ls Headers +The output image can only have one set of header keywords which are +inherited from the first input image in the input list. Copies of all the +input headers may be stored in a multiextension FITS file specified by the +\fIheaders\fR parameter. The extension names are the input image names. +The extensions are dataless headers. Since this means the image sizes are +lost, AXLEN keywords are added. Also the keywords INIMAGE and OUTIMAGE are +added giving the name of the input image and the name of the output +combined image. +.le +.ls Bad Pixel Masks +The \fIbpmasks\fR parameter produces optional output bad pixel mask(s) with +good values of 0 and bad values of 1. Output pixels are marked as bad when +no input pixels contributed to the output pixel. The file name is also +added to the output image header under the keyword BPM. +.le +.ls Rejection Masks +The \fIrejmasks\fR parameter produces optional output mask file(s) +identifying rejected or excluded pixels. The pixel mask is the size of the +output image. There is one extra dimension with length equal to the number +of input images. Each element of the highest dimension is a mask +corresponding to an input image with values of 1 for rejected or excluded +pixels and values of 0 for pixels which were used. The order of the masks +is the order of the input images and image header keywords indexed by the +element identify the input images. Note that the pixel positions are in +the output pixel coordinate system. + +This mask is the only way to record whether a particular input image pixel +contributed to the output image. As an example, consider the case of +three input two dimensional images of sizes 1020x1020, 1010x1010, and +1000x1000 with relative offsets of (0,0), (10,10), and (20,20). The output +image would then be 1020x1020. + +Suppose that the only input pixels not used are pixels (1,1) in each input +image. Because of the offsets the first 10 rows and columns of the output +will be based on just a single pixel except for (1,1) which has no input +pixels. The next 10 rows and columns of the output will be a combination +of 2 input pixels except (11,11) which is just based on pixel (11,11) +in the first input image. Finally all other pixels except (21,21) will be +a combination of 3 values. + +The rejection mask will be three dimensional of size 1020x1020x3. Plane 1 +will correspond to the first input image, plane 2 to the second, and so +on. All of the pixels will be zero except for the following pixels +which will have a value of 1. In the first plane only pixel (1,1,1) will be +one. In the second plane the first 10 rows and columns and pixel (11,11,2) +will be one. And in the third plane, the first 20 rows and columns and pixel +(21,21,3) will be one. So if we want to know about output pixel (11,11) +the rejection mask will tell us that pixels from the second and third +images were excluded. + +This is a complex example because of the offsets and dissimilar sizes. +In the more common and simpler case of equal sizes and registered images, +the mask +planes would have one to indicate that the pixel in the input image at +that coordinate was not used. For instance if pixel (12,15,2) is one +in the rejection mask then pixel (12,15) in the second input image was +excluded. + +Note that one can use image sections to extract a mask matching the input +image. For the example case with the offsets masks in the input +coordinates can be extracted with the commands + +.nf + cl> imcopy rejmask[*,*,1] mask1 + cl> imcopy rejmask[11:1020,11:1020,2] mask2 + cl> imcopy rejmask[21:1020,21:1020,3] mask3 +.fi + +For the case of equal sized and registered images one could also use +\fBimslice\fR. +.le +.ls Mask of the Number of Rejected Pixels +The \fInrejmasks\fR parameter produces optional pixel mask(s) giving the +number of input pixels rejected or excluded from the input images. This is +equivalent to projecting the rejection mask described previously by summing +along the highest dimension. Note that in this mask a value of 0 indicates +all the input pixels were used to create the output pixel and a value equal +to the number of input images indicate no input pixels were used. +.le +.ls Exposure Masks +The \fIexpmasks\fR parameter produces optional output exposure mask(s) +giving the sum of the exposure values of the input images with non-zero +weights that contributed to that pixel. Since masks are integer, the +exposure values may be scaled to preserve dynamic range and fractional +significance. The scaling values are given in the header under the +keywords MASKSCAL and MASKZERO. Exposure values are computed from the mask +values by scale * value + zero where scale is the value of the MASKSCAL +keyword and zero is the value of the MASKZERO keyword. +.le +.ls Sigma of Combined Pixels +The \fIsigma\fR parameter produces optional output sigma image(s). The +sigma is the standard deviation, corrected for a finite population, of the +input pixel values (excluding rejected pixels) about the output combined +pixel values. +.le +.ls Output Log File +The \fIlogfile\fR parameter produces an optional output log file. If no +file is specified then no log information is produced. The special +filename "STDOUT" prints log information to the terminal. +.le + +OFFSETS + +The images to be combined need not be of the same size or overlap. They +do have to have the same dimensionality which will also be the dimensionality +of the output image. Any dimensional images supported by IRAF may be +used. Note that if the \fIproject\fR flag is "yes" then the input images +are the elements of the highest dimension; for example the planes of a +three dimensional image. + +The overlap of the images is determined by a set of integer pixel offsets +with an offset for each dimension of each input image. For example +offsets of 0, 10, and 20 in the first dimension of three images will +result in combining the three images with only the first image in the +first 10 columns, the first two images in the next 10 columns and +all three images starting in the 21st column. At the 21st output column +the 21st column of the first image will be combined with the 11th column +of the second image and the 1st column of the third image. + +The output image size is set by the maximum extent in each dimension +of any input image after applying the offsets. In the above example if +all the images have 100 columns then the output image will have 120 +columns corresponding to the 20 column offset in the third image. +Note that this same output image size is computed and used as the +basis for the \fIoutlimits\fR parameter to specify a subregion to +actually be output. + +The input image offsets are set using the \fIoffset\fR parameter. There +are four ways to specify the offsets. If the word "none" or the empty +string "" are used then all offsets will be zero and all pixels with the +same coordinates will be combined. The output image size will be equal to +the biggest dimensions of the input images. + +If "wcs" offsets are specified then the world coordinate systems (wcs) +in the image headers are used to derived the offsets. The world coordinate +at the center of the first input image is evaluated. Then integer pixel +offsets are determined for each image to bring the same world coordinate +to the same point. Note the following caveats. The world coordinate +systems must be of the same type, orientation, and scale and only the +nearest integer shift is used. + +If the input images have offsets in a regular grid or one wants to make +an output image in which the input images are "mosaiced" together in +a grid then the special offset string beginning with the word "grid" +is used. The format is + +.nf + grid [n1] [s1] [n2] [s2] ... +.fi + +where ni is the number of images in dimension i and si is the step in +dimension i. For example "grid 5 100 5 100" specifies a 5x5 grid with +origins offset by 100 pixels. Note that one must insure that the input +images are specified in the correct order. This may best be accomplished +using a "@" list. One useful application of the grid is to make a +non-overlapping mosaic of a number of images for display purposes. Suppose +there are 16 images which are 100x100. The offset string "grid 4 101 4 +101" will produce a mosaic with a one pixel border having the value set +by \fIblank\fR parameter between the images. + +The offsets may be defined in a file by specifying the file name +in the \fIoffset\fR parameter. (Note that the special file name STDIN +may be used to type in the values terminated by the end-of-file +character). The file consists of a line for each input image. The lines +must be in the same order as the input images and so an "@" list may +be useful. The lines consist of whitespace separated offsets one for +each dimension of the images. In the first example cited above the +offset file might contain: + +.nf + 0 0 + 10 0 + 20 0 +.fi + +where we assume the second dimension has zero offsets. + +The offsets need not have zero for one of the images. The offsets may +include negative values or refer to some arbitrary common point. +When the offsets are read by the program it will find the minimum +value in each dimension and subtract it from all the other offsets +in that dimension. The above example could also be specified as: + +.nf + 225 15 + 235 15 + 245 15 +.fi + +There may be cases where one doesn't want the minimum offsets reset +to zero. If all the offsets are positive and the comment "# Absolute" +appears in the offset file then the images will be combined with +blank values between the first output pixel and the first overlapping +input pixel. Continuing with the above example, the file + +.nf + # Absolute + 10 10 + 20 10 + 30 10 +.fi + +will have the first pixel of the first image in the 11th pixel of the +output image. Note that there is no way to "pad" the other side of +the output image. + +OUTPUT OF SUBREGIONS + +The output image size is computed from all of the input images including +the offsets as described previously. The \fIoutlimits\fR may be used to +specify a subregion of this full size to be created. The syntax of this +parameter is pairs of whitespace separated numbers selecting the first and last +pixel in each output dimension. The pairs for each dimension are also +whitespace separated and are given in order of the dimensions. Any missing +values at the end of the string default to the full limits of the output +image. If the requested limits fall outside the full output image they are +reset to the size of the full computed output size. + +As an example, consider combining 10 images of size 1000x1000 with offsets +of 0, 1, ..., 9 along the first dimension. Because of the offsets the full +output size is 1010x1000. To output only the region [1:100,101:200] +of this full size the parameter value would be the string "1 100 101 200". +Note that if the value was just "1 100" then the output region would +be [1:100,1:1000]. + +The intended purpose for this option is to allow creating subregions using +a smaller number of images in the case of offset data taken at a raster of +positions. This is important since when the number of images becomes too +large (>4000) the program either has to prestack the images into a higher +dimensional single image (requiring equal sized images) or utilize an +inefficient algorithm where images are opened and closed for each input +line. A detail of how this task works is that it is the number of images +required to be accessed for each output line that is significant. + +The following example was developed when the maximum number of images +open at one time was ~240. In V2.12 the number was increased to +more than 4000 so it is not as relevant though it may apply to very +large surveys with many small images. + +As an example, consider a survey of a region of the sky composed of 8000 +images which are each 500x1000. The offsets between each image are 50 +pixels along the first dimension and 900 pixels along the second dimension, +give or take a few pixels due to telescope pointing errors. Thus this +survey consists of strips of exposures. Within a strip the images over by +about 450 pixels. Between strips the overlap is 100 pixels. So the +strips consist 400 exposures and there are 20 strips. + +The full size of this survey is then about 20450x18900. At any point in a +single strip the number of images contributing is no more than 10. +Including the overlap of the strips the maximum number is then 20. In +order to combine the data for such a survey one would like to create +subregion outputs which are 120 images from each strip. The lines where +the two strips overlap then require 240 images. To produce roughly equal +size regions we choose sizes along the first dimension of 5200 pixels. The +number of lines in the output subregions might be the full size of the +survey. However, it might be desirable to also break the second dimension +into blocks for ease of display and manipulation. + +The method for combining this example survey is then to combine the data in +four groups along the first dimension to produce subimages each 5200 pixels +wide which have no overlap. The reason for wanting to create +non-overlapping subregions is to simplify creation of the related masks, +most importantly, the exposure masks. The \fIoutlimits\fR parameter would +have the values "1 5200", "5201 10400", "10401 15600", and "15601 20800". +The second pair of limits is not specified to obtain the full size along +the second dimension. Note that the last block will actually be smaller +than 5200 pixels since the survey is less than 20800 pixels. + +In each combining step all the images must be specified for the input in +order to compute the full output size but then only those images needed to +produce an output line will be accessed at the same time. By design this +is roughly 240 images for lines where the strips overlap. The +non-overlapping blocks can be mosaiced together with this task as a final +step if desired. + + +SCALES AND WEIGHTS + +In order to combine images with rejection of pixels based on deviations +from some average or median they must be scaled to a common level. There +are two types of scaling available, a multiplicative intensity scale and an +additive zero point shift. The intensity scaling is defined by the +\fIscale\fR parameter and the zero point shift by the \fIzero\fR +parameter. These parameters may take the values "none" for no scaling, +"mode", "median", or "mean" to scale by statistics of the image pixels, +"exposure" (for intensity scaling only) to scale by the exposure time +keyword in the image header, any other image header keyword specified by +the keyword name prefixed by the character '!', and the name of a file +containing the scale factors for the input image prefixed by the +character '@'. + +Examples of the possible parameter values are shown below where +"myval" is the name of an image header keyword and "scales.dat" is +a text file containing a list of scale factors. + +.nf + scale = none No scaling + zero = mean Intensity offset by the mean + scale = exposure Scale by the exposure time + zero = !myval Intensity offset by an image keyword + scale = @scales.dat Scales specified in a file +.fi + +The image statistics are computed by sampling a uniform grid of points with +the smallest grid step that yields less than 100000 pixels; sampling is used +to reduce the time needed to compute the statistics. If one wants to +restrict the sampling to a region of the image the \fIstatsec\fR parameter +is used. This parameter has the following syntax: + +.nf + [input|output|overlap] [image section] +.fi + +The initial modifier defaults to "input" if absent. The modifiers are useful +if the input images have offsets. In that case "input" specifies +that the image section refers to each input image, "output" specifies +that the image section refers to the output image coordinates, and +"overlap" specifies the mutually overlapping region of the input images. +In the latter case an image section is ignored. + +The statistics are as indicated by their names. In particular, the +mode is a true mode using a bin size which is a fraction of the +range of the pixels and is not based on a relationship between the +mode, median, and mean. Also masked pixels are excluded from the +computations as well as during the rejection and combining operations. + +The "exposure" option in the intensity scaling uses the value of the +image header keyword specified by the \fIexpname\fR keyword. As implied +by the parameter name, this is typically the image exposure time since +intensity levels are linear with the exposure time in CCD detectors. +Note that the exposure keyword is also updated in the final image +as the weighted average of the input values. Thus, if one wants to +use a nonexposure time keyword and keep the exposure time updating +feature the image header keyword syntax is available; i.e. !<keyword>. + +Scaling values may be defined as a list of values in a text file. The file +name is specified by the standard @file syntax. The list consists of one +value per line. The order of the list is assumed to be the same as the +order of the input images. It is a fatal error if the list is incomplete +and a warning if the list appears longer than the number of input images. +Because the scale and zero levels are adjusted only the relative +values are important. + +If both an intensity scaling and zero point shift are selected the +zero point is added first and the scaling is done. This is +important if the scale and offset values are specified by +header keywords or from a file of values. However, +in the log output the zero values are given as the scale times +the offset hence those numbers would be interpreted as scaling +first and zero offset second. + +The image statistics and scale factors are recorded in the log file +unless they are all equal, which is equivalent to no scaling. The +scale factors are normalized so that the first input image has no +scaling. This is done because the header of the first input image +is used as the template header for the combined output image. +By scaling to this first image this means that flux related keywords, +such as exposure time and airmass, are representative of the output +(except when the "sum" option is used). + +Scaling affects not only the mean values between images but also the +relative pixel uncertainties. For example scaling an image by a +factor of 0.5 will reduce the effective noise sigma of the image +at each pixel by the square root of 0.5. Changes in the zero +point also changes the noise sigma if the image noise characteristics +are Poissonian. In the various rejection algorithms based on +identifying a noise sigma and clipping large deviations relative to +the scaled median or mean, one may need to account for the scaling induced +changes in the image noise characteristics. + +In those algorithms it is possible to eliminate the "sigma correction" +while still using scaling. The reasons this might be desirable are 1) if +the scalings are similar the corrections in computing the mean or median +are important but the sigma corrections may not be important and 2) the +image statistics may not be Poissonian, either inherently or because the +images have been processed in some way that changes the statistics. In the +first case because computing square roots and making corrections to every +pixel during the iterative rejection operation may be a significant +computational speed limit the parameter \fIsigscale\fR selects how +dissimilar the scalings must be to require the sigma corrections. This +parameter is a fractional deviation which, since the scale factors are +normalized to unity, is the actual minimum deviation in the scale factors. +For the zero point shifts the shifts are normalized by the mean shift +before adjusting the shifts to a zero mean. To always use sigma scaling +corrections the parameter is set to zero and to eliminate the correction in +all cases it is set to a very large number. + +If the final combining operation is "average" then the images may be +weighted during the averaging. The weights are specified in the same way +as the scale factors. In addition the NCOMBINE keyword, if present, will +be used in the weights. The weights, scaled to a unit sum, are printed in +the log output. + +The weights are used for the final weighted average, sigma image, and +exposure mask output. They are not used to form averages in the various +rejection algorithms. For weights in the case of no scaling or only +multiplicative scaling the weights are used as given or determined so that +images with lower signal levels will have lower weights. However, for +cases in which zero level scaling is used and the zero levels are +determined from image statistics (not from an input file or keyword) the +weights are computed from the initial weights (the exposure time, image +statistics, or input values) using the formula: + +.nf + weight_final = weight_initial / (scale * sky) +.fi + +where the sky values are those from the image statistics before conversion +to zero level shifts and adjustment to zero mean over all images. The +reasoning is that if the zero level is high the sky brightness is high and +so the S/N is lower and the weight should be lower. If any sky value +determined from the image statistics comes out to be negative a warning is +given and the none of the weight are adjusted for sky levels. + +The weights are not adjusted when the zero offsets are input from a file +or keyword since these values do not imply the actual image sky value. +In this case if one wants to account for different sky statistics +in the weights the user must specify the weights in a file taking +explicit account of changes in the weights due to different sky +statistics. + +When forming the final weighted averages if the sum of the weights of +the non-rejected or excluded pixels is zero then instead of producing +a zero average the unweighted average of the pixels is produced. Similarly, +in the sigma calculation when the weights of the pixels are all zero +then the sigma is computed as if all pixels have unit weights. + +When there are zero weights only the pixels with non-zero weights are +used in computing the output exposure time mask. Note that the actual +weight values are not used but simply the sum of all exposure times +of pixels from images with non-zero weights is produced. + +The purpose of using zero weights is to identify images that are of +poor quality (such as non-photometric or bad seeing) which are then +excluded in the final weighted average or exposure time. However, +they contribute to the final image when there is no good +quality data but with an output exposure time of zero. + +INPUT PIXEL MASKS + +A pixel mask is a type of IRAF file having the extension ".pl" or +a FITS extension of "type=mask" which +identifies an integer value with each pixel of the images to which it is +applied. In future masks may also be stored as special FITS extensions. +The integer values may denote regions, a weight, a good or bad +flag, or some other type of integer or integer bit flag. In the common +case where many values are the same, this type of file is compact. +It is most compact and efficient if the majority of +the pixels have a zero mask value so frequently zero is the value for good +pixels. Note that these files, while not stored as a strict pixel array, +may be treated as images in programs. This means they may be created by +programs such as \fBmkpattern\fR, edited by \fBimedit\fR, examined by +\fBimexamine\fR, operated upon by \fBimarith\fR, graphed by \fBimplot\fR, +and displayed by \fBdisplay\fR. + +To use pixel masks with \fBimcombine\fR one must associate a pixel +mask file with an image by entering the pixel list file name in the +image header under the keyword BPM (bad pixel mask) or some other +keyword to be specified. This can be +done with \fBhedit\fR. Note that the same pixel mask may be associated +with more than one image as might be the case if the mask represents +defects in the detector used to obtain the images. + +If a pixel mask is associated with an image the mask is used when the +\fImasktype\fR parameter is set to a value other than "none" or "". Note that +when it is set to "none", mask information is not used even if it exists for +the image. The values of \fImasktype\fR which apply masks are "goodvalue", +"badvalue", "novalue", "goodbits", "badbits", and "!<keyword>". The last choice +allows specifying the keyword whose value is the mask to be used otherwise +the keyword "BPM" is used. + +The \fImasktype\fR choices are used in conjunction with the +\fImaskvalue\fR parameter. When the mask type is "goodvalue" or an +explicit keyword is specified without a mask type, the pixels with mask +values matching the specified value are included in combining and all +others are rejected. For a mask type of "badvalue" the pixels with +mask values matching the specified value are rejected and all others +are accepted. The bit types are useful for selecting a combination of +attributes in a mask consisting of bit flags. The mask value is still +an integer but is interpreted by bitwise comparison with the values in +the mask file. + +The "novalue" option differs from the others in that there are three +classes of mask values and any output pixel mask will have the three +values 0 for good, 1 for no data, and 2 for bad. The purpose of this +option is to produce output values from the input values when there are +no good pixels. This happens when the input images have pixel values +which have been identified as bad (such as saturated) but whose values +can be used, possibly after being replaced or interpolated from nearby +pixels, to produce a value that is either cosmetically reasonable or even +marginally scientifically useful. Again, this only happens if there +are no good pixels to combine and then the output mask will identify +these pixels with a mask value of 2. If there is even one good pixel +then only the good data will contribute to the output. An exposure mask +may be useful in this case when most but not all image pixels have been +eliminated due to things like saturation. + +If a mask operation is specified and an image has no mask image associated +with it (the BPM or specified keyword is absent), the mask values are taken +as all zeros. In those cases be careful that zero is an accepted value +otherwise the entire image will be rejected. + +When the number of input images exceeds the maximum number of open files +allowed by IRAF and the input images need to be "stacked" then the masks +are also stacked. The stacking requires all the images to have the same size. + + +THRESHOLD REJECTION + +In addition to rejecting masked pixels, pixels in the unscaled input +images which are below or above the thresholds given by the parameters +\fIlthreshold\fR and \fIhthreshold\fR are rejected. Values of INDEF +mean that no threshold value is applied. Threshold rejection may be used +to exclude very bad pixel values or as an alternative way of masking +images. In the latter case one can use a task like \fBimedit\fR +or \fBimreplace\fR to set parts of the images to be excluded to some +very low or high magic value. + + +REJECTION ALGORITHMS + +The \fIreject\fR parameter selects a type of rejection operation to +be applied to pixels not masked or thresholded. If no rejection +operation is desired the value "none" is specified. + +.in 2 +MINMAX +.in 2 +A specified fraction of the highest and lowest pixels are rejected. +The fraction is specified as the number of high and low pixels, the +\fInhigh\fR and \fInlow\fR parameters, when data from all the input images +are used. If pixels have been rejected by offseting, masking, or +thresholding then a matching fraction of the remaining pixels, truncated +to an integer, are used. Thus, + +.nf + nl = n * nlow/nimages + 0.001 + nh = n * nhigh/nimages + 0.001 +.fi + +where n is the number of pixels surviving offseting, masking, and +thresholding, nimages is the number of input images, nlow and nhigh +are task parameters and nl and nh are the final number of low and +high pixels rejected by the algorithm. The factor of 0.001 is to +adjust for rounding of the ratio. + +As an example with 10 input images and specifying one low and two high +pixels to be rejected the fractions to be rejected are nlow=0.1 and nhigh=0.2 +and the number rejected as a function of n is: + +.nf + n 0 1 2 3 4 5 6 7 8 9 10 + nl 0 0 0 0 0 0 0 0 0 0 1 + nh 0 0 0 0 0 1 1 1 1 1 2 +.fi + +.in -2 +CCDCLIP +.in 2 +If the images are obtained using a CCD with known read out noise, gain, and +sensitivity noise parameters and they have been processed to preserve the +relation between data values and photons or electrons then the noise +characteristics of the images are well defined. In this model the sigma in +data values at a pixel with true value <I>, as approximated by the median +or average with the lowest and highest value excluded, is given by: + +.nf + sigma = ((rn / g) ** 2 + <I> / g + (s * <I>) ** 2) ** 1/2 +.fi + +where rn is the read out noise in electrons, g is the gain in +electrons per data value, s is a sensitivity noise given as a fraction, +and ** is the exponentiation operator. Often the sensitivity noise, +due to uncertainties in the pixel sensitivities (for example from the +flat field), is not known in which case a value of zero can be used. +See the task \fBstsdas.wfpc.noisemodel\fR for a way to determine +these values (though that task expresses the read out noise in data +numbers and the sensitivity noise parameter as a percentage). + +The read out noise is specified by the \fIrdnoise\fR parameter. The value +may be a numeric value to be applied to all the input images or a image +header keyword containing the value for each image. Similarly, the +parameter \fIgain\fR specifies the gain as either a value or image header +keyword and the parameter \fIsnoise\fR specifies the sensitivity +noise parameter as either a value or image header keyword. + +The algorithm operates on each output pixel independently. It starts by +taking the median or unweighted average (excluding the minimum and maximum) +of the unrejected pixels provided there are at least two input pixels. The +expected sigma is computed from the CCD noise parameters and pixels more +that \fIlsigma\fR times this sigma below or \fIhsigma\fR times this sigma +above the median or average are rejected. The process is then iterated +until no further pixels are rejected. If the average is used as the +estimator of the true value then after the first round of rejections the +highest and lowest values are no longer excluded. Note that it is possible +to reject all pixels if the average is used and is sufficiently skewed by +bad pixels such as cosmic rays. + +If there are different CCD noise parameters for the input images +(as might occur using the image header keyword specification) then +the sigmas are computed for each pixel from each image using the +same estimated true value. + +If the images are scaled and shifted and the \fIsigscale\fR threshold +is exceedd then a sigma is computed for each pixel based on the +image scale parameters; i.e. the median or average is scaled to that of the +original image before computing the sigma and residuals. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +This is the best clipping algorithm to use if the CCD noise parameters are +adequately known. The parameters affecting this algorithm are \fIreject\fR +to select this algorithm, \fImclip\fR to select the median or average for +the center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, the CCD noise parameters \fIrdnoise, gain\fR and \fIsnoise\fR, +\fIlsigma\fR and \fIhsigma\fR to select the clipping thresholds, +and \fIsigscale\fR to set the threshold for making corrections to the sigma +calculation for different image scale factors. + +.in -2 +CRREJECT +.in 2 +This algorithm is identical to "ccdclip" except that only pixels above +the average are rejected based on the \fIhsigma\fR parameter. This +is appropriate for rejecting cosmic ray events and works even with +two images. + +.in -2 +SIGCLIP +.in 2 +The sigma clipping algorithm computes at each output pixel the median or +average excluding the high and low values. The sigma is then computed +about this estimate (without excluding the low and high values). There +must be at least three input pixels, though for this method to work well +there should be at least 10 pixels. Values deviating by more than the +specified sigma threshold factors are rejected. These steps are repeated, +except that after the first time the average includes all values, until no +further pixels are rejected or there are fewer than three pixels. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +The parameters affecting this algorithm are \fIreject\fR to select +this algorithm, \fImclip\fR to select the median or average for the +center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, \fIlsigma\fR and \fIhsigma\fR to select the +clipping thresholds, and \fIsigscale\fR to set the threshold for +making corrections to the sigma calculation for different image scale +factors. + +.in -2 +AVSIGCLIP +.in 2 +The averaged sigma clipping algorithm assumes that the sigma about the +median or mean (average excluding the low and high values) is proportional +to the square root of the median or mean at each point. This is +described by the equation: + +.nf + sigma(column,line) = sqrt (gain(line) * signal(column,line)) +.fi + +where the \fIestimated\fR signal is the mean or median (hopefully excluding +any bad pixels) and the gain is the \fIestimated\fR proportionality +constant having units of photons/data number. + +This noise model is valid for images whose values are proportional to the +number of photons recorded. In effect this algorithm estimates a +detector gain for each line with no read out noise component when +information about the detector noise parameters are not known or +available. The gain proportionality factor is computed +independently for each output line by averaging the square of the residuals +(at points having three or more input values) scaled by the median or +mean. In theory the proportionality should be the same for all rows but +because of the estimating process will vary somewhat. + +Once the proportionality factor is determined, deviant pixels exceeding the +specified thresholds are rejected at each point by estimating the sigma +from the median or mean. If any values are rejected the median or mean +(this time not excluding the extreme values) is recomputed and further +values rejected. This is repeated until there are no further pixels +rejected or the number of remaining input values falls below three. Note +that the proportionality factor is not recomputed after rejections. + +If the images are scaled differently and the sigma scaling correction +threshold is exceedd then a correction is made in the sigma +calculations for these differences, again under the assumption that +the noise in an image scales as the square root of the mean intensity. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +This algorithm works well for even a few input images. It works better if +the median is used though this is slower than using the average. Note that +if the images have a known read out noise and gain (the proportionality +factor above) then the "ccdclip" algorithm is superior. The two algorithms +are related in that the average sigma proportionality factor is an estimate +of the gain. + +The parameters affecting this algorithm are \fIreject\fR to select +this algorithm, \fImclip\fR to select the median or average for the +center of the clipping, \fInkeep\fR to limit the number of pixels +rejected, \fIlsigma\fR and \fIhsigma\fR to select the +clipping thresholds, and \fIsigscale\fR to set the threshold for +making corrections to the sigma calculation for different image scale +factors. + +.in -2 +PCLIP +.in 2 +The percentile clipping algorithm is similar to sigma clipping using the +median as the center of the distribution except that, instead of computing +the sigma of the pixels from the CCD noise parameters or from the data +values, the width of the distribution is characterized by the difference +between the median value and a specified "percentile" pixel value. This +width is then multiplied by the scale factors \fIlsigma\fR and \fIhsigma\fR +to define the clipping thresholds above and below the median. The clipping +is not iterated. + +The pixel values at each output point are ordered in magnitude and the +median is determined. In the case of an even number of pixels the average +of the two middle values is used as the median value and the lower or upper +of the two is the median pixel when counting from the median pixel to +selecting the percentile pixel. The parameter \fIpclip\fR selects the +percentile pixel as the number (if the absolute value is greater +than unity) or fraction of the pixels from the median in the ordered set. +The direction of the percentile pixel from the median is set by the sign of +the \fIpclip\fR parameter with a negative value signifying pixels with +values less than the median. Fractional values are internally converted to +the appropriate number of pixels for the number of input images. A minimum +of one pixel and a maximum corresponding to the extreme pixels from the +median are enforced. The value used is reported in the log output. Note +that the same percentile pixel is used even if pixels have been rejected by +offseting, masking, or thresholding; for example, if the 3nd pixel below +the median is specified then the 3rd pixel will be used whether there are +10 pixels or 5 pixels remaining after the preliminary steps. + +After rejection the number of retained pixels is checked against the +\fInkeep\fR parameter. If there are fewer pixels retained than specified +by this parameter the pixels with the smallest residuals in absolute +value are added back. If there is more than one pixel with the same +absolute residual (for example the two pixels about an average +or median of two will have the same residuals) they are all added +back even if this means more than \fInkeep\fR pixels are retained. +Note that the \fInkeep\fR parameter only applies to the pixels used +by the clipping rejection algorithm and does not apply to threshold +or bad pixel mask rejection. + +Some examples help clarify the definition of the percentile pixel. In the +examples assume 10 pixels. The median is then the average of the +5th and 6th pixels. A \fIpclip\fR value of 2 selects the 2nd pixel +above the median (6th) pixel which is the 8th pixel. A \fIpclip\fR +value of -0.5 selects the point halfway between the median and the +lowest pixel. In this case there are 4 pixels below the median, +half of that is 2 pixels which makes the percentile pixel the 3rd pixel. + +The percentile clipping algorithm is most useful for clipping small +excursions, such as the wings of bright objects when combining +disregistered observations for a sky flat field, that are missed when using +the pixel values to compute a sigma. It is not as powerful, however, as +using the CCD noise parameters (provided they are accurately known) to clip +about the median. + +The parameters affecting this algorithm are \fIreject\fR to select this +algorithm, \fIpclip\fR to select the percentile pixel, \fInkeep\fR to limit +the number of pixels rejected, and \fIlsigma\fR and \fIhsigma\fR to select +the clipping thresholds. +.in -4 + +GROW REJECTION + +Neighbors of pixels rejected by the rejection algorithms +may also be rejected. The number of neighbors to be rejected +is specified by the \fIgrow\fR parameter which is a radius in pixels. +If too many pixels are rejected in one of the grown pixels positions +(as defined by the \fInkeep\fR parameter) then the value of that pixel +without growing will be used. + +COMBINING + +After all the steps of offsetting the input images, masking pixels, +threshold rejection, scaling, and applying a rejection algorithms the +remaining pixels are combined and output as specified by the \fIcombine\fR +parameter. In all cases if there are no remaining pixels the \fIblank\fR +is produced. The combining choices are as follows. + +.in 2 +AVERAGE +.in 2 +The weighted average of the remaining pixels is computed. If no +weighting was specified then a simple, unweighted average is used. +If the sum of the weights of for the accepted pixels is zero then the +unweighted average is output. + +.in -2 +MEDIAN +.in 2 +The median of the remaining pixels is computed. The median is the +usual mathematical definition where a particular pixel value is produced +for an odd number of pixels and the average of the two central values +is computed for an even number of pixels. + +.in -2 +SUM +.in 2 +The sum of the unrejected pixels is computed. + +.in -2 +LMEDIAN +.in 2 +The median of the remaining pixels is computed except that for two +pixels the lower value is used. This is a specialized feature useful +for minimizing the effects of cosmic rays in dithered and/or masked data. + +.in -2 +QUADRATURE +.in 2 +The pixels are combined as + +.nf + sqrt (sum {(wt * sigma)^2}) / sum {wt} +.fi + +This is used when the input pixel values represent "sigmas". This option +is usually a second pass after the input data has been combined. It is +important that the input is arranged such that the same scaling and +pixel rejections are used. This means that these cannot be given by +explicit lists and masks and not generated from the data. + +.in -2 +QUADRATURE +.in 2 +The pixels are combined as + +.nf + value = max (0, scaled_pixel_value) + variance = rdnoise^2 + value / gain + (snoise * value)^2 + output = sqrt (sum {variance * wt^2}) / sum {wt} +.fi + +This is used when the variances in the input images can be computed +by the above noise model. Note that the gain and rdnoise are adjusted +for any scaling applied to the pixel values. + +This method has the advantage that the input images are the same as +those used to form a combined image and so all the steps of deriving +scaling and rejecting pixels by some rejection method will be the same. +.in -4 + +SIGMA OUTPUT + +In addition to the combined image and optional sigma image may be +produced. The sigma computed is the standard deviation, corrected for a +finite population by a factor of n/(n-1), of the unrejected input pixel +values about the output combined pixel values. +.ih +EXAMPLES +1. To average and median images without any other features: + +.nf + cl> imcombine obj* avg combine=average reject=none + cl> imcombine obj* med combine=median reject=none +.fi + +2. To reject cosmic rays: + +.nf + cl> imcombine obs1,obs2 Obs reject=crreject rdnoise=5.1, gain=4.3 +.fi + +3. To make a grid for display purposes with 21 64x64 images: + +.nf + cl> imcombine @list grid offset="grid 5 65 5 65" +.fi + +4. To apply a mask image with good pixels marked with a zero value and +bad pixels marked with a value of one: + +.nf + cl> hedit ims* bpm badpix.pl add+ ver- + cl> imcombine ims* final combine=median masktype=goodval +.fi + +5. To scale image by the exposure time and then adjust for varying +sky brightness and make a weighted average: + +.nf + cl> imcombine obj* avsig combine=average reject=avsig \ + >>> scale=exp zero=mode weight=exp expname=exptime +.fi +.ih +REVISIONS +.ls IMCOMBINE V2.12 +A number of enhancements for dealing with large numbers of images were +made. Also the masktype option "!<keyword>", where <keyword> is a +user specified keyword, was added. + +The new parameters "headers", "bpmasks", "rejmasks", "nrejmasks", and +"expmasks" provide additional types of output. The old parameters +"rejmask" and "plfile" were removed. The new "nrejmasks" corresponds +to the old "plfile" and the new "rejmasks" corresponds to the old +"rejmask". + +There is a new "combine" type "sum" for summing instead of averaging the +final set of offset, scaled, and weighted pixels. + +there is a new parameter "outlimits" to allow output of a subregion of +the full output. This is useful for raster surveys with large numbers +of images. + +Additional keywords may appear in the output headers. + +The scaling is now done relative to the first image rather than an +average over the images. This is done so that flux related keywords +such as exposure time and airmass remain representative. +.le +.ls IMCOMBINE V2.11.2 +The grow algorithm was improved to give a 2D growing radius. + +An optional output mask file contains the identifications of which pixel +in which input image was rejected or excluded. + +The internal calculation type was changed to be the highest precedence +of the input and output types. Previously it was only the input types. +.le +.ls IMCOMBINE V2.11 +The limit of the number of images that may be combined has been removed. +If the number of images exceeds the maximum number of open images permitted +then the images are stacked in a single temporary image and then combined +with the project option. Note that this will double the amount of +diskspace temporarily. There is also a limitation in this case that the +bad pixel mask from the first image in the list will be applied to all the +images. + +Integer offsets may be determined from the image world coordinate system. + +A combination of ushort and short images now defaults to integer. +.le +.ls IMCOMBINE V2.14 +The "masktype" parameter has been generalized to allow both using a +different keyword for the input mask and choosing the mask method. +The "novalue" masktype is new and is useful for maintaining a distinction +between no data and possibly marginally useful or cosmetically useful +data. +.le +.ls IMCOMBINE V2.10.3 +The input scalings from an @file or header keyword are now truly +mulitplicative or additive and they are not normalized. The output +pixel types now include unsigned short integer. +.le +.ls IMCOMBINE V2.10.2 +The weighting was changed from using the square root of the exposure time +or image statistics to using the values directly. This corresponds +to variance weighting. Other options for specifying the scaling and +weighting factors were added; namely from a file or from a different +image header keyword. The \fInkeep\fR parameter was added to allow +controlling the maximum number of pixels to be rejected by the clipping +algorithms. The \fIsnoise\fR parameter was added to include a sensitivity +or scale noise component to the noise model. Errors will now delete +the output images. +.le +.ls IMCOMBINE V2.10 +This task was greatly revised to provide many new features. These features +are: + +.nf + o Bad pixel masks + o Combining offset and different size images + o Blank value for missing data + o Combining across the highest dimension (the project option) + o Separating threshold rejection, the rejection algorithms, + and the final combining statistic + o New CCDCLIP, CRREJECT, and PCLIP algorithms + o Rejection now may reject more than one pixel per output pixel + o Choice of a central median or average for clipping + o Choice of final combining operation + o Simultaneous multiplicative and zero point scaling +.fi +.le +.ih +LIMITATIONS +Though the previous limit on the number of images that can be combined +was removed in V2.11 the method has the limitation that only a single +bad pixel mask will be used for all images. +.ih +SEE ALSO +ccdred.combine mscred.combine onedspec.scombine, wpfc.noisemodel, +obsolete.ocombine +.endhelp diff --git a/pkg/images/immatch/doc/linmatch.hlp b/pkg/images/immatch/doc/linmatch.hlp new file mode 100644 index 00000000..21c04b22 --- /dev/null +++ b/pkg/images/immatch/doc/linmatch.hlp @@ -0,0 +1,699 @@ +.help linmatch Apr95 images.immatch +.ih +NAME +linmatch -- linearly match the intensity scales of 1 and 2D images +.ih +USAGE +linmatch input reference regions lintransform +.ih +PARAMETERS +.ls input +The list of input images to be matched. +.le +.ls reference +The list of reference images to which the input images are to be matched +if \fIscaling\fR is one of the "mean", "median", "mode", or "fit" +algorithms, or the list of reference photometry files if \fIscaling\fR +specifies the "photometry" algorithm. The number of reference images or +reference photometry files must be one or equal to the number of input +images. +.le +.ls regions +The list of image regions used to compute the intensity +matching function if \fIscaling\fR is one of the "mean", "median", "mode", +or "fit" algorithms, or a list of the input photometry files if +\fIscaling\fR specifies the "photometry" algorithm. In the former +case \fIregions\fR may be: 1) a string of the form "grid nx ny" defining +a grid of nx by ny equally spaced and sized image regions spanning the +entire image, 2) a list of object coordinates separated by commas e.g. +"303 401, 131 202", 3) a list of image sections separated by whitespace +e.g "[101:200,101:200] [301:400,301:400]", +4) the name of a text file containing a list of object coordinates separated +by newlines, and 5) the name of a text file containing a list of image +sections separated by whitespace and/or newlines. +.le +.ls lintransform +The name of the text file where the computed scaling factors are written. +If \fIdatabasefmt\fR is "yes", a single record containing the computed +bscale and bzero factors for each image region or object, and the +average bscale and bzero, is written to the text database +file for each input image. If \fIdatabasefmt\fR = "no", a single line +containing the input image name, bscale factor, bzero factor, error +in bscale, and error in bzero is written to a simple text file for +each image. +.le +.ls output = "" +The list of output matched images. If \fIoutput\fR is the NULL string +then bscale and bzero are computed for each input image and written to +\fIlintransform\fR, but no output images are written. If \fIoutput\fR +is not NULL then the number of output images must equal the number of +input images. +.le +.ls databasefmt = yes +If \fIdatabasefmt\fR is "yes" the computed bscale and bzero factors +are written to a text database file, otherwise they are written to a +simple text file. +.le +.ls records = "" +The list of records to be written to or read from \fIlintransform\fR one +input image. If \fIrecords\fR is NULL then the output or input record names +are assumed to be the names of the input images. If \fIrecords\fR is not NULL +then the record names in \fIrecords\fR are used to write / read the +database records. This parameter is useful for users +who, wish to compute the bscale and bzero factors using images that have +been processed +in some manner (e.g. smoothed), but apply the computed bscale and bzero +factors to the original unprocessed images. If more than one record +with the same name exists in \fIlintransform\fR then the most recently written +record takes precedence. The records parameter is ignored if +\fIdatabasefmt\fR is "no". +.le +.ls append = yes +Append new records to an existing \fIlintransform\fR file or start a new +file for each execution of LINMATCH? The append parameter is +ignored if \fIdatabasefmt\fR is "no". +.le +.ls shifts = "" +An optional list of shifts files containing the x and y shifts to be applied +to the reference regions to determine their positions in +the input images. The number of shifts files must equal the number of +reference images. The shifts are listed in the shifts file, 1 shift per line, +with the x and y shifts in +columns 1 and 2 respectively. If there are fewer x and y shifts defined +in the shifts file than there are input images, the extra input +images will be assigned x and y shifts of \fIxshift\fR and \fIyshift\fR +respectively. The shifts parameter is ignored if the \fIscaling\fR +parameter is set to "photometry". +.le +.ls xshift = 0.0 yshift = 0.0 +The default x and y shifts to be applied to the reference image regions +or objects to compute their positions in the input image. +Values in \fIshifts\fR take precedence over the values of \fIxshift\fR and +\fIyshift\fR. xshift and yshift are ignored if the \fIscaling\fR parameter +is set to "photometry". +.le +.ls dnx = 31 dny = 31 +The default size of a single image region used to compute the bscale +and bzero factors if \fIscaling\fR is one of the "mean", "median", "mode", +or "fit" algorithms and \fIregions\fR is a coordinate list rather than +a sections list. dnx and dny are ignored if the \fIscaling\fR parameter +is set to "photometry". +.le +.ls maxnregions = 100 +The maximum number of image regions or objects with measured photometry +that can be used to compute the bscale and bzero factors. +.le +.ls scaling = "mean mean" +The algorithms used to compute the bscale and bzero factors respectively. +The options are: +.ls mean median mode +Bscale or bzero are computed using the "mean", "median", or "mode" statistic +for each input and reference region individually. If one of the bscale or +bzero fitting +algorithms is set to "mean", "median", or "mode", the remaining factor +must be set to "mean", "median" or "mode" or a numerical constant, +e.g. "mean mean", "mean -100.0" or "2.63 mode". +If both algorithms are set to "mean", "median", or "mode" bscale will be +computed using the specified statistic and bzero will be set to 0.0 +If more than one input region is defined then a weighted least squares +fit of the reference statistics to the input image statistics +is performed and used to compute the final bscale and bzero factors. +.le +.ls fit +Bscale and bzero are computed for each input image region individually +by performing a least squares fit of the reference image pixels to +the input image pixels. If more than one input image region is defined +the final bscale and bzero factors are computed by averaging, +weighted by their signal-to-noise ratios, the individual bscale and bzero +values. If one of the bscale or bzero fitting +algorithms is set to "fit", the remaining factor must either also +be computed with the "fit" algorithm or set to a numerical constant, +e.g. "fit fit", "fit -100.0", or "2.63 fit". +.le +.ls photometry +Bscale and/or bzero are computed for each input object individually +using photometry computed for a set of objects common to the reference +and input images. If more than one input object is defined +the final bscale and bzero factors are computed by averaging, +weighted by their signal-to-noise ratios, the individual bscale and bzero +values. If one of the bscale or bzero fitting +algorithms is set to "photometry", the remaining factor must either also +be computed with the "photometry" algorithm or set to a numerical +constant, e.g. "photometry photometry", "photometry -100.0", or +"2.63 photometry". +.le +.ls number +Bscale and/or bzero are set to user defined numerical constants, +e.g. "2.62 -55.0" or "2.62 median". If both bscale and bzero are numerical +constants, LINMATCH must be run in non-interactive mode. If only one of bscale +or bzero is a numerical constant, any of the "mean", "median", "mode", "fit", +or "photometry" algorithms may be used to compute the remaining factor. +.le +.ls file +Bscale and bzero are not computed but instead read from record \fIrecord\fR in +the text database file \fIlintransform\fR if \fIdatabasefmt\fR is "yes", +or the next line of a simple text file if \fIdatabasefmt\fR is "no". +.le + +Further description of the matching algorithms can be found in the ALGORITHMS +section. +.le +.ls datamin = INDEF datamax = INDEF +The minimum and maximum good data values. Datamin and datamax are used by +the "mean", "median", and "mode" scaling algorithms to reject entire +image regions from the final fit, and by the "fit" algorithm to reject +individual bad pixels from the least squares fits for the individual +regions. +.le +.ls maxiter = 10 +The maximum number of iterations performed by the least squares fitting +algorithm. +.le +.ls nreject = 0 +The maximum number of rejection cycles used to detect and reject bad pixels +from the fit if the scaling algorithm is "fit" or bad regions / objects +from the fit if the scaling algorithm is "mean", "median", "mode", "fit", +or "photometry". +.le +.ls loreject = INDEF hireject = INDEF +The high- and low-side bad data rejection limits used to detect and reject +deviant pixels from the fit if the scaling algorithm is "fit" or bad +regions / objects from the fit if the scaling algorithm is "mean", "median", +"mode", "fit", or "photometry". +.le +.ls gain = "1.0 1.0" readnoise = "0.0 0.0" +The reference and input image gain and readout noise in e-/ADU and +e- respectively. Gain and readout may be numerical constants or the +image header keyword containing the actual gain and/or readout noise +value. Gain and readnoise are used by the "mean", "median", "mode", +and "fit" algorithms to estimate the expected errors in the computed +"mean", "median", or "mode" statistics, and by the "fit" algorithm +to compute the per pixel errors values. +.le +.ls interactive = no +Compute the bscale and bzero scaling factors for each image interactively +using graphics cursor and optionally image cursor input. +.le +.ls verbose = yes +Print messages about the progress of the task during task execution in +non-interactive mode. +.le +.ls graphics = "stdgraph" +The default graphics device. +.le +.ls display = "stdimage" +The default image display device. +.le +.ls gcommands = "" +The default graphics cursor. +.le +.ls icommands = "" +The default image cursor. +.le + +.ih +DESCRIPTION + +LINMATCH computes the bscale and bzero factors required to match +the intensity scales of a list of input +images \fIinput\fR to the intensity scales of a list of reference +images \fIreference\fR using the following definition of +bscale and bzero and a variety of techniques. + +.nf + reference = bscale * input + bzero +.fi + +The computed bscale and bzero factors are stored +in the text file \fIlintransform\fR, in the record \fIrecords\fR if +\fIdatabasefmt\fR is "yes", or a single line of a simple text file +if \fIdatabasefmt\fR is "no". One record is written to the output file +file for each input image. If a non NULL list of output images +\fIoutput\fR is supplied, a scaled output image is written for +each input image. LINMATCH is intended to solve 1D and 2D image intensity +matching problems where the input and reference images: 1) have the same +pixel scale and orientation, 2) differ in intensity by at most a scale +factor and a zero point, and 3) contain one or more regions or objects in +common that can be used to compute the scaling factors. Some of the scaling +algorithms also require that the images registered and have identical +point spread functions. LINMATCH cannot be used to compute or apply non-linear +intensity matching functions. + +If \fIscaling\fR = "mean", "median", "mode", or "fit" bscale and bzero +are computed directly from the input and reference image data using the +image sections specified in the \fIregions\fR and one of the above fitting +techniques as described in the ALGORITHMS section. All four algorithms +require accurate knowledge of the measurement errors which in turn +require accurate knowledge of the input and reference image gain and +readout noise values. Gain and readout noise values can be entered by +setting the \fIgain\fR and \fIreadnouse\fR parameters to the appropriate +numerical values or image header keyword. + +\fIRegions\fR is interpreted as either: 1) a string of +the form "grid nx ny" specifying a list of nx by ny image sections +spanning the entire image, 2) a string defining the coordinates of a list +of objects separated by commas e.g. +"103.3 189.2, 204.4 389.7", 3) a string containing a list of image +sections separated by whitespace, e.g "[100:203,200:300] [400:500,400:500]" +4) the name of a text file containing the coordinates of one or +more objects, one object per line, with the x and y coordinates +in columns 1 and 2 respectively, 5) the name of a text +file containing a list of image sections separated by whitespace and/or +newlines. The image sections specifications, or alternatively +the object coordinates and the parameters \fIdnx\fR and \fIdny\fR, +determine the size of the input and reference image data regions to be +extracted and used to compute the bscale and bzero factors. +These image regions should be selected with care. Ideal regions +span a range of intensity values and contain both object and background +data. + +If \fIscaling\fR = "photometry", the bscale and bzero factors +are computed directly from data in the input and reference image photometry +files using the technique described in the ALGORITHMS section. +In this case \fIregions\fR is a list of the input image photometry +files and \fIreference\fR are the corresponding reference image +photometry files written by a separate photometry task. +These photometry files are simple text files with the object +sky values, errors in the sky values, magnitudes, and errors in the +magnitudes in columns 1, 2, 3, and 4 respectively. + +An image region is rejected from the fit if it contains data outside the +limits specified by the \fIdatamin\fR and \fIdatamax\fR parameters +and \fIscaling\fR = +"mean", "median", or "mode". A pixel is rejected from the fit for an +individual region if the pixel value is outside the limits specified +by datamin and datamax, and the scaling algorithm is "fit". The datamin +and datamax parameters are not used by the "photometry" scaling algorithm . + +Deviant pixels can be rejected from the fits to individual image regions +if \fIscaling\fR = "fit", and \fInreject\fR, \fIloreject\fR, and +\fIhireject\fR are set appropriately. Nreject, loreject and reject +are also be used by all the scaling algorithms to reject image regions +which contribute deviant bscale and bzero values. + +The computed bscale and bzero value for each region and the final bscale +and bzero value for each input image are written to the linear +transformation file \fIlintransform\fR. +If \fIdatabasefmt\fR is "yes" each result is written to a record whose name +is either identical to the name of the input +image or supplied by the user via the \fIrecords\fR parameter . +If \fIdatabasefmt\fR is "no", then a single line containing the input image +name and the computed bscale and bzero values and their errors +is written to the output shifts file. + +If a list of output image names have been supplied then the bscale and +bzero values will be applied to the input images to compute the output images. + +If the \fIscaling\fR parameter is set to "file" then the shifts +computed in a previous run of LINMATCH will be read from the \fIlintransform\fR +file and applied to the input images to compute the output images. +If no record list is supplied by the user LINMATCH will +search for a record whose name is the same as the input image name. If more than +one record of the same name is found then the most recently written +record will be used. + +In non-interactive mode the task parameters are set at task startup time +and the input images are processed sequentially. If the \fIverbose\fR +flag is set, messages about the progress of the task are printed on the +screen as the task is running. + +In interactive mode the user can mark the regions to be used +to compute the matching function on the image display, show/set the data +and algorithm parameters, compute, recompute, and plot +matching function, and interactively delete and undelete +bad data from the fits using the plots and graphics cursor. A summary +of the available interactive commands is given in the CURSOR COMMANDS +section. + +.ih +CURSOR COMMANDS + +.nf +The following graphics cursor commands are currently available in LINMATCH. + + Interactive Keystroke Commands + +? Print help +: Colon commands + +g Draw a plot of the current fit +i Draw the residuals plot for the current fit +p Draw a plot of current photometry +s Draw histograms for the image region nearest the cursor +l Draw the least squares fit for the image region nearest the cursor +h Draw histogram plot of each image region in turn +l Draw least squares fits plot of each image region in turn +r Redraw the current plot +d Delete the image region nearest the cursor +u Undelete the image region nearest the cursor +f Recompute the intensity matching function +w Update the task parameters +q Exit + + + Colon Commands + +:markcoords Mark objects on the display +:marksections Mark image sections on the display +:show Show current values of all the parameters + + Show/set Parameters + +:input [string] Show/set the current input image +:reference [string] Show/set the current reference image / phot file +:regions [string] Show/set the current image regions +:photfile [string] Show/set the current input photometry file +:lintransform [string] Show/set the linear transform database file name +:dnx [value] Show/set the default x size of an image region +:dny [value] Show/set the default y size of an image region +:shifts [string] Show/set the current shifts file +:xshift [value] Show/set the input image x shift +:yshift [value] Show/set the input image y shift +:output [string] Show/set the current output image name +:maxnregions Show the maximum number of objects / regions +:gain [string] Show/set the gain value / image header keyword +:readnoise [string] Show/set the readout noise value / image header + keyword + +:scaling Show the current scaling algorithm +:datamin [value] Show/set the minimum good data value +:datamax [value] Show/set the maximum good data value +:nreject [value] Show/set the maximum number of rejection cycles +:loreject [value] Show/set low side k-sigma rejection parameter +:hireject [value] Show/set high side k-sigma rejection parameter +.fi + +.ih +ALGORITHMS + +MEAN, MEDIAN, AND MODE + +For each input and reference image region the mean, median, mode, statistic +and an error estimate for that statistic are computed as shown below, +mstat is for mean, median, or mode statistic, emstat stands for the error +estimate, stdev for the measured standard deviation, and npix for the +number of points. + +.nf + mstat = mean, median, or mode + emstat = min (sqrt (mean / gain + readnoise ** 2 / gain ** 2), + stdev / sqrt(npix)) +.fi + +If only a single image region is specified then mstat is used to compute +one of bscale or bzero but not both as shown below. Bscale is computed by +default. + +.nf + bscale = mstat[ref] / mstat[input] + err[bscale] = abs (bscale) * sqrt (emstat[ref] ** 2 / mstat[ref] ** 2 + + emstat[input] ** 2 / mstat[input] ** 2) + bzero = constant + err[bzero] = 0.0 + + bzero = mstat[ref] - mstat[input] + err[bzero] = sqrt (emstat[ref] ** 2 + emstat[input] ** 2) + bscale = constant + err[bscale] = 0.0 +.fi + +If more than one image region is defined then the computed mean, median, +or mode values for the input and reference image regions are used as +shown below to compute the bscale and bzero factors and their errors +using a weighted least squares fit. + +.nf + mstat[ref] = bscale * mstat[input] + bzero +.fi + +If an image region contains data outside the limits defined +by \fIdatamin\fR and \fIdatamax\fR that image region is eliminated +entirely from the fit. + +The parameters \fInreject\fR, \fIloreject\fR, +and \fIhireject\fR are used to detect and automatically eliminate +deviant data points from the final least squares fit. If for some reason +bscale or bzero cannot be fit, default values of 1.0 and 0.0 are +assigned. + +The mean, median, and mode algorithms depend on the global properties of +the image regions. These algorithms do require the reference and +input images to have the same pixel scale and orientation, +but do not automatically require the reference and input images +to have the same point spread function. Small shifts between the reference +and input images can be removed using the \fIshifts\fR, \fIxshift\fR, and +\fIyshift\fR parameters. + +If the image regions contain stars, then either regions should be large +enough to include all the flux of the stars in which case the images +do not have to have the same psf, or the psfs should be the same so +that same portion of the psf is sampled. The best image regions for +matching will contain object and background information. + +FIT + +For each input and reference image the bscale and bzero factors are +computed by doing a pixel to pixel weighted least squares fit of the reference +image counts to the input image counts as shown below. + +.nf + counts[ref] = bscale * counts[input] + bzero + weight = 1.0 / (err[ref] ** 2 + bscale ** 2 * err[input] ** 2) + err[ref] = sqrt (counts[ref] / gain[ref] + readnoise[ref] ** 2 / + gain[ref] ** 2) + err[input] = sqrt (counts[input] / gain[input] + + readnoise[input] ** 2 / gain[input] ** 2) +.fi + +The fitting technique takes into account errors in both the reference and +input image counts and provides an error estimate for the computed bscale +and bzero factors. Bad data are rejected +automatically from the fit by setting the \fIdatamin\fR and \fIdatamax\fR +parameters. Deviant pixels are rejected from the fit by setting the +\fInreject\fR, \fIloreject\fR, and \fIhireject\fR parameters appropriately. + +The final bscale and bzero for the input image are computed by calculating +the average weighted by their errors of the individual bscale and bzero +values. The parameters \fInreject\fR, \fIloreject\fR, and \fIhirject\fR +can be used to automatically detect and reject deviant points. + +The fit algorithm depends on the results of pixel to pixel fits in +each reference and input image region. The technique requires that the +images be spatially registered and psfmatched before it is employed. +Each input and reference image should contain a range of pixel intensities +so that both bscale and bzero can be accurately determined. + +PHOTOMETRY + +For each object common to the reference and input photometry files +the input sky values sky, errors in the sky values serr, +magnitudes mag, and magnitude errors merr are used to compute the +bscale and bzero factors and estimate their errors as shown +below. + +.nf + bscale = 10.0 ** ((mag[ref] - mag[input]) / 2.5) + bzero = sky[ref] - bscale * sky[input] + err[bscale] = 0.4 * log(10.0) * bscale * sqrt (merr[ref] ** 2 + + magerr[input] ** 2)) + err[bzero] = sqrt (serr[ref] ** 2 + err[bscale] ** 2 * + sky[input] ** 2 + bscale ** 2 * sky[input] ** 2) +.fi + +The final bscale and bzero for the input image are computed by calculation +the average of the individual bscale and bzero values weighted by their +errors. The parameters \fInreject\fR, \fIloreject\fR, and \fIhirject\fR can +be used to automatically detect and reject deviant points. + +THE LEAST SQUARES FITTING TECHNIQUE + +The least squares fitting code performs a double linear regression on +the x and y points, taking into account the errors in both x and y. + +The best fitting line is the defined below. + +.nf + y = a * x + b +.fi + +The error ellipses are + +.nf + S = (x - xfit) ** 2 / err[x] ** 2 + (y - yfit) ** 2 / + err[y] ** 2 +.fi + +where S is the quantity to be minimized. Initial values of a and b are +estimated by fitting the data to a straight line assuming uniform +weighting. The best fit values of a and b are then +determined by iterating on the relationship + +.nf + dy = x' * da + db +.fi + +where da and db are corrections to the previously determined values of a and +b and dy and x' are defined as. + +.nf + dy = y - (ax + b) + x' = x + a * err[x] ** 2 * dy / (a ** 2 * err[x] ** 2 + + err[y] ** 2) +.fi + +The new values of the a and b then become. + +.nf + a = a + da + b = b + db +.fi + +.ih +REFERENCES + +A review of doubly weighted linear regression problems in +astronomy can be found in the paper "Linear Regression in Astronomy. II" +by (Feigelson and Babu (1992 Ap.J. 397, 55). A detailed derivation of the +particular solution used by LINMATCH can be found in the article +"The Techniques of Least Squares and Stellar Photometry with CCDs" +by Stetson (1989 Proceeding of the V Advanced School of Astrophysics, +p 51). + +.ih +EXAMPLES + +1. Match the intensity scales of a list of images to a reference +image using a list of stars on the displayed reference image with +the image cursor and the "mean" scaling algorithm. Assume that none +of the stars are saturated and that a radius of 31 pixels is sufficient +to include all the flux from the stars plus some background flux. +Make sure that the correct gain and readout noise values are in the +image headers. + +.nf + cl> display refimage 1 + + cl> rimcursor > objlist + ... mark several candidate stars by moving the cursor to the + star of interest and hitting the space bar key + ... type EOF to terminate the list + + cl> linmatch @imlist refimage objlist lintran.db \ + out=@outlist dnx=31 dny=31 scaling="mean mean" gain=gain \ + readnoise=readnoise +.fi + +2. Repeat the previous command but force the bzero factor to be -100.0 +instead of using the fitted value. + +.nf + cl> linmatch @imlist refimage objlist lintran.db \ + out=@outlist dnx=31 dny=31 scaling="mean -100.0" \ + gain=gain readnoise=rdnoise +.fi + +3. Repeat the first example but compute bscale and bzero +the bscale and bzero values using boxcar smoothed versions of +the input images. Make sure the gain and readout noise are +adjusted appropriately. + +.nf + cl> linmatch @bimlist brefimage objlist lintran.db \ + dnx=31 dny=31 scaling="mean mean" gain=gain \ + readnoise=rdnoise + + cl> linmatch @imlist refimage objlist lintran.db \ + out=@outimlist records=@bimlist scaling="file file" +.fi + +4. Match the intensity of an input image which has been spatially +registered and psfmatched to the reference image using the "fit" algorithm +and a single reference image region. Remove the effects of saturated +pixels by setting datamax to 28000 counts, and the effects of any deviant pixels +by setting nreject, loreject, and hireject to appropriate values. + +.nf + cl> linmatch image refimage [50:150,50:150] lintran.db \ + out=outimage scaling="fit fit" datamax=28000 nreject=3 \ + loreject=3 hireject=3 gain=gain readnoise=rdnoise +.fi + +5. Repeat the previous example but use several image sections to compute +the bscale and bzero values. + +.nf + cl> linmatch image refimage sections lintran.db \ + out=outimage scaling="fit fit" datamax=28000 nreject=3 \ + loreject=3 hireject=3 gain=gain readnoise=rdnoise +.fi + +6. Match the intensity scales of two images using photometry +computed with the apphot package qphot task. The two images are +spatially registered, psfmatched, and the photometry aperture is sufficient to +include all the light from the stars. The filecalc task used to compute +the error in the mean sky is in the addon ctio package. + +.nf + cl> display refimage 1 fi+ + cl> rimcursor > objlist + ... mark several candidate stars by moving the cursor to the + star of interest and hitting the space bar key + ... type EOF to terminate the list + cl> qphot refimage coords=objlist inter- + cl> qphot image coords=objlist inter- + cl> pdump refimage.mag.1 msky,stdev,nsky,mag,merr yes | filecalc \ + STDIN "$1;$2/sqrt($3);$4;$5" > refimage.phot + cl> pdump image.mag.1 msky,stdev,nsky,mag,merr yes | filecalc \ + STDIN "$1;$2/sqrt($3);$4;$5" > image.phot + cl> linmatch image refimage.phot image.phot lintran.db \ + out=outimage scaling="phot phot" nreject=3 loreject=3\ + hireject=3 +.fi + +7. Register two images interactively using the fit algorithms and +five non-overlapping image regions in the sections file. + +.nf + cl> linmatch image refimage sections lintran.db \ + out=outimage scaling="fit fit" datamax=28000 nreject=3 \ + loreject=3 hireject=3 gain=gain readnoise=rdnoise \ + interactive + + + ... a plot of bscale and bzero versus region number + appears + + ... type ? to get a list of the keystroke and : commands + + ... type i to see a plot of the bscale and bzero residuals + versus region + + ... type g to return to the default bscale and bzero versus + region plot + + ... type l to examine plot of the fits and residuals for the + individual regions + ... step forward and back in the regions list with the + space bar and -keys + ... flip back and forth between the fit and residuals + keys with l and i keys + ... return to the main plot by typing q + + ... return to the residuals plot by typing i and delete a + region with a large residual by moving to the + bad point and typing d + + ... type f to recompute the fit + + ... type q to quit the interactive loop, n to go to the + next image or q to quit the task + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imexpr, imcombine, ctio.filecalc, apphot.qphot, apphot.phot +.endhelp diff --git a/pkg/images/immatch/doc/psfmatch.hlp b/pkg/images/immatch/doc/psfmatch.hlp new file mode 100644 index 00000000..4972700e --- /dev/null +++ b/pkg/images/immatch/doc/psfmatch.hlp @@ -0,0 +1,595 @@ +.help psfmatch Oct94 images.immatch +.ih +NAME +psfmatch -- match the point spread functions of 1 and 2D images +.ih +USAGE +psfmatch input reference psfdata kernel +.ih +PARAMETERS +.ls input +The list of input images to be matched. +.le +.ls reference +The list of reference images to which the input images are to be matched if +\fIconvolution\fR = "image", or the list of reference image psfs if +\fIconvolution\fR = "psf". The reference image psf must be broader than the +input image psf in at least one dimension. +The number of reference images/psfs must be one or equal to the number of +input images. +.le +.ls psfdata +The list of objects used to compute the psf matching function if +\fIconvolution\fR is "image", or the list of input image psfs if +\fIconvolution\fR is "psf". In the former case \fIpsfdata\fR may be: +1) a string containing the x and y coordinates of a single object, +e.g. "51.0 105.0" or 2) the name of a text file containing a list of +objects, and the number of objects +files must equal the number of reference images. In the latter case +the number of input psf images must equal the number of input images. +.le +.ls kernel +The list of input/output psf matching function images to be convolved with the +input images to produce the output images. The number of kernel images +must equal the number of input images. +.le +.ls output = "" +The list of output matched images. If \fIoutput\fR is the NULL string +then the psf matching function is computed for each input image and written to +\fIkernel\fR but no output images are written. If \fIoutput\fR is not NULL +then the number of output images must equal the number of input images. +.le +.ls convolution = "image" +The algorithm used to compute the psf matching function. The options are: +.ls image +The psf matching function is computed directly from the reference and input +image data using the objects specified in \fIpsfdata\fR, the data +regions specified by \fIdnx\fR, \fIdny\fR, \fIpnx\fR, and \fIpny\fR, +and the convolution theorem. +.le +.ls psf +The psf matching function is computed directly from pre-computed +reference and input image psfs using the convolution theorem. +.le +.ls kernel +No psf matching function is computed. Instead the psf matching function +is read from the input image \fIkernel\fR. +.le +.le +.ls dnx = 31, ls dny = 31 +The x and y width of the data region to be extracted around each object. The +data region should be big enough to include both object and sky data. +\fIDnx\fR and \fIdny\fR are not used if \fIconvolution\fR is "psf" or +"kernel". +.le +.ls pnx = 15, pny = 15 +The x and y width of the psf matching function to be computed which must be +less than \fIdnx\fR and \fIdny\fR respectively. The psf +matching function should be kept as small as possible to minimize +the time required to compute the output image. +\fIPnx\fR and \fIPny\fR are not used if \fIconvolution\fR is "psf" or +"kernel". +.le +.ls center = yes +Center the objects in \fIpsfdata\fR before extracting the data from the +input and reference images. Centering should be turned off if the objects +are non-stellar and do not have well-defined centers. +Centering is turned off if \fIconvolution\fR is "psf" or +"kernel". +.le +.ls background = median +The default background function to be subtracted from the input +and reference image data in each object region before the +psf matching function is computed. The background is computed using +data inside the data extraction region defined by \fIdnx\fR and \fIdny\fR +but outside the kernel region defined by \fIpnx\fR and \fIpny\fR. +Background fitting is turned off if \fIconvolution\fR is "psf" or +"kernel". +The options are: +.ls none +no background subtraction is done. +.le +.ls "insky refsky" +the numerical values of insky and refsky are subtracted from the +input and reference image respectively. +.le +.ls mean +the mean of the input and reference image region is computed and subtracted +from the image data. +.le +.ls median +the median of the input and reference image region is computed and subtracted +from the data. +.le +.ls plane +a plane is fit to the input and reference image region and subtracted +from the data. +.le +.le +.ls loreject = INDEF, ls hireject = INDEF +The k-sigma rejection limits for removing the effects of bad data from the +background fit. +.le +.ls apodize = 0.0 +The fraction of the input and reference image data endpoints in x and y +to apodize with a +cosine bell function before the psf matching function is computed. +Apodizing is turned off if \fIconvolution\fR is "psf" or +"kernel". +.le +.ls fluxratio = INDEF +The ratio of the integrated flux of the reference objects to the integrated +flux of the input objects. +By default \fIfluxratio\fR is computed directly from the input data. +.le +.ls filter = "replace" +The filter used to remove high frequency noise from the psf +matching function. Filtering is not performed if \fIconvolution\fR +is "kernel". The options are: +.ls cosbell +apply a cosine bell taper to the psf matching function in frequency space. +.le +.ls replace +replace the high-frequency low signal-to-noise components of the psf matching +function with a gaussian model computed from the low frequency +high signal-to-noise components of the matching function. +.le +.ls model +replace the entire psf matching function with a gaussian model fit to the +low frequency high signal-to-noise components of the matching function. +.le +.le +.ls sx1 = INDEF, sx2 = INDEF, sy1 = INDEF, sy2 = INDEF +The limits of the cosine bell taper in frequency space. Frequency components +inside sx1 and sy1 are unaltered. Frequency components outside sx2 and sy2 +are set to 0.0. By default sx1 and sy1 are set to 0.0, +and sx2 and sy2 are set to the largest frequency present in the data. +.le +.ls radsym = no +Compute a radially symmetric cosine bell function ? +.le +.ls threshold = 0.2 +The low frequency cutoff in fraction of the total input image spectrum +power for the filtering options "replace" and "model". +.le +.ls normfactor = 1.0 +The total power in the computed psf matching function \fIkernel\fR. By default +the psf matching function is normalized. If \fInormfactor\fR +is set to INDEF, then the total power is set to \fIfluxratio\fR. +\fINormfactor\fR is not used if \fIconvolution\fR is set "kernel". +.le +.ls boundary_type = "nearest" +The boundary extension algorithm used to compute the output matched +image. The options are: +.ls nearest +use the value of the nearest boundary pixel. +.le +.ls constant +use a constant value. +.le +.ls reflect +generate a value by reflecting about the boundary. +.le +.ls wrap +generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0.0 +The default constant for constant boundary extension. +.le +.ls interactive = no +Compute the psf matching function for each image +interactively using graphics cursor and, optionally, image cursor input. +.le +.ls verbose +Print messages about the progress of the task in non-interactive mode. +.le +.ls graphics = "stdgraph" +The default graphics device. +.le +.ls display = "stdimage" +The default image display device. +.le +.ls gcommands = "" +The default graphics cursor. +.le +.ls icommands = "" +The default image display cursor. +.le + +.ih +DESCRIPTION + +PSFMATCH computes the convolution kernel required to match the +point-spread functions +of the input images \fIinput\fR to the point-spread functions of +the reference images \fIreference\fR using either the image data +or pre-computed psfs and the convolution theorem. +The computed psf matching functions are stored in the \fIkernel\fR images. +If a non-NULL list of output images \fIoutput\fR is +specified the input images are +convolved with the kernel images to produce a list of psf matched output +images. PSFMATCH requires +that the input and reference images be spatially registered +and that the reference images have poorer resolution (broader PSF) +than the input images in at least one dimension. + +If \fIconvolution\fR = "image", the matching function is computed directly +from the input and reference image data using the objects listed in +\fIpsfdata\fR and the convolution theorem as described in the ALGORITHMS +section. \fIpsfdata\fR is interpreted as either: 1) a +string defining the coordinates of a single object e.g. "103.3 189.2" or 2) +the name of a text file containing the coordinates of one or +more objects, one object per line, with the x and y coordinates +in columns 1 and 2 respectively. The object coordinates, the +size of the data region to be extracted \fIdnx\fR +by \fIdny\fR, and the size of the kernel to be computed \fIpnx\fR and +\fIpny\fR, determine +the input and reference image regions used to compute the psf matching +function. +These image regions should be selected with care. Ideal regions +contain a single high signal-to-noise unsaturated star which has no close +neighbors and is well centered on a pixel. + +If \fIcenter\fR is "yes" and \fIconvolution\fR is "image", the objects +in \fIpsfdata\fR are centered before +the data region is extracted. Centering should be on if the objects +are stellar, particularly if their coordinates were read from the image +display cursor. Centering should be off if the objects are non-stellar and +do not have well-defined centers. + +If the \fIbackground\fR fitting algorithm is other than "none" and +\fIconvolution\fR is "image", the background for each object is fit using +data inside the region defined by +\fIdnx\fR and \fIdny\fR but outside the region defined by +\fIpnx\fR by \fIpny\fR. Bad data can be removed from the +background fit by setting the parameters \fIloreject\fR and \fIhireject\fR. +A cosine bell function is applied to the edges of the data region +after background fitting but before computing the psf matching function +if the \fIapodize\fR parameter is > 0.0. + +If \fIpsfdata\fR contains more than one object, the extracted image data +is weighted by the total intensity in the extracted region after +background subtraction, and averaged to produce a single smoothed +data region for each reference and input image. + +If \fIconvolution\fR = "psf", +the psf matching function is computed directly from the input image +and reference +image point-spread functions +using the convolution theorem as described in the ALGORITHMS section. +In this case \fIpsfdata\fR is the list of input image psfs and +\fIreference\fR are the corresponding reference image psfs written by +by some external psf modeling task. +If \fIconvolution\fR is "psf", +centering and background fitting +are assumed to have been performed by the psf modeling task and are not +performed by PSFMATCH. + +PSFMATCH requires that the total power in the psf matching function +before normalization be the ratio +of the integrated flux of the reference image/psf over the integrated +flux of the input image/psf. If \fIfluxratio\fR is INDEF, PSFMATCH +estimates this number internally as described in the ALGORITHMS section, +otherwise the \fIfluxratio\fR is set to the value supplied by the user. + +If \fIconvolution\fR is "kernel", PSFMATCH reads the psf matching function +from the images in \fIkernel\fR which were either +created during a previous run of PSFMATCH or by a separate task. + +PSFMATCH provides several options for filtering out the ill-behaved +noise-dominated high frequency components of the psf matching function +that are produced when the ratio of reference / input image of psf +fourier transforms is taken. + +If \fIfilter\fR is set to "cosbell", a cosine bell function +with a taper defined by \fIsx1\fR, \fIsx2\fR, \fIsy1\fR, and \fIsy2\fR and +symmetry defined by \fRradsym\fR is applied to +the psf matching function in frequency space. This filter +sets all the frequency components greater than \fIsx2\fR and \fIsy2\fR +to 0.0 and leaves all frequency components inside \fIsx1\fR and \fIsy1\fR +unaltered. Users should exercise this option with caution as the effect +of the filtering process can be to significantly +broaden the computed psf matching function as described in the ALGORITHMS +section. + +An alternative approach to dealing with the noisy +high frequency components of the psf +matching function it is to replace them with a reasonable guess. If the +matching function is approximately gaussian then its fourier transform is also +approximately gaussian and the low frequency components can be modeled +reliably with an elliptical gaussian function. The model derived from the low +frequency components of the matching can then be used to replace the high +frequency components. +If \fIfilter\fR is set to "replace", those high frequency components +of the matching function which have less than a fraction +\fIthreshold\fR of their total power in the equivalent high frequency +components of the divisor or input image transform, +are replaced by a model computed by fitting a gaussian to the low frequency +components of the matching function, as described in the ALGORITHMS section. +If \fIfilter\fR = "model" then the entire psf matching function +is replaced with the best fitting gaussian model. + +Another problem can arise during the computation of the psf matching +function . Occasionally it is not possible by means of a single execution +of PSFMATCH to match the reference and input image psfs. An example +of this situation +is the case where the seeing of the reference and input images +was comparable but the declination guiding error in the reference +image was larger than the error in the input image. +In this case input image needs to be convolved to the resolution of +the reference image. However it is also the case +that the guiding error in ra in the input image is greater than the guiding +error in ra in the reference image. In this case the reference image needs +to be convolved to the resolution of the input image along the other axis. +If no corrective action is taken by the task, the +first time PSFMATCH is run the values of the psf matching function along +the ra axis will be greater than the computed fluxratio, resulting in +unrealistic action +along this axis. PSFMATCH avoids this situation by internally limiting +the psf matching function to a maximum value of fluxratio computed as described +above. + +By default the psf matching function is normalized to unit power before +output. This may not be what is desired since if carefully computed the +internally computed quantity a contains information about differences +in exposure time, transparency, etc. If \fInormfactor\fR is set to +a number of INDEF, the total power of the psf matching function will be +set to that value of \fIfluxratio\fR respectively. + +If a list of output images names has been supplied then the computed +psf matching function is applied to the input images to produce +the output images using the boundary extension algorithm +defined by \fIboundary\fR and \fIconstant\fR. + +In non-interactive mode the parameters are set at task startup time and +the input images are processed sequentially. If the \fIverbose\fR flag +is set messages about the progress of the task are printed on he +screen as the task is running. + +In interactive mode the user can mark the regions to be used to compute +the psf matching function on the image display, show/set the data +and algorithm parameters, compute, recompute, and plot the psf matching +function and its accompanying fourier spectrum, and experiment with the +various filtering and modeling options. + +.ih +CURSOR COMMANDS + +The following graphics cursor commands are currently available in +PSFMATCH. + +.nf + Interactive Keystroke Commands + + +? Print help +: Colon commands +k Draw a contour plot of the psf matching kernel +p Draw a contour plot of the psf matching kernel fourier spectrum +x Draw a column plot of the psf matching kernel / fourier spectrum +y Draw a line plot of the psf matching kernel / fourier spectrum +r Redraw the current plot +f Recompute the psf matching kernel +w Update the task parameters +q Exit + + + Colon Commands + + +:mark [file] Mark objects on the display +:show Show current values of the parameters + + + Show/Set Parameters + + +:input [string] Show/set the current input image name +:reference [string] Show/set the current reference image/psf name +:psf [file/string] Show/set the objects/input psf list +:psfimage [string] Show/set the current input psf name +:kernel [string] Show/set the current psf matching kernel name +:output [string] Show/set the current output image name + +:dnx [value] Show/set x width of data region(s) to extract +:dny [value] Show/set y width of data region(s) to extract +:pnx [value] Show/set x width of psf matching kernel +:pny [value] Show/set y width of psf matching kernel +:center [yes/no] Show/set the centering switch +:background [string] Show/set the background fitting function +:loreject [value] Show/set low side k-sigma rejection parameter +:hireject [value] Show/set high side k-sigma rejection parameter +:apodize [value] Show/set percent of endpoints to apodize + +:filter [string] Show/set the filtering algorithm +:fluxratio [value] Show/set the reference/input psf flux ratio +:sx1 [value] Show/set inner x frequency for cosbell filter +:sx2 [value] Show/set outer x frequency for cosbell filter +:sy1 [value] Show/set inner y frequency for cosbell filter +:sy2 [value] Show/set outer y frequency for cosbell filter +:radsym [yes/no] Show/set radial symmetry for cosbell filter +:threshold [value] Show/set %threshold for replace/modeling filter +:normfactor [value] Show/set the kernel normalization factor +.fi + +.ih +ALGORITHMS + +The problem of computing the psf matching function can expressed +via the convolution theorem as shown below. +In the following expressions r is the reference +image data or reference image psf, i is the input image data or input image +psf, k is the unit power psf matching +function, +a is a scale factor specifying the ratio of the total +power in the reference data or psf to the total power in the input data or +psf, * is the convolution operator, and FT is the fourier transform operator. + +.nf + r = ak * d + R = FT (r) + I = FT (i) + aK = R / I + ak = FT (aK) +.fi + +The quantity ak is the desired psf matching function and aK is its fourier +transform. + +If the background was accurately removed from the image or psf data before the +psf matching function was computed, the quantity a is simply the central +frequency component of the computed psf matching function aK as shown below. + +.nf + aK[0,0] = a = sum(r) / sum(i) +.fi + +If the background was not removed from the image or psf data before the +psf matching function was computed the previous expression is not valid. +The computed aK[0,0] will include an offset and a must be estimated +in some other manner. The approach taken by PSFMATCH in this circumstance +is to fit a gaussian model to the absolute value of 1st and 2nd frequencies +of R and I along the x and y axes independently, average the fitted x and y +amplitudes, and set aK[0,0] to the ratio of the resulting fitted amplitudes +as shown below. + +.nf + a = amplitude (R) / amplitude (I) + = (sum(r) - sum(skyr)) / (sum(i) - sum(skyi)) + aK[0,0] = a +.fi + +This approach will work well as long as the image data or psf is reasonably +gaussian but may not work well in arbitrary image regions. If the user is +dissatisfied with either of the techniques described above they can +set aK[0,0] to a pre-determined value of their own. + +If a filter is applied to the computed psf matching function in frequency +space then instead of computing + +.nf + ak = FT (aK) +.fi + +PSFMATCH actually computes + +.nf + ak' = FT (aKF) = ak * f +.fi + +where F is the applied filter in frequency space and f is its +fourier transform. Care should be taken in applying any filter. +For example if F is the step function, then ak' will be the desired kernel +ak convolved with f, a sinc function of frequency 2 * PI / hwidth where +hwidth is the half-width of the step function, and the resulting k' +will be too broad. + +If the user chooses to replace the high frequency components of the psf +matching function with a best guess, PSFMATCH performs the following +steps: + +.nf +1) fits an elliptical gaussian to those frequency components of the fourier +spectrum of aK for which for which the amplitude of I is greater +than threshold * I[0,0] to determine the geometry of the ellipse + +2) uses the fourier shift theorem to preserve the phase information in the +model and solve for any x and y shifts + +3) replace those frequency components of aK for which the fourier spectrum +of I is less than threshold * I[0,0] with the model values + + or alternatively + +replace all of aK with the model values +.fi + +.ih +EXAMPLES + +1. Psf match a list of input images taken at different epochs with variable +seeing conditions to a reference image with the poorest seeing by marking +several high signal-to-noise isolated stars on the displayed reference image +and computing the psf matching function directly from the input and reference +image data. User makes two runs with psfmatch one to compute and check the +kernel images and one to match the images. + +.nf + cl> display refimage 1 fi+ + + cl> rimcursor > objects + + cl> psfmatch @inimlist refimage objects @kernels dnx=31 \ + dny=31 pnx=15 pny=15 + + cl> imstat @kernels + + cl> psfmatch @inlist refimage objects @kernels \ + output=@outlist convolution="kernel" +.fi + +2. Psf match two spectra using a high signal-to-noise portion of the +data in the middle of the spectrum. Since the spectra are registered +spatially and there is little data available for background fitting the +user chooses to turn centering off and set the backgrounds manually. + +.nf + cl> psfmatch inspec refspec "303.0 1.0" kernel \ + output=outspec dnx=31 dny=31 pnx=15 pny=15 center- \ + back="403.6 452.0" +.fi + +3. Psf match two images using psf functions inpsf and refpsf computed with +the daophot package phot/psf/seepsf tasks. Since the kernel is fairly +large use the stsdas fourier package task fconvolve to do the actual +convolution. The boundary extension algorithm in fconvolve is equivalent +to setting the psfmatch boundary extension parameters boundary and +constant to "constant" and "0.0" respectively. + +.nf + cl> psfmatch inimage refpsf inpsf kernel convolution=psf + + cl> fconvolve inimage kernel outimage +.fi + +4. Psf match two images interactively using the image data itself to +compute the psf matching function. + +.nf + cl> psfmatch inimage refimage objects kernel interactive+ + + ... a contour plot of the psf matching function appears + with the graphics cursor ready to accept commands + + ... type x and y to get line and column plots of the psf + matching function at various points and k to return + to the default contour plot + + ... type ? to get a list of the available commands + + ... type :mark to define a new set of objects + + ... type f to recompute the psf matching function using + the new objects + + ... increase the data window to 63 pixels in x and y + with the :dnx 63 and :dny 63 commands, at the + same time increase the psf function size to 31 with + the colon commands :pnx 31 and :pny 31 + + ... type f to recompute the psf matching function using + the new data and kernel windows + + ... type q to quit the task, and q again to verify the previous + q command +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +convolve, gauss, stsdas.fconvolve, digiphot.daophot.psf +.endhelp diff --git a/pkg/images/immatch/doc/skymap.hlp b/pkg/images/immatch/doc/skymap.hlp new file mode 100644 index 00000000..b1a4a3fc --- /dev/null +++ b/pkg/images/immatch/doc/skymap.hlp @@ -0,0 +1,642 @@ +.help skymap Dec96 images.immatch +.ih +NAME +skymap -- compute the spatial transformation function required to register +a list of images using celestial coordinate WCS information +.ih +USAGE +skymap input reference database +.ih +PARAMETERS +.ls input +The list of input images containing the input celestial coordinate wcs. +.le +.ls reference +The list of reference images containing the reference celestial coordinate +wcs. The number of reference images must be one or equal to the number +of input images. +.le +.ls database +The name of the output text database file containing the computed +transformations. +.le +.ls transforms = "" +An option transform name list. If transforms is undefined then the +transforms are assigned record names equal to the input image names. +.le +.ls results = "" +Optional output files containing a summary of the results including a +description of the transform geometry and a listing of the input coordinates, +the fitted coordinates, and the fit residuals. The number of results files +must be one or equal to the number of input files. If results is "STDOUT" the +results summary is printed on the standard output. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to generate +the grid of reference image control points and define the region of +validity of the spatial transformation. Xmin, xmax, ymin, and +ymax are assigned defaults of 1, the number of columns in the reference +image, 1, and the number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid. +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in degrees for all celestial coordinate +systems. Obviously if the +wcs is correct the ra and dec of an object +should remain the same no matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +.le +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls rwxformat = "", rwyformat = "" +The format of the output reference image celestial coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for all celestial coordinate +systems. +.le +.ls wxformat = "", wyformat = "" +The format of the output input image celestial coordinates +in columns 7 and 8 respectively. The internal default formats will give +reasonable output formats and precision for all celestial coordinate +systems. +.le +.ls fitgeometry = "general" +The fitting geometry to be used. The options are the following. +.ls shift +X and y shifts only are fit. +.le +.ls xyscale +X and y shifts and x and y magnification factors are fit. Axis flips are +allowed for. +.le +.ls rotate +X and y shifts and a rotation angle are fit. Axis flips are allowed for. +.le +.ls rscale +X and y shifts, a magnification factor assumed to be the same in x and y, and a +rotation angle are fit. Axis flips are allowed for. +.le +.ls rxyscale +X and y shifts, x and y magnifications factors, and a rotation angle are fit. +Axis flips are allowed for. +.le +.ls general +A polynomial of arbitrary order in x and y is fit. A linear term and a +distortion term are computed separately. The linear term includes an x and y +shift, an x and y scale factor, a rotation and a skew. Axis flips are also +allowed for in the linear portion of the fit. The distortion term consists +of a polynomial fit to the residuals of the linear term. By default the +distortion terms is set to zero. +.le + +For all the fitting geometries except "general" no distortion term is fit, +i.e. the x and y polynomial orders are assumed to be 2 and the cross term +switches are set to "none" regardless of the values of the \fIxxorder\fR, +\fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and \fIyxterms\fR +parameters set by the user. +.le +.ls function = "polynomial" +The type of analytic coordinate surfaces to be fit. The options are the +following. +.ls legendre +Legendre polynomials in x and y. +.le +.ls chebyshev +Chebyshev polynomials in x and y. +.le +.ls polynomial +Power series polynomials in x and y. +.le +.le +.ls xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2 +The order of the polynomials in x and y for the x and y fits respectively. +The default order and cross term settings define the linear term in x +and y, where the 6 coefficients can be interpreted in terms of an x and y shift, +an x and y scale change, and rotations of the x and y axes. The "shift", +"xyscale", "rotation", "rscale", and "rxyscale", fitting geometries +assume that the polynomial order parameters are 2 regardless of the values +set by the user. If any of the order parameters are higher than 2 and +\fIfitgeometry\fR is "general", then a distortion surface is fit to the +residuals from the linear portion of the fit. +.le + +.ls xxterms = "half", yxterms = "half" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1, xyorder - 1) for the x fit and +MAX (yxorder - 1, yyorder - 1) for the y fit. +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1 + xyorder - 1) for the x fit and +MAX (yxorder - 1 + yyorder - 1) for the y fit. +.le + +The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting +geometries, assume that the cross term switches are set to "none"regardless +of the values set by the user. If either of the cross terms parameters is +set to "half" or "full" and \fIfitgeometry\fR is "general" then a distortion +surface is fit to the residuals from the linear portion of the fit. +.le + +.ls reject = INDEF +The rejection limit in units of sigma. The default is no rejection. +.le +.ls calctype = "real" +The precision of coordinate transformation calculations. The options are "real" +and "double". +.le +.ls verbose = yes +Print messages about the progress of the task? +.le +.ls interactive = yes +Run the task interactively ? +In interactive mode the user may interact with the fitting process, e.g. +change the order of the fit, delete points, replot the data etc. +.le +.ls graphics = "stdgraph" +The graphics device. +.le +.ls gcommands = "" +The graphics cursor. +.le + +.ih +DESCRIPTION + +SKYMAP computes the spatial transformation function required to map the +celestial coordinate system of the reference image \fIreference\fR to +the celestial coordinate +system of the input image \fIinput\fR, and stores the computed function in +the output text database file \fIdatabase\fR. +The input and reference images may be 1D or 2D but +must have the same dimensionality. The input image and output +text database file can be input to the REGISTER or GEOTRAN tasks to +perform the actual image registration. SKYMAP assumes that the world +coordinate systems in the input and reference +image headers are accurate and that the two systems are compatible, e.g. both +images have a celestial coordinate system WCS. + +SKYMAP computes the required spatial transformation by matching the logical +x and y pixel coordinates of a grid of points +in the input image with the logical x and y pixels coordinates +of the same grid of points in the reference image, +using celestial coordinate information stored in the two image headers. +The coordinate grid consists of \fInx * ny\fR points evenly distributed +over the logical pixel space of interest in the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y reference image pixel coordinates are transformed to +reference image celestial coordinates using +world coordinate information stored in the reference image header. +The reference image celestial coordinates are transformed to +input image celestial coordinates using world coordinate +system information in both the reference and the input image headers. +Finally the input image celestial coordinates are transformed to logical x and y +input image pixel coordinates using world coordinate system information +stored in the input image header. The transformation sequence looks +like the following for an equatorial celestial coordinate system: + +.nf + (x,y) reference -> (ra,dec) reference (reference image wcs) +(ra,dec) reference -> (ra,dec) input (reference and input image wcs) + (ra,dec) input -> (x,y) input (input image wcs) +.fi + +The computed reference and input logical coordinates and the +world coordinates are written to temporary coordinates file which is +deleted on task termination. +The pixel and celestial coordinates are written using +the \fIxformat\fR and \fIyformat\fR and the \fIrwxformat\fR, \fIrwyformat\fR, +\fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the celestial coordinates a format attribute cannot be +read from either the reference or the input images, reasonable default +formats are chosen. +If the reference and input images are 1D then all the output logical and +world y coordinates are set to 1. + +SKYMAP computes a spatial transformation of the following form. + +.nf + xin = f (xref, yref) + yin = g (xref, yref) +.fi + +The functions f and g are either a power series polynomial or a Legendre or +Chebyshev polynomial surface of order \fIxxorder\fR and \fIxyorder\fR in x +and \fIyxorder\fR and \fIyyorder\fR in y. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xxterms = "none", xyterms = "none" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a13' * yref ** 2 + +xxterms = "half", xyterms = "half" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a22 * xref * yref + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a22' * xref * yref + a13' * yref ** 2 + +xxterms = "full", xyterms = "full" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a31 * xref ** 2 + + a12 * yref + a22 * xref * yref + a32 * xref ** 2 * yref + + a13 * yref ** 2 + a23 * xref * yref ** 2 + + a33 * xref ** 2 * yref ** 2 + yin = a11' + a21' * xref + a31' * xref ** 2 + + a12' * yref + a22' * xref * yref + a32' * xref ** 2 * yref + + a13' * yref ** 2 + a23' * xref * yref ** 2 + + a33' * xref ** 2 * yref ** 2 +.fi + +If the \fBfitgeometry\fR parameter is anything other than "general", the +order parameters assume the value 2 and the cross terms switches assume +the value "none", regardless of the values set by the user. The computation +can be done in either real or double precision by setting the \fIcalctype\fR +parameter. Automatic pixel rejection may be enabled by setting the \fIreject\fR +parameter to a positive number other than INDEF. + +The transformation computed by the "general" fitting geometry is arbitrary +and does not necessarily correspond to a physically meaningful model. +However the computed +coefficients for the linear term can be given a simple geometrical geometric +interpretation for all the fitting geometries as shown below. + +.nf + fitting geometry = general (linear term) + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + + fitting geometry = shift + xin = a + xref + yin = d + yref + + fitting geometry = xyscale + xin = a + b * xref + yin = d + f * yref + + fitting geometry = rotate + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/-1 + b = f, c = -e or b = -f, c = e + + fitting geometry = rscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const + b = f, c = -e or b = -f, c = e + + fitting geometry = rxyscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const +.fi + + +The coefficients can be interpreted as follows. Xref0, yref0, xin0, yin0 +are the origins in the reference and input frames respectively. Orientation +and skew are the orientation of the x and y axes and their deviation from +perpendicularity respectively. Xmag and ymag are the scaling factors in x and +y and are assumed to be positive. + +.nf + general (linear term) + xrotation = rotation - skew / 2 + yrotation = rotation + skew / 2 + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + shift + xrotation = 0.0, yrotation = 0.0 + xmag = ymag = 1.0 + b = 1.0 + c = 0.0 + e = 0.0 + f = 1.0 + a = xin0 - xref0 = xshift + d = yin0 - yref0 = yshift + + xyscale + xrotation 0.0 / 180.0 yrotation = 0.0 + b = + /- xmag + c = 0.0 + e = 0.0 + f = ymag + a = xin0 - b * xref0 = xshift + d = yin0 - f * yref0 = yshift + + rscale + xrotation = rotation + 0 / 180, yrotation = rotation + mag = xmag = ymag + const = mag * mag + b = mag * cos (xrotation) + c = mag * sin (yrotation) + e = -mag * sin (xrotation) + f = mag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + rxyscale + xrotation = rotation + 0 / 180, yrotation = rotation + const = xmag * ymag + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift +.fi + + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the region of +validity of the fit as well as the limits of the grid +in the reference coordinate system. These parameters are also used to +reject out of range data before the actual fitting is done. + +Each computed transformation is written to the output file \fIdatabase\fR +in a record whose name is supplied by the user via the \fItransforms\fR +parameter or set to the name of the corresponding input image. +The database file is opened in append mode and new records are written +to the end of the existing file. If more that one record of the same +name is written to the database file, the last record written is the +valid record, i.e. the one that will be used by the REGISTER or +GEOTRAN tasks. + +SKYMAP will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the celestial coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the celestial <-> logical coordinate systems cannot be compiled for either +or both images, or the celestial coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image. +This grid of points defines an identity transformation which will leave +the input image unchanged if applied by the REGISTER or GEOTRAN tasks. + +If \fIverbose\fR is "yes" then messages about the progress of the task +as well as warning messages indicating potential problems are written to +the standard output. If \fIresults\fR is set to a file name then the input +coordinates, the fitted coordinates, and the residuals of the fit are +written to that file. + +SKYMAP may be run interactively by setting the \fIinteractive\fR +parameter to "yes". +In interactive mode the user has the option of viewing the fit, changing the +fit parameters, deleting and undeleting points, and replotting +the data until a satisfactory +fit has been achieved. + +.ih +CURSOR COMMANDS + +In interactive mode the following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print options +f Fit the data and graph with the current graph type (g, x, r, y, s) +g Graph the data and the current fit +x,r Graph the x fit residuals versus x and y respectively +y,s Graph the y fit residuals versus x and y respectively +d,u Delete or undelete the data point nearest the cursor +o Overplot the next graph +c Toggle the constant x, y plotting option +t Plot a line of constant x, y through the nearest data point +l Print xshift, yshift, xmag, ymag, xrotate, yrotate +q Exit the interactive curve fitting +.fi + +The parameters listed below can be changed interactively with simple colon +commands. Typing the parameter name alone will list the current value. + +.nf + Colon Parameter Editing Commands + +:show List parameters +:fitgeometry Fitting geometry (shift,xyscale,rotate, + rscale,rxyscale,general) +:function [value] Fitting function (chebyshev,legendre, + polynomial) +:xxorder :xyorder [value] X fitting function xorder, yorder +:yxorder :yyorder [value] Y fitting function xorder, yorder +:xxterms :yxterms [n/h/f] X, Y fit cross terms type +:reject [value] Rejection threshold +.fi + + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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. + +.ih +EXAMPLES + +1. Compute the spatial transformation required to match a radio image to an +X-ray image of the same field using a 100 point coordinate grid +and a simple linear transformation. Both images have accurate sky +equatorial world coordinate systems define at different equinoxes. +Print the output world coordinates +in the coords file in hh:mm:ss.ss and dd:mm:ss.s format. Run geotran +on the results to do the actual registration. + +.nf + cl> skymap radio xray geodb rwxformat=%12.2H rwyformat=%12.1h \ + wxformat=%12.2H wyformat=%12.1h interactive- + + cl> geotran radio radio.tran geodb radio +.fi + +2. Repeat the previous command but begin with a higher order fit +and run the task in interactive mode in order to examine the fit +residuals. + +.nf + cl> skymap radio xray geodb rwxformat=%12.2H rwyformat=%12.1h \ + wxformat=%12.2H wyformat=%12.1h xxo=4 xyo=4 xxt=half \ + yxo=4 yyo=4 yxt=half + + ... a plot of the fit appears + + ... type x and r to examine the residuals of the x + surface fit versus x and y + + ... type y and s to examine the residuals of the y + surface fit versus x and y + + ... delete 2 deviant points with the d key and + recompute the fit with the f key + + ... type q to quit and save the fit + + cl> geotran radio radio.tran geodb radio +.fi + +3. Repeat example 1 but set the transform name specifically. + +.nf + cl> skymap radio xray geodb trans=m82 rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h \ + interactive- + + cl> geotran radio radio.tran geodb m82 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +wcsctran,register,geotran +.endhelp diff --git a/pkg/images/immatch/doc/skyxymatch.hlp b/pkg/images/immatch/doc/skyxymatch.hlp new file mode 100644 index 00000000..63485284 --- /dev/null +++ b/pkg/images/immatch/doc/skyxymatch.hlp @@ -0,0 +1,406 @@ +.help skyxymatch Dec96 images.immatch +.ih +NAME +skyxymatch -- match input and reference image x-y coordinates using the +celestial coordinate WCS +.ih +USAGE +skyxymatch input reference output +.ih +PARAMETERS +.ls input +The list of input images containing the input celestial coordinate wcs. +.le +.ls reference +The list of reference images containing the reference celestial coordinate +wcs. The number of reference images must be one or equal to the number +of input images. +.le +.ls output +The output matched coordinate lists containing: +1) the logical x-y pixel coordinates of a point +in the reference image in columns 1 and 2, 2) the logical x-y pixel +coordinates of the same point in the input image in columns 3 and 4, +3) the world coordinates of the point in the reference image in columns +5 and 6, and 4) the world coordinate of the point in the input image in +columns 7 and 8. The output coordinate list can be +input directly to the geomap task. The number of output files must be +equal to the number of input images or be the standard output STDOUT. +.le +.ls coords = "grid" +The source of the coordinate list. The options are: +.ls grid +Generate a list of \fInx * ny\fR coordinates evenly spaced over +the reference image, and beginning and ending at logical coordinates +\fIxmin\fR and \fIxmax\fR in x and \fIymin\fR and \fIymax\fR in y. +.le +.ls <filename> +The name of the text file containing the world coordinates of a set of +points in the reference image. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to generate +the grid of control points if \fIcoords\fR = "grid". Xmin, xmax, ymin, and +ymax default to 1, the number of columns in the reference image, 1, and the +number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid +if \fIcoords\fR = "grid". +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in decimal degrees for the celestial coordinate systems. Obviously if the +wcs is correct the ra and dec of an object +should remain the same no matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls xcolumn = 1, ycolumn = 2 +The columns in the input coordinate list containing the x and y coordinate +values if \fIcoords\fR = <filename>. +.le +.ls xunits = "", ls yunits = "" +The units of the x and y coordinates in the input coordinate list +if \fIcoords\fR = <filename>, by default decimal degrees for celestial +coordinate systems, otherwise any units. +The options are: +.ls hours +Input coordinates specified in hours are converted to decimal degrees by +multiplying by 15.0. +.le +.ls native +The internal units of the wcs. No conversions on the input coordinates +are performed. +.le + +If the units are not specified the default is "native". +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls rwxformat = "", rwyformat = "" +The format of the output world x and y reference image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for sky projection coordinates. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y input image coordinates +in columns 7 and 8 respectively. The internal default formats will give +reasonable output formats and precision for sky projection coordinates. +.le +.ls min_sigdigits = 7 +The minimum precision of the output coordinates if, the formatting parameters +are undefined, or the output world coordinate system is "world" and the wcs +cannot be decoded. +.le +.ls verbose = yes +Print messages about the progress of the task? +.le + +.ih +DESCRIPTION + +SKYXYMATCH matches the logical x and y pixel coordinates of a set of points +in the input image \fIinput\fR with the logical x and y pixels coordinates +of the same points in the reference image \fIreference\fR +using world celestial coordinate information +in the image headers. SKYXYMATCH writes its results to the +coordinate file \fIoutput\fR which is suitable for input to the GEOMAP task. +The input and reference images may be 1D or 2D but must both have +the same dimensionality. + +If \fIcoords\fR = "grid", SKYXYMATCH computes a grid of \fInx * ny\fR +logical x and y pixel coordinates evenly distributed over the +logical pixel space of the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y reference image pixel coordinates are transformed to +reference image celestial coordinates using +world coordinate information stored in the reference image header. +The reference image celestial coordinates are transformed to +input image celestial coordinates using world coordinate +system information in both the reference and the input image headers. +Finally the input image celestial coordinates are transformed to logical x and y +input image pixel coordinates using world coordinate system information +stored in the input image header. The transformation sequence looks +like the following for an equatorial celestial coordinate system: + +.nf + (x,y) reference -> (ra,dec) reference (reference image wcs) +(ra,dec) reference -> (ra,dec) input (reference and input image wcs) + (ra,dec) input -> (x,y) input (input image wcs) +.fi + +The reference and input image celestial coordinate systems +may be equatorial, ecliptic, galactic, or supergalactic. The equatorial systems +may be one of: 1) the mean place pre-IAU 1976 (FK4) system, 2) +the same as FK4 but without the E-terms (FK4-NO-E) system, 3) the mean +place post-IAU +1976 (FK5) system, 4) or the geocentric apparent place in the post-IAU 1976 +(GAPPT) system. + +SKYXYMATCH assumes that the celestial coordinate system is specified by the FITS +keywords CTYPE, CRPIX, CRVAL, CD (or alternatively CDELT / CROTA), RADECSYS, +EQUINOX (or EPOCH), MJD-WCS (or MJD-OBS, or DATE-OBS). USERS SHOULD TAKE NOTE +THAT MJD-WCS IS CURRENTLY NEITHER A STANDARD OR A PROPOSED STANDARD FITS +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 currently +permitted values of CTYPE[1:4] 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. + +The second four characters of the values of the ra / longitude and dec / +latitude axis CTYPE keywords specify the sky projection geometry. IRAF +currently supports the TAN, SIN, ARC, and GLS geometries, and consequently the +currently permitted values of CTYPE[5:8] are -TAN, -ARC, -SIN, and -GLS. +SKYXYMATCH fully supports the TAN, SIN, and ARC projections, but does not fully +support the GLS projection. + +If the image celestial coordinate systems are equatorial, the value of the +RADECSYS keyword specifies which fundamental equatorial system is to be +considered. 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 / EPOCH keywords (in that order of precedence) are used to determine +the fundamental equatorial coordinate 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, +if they must enter their own equinox values 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-WCS or MJD-OBS (which contain the modified Julian date, JD - +2400000.5, of the coordinate system), or the DATE-OBS keyword (which contains +the date of the observation in the form DD/MM/YY, CCYY-MM-DD, +CCYY-MM-DDTHH:MM:SS.S). As the latter quantity is +only accurate to a day, the MJD-WCS or MJD-OBS specification is preferred. +If all 3 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 (in that order of precedence) as for the FK4 and +FK4-NO-E system. + +If the image celestial coordinate systems are ecliptic the mean ecliptic +and equinox of date are required. These are read from the MJD-WCS, MJD-OBS, +or DATE-OBS keywords (in that order or precedence) 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 2 AND EARLIER) SUPPORTS ONLY THE +EQUATORIAL SYSTEM (CTYPE<lngax> = "RA--XXXX" CTYPE<latax> = "DEC-XXXX") +WHERE XXXX IS THE PROJECTION TYPE, EVEN THOUGH THE SKYXYMATCH TASK +SUPPORTS GALACTIC, SUPERGALACTIC, AND ECLIPTIC coordinate systems. + +If \fIcoords\fR is a file name, SKYXYMATCH reads a list of x and y +reference image world coordinates from columns \fIxcolumn\fR and \fIycolumn\fR +in the input coordinates file and transforms these coordinates to +"native" coordinate units using the \fIxunits\fR and \fIyunits\fR parameters. +The reference image world coordinates are +transformed to logical reference and input image coordinates +using the value of the \fIwcs\fR parameter and world coordinate +information in the reference and input image headers. + +SKYXYMATCH will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image, +and defining an identify transformation, is written to the output file. + +The computed reference and input logical and world coordinates +are written to the output file using +the \fIxformat\fR and \fIyformat\fR, \fIrwxformat\fr, \fIrwyformat\fR, +and the \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the world coordinates, a format attribute cannot be +read from either the reference or the input images reasonable defaults are +chosen. + +If the reference and input images are 1D then the +output logical and world y coordinates are +set to 1. + +If \fIverbose\fR is "yes" then a title section is written to the output +file for each set of computed coordinates, along with messages about +what if anything went wrong with the computation. + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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. + +.ih +EXAMPLES + +1. Compute a matched list of 100 logical x and y coordinates for an X-ray +and radio image of the same field, both of which have accurate sky +projection world coordinate systems with different equinoxes. Print the +output world coordinates in hh:mm:ss.ss and dd:mm:ss.s format + +.nf + cl> skyxymatch image refimage coords rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h +.fi + +2. Given a list of ras and decs of objects in the reference image, +compute a list of matched logical x and y coordinates for the two images, +both of which have a accurate sky projection wcss, although the reference +wcs is in equatorial coordinates and the input wcs is in galactic +coordinates. The ras and decs are in +columns 3 and 4 of the input coordinate file and are in hh:mm:ss.ss and +dd:mm:ss.s format respectively. Print the output world coordinates +in the same units as the input. + +.nf + cl> skyxymatch image refimage coords coords=radecs \ + xcolumn=3 ycolumn=4 xunits=hours rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +skyctran,wcsctran,geomap,geotran,skymap,sregister +.endhelp diff --git a/pkg/images/immatch/doc/sregister.hlp b/pkg/images/immatch/doc/sregister.hlp new file mode 100644 index 00000000..5bc829c5 --- /dev/null +++ b/pkg/images/immatch/doc/sregister.hlp @@ -0,0 +1,779 @@ +.help sregister Dec98 images.immatch +.ih +NAME +sregister -- register a list of images to a reference image using celestial +coordinate WCS information +.ih +USAGE +sregister input reference output +.ih +PARAMETERS +.ls input +The list of input images containing the input celestial coordinate wcs. +.le +.ls reference +The list of reference images containing the reference celestial coordinate wcs. +The number of reference images must be one or equal to the number of +input images. +.le +.ls output +The list of output registered images. The number of output images must +be equal to the number of input images. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to, generate +the grid of reference image control points, define the region of validity of +the spatial transformation, and define the extent of the output image. +Xmin, xmax, ymin, and +ymax are assigned defaults of 1, the number of columns in the reference +image, 1, and the number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid. +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in decimal degrees for celestial coordinate systems. Obviously if the +wcs is correct the ra and dec of an object +should remain the same no matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls rwxformat = "", rwyformat = "" +The format of the output world x and y reference image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for celestial coordinate +systems. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y input image coordinates +in columns 7 and 8 respectively. The internal default formats will give +reasonable output formats and precision for celestial coordinate +systems. +.le +.ls fitgeometry = "general" +The fitting geometry to be used. The options are the following. +.ls shift +X and y shifts only are fit. +.le +.ls xyscale +X and y shifts and x and y magnification factors are fit. Axis flips are +allowed for. +.le +.ls rotate +X and y shifts and a rotation angle are fit. Axis flips are allowed for. +.le +.ls rscale +X and y shifts, a magnification factor assumed to be the same in x and y, and a +rotation angle are fit. Axis flips are allowed for. +.le +.ls rxyscale +X and y shifts, x and y magnifications factors, and a rotation angle are fit. +Axis flips are allowed for. +.le +.ls general +A polynomial of arbitrary order in x and y is fit. A linear term and a +distortion term are computed separately. The linear term includes an x and y +shift, an x and y scale factor, a rotation and a skew. Axis flips are also +allowed for in the linear portion of the fit. The distortion term consists +of a polynomial fit to the residuals of the linear term. By default the +distortion terms is set to zero. +.le + +For all the fitting geometries except "general" no distortion term is fit, +i.e. the x and y polynomial orders are assumed to be 2 and the cross term +switches are set to "none", regardless of the values of the \fIxxorder\fR, +\fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and \fIyxterms\fR +parameters set by the user. +.le +.ls function = "polynomial" +The type of analytic coordinate surfaces to be fit. The options are the +following: +.ls legendre +Legendre polynomials in x and y. +.le +.ls chebyshev +Chebyshev polynomials in x and y. +.le +.ls polynomial +Power series polynomials in x and y. +.le +.le +.ls xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2 +The order of the polynomials in x and y for the x and y fits respectively. +The default order and cross term settings define the linear term in x +and y, where the 6 coefficients can be interpreted in terms of an x and y shift, +an x and y scale change, and rotations of the x and y axes. The "shift", +"xyscale", "rotation", "rscale", and "rxyscale", fitting geometries +assume that the polynomial order parameters are 2 regardless of the values +set by the user. If any of the order parameters are higher than 2 and +\fIfitgeometry\fR is "general", then a distortion surface is fit to the +residuals from the linear portion of the fit. +.le +.ls xxterms = "half", yxterms = "half" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1, xyorder - 1) for the x fit and +MAX (yxorder - 1, yyorder - 1) for the y fit. +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1 + xyorder - 1) for the x fit and +MAX (yxorder - 1 + yyorder - 1) for the y fit. +.le + +The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting +geometries, assume that the cross term switches are set to "none"regardless +of the values set by the user. If either of the cross terms parameters is +set to "half" or "full" and \fIfitgeometry\fR is "general" then a distortion +surface is fit to the residuals from the linear portion of the fit. +.le + +.ls reject = INDEF +The rejection limit in units of sigma. The default is no rejection. +.le +.ls calctype = "real" +The precision of coordinate transformation calculations. The options are "real" +and "double". +.le +.ls geometry = "geometric" +The type of geometric transformation. The options are: +.ls linear +Perform only the linear part of the geometric transformation. +.le +.ls geometric +Compute both the linear and distortion portions of the geometric correction. +.le +.le +.ls xsample = 1.0, ysample = 1.0 +The coordinate surface subsampling factor. The coordinate surfaces are +evaluated at every xsample-th pixel in x and every ysample-th pixel in y. +Transformed coordinates at intermediate pixel values are determined by +bilinear interpolation in the coordinate surfaces. If the coordinate +surface is of high order setting these numbers to some reasonably high +value is recommended. +.le +.ls interpolant = "linear" +The interpolant used for rebinning the image. The choices are the following. +.ls nearest +Nearest neighbor. +.le +.ls linear +Bilinear interpolation in x and y. +.le +.ls poly3 +Third order polynomial in x and y. +.le +.ls poly5 +Fifth order polynomial in x and y. +.le +.ls spline3 +Bicubic spline. +.le +.ls sinc +2D sinc interpolation. Users can specify the sinc interpolant width by +appending a width value to the interpolant string, e.g. sinc51 specifies +a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to +the nearest odd number. The default sinc width is 31 by 31. +.le +.ls lsinc +Look-up table sinc interpolation. Users can specify the look-up table sinc +interpolant width by appending a width value to the interpolant string, e.g. +lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user +supplied sinc width will be rounded up to the nearest odd number. The default +sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup +table sinc by appending the look-up table size in square brackets to the +interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc +look-up table interpolant with a pixel resolution of 0.05 pixels in x and y. +The default look-up table size and resolution are 20 by 20 and 0.05 pixels +in x and y respectively. +.le +.ls drizzle +2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y +by appending a value between 0.0 and 1.0 in square brackets to the +interpolant string, e.g. drizzle[0.5]. The default value is 1.0. +The value 0.0 is increased internally to 0.001. Drizzle resampling +with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel +rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no) if +xmag and ymag are > 1.0. +.le +.le +.ls boundary = "nearest" +The choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a user supplied constant value. +.le +.ls reflect +Generate a value by reflecting about the boundary of the image. +.le +.ls wrap +Generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0.0 +The value of the constant for boundary extension. +.le +.ls fluxconserve = yes +Preserve the total image flux? If flux conservation is turned on, the output +pixel values are multiplied by the Jacobian of the coordinate transformation. +.le +.ls nxblock = 512, nyblock = 512 +If the size of the output image is less than nxblock by nyblock then +the entire image is transformed at once. Otherwise the output image +is computed in blocks nxblock by nyblock pixels. +.le +.ls wcsinherit = yes +Inherit the wcs of the reference image? +.le +.ls verbose = yes +Print messages about the progress of the task? +.le +.ls interactive = no +Run the task interactively ? +In interactive mode the user may interact with the fitting process, e.g. +change the order of the fit, delete points, replot the data etc. +.le +.ls graphics = "stdgraph" +The graphics device. +.le +.ls gcommands = "" +The graphics cursor. +.le + +.ih +DESCRIPTION + +SREGISTER computes the spatial transformation function required to register +the input image \fIinput\fR to the reference image \fIreference\fR, +and writes the registered input image to the output image \fIoutput\fR. +The input and reference images may be 1D or 2D but must have +the same dimensionality. SREGISTER assumes that the world +coordinate systems in the input and reference +image headers are accurate and that both systems are compatible, e.g. both +images have a celestial coordinate system WCS. + +SREGISTER computes the required spatial transformation by matching the logical +x and y pixel coordinates of a grid of points +in the input image with the logical x and y pixels coordinates +of the same grid of points in the reference image, +using world coordinate information stored in the two image headers. +The coordinate grid consists of \fInx * ny\fR points evenly distributed +over the logical pixel space of interest in the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The reference image celestial coordinates are transformed to +input image celestial coordinates using world coordinate +system information in both the reference and the input image headers. +Finally the input image celestial coordinates are transformed to logical x and y +input image pixel coordinates using world coordinate system information +stored in the input image header. The transformation sequence looks +like the following for an equatorial celestial coordinate system: + +.nf + (x,y) reference -> (ra,dec) reference (reference image wcs) +(ra,dec) reference -> (ra,dec) input (reference and input image wcs) + (ra,dec) input -> (x,y) input (input image wcs) +.fi + +The computed reference and input logical coordinates and the +celestial coordinates are written to a temporary output coordinates file +which is deleted on task termination. The pixel and celestial coordinates +are output using the \fIxformat\fR and \fIyformat\fR and the \fIrwxformat\fR, +\fIrwyformat\fR, \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the celestial coordinates a format attribute cannot be +read from either the reference or the input images, the coordinates are +output in %g format with \fImin_sigdigits\fR digits of precision. +If the reference and input images are 1D then all the output logical and +world y coordinates are set to 1. + +SREGISTER computes a spatial transformation of the following form. + +.nf + xin = f (xref, yref) + yin = g (xref, yref) +.fi + +The functions f and g are either a power series polynomial or a Legendre or +Chebyshev polynomial surface of order +\fIxxorder\fR and \fIxyorder\fR in x and \fIyxorder\fR and \fIyyorder\fR in y. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xxterms = "none", xyterms = "none" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a13' * yref ** 2 + +xxterms = "half", xyterms = "half" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a22 * xref * yref + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a22' * xref * yref + a13' * yref ** 2 + +xxterms = "full", xyterms = "full" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a31 * xref ** 2 + + a12 * yref + a22 * xref * yref + a32 * xref ** 2 * yref + + a13 * yref ** 2 + a23 * xref * yref ** 2 + + a33 * xref ** 2 * yref ** 2 + yin = a11' + a21' * xref + a31' * xref ** 2 + + a12' * yref + a22' * xref * yref + a32' * xref ** 2 * yref + + a13' * yref ** 2 + a23' * xref * yref ** 2 + + a33' * xref ** 2 * yref ** 2 +.fi + + +The computation can be done in either real or +double precision by setting the \fIcalctype\fR parameter. +Automatic pixel rejection may be enabled by setting the \fIreject\fR +parameter to some number > 0.0. + +The transformation computed by the "general" fitting geometry is arbitrary +and does not correspond to a physically meaningful model. However the computed +coefficients for the linear term can be given a simple geometrical geometric +interpretation for all the fitting geometries as shown below. + +.nf + fitting geometry = general (linear term) + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + + fitting geometry = shift + xin = a + xref + yin = d + yref + + fitting geometry = xyscale + xin = a + b * xref + yin = d + f * yref + + fitting geometry = rotate + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/-1 + b = f, c = -e or b = -f, c = e + + fitting geometry = rscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const + b = f, c = -e or b = -f, c = e + + fitting geometry = rxyscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const +.fi + +The coefficients can be interpreted as follows. Xref0, yref0, xin0, yin0 +are the origins in the reference and input frames respectively. Orientation +and skew are the orientation of the x and y axes and their deviation from +perpendicularity respectively. Xmag and ymag are the scaling factors in x and +y and are assumed to be positive. + +.nf + general (linear term) + xrotation = rotation - skew / 2 + yrotation = rotation + skew / 2 + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + shift + xrotation = 0.0, yrotation = 0.0 + xmag = ymag = 1.0 + b = 1.0 + c = 0.0 + e = 0.0 + f = 1.0 + a = xin0 - xref0 = xshift + d = yin0 - yref0 = yshift + + xyscale + xrotation 0.0 / 180.0 yrotation = 0.0 + b = + /- xmag + c = 0.0 + e = 0.0 + f = ymag + a = xin0 - b * xref0 = xshift + d = yin0 - f * yref0 = yshift + + rscale + xrotation = rotation + 0 / 180, yrotation = rotation + mag = xmag = ymag + const = mag * mag + b = mag * cos (xrotation) + c = mag * sin (yrotation) + e = -mag * sin (xrotation) + f = mag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + rxyscale + xrotation = rotation + 0 / 180, yrotation = rotation + const = xmag * ymag + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift +.fi + + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the region of +validity of the transformation as well as the limits of the grid +in the reference coordinate system. + +Each computed transformation is written to the a temporary output text database +file which is deleted on task termination. Otherwise the +database file is opened in append mode and new records are written +to the end of the existing file. If more that one record of the same +name is written to the database file, the last record written is the +valid record. + +SREGISTER will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image. +This grid of points defines an identity transformation which results in +an output image equal to the input image. + +SREGISTER computes the output image by evaluating the fitted coordinate +surfaces and interpolating in the input image at position of the transformed +coordinates. The scale of the output image is the same as the scale of the +reference image. The extent and size of the output image are determined +by the \fIxmin\fR, \fIxmax\fR, \fIymin\fR, and \fIymax\fR parameters +as shown below + +.nf + xmin <= x <= xmax + ymin <= x <= ymax + ncols = xmax - xmin + 1 + nlines = xmax - xmin + 1 +.fi + +SREGISTER samples the coordinate surfaces at every \fIxsample\fR and +\fIysample\fR pixels in x and y. +The transformed coordinates at intermediate pixel values are +determined by bilinear interpolation in the coordinate surface. If +\fIxsample\fR and \fIysample\fR = 1, the coordinate +surface is evaluated at every pixel. Use of \fIxsample\fR and \fIysample\fR +are strongly recommended for large images and high order coordinate +surfaces in order to reduce the time required to compute the output image. + +The output image gray levels are determined by interpolating in the input +image at the positions of the transformed output pixels using the +interpolant specified by the \fIinterpolant\fR parameter. If the +\fIfluxconserve\fR switch is set the output pixel values are multiplied by +the Jacobian of the transformation, which preserves the flux of the entire +image. Out-of-bounds pixels are evaluated using the \fIboundary\fR and +\fIconstant\fR parameters. + +The output image is computed in \fInxblock\fR by \fInyblock\fR pixel sections. +If possible users should set these number to values larger than the dimensions +of the output image in order to minimize the number of disk reads and writes +required to compute the output image. If this is not feasible and the image +rotation is small, users should set nxblock to be greater than the number of +columns in the output image, and nyblock to be as large as machine memory +will permit. + +If \fIwcsinherit\fR = "yes", then the output image will inherit the world +coordinate system of the reference image. +Otherwise if the environment variable \fInomwcs\fR is "no" the world +coordinate +system of the input image is modified in the output image to reflect the +effects of the \fIlinear\fR portion of the registration operation. +Support does not yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that SREGISTER is capable +of performing. + +If \fIverbose\fR is "yes" then messages about the progress of the task +as well as warning messages indicating potential problems +are written to the standard output. + +SREGISTER may be run interactively by setting the \fIinteractive\fR +parameter to "yes". +In interactive mode the user has the option of viewing the fitted +spatial transformation, changing the +fit parameters, deleting and undeleting points, and replotting +the data until a satisfactory +fit has been achieved. + +.ih +CURSOR COMMANDS + +In interactive mode the following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print options +f Fit the data and graph with the current graph type (g, x, r, y, s) +g Graph the data and the current fit +x,r Graph the x fit residuals versus x and y respectively +y,s Graph the y fit residuals versus x and y respectively +d,u Delete or undelete the data point nearest the cursor +o Overplot the next graph +c Toggle the constant x, y plotting option +t Plot a line of constant x, y through the nearest data point +l Print xshift, yshift, xmag, ymag, xrotate, yrotate +q Exit the interactive curve fitting +.fi + +The parameters listed below can be changed interactively with simple colon +commands. Typing the parameter name alone will list the current value. + +.nf + Colon Parameter Editing Commands + +:show List parameters +:fitgeometry Fitting geometry (shift,xyscale,rotate, + rscale,rxyscale,general) +:function [value] Fitting function (chebyshev,legendre, + polynomial) +:xxorder :xyorder [value] X fitting function xorder, yorder +:yxorder :yyorder [value] Y fitting function xorder, yorder +:xxterms :yxterms [n/h/f] X, Y fit cross term types +:reject [value] Rejection threshold +.fi + + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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. + +.ih +EXAMPLES + +1. Register a radio image to an X-ray image of the same field using +a 100 point coordinate grid and a simple linear transformation. Both +images have accurate sky projection world coordinate systems. Print the +output world coordinates in the coords file in hh:mm:ss.ss and dd:mm:ss.s +format. Display the input and output image and blink them. + +.nf + cl> sregister radio xray radio.tran rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h + + cl> display radio 1 fi+ + + cl> display radio.tran 2 fi+ +.fi + +2. Repeat the previous command but begin with a higher order fit +and run the task in interactive mode in order to examine the fit +residuals. + +.nf + cl> sregister radio xray radio.tran rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h xxo=4 \ + xyo=4 xxt=half yxo=4 yyo=4 yxt=half inter+ + + ... a plot of the fit appears + + ... type x and r to examine the residuals of the x + surface fit versus x and y + + ... type y and s to examine the residuals of the y + surface fit versus x and y + + ... delete 2 deviant points with the d key and + recompute the fit with the f key + + ... type q to quit, save the fit, and compute the registered + image +.fi + + +3. Mosaic a set of 9 images covering a ~ 1 degree field into a single image +centered at 12:32:53.1 +43:13:03. Set the output image scale to 0.5 +arc-seconds / pixel which is close the detector scale of 0.51 arc-seconds +per pixel. Set the orientation to be north up and east to the left. +The 9 images all have accurate world coordinate information in their headers. + +.nf + # Create a dummy reference image big enough to cover 1 square degree + + cl> mkpattern refimage ncols=7200 nlines=7200 ... + + # Give the dummy reference image the desired coordinate system + + cl> ccsetwcs refimage "" xref=3600.5 yref=3600.5 xmag=-0.5 \ + ymag=0.5 lngref=12:32:53.1 latref=43:13:03 ... + + # Register the images using constant boundary extension and set + # uservalue to some reasonable value outside the good data range. + # It may be possible to improve performance by increasing nxblock + # and nyblock. + + cl> sregister @inlist refimage @outlist boundary=constant \ + constant=<uservalue> nxblock=7200 nyblock=1024 ... + + # Combine the images using imcombine + + cl> imcombine @outlist mosaic lthreshold=<uservalue> ... + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imalign,xregister,register,geotran,wregister +.endhelp diff --git a/pkg/images/immatch/doc/wcscopy.hlp b/pkg/images/immatch/doc/wcscopy.hlp new file mode 100644 index 00000000..493f1311 --- /dev/null +++ b/pkg/images/immatch/doc/wcscopy.hlp @@ -0,0 +1,80 @@ +.help wcscopy Jun95 images.immatch +.ih +NAME +wcscopy -- copy the wcs of a reference image to a list of images +.ih +USAGE +wcscopy images refimages +.ih +PARAMETERS +.ls images +The list of input images which will inherit the wcs of the reference image. +If the image does not exists a dataless image header is created. +.le +.ls reference +The list of reference images containing the reference wcs. The number of +reference images must be one or equal to the number of input images. +.le +.ls verbose = yes +Print messages about the progress of the task? +.le + +.ih +DESCRIPTION + +WCSCOPY copies the world coordinate system information in the header of the +reference image \fIreference\fR to the headers of the input images +\fIimages\fR, replacing any existing world coordinate system information +in the input image headers in the process. WCSCOPY assumes that the +world coordinate system information in the header of the reference +image is accurate and that all the input images have write permission. +If the input image does not exist a data-less image header is created. +The WCS is treated as an independent object and +there is no check made on the dimensionality and sizes of the images. + + +.ih +REFERENCES + +Information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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". Information on the spectral +coordinates systems and their suitability for use with WCSXYMATCH +can be obtained by typing "help specwcs | lprint". +Details of the FITS header +world coordinate system interface can be found in the document +"World Coordinate Systems Representations Within the FITS Format" +by Hanisch and Wells, available from our anonymous ftp archive. + +.ih +EXAMPLES + +1. Make sure that the world coordinates systems of a list of input images +that have been registered to a reference image with the xregister task +are identical to the world coordinate system of the reference image. + +.nf + cl> xregister @inlist refimage [200:400,200:400] shifts \ + output=@outlist xwindow=21 ywindow=21 + cl> wcscopy @outlist refimage +.fi + +2. Create a data-less WCS image by specifying a new image. + +.nf + cl> wcscopy new dev$wpix +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +tprecess,imalign,xregister,geomap,register,geotran,wcsmap,wregister,wcsedit +.endhelp diff --git a/pkg/images/immatch/doc/wcsmap.hlp b/pkg/images/immatch/doc/wcsmap.hlp new file mode 100644 index 00000000..e2a4dd01 --- /dev/null +++ b/pkg/images/immatch/doc/wcsmap.hlp @@ -0,0 +1,619 @@ +.help wcsmap Feb96 images.immatch +.ih +NAME +wcsmap -- compute the spatial transformation function required to register +a list of images using WCS information +.ih +USAGE +wcsmap input reference database +.ih +PARAMETERS +.ls input +The list of input images containing the input wcs. +.le +.ls reference +The list of reference images containing the reference wcs. The number of +reference images must be one or equal to the number of input images. +.le +.ls database +The name of the output text database file containing the computed +transformations. +.le +.ls transforms = "" +An optional list of transform names. If transforms is undefined the +transforms are assigned record names identical to the names of the input images. +.le +.ls results = "" +Optional output files containing a summary of the results including a +description of the transform geometry and a listing of the input coordinates, +the fitted coordinates, and the fit residuals. The number of results files +must be one or equal to the number of input files. If results is "STDOUT" the +results summary is printed on the standard output. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to generate +the grid of reference image control points and define the region of +validity of the spatial transformation. Xmin, xmax, ymin, and +ymax are assigned defaults of 1, the number of columns in the reference +image, 1, and the number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid. +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in world units, normally decimal degrees for sky projection coordinate +systems and angstroms for spectral coordinate systems. Obviously if the +wcs is correct the ra and dec or wavelength and position of an object +should remain the same not matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls transpose = no +Force a transpose of the reference image world coordinates before evaluating +the world to logical coordinate transformation for the input image ? This +option is useful if there is not enough information in the reference and +input image headers to tell whether or not the images are transposed with +respect to each other. +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y reference and input image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for both sky projection coordinates +and other types, e.g. spectral, coordinates. +.le +.ls fitgeometry = "general" +The fitting geometry to be used. The options are the following. +.ls shift +X and y shifts only are fit. +.le +.ls xyscale +X and y shifts and x and y magnification factors are fit. Axis flips are +allowed for. +.le +.ls rotate +X and y shifts and a rotation angle are fit. Axis flips are allowed for. +.le +.ls rscale +X and y shifts, a magnification factor assumed to be the same in x and y, and a +rotation angle are fit. Axis flips are allowed for. +.le +.ls rxyscale +X and y shifts, x and y magnifications factors, and a rotation angle are fit. +Axis flips are allowed for. +.le +.ls general +A polynomial of arbitrary order in x and y is fit. A linear term and a +distortion term are computed separately. The linear term includes an x and y +shift, an x and y scale factor, a rotation and a skew. Axis flips are also +allowed for in the linear portion of the fit. The distortion term consists +of a polynomial fit to the residuals of the linear term. By default the +distortion terms is set to zero. +.le + +For all the fitting geometries except "general" no distortion term is fit, +i.e. the x and y polynomial orders are assumed to be 2 and the cross term +switches are set to "none", regardless of the values of the \fIxxorder\fR, +\fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and \fIyxterms\fR +parameters set by the user. +.le +.ls function = "polynomial" +The type of analytic coordinate surfaces to be fit. The options are the +following. +.ls legendre +Legendre polynomials in x and y. +.le +.ls chebyshev +Chebyshev polynomials in x and y. +.le +.ls polynomial +Power series polynomials in x and y. +.le +.le +.ls xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2 +The order of the polynomials in x and y for the x and y fits respectively. +The default order and cross term settings define the linear term in x +and y, where the 6 coefficients can be interpreted in terms of an x and y shift, +an x and y scale change, and rotations of the x and y axes. The "shift", +"xyscale", "rotation", "rscale", and "rxyscale", fitting geometries +assume that the polynomial order parameters are 2 regardless of the values +set by the user. If any of the order parameters are higher than 2 and +\fIfitgeometry\fR is "general", then a distortion surface is fit to the +residuals from the linear portion of the fit. +.le +.ls xxterms = "half", yxterms = "half" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1, xyorder - 1) for the x fit and +MAX (yxorder - 1, yyorder - 1) for the y fit. +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1 + xyorder - 1) for the x fit and +MAX (yxorder - 1 + yyorder - 1) for the y fit. +.le + +The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting +geometries, assume that the cross term switches are set to "none"regardless +of the values set by the user. If either of the cross terms parameters is +set to "half" or "full" and \fIfitgeometry\fR is "general" then a distortion +surface is fit to the residuals from the linear portion of the fit. +.le +.ls reject = INDEF +The rejection limit in units of sigma. The default is no rejection. +.le +.ls calctype = "real" +The precision of coordinate transformation calculations. The options are "real" +and "double". +.le +.ls verbose = yes +Print messages about the progress of the task? +.le +.ls interactive = yes +Run the task interactively ? +In interactive mode the user may interact with the fitting process, e.g. +change the order of the fit, delete points, replot the data etc. +.le +.ls graphics = "stdgraph" +The graphics device. +.le +.ls gcommands = "" +The graphics cursor. +.le + +.ih +DESCRIPTION + +WCSMAP computes the spatial transformation function required to map the +coordinate system of the reference image \fIreference\fR to the coordinate +system of the input image \fIinput\fR, and stores the computed function in +the output text database file \fIdatabase\fR. +The input and reference images must be one- or two-dimensional and +must have the same dimensionality. The input image and output +text database file can be input to the REGISTER or GEOTRAN tasks to +perform the actual image registration. WCSMAP assumes that the world +coordinate systems in the input and reference +image headers are accurate and that the two systems are compatible, e.g. both +images have the same epoch sky projection world coordinate systems or both are +spectra whose coordinates are in the same units. + +WCSMAP computes the required spatial transformation by matching the logical +x and y pixel coordinates of a grid of points +in the input image with the logical x and y pixels coordinates +of the same grid of points in the reference image, +using world coordinate information stored in the two image headers. +The coordinate grid consists of \fInx * ny\fR points evenly distributed +over the logical pixel space of interest in the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y pixel reference image coordinates are transformed to the +reference image world coordinate system defined by \fIwcs\fR, using the wcs +information in the reference image header. +The reference image world coordinates are then transformed to logical x and +y pixel coordinates in the input image, using world coordinate system +information stored in the input image header. + +The computed reference and input logical coordinates and the +world coordinates are written to a temporary output coordinates file which +is deleted on task termination. +The x and y coordinates are written using +the \fIxformat\fR and \fIyformat\fR and the \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the world coordinates a format attribute cannot be +read from either the reference or the input images, the coordinates are +output in %g format with \fImin_sigdigits\fR digits of precision. +If the reference and input images are 1D then all the output logical and +world y coordinates are set to 1. + +WCSMAP computes a spatial transformation of the following form. + +.nf + xin = f (xref, yref) + yin = g (xref, yref) +.fi + +The functions f and g are either a power series polynomial or a Legendre or +Chebyshev polynomial surface of order \fIxxorder\fR and \fIxyorder\fR in +x and \fIyxorder\fR and \fIyyorder\fR in y. Cross terms are optional. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xxterms = "none", xyterms = "none" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a13' * yref ** 2 + +xxterms = "half", xyterms = "half" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a22 * xref * yref + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a22' * xref * yref + a13' * yref ** 2 + +xxterms = "full", xyterms = "full" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a31 * xref ** 2 + + a12 * yref + a22 * xref * yref + a32 * xref ** 2 * yref + + a13 * yref ** 2 + a23 * xref * yref ** 2 + + a33 * xref ** 2 * yref ** 2 + yin = a11' + a21' * xref + a31' * xref ** 2 + + a12' * yref + a22' * xref * yref + a32' * xref ** 2 * yref + + a13' * yref ** 2 + a23' * xref * yref ** 2 + + a33' * xref ** 2 * yref ** 2 +.fi + +If the \fBfitgeometry\fR parameter is anything +other than "general", the order parameters assume the value 2 and the +cross terms switches assume the value "none", regardless of the values set +by the user. The computation can be done in either real or +double precision by setting the \fIcalctype\fR parameter. +Automatic pixel rejection may be enabled by setting the \fIreject\fR +parameter to some number > 0.0. + +The transformation computed by the "general" fitting geometry is arbitrary +and does not correspond to a physically meaningful model. However the computed +coefficients for the linear term can be given a simple geometrical geometric +interpretation for all the fitting geometries as shown below. + +.nf + fitting geometry = general (linear term) + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + + fitting geometry = shift + xin = a + xref + yin = d + yref + + fitting geometry = xyscale + xin = a + b * xref + yin = d + f * yref + + fitting geometry = rotate + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/-1 + b = f, c = -e or b = -f, c = e + + fitting geometry = rscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const + b = f, c = -e or b = -f, c = e + + fitting geometry = rxyscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const +.fi + + +The coefficients can be interpreted as follows. Xref0, yref0, xin0, yin0 +are the origins in the reference and input frames respectively. Orientation +and skew are the orientation of the x and y axes and their deviation from +perpendicularity respectively. Xmag and ymag are the scaling factors in x and +y and are assumed to be positive. + +.nf + general (linear term) + xrotation = rotation - skew / 2 + yrotation = rotation + skew / 2 + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + shift + xrotation = 0.0, yrotation = 0.0 + xmag = ymag = 1.0 + b = 1.0 + c = 0.0 + e = 0.0 + f = 1.0 + a = xin0 - xref0 = xshift + d = yin0 - yref0 = yshift + + xyscale + xrotation 0.0 / 180.0 yrotation = 0.0 + b = + /- xmag + c = 0.0 + e = 0.0 + f = ymag + a = xin0 - b * xref0 = xshift + d = yin0 - f * yref0 = yshift + + rscale + xrotation = rotation + 0 / 180, yrotation = rotation + mag = xmag = ymag + const = mag * mag + b = mag * cos (xrotation) + c = mag * sin (yrotation) + e = -mag * sin (xrotation) + f = mag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + rxyscale + xrotation = rotation + 0 / 180, yrotation = rotation + const = xmag * ymag + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift +.fi + + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the region of +validity of the fit as well as the limits of the grid +in the reference coordinate system and must be set by +the user. These parameters are used to reject out of range data before the +actual fitting is done. + +Each computed transformation is written to the output file \fIdatabase\fR +in a record whose name is either specified by the user via the \fItransforms\fR +parameter or defaults the name of the input image. +The database file is opened in append mode and new records are written +to the end of the existing file. If more that one record of the same +name is written to the database file, the last record written is the +valid record, i.e. the one that will be used by the REGISTER or +GEOTRAN tasks. + +WCSMAP will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image. +This grid of points defines an identity transformation which will leave +the input image unchanged if applied by the REGISTER or GEOTRAN tasks. + +If \fIverbose\fR is "yes" then messages about the progress of the task +as well as warning messages indicating potential problems are written to +the standard output. If \fIresults\fR is set to a file name then the input +coordinates, the fitted coordinates, and the residuals of the fit are +written to that file. + +WCSMAP may be run interactively by setting the \fIinteractive\fR +parameter to "yes". +In interactive mode the user has the option of viewing the fit, changing the +fit parameters, deleting and undeleting points, and replotting +the data until a satisfactory +fit has been achieved. + +.ih +CURSOR COMMANDS + +In interactive mode the following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print options +f Fit the data and graph with the current graph type (g, x, r, y, s) +g Graph the data and the current fit +x,r Graph the x fit residuals versus x and y respectively +y,s Graph the y fit residuals versus x and y respectively +d,u Delete or undelete the data point nearest the cursor +o Overplot the next graph +c Toggle the constant x, y plotting option +t Plot a line of constant x, y through the nearest data point +l Print xshift, yshift, xmag, ymag, xrotate, yrotate +q Exit the interactive curve fitting +.fi + +The parameters listed below can be changed interactively with simple colon +commands. Typing the parameter name alone will list the current value. + +.nf + Colon Parameter Editing Commands + +:show List parameters +:fitgeometry Fitting geometry (shift,xyscale,rotate, + rscale,rxyscale,general) +:function [value] Fitting function (chebyshev,legendre, + polynomial) +:xxorder :xyorder [value] X fitting function xorder, yorder +:yxorder :yyorder [value] Y fitting function xorder, yorder +:xxterms :yxterms [n/h/f] X, Y fit cross terms type +:reject [value] Rejection threshold +.fi + + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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". Information on the spectral +coordinates systems and their suitability for use with WCSXYMATCH +can be obtained by typing "help specwcs | lprint". +Details of the FITS header +world coordinate system interface can be found in the document +"World Coordinate Systems Representations Within the FITS Format" +by Hanisch and Wells, available from our anonymous ftp archive. + +.ih +EXAMPLES + +1. Compute the spatial transformation required to match a radio image to an +X-ray image of the same field using a 100 point coordinate grid +and a simple linear transformation. Both images have accurate sky +projection world coordinate systems. Print the output world coordinates +in the coords file in hh:mm:ss.ss and dd:mm:ss.s format. Run geotran +on the results to do the actual registration. + +.nf + cl> wcsmap radio xray geodb wxformat=%12.2H wyformat=%12.1h \ + interactive- + + cl> geotran radio radio.tran geodb radio +.fi + +2. Repeat the previous command but begin with a higher order fit +and run the task in interactive mode in order to examine the fit +residuals. + +.nf + cl> wcsmap radio xray geodb wxformat=%12.2H wyformat=%12.1h \ + xxo=4 xyo=4 xxt=half yxo=4 yyo=4 yxt=half + + ... a plot of the fit appears + + ... type x and r to examine the residuals of the x + surface fit versus x and y + + ... type y and s to examine the residuals of the y + surface fit versus x and y + + ... delete 2 deviant points with the d key and + recompute the fit with the f key + + ... type q to quit and save the fit + + cl> geotran radio radio.tran geodb radio +.fi + +3. Repeat example 1 but assign a user name to the transform. + +.nf + cl> wcsmap radio xray geodb transforms="m82" wxformat=%12.2H \ + wyformat=%12.1h interactive- + + cl> geotran radio radio.tran geodb m82 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +wcstran,xregister,wcsxymatch,geomap,register,geotran +.endhelp diff --git a/pkg/images/immatch/doc/wcsxymatch.hlp b/pkg/images/immatch/doc/wcsxymatch.hlp new file mode 100644 index 00000000..0651b0c7 --- /dev/null +++ b/pkg/images/immatch/doc/wcsxymatch.hlp @@ -0,0 +1,314 @@ +.help wcsxymatch Jun95 images.immatch +.ih +NAME +wcsxymatch -- match input and reference image x-y coordinates using the WCS +.ih +USAGE +wcsxymatch input reference output +.ih +PARAMETERS +.ls input +The list of input images containing the input wcs. +.le +.ls reference +The list of reference images containing the reference wcs. The number of +reference images must be one or equal to the number of input images. +.le +.ls output +The output matched coordinate lists containing: +1) the logical x-y pixel coordinates of a point +in the reference image in columns 1 and 2, 2) the logical x-y pixel +coordinates of the same point in the input image in columns 3 and 4, +3) the world coordinates of the point in the reference and input +image in columns 5 and 6. The output coordinate list can be +input directly to the geomap task. The number of output files must be +equal to the number of input images or be the standard output STDOUT. +.le +.ls coords = "grid" +The source of the coordinate list. The options are: +.ls grid +Generate a list of \fInx * ny\fR coordinates, evenly spaced over +the reference image, and beginning and ending at logical coordinates +\fIxmin\fR and \fIxmax\fR in x and \fIymin\fR and \fIymax\fR in y. +.le +.ls <filename> +The name of the text file containing the world coordinates of a set of +points in the reference image. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to generate +the grid of control points if \fIcoords\fR = "grid". Xmin, xmax, ymin, and +ymax default to 1, the number of columns in the reference image, 1, and the +number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid +if \fIcoords\fR = "grid". +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in world units, normally decimal degrees for sky projection coordinate +systems and angstroms for spectral coordinate systems. Obviously if the +wcs is correct the ra and dec or wavelength and position of an object +should remain the same not matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls transpose = no +Force a transpose of the reference image world coordinates before evaluating +the world to logical coordinate transformation for the input image ? This +option is useful if there is not enough information in the reference and +input image headers to tell whether or not the images are transposed with +respect to each other. +.le +.ls xcolumn = 1, ycolumn = 2 +The columns in the input coordinate list containing the x and y coordinate +values if \fIcoords\fR = <filename>. +.le +.ls xunits = "", ls yunits = "" +The units of the x and y coordinates in the input coordinate list +if \fIcoords\fR = <filename>, by default decimal degrees for sky projection +coordinate systems, otherwise any units. +The options are: +.ls hours +Input coordinates specified in hours are converted to decimal degrees by +multiplying by 15.0. +.le +.ls native +The internal units of the wcs. No conversions on the input coordinates +are performed. +.le + +If the units are not specified the default is "native". +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y reference and input image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for both sky projection coordinates +and other types, e.g. spectral coordinates. +.le +.ls min_sigdigits = 7 +The minimum precision of the output coordinates if, the formatting parameters +are undefined, or the output world coordinate system is "world" and the wcs +format attribute is undefined. +.le +.ls verbose = yes +Print messages about the progress of the task. +.le + +.ih +DESCRIPTION + +WCSXYMATCH matches the logical x and y pixel coordinates of a set of points +in the input image \fIinput\fR with the logical x and y pixels coordinates +of the same points in the reference image \fIreference\fR +using world coordinate information +in the respective image headers, and writes the results to a coordinate file +\fIoutput\fR suitable for input to the GEOMAP task. +The input and reference images may be 1D or 2D but must both have +the same dimensionality. + +If \fIcoords\fR = "grid", WCSXYMATCH computes a grid of \fInx * ny\fR +logical x and y pixel coordinates evenly distributed over the +logical pixel space of the reference image as defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y pixel reference image coordinates are transformed to the +world coordinate system defined by \fIwcs\fR using +world coordinate information stored in the reference image header. +The world coordinates are then transformed back to the logical x and y pixel +input image coordinates, using world coordinate system information stored in +the input image header. + +If \fIcoords\fR is a file name, WCSXYMATCH reads a list of x and y +reference image world coordinates from columns \fIxcolumn\fR and \fIycolumn\fR +in the input coordinates file, and transforms these coordinates to +"native" coordinate units using the \fIxunits\fR and \fIyunits\fR parameters. +The reference image world coordinates are +transformed to logical reference and input image coordinates +using the value of the \fIwcs\fR parameter and world coordinate +information in the reference and input image headers. + +WCSXYMATCH will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image, +and defining an identify transformation, is written to the output file. + +The computed reference and input logical coordinates and the +world coordinates are written to the output file using +the \fIxformat\fR and \fIyformat\fR, and the \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the world coordinates, a format attribute cannot be +read from either the reference or the input images, the coordinates are +output with the %g format and \fImin_sigdigits\fR of precision. + +If the reference and input images are 1D then the +output logical and world y coordinates are +set to 1. + +If \fIverbose\fR is "yes" then a title section is written to the output +file for each set of computed coordinates, along with messages about +what if anything went wrong with the computation. + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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". Information on the spectral +coordinates systems and their suitability for use with WCSXYMATCH +can be obtained by typing "help specwcs | lprint". +Details of the FITS header +world coordinate system interface can be found in the document +"World Coordinate Systems Representations Within the FITS Format" +by Hanisch and Wells, available from our anonymous ftp archive. + +.ih +EXAMPLES + +1. Compute a matched list of 100 logical x and y coordinates for an X-ray +and radio image of the same field, both of which have accurate sky +projection world coordinate systems. Print the output world coordinates +in hh:mm:ss.ss and dd:mm:ss.s format + +.nf + cl> wcsxymatch image refimage coords wxformat=%12.2H \ + wyformat=%12.1h +.fi + +2. Given a list of ras and decs of objects in the reference image, +compute a list of matched logical x and y coordinates for the two images, +both of which have a accurate sky projection wcss. The ras and decs are in +columns 3 and 4 of the input coordinate file and are in hh:mm:ss.ss and +dd:mm:ss.s format respectively. Print the output world coordinates +in the same units as the input. + +.nf + cl> wcsxymatch image refimage coords coords=radecs \ + xcolumn=3 ycolumn=4 xunits=hours wxformat=%12.2H \ + wyformat=%12.1h +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +tprecess,wcstran,geomap,register,geotran,wcsmap,wregister +.endhelp diff --git a/pkg/images/immatch/doc/wregister.hlp b/pkg/images/immatch/doc/wregister.hlp new file mode 100644 index 00000000..e8519803 --- /dev/null +++ b/pkg/images/immatch/doc/wregister.hlp @@ -0,0 +1,761 @@ +.help wregister Dec98 images.immatch +.ih +NAME +wregister -- register a list of images to a reference image using WCS +information +.ih +USAGE +wregister input reference output +.ih +PARAMETERS +.ls input +The list of input images containing the input wcs. +.le +.ls reference +The list of reference images containing the reference wcs. The number of +reference images must be one or equal to the number of input images. +.le +.ls output +The list of output registered images. The number of output images must +be equal to the number of input images. +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to, generate +the grid of reference image control points, define the region of validity of +the spatial transformation, and define the extent of the output image. +Xmin, xmax, ymin, and +ymax are assigned defaults of 1, the number of columns in the reference +image, 1, and the number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid. +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in world units, normally decimal degrees for sky projection coordinate +systems and angstroms for spectral coordinate systems. Obviously if the +wcs is correct the ra and dec or wavelength and position of an object +should remain the same not matter how the image +is linearly transformed. The default world coordinate +system is either 1) the value of the environment variable "defwcs" if +set in the user's IRAF environment (normally it is undefined) and present +in the image header, 2) the value of the "system" +attribute in the image header keyword WAT0_001 if present in the +image header or, 3) the "physical" coordinate system. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls transpose = no +Force a transpose of the reference image world coordinates before evaluating +the world to logical coordinate transformation for the input image ? This +option is useful if there is not enough information in the reference and +input image headers to tell whether or not the images are transposed with +respect to each other. +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y reference and input image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for both sky projection coordinates +and other, e.g. spectral, coordinates. +.le +.ls fitgeometry = "general" +The fitting geometry to be used. The options are the following. +.ls shift +X and y shifts only are fit. +.le +.ls xyscale +X and y shifts and x and y magnification factors are fit. Axis flips are +allowed for. +.le +.ls rotate +X and y shifts and a rotation angle are fit. Axis flips are allowed for. +.le +.ls rscale +X and y shifts, a magnification factor assumed to be the same in x and y, and a +rotation angle are fit. Axis flips are allowed for. +.le +.ls rxyscale +X and y shifts, x and y magnifications factors, and a rotation angle are fit. +Axis flips are allowed for. +.le +.ls general +A polynomial of arbitrary order in x and y is fit. A linear term and a +distortion term are computed separately. The linear term includes an x and y +shift, an x and y scale factor, a rotation and a skew. Axis flips are also +allowed for in the linear portion of the fit. The distortion term consists +of a polynomial fit to the residuals of the linear term. By default the +distortion terms is set to zero. +.le + +For all the fitting geometries except "general" no distortion term is fit, +i.e. the x and y polynomial orders are assumed to be 2 and the cross term +switches are set to "none", regardless of the values of the \fIxxorder\fR, +\fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and \fIyxterms\fR +parameters set by the user. +.le +.ls function = "polynomial" +The type of analytic coordinate surfaces to be fit. The options are the +following: +.ls legendre +Legendre polynomials in x and y. +.le +.ls chebyshev +Chebyshev polynomials in x and y. +.le +.ls polynomial +Power series polynomials in x and y. +.le +.le +.ls xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2 +The order of the polynomials in x and y for the x and y fits respectively. +The default order and cross term settings define the linear term in x +and y, where the 6 coefficients can be interpreted in terms of an x and y shift, +an x and y scale change, and rotations of the x and y axes. The "shift", +"xyscale", "rotation", "rscale", and "rxyscale", fitting geometries +assume that the polynomial order parameters are 2 regardless of the values +set by the user. If any of the order parameters are higher than 2 and +\fIfitgeometry\fR is "general", then a distortion surface is fit to the +residuals from the linear portion of the fit. +.le +.ls xxterms = "half", yxterms = "half" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1, xyorder - 1) for the x fit and +MAX (yxorder - 1, yyorder - 1) for the y fit. +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is MAX (xxorder - 1 + xyorder - 1) for the x fit and +MAX (yxorder - 1 + yyorder - 1) for the y fit. +.le + +The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting +geometries, assume that the cross term switches are set to "none"regardless +of the values set by the user. If either of the cross terms parameters is +set to "half" or "full" and \fIfitgeometry\fR is "general" then a distortion +surface is fit to the residuals from the linear portion of the fit. +.le +.ls reject = INDEF +The rejection limit in units of sigma. The default is no rejection. +.le +.ls calctype = "real" +The precision of coordinate transformation calculations. The options are "real" +and "double". +.le +.ls geometry = "geometric" +The type of geometric transformation. The options are: +.ls linear +Perform only the linear part of the geometric transformation. +.le +.ls geometric +Compute both the linear and distortion portions of the geometric correction. +.le +.le +.ls xsample = 1.0, ysample = 1.0 +The coordinate surface subsampling factor. The coordinate surfaces are +evaluated at every xsample-th pixel in x and every ysample-th pixel in y. +Transformed coordinates at intermediate pixel values are determined by +bilinear interpolation in the coordinate surfaces. If the coordinate +surface is of high order setting these numbers to some reasonably high +value is recommended. +.le +.ls interpolant = "linear" +The interpolant used for rebinning the image. The choices are the following. +.ls nearest +Nearest neighbor. +.le +.ls linear +Bilinear interpolation in x and y. +.le +.ls poly3 +Third order polynomial in x and y. +.le +.ls poly5 +Fifth order polynomial in x and y. +.le +.ls spline3 +Bicubic spline. +.le +.ls sinc +2D sinc interpolation. Users can specify the sinc interpolant width by +appending a width value to the interpolant string, e.g. sinc51 specifies +a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to +the nearest odd number. The default sinc width is 31 by 31. +.le +.ls lsinc +Look-up table sinc interpolation. Users can specify the look-up table sinc +interpolant width by appending a width value to the interpolant string, e.g. +lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user +supplied sinc width will be rounded up to the nearest odd number. The default +sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup +table sinc by appending the look-up table size in square brackets to the +interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc +look-up table interpolant with a pixel resolution of 0.05 pixels in x and y. +The default look-up table size and resolution are 20 by 20 and 0.05 pixels +in x and y respectively. +.le +.ls drizzle +2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y +by appending a value between 0.0 and 1.0 in square brackets to the +interpolant string, e.g. drizzle[0.5]. The default value is 1.0. +The value 0.0 is increased internally to 0.001. Drizzle resampling +with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel +rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no) if +xmag and ymag are > 1.0. +.le +.le +.ls boundary = "nearest" +The choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a user supplied constant value. +.le +.ls reflect +Generate a value by reflecting about the boundary of the image. +.le +.ls wrap +Generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0.0 +The value of the constant for boundary extension. +.le +.ls fluxconserve = yes +Preserve the total image flux? If flux conservation is turned on, the output +pixel values are multiplied by the Jacobian of the coordinate transformation. +.le +.ls nxblock = 512, nyblock = 512 +If the size of the output image is less than nxblock by nyblock then the +entire image is computed in one iteration. Otherwise the output image is +computed in blocks of nxblock by nyblock pixels. +.le +.ls wcsinherit = yes +Inherit the wcs of the reference image ? +.le +.ls verbose = yes +Print messages about the progress of the task? +.le +.ls interactive = no +Run the task interactively ? +In interactive mode the user may interact with the fitting process, e.g. +change the order of the fit, delete points, replot the data etc. +.le +.ls graphics = "stdgraph" +The graphics device. +.le +.ls gcommands = "" +The graphics cursor. +.le + +.ih +DESCRIPTION + +WREGISTER computes the spatial transformation function required to register +the input image \fIinput\fR to the reference image \fIreference\fR, +and writes the registered input image to the output image \fIoutput\fR. +The input and reference images must be one- or two-dimensional and +have the same dimensionality. WREGISTER assumes that the world +coordinate systems in the input and reference +image headers are accurate and that the two systems are compatible, e.g. both +images have the same epoch sky projection world coordinate systems, or both are +spectra whose coordinates are in the same units. + +WREGISTER computes the required spatial transformation by matching the logical +x and y pixel coordinates of a grid of points +in the input image with the logical x and y pixels coordinates +of the same grid of points in the reference image, +using world coordinate information stored in the two image headers. +The coordinate grid consists of \fInx * ny\fR points evenly distributed +over the logical pixel space of interest in the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y pixel reference image coordinates are transformed to the +reference image world coordinate system defined by \fIwcs\fR, using the wcs +information in the reference image header. +The reference image world coordinates are then transformed to logical x and +y pixel coordinates in the input image, using world coordinate system +information stored in the input image header. + +The computed reference and input logical coordinates and the +world coordinates are written to a temporary coordinates file which is +deleted on task termination. +The x and y coordinates are written using +the \fIxformat\fR and \fIyformat\fR and the \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the world coordinates a format attribute cannot be +read from either the reference or the input images, the coordinates are +output in %g format with \fImin_sigdigits\fR digits of precision. +If the reference and input images are 1D then all the output logical and +world y coordinates are set to 1. + +WREGISTER computes a spatial transformation of the following form. + +.nf + xin = f (xref, yref) + yin = g (xref, yref) +.fi + +The functions f and g are either a power series polynomial or a Legendre or +Chebyshev polynomial surface of order +\fIxxorder\fR and \fIxyorder\fR in x and \fIyxorder\fR and \fIyyorder\fR in y. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xxterms = "none", xyterms = "none" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a13' * yref ** 2 + +xxterms = "half", xyterms = "half" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a12 * yref + + a31 * xref ** 2 + a22 * xref * yref + a13 * yref ** 2 + yin = a11' + a21' * xref + a12' * yref + + a31' * xref ** 2 + a22' * xref * yref + a13' * yref ** 2 + +xxterms = "full", xyterms = "full" +xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 + + xin = a11 + a21 * xref + a31 * xref ** 2 + + a12 * yref + a22 * xref * yref + a32 * xref ** 2 * yref + + a13 * yref ** 2 + a23 * xref * yref ** 2 + + a33 * xref ** 2 * yref ** 2 + yin = a11' + a21' * xref + a31' * xref ** 2 + + a12' * yref + a22' * xref * yref + a32' * xref ** 2 * yref + + a13' * yref ** 2 + a23' * xref * yref ** 2 + + a33' * xref ** 2 * yref ** 2 +.fi + + +If the \fBfitgeometry\fR parameter is anything other than "general", the order +parameters assume the value 2 and the cross terms switches assume the value +"none", regardless of the values set by the user. The computation can be done in +either real or double precision by setting the \fIcalctype\fR parameter. +Automatic pixel rejection may be enabled by setting the \fIreject\fR +parameter to some number > 0.0. + +The transformation computed by the "general" fitting geometry is arbitrary +and does not correspond to a physically meaningful model. However the computed +coefficients for the linear term can be given a simple geometrical geometric +interpretation for all the fitting geometries as shown below. + +.nf + fitting geometry = general (linear term) + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + + fitting geometry = shift + xin = a + xref + yin = d + yref + + fitting geometry = xyscale + xin = a + b * xref + yin = d + f * yref + + fitting geometry = rotate + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/-1 + b = f, c = -e or b = -f, c = e + + fitting geometry = rscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const + b = f, c = -e or b = -f, c = e + + fitting geometry = rxyscale + xin = a + b * xref + c * yref + yin = d + e * xref + f * yref + b * f - c * e = +/- const +.fi + + +The coefficients can be interpreted as follows. Xref0, yref0, xin0, yin0 +are the origins in the reference and input frames respectively. Orientation +and skew are the orientation of the x and y axes and their deviation from +perpendicularity respectively. Xmag and ymag are the scaling factors in x and +y and are assumed to be positive. + +.nf + general (linear term) + xrotation = rotation - skew / 2 + yrotation = rotation + skew / 2 + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + shift + xrotation = 0.0, yrotation = 0.0 + xmag = ymag = 1.0 + b = 1.0 + c = 0.0 + e = 0.0 + f = 1.0 + a = xin0 - xref0 = xshift + d = yin0 - yref0 = yshift + + xyscale + xrotation 0.0 / 180.0 yrotation = 0.0 + b = + /- xmag + c = 0.0 + e = 0.0 + f = ymag + a = xin0 - b * xref0 = xshift + d = yin0 - f * yref0 = yshift + + rscale + xrotation = rotation + 0 / 180, yrotation = rotation + mag = xmag = ymag + const = mag * mag + b = mag * cos (xrotation) + c = mag * sin (yrotation) + e = -mag * sin (xrotation) + f = mag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift + + rxyscale + xrotation = rotation + 0 / 180, yrotation = rotation + const = xmag * ymag + b = xmag * cos (xrotation) + c = ymag * sin (yrotation) + e = -xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xin0 - b * xref0 - c * yref0 = xshift + d = yin0 - e * xref0 - f * yref0 = yshift +.fi + + +\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the region of +validity of the transformation as well as the limits of the grid +in the reference coordinate system. + +Each computed transformation is written to a temporary output text database +file which is deleted on task termination. If more that one record of the same +name is written to the database file, the last record written is the +valid record. + +WREGISTER will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image. +This grid of points defines an identity transformation which results in +an output image equal to the input image. + +WREGISTER computes the output image by evaluating the fitted coordinate +surfaces and interpolating in the input image at position of the transformed +coordinates. The scale of the output image is the same as the scale of the +reference image. The extent and size of the output image are determined +by the \fIxmin\fR, \fIxmax\fR, \fIymin\fR, and \fIymax\fR parameters +as shown below + +.nf + xmin <= x <= xmax + ymin <= x <= ymax + ncols = xmax - xmin + 1 + nlines = xmax - xmin + 1 +.fi + +WREGISTER samples the coordinate surfaces at every \fIxsample\fR and +fIysample\fR pixels in x and y. +The transformed coordinates at intermediate pixel values are +determined by bilinear interpolation in the coordinate surface. If +\fIxsample\fR and \fIysample\fR = 1, the coordinate +surface is evaluated at every pixel. Use of \fIxsample\fR and \fIysample\fR +are strongly recommended for large images and high order coordinate +surfaces in order to reduce the time required to compute the output image. + +The output image gray levels are determined by interpolating in the input +image at the positions of the transformed output pixels using the +interpolant specified by the \fIinterpolant\fR parameter. If the +\fIfluxconserve\fR switch is set the output pixel values are multiplied by +the Jacobian of the transformation, which preserves the flux of the entire +image. Out-of-bounds pixels are evaluated using the \fIboundary\fR and +\fIconstant\fR parameters. + +The output image is computed in \fInxblock\fR by \fInyblock\fR pixel sections. +If possible users should set these number to values larger than the dimensions +of the output image to minimize the number of disk reads and writes required +to compute the output image. If this is not feasible and the image rotation is +small users should set nxblock to be greater than the number of columns in +the output image, and nyblock to be as large as machine memory will permit. + +If \fIwcsinherit\fR is "yes" then the world coordinate system of the +reference image will be copied to the output image. +Otherwise if the environment variable \fInomwcs\fR is "no" the +world coordinate +system of the input image is modified in the output image to reflect the +effects of the \fIlinear\fR portion of the registration operation. +Support does not yet exist in the IRAF world coordinate system interface +for the higher order distortion corrections that WREGISTER is capable +of performing. + +If \fIverbose\fR is "yes" then messages about the progress of the task +as well as warning messages indicating potential problems +are written to the standard output. + +WREGISTER may be run interactively by setting the \fIinteractive\fR +parameter to "yes". +In interactive mode the user has the option of viewing the fitted +spatial transformation, changing the +fit parameters, deleting and undeleting points, and replotting +the data until a satisfactory +fit has been achieved. + +.ih +CURSOR COMMANDS + +In interactive mode the following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print options +f Fit the data and graph with the current graph type (g, x, r, y, s) +g Graph the data and the current fit +x,r Graph the x fit residuals versus x and y respectively +y,s Graph the y fit residuals versus x and y respectively +d,u Delete or undelete the data point nearest the cursor +o Overplot the next graph +c Toggle the constant x, y plotting option +t Plot a line of constant x, y through the nearest data point +l Print xshift, yshift, xmag, ymag, xrotate, yrotate +q Exit the interactive curve fitting +.fi + +The parameters listed below can be changed interactively with simple colon +commands. Typing the parameter name alone will list the current value. + +.nf + Colon Parameter Editing Commands + +:show List parameters +:fitgeometry Fitting geometry (shift,xyscale,rotate, + rscale,rxyscale,general) +:function [value] Fitting function (chebyshev,legendre, + polynomial) +:xxorder :xyorder [value] X fitting function xorder, yorder +:yxorder :yyorder [value] Y fitting function xorder, yorder +:xxterms :yxterms [nh/f] X, Y fit cross terms fit +:reject [value] Rejection threshold +.fi + + +.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 +REFERENCES + +Additional information on IRAF world coordinate systems including +more detailed descriptions of the "logical", "physical", and "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". Information on the spectral +coordinates systems and their suitability for use with WCSXYMATCH +can be obtained by typing "help specwcs | lprint". +Details of the FITS header +world coordinate system interface can be found in the document +"World Coordinate Systems Representations Within the FITS Format" +by Hanisch and Wells, available from our anonymous ftp archive. + +.ih +EXAMPLES + +1. Register a radio image to an X-ray image of the same field using +a 100 point coordinate grid and a simple linear transformation. Both +images have accurate sky projection world coordinate systems. Print the +output world coordinates in the coords file in hh:mm:ss.ss and dd:mm:ss.s +format. Display the input and output image and blink them. + +.nf + cl> wregister radio xray radio.tran wxformat=%12.2H \ + wyformat=%12.1h + + cl> display radio 1 fi+ + + cl> display radio.tran 2 fi+ +.fi + +2. Repeat the previous command but begin with a higher order fit +and run the task in interactive mode in order to examine the fit +residuals. + +.nf + cl> wregister radio xray radio.tran wxformat=%12.2H \ + wyformat=%12.1h xxo=4 xyo=4 xxt=half yxo=4 yyo=4 \ + yxt=half inter+ + + ... a plot of the fit appears + + ... type x and r to examine the residuals of the x + surface fit versus x and y + + ... type y and s to examine the residuals of the y + surface fit versus x and y + + ... delete 2 deviant points with the d key and + recompute the fit with the f key + + ... type q to quit, save the fit, and compute the registered + image +.fi + +3. Mosaic a set of 9 images covering a ~ 1 degree field into a single image +centered at 12:32:53.1 +43:13:03. Set the output image scale to 0.5 +arc-seconds / pixel which is close the detector scale of 0.51 arc-seconds +per pixel. Set the orientation to be north up and east to the left. +The 9 images all have accurate world coordinate information in their headers. + +.nf + # Create a dummy reference image big enough to cover 1 square degree + + cl> mkpattern refimage ncols=7200 nlines=7200 ... + + # Give the dummy reference image the desired coordinate system + + cl> ccsetwcs refimage "" xref=3600.5 yref=3600.5 xmag=-0.5 \ + ymag=0.5 lngref=12:32:53.1 latref=43:13:03 ... + + # Register the images using constant boundary extension and + # set uservalue to some reasonable value outside the good data + # range. Note that it may be possible to improve performance by + #increasing nxblock and nyblock. + + cl> wregister @inlist refimage @outlist boundary=constant \ + constant=<uservalue> nxblock=7200 nyblock=1024 ... + + # Combine the images using imcombine + + cl> imcombine @outlist mosaic lthreshold=<uservalue> ... + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +imalign,xregister,tprecess,wcsxymatch,geomap,gregister,geotran,wcscopy +.endhelp diff --git a/pkg/images/immatch/doc/xregister.hlp b/pkg/images/immatch/doc/xregister.hlp new file mode 100644 index 00000000..b0690118 --- /dev/null +++ b/pkg/images/immatch/doc/xregister.hlp @@ -0,0 +1,707 @@ +.help xregister Dec98 images.immatch +.ih +NAME +xregister -- register 1 and 2D images using X-correlation techniques +.ih +USAGE +xregister input reference regions shifts +.ih +PARAMETERS +.ls input +The list of input images to be registered. +.le +.ls reference +The list of reference images to which the input images are to be registered. +The number of reference images must be one or equal to the number of input +images. +.le +.ls regions +The list of reference image region(s) used to compute the +x and y shifts. +\fIRegions\fR may be: 1) a list of one or more image sections +separated by whitespace, 2) the name of a text file containing a list +of one or more image sections separated by whitespace and/or newlines, +3) a string of the form "grid nx ny" defining a grid of nx by ny +equally spaced and sized image sections spanning the entire image. Shifts are +computed for each specified region individually and averaged to produce the +final x and y shift. +.le +.ls shifts +The name of the text file where the computed x and y shifts +are written. If \fIdatabasefmt\fR is "yes", a single record containing the +computed x and y shifts for each image region and the final average x and y +shift is written to a text database file for each input image. +If \fIdatabasefmt\fR = "no", a single line containing the image name and the +final average x and y shift is written to a simple text file +for each input image. +.le +.ls output = "" +The list of output shifted images. If \fIoutput\fR is the NULL string +then x and y shifts are computed for each input image and written to +\fIshifts\fR but no output images are written. If \fIoutput\fR is not NULL +then the number of output images must equal the number of input images. +.le +.ls databasefmt = yes +If \fIdatabasefmt\fR is "yes" the results are written to a text database +file, otherwise they are written to a simple text file. +.le +.ls records = "" +The list of records to be written to or read from \fIshifts\fR for each +input image. If \fIrecords\fR is NULL then the output or input record names +are assumed to be the names of the input images. If \fIrecords\fR is not NULL +then the record names in \fIrecords\fR are used to write / read the +records. This parameter is useful for users +who, wish to compute the x and y shifts using images that have been processed +in some manner (e.g. smoothed), but apply the computed x and y shifts to the +original unprocessed images. If more then one record +with the same name exists in \fIshifts\fR then the most recently written +record takes precedence. The records parameter is ignored if +\fIdatabasefmt\fR is "no". +.le +.ls append = yes +Append new records to an existing \fIshifts\fR file or start a new shifts +file for each execution of XREGISTER? The append parameter is ignored +if \fIdatabasefmt\fR is "no". +.le +.ls coords = "" +An optional list of coordinates files containing the x and y coordinates of +an object in the reference image on the first line and the x and y coordinates +of the same object in the input image(s) on succeeding lines. The number +of coordinate files must be equal to the number of reference images. +The input coordinates are used to compute initial +values for the x and y lags between the input image and the reference image, +and supersede any non-zero values of \fIxlag\fR, \fIylag\fR, \fIdxlag\fR, +and \fIdylag\fR supplied by the user. +.le +.ls xlag = 0, ylag = 0 +The initial x and y lags of the input image with respect to the reference +image. Positive values imply that the input image is shifted +in the direction of increasing x and y values with respect to the +reference image. \fIXlag\fR and \fIylag\fR are overridden if an offset +has been determined using the x and y coordinates in the \fIcoords\fR file. +.le +.ls dxlag = 0, dylag = 0 +The increment in \fIxlag\fR and \fIylag\fR to be applied to successive input +images. If \fIdxlag\fR and \fIdylag\fR are set to INDEF then the +computed x and y lags for the previous image are used as the initial +x and y lags for the current image. This option is useful for images which +were taken as a time sequence and whose x and y the shifts increase or +decrease in a systematic manner. +\fIDxlag\fR and \fIdylag\fR are overridden if an offset +has been determined using x and y coordinates in the \fIcoords\fR file. +.le +.ls background = none +The default background function to be subtracted from the input +and reference image data in each region before the +cross-correlation function is computed. The options are: +.ls none +no background subtraction is done. +.le +.ls mean +the mean of the reference and input image region is computed and subtracted +from the image data. +.le +.ls median +the median of the reference and input image region is computed and subtracted +from the data. +.le +.ls plane +a plane is fit to the reference and input image region and subtracted +from the data. +.le + +By default the cross-correlation function is computed in a manner +which removes the mean intensity in the reference and input image regions +from the data. For many data sets this "correction" is sufficient to +remove first order background level effects +from the computed cross-correlation function and no additional +background subtraction is required. +.le +.ls border = INDEF +The width of the border region around the input and reference image data +regions used to compute the background function if \fIbackground\fR +is not "none". By default the entire region is used. +.le +.ls loreject = INDEF, ls hireject = INDEF +The k-sigma rejection limits for removing the effects of bad data from the +background fit. +.le +.ls apodize = 0.0 +The fraction of the input and reference image data endpoints in x and y +to apodize with a +cosine bell function before the cross-correlation function is computed. +.le +.ls filter = none +The spatial filter to be applied to the reference and input image +data before the cross-correlation function is computed. The options are: +.ls none +no spatial filtering is performed. +.le +.ls laplace +a Laplacian filter is applied to the reference and input image data. +.le +.le +.ls correlation = discrete +The algorithm used to compute the cross-correlation function. The options +are: +.ls discrete +The cross-correlation function is calculated by computing the discrete +convolution of the reference and input image regions over the x and y +window of interest. This technique is most efficient method for small +cross-correlation function x and y search windows. +.le +.ls fourier +The cross-correlation function is calculated by computing the convolution +of the reference and input image regions using Fourier techniques. +This technique is the most efficient method for computing the +cross-correlation function for small x and y search windows. +.le +.ls difference +The cross-correlation function is calculated by computing the error +function of the reference and input images as a function of position +in the x and y search window. +.le +.ls file +No cross-correlation function is computed. Instead the previously +computed x and y shifts are read from record \fIrecord\fR in the text +database file \fIshifts\fR if \fIdatabasefmt\fR is "yes", or the +next line of a simple text file if \fIdatabasefmt\fR is "no". +.le +.le +.ls xwindow = 11, ywindow = 11 +The x and y width of the cross-correlation function region +to be computed and/or searched for peaks. The search window corresponds +to shifts of - xwindow / 2 <= xshift <= xwindow /2 and - ywindow / 2 <= +yshift <= ywindow / 2. \fIXwindow\fR and \fIywindow\fR +are automatically rounded up to the next nearest odd number. +.le +.ls function = centroid +The algorithm used to compute the x and y position of the cross-correlation +function peak. The options are: +.ls none +the position of the cross-correlation function peak is set to +x and y position of the maximum pixel. +.le +.ls centroid +the position of the cross-correlation function peak is calculated +by computing the intensity-weighted mean of the marginal profiles of +the cross-correlation function in x and y. +.le +.ls sawtooth +the position of the cross-correlation function peak is calculated +by convolving 1D slices in x and y through the cross-correlation function +with a 1D sawtooth function and using the point at which the peak is +bisected to determine the x and y position of the cross-correlation +peak. +.le +.ls parabolic +a 1D parabola is fit to 1D slices in x and y through the cross-correlation +function and the fitted coefficients are used to compute the peak of +the cross-correlation function. +.le +.ls mark +mark the peak of the cross-correlation function with the graphics cursor. +This option will only work if \fIinteractive\fR = "yes". +.le +.le +.ls xcbox = 5, ycbox = 5 +The width of the box centered on the peak of the cross-correlation function +used to compute the fractional pixel x and y center. +.le +.ls interp_type = "linear" +The interpolant type use to computed the output shifted image. +The choices are the following: +.ls nearest +nearest neighbor. +.le +.ls linear +bilinear interpolation in x and y. +.le +.ls poly3 +third order interior polynomial in x and y. +.le +.ls poly5 +fifth order interior polynomial in x and y. +.le +.ls spline3 +bicubic spline. +.le +.ls sinc +2D sinc interpolation. Users can specify the sinc interpolant width by +appending a width value to the interpolant string, e.g. sinc51 specifies +a 51 by 51 pixel wide sinc interpolant. The sinc width input by the +user will be rounded up to the nearest odd number. The default sinc width +is 31 by 31. +.le +.ls drizzle +2D drizzle resampling. Users can specify the drizzle pixel fractions in x and y +by appending values between 0.0 and 1.0 in square brackets to the +interpolant string, e.g. drizzle[0.5]. The default value is 1.0. The +value 0.0 is increased to 0.001. Drizzle resampling with a pixel fraction +of 1.0 in x and y is identical to bilinear interpolation. +.le +.le +.ls boundary_type = "nearest" +The boundary extension algorithm used to compute the output shifted +image. The choices are: +.ls nearest +use the value of the nearest boundary pixel. +.le +.ls constant +use a constant value. +.le +.ls reflect +generate a value by reflecting about the boundary. +.le +.ls wrap +generate a value by wrapping around to the opposite side of the image. +.le +.le +.ls constant = 0 +The default constant for constant boundary extension. +.le +.ls interactive = no +Compute the cross-correlation function and the shifts for each image +interactively using graphics cursor and optionally image cursor input. +.le +.ls verbose +Print messages about the progress of the task during task execution +in non-interactive mode. +.le +.ls graphics = "stdgraph" +The default graphics device. +.le +.ls display = "stdimage" +The default image display device. +.le +.ls gcommands = "" +The default graphics cursor. +.le +.ls icommands = "" +The default image display cursor. +.le + +.ih +DESCRIPTION + +XREGISTER computes the x and y shifts required to register a list of input +images \fIinput\fR to a list of reference images \fIreference\fR using +cross-correlation techniques. The computed x and y shifts are stored +in the text file \fIshifts\fR, in the records \fIrecords\fR if +\fIdatabasefmt\fR is "yes" or a single line of a simple text file +if \fIdatabasefmt\fR is "no". One entry is made in the shifts file for +each input image. If a non NULL list of output images +\fIoutput\fR is supplied a shifted output image is written for each input +image. XREGISTER is intended to solve 1D and 2D image registration problems +where the images have the same size, the same pixel scale, are shifted +relative to +each other by simple translations in x and y, and contain one or more +extended features in common that will produce a peak in the computed +cross-correlation function. + +The reference image regions used to compute the cross-correlation +function shifts are defined by the parameter +\fIregions\fR. \fIRegions\fR may be: +1) a list of one or more image sections, e.g. +"[100:200,100:200] [400:500,400:500]" separated +by whitespace, 2) the name of a text file containing a list of one or +more image sections separated by whitespace and / or newline characters, +or, 3) a string +of the form "grid nx ny" specifying a grid of nx by ny +image sections spanning the entire reference image. +All reference image regions should be chosen so as to +include at least one well-defined object or feature. Cross-correlation +functions and x and y shifts are computed independently for each +reference image region +and averaged to produce the final x and y shift for each input image. + +By default the initial x and y lags between the input and reference +image are assumed to by 0.0 and 0.0 +respectively and each reference image region is cross-correlated +with the identical region in the input image, e.g reference image +region [100:200,100:200] is cross-correlated with input image +region [100:200,100:200]. + +Non-zero initial guesses for +the x and y shifts for each input image can be input to XREGISTER using +the coordinates file parameter \fIcoords\fR. +\fICoords\fR is a simple text file containing the x +and y coordinates of a single +object in the reference image in columns one and two +of line one, and the x and y coordinates of the same object in the first +input image in columns one and two of line two, etc. If \fIcoords\fR +is defined there must be one coordinate file for every reference image. +If there are fewer lines of text in \fIcoords\fR than there are +numbers of reference plus input images, then x and y shifts of 0.0 are +assumed for the extra input images. For example, +if the user specifies a single input and reference image, sets the +\fIregions\fR parameter to "[100:200,100:200]", and defines +a coordinates file which contains the numbers +50.0 50.0 in columns one and two of line one, and the numbers 52.0 and 52.0 +in columns one and two of line two, then the initial x and y +lags for the input image with respect to the reference image will be 2.0 +and 2.0 respectively, and the reference image region [100:200,100:200] will be +cross-correlated with the input image region [102:202,102:202]. + +If \fIcoords\fR is NULL, the parameters \fIxlag\fR, \fIylag\fR, +\fIdxlag\fR, and \fIdylag\fR can be used to define initial x and y lags +for each input image. \fIXlag\fR and \fIylag\fR define the x and y lags +of the first input image with respect to the reference image. In the +example above they would be set to 2.0 and 2.0 respectively. Initial +shifts for succeeding images are computed by adding the values of the +\fIdxlag\fR and \fIdylag\fR parameters to the values of +\fIxlag\fR and \fIylag\fR assumed for the previous image. +If \fIdxlag\fR and \fIdylag\fR are 0.0 and 0.0 +the same initial x and y lag will be used for all the input +images. If \fIdxlag\fR and \fIdylag\fR are both finite numbers then these +numbers will be added to +the x and y lags assumed for the previous image. If these numbers +are both INDEF then the computed x and y lags for the previous image +will be used to compute the initial x and y lags for the current image. +Both options can be useful for time series images where the x and y +shifts between successive images display some regular behavior. + +Prior to computing the cross-correlation function +large mean background values and gradients should be removed +from the input and reference image data as either +can seriously degrade the peak of the cross-correlation +function. To first order XREGISTER computes the cross-correlation function +in a manner which removes +the effect of large mean background values from the resulting +function. For many if not most typical data sets the user can safely leave +the parameter \fIbackground\fR at its default value of "none" and +achieve reasonable results. For more demanding data sets the user should +experiment with the "mean", "median", and "plane" background fitting +algorithms which compute and subtract, the mean value, median value, and +a plane from the input and reference image data respectively, +before computing the +cross-correlation function. The region used to compute the background fitting +function can be restricted to a border around the reference and +input image regions by setting the \fIborder\fR parameter. Bad +data can be rejected from the background fit by setting the \fIloreject\fR +and \fIhireject\fR parameters. + +A cosine bell function can be applied to the edges of the input and +reference image data before +computing the cross-correlation function by setting the \fIapodize\fR +parameter. + +If the \fIfilter\fR parameter is set to "laplace" instead of its default +value of "none" then a Laplacian filter is applied to the input and +reference image data before the cross-correlation function is computed. +This spatial filtering operation effectively +removes both a background and a slope from the input and reference image +data and +highlights regions of the image where the intensity is changing rapidly. +The effectiveness of this filtering operation in sharpening the +correlation peak depends on the degree to +which the intensity in adjacent pixels is correlated. + +The cross-correlation function for each region is computed by +discrete convolution, \fIcorrelation\fR = "discrete", +Fourier convolution, \fIcorrelation\fR = "fourier", or by computing +the error function, \fIcorrelation\fR = "difference". The x and y lag +space in pixels around the initial x and y lag over which the cross-correlation +function is searched for the correlation peak, is specified by the +\fIxwindow\fR and +\fIywindow\fR parameters. These parameter define a range of x and y lags from +-xwindow / 2 to xwindow / 2 and -ywindow / 2 to ywindow / 2 respectively. For +a given input and reference image region, the +execution time of XREGISTER will depend strongly on both the correlation +algorithm chosen and +the size of the search window. In general users should use discrete +or difference correlation for small search windows and fourier +correlation for large search windows. + +The x and y lags for each input and reference image +region are computed by computing +the position of the peak of the cross-correlation function in the +search window using +one of the four centering algorithms: "none", "centroid", "sawtooth", +and "parabolic". + +The computed x and y shifts for each region and the final x and y shift +for each input image (where the computed x and y shifts are just the negative +of the computed x and y lags) are written to the shifts file \fIshifts\fR. +If \fIdatabasefmt\fR is "yes" each results is written in a record whose name +is either identical to the name of the input +image or supplied by the user via the \fIrecords\fR parameter . +If \fIdatabasefmt\fR is "no", then a single containing the input image +name and the computed x and y shifts is written to the output shifts file. + +If a list of output image names have been supplied then the x and y +shifts will be applied to the input images to compute the output images +using the interpolant type specified by \fIinterp_type\fR and the +boundary extension algorithm specified by \fIboundary\fR and \fIconstant\fR. + +If the \fIcorrelation\fR parameter is set to "file" then the shifts +computed in a previous run of XREGISTER will be read from the \fIshifts\fR +file and applied to the input images to compute the output images. +If no record list is supplied by the user XREGISTER will for each input +image search for +a record whose name is the same as the input image name. If more than +one record of the same name is found then the most recently written +record will be used. + +XREGISTER does not currently trim the input images but it computes and +prints the region over which they all overlap in the form of an image +section. Although XREGISTER is designed for use with same sized images, +it may be used with images of varying size. +In this case it is possible for the calculated overlap region to be vignetted, +as XREGISTER currently preserves the size of the input image when it shifts it. +For example if an image is much smaller than the reference image +it is possible for the image to be shifted outside of its own borders. +If the smallest image is used as a reference this will not occur. If +vignetting is detected the vignetted image section is printed on the +screen. Vignetting may also occur for a list of same-sized images +if the reference image is not included in the input image list, and the +computed shifts are all positive or negative as may occur in a time +sequence. Choosing a reference image with a shift which is in the +middle of the observed range of shifts in x and y will remove this problem. + +In non-interactive mode the parameters are set at task startup +and the input images are processed sequentially. If the \fIverbose\fR +flag is set messages about the progress of the task are printed on the +screen as the task is running. + +In interactive mode the user can mark the regions to be used +to compute the cross-correlation function on the image display, +define the initial shifts from the reference image to the input image +on the image display, show/set the data and algorithm parameters, +compute, recompute, and plot the cross-correlation function, experiment +with the various peak fitting algorithms, and overlay row and column +plots of the input and reference images with and without the initial and / or +computed shifts factored in. + +.ih +CURSOR COMMANDS + +The following graphics cursor commands are currently available in +XREGISTER. + + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +t Define the offset between the reference and the input image +c Draw a contour plot of the cross-correlation function +x Draw a column plot of the cross-correlation function +y Draw a line plot of the cross-correlation function +r Redraw the current plot +f Recompute the cross-correlation function +o Enter the image overlay plot submenu +w Update the task parameters +q Exit + + + Colon Commands + +:mark Mark regions on the display +:show Show the current values of the parameters + + Show/Set Parameters + +:reference [string] Show/set the current reference image name +:input [string] Show/set the current input image name +:regions [string] Show/set the regions list +:shifts {string] Show/set the shifts database file name +:coords [string] Show/set the current coordinates file name +:output [string] Show/set the current output image name +:records [string] Show/set the current database record name +:xlag [value] Show/set the initial lag in x +:ylag [value] Show/set the initial lag in y +:dxlag [value] Show/set the incremental lag in x +:dylag [value] Show/set the incremental lag in y +:cregion [value] Show/set the current region +:background [string] Show/set the background fitting function +:border [value] Show/set border region for background fitting +:loreject [value] Show/set low side k-sigma rejection +:hireject [value] Show/set high side k-sigma rejection +:apodize [value] Show/set percent of end points to apodize +:filter [string] Show/set the default spatial filter +:correlation [string] Show/set cross-correlation function +:xwindow [value] Show/set width of correlation window in x +:ywindow [value] Show/set width of correlation window in y +:function [string] Show/set correlation peak centering function +:xcbox [value] Show/set the centering box width in x +:ycbox [value] Show/set the centering box width in y +.fi + + +The following submenu of image cursor commands is also available. + +.nf + Image Overlay Plot Submenu + + +? Print help +c Overlay the marked column of the reference image + with the same column of the input image +l Overlay the marked line of the reference image + with the same line of the input image +x Overlay the marked column of the reference image + with the x and y lagged column of the input image +y Overlay the marked line of the reference image + with the x and y lagged line of the input image +v Overlay the marked column of the reference image + with the x and y shifted column of the input image +h Overlay the marked line of the reference image + with the x and y shifted line of the input image +q Quit + + + Image Overlay Sub-menu Colon Commands + +:c [m] [n] Overlay the middle [mth] column of the reference image + with the mth [nth] column of the input image +:l [m] [n] Overlay the middle [mth] line of the reference image + with the mth [nth] line of the input image +:x [m] Overlay the middle [mth] column of the reference image + with the x and y lagged column of the input image +:y [m] Overlay the middle [mth] line of the reference image + with the x and y lagged line of the input image +:v [m] Overlay the middle [mth] column of the reference image + with the x and y shifted column of the input image +:h [m] Overlay the middle [mth] line of the reference image + with the x and y shifted line of the input image +.fi + +.ih +ALGORITHMS + +The cross-correlation function is computed in the following manner. +The symbols I and R refer to the input and reference images respectively. + +.nf +correlation = discrete + + <I> = SUMj SUMi { I[i+xlag,j+ylag] } / (Nx * Ny) + <R> = SUMj SUMi { R[i,j] } / (Nx * Ny) + sumsqI = sqrt (SUMj SUMi { (I[i+xlag,j+ylag] - <I>) ** 2 }) + sumsqR = sqrt (SUMj SUMi { (R[i,j] - <R>) ** 2 }) + + X = SUMj SUMi { (I[i+xlag,j+ylag] - <I>) * (R[i,j] - <R>) } + ---------------------------------------------------- + sumsqI * sumsqR + + +correlation = fourier + + <I> = SUMj SUMi { I[i,j] } / (Nx * Ny) + <R> = SUMj SUMi { R[i,j] } / (Nx * Ny) + sumsqI = sqrt (SUMj SUMi { (I[i,j] - <I>) ** 2 }) + sumsqR = sqrt (SUMj SUMi { (R[i,j] - <R>) ** 2 }) + FFTI = FFT { (I - <I>) / sumsqI } + FFTR = FFT { (R - <R>) / sumsqR } + + X = FFTINV { FFTR * conj { FFTI } } + + +correlation = difference + + <I> = SUMj SUMi { I[i+xlag,j+ylag] } / (Nx * Ny) + <R> = SUMj SUMi { R[i,j] } / (Nx * Ny) + + X = SUMj SUMi { abs ((I[i+xlag,j+ylag] - <I>) - (R[i,j] - <R>)) } + X = 1.0 - X / max { X } +.fi + +.ih +EXAMPLES + +1. Register a list of images whose dimensions are all 256 by 256 pixels +and whose shifts with respect to the reference image are all less than +5.0 pixels, using the discrete cross-correlation algorithm and a search +window of 21 pixels in x and y. + +.nf + cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ + xwindow=21 ywindow=21 +.fi + +2. Register the previous list of images, but compute the cross_correlation +function using boxcar smoothed versions of the input images. + +.nf + cl> xregister @binimlist brefimage [*,*] shifts.db xwindow=21 \ + ywindow=21 + + cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ + records=@binimlist correlation=file +.fi + +3. Register the previous list of images but write the results to a simple +text file instead of a text database file and do the actual shifting with +the imshift task. + +.nf + cl> xregister @binimlist brefimage [*,*] shifts.db xwindow=21 \ + ywindow=21 databasefmt- + + cl> fields shifts.db 2,3 > shifts + + cl> imshift @inimlist @outimlist shifts_file=shifts +.fi + +4. Register list of 512 by 512 pixel square solar sunspot images that were +observed as a time series. Compute the cross-correlation function using +Fourier techniques, a search window of 21 pixels in x and y, an initial +shift of 10 pixels in x and 1 pixel in y, and use the computed shift of +the previous image as the initial guess for the current image. + +.nf + cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ + xlag=10 ylag=1 dxlag=INDEF dylag=INDEF correlation=fourier \ + xwindow=21 ywindow=21 +.fi + +5. Register two 2K square images interactively using discrete cross-correlation +and an initial search window of 15 pixels in x and y. + +.nf + cl> display refimage + + cl> xregister inimage refimage [900:1100,900:1100] shifts.db \ + xwindow=15 ywindow=15 interactive+ + + ... a contour plot of the cross-correlation function appears + with the graphics cursor ready to accept commands + + ... type x and y to get line and column plots of the cross- + correlation function at various points and c to return + to the default contour plot + + ... type ? to get a list of the available commands + + ... type :mark to mark a new region on the image display + + ... type f to recompute the cross-correlation function using + the new data + + ... increase the search window to 21 pixels in x and y + with the :xwindow 21 and :ywindow 21 commands + + ... type f to recompute the cross-correlation function with the + new search window + + ... type o to enter the image data overlay plot submenu, + move the cursor to a line in the displayed reference image + and type l to see of plot of the line in the input and + reference image, type h to see a plot of the same line in + the reference image and the x and y shifted line in the input + image, type q to return to the main menu + + ... type q to quit the task, and q again to verify the previous + q command +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +rv.fxcor,proto.imalign,images.imcombine,ctio.immatch,center1d,images.imshift +.endhelp diff --git a/pkg/images/immatch/doc/xyxymatch.hlp b/pkg/images/immatch/doc/xyxymatch.hlp new file mode 100644 index 00000000..82a8c8bb --- /dev/null +++ b/pkg/images/immatch/doc/xyxymatch.hlp @@ -0,0 +1,468 @@ +.help xyxymatch Jul95 images.immatch +.ih +NAME +xyxymatch -- Match pixel coordinate lists using various methods +.ih +USAGE +xyxymatch input reference output tolerance +.ih +PARAMETERS +.ls input +The list of input coordinate files. The input file is a whitespace-delimited +text table containing the coordinates. The \fIxcolumn\fR and \fIycolumn\fR +parameters define the coordinate columns to be used. +.le +.ls reference +The list of reference coordinate files. The number of reference coordinate +files must be one or equal to the number of input coordinate files. +The reference file is a whitespace-delimited +text table containing the coordinates. The \fIxrcolumn\fR and \fIyrcolumn\fR +parameters define the coordinate columns to be used. +.le +.ls output +The output matched x-y lists containing three pairs of numbers: the coordinates +of the object in the reference list in columns 1 and 2, the +coordinates of the object in the input list in columns 3 and 4, and +the line number of the objects in the original reference and input +lists in columns 5 and 6. +.le +.ls tolerance +The matching tolerance in pixels. +.le +.ls refpoints = "" +The list of tie points used to compute the linear transformation +from the input coordinate system to the reference coordinate system. Refpoints +is a text file containing the x-y coordinates of 1-3 reference list tie points +in the first line, followed by the x-y coordinates of the 1-3 corresponding +input tie points in succeeding +lines. If refpoints is undefined then the parameters \fIxin\fR, \fIyin\fR, +\fIxmag\fR, \fIymag\fR, \fIxrotation\fR, \fIyrotataion\fR, \fIxref\fR, +and \fIyref\fR are used to compute the linear transformation from the +input coordinate system to the reference coordinate system. +.le +.ls xin = INDEF, yin = INDEF +The x and y origin of the input coordinate system. Xin and yin default to +0.0 and 0.0 respectively. +.le +.ls xmag = INDEF, ymag = INDEF +The x and y scale factors in reference pixels per input pixels. Xmag and +ymag default to 1.0 and 1.0 respectively. +.le +.ls xrotation = INDEF, yrotation = INDEF +The x and y rotation angles measured in degrees counter-clockwise with +respect to the x axis. Xrotation and yrotation default to 0.0 and 0.0 +respectively. +.le +.ls xref = INDEF, yref = INDEF +The x and y origin of the reference coordinate system. Xref and yref default +to 0.0 and 0.0 respectively. +.le +.ls xcolumn = 1, ycolumn = 2 +The columns in the input coordinate list containing the x and y coordinate +values respectively. +.le +.ls xrcolumn = 1, yrcolumn = 2 +The columns in the reference coordinate list containing the x and y coordinate +values respectively. +.le +.ls separation = 9.0 +The minimum separation for objects in the input and reference coordinate +lists. Objects closer together than separation pixels +are removed from the input and reference coordinate lists prior to matching. +.le +.ls matching = "triangles" +The matching algorithm. The choices are: +.ls tolerance +A linear transformation is applied to the input coordinate list, +the transformed input list and the reference list are sorted, +points which are too close together are removed, and the input coordinates +which most closely match the reference coordinates within the +user specified tolerance are determined. The tolerance algorithm requires +an initial estimate for the linear transformation. This estimate can be +derived interactively by pointing to common objects in the two displayed +images, by supplying the coordinates of tie points via the +\fIrefpoints\fR file, or by setting the linear transformation parameters +\fIxin\fR, \fIyin\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, +\fIyrotation\fR, \fIxref\fR, and \fIyref\fR. Assuming that +well chosen tie points are supplied, the tolerance algorithm +functions well in the presence of any shifts, axis flips, x and y +scale changes, rotations, and axis skew, between the two coordinate +systems. The algorithm is sensitive to higher order distortion terms +in the coordinate transformation. +.le +.ls triangles +A linear transformation is applied to the input coordinate list, +the transformed input list and the reference list are sorted, points +which are too close together are removed, and the input coordinates +are matched to the reference coordinates using a triangle pattern +matching technique and the user specified tolerance parameter. +The triangles pattern matching algorithm does not require prior knowledge +of the linear transformation, although it will use one if one is supplied. +The algorithm functions well in the presence of +any shifts, axis flips, magnification, and rotation between the two coordinate +systems as long as both lists have a reasonable number of objects +in common and the errors in the computed coordinates are small. +However since the algorithm depends on comparisons of similar triangles, it +is sensitive to differences in the x and y coordinate scales, +any skew between the x and y axes, and higher order distortion terms +in the coordinate transformation. +.le +.le +.ls nmatch = 30 +The maximum number of reference and input coordinates used +by the "triangles" pattern matching algorithm. If either list contains +more coordinates than nmatch the lists are subsampled. Nmatch should be +kept small as the computation and memory requirements of the "triangles" +algorithm depend on a high power of the lengths of the respective lists. +.le +.ls ratio = 10.0 +The maximum ratio of the longest to shortest side of the +triangles generated by the "triangles" pattern matching algorithm. +Triangles with computed longest to shortest side ratios > ratio +are rejected from the pattern matching algorithm. \fIratio\fR should never +be set higher than 10.0 but may be set as low as 5.0. +.le +.ls nreject = 10 +The maximum number of rejection iterations for the "triangles" pattern +matching algorithm. +.le +.ls xformat = "%13.3f", yformat = "%13.3f" +The format of the output reference and input x and y coordinates. +By default the coordinates are output right justified in a field of +13 characters with 3 places following the decimal point. +.le +.ls interactive = no +Compute the initial linear transformation required to transform the +input coordinate coordinates to the reference coordinate system, by defining +up to three tie points using the image display and the image cursor. +.le +.ls verbose = yes +Print messages about the progress of the task ? +.le +.ls icommands = "" +The image display cursor. +.le + +.ih +DESCRIPTION + +XYXYMATCH matches the x and y coordinates in the reference coordinate list +\fIreference\fR to the corresponding x and y coordinates in the input +coordinate list \fIinput\fR to within a user specified tolerance +\fItolerance\fR, and writes the matched coordinates to the output +file \fIoutput\fR. The output file is suitable for input to the +GEOMAP task which computes the actual transformation required to +register the corresponding reference and input images. + +XYXYMATCH matches the coordinate lists by: 1) computing an initial +guess at the linear transformation required to match the input +coordinate system to the reference coordinate system, 2) applying +the computed transformation to the input coordinates, 3) sorting +the reference and input coordinates and removing points with a +minimum separation specified by the parameter \fIseparation\fR +from both lists, 4) matching the two lists using either the "tolerance" +or "triangles" algorithm, and 5) writing the matched list to the +output file. + +The initial estimate of the linear transformation is computed in one of +three ways. If \fIinteractive\fR is "yes" the user displays the reference and +input images corresponding to the reference and input coordinate files +on the image display, and marks up to three objects which the two +images have in common with the image cursor. The coordinates of these +tie points are used as tie points to compute the linear transformation. +If \fIrefpoints\fR is defined, the x-y coordinates of up to three tie +points are read from succeeding lines in the refpoints file. The format +of two sample refpoints files is shown below. + +.nf +# First sample refpoints file (1 reference file and N input files) + +x1 y1 [x2 y2 [x3 y3]] # tie points for reference coordinate file +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file 1 +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file 2 +... +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file N + + +# Second sample refpoints file (N reference files and N input files) + +x1 y1 [x2 y2 [x3 y3]] # tie points for reference coordinate file 1 +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file 1 +x1 y1 [x2 y2 [x3 y3]] # tie points for reference coordinate file 2 +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file 2 +... +x1 y1 [x2 y2 [x3 y3]] # tie points for reference coordinate file N +x1 y1 [x2 y2 [x3 y3]] # tie points for input coordinate file N + +.fi + +The coordinates of the tie points can be typed in by hand if \fIrefpoints\fR +is "STDIN". If the refpoints file is undefined the parameters +\fIxin\fR, \fIxin\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, \fIyrotation\fR, +\fIxref\fR, and \fIyref\fR are used to compute the linear transformation +from the input coordinates [xi,yi] to the reference coordinates [xr,yr] +as shown below. Orientation and skew are the orientation of the x and y axes +and their deviation from non-perpendicularity respectively. + +.nf + xr = a + b * xi + c * yi + yr = d + e * xi + f * yi + + xrotation = orientation - skew / 2 + yrotation = orientation + skew / 2 + b = xmag * cos (xrotation) + c = -ymag * sin (yrotation) + e = xmag * sin (xrotation) + f = ymag * cos (yrotation) + a = xref - b * xin - c * yin = xshift + d = yref - e * xin - f * yin = yshift +.fi + +The reference and input coordinates are read from columns \fIxrcolumn\fR, +\fIyrcolumn\fR in the reference, and \fIxcolumn\fR, and \fIycolumn\fR in the +input coordinate lists respectively. The input coordinates are transformed +using the computed linear transformation and stars closer together than +\fIseparation\fR pixels are removed from both lists. + +The coordinate lists are matched using the algorithm specified by +the \fImatching\fR +parameter. If matching is "tolerance", XYXYMATCH searches the sorted +transformed input coordinate list for the object closest to the current +reference object within the matching tolerance \fItolerance\fR. +The major advantage of the "tolerance" algorithm is that it can deal +with x and y scale differences and axis skew in the coordinate +transformation. The major disadvantage is that the user must supply +tie point information in all but the simplest case of small x and y +shifts between the input and reference coordinate systems. + +If matching is "triangles" XYXYMATCH constructs a list of triangles +using up to \fInmatch\fR reference coordinates and transformed input +coordinates, and performs a pattern matching operation on the resulting +triangle lists. If the number of coordinates +in both lists is less than \fInmatch\fR the entire list is matched using +the "triangles" algorithm directly, otherwise the "triangles" algorithm +is used to estimate a new linear transformation, the input coordinate +list is transformed using the new transformation, and the entire list +is matched using the "tolerance" algorithm. The major advantage of the +"triangles" algorithm is that it requires no tie point information +from the user. The major disadvantages are that it is sensitive to +x and y scale differences and axis skews between the input and reference +coordinate systems and can be computationally expensive. + +The matched x and y reference and input coordinate lists are written to +columns 1 and 2, and 3 and 4 of the output file respectively, in a format +specified by the \fIxformat\fR and \fIyformat\fR parameters. +The respective line numbers in the original reference and input +coordinate files are written to columns 5 and 6 respectively. + +If \fIverbose\fR is yes, detailed messages about actions taken by the +task are written to the terminal as the task executes. + +.ih +ALGORITHMS + +The "triangles" algorithm uses a sophisticated pattern matching +technique which requires no tie point information from the user. +It is expensive computationally and hence is restricted to a maximum +of \fInmatch\fR objects from the reference and input coordinate lists. + +The "triangles" algorithm first generates a list +of all the possible triangles that can be formed from the points in each list. +For a list of nmatch points this number is the combinatorial factor +nmatch! / [(nmatch-3)! * 3!] or nmatch * (nmatch-1) * (nmatch-2) / 6. +The length of the perimeter, ratio of longest to shortest side, cosine +of the angle between the longest and shortest side, the tolerances in +the latter two quantities and the direction of the arrangement of the vertices +of each triangle are computed and stored in a table. +Triangles with vertices closer together than \fItolerance\fR or +with a ratio of the longest to shortest side greater than \fIratio\fR +are discarded. The remaining triangles are sorted in order of increasing +ratio. A sort merge algorithm is used to match the triangles using the +ratio and cosine information, the tolerances in these quantities, and +the maximum tolerances for both lists. Next the ratios of the +perimeters of the matched triangles are compared to the average ratio +for the entire list, and triangles which deviate too widely from the mean +are discarded. The number of triangles remaining are divided into +the number which match in the clockwise sense and the number which match +in the counter-clockwise sense. Those in the minority category +are eliminated. +The rejection step can be repeated up to \fInreject\fR times or until +no more rejections occur whichever comes first. +The last step in the algorithm is a voting procedure in which each remaining +matched triangle casts three votes, one for each matched pair of vertices. +Points which have fewer than half the maximum number of +votes are discarded. The final set of matches are written to the output file. + +The "triangles" algorithm functions well when the reference and +input coordinate lists have a sufficient number of objects (~50%, +in some cases as low as 25%) of their objects in common, any distortions +including x and y scale differences and skew between the two systems are small, +and the random errors in the coordinates are small. Increasing the value of the +\fItolerance\fR parameter will increase the ability to deal with distortions but +will also produce more false matches. + +.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 +REFERENCES + +A detailed description of the "triangles" pattern matching algorithm used here +can be found in the article "A Pattern-Matching Algorithm for Two- +Dimensional Coordinate Lists" by E.J. Groth, A.J. 91, 1244 (1986). + +.ih +EXAMPLES + +1. Match the coordinate list of an image to the coordinate list of a reference +image using the triangles matching algorithm and a tolerance of 3 pixels. +Use the resulting matched list to compute the transformation +required to register the input image lpix to the reference image. +For completeness this example demonstrates how the individual input +and reference coordinate lists can be generated. + +.nf + cl> imlintran dev$pix[-*,*] lpix xrot=15 yrot=15 xmag=1.2 \ + ymag=1.2 xin=INDEF yin=INDEF xref=265.0 yref=265.0 \ + ncols=INDEF nlines=INDEF + + cl> daofind dev$pix fwhm=2.5 sigma=5.0 threshold=100.0 + cl> daofind lpix fwhm=2.5 sigma=5.0 threshold=100.0 + + cl> xyxymatch lpix.coo.1 pix.coo.1 xymatch toler=3 \ + matching=triangles + + cl> geomap xymatch geodb 1.0 512.0 1.0 512.0 +.fi + +2. Match the coordinate lists above using the tolerance matching algorithm +and the image display and cursor. + +.nf + cl> display dev$pix 1 fi+ + cl> display lpix 2 fi+ + + cl> xyxymatch lpix.coo.1 pix.coo.1 xymatch toler=3 \ + matching=tolerance interactive+ + + ... Mark three points in the reference image dev$pix + ... Mark three points in the input image lpix + + cl> geomap xymatch geodb 1.0 512.0 1.0 512.0 +.fi + +3. Repeat example 2 but run xyxymatch non-interactively by setting the +appropriate linear transformation parameters rather than marking stars +on the image display. + +.nf + cl> ... + + cl> xyxymatch lpix.coo.1 pix.coo.1 xymatch toler=3 \ + matching=tolerance xmag=1.2 ymag=1.2 xrot=165 \ + yrot=345 xref=646.10 yref=33.38 + + cl> geomap xymatch geodb 1.0 512.0 1.0 512.0 +.fi + +4. Repeat example 2 but run xyxymatch non-interactively +inputting the appropriate linear transformation via a list of tie points +rather than marking stars on the image display or creating a refpoints +file. + +.nf + cl> ... + + cl> type refpts + 442.0 409.0 380.0 66.0 69.0 460.0 + 82.0 347.0 207.0 84.0 371.0 469.0 + + cl> xyxymatch lpix.coo.1 pix.coo.1 xymatch toler=3 \ + refpoints=refpts matching=tolerance + + cl> geomap xymatch geodb 1.0 512.0 1.0 512.0 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +daophot.daofind,lintran,imlintran,geomap,register,geotran +.endhelp |