regUtils "C" Routines

Region Utilities perform standards operations on regions. These include standard arithmetic operations, like multiply and divide, even if the regions have pixels of differing types. For example, it is possible to add an 8-bit region to a floating point region, and store the result into a 16-bit unsigned region.

Headers for these functions are available in Notes

Arithmetic operations are performed "as if" all operands are converted to a new type which has an exact representation for all the values of each type of pixel in the operation.

Before a result is stored back into a pixel, the following conversions are performed: 1) If the result is smaller (larger) 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 the positive (negative) value.

Routines which operate on more than one region require all the regions involved to have the same number of rows and columns. If the regUtils routines were compiled with NDEBUG undefined, the dimensions are checked by means of the sh_assert macro. Otherwise, the dimensions are not checked, and calls with mis-sized regions will have unpredictable results. The routines work on sub-regions as well as regions.

  • shRegTypeSwitch
  • shRegPixGetAsDbl
  • shRegPixSetWithDbl
  • shRegSetWithDbl
  • shRegSub
  • shRegAdd
  • shRegAddWithDbl
  • shRegComp
  • shRegRowFlip
  • shRegColFlip
  • shRegMultWithDbl
  • shRegMult
  • shRegDiv
  • 
    
    

    shRegTypeSwitch

    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.

    C SYNTAX: double shRegTypeSwitch ( REGION *region, /* IN: Region whose pixel type is to be switched */ PIXDATATYPE type /* IN: Type to switch the pixels to. Allowable types are - S8, U8, S16, U16, S32, U32 */ ) RETURNS: SH_SUCCESS - Operation completed successfully SH_CANT_SWITCH_TYPES - Could not switch the types as requested. A more explanatory error message has been pushed on the error stack.
    
    
    

    shRegPixGetAsDbl

    Return as a double the value of the pixel in REGION at the location specified by ROW and COLUMN. The macro sdss_assert is used to check that ROW and COLUMN are in bounds. See Notes for details about arithmetic operations and region size.

    C SYNTAX: double shRegPixGetAsDbl ( REGION *region, /* IN: Region whose pixels are to be retrieved */ int row, /* IN: Row Number */ int column, /* IN: Column Number */ ) RETURNS: The value of the specified pixel.
    
    
    

    shRegPixSetWithDbl

    Set the pixel in REGION at ROW, COL to the value implied by CONSTANT. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegPixSetWithDbl ( REGION *region, /* MOD: Region whose pixels are to be set */ int row, /* IN : Row number */ int column, /* IN : Column Number */ double constant, /* IN : Number to set */ )
    
    

    shRegSetWithDbl

    Set all of the pixels in REGION to the value implied by CONSTANT. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegSetWithDbl ( double constant, /* IN : Number for initialization */ REGION *region, /* MOD: Region whose pixels are to be set */ )
    
    

    shRegSub

    Subtract SUBTRAHEND from MINUEND pixel-by-pixel. Place the resulting pixels in RESULT. RESULT may be the same region as SUBTRAHEND or MINUEND. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegSub ( REGION *minuend, /* IN : Region */ REGION *subtrahend, /* IN : This Region's pixels are negated */ REGION *result, /* Mod: Pixels are stored here */ )
    
    

    shRegAdd

    Add ADDEND1 to ADDEND2 pixel-by-pixel. Place the resulting pixels in RESULT. RESULT may be the same region as ADDEND1 or ADDEND2. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegAdd ( REGION *addend1, /* IN : First operand Region */ REGION *addend2, /* IN : Second Operand */ REGION *result, /* Mod: Pixels are stored here */ )
    
    
    

    shRegAddWithDbl

    Add CONSTANT to ADDEND pixel-by-pixel. Place the resulting pixels in RESULT. RESULT may be the same region as ADDEND. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegAddWithDbl ( double *constant, /* IN : First operand Region */ REGION *addend, /* IN : Second Operand */ REGION *result, /* Mod: Pixels are stored here */ )
    
    
    
    

    shRegPixCopy

    Copy the pixels from REGIN to REGOUT pixel-by-pixel. REGIN and REGOUT may have any type of pixel. This procedure correctly copies regions which overlap. See Notes for details about arithmetic operations and region size.

    C SYNTAX: void shRegPixCopy ( REGION *regIn, /* IN : Source of pixels */ REGION *regOut, /* Mod: Pixels are stored here */ )
    
    
    
    

    shRegComp

    Compare the pixels in REG1 to REG1 pixel-by-pixel. REGIN and REGOUT may have any type of pixel. If after conversion, a difference is detected, ROWDIFF and COLDIFF are set to the row, col of the difference. See Notes for details about arithmetic operations and region size.

    C SYNTAX: int shRegComp ( REGION *region1, /* IN : Source of pixels */ REGION *region2, /* IN : Source of pixels */ int *rowdiff /* OUT: row number*/ int *colDiff /* OUT: Col number*/ ) RETURNS: 0 - Regions are the same 1 - Regions are different
    
    
    
    

    shRegRowFlip

    Flip the pixels in REGION row-wise. This procedure may be called on regions having any type of pixel. Flipping is done by copying pixels, not by altering row vectors.

    C SYNTAX: void shRegRowFlip ( REGION *region, /* Mod : Region to flip */ )
    
    
    
    

    shRegColFlip

    Flip the pixels in REGION column-wise. This procedure may be called on regions having any type of pixel. Flipping is done by copying pixels.

    C SYNTAX: void shRegColFlip ( REGION *region, /* Mod : Region to flip */ )
    
    
    
    

    shRegMultWithDbl

    Multiply each pixel in REGIN by CONSTANT. Place the result in REGOUT. REGIN and REGOUT my be the same. See Notes for details about arithmetic operations and region size.

    C SYNTAX: int shRegMultWithDbl ( double constant /* IN : Constant */ REGION *regIn, /* IN : Source of pixels */ REGION *regOut, /* MOD : Sink of pixels */ )
    
    
    
    

    shRegMult

    Multiply MULT1 and MULT2 pixel-by-pixel. Divide each pixel by SCALE. Place the result in REGOUT. REGOUT may be the same region as MULT1 or MULT2. See Notes for details about arithmetic operations and region size.

    C SYNTAX: int shRegMult ( double scale /* IN : Constant */ REGION *Mult1, /* IN : Source of pixels */ REGION *Mult2, /* IN : Source of pixels */ REGION *regOut, /* MOD : Sink of pixels */ )
    
    
    
    
    

    shRegDiv

    Divide DIVIDEND by DIVISOR pixel-by-pixel. Multiply the intermediate result by SCALE. Place the result in REGOUT. REGOUT may be the same region as DIVIDEND or DIVISOR. See Notes for details about arithmetic operations and region size.

    C SYNTAX: int shRegDiv ( double scale /* IN : Constant */ REGION *dividend, /* IN : Source of pixels */ REGION *divisor, /* IN : Source of pixels (take the inverse of these) */ REGION *result /* MOD : Sink of pixels */ )