Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmimgblob.html
AHELP for CIAO 4.16

dmimgblob

Context: Tools::Image

Synopsis

Identifies groups of pixels above/below threshold

Syntax

dmimgblob  infile outfile threshold [srconly] [clobber] [verbose]

Description

`dmimgblob' will identify groups of contigious pixels that are above (and optionally below) some user selected threshold. The output image is a mask where the pixels in the mask respresent which unique set the pixel belongs to. Pixels above threshold are given values 1 to N (where N is the number of blobs found). This can be used as a crude source detection.

When the 'srconly' parameter is set to no (default), then pixels which fall below the threshold are also grouped. These (presumably) background pixels are given group numbers in the output mask from -1 to -M (where M is the number of background blobs).

Any Null/NaN valued pixels or pixels outside the data-subspace are assigned a mask value = 0.

Note: This tool uses a recursive algorithm that may exhaust the stack for particularly large datasets. If you get a 'Segmentation violation' please try increase the 'stacksize' (see 'man limit'); (t)csh: limit stacksize unlimited; (ba)sh: ulimit -s unlimited.


Examples

Example 1

dmimgblob infile=img.fits outfile=mask.fits threshold=10

The file 'mask.fits' will contain a map of where the input image, img.fits, was >= 10 (in whatever units the input image is). Contigious pixel < 10 are labeled with negative values in the mask image.

Example 2

dmimgblob infile=img.fits outfile=mask.fits threshold=10 srconly=yes

Similar to above except that only values >= the threshold are included (as are Null/NaN or data-subpsace excluded values with a mask value = 0).


Parameters

name type ftype def min max reqd
infile file input       yes
outfile file output       yes
threshold real         yes
srconly boolean   no      
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image.

The input 2D image.

Parameter=outfile (file required filetype=output)

The output file name

The output mask file (long data-type). Each unique blob of pixels in the input image above threshold are identified with unique values in the output mask file.

Parameter=threshold (real required)

Threshold to apply to image

Input image values >= this value are masked w/ positive values in the output mask. Value < this value are optionally identified with negative values in the output.

Parameter=srconly (boolean default=no)

Include values only >= threshold?

If set to 'yes' then only values >= the threshold are included. If set to 'no' then values < are also included.

Parameter=clobber (boolean default=no)

Remove output if it exists?

Used to specify whether or not to clobber existing file that has the same name as the specified output file

Parameter=verbose (integer default=0 min=0 max=5)

The tool chatter level

Verbose can be from 0 to 5, generating different amounts of debugging output.


Bugs

There are no known bugs for this tool.

See Also

dm
dmfiltering
tools::core
dmappend
tools::image
centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, pathfinder, vtbin
tools::region
dmcontour, dmellipse, dmimghull, dmimglasso
tools::response
mean_energy_map, pileup_map
tools::statistics
dmstat, imgmoment, statmap