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, CPL_ERROR_NULL_INPUT, and cpl_mask_count_window().

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, CPL_ERROR_NULL_INPUT, and CPL_MIN.

Referenced by cpl_mask_count().

◆ 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:2132

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

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.

Functions

Detailed Description

Function Documentation

◆ cpl_mask_and()

◆ cpl_mask_closing()

◆ cpl_mask_collapse_create()

◆ cpl_mask_copy()

◆ cpl_mask_count()

◆ cpl_mask_count_window()

◆ cpl_mask_delete()

◆ cpl_mask_dilation()

◆ cpl_mask_dump_window()

◆ cpl_mask_duplicate()

◆ cpl_mask_erosion()

◆ cpl_mask_extract()

◆ cpl_mask_extract_subsample()

◆ cpl_mask_filter()

◆ cpl_mask_flip()

◆ cpl_mask_get()

◆ cpl_mask_get_data()

◆ cpl_mask_get_data_const()

◆ cpl_mask_get_size_x()

◆ cpl_mask_get_size_y()

◆ cpl_mask_is_empty()

◆ cpl_mask_is_empty_window()

◆ cpl_mask_load()

◆ cpl_mask_load_window()

◆ cpl_mask_move()

◆ cpl_mask_new()

◆ cpl_mask_not()

◆ cpl_mask_opening()

◆ cpl_mask_or()

◆ cpl_mask_save()

◆ cpl_mask_set()

◆ cpl_mask_shift()

◆ cpl_mask_threshold_image()

◆ cpl_mask_threshold_image_create()

◆ cpl_mask_turn()

◆ cpl_mask_unwrap()

◆ cpl_mask_wrap()

◆ cpl_mask_xor()