Masks of pixels


Functions

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_closing (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological closing.
cpl_mask * cpl_mask_collapse_create (const cpl_mask *in, int dir)
 Collapse 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.
int cpl_mask_count (const cpl_mask *in)
 Get the number of occurences of CPL_BINARY_1.
int cpl_mask_count_window (const cpl_mask *self, int llx, int lly, int urx, int ury)
 Get the number of occurences of CPL_BINARY_1 in a window.
void cpl_mask_delete (cpl_mask *m)
 Delete a cpl_mask.
cpl_error_code cpl_mask_dilation (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological dilation.
cpl_mask * cpl_mask_duplicate (const cpl_mask *in)
 Duplicates a cpl_mask.
cpl_error_code cpl_mask_erosion (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological erosion.
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_mask * cpl_mask_extract_subsample (const cpl_mask *in, int xstep, int ystep)
 Subsample a mask.
cpl_error_code cpl_mask_flip (cpl_mask *in, int angle)
 Flip a mask on a given miror line.
cpl_binary cpl_mask_get (const cpl_mask *in, int xpos, int ypos)
 Get the value of a mask at a given position.
cpl_binary * cpl_mask_get_data (cpl_mask *in)
 Get a pointer to the data part of the mask.
const cpl_binary * cpl_mask_get_data_const (const cpl_mask *in)
 Get a pointer to the data part of the mask.
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.
cpl_boolean cpl_mask_is_empty (const cpl_mask *self)
 Return CPL_TRUE iff a mask has no elements set (to CPL_BINARY_1).
cpl_boolean cpl_mask_is_empty_window (const cpl_mask *self, int llx, int lly, int urx, int ury)
 Return CPL_TRUE iff a mask has no elements set in the window.
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_new (int nx, int ny)
 Create a new cpl_mask.
cpl_error_code cpl_mask_not (cpl_mask *in)
 Performs a logical NOT on a mask.
cpl_error_code cpl_mask_opening (cpl_mask *in, const cpl_matrix *ker)
 Compute a morphological opening.
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_set (cpl_mask *self, int xpos, int ypos, cpl_binary value)
 Set a value in a mask at a given position.
cpl_error_code cpl_mask_shift (cpl_mask *self, int dx, int dy)
 Shift a mask.
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.
cpl_error_code cpl_mask_turn (cpl_mask *self, int rot)
 Rotate a mask by a multiple of 90 degrees counterclockwise.
void * cpl_mask_unwrap (cpl_mask *m)
 Delete a cpl_mask except the data array.
cpl_mask * cpl_mask_wrap (int nx, int ny, cpl_binary *data)
 Create a cpl_mask from existing data.
cpl_error_code cpl_mask_xor (cpl_mask *in1, const cpl_mask *in2)
 Performs a logical XOR between two masks.

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_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_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_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:

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
See also:
cpl_mask_count_window()
Possible _cpl_error_code_ set in this function:

int cpl_mask_count_window ( const cpl_mask *  self,
int  llx,
int  lly,
int  urx,
int  ury 
)

Get the number of occurences of CPL_BINARY_1 in a window.

Parameters:
self The mask to count
llx Lower left x position (FITS convention)
lly Lower left y position (FITS convention)
urx Upper right x position (FITS convention)
ury Upper right y position (FITS convention)
Returns:
the number of occurences of CPL_BINARY_1 or -1 on error
Possible _cpl_error_code_ set in this function:

void cpl_mask_delete ( cpl_mask *  m  ) 

Delete a cpl_mask.

Parameters:
m cpl_mask to delete
Returns:
void
The function deallocates the memory used by the mask m. If m is NULL, nothing is done, and no error is set.

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_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_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_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_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().

Possible _cpl_error_code_ set in this function:

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:

Possible _cpl_error_code_ set in this function:

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_binary* cpl_mask_get_data ( 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:

const cpl_binary* cpl_mask_get_data_const ( 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
See also:
cpl_mask_get_data

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:

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_boolean cpl_mask_is_empty ( const cpl_mask *  self  ) 

Return CPL_TRUE iff a mask has no elements set (to CPL_BINARY_1).

Parameters:
self The mask to search
Returns:
CPL_TRUE iff the mask has no elements set (to CPL_BINARY_1)
See also:
cpl_mask_is_empty_window()
Possible _cpl_error_code_ set in this function:

cpl_boolean cpl_mask_is_empty_window ( const cpl_mask *  self,
int  llx,
int  lly,
int  urx,
int  ury 
)

Return CPL_TRUE iff a mask has no elements set in the window.

Parameters:
self The mask to search
llx Lower left x position (FITS convention)
lly Lower left y position (FITS convention)
urx Upper right x position (FITS convention)
ury Upper right y position (FITS convention)
Returns:
CPL_TRUE iff the mask has no elements set (to CPL_BINARY_1)
Possible _cpl_error_code_ set in this function:

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_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_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_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_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 *  self,
int  xpos,
int  ypos,
cpl_binary  value 
)

Set a value in a mask at a given position.

Parameters:
self 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_code cpl_mask_shift ( cpl_mask *  self,
int  dx,
int  dy 
)

Shift a mask.

Parameters:
self Mask to shift in place
dx Shift in X
dy Shift 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 to CPL_BINARY_1. The shift values have to be valid: -nx < dx < nx and -ny < dy < ny

Possible _cpl_error_code_ set in this function:

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 ones strictly 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_code cpl_mask_turn ( cpl_mask *  self,
int  rot 
)

Rotate a mask by a multiple of 90 degrees counterclockwise.

Parameters:
self Mask to rotate in place
rot The multiple: -1 is a rotation of 90 deg clockwise.
Returns:
CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_
See also:
cpl_image_turn()
rot may be any integer value, its modulo 4 determines the rotation:

Possible _cpl_error_code_ set in this function:

void* cpl_mask_unwrap ( cpl_mask *  m  ) 

Delete a cpl_mask except the data array.

Parameters:
m cpl_mask to delete
Returns:
A pointer to the data array or NULL if the input is NULL.
Note:
The data array must subsequently be deallocated. Failure to do so will result in a memory leak.

cpl_mask* cpl_mask_wrap ( int  nx,
int  ny,
cpl_binary *  data 
)

Create a cpl_mask from existing data.

Parameters:
nx number of element in x direction
ny number of element in y direction
data Pointer to array of nx*ny cpl_binary
Returns:
1 newly allocated cpl_mask or NULL in case of an error
The returned object must be deallocated using cpl_mask_unwrap().

Possible _cpl_error_code_ set in this function:

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 Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7