User's Guide

PMASK

Creates a mask of a specified value within an image.

Function:

Creates a mask of a specified value within an image. The cutline which defines this area has to form an enclosed polygon. The direction in which the polygon is formed determines if the area outside or inside the cutline will be masked. A clockwise cutline keeps the area inside the cutline and masks the area outside the polygon. A counterclockwise cutline keeps the area outside of the polygon and masks the area inside the cutline.

Parameters:

IN
Input image. The input image to be masked. The input image can be BYTE, INTEGER*2, INTEGER*4, or REAL*4 data type.

OUT
Output image. The output image will be the same size and data type as the input image.

INFILE(--)
Input file. The input IBIS graphics file that contains the cutline coordinates. If there is no INFILE, use the LSCOORS parameter to specify the cutline mask.

LSCOORS(--)
Line/sample coordinates. These are the line/sample locations that form the cutline mask when INFILE does not exist. The order in which these locations are specified will determine if the mask is on the inside or the outside of the cutline that is created. A clockwise cutline will keep the area inside the polygon and mask the area outside the cutline. A counterclockwise polygon will keep the area outside of the cutline and mask the area inside the cutline. The first coordinate and the last coordinate must be the same in order to separate the area inside the cutline from the area outside the cutline.

MASKVAL(0)
Mask value. The pixel value that will be given to the masked area of the image.

SCALFACT(1)
Scale factor. Scale factor to be applied to the input image and/or the window option and cutline coordinates. If the image has already been scaled, only the window option and cutline coordinates are reduced by the scale factor. If the image has not already been scaled, the image, as well as the window option and cutline coordinates, are reduced by a factor of SCALFACT.

CUTAREA(IN)
Cutline area. The area of the image that will remain.


  =IN:  Inside.  The area of the image inside the cutline 
        will remain.
  =OUT: Outside.  The area of the image outside the cutline 
        will remain.
  =TBD: To Be Determined.  The direction that the cutline 
        was formed will determine which area will remain.

Examples:

  1. LAS> pmask in="in.dat(1,1,512,512)" out=out.dat infile=poly.dat

    OUT.DAT contains the cut and masked image of IN.DAT. Because SCALFACT is defaulted to 1, OUT.DAT will be the same size as IN.DAT. The cutline is formed by the line/ sample locations in file POLY.DAT. The mask created has a default value of 0. Since CUTAREA is defaulted to IN, the area inside the cutline will remain and the area outside will be masked.

  2. LAS> pmask in="in.dat(1,1,512,512)" out=out.dat lscoors=(20,20,20,500,500,500,500,20,20,20) maskval=255 scalfact=2 cutarea=tbd

    OUT.DAT contains the cut and masked image of IN.DAT. Because SCALFACT is set to 2, OUT.DAT will be 256 lines X 256 samples. The area masked will lie outside of the cutline formed by the coordinates given in the parameter LSCOORS because the cutline was formed in a clockwise direction. The mask created has a value of 255.

Description/Algorithm:

After reading the parameters, IN and OUT are opened for read and write, respectively. If specified, INFILE is opened and the line/sample coordinates are read.

If SCALFACT is greater than 1, the window specification and the line/sample locations are divided by SCALFACT and the input image data descriptor record (DDR) is read to see if the image has been scaled or not. If the image has not been scaled, the image is reduced by a factor of SCALFACT. The slope and direction of the cutline lines are calculated. If CUTAREA is either IN or OUT, the direction of the cutline is set to clockwise or counterclockwise, regardless of how the polygon was formed.

The image is processed in the following manner if the cutline is in a clockwise direction:


   o  The lines before the cutline begins are written to the out-
      put image with a pixel value of MASKVAL.  The left and right 
      edges of the cutline are calculated.

   o  The samples before the cutline's left edge are written to 
      the output image with a pixel value of MASKVAL.

   o  The samples within the cutline are copied from the input 
      image to the output image.

   o  The samples after the right edge of the cutline are written
      to the output image with a pixel value of MASKVAL.  The lines 
      after the cutline ends are written to the output image with
      a pixel value of MASKVAL.

The image is processed in the following manner if the cutline is 
in a counterclockwise direction:

   o  The lines before the cutline begins are copied from the in-
      put image to the output image.  

   o  The left and right edges of the cutline are calculated.

   o  The samples before the cutline's left edge are copied from 
      the input image to the output image.  The samples within 
      the cutline are written to the output image with a pixel 
      value of MASKVAL.

   o  The samples after the right edge of the cutline are copied 
      from the input image to the output image.  The lines after 
      the cutline ends are copied from the input image to the 
      output image.
After every line is processed and written to OUT--all the files are closed, the history and DDR files may be updated, and the completion message is displayed.

Nonfatal Error Message:

  1. [pmask-warn] Nonfatal error encountered

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

Fatal Error Messages:

  1. [pmask-fatal] Fatal error encountered

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

  2. [pmask-open] Cannot open <XXXXXX> file

    The <XXXXXX> file could not be opened and processing is terminated. Verify that the <XXXXXX> file exists.

  3. [pmask-points] Minimum of four points needed

    A minimum of four points are required to create a full polygon around which to mask the image. Enter at least four points.

  4. [pmask-read] Error reading <XXXXXX> file

    The <XXXXXX> file could not be read; and therefore, an output file cannot be created. Verify that the format of the file is correct.

  5. [pmask-sf] Scale factor of input image and SCALFACT are not equal

    The scale factor that was applied to the input image and the value specified in SCALFACT are not equal. Respecify the SCALFACT parameter.

  6. [pmask-write] Error encountered writing to <XXXXXX>

    An error occurred while trying to write to the <XXXXXX> file. Please check output parameters or free disk space.

  7. [pmask-max] Maximum number of points exceeded

    The maximum number of points in the polygon is greater than allowed. Reduce the number of the points in the polygon and rerun.

  8. [pmask-window] Input images do not have the same window size

    The input images must be the same size. Respecify the windows and rerun.

User Notes:

    None.