• atRegClippedStatsFind
  • atRegGaussianAdd
  • atRegMap
  • atRegModeFind
  • atRegMedianFindAsDbl
  • atRegStatsFind
  • atRegConvolve
  • atRegSkyFind
  • atRegBin
  • atRegMedianFind
  • atRegClippedMeanFind
  • atRegMedianFindByColumn
  • atRegMedianFindByRow
  • atRegPixValSubstitute
  • atRegCorrectFL32
  • atRegDistortFL32
  • atRegCorrectINT
  • atRegCorrectQuick
  • atRegSigmaClip
  • atRegPixRangeSubstitute
  • atRegMedianSmooth
  • atRegSci

      Science routines that are applied to REGIONs
    
    
    
    

    atRegClippedStatsFind

    DESCRIPTION:
    
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      RET_CODE atRegClippedStatsFind (const REGION *reg, const double lbound,
      	const double ubound, double *mean, double 
      	*sigma, double *high, int *hrow, int *hcol, double *low, int *lrow, 
      	int *lcol)
    

    atRegGaussianAdd

    DESCRIPTION:
    
    Add a 2-D Gaussian profile to an image
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      #define epsilon 1e-12
      
      RET_CODE atRegGaussianAdd(REGION *reg, const double rpos, const double cpos, 
                                const double amplitude, const double rsig, 
                                const double csig, const double radius) 
    

    atRegMap

    DESCRIPTION:
    
    magnify, rotate around a given point, and shift the SOURCE region (in that order) to produce the TARGET region. The rotation is input in radians. For each pixel in the TARGET region, it calculates the corresponding position in the source region. It then uses bilinear interpolation of the closest four pixels to determine the value to be put in the target pixel. If the position is within half a pixel of the edge of the source region, it will simply take the value of the closest pixel. If the pixel is outside the source region, the target region pixel will be set to zero. There is no requirement that the SOURCE and TARGET regions should be the same size.
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      
      RET_CODE atRegMap(const REGION *source, REGION *target, const double rowoff, 
        const double coloff, const double theta, const double rcenter, 
        const double ccenter, const double rowmag, const double colmag) 
    

    atRegModeFind

    DESCRIPTION:
    
    This histograms all of the pixels in a region and finds the most common value. This is only defined for integer region types
    RETURN VALUES:
    
    SH_SUCCESS or SH_GENERIC_ERROR
    SIGNATURE:
      
      RET_CODE atRegModeFind(const REGION *reg,  double min, double max,
      	double *mode) 
    

    atRegMedianFindAsDbl

    DESCRIPTION:
    
    This finds the median pixel in a region
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      
      RET_CODE atRegMedianFindAsDbl(const REGION *reg, double *median) 
    

    atRegStatsFind

    DESCRIPTION:
    
    Finds the mean and sigma on the mean in an image, plus the high and low values and their positions.
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      RET_CODE
      atRegStatsFind (const REGION *reg, double *mean, double *sigma,
              double *high, int *hrow, int *hcol, double *low, int *lrow, int *lcol, double *totalOut) 
    

    atRegConvolve

    DESCRIPTION:
    
    Convolve reg with template to produce target. Normally, the target will be the same size as the input region, and the template will be a small region with an odd number of rows and columns.
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      
      RET_CODE atRegConvolve(const REGION * const reg,
      		   const REGION * const tmplt,
      		   REGION * const target) 
    

    atRegSkyFind

    DESCRIPTION:
    
    Find the sky background in an image by fitting a Gaussian to the peak of a histogram of pixel values
    RETURN VALUES:
    
    Double sky
    SIGNATURE:
      
      
      double atRegSkyFind (const REGION *reg) 
    

    atRegBin

    DESCRIPTION:
    
    A routine to bin an image into larger pixels. Input is the region to be binned, the target region, and the x and y binning factor. If the image size modulo one of the binning factors is not zero, the extra pixels are thrown away. These pixels are always the ones with the high row and column numbers. The output region has one pixel for every summed over group of pixels. If the value of 'normalize' is 1, then divide the sum in each superpixel by the number of original pixels that comprise it.
    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      RET_CODE atRegBin(const REGION *reg, REGION *regtarget, const int rowfactr, 
      	      const int colfactr, const int normalize) 
    

    atRegMedianFind

    DESCRIPTION:
    
    Finds the pixel by pixel median of the number nReg regions. Each pixel from a region is put in a array, the median of the array is found and recorded. Each region should be the same size.

    We check for the special case that all the input regions are type TYPE_U16; in that case, we do not use "shRegPixGetAsDbl", but instead access the pixel data as type U16 directly.

    RETURN VALUES:
    
    SH_SUCCESS
    SIGNATURE:
      
      RET_CODE atRegMedianFind (
        const REGION * const * const apRegSource,   /* Array of pointers to REGIONs */
        const int nReg,			      /* Number of Regions */
        REGION * const pRegTarget)		      /* Pointer to target REGION */
    

    atRegClippedMeanFind

    DESCRIPTION:
    
     Finds the pixel-by-pixel mean from a number 'nReg' regions.  The mean
     can be calculated iteratively, with pixel values more than 'nsigma'
     sigma away from the previous solution ignored and a new mean found. 
     The resulting set of pixel values is placed in the output region.
    
     If clipping correction is requested, the sigma used to clip the data
     is corrected (increased) from the effects of truncation by assuming
     that the underlying distribution is a gaussian.  In other words, if
     a gaussian is edited at N sigma, the wings will be lost and the sigma
     determined from the remaining data will be an underestimate of the
     true sigma.  The '-correct' switch compensates for this if 'nsigma >= 1.5'.
     (see Newberg and Yanny 1997).
    
     All regions must be of the same size and type.  The output region 
     defaults to the first region specified in the list of regions.  If 
     'niter' == 1 no editing of the data occurs, and a simple mean of the
     for each pixel is written into the output region.
    
     We check for the special case that all the input regions are
     type TYPE_U16; in that case, we do not use "shRegPixGetAsDbl",
     but instead access the pixel data as type U16 directly.
    
    RETURN VALUES:
     	SH_SUCCESS
    
    SIGNATURE:
      
      RET_CODE
      atRegClippedMeanFind 
         (
         const REGION * const * const apRegSource,  /* Array of pointers to REGIONs */
         const int nReg,			      /* Number of Regions */
         const int niter,                           /* # of iters in calc clipped mean */
         const double nsigma,                       /* discard values this many stdevs */
                                                    /*   from mean in each iteration */
         REGION * const pRegTarget,		      /* Pointer to output REGION */
         const int clipCorrectFlag                  /* flag to apply sigma clipping correction */
         )
    

    atRegMedianFindByColumn

    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.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegMedianFindByColumn
         (
         REGION *input,          /* I: MxN region from which we calculate medians */
         REGION *output          /* O: 1xN region into which we place medians */
         )
    

    atRegMedianFindByRow

    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 row of the original.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegMedianFindByRow
         (
         REGION *input,          /* I: NxM region from which we calculate medians */
         REGION *output          /* O: Nx1 region into which we place medians */
         )
    

    atRegPixValSubstitute

    DESCRIPTION:
     Given a REGION, a (double) value, and a (double) new value, 
     replace all instances of pixels having 'value' with 'newvalue'.
     The value of compare determines whether only pixels with value
     oldvalue are replaced (compare = 0), or if pixels with values <=
     oldvalue are replaced (compare = 1), or whether pixels with values
     >= oldvalue are replaced (all other values of compare)
    
     This might be used, for example, to remove all instances of 0.0
     from a region, prior to dividing by that region.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegPixValSubstitute
         (
         REGION *reg,            /* I: region in which we subsitute values */
         double oldval,          /* I: we replace any pixel having this value... */
         double newval,          /* I:   ... by this value */
         int compare		   /* I: 0 - substitute only values equal to oldval
      				 1 - substitute values <= oldval
      				 others - substitute values >= oldval */
         )
    

    atRegCorrectFL32

    DESCRIPTION:
     Apply the corrections given in the array CORR to the pixels in REG
     type type of REG must be TYPE_FL32.
    
     Use simple two-point interpolation among the elements of CORR to obtain a
     correction to multiply pixels bigger than firstC and smaller than lastC.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegCorrectFL32
         (
         REGION *reg,           /* I/0: Unsigned 16-bit integer region to correct */
         double *corr,          /* I:   Corrections to multiply to the region */
         int ncorr,		  /* I:   number of corrections */
         float firstC,	  /* I:   first correction is for this pixel value*/
         float lastC		  /* I:   last correction is for this pixel value */
         )
    

    atRegDistortFL32

    DESCRIPTION:
     Apply the inverse corrections given in the array CORR to the pixels in REG
     type of REG must be TYPE_FL32.
    
     Use simple two-point interpolation among the elements of CORR to obtain a
     correction to multiply pixels bigger than firstC and smaller than lastC.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegDistortFL32
         (
         REGION *reg,           /* I/0: FL32  region to distort */
         double *corr,          /* I:   Corrections to multiply to the region */
         int ncorr,		  /* I:   number of corrections */
         float firstC,	  /* I:   first correction is for this pixel value*/
         float lastC		  /* I:   last correction is for this pixel value */
         )
    

    atRegCorrectINT

    DESCRIPTION:
     Muliply the corrections given in the array CORR to the pixels in REG.
     The type of REG may not be TYPE_FL32. The routine treats the type U16
     as a special optimised case -- regions of other types are handled through
     regPixGetAsDbl. Fractional pixles are dithered in. The thing is too slow,
     due to the necessity of manufaturing random numbers. Maybe they should be 
     cached and re-used. 
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE atRegCorrectINT(
      		    REGION *reg , /* I/0: Unsigned 16-bit integer region to 
      				    correct */
      		    double *corr, /* I:  Corrections to multiply to the 
      				     region */
      		    int ncorr,    /* I:   number of corrections */
      		    int firstC	  /* I:   first correction is for this pixel 
      				     value*/
      		    )
    

    atRegCorrectQuick

    DESCRIPTION:
     Muliply the corrections given in the array CORR to the pixels in REG.
     The type of REG must be TYPE_U16. 
     Fractional pixels are dithered in. 
    
     The difference between this and the "atRegCorrectINT" routine is that
     "atRegCorrectINT" generates a random number for every pixel in the 
     REGION, while "atRegCorrectQuick" re-uses a smaller set of random numbers.
    
     We make a pair of tables, each 65536 elements long:
    
        output[i]     contains the calculated U16 output value appropriate 
                          for an input value of 'i'; that is,
                             output[i] = integer part of (corrected value of i)
    
        dither[i]     contains the fractional part of the correction for
                          an input value of 'i'; that is,
                             dither[i] = (corrected value of i) - output[i]
    
     We use the 'dither' table, in conjunction with a set of random numbers
     uniformly distributed between 0.0 and 1.0, to add an additional 1
     to the output value for _some_ of the input values.
    
     The correction factors 'corr[]' are assumed to be given at uniform
     steps between 'firstC' and 'lastC'.  That is, given 
        firstC =  100
        lastC  = 1000
        ncorr  =   10
     we assume that
                       corr[0] applies at input value 100
                       corr[1] applies at input value 200
                       corr[2] applies at input value 300
    
                       corr[8] applies at input value 900
                       corr[9] applies at input value 1000
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      #undef DEBUG
      
      static U16 regCorrect_output[65536];
      static float regCorrect_dither[65536];
      
      RET_CODE
      atRegCorrectQuick(
      		      REGION *reg,  /* I/0: Unsigned 16-bit integer 
      				      region to correct */
      		      double *corr, /* I:   Corrections to multiply to 
      				       the region */
      		      int ncorr,    /* I:   number of corrections */
      		      int firstC,   /* I:   first correction is for this 
      				       pixel value*/
      		      int lastC     /* I:   last correction is for this 
      				       pixel value */
      		      )
    

    atRegSigmaClip

    DESCRIPTION:
    
    	Find the mean and sigma of the pixels in a region, but only use
     the pixel values within sigma_clip sigma of the mean to calculate these
     numbers.  The routine will iterate number_of_iterations times.
    
     return: SH_SUCCESS          if all goes well
    
    
    SIGNATURE:
      
      RET_CODE atRegSigmaClip(
                      REGION *regPtr,                 /* the data */
                      double sigma_clip,              /* how many sigma */
                      int number_of_iterations,       /* how many times */
                      double *sigma_mean,             /* the sigma-clipped  mean */
                      double *sigma_stddev            /* the sigma-clipped sigma */
              )
      
    

    atRegPixRangeSubstitute

    DESCRIPTION:
     Given a REGION, two (double) values, and a (double) new value, 
     replace all instances of pixels with value inside range with 'newvalue'.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegPixRangeSubstitute
         (
         REGION *reg,            /* I: region in which we subsitute values */
         double minval,          /* I: we replace any pixel greater than this value... */
         double maxval,          /* I: and less than or equal to this value... */
         double newval          /* I:   ... by this value */
         )
    

    atRegMedianSmooth

    DESCRIPTION:
     Smooth a REGION using an nxm median filter.
    
     Return SH_SUCCESS if all goes well, or SH_GENERIC_ERROR if not.
    
     return: SH_SUCCESS          if all goes well
             SH_GENERIC_ERROR    if not
    
    
    SIGNATURE:
      
      RET_CODE
      atRegMedianSmooth
         (
         REGION *input,          
         int m,		/* number of rows to include in filter */
         int n,		/* number of cols to include in filter */
         REGION *output       
         )