NAME
peak - peak measurements
SYNOPSIS
peak [options] image.fits
DESCRIPTION
peak detects localizes bright object centroids in an image.
It takes as argument a list of FITS cube names and outputs
on stdout the center of each detected bright zone, an esti-
mation of FWHM in x and y, an average FWHM, a flux estima-
tion, and the minimum and maximum pixel values around each
object.
Two different detection method can be used with the peak
command: the 'kappa-sigma' method (default) or the 'squares'
method (use the -m (--method) option to choose).
With the 'kappa-sigma' method, bright objects are detected
if and only if they contain a peak of sufficient amplitude
i.e. more than K deviations above the median image value,
AND if they cover a surface at least of 3x3 pixels. To
detect peaks located in a window smaller than 3x3, there is
an option to smear out the image by a low-pass filter before
applying peak detection, but of course it has associated
drawbacks. By default, peak will be looking at all the sig-
nal which is more than 2 deviations above the median pixel
value. This value can be changed using the -k (or --kappa)
option. Notice that this is not more than kappa-sigma clip-
ping for signal detection, except that to avoid mis-
estimation of the mean and sigma in crowded fields, the
measurements are done with the median and a deviation which
is the average absolute distance to the median.
In the 'square' method, a standard deviation filter is apply
to the image, which has the effect to make the bright points
appear like squares. This squares image is then used as a
mask to detect objects.
In spite of calls to morphological filters, peak is surpris-
ingly faster than other usual algorithms. It should be used
as a peak position estimator more than a precise locator,
though.
ALGORITHMS
Kappa-sigma method
If smearing is activated, the input image is smeared out
with a low-pass 5x5 filter before detection is applied. This
filtered version of the input image is only used for detec-
tion purposes, and not for any kind of later measurement.
A binary map is first created of all pixel positions which
have a value above a given threshold (by default, median
plus 2 deviations).
A binary morphological erosion, and a dilation are then per-
formed on the binary map to close all regions smaller than
3x3, which removes all isolated bad pixels. If smearing was
applied, small objects would have been enlarged to bigger
than 3x3 and appear in the resulting pixel map.
A floodfill algorithm is applied to find the geometric
center of all white blobs, weighted by pixel values taken
from the original image.
Squares method
A standard deviation filter is applied to the image which
make the bright objects appaear like bright squares. This
bright squares image is then binarized and used as a mask to
identify zones where the objects are in the original image.
A morphological closing is then applied, and the remaining
objects are registered.
For both methods, if fine positioning is activated (-f or
--finepos option), a subsequent process is called, which
requests 3 user-defined radiuses in pixels: r1, r2, and r3.
For each found peak position in the image, a background is
computed as the median pixel value in the ring centered on
the estimated peak position, of radiuses r2 and r3. Then a
barycenter is computed within the disk centered on the same
spot, of radius r1, using background-subtracted pixel values
as weights. This fine positioning method proves quite reli-
able, but requires all peaks in the image to have more or
less the same size to fit into the circles defined by r1,
r2, r3.
OPTIONS
-m clip or --method
Use 'kappa-sigma' detection method.
-m squares or --method
Use 'squares' detection method.
-k cut or --kappa cut
To be used for 'kappa-sigma' method. Use this option
to change the cut level in a factor of deviations. The
lower this value, the more bright zones may be
detected. The higher this factor is, the less detected
peaks. The default of 2.0 seems to work fine on images
having a high Signal to Noise Ratios.
-s or --smear
This option (low-pass filter) applies a 5x5 convolution
with a flat kernel before trying to detect objects. The
smearing is h.PPful to detect objects which are smaller
than a 3x3 window. It increases the number of detec-
tions, but also the number of false detections. Bad
pixels, for example, are smeared out to a 5x5 window
and detected as proper peaks. Another issue is that 2
close peaks will be smeared out to a single one. Most
probably, the returned result will be a barycenter of
the 2 regions instead of the 2 expected centers.
Because the smearing will lower the signal in all
regions, the default sigma cut is halved when this
options is used.
-S or --sqhsize 'hx hy'
To be used for 'squares' method. Define the size of
the standard deviation filter applied to generate the
squares image. The bigger the filter is, the bigger the
squares are.
-f 'r1 r2 r3' or --fpos 'r1 r2 r3'
Fine positioning: provide three values r1 < r2 < r3.
The radiuses r2 and r3 specify a ring around each
detected point, from which an estimation of the back-
ground is computed. A barycenter is then computed in
the disk of radius r1, using background-subtracted
pixel values as weights. No defaults are given to these
parameters.
Be aware when using this position refining that it
assumes the following conditions.
All peaks are isolated, i.e. the closest distance between 2
peaks is strictly greater than 2 * r3.
There is a background zone around every peak, always within
the disk defined by r2 and r3. Otherwise, the background
estimation is contaminated with peak signals.
All peaks are contained in a disk of radius r1.
-F or --fwhm
Flag to print out the fhwm for detected objects.
-P or --phot 'r1 r2 r3'
Provides the radiuses used to compute photometry.
-d or --rtd
Flag to display detected objects in rtd.
BUGS
Peaks located on an image edge will not be detected.