STScI Logo

psfmatch images.immatch


NAME · USAGE · PARAMETERS · DESCRIPTION · CURSOR_COMMANDS · ALGORITHMS
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


Source Code · Search Form · STSDAS