clipm_priv_image.h File Reference

#include <cpl.h>

Go to the source code of this file.

Functions
cpl_image *	clipm_priv_image_wrap (const cpl_size *size, cpl_type type, void *data)
	Create an image by wrapping it around an existing data buffer. More...
double	clipm_priv_image_get_nearest_good (const cpl_image *image, double x, double y, cpl_size *out_x, cpl_size *out_y)
	Return closest pixel which is not flagged as bad. More...
const cpl_binary *	clipm_priv_image_bpm_get_if_exist (const cpl_image *image)
	Return bad pixel mask data, if there are bad pixels, otherwise NULL. More...
cpl_error_code	clipm_priv_image_bpm_or (cpl_image *mod_image, const cpl_image *ref_image)
	Perform a logical OR between the bad pixel masks of 2 images. More...
cpl_error_code	clipm_priv_image_bpm_border_bad (cpl_image *image, cpl_size left, cpl_size right, cpl_size lower, cpl_size upper)
	Mark the border of an image as bad. More...
cpl_error_code	clipm_priv_image_bpm_reject_above (cpl_image *image, const cpl_size *window_xxyy, double limit)
	Reject all pixels equal to or greater than a limit. More...
cpl_vector *	clipm_priv_image_copy_good_data_vector (const cpl_image *image, const cpl_size *window_xxyy, cpl_size *out_ngood)
	Copy all non-bad pixels into a new vector of appropriate size. More...
cpl_error_code	clipm_priv_image_get_data_const (const cpl_image *image, const cpl_size *window_xxyy, int allow_window_NULL, cpl_size *img_size_xy, cpl_size *window_size_xy, cpl_size *buffer_start_xy, cpl_type *type, const void **data_start, const cpl_binary **badp_start)
	Get image and window sizes, and data pointers to image (window). More...
cpl_image *	clipm_priv_image_extract_cast (const cpl_image *input, const cpl_size *window_xxyy, cpl_type outtype)
	Extract an image window and cast into a new image. More...
cpl_image *	clipm_priv_image_extract_round (const cpl_image *input, const cpl_size *window_xxyy)
	Extract an image window and round to integer. More...
cpl_error_code	clipm_priv_image_fill (cpl_image *image, const cpl_size *window_xxyy, double value)
	Apply a value to all pixels inside the image or a window of the image. More...
cpl_error_code	clipm_priv_image_fill_circle (cpl_image *img_modified, double centre_xy[2], double radius, double brightness, int anti_alias, int additive)
	Fill a circle. More...
cpl_error_code	clipm_priv_image_fill_polygon (cpl_image *image, const cpl_matrix *points, double brightness, int anti_alias, int additive)
	Fill a polygon. More...
cpl_error_code	clipm_priv_image_fill_rectangle (cpl_image *image, const double centre_xy[2], double angle, const double size_lw[2], double brightness, int anti_alias, int additive)
	Fill a rectangle. More...
cpl_error_code	clipm_priv_image_save_debug (const cpl_image *img, const char *filename)
	Write an image to disk and print a message. More...
void	clipm_priv_image_null (cpl_image **i)
	Delete a CPL image object and set the pointer to NULL. More...

Function Documentation

cpl_error_code clipm_priv_image_bpm_border_bad	(	cpl_image *	image,
		cpl_size	left,
		cpl_size	right,
		cpl_size	lower,
		cpl_size	upper
	)

Mark the border of an image as bad.

Parameters

image	Image to modify
left	Left border width
right	Right border width
lower	Lower border width
upper	Upper border width

Returns

CPL error code

Principle:

• The width parameters must be >= 0, no maximum limit is required (this means, some width value big enough will just flag the whole image as bad).

Error Handling:

The following error codes can be set:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_ILLEGAL_INPUT: a width parameter is < 0

const cpl_binary* clipm_priv_image_bpm_get_if_exist

(

const cpl_image *

image

)

Return bad pixel mask data, if there are bad pixels, otherwise NULL.

Parameters

image

Input image

Returns

BPM pointer, NULL in case there are no bad pixels, or in the case of error

Error Handling:

The following error codes can be set:

• CPL_ERROR_NULL_INPUT: image is NULL

cpl_error_code clipm_priv_image_bpm_or	(	cpl_image *	mod_image,
		const cpl_image *	ref_image
	)

Perform a logical OR between the bad pixel masks of 2 images.

Parameters

mod_image	Image to modify
ref_image	Reference image

Returns

CPL error code

Error Handling:

The following error codes can be set:

• CPL_ERROR_NULL_INPUT: mod_image or ref_image is NULL
• CPL_ERROR_INCOMPATIBLE_INPUT: mod_image and ref_image have different sizes

cpl_error_code clipm_priv_image_bpm_reject_above	(	cpl_image *	image,
		const cpl_size *	window_xxyy,
		double	limit
	)

Reject all pixels equal to or greater than a limit.

Parameters

image	Image to modify
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
limit	Limit

Returns

CPL error code

Bad Pixel Handling:

Bad pixels are kept as bad.

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image range

cpl_vector* clipm_priv_image_copy_good_data_vector	(	const cpl_image *	image,
		const cpl_size *	window_xxyy,
		cpl_size *	out_ngood
	)

Copy all non-bad pixels into a new vector of appropriate size.

Parameters

image	Input image
window_xxyy	Coordinate buffer of the form {x1a, x1b, y1a, y1b}, minimum/maximum order is irrelevant
out_ngood	(Optional output) number of good pixels, contains 0 in the case of error

Returns

The new vector, NULL in the case of error

Error Handling:

The following errors may occur:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image range
• CPL_ERROR_DATA_NOT_FOUND: image contains only bad pixels

cpl_image* clipm_priv_image_extract_cast	(	const cpl_image *	input,
		const cpl_size *	window_xxyy,
		cpl_type	outtype
	)

Extract an image window and cast into a new image.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
outtype	Output image type

Returns

The new extracted and casted image, NULL in the case of error

Principle:

The image data (from a window) is copied and casted to the new type. Valid types are CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE (for both input and output images).

Error Handling:

Possible error codes set in this function:

• CPL_ERROR_NULL_INPUT if image is NULL
• CPL_ERROR_INVALID_TYPE:
  • out_type is not supported
  • the type of the input image is not supported
• CPL_ERROR_ACCESS_OUT_OF_RANGE if a coordinate is out of the image range

Todo:

• implement unit test

cpl_image* clipm_priv_image_extract_round	(	const cpl_image *	input,
		const cpl_size *	window_xxyy
	)

Extract an image window and round to integer.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant

Returns

The new rounded image, NULL in the case of error

Principle:

The image data (from a window) is copied and rounded to integer.

Error Handling:

Possible error codes set in this function:

• CPL_ERROR_NULL_INPUT if image is NULL
• CPL_ERROR_INVALID_TYPE if the input image type is not CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE if a coordinate is out of the image range

cpl_error_code clipm_priv_image_fill	(	cpl_image *	image,
		const cpl_size *	window_xxyy,
		double	value
	)

Apply a value to all pixels inside the image or a window of the image.

Parameters

image	The image to draw into (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
value	The value to be set (true or false)

Returns

CPL error code

Overview:

• If window is given, all pixels inside the window are set to the provided value.
• If window is NULL, all pixels in the image are set to the provided value.
• If the type of the image is CPL_TYPE_INT, then value is rounded to the nearest integer.

Bad Pixel Handling:

• Bad pixels are flagged as good.

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window specifies coordinates outside the image plane

In the case of error, the image is not changed.

Todo:

• implement unit test

cpl_error_code clipm_priv_image_fill_circle	(	cpl_image *	img_modified,
		double	centre_xy[2],
		double	radius,
		double	brightness,
		int	anti_alias,
		int	additive
	)

Fill a circle.

Parameters

img_modified	The image to draw into
centre_xy	Centre position (double buffer of length 2 [x, y])
radius	The circle's radius
brightness	The circle's content value
anti_alias	Flag whether to soften the edge
additive	Flag whether to add the circle on top of the existing image content (additive != 0), or whether to set the area to the brightness value

Returns

CPL error code

Principle:

• If additive is true, then the filled circle will be added to the current image content, otherwise the circle is filled with brightness.
• If anti_alias is true, then the edges are softened.
• If the type of img_modified is CPL_TYPE_INT, then the resulting values are rounded.
• radius can be negative, in this case no pixel is modified, and no error is set. If the circle is outside the range, no error is set either.

Note

Be aware, that a very small circle can also fit between pixels, so that none might be set (if anti_alias is false).

Bad Pixel Handling:

• If additive is false, then bad pixels inside the circle are flagged as good.
• If additive is true, then only good pixels inside the circle are modified.
• If anti_alias is true, then only good pixels in the range of the softened edge are modified (regardless of additive).

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT: img_modified or centre_xy is NULL
• CPL_ERROR_INVALID_TYPE: img_modified is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE

In the case of error, img_modified is not changed.

cpl_error_code clipm_priv_image_fill_polygon	(	cpl_image *	image,
		const cpl_matrix *	points,
		double	brightness,
		int	anti_alias,
		int	additive
	)

Fill a polygon.

Parameters

image	The image to draw into
points	2xN corner point matrix
brightness	The polygon's content value
anti_alias	Flag whether to soften the edge
additive	Flag whether to add the circle on top of the existing image content (additive != 0), or whether to set the area to the brightness value

Returns

CPL error code

Principle:

• If additive is true, then the filled polygon will be added to the current image content, otherwise the polygon is filled with brightness.
• If anti_alias is true, then the edges are softened.
• Anti-alias values are computed numerically.
• If the type of image is CPL_TYPE_INT, then the resulting values are rounded.

Note

• Be aware, that a very narrow structures can also fit between pixels, so that none might be set, if anti_alias is false.
• The number of points N must be equal or greater than 3.

Bad Pixel Handling:

• If additive is false, then bad pixels inside the polygon are flagged as good.
• If additive is true, then only good pixels inside the polygon are modified.
• If anti_alias is true, then only good pixels in the range of the softened edge are modified (regardless of additive).

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT: image or points is NULL
• CPL_ERROR_ILLEGAL_INPUT: the points matrix has an improper size
• CPL_ERROR_INVALID_TYPE: img_modified is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE

In the case of error, image is not changed.

cpl_error_code clipm_priv_image_fill_rectangle	(	cpl_image *	image,
		const double	centre_xy[2],
		double	angle,
		const double	size_lw[2],
		double	brightness,
		int	anti_alias,
		int	additive
	)

Fill a rectangle.

Parameters

image	The image to draw into
centre_xy	Centre coordinate as (x,y) tuple
angle	Orientation
size_lw	Length and width as a data tuple, the first entry (size_lw[0]) will point into the direction of angle
brightness	The polygon's content value
anti_alias	Flag whether to soften the edge
additive	Flag whether to add the circle on top of the existing image content (additive != 0), or whether to set the area to the brightness value

Returns

CPL error code

Principle:

• If additive is true, then the filled polygon will be added to the current image content, otherwise the polygon is filled with brightness.
• If anti_alias is true, then the edges are softened.
• Anti-alias values are computed numerically.
• If the type of image is CPL_TYPE_INT, then the resulting values are rounded.

Bad Pixel Handling:

• If additive is false, then bad pixels inside the rectangle are flagged as good.
• If additive is true, then only good pixels inside the rectangle are modified.
• If anti_alias is true, then only good pixels in the range of the softened edge are modified (regardless of additive).

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT: any input pointer is NULL
• CPL_ERROR_INVALID_TYPE: img_modified is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE

In the case of error, image is not changed.

Todo:

• implement unit test

cpl_error_code clipm_priv_image_get_data_const	(	const cpl_image *	image,
		const cpl_size *	window_xxyy,
		int	allow_window_NULL,
		cpl_size *	img_size_xy,
		cpl_size *	window_size_xy,
		cpl_size *	buffer_start_xy,
		cpl_type *	type,
		const void **	data_start,
		const cpl_binary **	badp_start
	)

Get image and window sizes, and data pointers to image (window).

Parameters

image	Image (FITS convention)
window_xxyy	Coordinate buffer of the form {x1a, x1b, y1a, y1b}, minimum/maximum order is irrelevant
allow_window_NULL	If !0, then no error is set if (window==NULL)
img_size_xy	(Optional) buffer of size 2, to which the image size [x, y] is put out, can be NULL
window_size_xy	(Optional) buffer of size 2, to which the window size is determined and written, can be NULL
buffer_start_xy	(Optional) buffer of size 2, to which the lower left window indices are written (buffer, not FITS), starting at 0, can be NULL
type	(Optional) output CPL-type of image
data_start	(Optional) output pointer to image data, if window_xxyy is given, then it points to the lower left corner of the data
badp_start	(Optional) output bad pixel map pointer, returns NULL if no bad pixels are set, if window_xxyy is given, then it points to the lower left corner of the data

Returns

CPL error code

Overview:

• The window coordinates are checked for being inside the image range.
• If an input is NULL, or if the coordinates are out of range, then the appropriate CPL error is set and returned.
• If out_window_size != NULL, then the window size is calculated and written to this buffer. If window_xxyy == NULL, then out_window_size is set to the image size!
• data_start and badp_start are (if provided) set to the respective buffers, if window_xxyy is provided, they point to the position in the data buffers corresponding to the lower left window corner.

Error Handling:

The following codes are set, if the check fails:

• CPL_ERROR_NULL_INPUT: image and/or window_xxyy is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy coordinates are outside the image In the case of error, the output parameter values are undefined.

Note

• This function does not check min/max conditions of window_xxyy. Use clipm_priv_checks_window_minmax() for this purpose.
• Specifying buffers of too small size (sizeof(window) < 4 || sizeof(out_img_size) < 2 || sizeof(out_window_size) < 2 || sizeof(out_buffer_start_xy) < 2) will crash the application!

double clipm_priv_image_get_nearest_good	(	const cpl_image *	image,
		double	x,
		double	y,
		cpl_size *	out_x,
		cpl_size *	out_y
	)

Return closest pixel which is not flagged as bad.

Parameters

image	Input image
x	X position (FITS convention)
y	Y position (FITS convention)
out_x	(Optional output) x index of found pixel (FITS convention)
out_y	(Optional output) y index of found pixel (FITS convention)

Returns

The pixel value, -1.0 on error

Principle:

Returns the pixel value at the respective rounded position. If the pixel is bad, the next good pixel in minimum distance is searched (in circles around the provided position).

Constraints:

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Error Handling:

Possible error codes set in this function:

• CPL_ERROR_NULL_INPUT: if image is NULL
• CPL_ERROR_INVALID_TYPE: if the passed image type is not supported
• CPL_ERROR_ACCESS_OUT_OF_RANGE: if x or y are out of the image range
• CPL_ERROR_DATA_NOT_FOUND: if no good pixel was found

In the case of error, the return values are:

• Function: -1.0
• out_x: 0
• out_y: 0

void clipm_priv_image_null

(

cpl_image **

i

)

Delete a CPL image object and set the pointer to NULL.

Parameters

i	Pointer to image pointer

Returns

Nothing

The following code is executed:

   if (i != NULL)
   {
       cpl_image_delete(*i);  // checks for NULL pointer
       *i = NULL;
   }
* 

Error Handling:

No error can occur here.

cpl_error_code clipm_priv_image_save_debug	(	const cpl_image *	img,
		const char *	filename
	)

Write an image to disk and print a message.

Parameters

img
filename

Returns

CPL error code

Principle:

• The image is written to disk.
• A message is printed.
• Bad pixels are filled with min-(max-min) for visualisation.

Note

This function is intended for debugging/hacking and unit testing purposes only.

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: img or filename is NULL
• CPL_ERROR_TYPE_MISMATCH: the image type is not supported
• CPL_ERROR_FILE_NOT_CREATED: the file could not be created

Todo:

• implement unit test

cpl_image* clipm_priv_image_wrap	(	const cpl_size *	size,
		cpl_type	type,
		void *	data
	)

Create an image by wrapping it around an existing data buffer.

Parameters

size	Buffer of size 2, containing the image size [x, y], can be NULL
type	Either CPL_TYPE_INT, CPL_TYPE_FLOAT, or CPL_TYPE_DOUBLE
data	The data buffer of the specified type and size

Returns

Newly allocated image, NULL in the case of error

Error Handling:

Possible error codes set in this function:

• CPL_ERROR_NULL_INPUT:
  • size is NULL
  • data is NULL
• CPL_ERROR_ILLEGAL_INPUT: an entry of size is <= 0
• CPL_ERROR_INVALID_TYPE: if the passed image type is not supported

Note

• Specifying a size buffer with less then 2 entries (sizeof(size) < 2) will crash the application!