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
  • 
    
    

    regInfoGet

    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>
    
    
    

    regListNames

    Return a Tcl list of the handle names that are attached to a region. This Tcl procedure uses handleListFromType.

    TCL SYNTAX: regListNames
    
    
    

    regTypeSwitch

    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
    
    
    

    regSetWithDbl

    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
    
    
    
    

    regSubtract

    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.
    
    
    
    
    

    regAddWithDbl

    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.
    
    
    
    
    

    regAdd

    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.
    
    
    
    
    

    regPixSetWithDbl

    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.
    
    
    
    
    

    regPixGet

    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.
    
    
    
    
    

    regComp

    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.
    
    
    
    

    regRowFlip

    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
    
    
    
    

    regColFlip

    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.
    
    
    
    

    regMultiplyWithDbl

    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.
    
    
    
    

    regMultiply

    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.
    
    
    
    

    regDivide

    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.
    
    
    
    
    

    regAddRow

    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.
    
    
    
    

    regAddCol

    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.
    
    
    
    

    regSubRow

    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.
    
    
    
    

    regSubCol

    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.
    
    
    
    

    regMultWithRow

    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.
    
    
    
    

    regMultWithCol

    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.
    
    
    
    

    regDivByRow

    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.
    
    
    
    
    

    regDivByCol

    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.
    
    
    
    

    regMaskSetAsPix

    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.
    
    
    
    

    regMaskGetAsPix

    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.
    
    
    

    regPixCopy

    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.
    
    
    

    regMaskCopy

    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.
    
    
    
    

    regMaskSet

    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.