Simple Region Manipulation
These region utilities will operate on regions whose
pixels are of any supported type. Procedures which
take more than one region as parameters require that all
regions have the same number of rows and columns.
Arithmetic
Arithmetic operations are performed "as if" all operations were
converted to a type which has an exact representation for all the
values of each type of pixel.
Before a result is stored back into a pixel the following conversions
are performed: 1) If the result is smaller (largest) than the
smallest (largest) value representable in a pixel, it is set to that
small (large) value. 2)If any of the operands were a floating-point
type, and the result is an integer type, the result is rounded down after
0.5 (-0.5) has been added to positive (negative) values.
Rows and Columns
ROW and COLUMN operands which locate specific pixels in a region
may be specified as either floating point or decimal numbers. 0.0,
0, 0.5, or 0.9 all refer to the row or column 0.
regInfoGet
regListNames
regTypeSwitch
regSetWithDbl
regSubtract
regAddWithDbl
regAdd
regPixSetWithDbl
regPixGet
regComp
regRowFlip
regColFlip
regMultiplyWithDbl
regMultiply
regDivide
regAddCol
regAddRow
regSubCol
regSubRow
regMultWithRow
regMultWithCol
regDivByRow
regDivByCol
regMaskGetAsPix
regMaskSetAsPix
regMaskSet
regMaskCopy
regPixCopy
Return a Tcl list of region information. The information returned includes
nrow
ncol
type
name
row0
col0
modCntr
isSubReg
isPhysical
physicalRegNum
pxAreContiguous
hasHeader
headerModCntr
nSubReg
hasMask
TCL SYNTAX:
regInfoGet <handle>
Return a Tcl list of the handle names that are attached to a region. This
Tcl procedure uses handleListFromType.
TCL SYNTAX:
regListNames
Switch the pixel type of the entered region. The type is
switched to either the entered type (if allowed) or to the
logically correct type. The following switches are allowed.
signed 8-bit data to unsigned 8-bit data and vice versa
signed 16-bit data to unsigned 16-bit data and vice versa
signed 32-bit data to unsigned 32-bit data and vice versa
For example, if an unsigned 8-bit region is entered and no
type is entered, the region will have it's type switched to
signed 8-bit. In all cases the pixels remain untouched.
Regions with pixel types equal to floating point, cannot be
switched to any other type.
TCL SYNTAX:
regTypeSwitch <region> [type]
<region> Handle to region.
[type] Pixel type to switch the region's pixel type to.
Allowed values are - U8, S8, U16, S16, U32, S32.
RETURNS:
TCL_OK Successful completion. The Interp result string is null.
TCL_ERROR Error occurred. The Interp result string explain the error
Sets all pixels in REGION to the value implied by DOUBLE.
REGION may have pixels of any type.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regSetWithDbl <region> <double>
<region> Handle to region.
<double> Number which can be converted to a floating point number.
RETURNS:
TCL_OK Successful completion. The Interp result string is null.
TCL_ERROR Error occurred. The Interp result string explain the error
This procedure subtracts REGION2 from REGION1 pixel-by-pixel.
If regOut is present, store the result there; else store the
result in REGION1. The regions may have pixels of any type.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regSubtract <region1> <region2> [-regOut reg]
<region1> Required handle to region holding minuend pixels
<region2> Required handle to region holding subtrahend pixels.
[-regOut] Optional Handle to region to receive the
resulting pixels. If Not specified, REGION1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result string explains why.
This procedure adds NUMBER to each pixel in REGIN. If REGOUT is present, store
the result there; else store the result in REGIN. NUMBER may have the syntax
of a floating point or decimal integer. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regAddWithDbl <regIn> <number> [-regOut reg]
<regIn> Required handle to region supplying the pixels.
<number> Required decimal or floating-point number.
[-regOut] Optional handle to region receiving the pixels.
If not specified REGIN is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
This procedure adds REGION1 to REGION2 pixel-by-pixel.
If regOut is present, store the result there; else store the
result in REGION1. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regAdd <addend1> <addend2> [-regOut reg]
<addend1> Required handle to region.
<addend2> Required handle to region.
[-regOut] Optional handle to region receiving the result
If not supplied, ADDEND1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
The pixel in REGION specified by ROW and COL is set to NUMBER.
NUMBER may be floating point or decimal.
Row or Column .
may be specified using decimal or floating-point number
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regPixSetWithDbl <region> <row> <column> <number>
<region> Required handle to region holding pixel to be set.
<row> Required row number of pixel to be set.
<column> Required column number of pixel to be set.
<number> Required value to set as decimal or floating point number.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result string will contain
the error string.
Return the pixel in REGION at location ROW, COL. The pixel is formatted
in a way appropriate to the type of the pixels in REGION. ROW and COLUMN
may be specified as either decimal or floating point numbers.
Row or Column .
may be specified using decimal or floating-point number
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regPixGet <region> <row> <column>
<region> Required handle to region supplying the pixel.
<row> Required row number of pixel.
<column> Required column number of pixel.
RETURNS:
TCL_OK Successful completion. The Interp result contains the pixel.
TCL_ERROR Error occurred. The Interp result explains the error.
Compare REGION1 to REGION2 pixel-by-pixel after applying the arithmetic
conversions described at the top of this file. Return the string "same"
if all the pixels are equivalent. If not, return a keyed list with keys
"row" and "col" set to the coordinates of a pixel which is not equivalent.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regComp <region1> <region2>
<region1> Required Handle to region holding pixels to compare.
<region2> Required Handle to region holding pixels to compare.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Flip the pixels in REGION row-wise by copying the pixels.
TCL SYNTAX:
regRowFlip <region>
<region> Required Handle of region to flip.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error
Flip the pixels in REGION column-wise by copying the pixels.
TCL SYNTAX:
regionRowFlip <region>
<region> Required Handle of region to flip.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Set each pixel in the resulting region to the product of the corresponding
pixel in REGIN and NUMBER after applying the conversions specified
at the top of this file. If regOut is not specified, place the result in
REGIN.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regMultiplyWithDbl <regIn> <number> [-regOut reg]
<regIn> Required handle of region supplying the pixels.
<number> Required floating point or decimal number.
[-regOut] Optional handle of region receiving the pixels.
If absent, REGIN is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Set each pixel in the resulting region to the product of the corresponding
pixels in MULT1 and MULT2 divided by SCALE. If -regOut is omitted, the
result is MUTL1. If scale is omitted, use 1.0. The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regMultiply [-scale SCALE] [-regOut reg] <mult1> <mult2>
[-scale] Optional decimal or floating point number divisor
[-regOut] Optional output region
<mult1> Required handle to region.
<mult2> Required handle to region.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Set each pixel in the resulting region to the corresponding pixel in
DIVIDEND divided by DIVISOR. If -scale is present, the (intermediate)
result is multiplied by the value SCALE. DIVIDEND is the result unless
the -regOut switch is present. The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regDivide [-scale SCALE] [-regOut reg] <dividend> <divisor>
<dividend> Required dividend.
<divisor> Required divisor.
[-scale] Optional switch giving multiplicative scale factor
[-regOut] Optional switch giving output region
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
This procedure adds ROWVECTOR to REGION1 pixel-by-pixel,
row-by-row. If regOut is present, store the result there;
else store the result in REGION1. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regAddRow <region1> <rowvector> [-regOut reg]
<region1> Required handle to region.
<rowvector> Required handle to the row.
[-regOut] Optional handle to region receiving the result
If not supplied, REGION1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
This procedure adds COLVECTOR to REGION1 pixel-by-pixel,
column-by-column. If regOut is present, store the result there;
else store the result in REGION1. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regAddCol <region1> <colvector> [-regOut reg]
<region1> Required handle to region.
<colvector> Required handle to the column.
[-regOut] Optional handle to region receiving the result
If not supplied, REGION1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
This procedure subtracts ROWVECTOR from REGION1 pixel-by-pixel,
row-by-row. If regOut is present, store the result there;
else store the result in REGION1. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regSubRow <region1> <rowvector> [-regOut reg]
<region1> Required handle to region.
<rowvector> Required handle to the row.
[-regOut] Optional handle to region receiving the result
If not supplied, REGION1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
This procedure subtracts COLVECTOR from REGION1 pixel-by-pixel,
column-by-column. If regOut is present, store the result there;
else store the result in REGION1. The regions may be of differing types.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regSubCol <region1> <colvector> [-regOut reg]
<region1> Required handle to region.
<colvector> Required handle to the column.
[-regOut] Optional handle to region receiving the result
If not supplied, REGION1 is used.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Multiply each pixel in MULT1 by the corresponding (same column) pixel
in ROWVECTOR, divide the result by SCALE (which is set to 1.0 if not
specified) and store the result in the output region
(store in MULT1 if -regOut not specified). The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regMultWithRow [-scale SCALE] [-regOut reg] <mult1> <rowvector>
[-scale] Optional decimal or floating point number divisor
[-regOut] Optional output result region
<mult1> Required handle to input region.
<rowvector> Required handle to row vector.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Multiply each pixel in MULT1 by the corresponding (same row) pixel
in COLVECTOR, divide the result by SCALE (which is set to 1.0 if not
specified) and store the result in the output region
(store in MULT1 if -regOut not specified). The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regMultWithCol [-scale SCALE] [-regOut reg] <mult1> <colvector>
[-scale] Optional decimal or floating point number divisor
[-regOut] Optional output result region
<mult1> Required handle to input region.
<colvector> Required handle to column vector.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Divide each pixel in DIVIDEND by the corresponding (same column) pixel
in ROWVECTOR, multiply the result by SCALE (which is set to 1.0 if not
specified) and store the result in the output region
(store in DIVIDEND if -regOut not specified). The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regDivByRow [-scale SCALE] [-regOut reg] <dividend> <rowvector>
[-scale] Optional decimal or floating point number divisor
[-regOut] Optional output result region
<dividend> Required handle to input region.
<rowvector> Required handle to row vector.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Divide each pixel in DIVIDEND by the corresponding (same row) pixel
in COLVECTOR, multiply the result by SCALE (which is set to 1.0 if not
specified) and store the result in the output region
(store in DIVIDEND if -regOut not specified). The regions may be of different
types. The arithmetic conversions specified at the file are performed.
Type conversions are performed as described in
Arithmetic .
TCL SYNTAX:
regDivByCol [-scale SCALE] [-regOut reg] <dividend> <rowvector>
[-scale] Optional decimal or floating point number divisor
[-regOut] Optional output result region
<dividend> Required handle to input region.
<colvector> Required handle to column vector.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Set the indicated mask element in REGION to VALUE. VALUE may
be a decimal, octal or hexadecimal number. It is an error if
VALUE has bits set which are not representable in a mask element.
e.g. set an 8-bit mask pixel to 512. n.b. Tcl supports c-style
bit-wise operators.
TCL SYNTAX:
regMaskSetAsPix
<region> Required handle to region
<row> Required row number
<col> Required column number
<value> Required decimal, octal or hexadecimal number
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Return the Mask-pixel in REGION at ROW, COL as a hexadecimal
number.
TCL SYNTAX:
regMaskGetAsPix <region> <row> <col>
<region> Required handle to region
<row> Required row number
<col> Required column number
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Copy the Pixels from REGIN to REGOUT. Both regions must be of the
same size. Either region may be a sub-region. The regions may
be of different types.
TCL SYNTAX:
regPixCopy <regIn> <regOut>
<regIn> Required handle to region
<regIn> Required handle to region
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Copy the mask pixels from REGIN to REGOUT. Both REGIN and
REGOUT must be of the same size. Both REGIN an REGOUT must
have masks.
TCL SYNTAX:
regMaskCopy <regIn> <regOut>
<regIn> Required handle to region
<regIn> Required handle to region
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.
Set the mask pixels in REGION to NUMBER. NUMBER may be
positive decimal, hexadecimal or octal.
It is an error for NUMBER to have bits set which are not representable
in a mask-pixel. If "-and", "-or", or "-xor" are present, set then mask
to the result of the operation on the corresponding pixel and number.
REGION must have a mask.
TCL SYNTAX:
regMaskSet <region> <number>
<region> Required handle to region
<number> Number to set
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred. The Interp result explains the error.