STR

Description

Parameters

str(file, dbic, dblut, dbsn, dbsd, expo, istr, ostr, lctr, hctr, trim, mask, lasc)

Parameter descriptions

FILE

Specifies the name of the file to receive the lookup table segment.

DBIC

Specifies the input channel from which "actual" minimum and maximum gray levels for stretching are determined.

DBIC and ISTR cannot both be specified. However, one of DBIC or ISTR must be specified.

DBLUT

Specifies the lookup table segment or layer to receive the function.

DBLUT (Input) may contain one or no elements. If this parameter is explicitly specified, the lookup table segment must be of type 170 or 172 and will be overwritten. If it is not specified, then a new lookup table segment is created.

Upon completion, DBLUT returns the number of the segment used to save the created lookup table function.

DBSN

Specifies a name (up to 8 characters) for the output lookup table (LUT) segment or layer. This parameter is only used if a new segment is created.

This string is displayed by ASL, and may be changed with MAS.

DBSD

Optionally describes (in up to 64 characters) the contents or origins of the output segment lookup table (LUT) segment or layer. This parameter is only used if a new segment is created.

This string is displayed by ASL if the LTYP parameter is set to "MEDIUM" or "FULL", and may be changed with MAS.

EXPO

Specifies a positive real number corresponding to the exponent in the following contrast stretching formula:

newval = A*(oldval - ISTR(1))**EXPO + OSTR(1)

where newval and oldval are gray levels, A is the scaling factor, and ISTR(1) and OSTR(1) are the minimum input and output gray levels.

For example, if EXPO (Exponent) is set to 1, the stretch is linear.

Any floating point number between 0.0 and 100.0 can be specified. The default value for this parameter is 0.5, which eliminates the typical skewing of histograms.

ISTR

Specifies the range of input gray levels.

 ISTR=i,j

where i must be less than or equal to j. The default value is [0,255].

Only gray values in this range will be stretched; the rest are treated in accordance with the OSTR, LCTR, and HCTR parameters.

DBIC and ISTR cannot both be specified. However, one of DBIC or ISTR must be specified.

OSTR

Specifies the range of output gray levels.

OSTR=i,j

LCTR

Specifies the mapping of pixels that fall short of the minimum input gray level.

HCTR

Specifies the mapping of pixels that are higher than the maximum input gray level.

TRIM

Optionally specifies the amount of tail trimming to apply to the image histogram sample.

Valid values include real values in units of % (between 0 and 100). Default is no tail trimming (0).

 TRIM=n1,n2

where n1 is for left (low) tail, and n2 is for right (high).

Trimming is performed only if DBIC is set.

MASK

Specifies the window or bitmap that defines the area to be stretched within the input raster. If this parameter is not specified, the entire channel (layer) is used by default. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

MASK=Xoffset,Yoffset,Xsize,Ysize        | process window
MASK=b   | process only under bitmap stored in segment b
MASK=	| process entire channel (default)

LASC

If a new segment is created, then LASC is assigned the number for the new segment, after STR has finished executing.

Details

STR generates custom-made lookup table segments (type 170 or 172), which can then be used by LUT to perform contrast stretching functions on image data stored in specified database channels. In general, the user has total control of the parameters that make up the contrast stretch function. The range of input values for the lookup table function can be determined from an input channel or can be set manually by the user. The range of output values for the lookup table function can be defaulted to the full gray-scale range (0-255), or specified over a user-selected range. Input image data between the minimum and maximum values are mapped using a power function with a specified exponent. The LCTR (Low End Control) and HCTR (High End Control) parameters control the mapping function for input values that are outside the input gray level value range.

The MASK (Mask) parameter specifies the area within the input channel or layer to be processed. Only the area under mask will be processed and the rest of the image will be unchanged. If a single value is specified, then this value points to a bitmap segment, which defines the area to be processed. When four values are specified, these values define the x,y offsets and x,y dimensions of a rectangular window within the image to be processed. If defaulted, the entire database is processed.

Sampling may be further restricted using the TRIM parameter, which trims the low and high ends of the sample by specified percentages. This parameter is useful for eliminating outliers or noise.

STR can be used to create completely new lookup table segments or to modify existing lookup table segments. If DBLUT is not specified, a new lookup table segment is created. The database segment name (DBSN) and database segment descriptor (DBSD) must be specified.

If DBLUT is specified, then the lookup table segment is read in and the table values between ISTR(1) and ISTR(2) are overwritten with new values. This allows for the creation of piecewise functions. DBSN and DBSD need not be specified in this case. If DBLUT is not specified, then the lookup table is initialized to zero and appropriate values are overwritten.

If all parameters are defaulted, STR performs the "default enhancement", a square-root function which exaggerates contrast in the low end of the gray-level spectrum. gray-level values are transformed such that the minimum and maximum gray-level values on the input image are mapped to 0 and 255 respectively on the output image.

When a new lookup table segment is created on the database, a message appears on the terminal giving the segment number of the newly created lookup table. This new segment number is saved in the parameter DBLUT.

Functions

Various types of functions can be obtained by varying the value of the exponent:

 EXPO = 0.5     Square root function (default)
 EXPO = 1       Linear ramp function
 EXPO = 2       Squaring function

In general, the user has total control of the parameters that make up the contrast stretch function. All default minimum and maximum input and output values can be overridden by user-specified values .

If ISTR is specified, DBIC is ignored.

 EXPO           Power exponent (must be positive value)
                (default = 0.5)

 ISTR(1)        Minimum input gray-level value (must be <= ISTR(2))
                (default = 0)

 ISTR(2)        Maximum input gray-level value (must be >= ISTR(1))
                (default = 255)

 OSTR(1)        Minimum output gray-level value
                (default = 0)

 OSTR(2)        Maximum output gray-level value
                (default = 255)

If OSTR(1) > OSTR(2), the result is a "negative" image.

LCTR and HCTR control the mapping function for input values that are outside the range specified by ISTR:

 For X < ISTR(1)        F(X) = OSTR(1)  if LCTR = "MIN" (default)
                        F(X) = OSTR(2)  if LCTR = "MAX"
                        F(X) unchanged  if LCTR = "OFF"

 For X > ISTR(2)        F(X) = OSTR(2)  if HCTR = "MAX" (default)
                        F(X) = OSTR(1)  if HCTR = "MIN"
                        F(X) unchanged  if HCTR = "OFF"

LCTR or HCTR should only be set to "OFF" when modifying an existing lookup table segment (DBLUT is specified), so that the table values outside ISTR are not modified.

The area under which the image is sampled to determine the minimum and maximum input values can be restricted to a specified mask window or under a specified database. The low and high ends of this sample can be trimmed by specified percentages to eliminate outliers or noise.

Examples

Example 1: Perform a "default enhancement" (a square-root function which exaggerates dark features in the image), on the third channel of image data:

from pci.str import str as str_

file="irvine.pix"
dbic=[3]                    # specify channel for input range
dbsn="SQ.RT.C3"             # specify segment name
lasc=[]                     # receives segment number created


str_(file, dbic, dbsn=dbsn, lasc=lasc)

        INPUT                   OUTPUT
        +----+                  +----+
        22-40                    0-50

from pci.str import str as str_

file="irvine.pix"
dbic=[]                   # input range specified by user
dblut=[]                  # create a new LUT segment
dbsn="PWLUT"              # specify segment name
dbsd="Piecewise stretch"  # specify segment descriptor
expo=[1]                  # specify linear function
istr=[22,40]              # specify first input range
ostr=[0,50]               # specify first output range
lctr=''                   # all pixels with values less
# than 22 will be set to 0
hctr=''                   # all pixels with values greater
# than 40 will be set to 50
trim=[]
mask=[]
lasc=[]                   # receives segment number created

str_(file,dbic,dblut,dbsn,dbsd,expo,istr,ostr,lctr,hctr,trim,mask,lasc)

Since DBLUT is updated with the segment number of the newly created LUT segment on the first run through STR, it does not have to be specified prior to the second or third run through.

Algorithm

The contrast stretch function has the following form:

  F(X) = A * (X - ISTR(1)) ** EXPO + OSTR(1) 
                                        ISTR(1) < X < ISTR(2)

 X              Input gray-level value
 F(X)           Output gray-level value
 A              Scaling factor
 EXPO           Power exponent (must be positive value)
 ISTR(1)        Minimum input gray-level value (must be <= ISTR(2))
 ISTR(2)        Maximum input gray-level value (must be >= ISTR(1))
 OSTR(1)        Minimum output gray-level value
 OSTR(2)        Maximum output gray-level value

 If OSTR(1) > OSTR(2), the result is a `negative' image.

The formula for determining the scaling factor A is as follows:

                OSTR(2) - OSTR(1)
        A = ---------------------------
            (ISTR(2) - ISTR(1)) ** EXPO