User's Guide

PIXSERT

Insert regions of pixels into an existing or a constant valued image

Function:

Inserts regions of pixels of a specified size into an existing single- or multi-band image or a constant valued image with one or more bands. The coordinates of the pixel-region centers are supplied by the user from the terminal or a text file. If multiple regions are specified and they overlap, the first region is overwritten by the values of the second region.

This program uses two subcommands for the processing options: 


  -IMAGE: Regions are inserted into a 
          specified input image.
  -CONST: Regions are inserted into a 
          constant valued image.

Parameters:

Subcommand -IMAGE:
Pixel regions are inserted into the bands of an existing input image. Allows the user to insert rectangular or circular pixel regions into the specified bands of an existing single- or multi-band image.

IN
Input image. The name of the input image to be used by PIXSERT. IN can have one or more bands and may be BYTE, INTEGER*2, INTEGER*4, or REAL data type.

INCOORD(--)
Input coordinates file. Name of the file containing the coordinates and pixel block values to be used. The data consist of Y-coordinate, X-coordinate and the gray value for each pixel region. The data must appear in the order of line (Y-coordinate), sample (X-coordinate), and gray level value. The file records are assumed to contain one set of coordinates and pixel region value per record. If defaulted, the user will be prompted for the coordinates and gray levels. Must be specified in batch mode.

INGRID(--)
Input grid file. Contains transformation coefficients that are used to convert input coordinates to line, sample. If defaulted, no transformation is done.

BANDS(--)
Band numbers. The bands of the image into which the regions are to be inserted. A maximum of 100 bands may be specified.

BLKSIZ(1,1)
Block size (NL, NS). The size of the rectangular regions to be inserted into the output image. The region size must be smaller than the image size. The values for BLKSIZ are specified as the number of lines in the region and the number of samples per line for the region, respectively. Must be set to NULL if region is a circle.

RADIUS(--)
Radius of the circle. The radius of the area to be inserted into the output image. The radius must be smaller than half the image size. The value for RADIUS is specified in pixels. If RADIUS is specified, BLKSIZ must be set to NULL. Maximum radius is 24999.

COOROPT(RELATIVE)
Coordinate option. The coordinate system to be used in inserting the pixel regions at the input coordinates. 


  = RELATIVE:  Relative coordinates.  Indicates that 
               the input coordinates reference the 
               input image area given in the IN pa-
               rameter.
  = MASTER:    Master coordinates.  Indicates that 
               the input coordinates reference the 
               origin of the input image.
Subcommand -CONST:
Pixel regions are inserted into the bands of a created constant image. Allows the user to create a single- or multi-band image containing a constant pixel value and then insert rectangular or circular pixel regions into the specified bands of the image.

INCOORD(--)
Input coordinates file. Name of the file containing the coordinates and pixel block values to be used. The data consist of Y-coordinate, X-coordinate and the gray value for each pixel region. The data must appear in the order of line (Y-coordinate), sample (X-coordinate), and gray level value. The file records are assumed to contain one set of coordinates and pixel region value per record. If defaulted, the user will be prompted for the coordinates and gray levels. Must be specified in batch mode.

INGRID(--)
Input grid file. Contains transformation coefficients that are used to convert input coordinates to line, sample. If defaulted, no transformation is done.

ODTYPE(BYTE)
Output data type. The data type of the output image. 


  = BYTE: BYTE 
  = I*2:  INTEGER*2
  = I*4:  INTEGER*4
  = R*4:  REAL*4

NL(512)
Number of lines. Specifies the number of lines in the output image.

NS(512)
Number of samples per line. Specifies the number of samples per line in the output image.

NBANDS(1)
Number of bands. The number of bands to be created in the output image. The output image may have from 1 to 256 bands.

BACKGRND(0)
Background value. The gray level to be used as a background value in the bands of the output image.

BANDS(--)
Band numbers. The bands of the image into which the regions are to be inserted. A maximum of 100 bands may be specified.

BLKSIZ(1,1)
Block size (NL, NS). The size of the rectangular regions to be inserted into the output image. The region size must be smaller than the image size. The values for BLKSIZ are specified as the number of lines in the region and the number of samples per line for the region, respectively. Must be set to NULL if region is a circle.

RADIUS(--)
Radius of the circle. The radius of the area to be inserted into the output image. The radius must be smaller than half the image size. The value for RADIUS is specified in pixels. If RADIUS is specified, BLKSIZ must be set to NULL. Maximum radius is 24999.

Examples:

  1. LAS> pixsert-image in=dc out=dc.pix bands=2 blksiz=(3,3)

    The 3 x 3 blocks are inserted into the second band of the output image. The other bands of DC.PIX remain exactly the same as the input image. The point data are entered from the terminal.

  2. LAS> pixsert-const out=pix.out incoord=point.file nl=512 ns=512 nbands=3 backgrnd=100 blksiz=(100,100)

    The 100 x 100 blocks are inserted into all bands of the output image. The output image has three bands with a background gray level of 100. The point data are contained in POINT.FILE.

  3. LAS> pixsert-image in=dc out=dc.pix incoord=point.file bands=2 blksiz=-- radius=2

    Circles with a radius of 2 pixels are inserted into the second band of the output image. The other bands of DC.PIX remain exactly the same as the input image. The point data are contained in POINT.FILE.

Description/Algorithm:

PIXSERT first creates an output image. For subcommand -IMAGE, the output image is copied from the input image. For subcommand -CONST, the output image is generated with the specified constant gray level. Then, the regions with gray levels are inserted into the selected bands. The locations of rectangles or circles and gray levels are contained in the input point data. The point data (coordinates and associated gray value) may be provided in a file or entered from the terminal.

The point data consist of the Y-coordinate, X-coordinate, and the gray value for each region. The point data must appear in the order of line (Ycoordinate), sample (x-coordinate), and gray level. For subcommand -IMAGE, two coordinate systems may be used by the point data. The relative coordinates give the locations within the image window. The master coordinates give the locations referenced to the origin of the input image.

The coordinates given in the point data are taken as the coordinates of the region's center pixel. For even-dimensional rectangles, the center is defined as the pixel just above and to the left of true center. Thus, for a 4 x 6 rectangle, the center is taken as pixel (2,3). Also if the coordinates contain fractional components, they are rounded to the nearest integer. PIXSERT attempts to place as much of the region as possible on the output image. Even if the center coordinates are off the image, the part inside the image is still overlaid. When there is overlapping of regions to be modified, the value of the last region written will override the previous value.

Nonfatal Error Messages:

  1. [pixsert-dtype] Data type of value for region XXX invalid

    The region is not inserted. The program continues executing.

  2. [pixsert-noblk] Region XXX completely outside of the image; respecify

    Check the coordinates and/or transformation coefficients. The region is not inserted. The program continues executing.

  3. [pixsert-partblk] Warning: Region XXX only partially contained in image

    Check the coordinates and/or transformation coefficients. The region is partially inserted.

Fatal Error Messages:

  1. [pixsert-bandnum] Band number is greater than number of bands in image

    The value of a band number is larger than the number of input bands. Specify values for BANDS that are appropriate for the specified input image.

  2. [pixsert-batch] Regions must be specified through INCOORD in batch mode

    Input coordinates must be specified through a file in batch mode.

  3. [pixsert-bkgrnd] Invalid background value

    The user specified a value for BACKGRND that is not in the data range of the output image.

  4. [pixsert-blksize] Region size must be less than image size

    The specified value for BLKSIZ for the region to be corrected is larger than the entire image.

  5. [pixsert-both] Either block size or radius must be set to NULL

    Both BLKSIZ and RADIUS are specified. Specify only one of the two, setting the other to NULL.

  6. [pixsert-circle] Radius size must be less than half the image size

    The specified RADIUS for the region to be corrected is larger than half the entire image.

  7. [pixsert-fatal] Fatal error encountered

    A fatal error was encountered. The message that is displayed preceding this message was the error that was encountered.

  8. [pixsert-missing] Either block size or radius must be specified

    Both BLKSIZ and RADIUS are NULL. Specify one or the other.

  9. [pixsert-numbands] More band numbers specified than the number of bands in image

    The number of bands specified is larger than the number of bands in the original image. Specify values for BANDS that are appropriate for the specified input image.

  10. [pixsert-size] Images must be of the same size

    If more than one image is specified in IN, the window size must be the same.

User Notes:

  1. Processing time will vary with the size of the image and the number of blocks to be inserted.