Common Pipeline Library Reference Manual  5.3.1
Functions
High level functions to handle apertures

Functions

void cpl_apertures_dump (const cpl_apertures *aperts, FILE *fp)
 Dump a cpl_apertures to an opened file pointer.
cpl_apertures * cpl_apertures_extract (const cpl_image *in, const cpl_vector *sigmas, int *pisigma)
 Simple detection of apertures in an image.
cpl_apertures * cpl_apertures_extract_sigma (const cpl_image *in, double sigma)
 Simple apertures detection in an image using a provided sigma.
cpl_apertures * cpl_apertures_extract_window (const cpl_image *in, const cpl_vector *sigmas, int llx, int lly, int urx, int ury, int *pisigma)
 Simple detection of apertures in an image window.
int cpl_apertures_get_bottom (const cpl_apertures *in, int ind)
 Get the bottommost y position in an aperture.
int cpl_apertures_get_bottom_x (const cpl_apertures *in, int ind)
 Get the x position of the bottommost y position in an aperture.
double cpl_apertures_get_centroid_x (const cpl_apertures *in, int ind)
 Get the x centroid of an aperture.
double cpl_apertures_get_centroid_y (const cpl_apertures *in, int ind)
 Get the y centroid of an aperture.
double cpl_apertures_get_flux (const cpl_apertures *in, int ind)
 Get the flux of an aperture.
int cpl_apertures_get_left (const cpl_apertures *in, int ind)
 Get the leftmost x position in an aperture.
int cpl_apertures_get_left_y (const cpl_apertures *in, int ind)
 Get the y position of the leftmost x position in an aperture.
double cpl_apertures_get_max (const cpl_apertures *in, int ind)
 Get the maximum value of an aperture.
double cpl_apertures_get_max_x (const cpl_apertures *in, int ind)
 Get the x position of an aperture.
double cpl_apertures_get_max_y (const cpl_apertures *in, int ind)
 Get the y position of an aperture.
double cpl_apertures_get_mean (const cpl_apertures *in, int ind)
 Get the mean value of an aperture.
double cpl_apertures_get_median (const cpl_apertures *in, int ind)
 Get the median value of an aperture.
double cpl_apertures_get_min (const cpl_apertures *in, int ind)
 Get the minimum value of an aperture.
int cpl_apertures_get_npix (const cpl_apertures *in, int ind)
 Get the number of pixels of an aperture.
int cpl_apertures_get_right (const cpl_apertures *in, int ind)
 Get the rightmost x position in an aperture.
int cpl_apertures_get_right_y (const cpl_apertures *in, int ind)
 Get the y position of the rightmost x position in an aperture.
int cpl_apertures_get_size (const cpl_apertures *in)
 Get the number of apertures.
double cpl_apertures_get_stdev (const cpl_apertures *in, int ind)
 Get the std dev. value of an aperture.
int cpl_apertures_get_top (const cpl_apertures *in, int ind)
 Get the topmost y position in an aperture.
int cpl_apertures_get_top_x (const cpl_apertures *in, int ind)
 Get the x position of the topmost y position in an aperture.
cpl_apertures * cpl_apertures_new_from_image (const cpl_image *in, const cpl_image *lab)
 Compute statistics on selected apertures.
cpl_error_code cpl_apertures_sort_by_flux (cpl_apertures *in)
 Sort by decreasing aperture flux.
cpl_error_code cpl_apertures_sort_by_max (cpl_apertures *in)
 Sort by decreasing aperture peak value.
cpl_error_code cpl_apertures_sort_by_npix (cpl_apertures *in)
 Sort by decreasing aperture size.

Detailed Description

The aperture object contains a list of zones in an image. It is typically used to contain the results of an objects detection, or if one wants to work on a very specific zone in an image.

This module provides functions to handle cpl_apertures.


Function Documentation

void cpl_apertures_dump ( const cpl_apertures *  aperts,
FILE *  fp 
)

Dump a cpl_apertures to an opened file pointer.

Parameters:
apertscpl_apertures to dump
fpOpened file pointer, ready to receive data
Returns:
void

This function dumps all informations contained into a cpl_apertures to the passed (opened) file pointer. It is Ok to pass stdout or stderr. If the object is unallocated or contains nothing, this function does nothing.

cpl_apertures* cpl_apertures_extract ( const cpl_image *  in,
const cpl_vector *  sigmas,
int *  pisigma 
)

Simple detection of apertures in an image.

Parameters:
inInput image
sigmasPositive, decreasing sigmas to apply
pisigmaIndex of the sigma that was used or unchanged on error
Returns:
The detected apertures or NULL on error
See also:
cpl_apertures_extract_sigma()

pisigma may be NULL.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in or sigmas is NULL
  • CPL_ERROR_DATA_NOT_FOUND if the apertures cannot be detected
cpl_apertures* cpl_apertures_extract_sigma ( const cpl_image *  in,
double  sigma 
)

Simple apertures detection in an image using a provided sigma.

Parameters:
inInput image
sigmadetection level
Returns:
The list of detected apertures or NULL if nothing detected or in error case.

The threshold used for the detection is the median plus the average distance to the median times sigma.

The input image type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if sigma is negative or 0.0
  • CPL_ERROR_ILLEGAL_OUTPUT if the image cannot be binarised or labelised
cpl_apertures* cpl_apertures_extract_window ( const cpl_image *  in,
const cpl_vector *  sigmas,
int  llx,
int  lly,
int  urx,
int  ury,
int *  pisigma 
)

Simple detection of apertures in an image window.

Parameters:
inInput image
sigmasPositive, decreasing sigmas to apply
llxLower left x position (FITS convention)
llyLower left y position (FITS convention)
urxUpper right x position (FITS convention)
uryUpper right y position (FITS convention)
pisigmaIndex of the sigma that was used or undefined on error
Returns:
The list of detected apertures or NULL on error
See also:
cpl_apertures_extract()
cpl_image_extract()
int cpl_apertures_get_bottom ( const cpl_apertures *  in,
int  ind 
)

Get the bottommost y position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the bottommost y position in the aperture or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_bottom_x ( const cpl_apertures *  in,
int  ind 
)

Get the x position of the bottommost y position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the bottommost x position of the aperture or -1 on error
Note:
An aperture may have multiple bottom x positions, in which case one of these is returned.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_centroid_x ( const cpl_apertures *  in,
int  ind 
)

Get the x centroid of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the x centroid position of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_centroid_y ( const cpl_apertures *  in,
int  ind 
)

Get the y centroid of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the y centroid position of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_flux ( const cpl_apertures *  in,
int  ind 
)

Get the flux of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the flux of the aperture
See also:
cpl_apertures_get_mean()
int cpl_apertures_get_left ( const cpl_apertures *  in,
int  ind 
)

Get the leftmost x position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the leftmost x position of the aperture or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_left_y ( const cpl_apertures *  in,
int  ind 
)

Get the y position of the leftmost x position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the y position of the leftmost x position or -1 on error
Note:
An aperture may have multiple leftmost x positions, in which case one of these is returned.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_max ( const cpl_apertures *  in,
int  ind 
)

Get the maximum value of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the maximum value of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_max_x ( const cpl_apertures *  in,
int  ind 
)

Get the x position of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the x position of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_max_y ( const cpl_apertures *  in,
int  ind 
)

Get the y position of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the y position of the aperture
See also:
cpl_apertures_get_max_x()
double cpl_apertures_get_mean ( const cpl_apertures *  in,
int  ind 
)

Get the mean value of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the mean value of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
double cpl_apertures_get_median ( const cpl_apertures *  in,
int  ind 
)

Get the median value of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the median value of the aperture
See also:
cpl_apertures_get_mean()
double cpl_apertures_get_min ( const cpl_apertures *  in,
int  ind 
)

Get the minimum value of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the minimum value of the aperture

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 an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_npix ( const cpl_apertures *  in,
int  ind 
)

Get the number of pixels of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the number of pixels of the aperture or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_right ( const cpl_apertures *  in,
int  ind 
)

Get the rightmost x position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the rightmost x position in an aperture or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_right_y ( const cpl_apertures *  in,
int  ind 
)

Get the y position of the rightmost x position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the y position of the rightmost x position or -1 on error
Note:
An aperture may have multiple rightmost x positions, in which case one of these is returned.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_size ( const cpl_apertures *  in)

Get the number of apertures.

Parameters:
ina cpl_apertures object
Returns:
the number of apertures or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
double cpl_apertures_get_stdev ( const cpl_apertures *  in,
int  ind 
)

Get the std dev. value of an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the standard deviation of the aperture
See also:
cpl_apertures_get_mean()
int cpl_apertures_get_top ( const cpl_apertures *  in,
int  ind 
)

Get the topmost y position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the topmost y position in the aperture or -1 on error

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
int cpl_apertures_get_top_x ( const cpl_apertures *  in,
int  ind 
)

Get the x position of the topmost y position in an aperture.

Parameters:
ina cpl_apertures object
indthe aperture index (1 for the first one)
Returns:
the x position of the topmost y position or -1 on error
Note:
An aperture may have multiple topmost x positions, in which case one of these is returned.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if ind is out of the bounds of in
cpl_apertures* cpl_apertures_new_from_image ( const cpl_image *  in,
const cpl_image *  lab 
)

Compute statistics on selected apertures.

Parameters:
inReference image.
lablabelized image (type CPL_TYPE_INT)
Returns:
An apertures statistics holder or NULL on error

The returned object must be deleted using cpl_apertures_delete().

The labelized image must contain at least one pixel for each successive values from 1 to its maximum value.

For the centroiding computation of an aperture, if some pixels have values lower or equal to 0, all the values of the aperture are locally shifted such as the minimum value of the aperture has a value of epsilon. The centroid is then computed on these positive values. In principle, centroid should always be computed on positive values, this is done to avoid raising an error in case the caller of the function wants to use it on negative values images without caring about the centroid results. In such cases, the centroid result would be meaningful, but slightly depend on the hardcoded value chosen for epsilon (1e-8).

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL
  • CPL_ERROR_TYPE_MISMATCH if lab is not of type CPL_TYPE_INT
  • CPL_ERROR_ILLEGAL_INPUT if lab maximum value is lower or equal to 0
  • CPL_ERROR_INCOMPATIBLE_INPUT if lab and in have different sizes.
  • CPL_ERROR_DATA_NOT_FOUND if one of the lab values is missing.
cpl_error_code cpl_apertures_sort_by_flux ( cpl_apertures *  in)

Sort by decreasing aperture flux.

Parameters:
inApertures to sort (MODIFIED)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_apertures_sort_by_npix()
cpl_error_code cpl_apertures_sort_by_max ( cpl_apertures *  in)

Sort by decreasing aperture peak value.

Parameters:
inApertures to sort (MODIFIED)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_apertures_sort_by_npix()
cpl_error_code cpl_apertures_sort_by_npix ( cpl_apertures *  in)

Sort by decreasing aperture size.

Parameters:
inApertures to sort (MODIFIED)
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if an input pointer is NULL