SourceFinder¶
- class photutils.segmentation.SourceFinder(npixels, *, connectivity=8, deblend=True, nlevels=32, contrast=0.001, mode='exponential', relabel=True, nproc=1, progress_bar=True)[source]¶
Bases:
object
Class to detect sources, including deblending, in an image using segmentation.
This is a convenience class that combines the functionality of
detect_sources
anddeblend_sources
.Sources are deblended using a combination of multi-thresholding and watershed segmentation. In order to deblend sources, there must be a saddle between them.
- Parameters:
- npixelsint
The minimum number of connected pixels, each greater than a specified threshold, that an object must have to be detected.
npixels
must be a positive integer.- connectivity{4, 8}, optional
The type of pixel connectivity used in determining how pixels are grouped into a detected source. The options are 4 or 8 (default). 4-connected pixels touch along their edges. 8-connected pixels touch along their edges or corners.
- deblendbool, optional
Whether to deblend overlapping sources.
- nlevelsint, optional
The number of multi-thresholding levels to use for deblending. Each source will be re-thresholded at
nlevels
levels spaced exponentially or linearly (see themode
keyword) between its minimum and maximum values. This keyword is ignored unlessdeblend=True
.- contrastfloat, optional
The fraction of the total source flux that a local peak must have (at any one of the multi-thresholds) to be deblended as a separate object.
contrast
must be between 0 and 1, inclusive. Ifcontrast=0
then every local peak will be made a separate object (maximum deblending). Ifcontrast=1
then no deblending will occur. The default is 0.001, which will deblend sources with a 7.5 magnitude difference. This keyword is ignored unlessdeblend=True
.- mode{‘exponential’, ‘linear’, ‘sinh’}, optional
The mode used in defining the spacing between the multi-thresholding levels (see the
nlevels
keyword) during deblending. The'exponential'
and'sinh'
modes have more threshold levels near the source minimum and less near the source maximum. The'linear'
mode evenly spaces the threshold levels between the source minimum and maximum. The'exponential'
and'sinh'
modes differ in that the'exponential'
levels are dependent on the source maximum/minimum ratio (smaller ratios are more linear; larger ratios are more exponential), while the'sinh'
levels are not. Also, the'exponential'
mode will be changed to'linear'
for sources with non-positive minimum data values. This keyword is ignored unlessdeblend=True
.- relabelbool, optional
If
True
(default), then the segmentation image will be relabeled after deblending such that the labels are in consecutive order starting from 1. This keyword is ignored unlessdeblend=True
.- nprocint, optional
The number of processes to use for multiprocessing (if larger than 1). If set to 1, then a serial implementation is used instead of a parallel one. If
None
, then the number of processes will be set to the number of CPUs detected on the machine. Please note that due to overheads, multiprocessing may be slower than serial processing. This is especially true if one only has a small number of sources to deblend. The benefits of multiprocessing require ~1000 or more sources to deblend, with larger gains as the number of sources increase. This keyword is ignored unlessdeblend=True
.- progress_barbool, optional
Whether to display a progress bar. Note that if multiprocessing is used (
nproc > 1
), the estimation times (e.g., time per iteration and time remaining, etc) may be unreliable. The progress bar requires that the tqdm optional dependency be installed. Note that the progress bar does not currently work in the Jupyter console due to limitations intqdm
. This keyword is ignored unlessdeblend=True
.
Examples
import matplotlib.pyplot as plt from astropy.convolution import convolve from astropy.visualization import simple_norm from photutils.background import Background2D, MedianBackground from photutils.datasets import make_100gaussians_image from photutils.segmentation import (SourceFinder, make_2dgaussian_kernel) # make a simulated image data = make_100gaussians_image() # subtract the background bkg_estimator = MedianBackground() bkg = Background2D(data, (50, 50), filter_size=(3, 3), bkg_estimator=bkg_estimator) data -= bkg.background # convolve the data kernel = make_2dgaussian_kernel(3., size=5) # FWHM = 3. convolved_data = convolve(data, kernel) # detect the sources threshold = 1.5 * bkg.background_rms # per-pixel threshold finder = SourceFinder(npixels=10, progress_bar=False) segm = finder(convolved_data, threshold) # plot the image and the segmentation image fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(8, 10)) norm = simple_norm(data, 'sqrt', percent=99.) ax1.imshow(data, origin='lower', interpolation='nearest', norm=norm) ax2.imshow(segm.data, origin='lower', interpolation='nearest', cmap=segm.cmap) plt.tight_layout()
(
Source code
,png
,hires.png
,pdf
,svg
)Methods Summary
__call__
(data, threshold[, mask])Detect sources, including deblending, in an image using using segmentation.
Methods Documentation
- __call__(data, threshold, mask=None)[source]¶
Detect sources, including deblending, in an image using using segmentation.
- Parameters:
- data2D
ndarray
The 2D array from which to detect sources. Typically, this array should be an image that has been convolved with a smoothing kernel.
- threshold2D
ndarray
or float The data value or pixel-wise data values (as an array) to be used as the per-pixel detection threshold. A 2D
threshold
array must have the same shape asdata
.- mask2D bool
ndarray
, optional A boolean mask with the same shape as
data
, where aTrue
value indicates the corresponding element ofdata
is masked. Masked pixels will not be included in any source.
- data2D
- Returns:
- segment_image
SegmentationImage
orNone
A 2D segmentation image, with the same shape as the input data, where sources are marked by different positive integer values. A value of zero is reserved for the background. If no sources are found then
None
is returned.
- segment_image