User's Guide

MAPFILE

Matches two histograms created by PIXCOUNT by cumulative percentages.

Function:

Matches the histograms of two images that were created by PIXCOUNT at certain cumulative percentages in order to create a file that is used by MAP to transform the first image to match the second.

Parameters:

Subcommand -NOCTRL:

No control. The user does not want to control what the values are in the TO column of the output file. The user wants the program to match the cumulative percentages in both INFILE(1) and INFILE(2).

INFILE
Input files. The input files that contain the histogram information generated by the function PIXCOUNT. The values from the first infile are used in the first column of the output file, the FROM column. The values from the second infile are used in the second column of the output file, the TO column.

OUTFILE
Output file. This output file will contain the FROM and TO values that are needed by the function MAP.

MAPPERC(0.0,0.5,5.0,25.0,50.0,75.0,95.0,99.5,100.0)
Map percentages. These are the cumulative percentages of the histogram which are used to calculate the FROM and TO values needed by MAP. The value of the histogram of INFILE(1) closest to the percentages entered is the FROM values in the output file and the values of the histogram of INFILE(2) closest to the percentages entered are the TO values in the output file. These values must be in ascending order.

PIXVAL(0.0)
Pixel value. Pixels with this value will retain their original value. This is commonly used to preserve the value of those pixels which form the background of the image. (See user note #3)

Subcommand -CTRL:

Control. The user wants to control what the values are in the TO column of the output file. The user wants the program to match the cumulative percentages in only INFILE(1).

INFILE
Input files. The input files that contain the histogram information generated by the function PIXCOUNT. The values from the first infile are used in the first column of the output file, the FROM column. The values from the second infile are used in the second column of the output file, the TO column.

OUTFILE
Output file. This output file will contain the FROM and TO values that are needed by the function MAP.

OUTVAL
TO column values. These are the values that the user enters, they are used in the TO column of the output file.

MAPPERC(0.0,0.5,5.0,25.0,50.0,75.0,95.0,99.5,100.0)
Map percentages. These are the cumulative percentages of the histogram which are used to calculate the FROM and TO values needed by MAP. The value of the histogram of INFILE(1) closest to the percentages entered is the FROM values in the output file and the values of the histogram of INFILE(2) closest to the percentages entered are the TO values in the output file. These values must be in ascending order.

PIXVAL(0.0)
Pixel value. Pixels with this value will retain their original value. This is commonly used to preserve the value of those pixels which form the background of the image. (See user note #3)

Examples:

LAS> mapfile-noctrl infile=(histo1,histo2) outfile=outfile
Using the histogram HISTO1, the values nearest the cumulative percentages of (0.0,0.5,5.0,25.0,50.0, 75.0,95.0,99.5,100.0) are stored in the FROM column of the output file OUTFILE. Using the histogram of HISTO2, the values nearest the cumulative percentages of (0.0,0.5,5.0,25.0,50.0,75.0,95.0,99.5,100.0) are stored in the TO column of the output file OUTFILE. Since PIXVAL default is 0, the first values in the FROM and TO columns will be set to 0. OUTFILE can then be used by MAP to transform the image associated with HISTO1 to match the image associated with HISTO2.
LAS> mapfile-ctrl infile=(histo1) outfile=outfile outval=(8,21,41,58,67,93,125,159)
Using the histogram HISTO1, the values nearest the cumulative percentages of (0.0,.5,5.0,25.0,50.0, 75.0,95.0,99.5,100.0) are stored in the FROM column of the output file OUTFILE. The values in OUTVAL will be placed in the TO column of the output file OUTFILE. Since PIXVAL is set to 0, the first values in the FROM and TO columns will be set to 0. OUTFILE can then be used by MAP to transform the image associated with HISTO1 to match the image associated with the users input.
LAS> mapfile-noctrl infile=(histo1,histo2) outfile=outfile mapperc=(.5,95.0,99.5) pixval=65.0
Using the histogram HISTO1, the values nearest the cumulative percentages of (.5,95.0,99.5) are stored in the FROM column of the output file OUTFILE. Using the file HISTO2, the values nearest the cumulative percentages of (.5,95.0,99.5) are stored in the TO column of the output file OUTFILE. The PIXVAL value will be placed in ascending order in the FROM and TO columns of the output file OUTFILE.
LAS> mapfile-ctrl infile=(histo1) outfile=outfile outval=(13.0,34.0,123.0) mapperc=(.5,95.0,99.5) pixval=65.0
Using the histogram HISTO1, the values nearest the cumulative percentages of (.5,95.0,99.5) are stored in the FROM column of the output file OUTFILE. Using the values in OUTVAL, these will be stored in the TO column of the output file OUTFILE. The PIXVAL value will be placed in ascending order in the FROM and TO columns of the output file OUTFILE. The values in MAPPERC are the cumulative percentages we want to match in the PIXCOUNT files.

Description/Algorithm:

After INFILE(1), and if appropriate INFILE(2), are opened, the pixel values nearest the percentages given in MAPPERC are read in according to the following guidelines:
  1. If a percentage of zero is specified and there is more than
     one value with the cumulative percentage of zero, the lowest
     value is used.

  2. If two values have the same cumulative percentage as a 
     percentage that is specified (except for zero), the highest 
     value is used in creating OUTFILE.

  3. If the difference between the cumulative percentages of
     two values and a specified percentage is equal but greater
     than zero, the cumulative percentages of these values
     are compared to the cumulative percentage used from the 
     other input file.  The value of the cumulative percentage 
     that is closest to the cumulative percentage of the other 
     input file is used.
The value of PIXVAL is written to the correct row of the FROM and TO columns of the output file. The values from INFILE(1) are written to the FROM column of the output file and the TO column values are written to the output file from either INFILE2 or from OUTVAL. After all the values are written to the output file, the files are closed and the completion message is displayed.

Nonfatal Error Messages:

None.

Fatal Error Messages:

[mapfile-ascend] Percentages are not in ascending order
The percentage values given in the parameter MAPPERC and OUTVAL must be in ascending order. Go back and reorder the values so they are in ascending order. Rerun the program.
[mapfile-create] Error creating output file <XXXXX>
The output file <XXXXX> could not be created. Check the to see if the file already exists and also check if you have permission to write to the file. Rerun the program.
[mapfile-fatal] Fatal error encountered
A fatal error was encountered during processing. The processing is terminated. The message that is displayed immediately preceding this message is the specific error that was encountered.
[mapfile-nohost] Error in retrieving host name
An error occurred while trying to convert the TAE format name to the UNIX format. Make sure that the characters in the TAE\ format are what TAE accepts. Rerun the program.
[mapfile-notequal] Number of values in OUTVAL and MAPPERC are not equal
The number of values in OUTVAL and MAPPERC must be equal. Go back and make sure the number of values in both parameters are equal. Rerun the program.
[mapfile-read] Error reading <XXXXX> file
The <XXXXX> file could not be read; and therefore, an output file cannot be created. Verify that the format of the file is correct. Rerun the program.
[mapfile-tae] Error in creating TAE format output file name
An error occurred while trying to convert the UNIX format name into the TAE format. Make sure that the characters in the UNIX format are what UNIX accepts. Rerun the program.

User Notes:

Any changes made to the routines PIXCOUNT or MAP may affect the operation of this routine.
PIXCOUNT must be run with OPTION = BOTH.
Other pixels may be mapped to this value.