diff options
Diffstat (limited to 'pkg/images/immatch/doc/psfmatch.hlp')
| -rw-r--r-- | pkg/images/immatch/doc/psfmatch.hlp | 595 |
1 files changed, 595 insertions, 0 deletions
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 |