User's Guide

INTERSECT

Overlay input images to generate gray level permutation codes

Function:

Overlays corresponding pixels from multiple input images to generate a permutation table and optional single-band output image. The permutation table is created as a labeled table. Each entry in the permutation table stores a permutation code, a count of the number of pixels in the output image that have been assigned that permutation code, and a list of the input image pixel values that comprise that permutation. Each pixel value in the optional output image stores the permutation code assigned to the collection of pixel values from the input image(s).

Parameters:

IN
Input images. Input images or image bands for processing. These images may be any combination of BYTE, INTEGER*2, or INTEGER*4 data types. While separate window specifications are allowed for each image, the resulting window specifications must be the same size. Any combination of single or multi-band images may be used.

OUTLT
Output labeled table file. This labeled table will contain a permutation code, a count of the number of pixels in the output image that have been assigned that permutation code, and a list of the input image pixel values that comprise that permutation.

OUT(--)
Output image. The output image name. The data type of this image depends on the number of unique permutations found in the input image.

             Range of 
         Permutation Codes        Data Type 
         __________________       __________ 

           0 -        255         BYTE 
           0 -      32767         INTEGER*2 
           0 - 2147483647         INTEGER*4 

LTTYPE
Labeled table type. This is the type of labeled table file to be created.

ATRNAME
Attribute names. This is the attribute name(s) given to each of the field(s) in the labeled table file.

MASKVAL(-- )
Mask values. Mask values for all bands . This allows mask values to be specified for each input image band. A mask value must be specified for each image band, and it may lie outside the data range for its associated image band. INTERSECT assigns a permutation code of 0 when a pixel value from any band matches the mask value specified for that band. The first data record in the labeled table contains the number of mask values found. If the mask value lies outside the data range for its associated image band, the mask value is ignored.

Examples:

  1. LAS> intersect in="county + township" outlt=county out=county.twnshp lttype=permutation atrname=(county,twnshp)

    IN specifies two single-band input images--COUNTY and TOWNSHIP. The labeled table will be named COUNTY, and the output image name will be COUNTY.TWNSHP. The type of the labeled table will be PERMUTATION with attribute names of COUNTY and TWNSHP. MASKVAL is defaulted to NULL. This causes INTERSECT to seek permutation codes for each pixel of the input image.

  2. LAS> intersect in="vegclass + mss.apr + mss.aug" outlt=veg out=vegclass.intrsct lttype=permutation atrname=(a, b, c, d, e, f, g, h, i) maskval =(73, -1, -1, -1, -1,-1, -1, -1, -1)

    IN specifies nine input bands: the single-band classified vegetation image VEGCLASS, the 4-band MSS multiband image MSS.APR, and the 4-band MSS multi-band image MSS.AUG. MASKVAL specifies that masking is to take place in this run. VEGCLASS pixel values of 73 denote pixels that are to be masked out during this run. The output pixel values in VEGCLASS.INTRSCT are assigned the value 0 when a pixel value from the VEGCLASS image is 73. The -1 mask values fall out of the data range for the MSS image bands and do not contribute to the masking. The first data record in the labeled table VEG will contain the number of mask values found.

Description/Algorithm:

INTERSECT compares corresponding pixels from each input image band and creates a permutation table as a labeled table. Each entry in the permutation table stores a permutation code, a count of the pixels in the output image that are assigned to the permutation code, and a list of the gray levels that compose the permutation. The user has the option of creating a single-band output image representing the permutations of grey levels from the input images.

The image bands are read simultaneously. A table of run-length codes is created for each input image line. Each run-length code consists of an integer pair (X,Y), where X is the number of consecutive pixels with gray value Y. Intersections are determined by noting common runs of run-length codes. Permutations are defined by the intersection of run-length codes from each input image band. Each intersection of pixel values is compared to entries in the table of permutations that is being generated. When no match is found, the next consecutive permutation code is assigned to the permutation defined by that intersection. The run length of the intersection is assigned to the count for the permutation code. The permutation code is assigned to pixels of the temporary image corresponding to the run-length code of the input images. When the attributes of an intersection match the attributes that define a permutation code, the number of pixels in the current intersection is added to the count for the matching permutation. The permutation code is assigned to pixels of the temporary image corresponding to the run-length code of the input images.

Only a fixed number of permutations can be stored in memory. When the number of permutations defined exceeds the number that can be stored, room for the new permutation is made in memory by writing the least-recently used permutation table entry to a temporary file. This may result in the generation of duplicate definitions for permutation codes. After the "intersection pass" through the input image(s), remaining permutation table entries are written to the temporary file. The temporary file is sorted by component gray codes to group duplicate permutation definitions together. Consecutive records of the temporary file are then compared to determine if they share the same permutation definition. Records sharing a common definition are merged with the first record that defines that permutation, and the permutation codes are sequentially reassigned. The resulting permutation record is written to the labeled table.

If an output image is requested, a translation table is generated that maps initial permutation codes to resulting permutation codes. The temporary image is read and pixel values are passed through the translation table to generate the output image. If the translation table cannot be stored in memory, it is created as a temporary file.

Nonfatal Error Messages:

  1. [intersect-create] Creating the labeled table

    The labeled table and, optionally, the translation table are being created. The processing time will vary depending on the number of permutations found and the number of image bands being processed.

  2. [intersect-sort] Sorting the permutation file

    The host system sort is being used to sort the permutation file. The processing time will vary depending on the number of permutations found and the number of image bands being processed.

  3. [intersect-slow] Sorting without the system sorts

    The host system sorts could not be used to sort the permutation file. The processing time will vary depending on the number of permutations found and the number of image bands being processed. See User Note 2.

  4. [intersect-temp] Temporary image name already exists

    The temporary image used by INTERSECT already exists, probably from an unsuccessful run. The image will be deleted and processing will continue.

  5. [intersect-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The data is probably valid and therefore saved. The error message that is displayed preceding this message is the specific error that was encountered.

  6. [intersect-range] Unable to handle the data range efficiently

    This error occurs only on a VAX/VMS system. Since the VMS system sort will not handle negative data values, an offset value is added to all pixel values when creating the permutation table, thus enabling the use of the system sort. This error occurs if the offset value plus the maximum pixel value is greater than the value that I*4 can handle. Processing will continue, but the internal bubble sort will be used to sort the permutation file. See User Note 2.

Fatal Error Messages:

  1. [intersect-mask] Number of mask values must equal the number of image bands

    The number of MASKVAL values must be 0 or match the number of input image bands. The user should specify the correct number of MASKVAL values and rerun INTERSECT.

  2. [intersect-real] Real images are not allowed

    INTERSECT will not process REAL input images. The user should convert the REAL input images to an appropriate data type and rerun INTERSECT.

  3. [intersect-open] Error opening temporary file

    INTERSECT was not able to open the temporary file. This system error is normally out of the user's control. The user should rerun INTERSECT. If the error occurs again, contact the system manager.

  4. [intersect-system] System file sort failed

    INTERSECT was not able to sort the temporary permutation file or translation table. This system error is normally out of the user's control. The user should rerun INTERSECT. If the error occurs again, contact the system manager.

  5. [intersect-alloc] Error allocating dynamic memory

    An error occurred allocating memory. Rerun INTERSECT, and if the error reoccurs, contact the system manager.

  6. [intersect-size] Input images to not have same window sizes

    The input images are specified with different window sizes. Rerun INTERSECT and respecify the window sizes.

  7. [intersect-fatal] Fatal error encountered

    A fatal error was encountered during processing. Processing is terminated. The error message that is displayed preceding this message is the specific error that was encountered.

  8. [intersect-atrname] Number of attribute names must equal the number of image bands

    The number of ATRNAME values must match the number of input image bands. The user should specify the correct number of ATRNAME values and rerun INTERSECT.

User Notes:

  1. Each permutation record contains a permutation code, a count of the number of times the permutation code was assigned to a pixel in the output image, and the corresponding pixel values from the input images that define the permutation. A zero permutation code only occurs when a masked input value is detected in an intersection. Permutation codes greater than zero enumerate the order of the sorted component pixel values.

  2. The number of input bands affects INTERSECT run times, especially the sorting of the permutation file. A UNIX system sort will only allow 9 image bands to be sorted while a VAX/VMS system sort allows 44 image bands to be sorted. If these limits are exceeded, a bubble sort is used to sort the permutation file. This can be quite slow since up to N^2 (where N is the number of permutations) passes through the permutation file may be needed to sort the file.

  3. INTERSECT creates intermediate files during the course of processing which are deleted at the completion of INTERSECT. If INTERSECT terminates before normal completion, these files may be left in the user's directory. The files are named SORT*.DAT and SORT*.OUT, where the "*" is an integer value. These files should be removed by the user if this occurs.

  4. INTERSECT defines two attributes in addition to the userspecified attribute names: PERMNUM is the permutation code assigned by INTERSECT; NPIXELS is the number of pixels that have been assigned to the permutation code. The user should not user PERMNUM or NPIXELS as user-specified attribute names.

  5. INTERSECT builds run length codes for each line of the input image bands. Intersections are determined by comparing the lengths of the run length codes for each input image. This allows for faster processing of relatively uniform input images than is possible by checking for permutation matches a pixel at a time.