Common Pipeline Library Reference Manual
5.3.1
|
Functions | |
cpl_error_code | cpl_mask_and (cpl_mask *in1, const cpl_mask *in2) |
Performs a logical AND of one mask onto another. | |
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_error_code | cpl_mask_dump_window (const cpl_mask *self, int llx, int lly, int urx, int ury, FILE *stream) |
Dump a mask. | |
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_filter (cpl_mask *self, const cpl_mask *other, const cpl_mask *kernel, cpl_filter_mode filter, cpl_border_mode border) |
Filter a mask using a binary kernel. | |
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_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 of one mask onto another. | |
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 clockwise. | |
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 of one mask onto another. |
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.
The element indexing follows the FITS convention in the sense that the lower left element in a CPL mask has index (1, 1).
#include "cpl_mask.h"
cpl_error_code cpl_mask_and | ( | cpl_mask * | in1, |
const cpl_mask * | in2 | ||
) |
Performs a logical AND of one mask onto another.
in1 | first mask, to be modified |
in2 | second 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.
in | input mask to filter |
ker | binary kernel (0 for 0, any other value is considered as 1) |
cpl_mask* cpl_mask_collapse_create | ( | const cpl_mask * | in, |
int | dir | ||
) |
Collapse a mask.
in | input mask to collapse |
dir | collapsing direction |
direction 0 collapses along y, producing a nx by 1 mask direction 1 collapses along x, producing a 1 by ny mask
The resulting mask element is set to CPL_BINARY_1 iff all elements of the associated column (resp. row) in the input mask are set to CPL_BINARY_1.
Direction 0 collapse: 1 0 1 Input mask. 0 1 1 0 0 1 ----- 0 0 1 Only the third element is set to CPL_BINARY_1 since all input elements of that column are set to CPL_BINARY_1.
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.
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) |
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.
in | the input mask |
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.
self | The mask to count |
llx | Lower left x position (FITS convention, 1 for leftmost) |
lly | Lower left y position (FITS convention, 1 for lowest) |
urx | Upper right x position (FITS convention) |
ury | Upper right y position (FITS convention) |
Possible _cpl_error_code_ set in this function:
void cpl_mask_delete | ( | cpl_mask * | m | ) |
Delete a cpl_mask.
m | cpl_mask to delete |
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.
in | input mask to filter |
ker | binary kernel (0 for 0, any other value is considered as 1) |
cpl_error_code cpl_mask_dump_window | ( | const cpl_mask * | self, |
int | llx, | ||
int | lly, | ||
int | urx, | ||
int | ury, | ||
FILE * | stream | ||
) |
Dump a mask.
self | mask to dump |
llx | Lower left x position (FITS convention, 1 for leftmost) |
lly | Lower left y position (FITS convention, 1 for lowest) |
urx | Upper right x position (FITS convention) |
ury | Upper right y position (FITS convention) |
stream | Output stream, accepts stdout or stderr |
Possible _cpl_error_code_ set in this function:
cpl_mask* cpl_mask_duplicate | ( | const cpl_mask * | in | ) |
Duplicates a cpl_mask.
in | the mask to duplicate |
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.
in | input mask to filter |
ker | binary kernel (0 for 0, any other value is considered as 1) |
cpl_mask* cpl_mask_extract | ( | const cpl_mask * | in, |
int | llx, | ||
int | lly, | ||
int | urx, | ||
int | ury | ||
) |
Extract a mask from an other one.
in | input mask |
llx | Lower left x position (FITS convention, 1 for leftmost) |
lly | Lower left y position (FITS convention, 1 for lowest) |
urx | Upper right x position (FITS convention) |
ury | Upper right y position (FITS convention) |
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.
in | input mask |
xstep | Take every xstep pixel in x |
ystep | Take every ystep pixel in y |
The returned mask must be deallocated using cpl_mask_delete().
Possible _cpl_error_code_ set in this function:
cpl_error_code cpl_mask_filter | ( | cpl_mask * | self, |
const cpl_mask * | other, | ||
const cpl_mask * | kernel, | ||
cpl_filter_mode | filter, | ||
cpl_border_mode | border | ||
) |
Filter a mask using a binary kernel.
self | Pre-allocated mask to hold the filtered result |
other | Mask to filter |
kernel | Elements to use, if set to CPL_BINARY_1 |
filter | CPL_FILTER_EROSION, CPL_FILTER_DILATION, CPL_FILTER_OPENING, CPL_FILTER_CLOSING |
border | CPL_BORDER_NOP, CPL_BORDER_ZERO or CPL_BORDER_COPY |
The two masks must have equal dimensions.
The kernel must have an odd number of rows and an odd number of columns.
At least one kernel element must be set to CPL_BINARY_1.
For erosion and dilation: In-place filtering is not supported, but the input buffer may overlap all but the 1+h first rows of the output buffer, where 1+2*h is the number of rows in the kernel.
For opening and closing: Opening is implemented as an erosion followed by a dilation, and closing is implemented as a dilation followed by an erosion. As such a temporary, internal buffer the size of self is used. Consequently, in-place opening and closing is supported with no additional overhead, it is achieved by passing the same mask as both self and other.
Supported modes: CPL_FILTER_EROSION, CPL_FILTER_DILATION: CPL_BORDER_NOP, CPL_BORDER_ZERO or CPL_BORDER_COPY.
CPL_FILTER_OPENING, CPL_FILTER_CLOSING: CPL_BORDER_ZERO or CPL_BORDER_COPY.
Duality and idempotency: Erosion and Dilation have the duality relations: not(dil(A,B)) = er(not(A), B) and not(er(A,B)) = dil(not(A), B).
Opening and closing have similar duality relations: not(open(A,B)) = close(not(A), B) and not(close(A,B)) = open(not(A), B).
Opening and closing are both idempotent, i.e. open(A,B) = open(open(A,B),B) and close(A,B) = close(close(A,B),B).
The above duality and idempotency relations do _not_ hold on the mask border (with the currently supported border modes).
Unnecessary large kernels: Adding an empty border to a given kernel should not change the outcome of the filtering. However doing so widens the border of the mask to be filtered and therefore has an effect on the filtering of the mask border. Since an unnecessary large kernel is also more costly to apply, such kernels should be avoided.
cpl_mask * kernel = cpl_mask_new(1, 3); cpl_mask_not(kernel); cpl_mask_filter(filtered, raw, kernel, CPL_FILTER_EROSION, CPL_BORDER_NOP); cpl_mask_delete(kernel);
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.
in | mask to flip |
angle | mirror line in polar coord. is theta = (PI/4) * angle |
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.
in | the input mask |
xpos | x position (FITS convention) |
ypos | y position (FITS convention) |
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.
in | the input mask |
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.
in | the input mask |
int cpl_mask_get_size_x | ( | const cpl_mask * | in | ) |
Get the x size of the mask.
in | the input mask |
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.
in | the input mask |
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)
self | The mask to search |
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.
self | The mask to search |
llx | Lower left x position (FITS convention, 1 for leftmost) |
lly | Lower left y position (FITS convention, 1 for lowest) |
urx | Upper right x position (FITS convention) |
ury | Upper right y position (FITS convention) |
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.
in | mask to collapse |
nb_cut | the number of cut in x and y |
new_pos | array with the nb_cut^2 new positions |
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_code cpl_mask_not | ( | cpl_mask * | in | ) |
Performs a logical NOT on a mask.
in | mask to be modified |
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.
in | input mask to filter |
ker | binary kernel (0 for 0, any other value is considered as 1) |
cpl_error_code cpl_mask_or | ( | cpl_mask * | in1, |
const cpl_mask * | in2 | ||
) |
Performs a logical OR of one mask onto another.
in1 | first mask, to be modified |
in2 | second mask |
Possible _cpl_error_code_ set in this function:
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.
self | the input mask |
xpos | x position (FITS convention) |
ypos | y position (FITS convention) |
value | the value to set in the mask |
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.
self | Mask to shift in place |
dx | Shift in X |
dy | Shift in Y |
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.
in | Image to threshold. |
lo_cut | Lower bound for threshold. |
hi_cut | Higher bound for threshold. |
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 clockwise.
self | Mask to rotate in place |
rot | The multiple: -1 is a rotation of 90 deg counterclockwise. |
rot may be any integer value, its modulo 4 determines the rotation:
The definition of the rotation relies on the FITS convention: The lower left corner of the image is at (1,1), x increasing from left to right, y increasing from bottom to top.
Possible _cpl_error_code_ set in this function:
void* cpl_mask_unwrap | ( | cpl_mask * | m | ) |
Delete a cpl_mask except the data array.
m | cpl_mask to delete |
cpl_mask* cpl_mask_wrap | ( | int | nx, |
int | ny, | ||
cpl_binary * | data | ||
) |
Create a cpl_mask from existing data.
nx | number of element in x direction |
ny | number of element in y direction |
data | Pointer to array of nx*ny cpl_binary |
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 of one mask onto another.
in1 | first mask, to be modified |
in2 | second mask |
Possible _cpl_error_code_ set in this function: