SourceFinder

class photutils.segmentation.SourceFinder(npixels, *, connectivity=8, deblend=True, nlevels=32, contrast=0.001, mode='exponential', relabel=True, nproc=1, progress_bar=True)

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 and deblend_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 or array_like of 2 int

The minimum number of connected pixels, each greater than a specified threshold, that an object must have to be detected. If npixels is an integer, then the value will be used for both source detection and deblending (which internally uses source detection at multiple thresholds). If npixels contains two values, then the first value will be used for source detection and the second value used for source deblending. npixels values must be positive integers.

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 the mode keyword) between its minimum and maximum values. This keyword is ignored unless deblend=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. If contrast=0 then every local peak will be made a separate object (maximum deblending). If contrast=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 unless deblend=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 unless deblend=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 unless deblend=True.

nprocint, optional

The number of processes to use for source deblending. 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 if only a small number of sources are to be deblended. The benefits of multiprocessing require ~1000 or more sources to deblend, with larger gains as the number of sources increase. This keyword is ignored unless deblend=True.

progress_barbool, optional

Whether to display a progress bar. If nproc = 1, then the ID shown after the progress bar is the source label being deblended. If multiprocessing is used (nproc > 1), the ID shown is the last source label that was deblended. 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 in tqdm. This keyword is ignored unless deblend=True.

See also

photutils.segmentation.detect_sources()

photutils.segmentation.deblend_sources()

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

Methods Documentation

__call__(data, threshold, mask=None)

Detect sources, including deblending, in an image 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. If data is a Quantity array, then threshold must have the same units as data. A 2D threshold array must have the same shape as data.

mask2D bool ndarray, optional

A boolean mask with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked pixels will not be included in any source.

Returns:

segment_imageSegmentationImage or None

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.