• regGaussiansAdd
  • regMap
  • regMedianFindAsDbl
  • regModeFind
  • regStatsFind
  • regSigmaClip
  • regConvolve
  • regSkyFind
  • regBin
  • regMedianFind
  • regClippedMeanFind
  • regMedianFindByColumn
  • regMedianFindByRow
  • regPixValSubstitute
  • regPixRangeSubstitute
  • regCorrectWithVec
  • regDistortWithVec
  • regCorrectQuick
  • regMedianSmooth
  • tclRegSci

    ABSTRACT:
    

    RegSci routines perform scientific operations on regions. The routines are intended to be multi-purpose and to act on regions of all types that apply. For example the regSkyFind routine finds the fit peak of a histogram of pixel values in a region. There are many possible algorithms to do this, all of which will give misleading results in some cases. We have chosen one which can be used to give a reasonable result in most cases for development or quality assurance purposes. It is not intended for detailed analysis.

    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. The pixels are retrieved and set in an image using the shRegPixGetAsDbl and shRegPixSetWithDbl routines.

    
    

    regGaussiansAdd

      C ROUTINE CALLED:
                    atRegGaussiansAdd in atRegSci.c
    
    

    Add a Gaussian to a region

    TCL SYNTAX:
      regGaussiansAdd  "<region>" "<listofrowpositions>" "<listofcolumnpositions>" "<listofamplitudes>" "-rsig" "-csig " "-sig" "-radius" 
    
    TCL HELP STRING:
      Add a Gaussian to a region
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : Initial region
      "<listofrowpositions>" : List of row positions
      "<listofcolumnpositions>" : List of column positions
      "<listofamplitudes>" : List of amplitudes to apply
      "-rsig"        : Row sigma of the Gaussians;
                    Default: 1.0
      "-csig "       : Column sigma of the Gaussians;
                    Default: 1.0
      "-sig"         : Sigma; Default: -1.0
      "-radius"      : Radius; Default: -1.0
    
    

    regMap

      C ROUTINE CALLED:
                    atRegMap in atRegSci.c
    
    

    Shift, rotate, and magnify (in that order) the SOURCE region to produce the TARGET region. The rotation is input in degrees. If there is no pixel in the SOURCE region for the corresponding pixel in the TARGET region, a zero will be substituted. There is no requirement that the SOURCE and TARGET regions must be the same size.

    TCL SYNTAX:
      regMap  "<regsource>" "-regtarget" "-rowoff" "-coloff" "-theta" "-rcenter" "-ccenter" "-mag" "-rowmag" "-colmag" 
    
    TCL HELP STRING:
      Magnify, rotate, and shift SOURCE region to produce TARGET region.
    
    TCL ARGUMENTS:
                     : 
      "<regsource>" : Initial region
      "-regtarget"   : Resulting region; Default: create new region
      "-rowoff"      : Offset in pixels; Default: 0.0
      "-coloff"      : Offset in pixels; Default: 0.0
      "-theta"       : Rotation in degrees; Default: 0.0
      "-rcenter"     : Center of rotation; Default: -1.0
      "-ccenter"     : Center of rotation; Default: -1.0
      "-mag"         : Magnification (r&c); Default: -1.0
      "-rowmag"      : Magnification (r only); Default: 1.0
      "-colmag"      : Magnification (c only); Default: 1.0
    
    

    regMedianFindAsDbl

      C ROUTINE CALLED:
                    atRegMedianFindAsDbl in atRegSci.c
    
    

    Find the median pixel in a region.

    TCL SYNTAX:
      regMedianFindAsDbl  "<region>" 
    
    TCL HELP STRING:
      Find the median pixel in a region.
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : Region containing pixels to median
    
    

    regModeFind

      C ROUTINE CALLED:
          atRegModeFind in atRegSci.c
    
    

    Histograms all of the pixels in a region and finds the most common value. This is only defined for integer region types. The minimum and maximum values for the histogram are passed as min and max, respectively. If all the bins have values below min, the value returned is max + 1.

    TCL SYNTAX:
      regModeFind  "<region>" "-min" "-max" 
    
    TCL HELP STRING:
      Histogram all of the pixels in a region and find the most common value.
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : Region containing pixels to histogram
      "-min"         : minimum value; Default: 0.0
      "-max"         : maximum value; Default: 65535.0
    
    

    regStatsFind

      C ROUTINE CALLED:
                    atRegStatsFind in atRegSci.c
    
    

    Finds the mean and sigma on the mean in an image, plus the high and low values and their positions. One of three subroutines is called depending on the presence or absence of flags. If -min/-max are present then atRegClippedStatsFind is called, which computes mean and sigma, throwing out pixels with values above max and below min from the average. Hi/Lo pixel value and position are calculated in this case between min and max. If -nsigma/-niterations are present (niteration>0) then atRegSigmaClip is called, and the mean and sigma are determined iteratively, with values above nsigma thrown out after each iteration. Hi/Lo pixel value and position are calculated in this case without any pixel rejection. (If this option is invoked the clipped mean above is ignored even if the -min/-max flags are present.) If neither of these sets of switches are present, then a straight mean and sigma are calculated.

    TCL SYNTAX:
      regStatsFind  "<region>" "-min" "-max" "-nsigma" "-niterations" 
    
    TCL HELP STRING:
      Find region statistics.  Optional clipping.
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : region to compute stats on
      "-min"         : min pix value for clipping; Default: 0
      "-max"         : max pix value for clipping; Default: 65535
      "-nsigma"      : number of sigma to clip at; Default: 3.0
      "-niterations" : number of iterations for sigma clipping; Default=0
    
    

    regSigmaClip

      C ROUTINE CALLED:
                    atRegSigmaClip in atRegSci.c
    
    

    Over a number of iterations, it finds the sigma, clips out pixels farther away than n sigma and goes on to the next iteration.

    TCL SYNTAX:
      regSigmaClip  "<regName>" "<nsigma>" "<niterations>" 
    
    TCL HELP STRING:
      Finds the mean and variance using a sigma clipping alogorithm. 
    
    TCL ARGUMENTS:
                     : 
      "<regName>"  : The REGION's handle
      "<nsigma>"   : number of sigmas for rejection
      "<niterations>" : number of iterations
    
    

    regConvolve

      C ROUTINE CALLED:
                    atRegConvolve in atRegSci.c
    
    

    Convolve region with template to produce target.

    TCL SYNTAX:
      regConvolve  "<regsource>" "<regconvolve>" "-regtarget" 
    
    TCL HELP STRING:
      Convolve region with template to produce target.
    
    TCL ARGUMENTS:
                     : 
      "<regsource>" : source region
      "<regconvolve>" : convolving region
      "-regtarget"   : target region; Default: create new region
    
    

    regSkyFind

      C ROUTINE CALLED:
                    atRegSkyFind in atRegSci.c
    

    Find the sky background in an image by fitting a Gaussian

    TCL SYNTAX:
      regSkyFind  "<reg>" 
    
    TCL HELP STRING:
      Find the sky background in a region
    
    TCL ARGUMENTS:
                     : 
      "<reg>"      : region
    
    

    regBin

      C ROUTINE CALLED:
                    atRegBin in atRegSci.c
    
    

    Bin an image into larger pixels by an integer factor. Specify one number for both directions or a number for each direction. If the optional 'normalize' flag is given a value of 1, it means the user wants an average value in each superpixel, rather than a sum.

    TCL SYNTAX:
      regBin  "<region>" "-row" "-col" "-both" "-target" "-normalize" 
    
    TCL HELP STRING:
      Bin an image into larger pixels by an integer factor.  
     Specify one number for both directions or a number for each direction.
     Set superpixels to sum of all included pixels unless 'normalize' is 1.
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : 
      "-row"         : Row binning factor
      "-col"         : Column binning factor
      "-both"        : Binning factor or row and column
      "-target"      : Target region; Default: create new region
      "-normalize"   : If 1 use average; Default: 0
    
    

    regMedianFind

      C ROUTINE CALLED:
                    atRegMedianFind in atRegSci.c
    
    

    Find the pixel median of a list of regions

    TCL SYNTAX:
      regMedianFind  "<reglist>" "-regtarget" 
    
    TCL HELP STRING:
      Find the pixel median of a list of regions.
    
    TCL ARGUMENTS:
                     : 
      "<reglist>"  : List of regions
      "-regtarget"   : Target region; Default: 1st region on list
    
    

    regClippedMeanFind

     C ROUTINE CALLED:
        atRegClippedMeanFind in atRegSci.c
    
     

    From a list of input regions determine the mean on a pixel by pixel basis. If 'niter' > 1 find a clipped mean, where pixel values more than 'nsigma' sigma from the previous solution are ignored and a new mean found. The resulting values for each pixel are placed in the output region. If the '-correct' switch is used the sigma used to edit the data is corrected (increased slightly) to compensate for the truncated wings, by assuming the underlying distribution is a gaussian. With this option 'nsigma' >= 1.5.

    TCL SYNTAX:
      regClippedMeanFind  "<reglist>" "<niter>" "<nsigma>" "-regtarget" "-correct" 
    
    TCL HELP STRING:
      Find the clipped mean of each pixel in a list of regions.
    
    TCL ARGUMENTS:
                     : 
      "<reglist>"  : List of regions
      "<niter>"    : Number of iterations in calculation of clipped mean.
      "<nsigma>"   : Discard values more than 'nsigma' times the stdev from the mean.
      "-regtarget"   : Target region (Default: 1st region on list)
      "-correct"     : Turn on clipping sigma correction
    
    

    regMedianFindByColumn

     C ROUTINE CALLED:
     atRegMedianFindByColumn 
     in atRegSci.c.
    
     

    DESCRIPTION: Given a M-row x N-col REGION, and an empty 1-row x N-col REGION, fill the 1xN region with values which are the median value of the pixels in each column of the original.

    TCL SYNTAX:
      regMedianFindByColumn  "<input>" "<output>" 
    
    TCL HELP STRING:
      Make a 1xN region from the median of each column in a region.
    
    TCL ARGUMENTS:
                     : 
      "<input>"    : MxN region from whose cols we calculate median
      "<output>"   : 1xN region into which we place median of each column
    
    

    regMedianFindByRow

     C ROUTINE CALLED:
     atRegMedianFindByRow 
     in atRegSci.c.
    
     

    DESCRIPTION: Given a N-row x M-col REGION, and an empty N-row x 1-col REGION, fill the Nx1 region with values which are the median value of the pixels in each column of the original.

    TCL SYNTAX:
      regMedianFindByRow  "<input>" "<output>" 
    
    TCL HELP STRING:
      Make an Nx1 region from the median of each row in a region.
    
    TCL ARGUMENTS:
                     : 
      "<input>"    : NxM region from whose rows we calculate median
      "<output>"   : Nx1 region into which we place median of each row
    
    

    regPixValSubstitute

     C ROUTINE CALLED:
     atRegPixValSubstitute 
     in atRegSci.c.
    
     

    DESCRIPTION: Given a REGION, a (double) value, and a (double) new value, replace all instances of pixels having 'value' with 'newvalue'.

    TCL SYNTAX:
      regPixValSubstitute  "<reg>" "<oldval>" "<newval>" "-compare" 
    
    TCL HELP STRING:
      replace all occurences of 'oldval' with 'newval'.
    
    TCL ARGUMENTS:
                     : 
      "<reg>"      : region in which we make substitutions
      "<oldval>"   : replace all occurences of this value ...
      "<newval>"   : ... with this value
      "-compare"     : 0: replace pixel=oldval (default)
                     1: replace pixel<=oldval
                     else: replace pixel>=oldval
    
    

    regPixRangeSubstitute

     C ROUTINE CALLED:
     atRegPixRangeSubstitute 
     in atRegSci.c.
    
     

    DESCRIPTION: Given a REGION, the values of all pixels within a given range are replaced with a new value.

    TCL SYNTAX:
      regPixRangeSubstitute  "<reg>" "<minval>" "<maxval>" "<newval>" 
    
    TCL HELP STRING:
      replace all values in range with 'newval'.
    
    TCL ARGUMENTS:
                     : 
      "<reg>"      : region in which we make substitutions
      "<minval>"   : replace all occurences greater than this value ...
      "<maxval>"   : ... and less than this value ...
      "<newval>"   : ... with this value
    
    

    regCorrectWithVec

      C ROUTINE CALLED:
          
          atRegCorrectWithVec in atRegSci.c
    
    

    Multiply corrections specifed in VECTOR to the pixels in a region. The first argument is the region to apply corrections to. The second argument is a VECTOR of corrections. By default, the first element of the VECTOR is the correction to pixels with value is 0, the second is a correction for pixels with value 1, etc. Corrections may be specified as floating point numbers. One imagines, for instance, a list of 65535 corrections...

    If REGION is of type FL32, and the pixel happens to have no fractional part, the corresponding vector element is multiplied to it. If the pixel has a fractional part, a correction is generated by interpolating, and the interpolateded correction is multipled to the pixel.

    If region is of any type othe than FL32, the pixel value is used to look up a correction, and the correction is multipled with the pixel. Any fractional part correction is dithered in. The first pixel in the image is used in the computation of the random seed for the dither making the correction reproduceable.

    The -firstC and -lastC flags may be used to specify the pixel values the first element of Vec and last element of Vec correspond to. In this case the values of vector are assumed to apply to linearly spaced values, with spacing (lastC-firstC)/length, where length is the length of the vector of corrections. Simple two-point interpolation is used among the elements of the correction vector to obtain a correction to multiply pixels by. Pixel values smaller than -firstC and larger than -lastC are left unmodified.

    TCL SYNTAX:
      regCorrectWithVec  "<region>" "<corrections>" "-firstC" "-lastC " 
    
    TCL HELP STRING:
      Multiply pixels in a region by a correction table (i.e., a list).
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : Region containing pixels to correct
      "<corrections>" : vector of corrections
      "-firstC"      : Pixel value for first correction in Vec; Default: 0
      "-lastC "      : Pixel value for last correction in Vec; Default: sizeof(Vec)-1, olny used for FL32 regions
    
    

    regDistortWithVec

      C ROUTINE CALLED:
          
          atRegDistortWithVec in atRegSci.c
    
    

    Multiply inverse corrections specifed in VECTOR to the pixels in a region. The first argument is the region to apply corrections to. The second argument is a VECTOR of corrections. By default, the first element of the VECTOR is the correction to pixels with value is 0, the second is a correction for pixels with value 1, etc. Corrections may be specified as floating point numbers. One imagines, for instance, a list of 65535 orrections...

    Unlike regCorrectWithVec, this only works with a REGION of type FL32.

    The -firstC and -lastC flags may be used to specify the pixel values the first element of Vec and last element of Vec correspond to. In this case the values of vector are assumed to apply to linearly spaced values, with spacing (lastC-firstC)/length, where length is the length of the vector of corrections. Simple two-point interpolation is used among the elements of the correction vector to obtain a correction to multiply pixels by. Pixel values smaller than -firstC and larger than -lastC are left unmodified.

    TCL SYNTAX:
      regDistortWithVec  "<region>" "<corrections>" "-firstC" "-lastC " 
    
    TCL HELP STRING:
      Multiply pixels in a region by inverse of a correction table (i.e., a list).
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : Region containing pixels to correct
      "<corrections>" : vector of corrections
      "-firstC"      : Pixel value for first correction in Vec (def:0)
      "-lastC "      : Pixel value for last correction in Vec (def:sizeof(Vec)-1, only used for FL32 regions
    
    

    regCorrectQuick

      C ROUTINE CALLED:
          
          atRegCorrectQuick in atRegSci.c
    
    

    This routine is a special version of the atRegCorrectWithVec routine that is designed specically for the Monitor Telescope. It should operate more quickly than the other versions, but may yield output REGIONs that have discernible patterns.

    The routine takes as input a type U16 REGION, a VECTOR of correction factors, and a range over which to apply the corrections. The correction factors are assumed to be given for uniform steps between firstC and lastC. For example, given

           firstC = 10000
           lastC  = 50000
           vector = 1.0   1.1   1.2   1.3   1.4     
    
    we would apply a multiplicative correction factor
     
           1.0    to pixels with values < 10,000 (no correction)
           1.0    to pixels with values approx 10,000   
           1.1    to pixels with values approx 20,000
           1.2    to pixels with values approx 30,000
           1.3    to pixels with values approx 40,000
           1.4    to pixels with values approx 50,000
           1.0    to pixels with values > 50,000 (no correction)
    

    The routine uses some form of interpolation (currently simple linear interpolation) to apply intermediate correction factors to the pixels with values between those specified by firstC and lastC.

    Algorithmically, the routine builds two tables with 65536 elements, with one entry for each possible input pixel value. The first table contains the corrected output value i.e. integer part of input*correction factor), and the second contains a floating-point value between 0.0 and 1.0, denoting the fractional portion of the input*correction. To translate input to output values, the routine

          a. sets i = input pixel value
          b. looks up corrected integer portion j = integer_table[i]
          c. looks up corrected fractional portion f = fractional_table[i]
          d. picks a random number R between 0.0 and 1.0
          e. if R > f, adds 1 to j
          f. sets output pixel value to j
    
    TCL SYNTAX:
      regCorrectQuick  "<region>" "<corrections>" "-firstC" "-lastC " 
    
    TCL HELP STRING:
      Multiply pixels in a region by a correction table (i.e., a list).
    
    TCL ARGUMENTS:
                     : 
      "<region>"   : U16 region containing pixels to correct
      "<corrections>" : vector of corrections
      "-firstC"      : Pixel value for first correction in Vec (def:0)
      "-lastC "      : Pixel value for last correction in Vec (def:65535)
    
    

    regMedianSmooth

     C ROUTINE CALLED:
     atRegMedianSmooth 
     in atRegSci.c.
    
     

    DESCRIPTION: Smooth a REGION using a M-row x N-col median filter.

    TCL SYNTAX:
      regMedianSmooth  "<regName>" "<m>" "<n>" "<outRegName>" 
    
    TCL HELP STRING:
      Smooth a REGION using a M-row x N-col median filter
    
    TCL ARGUMENTS:
                     : 
      "<regName>"  : The input REGION's handle
      "<m>"        : Number of rows to use in filter
      "<n>"        : Number of cols to use in filter
      "<outRegName>" : The output REGION's handle