dmimgthresh

Synopsis

Set low (or high) intensity or exposure regions of an image to a constant value.

Syntax

dmimgthresh  infile outfile [expfile] [cut] [value] [verbose] [clobber]

Description

For observations with strongly variable exposure across an image, you can get spurious results (e.g. with smoothing or source detection algorithms) where the exposure is very low. It can therefore be useful to change parts of the image where the exposure is less than a given value (or percentage of its maximum value). Equivalently, the same task may be carried out for maximum values.

The threshold may be expressed as a percentage of maximum or as an absolute value. The threshold value is compared to the values in the input exposure map (expfile parameter) and any pixel whose exposure value is less than threshold is set to a fixed value (often zero). If an exposure image is not supplied, the input image itself will be used, allowing you to threshold an image to alter all pixels above or below a certain value.

Note that the user-supplied cut value will be truncated to a integer if the image data is of integer type.

Examples

Example 1

dmimgthresh sky.img new.img expfile=exp.img cut="1.5%"

Zero-out all pixels whose exposure is less than 1.5 percent of the maximum exposure in exp.img. Note that the default replacement value is 0 (value parameter).

Example 2

dmimgthresh sky.img new.img expfile=exp.img cut=400.0 value=0.018

Threshold the image, setting all pixels whose exposure is less than 400 to a value of 0.018.

Example 3

dmimgthresh sky.img new.img expfile="" cut="20:80" value=0

Set all pixels whose value is less than 20 or greater than 80 to zero. Since an exposure image is not provided, the values in sky.img are used for the thresholding.

Example 4

dmimgthresh sky.img new.img expfile="" cut=":80%" value=0

Threshold the image, setting all pixels with values greater than 80% of the peak (of sky.img) to zero.

Example 5

dmimgthresh infile=expfile.fits outfile=expfile_flat.fits cut=:1 value=1
dmimgthresh infile=expfile_flat.fits outfile=mask.fits cut=1 value=0

Two dmimgthresh commands are combined to create an image mask. The first line flattens all values greater than 1 to 1; the second line cuts values less than 1 and sets them to 0.

Example 6

dmcopy "flux.img[sky=circle(4096,4096,10)][opt null=NaN]" img.fits
dmimgthresh img.fits img_no_nans.fits cut=INDEF value=0

The dmcopy command will create an image with the pixel values preserving the pixel values inside the specified circle, and will replace the pixels outside the circle (but inside the bounding box around the circle) with NaN's. However, not all applications can seamlessly handle NaN values so dmimgthresh is used to replace those NaNs with the value 0.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
expfile	file	input
cut	string
value	real		0.0
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image.

Parameter=outfile (file required filetype=output)

The output thresholded image.

Parameter=expfile (file filetype=input)

The exposure image (e.g. an exposure map) used to determine which pixels are to be changed in the input image. If an exposure image is provided, it must be the same size as the data image.

Parameter=cut (string)

The threshold value; it may be expressed as a percentage of maximum, e.g., cut="50%", as an actual value, e.g. cut=100.0, as a min:max value, e.g., "20:80" (set min at 20 counts, max at 80 counts), or as a min:max percentage, e.g., "20:80%" (set min at 20%, max at 80%). Both values do not need to be specified: cut="20:" is the same as cut="20": the minimum is set at 20 counts; cut=":70%" sets the upper limit to 70%.

The threshold value can also be set to "INDEF". This special value is used to convert any NaN pixels to the new value.

Parameter=value (real default=0.0)

Thresholded pixels will be set to this value.

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

Specifies the level of verbosity in displaying diagnostic messages.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

Bugs

There are no known bugs for this tool.