EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

## NAME

psfmatch -- match the point spread functions of 1 and 2D images

## USAGE

`psfmatch input reference psfdata kernel `

## PARAMETERS

- input
- The list of input images to be matched.

- reference
- The list of reference images to which the input images are to be matched if
*convolution*= "image", or the list of reference image psfs if*convolution*= "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.

- psfdata
- The list of objects used to compute the psf matching function if
*convolution*is "image", or the list of input image psfs if*convolution*is "psf". In the former case*psfdata*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.

- 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.

- output = ""
- The list of output matched images. If
*output*is the NULL string then the psf matching function is computed for each input image and written to*kernel*but no output images are written. If*output*is not NULL then the number of output images must equal the number of input images.

- convolution = "image"
- The algorithm used to compute the psf matching function. The options are:
- image
- The psf matching function is computed directly from the reference and input
image data using the objects specified in
*psfdata*, the data regions specified by*dnx*,*dny*,*pnx*, and*pny*, and the convolution theorem.

- psf
- The psf matching function is computed directly from pre-computed reference and input image psfs using the convolution theorem.

- kernel
- No psf matching function is computed. Instead the psf matching function
is read from the input image
*kernel*.

- 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.
*Dnx*and*dny*are not used if*convolution*is "psf" or "kernel".

- pnx = 15, pny = 15
- The x and y width of the psf matching function to be computed which must be
less than
*dnx*and*dny*respectively. The psf matching function should be kept as small as possible to minimize the time required to compute the output image.*Pnx*and*Pny*are not used if*convolution*is "psf" or "kernel".

- center = yes
- Center the objects in
*psfdata*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*convolution*is "psf" or "kernel".

- 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
*dnx*and*dny*but outside the kernel region defined by*pnx*and*pny*. Background fitting is turned off if*convolution*is "psf" or "kernel". The options are:- none
- no background subtraction is done.

- "insky refsky"
- the numerical values of insky and refsky are subtracted from the input and reference image respectively.

- mean
- the mean of the input and reference image region is computed and subtracted from the image data.

- median
- the median of the input and reference image region is computed and subtracted from the data.

- plane
- a plane is fit to the input and reference image region and subtracted from the data.

- loreject = INDEF, ls hireject = INDEF
- The k-sigma rejection limits for removing the effects of bad data from the background fit.

- 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
*convolution*is "psf" or "kernel".

- fluxratio = INDEF
- The ratio of the integrated flux of the reference objects to the integrated
flux of the input objects.
By default
*fluxratio*is computed directly from the input data.

- filter = "replace"
- The filter used to remove high frequency noise from the psf
matching function. Filtering is not performed if
*convolution*is "kernel". The options are:- cosbell
- apply a cosine bell taper to the psf matching function in frequency space.

- 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.

- 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.

- sx= 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.

- radsym = no
- Compute a radially symmetric cosine bell function ?

- threshold = 0.2
- The low frequency cutoff in fraction of the total input image spectrum power for the filtering options "replace" and "model".

- normfactor = 1.0
- The total power in the computed psf matching function
*kernel*. By default the psf matching function is normalized. If*normfactor*is set to INDEF, then the total power is set to*fluxratio*.*Normfactor*is not used if*convolution*is set "kernel".

- boundary_type = "nearest"
- The boundary extension algorithm used to compute the output matched
image. The options are:
- nearest
- use the value of the nearest boundary pixel.

- constant
- use a constant value.

- reflect
- generate a value by reflecting about the boundary.

- wrap
- generate a value by wrapping around to the opposite side of the image.

- constant = 0.0
- The default constant for constant boundary extension.

- interactive = no
- Compute the psf matching function for each image interactively using graphics cursor and, optionally, image cursor input.

- verbose
- Print messages about the progress of the task in non-interactive mode.

- graphics = "stdgraph"
- The default graphics device.

- display = "stdimage"
- The default image display device.

- gcommands = ""
- The default graphics cursor.

- icommands = ""
- The default image display cursor.

## DESCRIPTION

PSFMATCH computes the convolution kernel required to match the
point-spread functions
of the input images *input*
to the point-spread functions of
the reference images *reference*
using either the image data
or pre-computed psfs and the convolution theorem.
The computed psf matching functions are stored in the *kernel*
images.
If a non-NULL list of output images *output*
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 *convolution*
= "image", the matching function is computed directly
from the input and reference image data using the objects listed in
*psfdata*
and the convolution theorem as described in the ALGORITHMS
section. *psfdata*
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 *dnx*
by *dny*
, and the size of the kernel to be computed *pnx*
and
*pny*
, 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 *center*
is "yes" and *convolution*
is "image", the objects
in *psfdata*
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 *background*
fitting algorithm is other than "none" and
*convolution*
is "image", the background for each object is fit using
data inside the region defined by
*dnx*
and *dny*
but outside the region defined by
*pnx*
by *pny*
. Bad data can be removed from the
background fit by setting the parameters *loreject*
and *hireject*
.
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 *apodize*
parameter is > 0.0.

If *psfdata*
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 *convolution*
= "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 *psfdata*
is the list of input image psfs and
*reference*
are the corresponding reference image psfs written by
by some external psf modeling task.
If *convolution*
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 *fluxratio*
is INDEF, PSFMATCH
estimates this number internally as described in the ALGORITHMS section,
otherwise the *fluxratio*
is set to the value supplied by the user.

If *convolution*
is "kernel", PSFMATCH reads the psf matching function
from the the images in *kernel*
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 *filter*
is set to "cosbell", a cosine bell function
with a taper defined by *sx1*
, *sx2*
, *sy1*
, and *sy2*
and
symmetry defined by radsym is applied to
the the psf matching function in frequency space. This filter
sets all the frequency components greater than *sx2*
and *sy2*
to 0.0 and leaves all frequency components inside *sx1*
and *sy1*
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 *filter*
is set to "replace", those high frequency components
of the matching function which have less than a fraction
*threshold*
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 *filter*
= "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 *normfactor*
is set to
a number of INDEF, the total power of the psf matching function will be
set to that value of *fluxratio*
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 *boundary*
and *constant*
.

In non-interactive mode the parameters are set at task startup time and
the input images are processed sequentially. If the *verbose*
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.

## CURSOR COMMANDS

The following graphics cursor commands are currently available in PSFMATCH.

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

## ALGORITHMS

The problem of computing the 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.

r = ak * d R = FT (r) I = FT (i) aK = R / I ak = FT (aK)

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.

aK[0,0] = a = sum(r) / sum(i)

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.

a = amplitude (R) / amplitude (I) = (sum(r) - sum(skyr)) / (sum(i) - sum(skyi)) aK[0,0] = a

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

ak = FT (aK)

PSFMATCH actually computes

ak' = FT (aKF) = ak * f

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:

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

## 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.

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"

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.

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"

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.

cl> psfmatch inimage refpsf inpsf kernel convolution=psf cl> fconvolve inimage kernel outimage

4. Psf match two images interactively using the image data itself to compute the psf matching function.

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

## TIME REQUIREMENTS

## BUGS

## SEE ALSO

convolve, gauss, stsdas.fconvolve, digiphot.daophot.psf