Main Page | Modules | Alphabetical List | Class List | Class Members

Masks of pixels


Functions

cpl_mask * cpl_mask_new (int nx, int ny)
 Create a new cpl_mask.
cpl_mask * cpl_mask_duplicate (const cpl_mask *in)
 Duplicates a cpl_mask.
void cpl_mask_delete (cpl_mask *m)
 Delete a cpl_mask.
cpl_binary * cpl_mask_get_data (const cpl_mask *in)
 Get a pointer to the data part of the mask.
cpl_binary cpl_mask_get (const cpl_mask *in, int xpos, int ypos)
 Get the value of a mask at a given position.
cpl_error_code cpl_mask_set (cpl_mask *in, int xpos, int ypos, cpl_binary value)
 Set a value in a mask at a given position.
int cpl_mask_get_size_x (const cpl_mask *in)
 Get the x size of the mask.
int cpl_mask_get_size_y (const cpl_mask *in)
 Get the y size of the mask.
int cpl_mask_count (const cpl_mask *in)
 Get the number of occurences of CPL_BINARY_1.
cpl_error_code cpl_mask_and (cpl_mask *in1, const cpl_mask *in2)
 Performs a logical AND between two masks.
cpl_error_code cpl_mask_or (cpl_mask *in1, const cpl_mask *in2)
 Performs a logical OR between two masks.
cpl_error_code cpl_mask_xor (cpl_mask *in1, const cpl_mask *in2)
 Performs a logical XOR between two masks.
cpl_error_code cpl_mask_not (cpl_mask *in)
 Performs a logical NOT on a mask.
cpl_mask * cpl_mask_collapse_create (const cpl_mask *in, int dir)
 Collapse a mask.
cpl_mask * cpl_mask_extract (const cpl_mask *in, int llx, int lly, int urx, int ury)
 Extract a mask from an other one.
cpl_error_code cpl_mask_turn (cpl_mask *in, int rot)
 Rotate a mask by a multiple of 90 deg clockwise.
cpl_error_code cpl_mask_shift (cpl_mask *in, int x_shift, int y_shift)
 Shift a mask.
cpl_error_code cpl_mask_copy (cpl_mask *in1, const cpl_mask *in2, int x_pos, int y_pos)
 Insert a mask in an other one.
cpl_error_code cpl_mask_flip (cpl_mask *in, int angle)
 Flip a mask on a given miror line.
cpl_error_code cpl_mask_move (cpl_mask *in, int nb_cut, const int *new_pos)
 Reorganize the pixels in a mask.
cpl_mask * cpl_mask_extract_subsample (const cpl_mask *in, int xstep, int ystep)
 Subsample a mask.
cpl_error_code cpl_mask_opening (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological opening.
cpl_error_code cpl_mask_closing (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological closing.
cpl_error_code cpl_mask_erosion (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological erosion.
cpl_error_code cpl_mask_dilation (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological dilation.
cpl_mask * cpl_mask_threshold_image_create (const cpl_image *in, double lo_cut, double hi_cut)
 Select parts of an image with provided thresholds.

Detailed Description

This module provides functions to handle masks of pixels

These masks are useful for object detection routines or bad pixel map handling. Morphological routines (erosion, dilation, closing and opening) and logical operations are provided. A cpl_mask is a kind of binary array whose elements are of type cpl_binary and can take only two values: either CPL_BINARY_0 or CPL_BINARY_1.

Synopsis:
   #include "cpl_mask.h"

Function Documentation

cpl_error_code cpl_mask_and cpl_mask *  in1,
const cpl_mask *  in2
 

Performs a logical AND between two masks.

Parameters:
in1 first mask
in2 second mask
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The result is stored in the first mask.

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 input masks have different sizes

cpl_error_code cpl_mask_closing cpl_mask *  in,
const cpl_matrix *  ker
 

Compute a morphological closing.

Parameters:
in input mask
ker binary kernel (0 for 0, any other value is considered as 1)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The morphological closing is a dilation followed by an erosion. The input mask is modified. The input kernel should have an odd number of rows and columns. The maximum size of the kernel is 31x31.

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 kernel is such that the erosion or the dilation cannot be done

cpl_mask* cpl_mask_collapse_create const cpl_mask *  in,
int  dir
 

Collapse a mask.

Parameters:
in input mask to collapse
dir collapsing direction
Returns:
the newly allocated mask or NULL in error case
The returned mask must be deallocated using cpl_mask_delete(). direction 0 is to collapse along y (sum of rows), 1 is along x. The resulting mask element is set to 1 if all element of the associated column (resp. row) in the input mask are set to 1.

  Collapse along y:

  1 0 1    Input mask.
  0 1 1
  0 0 1
  -----
  0 0 1    The third element is flagged as bad because all elements of the
           column are bad.
  

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT

cpl_error_code cpl_mask_copy cpl_mask *  in1,
const cpl_mask *  in2,
int  x_pos,
int  y_pos
 

Insert a mask in an other one.

Parameters:
in1 mask in which in2 is inserted
in2 mask to insert
x_pos the x pixel position in in1 where the lower left pixel of in2 should go (from 1 to the x size of in1)
y_pos the y pixel position in in1 where the lower left pixel of in2 should go (from 1 to the y size of in1)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if in1 or in2 is NULL
  • CPL_ERROR_ILLEGAL_INPUT if x_pos, y_pos is outside in1

int cpl_mask_count const cpl_mask *  in  ) 
 

Get the number of occurences of CPL_BINARY_1.

Parameters:
in the input mask
Returns:
the number of occurences of CPL_BINARY_1 or -1 in error case
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

void cpl_mask_delete cpl_mask *  m  ) 
 

Delete a cpl_mask.

Parameters:
m cpl_mask to delete
Returns:
void

cpl_error_code cpl_mask_dilation cpl_mask *  in,
const cpl_matrix *  ker
 

Compute a morphological dilation.

Parameters:
in input mask
ker binary kernel (0 for 0, any other value is considered as 1)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The input mask is modified. The input kernel should have an odd number of rows and columns. The maximum size of the kernel is 31x31.

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 kernel is not as requested

cpl_mask* cpl_mask_duplicate const cpl_mask *  in  ) 
 

Duplicates a cpl_mask.

Parameters:
in the mask to duplicate
Returns:
1 newly allocated cpl_mask or NULL in error case
The returned object must be deallocated using cpl_mask_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in is NULL

cpl_error_code cpl_mask_erosion cpl_mask *  in,
const cpl_matrix *  ker
 

Compute a morphological erosion.

Parameters:
in input mask
ker binary kernel (0 for 0, any other value is considered as 1)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The input mask is modified. The input kernel should have an odd number of rows and columns. The maximum size of the kernel is 31x31.

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 kernel is not as requested

cpl_mask* cpl_mask_extract const cpl_mask *  in,
int  llx,
int  lly,
int  urx,
int  ury
 

Extract a mask from an other one.

Parameters:
in input mask
llx coordinates of the extracted mask
lly 
urx 
ury 
Returns:
1 newly allocated mask or NULL in error case.
The returned mask must be deallocated using cpl_mask_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_ILLEGAL_INPUT if the zone falls outside the mask
  • CPL_ERROR_NULL_INPUT if the input mask is NULL

cpl_mask* cpl_mask_extract_subsample const cpl_mask *  in,
int  xstep,
int  ystep
 

Subsample a mask.

Parameters:
in input mask
xstep Take every xstep pixel in x
ystep Take every ystep pixel in y
Returns:
the newly allocated mask or NULL on error case
See also:
cpl_image_extract_subsample()
The returned mask must be deallocated using cpl_mask_delete(). Currently xstep must equal ystep. Currently, both the X- and Y-size of the mask must be divisible by the step.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in is NULL
  • CPL_ERROR_ILLEGAL_INPUT if xstep and ystep are not as requested.

cpl_error_code cpl_mask_flip cpl_mask *  in,
int  angle
 

Flip a mask on a given miror line.

Parameters:
in mask to flip
angle mirror line in polar coord. is theta = (PI/4) * angle
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
angle can take one of the following values:
  • 0 (theta=0) to flip the image around the horizontal
  • 1 (theta=pi/4) to flip the image around y=x
  • 2 (theta=pi/2) to flip the image around the vertical
  • 3 (theta=3pi/4) to flip the image around y=-x

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in is NULL
  • CPL_ERROR_ILLEGAL_INPUT if angle is not as specified

cpl_binary cpl_mask_get const cpl_mask *  in,
int  xpos,
int  ypos
 

Get the value of a mask at a given position.

Parameters:
in the input mask
xpos x position (FITS convention)
ypos y position (FITS convention)
Returns:
The mask value or undefined if an error code is set
The mask value can be either CPL_BINARY_0 or CPL_BINARY_1

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 xpos or ypos is out of bounds

cpl_binary* cpl_mask_get_data const cpl_mask *  in  ) 
 

Get a pointer to the data part of the mask.

Parameters:
in the input mask
Returns:
Pointer to the data or NULL in error case
The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

int cpl_mask_get_size_x const cpl_mask *  in  ) 
 

Get the x size of the mask.

Parameters:
in the input mask
Returns:
The mask x size, or -1 on NULL input
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

int cpl_mask_get_size_y const cpl_mask *  in  ) 
 

Get the y size of the mask.

Parameters:
in the input mask
Returns:
The mask y size, or -1 on NULL input
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

cpl_error_code cpl_mask_move cpl_mask *  in,
int  nb_cut,
const int *  new_pos
 

Reorganize the pixels in a mask.

Parameters:
in mask to collapse
nb_cut the number of cut in x and y
new_pos array with the nb_cut^2 new positions
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_move()
nb_cut must be positive and divide the size of the input mask in x and y.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in or new_pos is NULL
  • CPL_ERROR_ILLEGAL_INPUT if nb_cut is not as requested.

cpl_mask* cpl_mask_new int  nx,
int  ny
 

Create a new cpl_mask.

Parameters:
nx number of element in x direction
ny number of element in y direction
Returns:
1 newly allocated cpl_mask or NULL in error case
The created cpl_mask elements are all set to CPL_BINARY_0.

The returned object must be deallocated using cpl_mask_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_ILLEGAL_INPUT if nx or ny is negative

cpl_error_code cpl_mask_not cpl_mask *  in  ) 
 

Performs a logical NOT on a mask.

Parameters:
in input mask
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

cpl_error_code cpl_mask_opening cpl_mask *  in,
const cpl_matrix *  ker
 

Compute a morphological opening.

Parameters:
in input mask
ker binary kernel (0 for 0, any other value is considered as 1)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The morphological opening is an erosion followed by a dilation. The input mask is modified. The input kernel should have an odd number of rows and columns. The maximum size of the kernel is 31x31.

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 kernel is such that the erosion or the dilation cannot be done

cpl_error_code cpl_mask_or cpl_mask *  in1,
const cpl_mask *  in2
 

Performs a logical OR between two masks.

Parameters:
in1 first mask
in2 second mask
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_mask_and()

cpl_error_code cpl_mask_set cpl_mask *  in,
int  xpos,
int  ypos,
cpl_binary  value
 

Set a value in a mask at a given position.

Parameters:
in the input mask
xpos x position (FITS convention)
ypos y position (FITS convention)
value the value to set in the mask
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The value can be either CPL_BINARY_0 or CPL_BINARY_1

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 xpos or ypos is out of bounds or if value is different from CPL_BINARY_0 and CPL_BINARY_1

cpl_error_code cpl_mask_shift cpl_mask *  in,
int  x_shift,
int  y_shift
 

Shift a mask.

Parameters:
in mask to shift
x_shift shift to apply in x
y_shift shift to apply in y
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_turn()
The 'empty zone' in the shifted mask is set as bad pixels. The shift values have to be valid: -nx<x_shift<nx and -ny<y_shift<ny

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if in is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the offsets are too big

cpl_mask* cpl_mask_threshold_image_create const cpl_image *  in,
double  lo_cut,
double  hi_cut
 

Select parts of an image with provided thresholds.

Parameters:
in Image to threshold.
lo_cut Lower bound for threshold.
hi_cut Higher bound for threshold.
Returns:
1 newly allocated mask or NULL in error case
Create a mask from an image. Selected areas are the one inside the provided interval. The input image type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT. The returned mask must be deallocated with cpl_mask_delete()

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

cpl_error_code cpl_mask_turn cpl_mask *  in,
int  rot
 

Rotate a mask by a multiple of 90 deg clockwise.

Parameters:
in mask to rotate
rot the mutiple: -1 is a rotation of 90 deg counterclockwise.
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_turn()
rot can take one of the following values:
  • +1 to turn 90 degrees clockwise.
  • -1 to turn 90 degrees counterclockwise.
  • +2 to turn 180 degrees.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_ILLEGAL_INPUT if rot is not as specified
  • CPL_ERROR_NULL_INPUT if in is NULL

cpl_error_code cpl_mask_xor cpl_mask *  in1,
const cpl_mask *  in2
 

Performs a logical XOR between two masks.

Parameters:
in1 first mask
in2 second mask
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_mask_and()


Generated on Sat Mar 24 01:33:19 2007 for Common Pipeline Library Reference Manual by  doxygen 1.3.9.1