CHDETOP

Description

CHDETOP detects differences between two input raster images ('new' and 'reference'). Typically, CHDETOP is used on a pair of images from the same optical satellite sensor and, depending on the sensor, tasseled caps can be used to determine the changes. The output raster reveals the areas of change that occurred between two defined time periods. The output file may be used as input to EXPOLRAS, which extracts and refines polygons from raster to detect very specific changes in features of interest.

Parameters

chdetop(fili, dbic, fili_ref, dbic_ref, filo, algo, opertype, asensor, mask, maskfile, ftype, foptions)

Name	Type	Caption	Length	Value range
FILI *	str	Input "new" image file name	1 -
DBIC	List[int]	Input "new" image channels	0 -
FILI_REF *	str	Input reference image file name	1 -
DBIC_REF	List[int]	Input reference image channels	0 -
FILO *	str	Output file name	1 -
ALGO	str	Change detection algorithm	0 - 10	COMBINE \| MAGDIFF \| CHANDIFF \| INTENRATIO \| TCGNDIFF \| TCSBDIFF \| AVGDIFF \| AVGRATIO Default: MAGDIFF
OPERTYPE	str	Difference operation type	0 - 3	POS \| NEG \| ABS Default: POS
ASENSOR	str	Sensor name	0 - 29	See Description.
MASK	List[int]	Area mask	0 - 4
MASKFILE	str	Area mask file name	0 -
FTYPE	str	Output file type	0 - 4	Default: PIX
FOPTIONS	str	Output file options	0 - 64

* Required parameter

Parameter descriptions

FILI

Specifies the name of the file that contains the raster data after change occurs.

DBIC

Specifies the input image channels representing the area after change occurs.

If this parameter is not explicitly specified, the behavior depends on the ALGO (Algorithm) parameter setting.

FILI_REF

Specifies the name of the file that contains the reference raster data representing the area before change occurs.

DBIC_REF

Specifies the input image channels representing the area before change occurs.

If this parameter is not explicitly specified, the behavior depends on the ALGO (Algorithm) parameter setting.

FILO

Specifies the name of the output file that will be created. The file must not already exist. The output file's georefencing will be based on the reference file, but its extents will be the overlap area of the two input data sets. See the Details sections for notes about the exact content of the output file.

ALGO

Specifies the algorithm used for automated change detection.

Supported methods are:

COMBINE (Combine): copies all the input channels from both files
MAGDIFF (Magnitude Difference): magnitude difference between any two images
CHANDIFF (Channel Difference): calculates the difference between corresponding channels in two images
INTENRATIO (Intensity Ratio): intensity ratio between any two images
TCGNDIFF (Tasseled Cap Greenness Difference): computes greenness differences for select sensors using tasseled cap transformation
TCSBDIFF (Tasseled Cap Brightness Difference): computes soil brightness differences fo select sensors using tasseled cap transformation
AVGDIFF (Average Channel Difference): Calculate the difference between sequentially corresponding input channels and then average all of difference rasters together to create a single change layer
AVGRATIO (Average Channel Ratio): Calculate the ratio between sequentially corresponding input channels and then average all of ratio rasters together to create a single change layer

OPERTYPE

Specifies the direction of change to be detected, unless ALGO (Algorithm) is set to COMBINE, in which case this parameter is ignored.

Supported types are:

POS (Positive): New - Reference (features appear); this is the default value
NEG (Negative): Reference - New (features disappear)
ABS (Absolute): Absolute value of New - Reference (absolute change)

ASENSOR

Specifies the name of the sensor used to capture the input images.

This parameter is ignored unless ALGO is TCGNDIFF or TCSBDIFF.

To use either of the tasseled cap based change detection algorithms, the sensor must be known. Identifying information can either exist in metadata or be specified explicitly using this parameter.

Valid sensors are:

Ikonos
Landsat-4 MSS
Landsat-5 MSS
Landsat-4 TM
Landsat-5 TM
Landsat-7 ETM+
QuickBird

Note: Define this parameter using the exact spelling from the list above.

Change detection is typically done between two images from the same sensor. It is possible, however, to use images from two sensors, provided the images are spatially comparable. You may specify two sensors by separating the names with a comma and space; for example, "Landsat-5 MSS, Landsat-4 MSS". When two sensors are specified, the first entry is applied to the new image; the second is applied to the reference image.

If this parameter is not specified, the function checks for CollectorType, PlatformName, PlatformNumber, and SensorModelName metadata tags at the file level.

When sensor information is required, if this parameter is not specified and the necessary tags are not found in the metadata, an error is generated.

MASK

Optionally, specifies the areas of the data to be processed. If this parameter is specified, only pixels within the mask area are processed; all other pixels in the output will be set to -3.4E38 and defined as NoData. If the Algorithm parameter is specified as Combine, however, the NoData values in the input channels are preserved. If this parameter is not specified, the entire overlapping region is processed.

You can define these areas using three types of mask boundaries: window, bitmap, and vector.

For a window mask, define a rectangular area by specifying a starting pixel (Xoffset) and line (Yoffset) reference, and a window size (Xsize and Ysize).

For a bitmap mask, specify the number of the bitmap segment that you want to use. All the pixels within the specified segment having a pixel value of 1 define the area where input data must exist to be processed.

For a vector mask, specify the number of the vector segment that you want to use as a mask. If the segment is a polygon layer, the input data is clipped along the polygon boundary. If the segment is not a polygon layer, the extents of the shapes in the segment are used to define the mask area.

Note: A bitmap segment is chosen over a vector segment for defining the mask area, if both segments share the same segment number.

MASK can be set as follows:

unspecified/blank: a mask is not defined.
xOffset, yOffset, Xsize, Ysize: a window mask is defined by a starting pixel (Xoffset) and line (Yoffset) reference, and a window size (Xsize and Ysize).
segment_number: the bitmap or vector segment corresponding to the specified number defines the mask area.

If you specify a MASK but not a MASKFILE, the MASK is obtained from the input file.

MASKFILE

Specifies the name of the file containing the MASK.

If you do not specify a MASK, this parameter is ignored. If you specify a MASK but not a MASKFILE, CHDETOP obtains the MASK from the input file.

FTYPE

Specifies the output file format type, represented by a three- or four-letter code. The format type must be a GDB-recognized file type.

Supported file format codes include:

PIX: PCIDSK format (default)
TIF: Tagged Image File format

For a complete list of GDB-recognized file types and their codes, see the GDB file formats section of the CATALYST Professional online Help.

FOPTIONS

Specifies the file creation options to be applied when creating the output file. These are specific to the file format; in each case, the default of no options is allowed. FOPTIONS can be used to specify the compression schemes, file format subtypes, and other information.

Different options are available for different file types (see the FTYPE parameter). The options are described in the 'GDB file formats' section of the CATALYST Professional online Help.

Details

CHDETOP automatically detects changes between two specified raster images (new and reference). The two input rasters must overlap, align at the pixel level and have the same spatial resolution. They can have different extents and the output will cover the spatial intersection of the two input rasters. The two files should be co-registered and radiometrically normalized.

The same number of channels must be processed from both the input new and reference images. When channels are explicitly specified for DBIC (InputNew), the corresponding channels must be explicitly specified through DBIC_REF (InputRef) or vice versa. When input channels are not explicitly specified, the automatic behavior depends on the setting for the ALGO (Algorithm) parameter. If ALGO (Algorithm) is specified as COMBINE, MAGDIFF (Magnitude Difference), CHANDIFF (Channel Difference), or INTENRATIO (Intensity Ratio), all the channels in the input files are automatically used unless specifically defined. When using either of the tasseled cap based algorithms, however, the appropriate input channels are automatically determined based on the metadata of the input files. In particular, the input files must contain MINWAVELENGTH and MAXWAVELENGTH metadata tags at the channel level to properly associate each channel with the correct band. If this metadata is not present (and the channels are not explicitly specified and ALGO is TCGNDIFF or TCSBDIFF), an error is generated.

When using TCGNDIFF (Tassel Cap Greenness Difference) or TCSBDIFF (Tassel Cap Brightness Difference), there must be four input channels for Landsat-4/5 MSS, IKONOS, and QUICKBIRD data, and six channels for Landsat-4/5 TM, Landsat-7 ETM+ data. Furthermore, for the tasseled cap calculations to have meaning when specifying channels explicitly, you must specify them in increasing band order.

The function generates an output raster that indicates changes between the new and reference images. The channels in the output raster depend on the input channels and on the specified ALGO (Algorithm) value. If the input file contains a NO_DATA_VALUE metadata tag, pixels having a NoData value in either of the input files will be NoData in the output.

Combine: the output will consist of a copy of the input channels from both the new and reference images.
Channel Difference (CHANDIFF): the output consists of the same number of channels as those specified as input, each illustrating the corresponding differences. The Channel Difference algorithm creates an output channel of the next-highest bit depth to the two input channels. For example, if both input and input reference channels are 8U, the output channel will be 16S. Similarly, if the input channel is 8U and the input reference channel is 16U, the output channel will be 32R.
Magnitude Difference (MAGDIFF): the output will consist of three channels, where the first channel is the magnitude of the input channels from the new image, and the second channel is the magnitude for the reference image channels. Magnitude is computed for each pixel by taking the square root of the sum of the squares of all the pixels values from the input channels. The third channel is the difference between the first two channels, with the reference subtracted from the new.
Intensity Ratio (INTENRATIO): the output will consist of four channels. The first channel is the normalized intensity for the new image. The second channel is the normalized intensity for the reference image. The third channel is the absolute value of the intensity ratio (written in decibels) between the new and reference intensity. The fourth channel stores the normalized change, as percentiles.

The sign of the percentiles (+ or -) is dependent on the specified OPERTYPE (Difference detection algorithm) string. If OPERTYPE is set to POS, pixels that were greater in the input than in the reference file are set to positive (+). If OPERTYPE is set to NEG, pixels that were greater in the input than in the reference are set to negative (-). If OPERTYPE is set to ABS, all values are between 0 and 100%.
Tasseled Cap transformations (TCGNDIFF or TCSBDIFF): the output will consist of three channels. The first channel is derived from the new image by applying specific transformation coefficients to the input channels. The second channel is computed in exactly the same manner, but for the reference image. The third channel is the difference between those two channels, with the reference subtracted from the new. The coefficients depend on the sensor of the imagery and whether you are using it with greenness or soil brightness variations. Only Landsat, Ikonos and QuickBird multispectral data sets are supported.

Example

from pci.chdetop import chdetop

fili	=	"after.tif"
dbic	=	[1,2,3]
fili_ref	=	"before.tif"
dbic_ref	=	[1,2,3]
filo	=	"test1.pix"
algo	=	"COMB"
opertype	=	""
asensor	=	""
mask	=	[]
maskfile	=	""
ftype	=	""
foptions	=	""

chdetop( fili, dbic, fili_ref, dbic_ref, filo, algo, opertype, asensor, mask, maskfile, ftype, foptions )

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Example :: Related