deblend_sources

photutils.segmentation.deblend_sources(data, segment_img, npixels, *, labels=None, nlevels=32, contrast=0.001, mode='exponential', connectivity=8, relabel=True, nproc=1, progress_bar=True)[source]

Deblend overlapping sources labeled in a segmentation image.

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:
data2D ndarray

The 2D array of the image. If filtering is desired, please input a convolved image here. This array should be the same array used in detect_sources.

segment_imgSegmentationImage

The segmentation image to deblend.

npixelsint

The minimum number of connected pixels, each greater than threshold, that an object must have to be deblended. npixels must be a positive integer.

labelsint or array_like of int, optional

The label numbers to deblend. If None (default), then all labels in the segmentation image will be deblended.

nlevelsint, optional

The number of multi-thresholding levels to use for deblending. Each source will be re-thresholded at nlevels levels spaced between its minimum and maximum values (non-inclusive). The mode keyword determines how the levels are spaced.

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.

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.

connectivity{8, 4}, optional

The type of pixel connectivity used in determining how pixels are grouped into a detected source. The options are 8 (default) or 4. 8-connected pixels touch along their edges or corners. 4-connected pixels touch along their edges. The connectivity must be the same as that used to create the input segmentation image.

relabelbool, optional

If True (default), then the segmentation image will be relabeled such that the labels are in consecutive order starting from 1.

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.

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 in tqdm.

Returns:
segment_imageSegmentationImage

A segmentation image, with the same shape as data, where sources are marked by different positive integer values. A value of zero is reserved for the background.