User's Guide

RANDSEL

Copy randomly-selected non-masked pixels.

Function:

Randomly selects pixels from an input image and copies them to an output image. The output image will have approximately the same non-spatial statistics as the input but will have different spatial properties. The user may specify mask values which will not be copied to the output image.

Parameters:

IN
Input image. The input image may be windowed and subbanded and may contain any data type.

OUT
Output image. The name of the output image. This image will have the same number of bands as IN. The numbers of lines and samples will be determined by SAMPERC and the amount of masked data in the input image.

SAMPERC
Sampling percentage. The percentage of non-masked pixels to randomly select. If SAMPERC < 100.0, the input (non-masked) pixels will be randomly selected and the image size will be reduced. If SAMPERC=100.0, then all (non-masked) input pixels will be copied to the output. 

  < 100.0:  Reduce image size, select this percentage of pixels
  = 100.0:  Copy all non-masked pixels

MASKBAND(1 )
Mask band. The band of IN used to identify masked pixels. If a masked pixel is located in MASKBAND, then all image bands will be masked at that pixel location. If MASKVAL=NULL, MASKBAND will be ignored.

MASKVAL(-- )
Mask values. The pixel values or value ranges designating masked areas of IN that should not be copied to OUT. If MASKVAL=NULL, no checks are performed for masked data. See User Note 2 for more detailed information.

SEEDVAL(-- )
Seed value. The user may specify a seed value for random number generation. This allows generating an identical output image for a given input image and set of parameters. If SEEDVAL=NULL, a seed value will be based on the system clock to produce different output images for each execution.

FILLVAL(0 )
Fill value. The pixel value to be used for completing the last image line. Image data will normally constitute a portion of the last image line; FILLVAL is used to complete this line.

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

  = SAME: Same as input 
  = BYTE: Byte       
  = I*2:  Integer*2  
  = I*4:  Integer*4  
  = R*4:  Real*4

Examples:

  1. LAS> randsel in=wheel out=example1 samperc=100 maskval=0

    RANDSEL will check band 1 for the mask value of 0. All non-masked pixels will be copied from the input image WHEEL to the output image EXAMPLE1. The number of output pixels will equal the total number of input pixels minus the number of masked input pixels.

  2. LAS> randsel in=wheel out=example2 samperc=30

    30% of the pixels of the input image WHEEL will be randomly selected to create the output image EXAMPLE2. No checks will be applied for masked data.

    Input and output images for the examples appear in the online Mosaic help and the hardcopy user guide.

Description/Algorithm:

RANDSEL randomly selects pixels from an input image and copies them to an output image. It maintains pixel values for each band but optionally subsamples the image and shifts pixels from one line to the next. The output image will have the same number of bands and (nearly) the same non-spatial statistics as the input, but will not generally be recognizable.

The user may specify mask values (MASKVAL) which will not be copied to the output image. If MASKVAL is specified, every pixel in MASKBAND is checked to determine if that pixel is masked data and should therefore be excluded from the output image. If SAMPERC is less than 100, the input image will be reduced in size and a random selection criteria will be applied to the non-masked pixels; the decision to select or not select each non-masked pixel will be based on a random number. (See User Note 3 for information on random numbers.) If SAMPERC=100, no subsampling will occur; all non-masked input pixels will be copied to the output image. If SAMPERC=100 and MASKVAL=NULL, the input image will be copied without change.

An intermediate single-band byte image is created with the same numbers of lines and samples as the input image. This intermediate image indicates whether or not each input pixel will later be copied to the output image; it contains the results of both application of MASKVAL and random pixel selection. The intermediate image is deleted before RANDSEL completes.

As the intermediate image is created, the number of pixels that will be copied to the output image (number_selected_pixels) is tracked. This information is used to determine the output image size that will maintain the width to height ratio of the input image. The output image size is given by the following two formulas: 

out_NL = in_NL * sqrt (number_selected_pixels / number_input_pixels)
out_NS = number_selected_pixels / out_NL

In most cases, these calculations will result in a real number of samples that is rounded up to the next integer. As a result of rounding, the last output image line will contain both image data and fill. In a few rare cases, image size will not have to be rounded up and the last output image line will consequently contain no fill.

Nonfatal Error Message:

  1. [randsel-copy] The input image will be copied without change

    If MASKVAL=NULL and SAMPERC=100, then IN will be copied to OUT without change. It would be more efficient to simply run COPY in these cases.

Fatal Error Messages:

  1. [randsel-badband] MASKBAND <x> exceeds number of bands in IN <y>

    MASKBAND is greater than the number of input bands; the user has specified an image band which does not exist.

  2. [randsel-badmask] An invalid value of <xxxxx> was entered for MASKVAL

    An invalid value was entered. See User Note 2 for the format of valid values for MASKVAL.

  3. [randsel-fatal] Fatal error encountered

    A fatal error was encountered. The message displayed preceding this message was the error encountered. Processing terminates.

  4. [randsel-mask] Maximum value <xxxxx> for MASKVAL is less than minimum value <yyyyy>

    Data ranges (as in 4:99) can be given for MASKVAL. The minimum value must precede the maximum value for a data range. It would be an error, for example, to set MASKVAL=99:4.

  5. [randsel-memory] Unable to allocate memory for <xxxxx>

    An error occurred attempting to dynamically allocate memory. Rerun, and if the error persists, contact the system administrator.

  6. [randsel-noout] No output image was created

    Under certain conditions RANDSEL will not select any input pixels and no output image will therefore be created. These conditions are: the input image is all masked data; the input image and SAMPERC are both small.

  7. [randsel-size] Error sizing output image

    The program had an internal error while calculating the size of the output image. Contact system support.

  8. [randsel-time] Error getting system time

    The program had an error while determining the system time. Rerun, and if the error persists, contact system support.

  9. [randsel-window] Images specified by IN do not have the same window size

    The image components specified for IN must all have the same numbers of lines and samples.

User Notes:

  1. If MASKVAL=NULL and SAMPERC=100, then IN will be copied to OUT without change. It would be more efficient to simply run COPY in these cases.

  2. Values for MASKVAL can be real numbers and data ranges. For example, if MASKVAL=(1.2, 4) RANDSEL will check for the mask values of only 1.2 and 4. If MASKVAL=1:4, all data values between 1 and 4 inclusive will correspond to masked data. MASKVAL can include single values and data ranges as in MASKVAL=(0:10, 100, 255). When a data range (as in 4:99) is given for MASKVAL, the minimum value must precede the maximum value.

  3. If SAMPERC is less than 100, a random number is generated via the C function random() for each non-masked pixel. (See the unix man page on random for more information). This random number is scaled to a percentage. If the random percentage is less than or equal to SAMPERC, then the input pixel is copied to the output image.

    Random processes produce random results. Therefore, the percentage of pixels selected usually varies from the desired percentage (SAMPERC). For small images (100 pixels square), the variation from desired percentage can be 0.2%. As the image size increases, the variation approaches zero. For an image 10,000 pixels square, variation is on the order of 0.003%.

  4. This application sets projection flags in the output DDR to INVALID. RANDSEL rearranges image data from line to line and thus invalidates projection information.

  5. This routine creates an intermediate image named RANDSEL.INTERMEDIATE.# where # stands for a number from 0 to 99. This number is determined at runtime and allows for multiple concurrent RANDSEL jobs in the same directory.

  6. When converting a REAL*4 image to an integer data type, the fractional portion of each pixel value will be truncated (not rounded) to the nearest integer value.

  7. Related applications are RANDSAMP, ZOOM, and MAGNIFY.

  8. An example utilization of RANDSEL would be to eliminate image masks and reduce image size prior to executing ISOCLASS.