THR

Description

Parameters

thr(file, dbic, dbob, tval, comp, dbsn, dbsd)

Parameter descriptions

FILE

The name of the PCIDSK image file that contains the image channels, and to which the output threshold bitmaps will be written.

DBIC

The image channel or channels to be thresholded.

For each channel specified, the entire image area will be processed.

DBOB

The bitmap segment or segments to receive the results of thresholding.

If no value is specified for this parameter, an output bitmap of segment type 101 will be created.

TVAL

The minimum and maximum threshold values.

If the value of the COMP (Complement Mode) parameter is OFF (default), gray values within this range (including the range values themselves) are turned on for the bitmap (assigned a bit-value of 1). If only one range endpoint is specified (for example, TVAL=i), all values equal to and above this value will be turned on for the bitmap. If the same value is entered for the threshold minimum and maximum (for example, TVAL=i,i), all pixels with that value will be turned on for the bitmap.

when the value of of the COMP (Complement Mode) parameter is ON, all values within the range will be turned off (assigned a bit-value of 0) in the output bitmap. For more information, see Details.

With the complex channels, the threshold values are intensity-based.

COMP

Specifies whether to use the complement or negative bitmap mode for thresholding.

DBSN

The name (up to eight characters) of the output bitmap segments.

If no value is specified for this parameter, a default name of THR is used.

DBSD

A description of up to 64 characters of the contents or origins of the output data.

Return Value

Returns: Number of bits set per bitmap

Type:  PCI_LONG

Parameter: IMSTAT

A list of uint64 with the values being the counts of the bits set (pixel value of 1) in each output bitmap. The list contains one value for each bitmap created or updated. The list is in the same order as the bitmap segment numbers except that the list starts at index 0 and ends at index N-1 where N is the number of bitmaps processed.

Details

THR creates threshold bitmap segments from a set of image channels. Each input channel is processed independently and results in one corresponding output bitmap. When the value of the COMP (Complement Mode) parameter is OFF, for each input pixel value between the minimum and maximum threshold gray-level values inclusively (TVAL), corresponding bits are turned on in the output bitmaps (assigned a bit-value of 1). For each input pixel value outside this range, the corresponding bits are turned off. When the maximum threshold value is not specified, every pixel above the minimum threshold value will be turned on.

When the value of the COMP (Complement Mode) parameter is ON, the complement of the resulting bitmap is stored. That is, all bits inside the threshold range are turned off (assigned a bit-value of 0), and bits outside the range are turned on (assigned a bit-value of 1).

If no output bitmap segment is specified, the function creates a new set of bitmaps, writing the segment numbers to the user and updating the LASC parameter with the segment number of the last segment created. A segment name (DBSN) of from one to eight characters, and a segment descriptor (DBSD) of from one to 64 characters, can be specified for the newly created bitmap segments; the default segment name is THR.

When an existing bitmap segment is specified, it will be overwritten by the results of THR. A segment name (DBSN) must still be specified, but LASC will not be updated, as a new segment has not been created.

Note that NoData pixels are excluded from consideration with one exception. When THR is run with threshold minimum and maximum are both specified as the NoData number, then pixels equal to that value will be turned on in the output bitmap. For example: COMP=OFF, TVAL=0,0 and NoData=0 would produce a bitmap of the NoData areas in the input raster.

When run with EASI the function sets the parameter named IMSTAT to the number of bits set per bitmap. If the number of bits set is large then some precision is lost, due to conversion from int64 to float (32bit) type.

Examples

Analysis of histogram data for a channel indicates that water bodies have a gray-level response of 10.0 to 25.0. Create two "masks" for the imagery, the first masks out the water bodies, the second masks out the land.

i) Water Mask

from pci.thr import thr

file	=	"irvine.pix"
dbic	=	[4]
dbob	=	[]	# create new bitmap
tval	=	[9,11]	# threshold range (min,max)
comp	=	'OFF'	# threshold values from 9 to 11
dbsn	=	'Watmask'	# output segment name
dbsd	=	'Bitmap mask-water'	# output segment description

thr( file, dbic, dbob, tval, comp, dbsn, dbsd )

ii) Land Mask

from pci.thr import thr

file	=	"irvine.pix"
dbic	=	[1]
dbob	=	[]	# create new bitmap
tval	=	[10.0,25.0]	# threshold range (min,max)
comp	=	'ON'	# threshold values less than 10.0 and
# greater than 25.0
dbsn	=	'Landmask'	# output segment name
dbsd	=	'Bitmap mask-land'	# output segment description

thr( file, dbic, dbob, tval, comp, dbsn, dbsd )