FUN

Description

FUN generates a lookup table (LUT) to perform a specified function and stores it in a database lookup table segment. Supported functions include histogram equalization, histogram normalization, histogram matching, infrequency brightening, and adaptive enhancement.

Parameters

fun(file, func, dbic, dblut, dbsn, dbsd, ostr, sdpt, trim, mask, dbhc, lasc)

Name	Type	Caption	Length	Value range
FILE *	str	Input file name	1 -
FUNC *	str	Enhancement function	2 - 13	EQUA | NORM | MATC | INFR | ADAP
DBIC *	List[int]	Input raster channel(s)	1 -
DBLUT	List[int]	Output lookup table segment	0 -
DBSN	str	Output LUT segment name	0 - 8
DBSD	str	Output LUT segment description	0 - 64
OSTR	List[int]	Output stretch range (min, max)	0 - 2	Default: 0, 255
SDPT	List[float]	Standard deviations per tail	0 - 1	Default: 3.0
TRIM	List[float]	Tail trimming percentage (left, right)	0 - 2
MASK	List[int]	Area mask	0 - 4
DBHC	List[int]	Input histogram match channel	0 - 1
LASC	List[int]	Last segment created	0 -

* Required parameter

Parameter descriptions

FILE

Specifies the name of PCIDSK file to contain the output lookup table.

FUNC

Specifies the type of enhancement to perform.

DBIC

Specifies a set of input channels to be sampled for lookup table generation.

Duplicate channels are NOT allowed.

DBLUT

Specifies the LUT segment(s) in the input file to receive the generated lookup table.

The value of this parameter must be less than or equal to the number of input channels (DBIC). Duplicate segments are NOT allowed.

If the output LUT segment is explicitly specified, the existing lookup table segment is overwritten.

If this parameter is defaulted, a new lookup table segment is created. Upon completion, the parameter returns a list of segment numbers used to save each of the LUT segments written.

DBSN

Specifies a name (up to 8 characters) for the output segment, if a new one is created.

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

DBSD

Describes (in up to 64 characters) the contents or origins of the output LUT.

This string is displayed by ASL if LTYP "SHORT" or "FULL" and may be changed using MAS.

OSTR

Specifies the gray-level range to which the the output is mapped. The default minimum and maximum values are 0 and 255.

SDPT

Specifies the number of standard deviations to be included in each tail for the Histogram Normalization function.

This value is a real number, in units of standard deviations. The default value is 3.0.

TRIM

Specifies the percentage of tail trimming of the low and high ends of the input histogram(s).

Specified as:

TRIM = n1, n2

These are real values, in percentage units (between 0 and 100).

MASK

Specifies the window or bitmap that defines the area of the input raster to be processed.

If a single value is specified, that value represents the channel number of the bitmap segment in the input file. Only the pixels under the bitmap are processed; the rest of the image remains unchanged.

If four values are specified, they define the X,Y offsets and X,Y dimensions of a rectangular window identifying the area to process. 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 pixels that define the window height.

If no value is specified, the entire channel is processed.

DBHC

Specifies the input channel containing the histogram to be matched.

Only one channel may be specified.

This parameter is used only if the specified function is 'Histogram Matching' (MATC).

LASC

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

Details

FUN generates a lookup table to perform a specified function and stores it in a database LUT segment.

FUN reads image data from a set of input channels (DBIC) and uses the histograms to generate lookup tables, which FUN then stores to a set of LUT segments (DBLUT) for later use by LUT or IVL. If the output LUT (DBLUT) is not specified, FUN creates a new LUT segment for each input channel specified, and stores the segment numbers in the output LUT segment. If new LUT segments are created, the segment name (DBSN) and a description (DBSD) may be defined. If the output LUT is specified, FUN overwrites the existing lookup table segments.

A lookup table is generated to map the input histogram over the entire range of output gray-level values. By default, the output range is 0 to 255, but the user may explicitly specify the minimum and maximum output gray levels (OSTR).

The MASK parameter specifies the area within the input channel to process. Only the area under the mask is read; the rest of the image is not used.

If a single MASK value is specified, this value points to a bitmap segment, which defines the area to be processed. When four MASK values are specified, these values define the X,Yoffsets and X,Y dimensions of a rectangular window within the image to process.

If MASK is not specified, the entire database is sampled and one quarter of the pixels in one quarter of the scanlines are used.

The low and high ends of the sampled area can be trimmed by specified percentages (TRIM) to eliminate outliers or noise.

Enhancement functions

Example

The following example illustrates how to generate histogram equalization lookup tables for three image channels.

from pci.fun import fun

file	=	'agrihot.pix'
func	=	'EQUA'			# set function to equalization
dbic	=	[1,2,3]			# equalize channel 1,2,3
dblut	=	[]				# write functions to new LUTs
dbsn	=	'Equalut'		# new created segment name
dbsd	=	''				# blank segment description
ostr	=	[]				# default stretch range, 0-255
sdtp	=	[]				# not used for EQUA
trim	=	[]				# default, no trimming
sdpt    =       []                              # default not used for EQUA
mask	=	[]				# default, sample 1/16 of channel
dbhc	=	[]				# not used for EQUA
lasc	=	[]				# receives number of created segment

fun( file, func, dbic, dblut, dbsn, dbsd, ostr, sdpt, trim, mask, dbhc, lasc )