Loading...
Searching...
No Matches
Masks of pixels

## 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, cpl_size x_pos, cpl_size y_pos)
| Insert a mask in an other one.
cpl_size | cpl_mask_count (const cpl_mask *in)
| Get the number of occurences of CPL_BINARY_1.
cpl_size | cpl_mask_count_window (const cpl_mask *self, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size 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, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size 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, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Extract a mask from an other one.
cpl_mask * | cpl_mask_extract_subsample (const cpl_mask *in, cpl_size xstep, cpl_size 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 mirror line.
cpl_binary | cpl_mask_get (const cpl_mask *self, cpl_size xpos, cpl_size 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.
cpl_size | cpl_mask_get_size_x (const cpl_mask *in)
| Get the x size of the mask.
cpl_size | 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, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Return CPL_TRUE iff a mask has no elements set in the window.
cpl_mask * | cpl_mask_load (const char *filename, cpl_size pnum, cpl_size xtnum)
| Load a mask from a FITS file.
cpl_mask * | cpl_mask_load_window (const char *filename, cpl_size pnum, cpl_size xtnum, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Load a mask from a FITS file.
cpl_error_code | cpl_mask_move (cpl_mask *in, cpl_size nb_cut, const cpl_size *new_pos)
| Permute tiles in a mask.
cpl_mask * | cpl_mask_new (cpl_size nx, cpl_size 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 of one mask onto another.
cpl_error_code | cpl_mask_save (const cpl_mask *self, const char *filename, const cpl_propertylist *plist, unsigned mode)
| Save a mask to a FITS file.
cpl_error_code | cpl_mask_set (cpl_mask *self, cpl_size xpos, cpl_size ypos, cpl_binary value)
| Set a value in a mask at a given position.
cpl_error_code | cpl_mask_shift (cpl_mask *self, cpl_size dx, cpl_size dy)
| Shift a mask.
cpl_error_code | cpl_mask_threshold_image (cpl_mask *self, const cpl_image *image, double lo_cut, double hi_cut, cpl_binary inval)
| Select parts of an image with provided thresholds.
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 (cpl_size nx, cpl_size 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.

## 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.

The element indexing follows the FITS convention in the sense that the lower left element in a CPL mask has index (1, 1).

Synopsis:
  #include "cpl_mask.h"

## Function Documentation

## cpl_mask_and()

cpl_error_code cpl_mask_and | ( | cpl_mask * | in1,
|  | const cpl_mask * | in2 )

Performs a logical AND of one mask onto another.

Parameters

  in1 | first mask, to be modified
  in2 | second mask

Returns
  CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_

See also
  cpl_image_and()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if the two masks have different sizes

References cpl_ensure_code, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_mask_closing()

cpl_error_code cpl_mask_closing | ( | cpl_mask * | in,
|  | const cpl_matrix * | ker )

Compute a morphological closing.

Parameters

  in | input mask to filter
  ker | binary kernel (0 for 0, any other value is considered as 1)

Returns
  CPL_ERROR_NONE on success or the _cpl_error_code_ on failure

See also
  cpl_mask_filter()

Deprecated
  Replace this call with cpl_mask_filter() using CPL_FILTER_CLOSING and CPL_BORDER_ZERO.

References CPL_BORDER_ZERO, CPL_FILTER_CLOSING, cpl_mask_delete(), and cpl_mask_filter().

## cpl_mask_collapse_create()

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 on error

Note
  The returned mask must be deallocated using cpl_mask_delete().

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_NULL_INPUT
- CPL_ERROR_ILLEGAL_INPUT

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_mask_wrap().

## cpl_mask_copy()

cpl_error_code cpl_mask_copy | ( | cpl_mask * | in1,
|  | const cpl_mask * | in2,
|  | cpl_size | x_pos,
|  | cpl_size | 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

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_mask_get_data(), and cpl_mask_get_data_const().

Referenced by cpl_image_copy(), and cpl_mask_filter().

## cpl_mask_count()

cpl_size 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 on error

See also
  cpl_mask_count_window()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_count_rejected(), and cpl_image_dump_structure().

## cpl_mask_count_window()

cpl_size cpl_mask_count_window | ( | const cpl_mask * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | 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, 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)

Returns
  the number of occurences of CPL_BINARY_1 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 the window coordinates are invalid

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

## cpl_mask_delete()

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.

References cpl_free().

Referenced by cpl_apertures_extract_sigma(), cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_fine(), cpl_image_accept_all(), cpl_image_copy(), cpl_image_delete(), cpl_image_divide(), cpl_image_divide_create(), cpl_image_filter_median(), cpl_image_filter_stdev(), cpl_image_unwrap(), cpl_image_warp(), cpl_image_warp_polynomial(), cpl_imagelist_swap_axis_create(), cpl_mask_closing(), cpl_mask_dilation(), cpl_mask_erosion(), cpl_mask_filter(), cpl_mask_flip(), cpl_mask_move(), cpl_mask_opening(), cpl_mask_threshold_image_create(), cpl_mask_turn(), and cpl_vector_filter_median_create().

## cpl_mask_dilation()

cpl_error_code cpl_mask_dilation | ( | cpl_mask * | in,
|  | const cpl_matrix * | ker )

Compute a morphological dilation.

Parameters

  in | input mask to filter
  ker | binary kernel (0 for 0, any other value is considered as 1)

Returns
  CPL_ERROR_NONE on success or the _cpl_error_code_ on failure

See also
  cpl_mask_filter()

Deprecated
  Replace this call with cpl_mask_filter() using CPL_FILTER_DILATION and CPL_BORDER_ZERO.

References CPL_BORDER_ZERO, CPL_FILTER_DILATION, cpl_mask_delete(), cpl_mask_duplicate(), and cpl_mask_filter().

## cpl_mask_dump_window()

cpl_error_code cpl_mask_dump_window | ( | const cpl_mask * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | FILE * | stream )

Dump a mask.

Parameters

  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`

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_FILE_IO if a write operation fails
- CPL_ERROR_ACCESS_OUT_OF_RANGE if the defined window is not in the mask
- CPL_ERROR_ILLEGAL_INPUT if the window definition is wrong (e.g llx > urx)

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_FILE_IO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_SIZE_FORMAT.

## cpl_mask_duplicate()

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 on error

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

References CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_mask_wrap().

Referenced by cpl_image_average_create(), cpl_image_cast(), cpl_image_divide(), cpl_image_divide_create(), cpl_image_duplicate(), cpl_mask_dilation(), cpl_mask_erosion(), cpl_mask_flip(), cpl_mask_move(), and cpl_mask_turn().

## cpl_mask_erosion()

cpl_error_code cpl_mask_erosion | ( | cpl_mask * | in,
|  | const cpl_matrix * | ker )

Compute a morphological erosion.

Parameters

  in | input mask to filter
  ker | binary kernel (0 for 0, any other value is considered as 1)

Returns
  CPL_ERROR_NONE on success or the _cpl_error_code_ on failure

See also
  cpl_mask_filter()

Deprecated
  Replace this call with cpl_mask_filter() using CPL_FILTER_EROSION and CPL_BORDER_ZERO.

References CPL_BORDER_ZERO, CPL_FILTER_EROSION, cpl_mask_delete(), cpl_mask_duplicate(), and cpl_mask_filter().

## cpl_mask_extract()

cpl_mask * cpl_mask_extract | ( | const cpl_mask * | in,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Extract a mask from an other one.

Parameters

  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)

Returns
  1 newly allocated mask or NULL on error.

Note
  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

References cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_mask_new().

## cpl_mask_extract_subsample()

cpl_mask * cpl_mask_extract_subsample | ( | const cpl_mask * | in,
|  | cpl_size | xstep,
|  | cpl_size | 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_NULL_INPUT if in is NULL
- CPL_ERROR_ILLEGAL_INPUT if xstep and ystep are not greater than zero

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_mask_get_data(), cpl_mask_get_data_const(), and cpl_mask_new().

Referenced by cpl_image_extract_subsample().

## cpl_mask_filter()

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.

Parameters

  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

Returns
  CPL_ERROR_NONE or the relevant CPL error code

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 allocated and 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.

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.

A 1 x 3 erosion filtering example (error checking omitted for brevity)
  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);
  CPL_BORDER_NOP
  @ CPL_BORDER_NOP
  Definition cpl_filter.h:80
  CPL_FILTER_EROSION
  @ CPL_FILTER_EROSION
  Definition cpl_filter.h:112
  cpl_mask_filter
  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.
  Definition cpl_mask.c:2155
  cpl_mask_new
  cpl_mask * cpl_mask_new(cpl_size nx, cpl_size ny)
  Create a new cpl_mask.
  Definition cpl_mask.c:794
  cpl_mask_not
  cpl_error_code cpl_mask_not(cpl_mask *in)
  Performs a logical NOT on a mask.
  Definition cpl_mask.c:1469
  cpl_mask_delete
  void cpl_mask_delete(cpl_mask *m)
  Delete a cpl_mask.
  Definition cpl_mask.c:878

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL.
- CPL_ERROR_ILLEGAL_INPUT if the kernel has a side of even length.
- CPL_ERROR_DATA_NOT_FOUND If the kernel is empty.
- CPL_ERROR_ACCESS_OUT_OF_RANGE If the kernel has a side longer than the input mask.
- CPL_ERROR_INCOMPATIBLE_INPUT If the input and output masks have incompatible sizes.
- CPL_ERROR_UNSUPPORTED_MODE If the output pixel buffer overlaps the input one (or the kernel), or the border/filter mode is unsupported.

References CPL_BORDER_COPY, CPL_BORDER_CROP, CPL_BORDER_NOP, CPL_BORDER_ZERO, cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, CPL_FILTER_CLOSING, CPL_FILTER_DILATION, CPL_FILTER_EROSION, CPL_FILTER_OPENING, cpl_mask_copy(), cpl_mask_delete(), cpl_mask_get_data(), cpl_mask_get_data_const(), cpl_mask_get_size_x(), cpl_mask_get_size_y(), cpl_mask_is_empty(), and cpl_mask_new().

Referenced by cpl_apertures_extract_sigma(), cpl_mask_closing(), cpl_mask_dilation(), cpl_mask_erosion(), and cpl_mask_opening().

## cpl_mask_flip()

cpl_error_code cpl_mask_flip | ( | cpl_mask * | in,
|  | int | angle )

Flip a mask on a given mirror 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

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_mask_delete(), cpl_mask_duplicate(), cpl_mask_get_data(), and cpl_mask_get_data_const().

Referenced by cpl_image_flip().

## cpl_mask_get()

cpl_binary cpl_mask_get | ( | const cpl_mask * | self,
|  | cpl_size | xpos,
|  | cpl_size | ypos )

Get the value of a mask at a given position.

Parameters

  self | The input mask
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)

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 an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if xpos or ypos is out of bounds

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_dump_window(), and cpl_image_is_rejected().

## cpl_mask_get_data()

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 on error

The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_divide(), cpl_image_divide_create(), cpl_image_fill_rejected(), cpl_image_filter(), cpl_image_filter_mask(), cpl_image_rebin(), cpl_image_reject_from_mask(), cpl_image_warp(), cpl_image_warp_polynomial(), cpl_imagelist_swap_axis_create(), cpl_mask_copy(), cpl_mask_extract_subsample(), cpl_mask_filter(), cpl_mask_flip(), cpl_mask_move(), cpl_mask_threshold_image(), and cpl_mask_turn().

## cpl_mask_get_data_const()

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 on error

See also
  cpl_mask_get_data

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_detector_interpolate_rejected(), cpl_image_filter(), cpl_image_filter_mask(), cpl_image_get_interpolated(), cpl_image_labelise_mask_create(), cpl_image_new_from_mask(), cpl_image_rebin(), cpl_image_reject_from_mask(), cpl_image_warp(), cpl_image_warp_polynomial(), cpl_mask_copy(), cpl_mask_extract_subsample(), cpl_mask_filter(), cpl_mask_flip(), cpl_mask_move(), cpl_mask_threshold_image(), cpl_mask_turn(), and cpl_plot_mask().

## cpl_mask_get_size_x()

cpl_size 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 an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter_mask(), cpl_image_filter_stdev(), cpl_image_labelise_mask_create(), cpl_image_new_from_mask(), cpl_image_reject_from_mask(), cpl_mask_filter(), cpl_mask_threshold_image(), and cpl_plot_mask().

## cpl_mask_get_size_y()

cpl_size 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 an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter_mask(), cpl_image_filter_stdev(), cpl_image_labelise_mask_create(), cpl_image_new_from_mask(), cpl_image_reject_from_mask(), cpl_mask_filter(), cpl_mask_threshold_image(), and cpl_plot_mask().

## cpl_mask_is_empty()

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_ERROR_NULL_INPUT if an input pointer is NULL

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_fit_image_gaussian(), cpl_geom_img_offset_saa(), cpl_image_dump_window(), cpl_image_fill_rejected(), cpl_image_filter(), cpl_image_filter_mask(), and cpl_mask_filter().

## cpl_mask_is_empty_window()

cpl_boolean cpl_mask_is_empty_window | ( | const cpl_mask * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | 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, 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)

Returns
  CPL_TRUE iff the mask has no elements set (to CPL_BINARY_1)

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if the window coordinates are not valid

## cpl_mask_load()

cpl_mask * cpl_mask_load | ( | const char * | filename,
|  | cpl_size | pnum,
|  | cpl_size | xtnum )

Load a mask from a FITS file.

Parameters

  filename | Name of the file to load from.
  pnum | Plane number in the Data Unit (0 for first)
  xtnum | Extension number in the file (0 for primary HDU)

Returns
  1 newly allocated mask or NULL on error

See also
  cpl_image_load()

This function loads a mask from a FITS file (NAXIS=2 or 3). Each non-zero pixel is set to CPL_BINARY_1.

The returned mask has to be deallocated with cpl_mask_delete().

'xtnum' specifies from which extension the mask should be loaded. This could be 0 for the main data section (files without extension), or any number between 1 and N, where N is the number of extensions present in the file.

The requested plane number runs from 0 to nplanes-1, where nplanes is the number of planes present in the requested data section.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_FILE_IO if the file cannot be opened or does not exist
- CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file
- CPL_ERROR_ILLEGAL_INPUT if the passed extension number is negative
- CPL_ERROR_DATA_NOT_FOUND if the specified extension has no mask data

## cpl_mask_load_window()

cpl_mask * cpl_mask_load_window | ( | const char * | filename,
|  | cpl_size | pnum,
|  | cpl_size | xtnum,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Load a mask from a FITS file.

Parameters

  filename | Name of the file to load from.
  pnum | Plane number in the Data Unit (0 for first)
  xtnum | Extension number in the file.
  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)

Returns
  1 newly allocated mask or NULL on error

See also
  cpl_mask_load()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_FILE_IO if the file does not exist
- CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file
- CPL_ERROR_ILLEGAL_INPUT if the passed position is invalid

## cpl_mask_move()

cpl_error_code cpl_mask_move | ( | cpl_mask * | in,
|  | cpl_size | nb_cut,
|  | const cpl_size * | new_pos )

Permute tiles in a mask.

Parameters

  in | Mask to modify
  nb_cut | The number of cuts in x and y
  new_pos | Array with the nb_cut^2 permuted positions

Returns
  the _cpl_error_code_ or CPL_ERROR_NONE

See also
  cpl_image_move()

Note
  The permutation array must contain nb_cut-squared elements

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if nb_cut is not strictly positive or cannot divide one of the image sizes or if the new_pos array does not contain a permutation of the values from 1 through nb_cut squared.

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), cpl_malloc(), cpl_mask_delete(), cpl_mask_duplicate(), cpl_mask_get_data(), and cpl_mask_get_data_const().

Referenced by cpl_image_move().

## cpl_mask_new()

cpl_mask * cpl_mask_new | ( | cpl_size | nx,
|  | cpl_size | ny )

Create a new cpl_mask.

Parameters

  nx | The number of elements in the X-direction
  ny | The number of elements in the Y-direction

Returns
  1 newly allocated cpl_mask or NULL on error

Note
  The returned object must be deallocated using cpl_mask_delete().

The created cpl_mask elements are all set to CPL_BINARY_0.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_ILLEGAL_INPUT if nx or ny is negative

References cpl_calloc(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, and cpl_mask_wrap().

Referenced by cpl_apertures_extract_sigma(), cpl_geom_img_offset_fine(), cpl_image_copy(), cpl_image_divide(), cpl_image_divide_create(), cpl_image_get_bpm(), cpl_image_rebin(), cpl_image_shift(), cpl_image_warp(), cpl_image_warp_polynomial(), cpl_imagelist_swap_axis_create(), cpl_mask_extract(), cpl_mask_extract_subsample(), cpl_mask_filter(), cpl_mask_threshold_image_create(), and cpl_vector_filter_median_create().

## cpl_mask_not()

cpl_error_code cpl_mask_not | ( | cpl_mask * | in | ) |

Performs a logical NOT on a mask.

Parameters

  in | mask to be modified

Returns
  CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_

See also
  cpl_image_not()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_apertures_extract_sigma(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), and cpl_vector_filter_median_create().

## cpl_mask_opening()

cpl_error_code cpl_mask_opening | ( | cpl_mask * | in,
|  | const cpl_matrix * | ker )

Compute a morphological opening.

Parameters

  in | input mask to filter
  ker | binary kernel (0 for 0, any other value is considered as 1)

Returns
  CPL_ERROR_NONE on success or the _cpl_error_code_ on failure

See also
  cpl_mask_filter()

Deprecated
  Replace this call with cpl_mask_filter() using CPL_FILTER_OPENING and CPL_BORDER_ZERO.

References CPL_BORDER_ZERO, CPL_FILTER_OPENING, cpl_mask_delete(), and cpl_mask_filter().

## cpl_mask_or()

cpl_error_code cpl_mask_or | ( | cpl_mask * | in1,
|  | const cpl_mask * | in2 )

Performs a logical OR of one mask onto another.

Parameters

  in1 | first mask, to be modified
  in2 | second mask

Returns
  CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_

See also
  cpl_image_or()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if the two masks have different sizes

References cpl_ensure_code, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fit_imagelist_polynomial_window(), cpl_image_average_create(), cpl_image_divide(), and cpl_image_divide_create().

## cpl_mask_save()

cpl_error_code cpl_mask_save | ( | const cpl_mask * | self,
|  | const char * | filename,
|  | const cpl_propertylist * | plist,
|  | unsigned | mode )

Save a mask to a FITS file.

Parameters

  self | mask to write to disk
  filename | Name of the file to write
  plist | Property list for the output header or NULL
  mode | The desired output options

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_propertylist_save()

This function saves a mask to a FITS file. If a property list is provided, it is written to the header where the mask is written.

The type used in the file is CPL_TYPE_UCHAR (8 bit unsigned).

Supported output modes are CPL_IO_CREATE (create a new file) and CPL_IO_EXTEND (append a new extension to an existing file)

The output mode CPL_IO_EXTEND can be combined (via bit-wise or) with an option for tile-compression. This compression is lossless. The options are: CPL_IO_COMPRESS_GZIP, CPL_IO_COMPRESS_RICE, CPL_IO_COMPRESS_HCOMPRESS, CPL_IO_COMPRESS_PLIO.

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask).

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if the mode is not supported
- CPL_ERROR_FILE_NOT_CREATED if the output file cannot be created
- CPL_ERROR_FILE_IO if the data cannot be written to the file

References cpl_ensure_code, CPL_ERROR_FILE_IO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), CPL_IO_COMPRESS_GZIP, CPL_IO_COMPRESS_HCOMPRESS, CPL_IO_COMPRESS_PLIO, CPL_IO_COMPRESS_RICE, CPL_IO_CREATE, CPL_IO_EXTEND, CPL_IO_MAX, and cpl_sprintf().

## cpl_mask_set()

cpl_error_code cpl_mask_set | ( | cpl_mask * | self,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | cpl_binary | value )

Set a value in a mask at a given position.

Parameters

  self | the input mask
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)
  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 an input pointer 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

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_mask_shift()

cpl_error_code cpl_mask_shift | ( | cpl_mask * | self,
|  | cpl_size | dx,
|  | cpl_size | 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_ERROR_NULL_INPUT if in is NULL
- CPL_ERROR_ILLEGAL_INPUT if the offsets are too big

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_shift().

## cpl_mask_threshold_image()

cpl_error_code cpl_mask_threshold_image | ( | cpl_mask * | self,
|  | const cpl_image * | image,
|  | double | lo_cut,
|  | double | hi_cut,
|  | cpl_binary | inval )

Select parts of an image with provided thresholds.

Parameters

  self | Mask to flag according to threshold
  image | Image to threshold.
  lo_cut | Lower bound for threshold.
  hi_cut | Higher bound for threshold.
  inval | This value (CPL_BINARY_1 or CPL_BINARY_0) is assigned where the pixel value is not marked as rejected and is strictly inside the provided interval. The other positions are assigned the other value.

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

The input image type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT. If lo_cut is greater than or equal to hi_cut, then the mask is filled with outval.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_UNSUPPORTED_MODE if the pixel type is unsupported
- CPL_ERROR_INCOMPATIBLE_INPUT if the mask and image have different sizes
- CPL_ERROR_ILLEGAL_INPUT if inval is not one of CPL_BINARY_1 or CPL_BINARY_0

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, cpl_image_get_bpm_const(), cpl_image_get_data_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_mask_get_data(), cpl_mask_get_data_const(), cpl_mask_get_size_x(), cpl_mask_get_size_y(), CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, and CPL_TYPE_INT.

Referenced by cpl_mask_threshold_image_create().

## cpl_mask_threshold_image_create()

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 on error

Note
  The returned mask must be deallocated with cpl_mask_delete()

See also
  cpl_mask_threshold_image()

References cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_mask_delete(), cpl_mask_new(), and cpl_mask_threshold_image().

Referenced by cpl_apertures_extract_sigma().

## cpl_mask_turn()

cpl_error_code cpl_mask_turn | ( | cpl_mask * | self,
|  | int | rot )

Rotate a mask by a multiple of 90 degrees clockwise.

Parameters

  self | Mask to rotate in place
  rot | The multiple: -1 is a rotation of 90 deg counterclockwise.

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:

- -3 to turn 270 degrees counterclockwise.
- -2 to turn 180 degrees counterclockwise.
- -1 to turn 90 degrees counterclockwise.
- 0 to not turn
- +1 to turn 90 degrees clockwise (same as -3)
- +2 to turn 180 degrees clockwise (same as -2).
- +3 to turn 270 degrees clockwise (same as -1).

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:

- CPL_ERROR_NULL_INPUT if self is NULL

References cpl_ensure_code, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_mask_delete(), cpl_mask_duplicate(), cpl_mask_get_data(), and cpl_mask_get_data_const().

Referenced by cpl_image_turn().

## cpl_mask_unwrap()

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 be deallocated, otherwise a memory leak occurs.

References cpl_free().

## cpl_mask_wrap()

cpl_mask * cpl_mask_wrap | ( | cpl_size | nx,
|  | cpl_size | 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

Note
  The returned object must be deallocated using cpl_mask_unwrap().

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if nx or ny is negative or zero

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_malloc().

Referenced by cpl_image_filter(), cpl_image_filter_mask(), cpl_mask_collapse_create(), cpl_mask_duplicate(), and cpl_mask_new().

## cpl_mask_xor()

cpl_error_code cpl_mask_xor | ( | cpl_mask * | in1,
|  | const cpl_mask * | in2 )

Performs a logical XOR of one mask onto another.

Parameters

  in1 | first mask, to be modified
  in2 | second mask

Returns
  CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_

See also
  cpl_image_xor()

Note
  Passing the same mask twice will clear it

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if the two masks have different sizes

References cpl_ensure_code, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.