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)
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)
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)
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)
DESCRIPTION:This finds the median pixel in a region
RETURN VALUES:SH_SUCCESS
SIGNATURE: RET_CODE atRegMedianFindAsDbl(const REGION *reg, double *median)
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)
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)
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)
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)
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 */
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 */ )
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 */ )
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 */ )
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 */ )
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 */ )
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 */ )
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*/ )
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 */ )
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 */ )
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 */ )
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 )