Common Pipeline Library Reference Manual  5.3.1
Functions
Statistics

Functions

void cpl_stats_delete (cpl_stats *stats)
 Free memory associated to an cpl_stats object.
cpl_error_code cpl_stats_dump (const cpl_stats *self, unsigned bitmask, FILE *stream)
 Dump a cpl_stats object.
double cpl_stats_get_absflux (const cpl_stats *in)
 Get the absolute flux from a cpl_stats object.
double cpl_stats_get_centroid_x (const cpl_stats *in)
 Get the x centroid position from a cpl_stats object.
double cpl_stats_get_centroid_y (const cpl_stats *in)
 Get the y centroid position from a cpl_stats object.
double cpl_stats_get_flux (const cpl_stats *in)
 Get the flux from a cpl_stats object.
double cpl_stats_get_max (const cpl_stats *in)
 Get the maximum from a cpl_stats object.
int cpl_stats_get_max_x (const cpl_stats *in)
 Get the maximum x position from a cpl_stats object.
int cpl_stats_get_max_y (const cpl_stats *in)
 Get the maximum y position from a cpl_stats object.
double cpl_stats_get_mean (const cpl_stats *in)
 Get the mean from a cpl_stats object.
double cpl_stats_get_median (const cpl_stats *in)
 Get the median from a cpl_stats object.
double cpl_stats_get_median_dev (const cpl_stats *in)
 Get the median deviation from a cpl_stats object.
double cpl_stats_get_min (const cpl_stats *in)
 Get the minimum from a cpl_stats object.
int cpl_stats_get_min_x (const cpl_stats *in)
 Get the minimum x position from a cpl_stats object.
int cpl_stats_get_min_y (const cpl_stats *in)
 Get the minimum y position from a cpl_stats object.
int cpl_stats_get_npix (const cpl_stats *in)
 Get the number of pixels from a cpl_stats object.
double cpl_stats_get_sqflux (const cpl_stats *in)
 Get the sum of the squared values from a cpl_stats object.
double cpl_stats_get_stdev (const cpl_stats *in)
 Get the std. dev. from a cpl_stats object.
cpl_stats * cpl_stats_new_from_image (const cpl_image *image, unsigned bitmask)
 Compute various statistics of an image.
cpl_stats * cpl_stats_new_from_image_window (const cpl_image *image, unsigned bitmask, int llx, int lly, int urx, int ury)
 Compute various statistics of an image sub-window.

Detailed Description

This module provides functions to handle the cpl_stats object. This object can contain the statistics that have been computed from different CPL objects. Currently, only the function that computes statistics on images (or images windows) is provided.

Synopsis:
   #include "cpl_stats.h"

Function Documentation

void cpl_stats_delete ( cpl_stats *  stats)

Free memory associated to an cpl_stats object.

Parameters:
statsthe object to delete
Returns:
void

Frees all memory associated to a cpl_stats object. If the object stats is NULL, nothing is done and no error is set.

cpl_error_code cpl_stats_dump ( const cpl_stats *  self,
unsigned  bitmask,
FILE *  stream 
)

Dump a cpl_stats object.

Parameters:
selfcpl_stats object to dump
bitmaskDefines which parameters have to be dumped.
streamThe output stream
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_
See also:
cpl_stats_new_from_image_window()

It is an error to request parameters that have not been set.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if bitmask specifies statistics that have not been computed
  • CPL_ERROR_FILE_IO if the write fails
double cpl_stats_get_absflux ( const cpl_stats *  in)

Get the absolute flux from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
The absolute flux, or a negative number on error
See also:
cpl_stats_get_min()
double cpl_stats_get_centroid_x ( const cpl_stats *  in)

Get the x centroid position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the x centroid
See also:
cpl_stats_get_min()
double cpl_stats_get_centroid_y ( const cpl_stats *  in)

Get the y centroid position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the y centroid
See also:
cpl_stats_get_min()
double cpl_stats_get_flux ( const cpl_stats *  in)

Get the flux from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the flux
See also:
cpl_stats_get_min()
double cpl_stats_get_max ( const cpl_stats *  in)

Get the maximum from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the maximum value
See also:
cpl_stats_get_min()
int cpl_stats_get_max_x ( const cpl_stats *  in)

Get the maximum x position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the x position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
int cpl_stats_get_max_y ( const cpl_stats *  in)

Get the maximum y position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the y position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
double cpl_stats_get_mean ( const cpl_stats *  in)

Get the mean from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the mean value
See also:
cpl_stats_get_min()
double cpl_stats_get_median ( const cpl_stats *  in)

Get the median from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the median value
See also:
cpl_stats_get_min()
double cpl_stats_get_median_dev ( const cpl_stats *  in)

Get the median deviation from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the median value
See also:
cpl_stats_get_min()
double cpl_stats_get_min ( const cpl_stats *  in)

Get the minimum from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the minimum value

The call that created the cpl_stats object must have determined the minimum value.

In case of error, the _cpl_error_code_ code is set, and the returned double is undefined.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the requested stat has not been computed in in
int cpl_stats_get_min_x ( const cpl_stats *  in)

Get the minimum x position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the x position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
int cpl_stats_get_min_y ( const cpl_stats *  in)

Get the minimum y position from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the y position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
int cpl_stats_get_npix ( const cpl_stats *  in)

Get the number of pixels from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the number of pixels, -1 in error case.

The creation of a cpl_stats object always causes the number of pixels to be determined.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
double cpl_stats_get_sqflux ( const cpl_stats *  in)

Get the sum of the squared values from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the square flux, or a negative number on error
See also:
cpl_stats_get_min()
double cpl_stats_get_stdev ( const cpl_stats *  in)

Get the std. dev. from a cpl_stats object.

Parameters:
inthe cpl_stats object
Returns:
the standard deviation
See also:
cpl_stats_get_min()
cpl_stats* cpl_stats_new_from_image ( const cpl_image *  image,
unsigned  bitmask 
)

Compute various statistics of an image.

Parameters:
imageinput image.
bitmaskDefines which parameters have to be computed
Returns:
1 newly allocated cpl_stats structure or NULL in error case
See also:
cpl_stats_new_from_image_window()
cpl_stats* cpl_stats_new_from_image_window ( const cpl_image *  image,
unsigned  bitmask,
int  llx,
int  lly,
int  urx,
int  ury 
)

Compute various statistics of an image sub-window.

Parameters:
imageInput image.
bitmaskDefines which parameters have to be computed
llxLower left x position (FITS convention)
llyLower left y position (FITS convention)
urxUpper right x position (FITS convention)
uryUpper right y position (FITS convention)
Returns:
1 newly allocated cpl_stats structure or NULL in error case

Compute various images statistics.

The specified bounds are included in the specified region. The user specifies the statistics he wants to get with a bitmask. Possible requested values are:

  • CPL_STATS_MIN
  • CPL_STATS_MAX
  • CPL_STATS_MEAN
  • CPL_STATS_MEDIAN
  • CPL_STATS_MEDIAN_DEV
  • CPL_STATS_STDEV
  • CPL_STATS_FLUX
  • CPL_STATS_ABSFLUX
  • CPL_STATS_SQFLUX
  • CPL_STATS_CENTROID
  • CPL_STATS_MINPOS
  • CPL_STATS_MAXPOS
  • CPL_STATS_ALL or any bitwise combination of these.

E.g. the bitmask would be CPL_STATS_MIN | CPL_STATS_MEDIAN in order to get the minimum and the median of the image.

In the case of CPL_STATS_MIN and CPL_STATS_MAX where more than one set of coordinates share the extremum it is undefined which of those coordinates will be returned.

Images can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT.

For the CPL_STATS_CENTROID computation, if there are negative pixels, the minimum value is added to all the pixels in order to have all pixels with positive values for computation.

The returned object must be deallocated using cpl_stats_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if the defined window is not in the image
  • CPL_ERROR_ILLEGAL_INPUT if the window definition is wrong (e.g llx > urx)
  • CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad
  • CPL_ERROR_INVALID_TYPE if the passed image type is not supported
  • CPL_ERROR_INVALID_TYPE if bitmask is 1, e.g. due to a logical or (||) of the allowed options.
  • CPL_ERROR_UNSUPPORTED_MODE if bitmask is otherwise different from the allowed options.