Name
findobjs - detection and stats of bright objects in an
image
Synopsis
findobjs [options] <list of FITS files...>
Description
findobjs detects and localizes bright objects in a given
set of images. It takes in argument a list of FITS files
and prints out for each input image a list of objects with
their key statistics.
findobjs can also be used to produce binary maps of the
detected signals, and labelized maps (each detected zone
is affected a unique ID).
findobjs supersedes detpeak, fwhm, photfits.
Algorithm
The following steps are performed:
1. smearing (optional)
2. thresholding
3. morphological closure (can be cancelled)
4. labelization
5. key gray-level statistics calculation
5. fine-positioning (optional)
6. photometry calculation (optional)
Smearing can be applied to the initial image to spread out
very localized peaks, to increase detectability.
The second step is to threshold the input image between
background and signal. The method offered here is a kappa-
sigma clipping with a threshold K (default is 2.0). The
mean of the image is actually estimated by the median
pixel value, and the standard deviation is estimated by
the absolute average distance to this median value. All
pixels above M+SK are retained as "signal", the others are
"background".
Since bad pixels and other detector defects will also be
found by this thresholding, an optional morphological clo-
sure (erosion+dilatation) can be performed to close all
zones smaller than a structural element. The structural
element is a square 3x3 pixel zone. All objects strictly
smaller than the structural element will disappear.
A binary map of the zones found by this thresholding +
optional closure can be dumped to disk upon user request.
Labelization is then applied to this binary map to iden-
tify each zone with a unique ID. An image of these labels
can be dumped to disk upon user request.
Next step is then to perform a series of statistical mea-
surements on each zone. The following parameters are cal-
culated:
o A label ID. Number 0 is the background, number 1 is
reserved for all unclassified zones (not used). Thus the
first object of interest is number 2 and henceforth.
o Number of pixels in the zone
o Min, max, average, standard deviation and total inten-
sity of the zone
o Barycenter of the zone (weighted by pixel values)
o FWHM (if computable, -1.0=n/a)
o fixed aperture photometry (optional).
Barycenter computation can be optionally refined with fine
positioning, but needs then three radius values r1<r2<r3.
(r2,r3) specify a ring around each detected object, from
which an estimation of the background is computed. A
barycenter is then computed in the disk of radius r1,
using background-subtracted pixel values as weights. Fine
positioning assumes that:
- All peaks are isolated, i.e. the closest distance
between 2 peaks is strictly greater than 2*r3, otherwise
some objects would contaminate the background estimation
for other objects.
- There is a backround zone around every peak, always
within the disk defined by (r2,r3), which is not an
extended object but a true background.
- All peaks are contained within a disk of radius r1.
If the computed FWHM is perturbed (e.g. blended objects)
or does not make sense, the value printed out is -1.
Fixed aperture photometry is also computed for peaks if
three radii r1,r2,r3 are provided. Again, (r2,r3) define a
crown into which the background is estimated, and r1 a
disk into which the background-subtracted flux is accumu-
lated. Same assumptions as for fine positioning apply
here. The provided radii need not be the same as the ones
for fine positioning.
Options
-s/--sigmacut
sets the threshold for kappa-sigma thresholding.
The lower this value, the more bright zones are
detected. The higher this factor the less detected
peaks. The default of 2.0 seems to work fine on
images having a high Signal to Noise Ratio.
-f `r1 r2 r3' or --finepos `r1 r2 r3'
Use fine positioning. The user must provide three
values r1 < r2 < r3. The radii r2 and r3 specify a
ring around each detected point, from which an
estimation of the background 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.
-p `r1 r2 r3' or --photo `r1 r2 r3'
Compute photometry. The flux is computed as the sum
of all pixel values found within the r1 disk
(including the border). If a background had been
estimated per pixel, it is then subtracted from
each pixel before accumulation. If no background
computation is requested it is assumed having value
0.
-b Estimate background for photometry computation.
For background estimation, 2 methods are offered.
In both cases, a list of all pixels found to be in
the ring is first constructed. The difference
between the average (default) and the median (-m
option) is the following:
In the case of an average estimation, the back-
ground is simply estimated as the average pixel
value of the pixels found in the ring.
In the case of the median estimation, the found
pixel values are first sorted, the background is
then estimated as an average of the 3 or 4 central
values in the sorted array (whether the number of
found pixels is odd or even). This method h.PPs
getting rid of spurious pixel values that can occur
in the ring. Note that in this case, a minimum of
60 pixels has to be found to perform a background
estimation.
-m See -b.
-l or --smearing
This option (low-pass filter) applies a 5x5 convo-
lution with a flat kernel before trying to detect
objects. The smearing is helpful to detect objects
which are smaller than the structural element used
for morphological closing (a 3x3 window). It
increases the number of detections, 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 option is
used.
--no-erosion or -c
cancels morphological closure.
--output-binary or -i
save the binary map (whether it has been eroded or
not). The output file has the basename of the input
file suffixed with "_thr".
--output-labeled or -o
save the label image. The output file has the base-
name of the input file suffixed with "_lab".
Files
Input files must all comply with FITS format.
See Also
detpeak, fwhm, photfits
Bugs
Peaks located on an image edge will not be detected.
FWHM results given in arcseconds not possible (not imple-
mented).
The fine positioning method makes assumptions about the
signal, which may not be fulfilled in many cases. Use it
with caution, especially when determining the radii r1,
r2, and r3 for background computation and weighting
region.
It would be nice to find an algorithm for automatic set-
ting of the sigma threshold, instead of relying on a
default value.