ROI

Collection of functions to manage a ROI (Region Of Interest) More...

Collaboration diagram for ROI:

Data Structures
struct	sb_t_roi
	Defines a roi. More...

Functions
sb_t_err	sb_roi_create (sb_t_roi **const roi, int width, int height)
	Creates a ROI. More...
sb_t_err	sb_roi_create_header (sb_t_roi **const roi, int width, int height, int width_step)
	Creates a ROI but doesn't allocate memory for the data. More...
sb_t_err	sb_roi_destroy (sb_t_roi **const roi)
	Destroys the ROI. More...
sb_t_err	sb_roi_reset (sb_t_roi *const roi)
	Resets the ROI. More...
sb_t_err	sb_roi_evaluate_bounding_box (sb_t_roi *const roi)
	Calculates the bounding box of the roi depending by the lut. More...
sb_t_err	sb_roi_set_data (sb_t_roi *const roi, unsigned char *const data)
	Sets the pointer of the ROI data into the ROI. More...
sb_t_err	sb_roi_set_rect (sb_t_roi *const roi, unsigned char gl, sb_t_rect rect, int reset_roi)
	Sets a rectangular ROI. More...
sb_t_err	sb_roi_set_circle (sb_t_roi *const roi, unsigned char gl, int center_x, int center_y, int radius, int reset_roi)
	Sets a circular ROI. More...
sb_t_err	sb_roi_set_circular_crown (sb_t_roi *const roi, unsigned char gl, int center_x, int center_y, int radius_min, int radius_max, int start_angle, int end_angle, int reset_roi)
	Sets an angular circular crown ROI. More...
sb_t_err	sb_roi_set_ellipse (sb_t_roi *const roi, unsigned char gl, int center_x, int center_y, int radius_x, int radius_y, int reset_roi)
	Sets an elliptical ROI. More...
sb_t_err	sb_roi_clone (sb_t_roi **const dst, const sb_t_roi *const src)
	Copies a roi. More...
sb_t_err	sb_roi_compress (sb_t_roi *const roi)
	Compresses the ROI and deletes the uncompressed version. More...
sb_t_err	sb_roi_decompress (sb_t_roi *const roi)
	Decompresses the ROI and deletes the compressed version. More...
sb_t_err	sb_roi_plot (sb_t_image *const image, const sb_t_roi *const roi, const unsigned char *lut, sb_t_rgba color)
	Draws the roi on the image. More...
sb_t_err	sb_roi_apply_lut (sb_t_roi *const roi, unsigned char *lut)
	Applies the gray level lut to the roi image. More...
sb_t_err	sb_roi_set_blob (sb_t_roi *const roi, unsigned char gl, const sb_t_image *const src, const sb_t_blob_par *const par, const sb_t_point *const start_point, int fill_holes, sb_t_range hole_area, const sb_t_rect *analysis_rect)
	Sets a ROI from blob analysis. More...

Detailed Description

Collection of functions to manage a ROI (Region Of Interest)

See ROI management for more information.

Function Documentation

sb_roi_apply_lut()

sb_t_err sb_roi_apply_lut	(	sb_t_roi *const	roi,
		unsigned char *	lut
	)

Applies the gray level lut to the roi image.

This function is used to change the model of a Surface roi defects. To do this the function applies the lut to the pixels of the roi image.
Let's consider this example:
The defects ROI contains defects belonging to the first model "model1" with a corresponding gray level of 255. We want to assign the defects to the second model "model2" with a corresponding gray level of 254.
In order to do this we will create a lut in this way and pass it to the sb_roi_apply_lut function:

unsigned char lut[256];
for(int i=0; i < 255; i++)
    lut[i] = i;
lut[255] = 254;

To obtain the gray level of a model, it is possible to call the function sb_surface_model_to_gl.
The function updates the sb_t_roi::bounding_box parameter of the roi.

Parameters

[in]	roi	Pointer to the ROI.
[in]	lut	Pointer to the LUT.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_surface_model_to_gl

sb_roi_clone()

sb_t_err sb_roi_clone	(	sb_t_roi **const	dst,
		const sb_t_roi *const	src
	)

Copies a roi.

Parameters

[out]	dst	Pointer to the pointer of the ROI destination. On successful return, this parameter will be updated with the pointer of the structure.
[in]	src	Pointer to the ROI source.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_compress()

sb_t_err sb_roi_compress

(

sb_t_roi *const

roi

)

Compresses the ROI and deletes the uncompressed version.

The ROI is compressed using RLE (Run-Length Encoding) method.
The function frees the pointer data of the ROI and allocates the pointer seg.

Parameters

[in]

roi

Pointer to the ROI.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_decompress

sb_roi_create()

sb_t_err sb_roi_create	(	sb_t_roi **const	roi,
		int	width,
		int	height
	)

Creates a ROI.

Parameters

[out]	roi	Pointer to the pointer of the ROI, On successful return, this parameter will be updated with the pointer to the ROI.
[in]	width	Width, in pixel of the ROI.
[in]	height	Height, in pixel, of the ROI.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_create_header

sb_roi_destroy

sb_roi_set_data

sb_roi_create_header()

sb_t_err sb_roi_create_header	(	sb_t_roi **const	roi,
		int	width,
		int	height,
		int	width_step
	)

Creates a ROI but doesn't allocate memory for the data.

The user should use the function sb_roi_set_data to assign a block on memory for roi data.
The block of memory must be greater or equal than (height * width_step).

Parameters

[out]	roi	Pointer to the pointer of the ROI, On successful return, this parameter will be updated with the pointer to the ROI.
[in]	width	Width, in pixel of the ROI.
[in]	height	Height, in pixel, of the ROI.
[in]	width_step	Number of bytes to move the pointer to one row to the next one of the ROI

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_create

sb_roi_destroy

sb_roi_set_data

sb_roi_decompress()

sb_t_err sb_roi_decompress

(

sb_t_roi *const

roi

)

Decompresses the ROI and deletes the compressed version.

The function frees the pointer seg of the ROI and allocates the pointer data.

Parameters

[in]

roi

Pointer to the ROI.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_compress

sb_roi_destroy()

sb_t_err sb_roi_destroy

(

sb_t_roi **const

roi

)

Destroys the ROI.

Parameters

[in,out]

roi

Pointer to the pointer of the ROI. The function set it to NULL.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_create

sb_roi_create_header

sb_roi_evaluate_bounding_box()

sb_t_err sb_roi_evaluate_bounding_box

(

sb_t_roi *const

roi

)

Calculates the bounding box of the roi depending by the lut.

Attention

The function must be called before sb_project_detection whenever the ROI is edited. In particular it is necessary to call this function when a ROI operation that deletes a portion of the ROI causes a potential change of the bounding box. In case no such operation is performed it is not necessary to call this function.

Parameters

[in]

roi

Pointer to the ROI.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_project_detection

sb_roi_plot()

sb_t_err sb_roi_plot	(	sb_t_image *const	image,
		const sb_t_roi *const	roi,
		const unsigned char *	lut,
		sb_t_rgba	color
	)

Draws the roi on the image.

Parameters

[in,out]	image	Pointer to the image.
[in]	roi	Roi.
[in]	lut	Lut to select the level to be shown. If NULL the roi lut is used.
[in]	color	Color to be used to draw the roi

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_reset()

sb_t_err sb_roi_reset

(

sb_t_roi *const

roi

)

Resets the ROI.

The function does the following operation:

• resets each pixel of the roi
• resets the bounding box to a rectangle with null dimension
• resets the lut

  Parameters

  [in]

  roi

  Pointer to the ROI.

  Returns

  If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

  See also

  ROI management

sb_roi_set_blob()

sb_t_err sb_roi_set_blob	(	sb_t_roi *const	roi,
		unsigned char	gl,
		const sb_t_image *const	src,
		const sb_t_blob_par *const	par,
		const sb_t_point *const	start_point,
		int	fill_holes,
		sb_t_range	hole_area,
		const sb_t_rect *	analysis_rect
	)

Sets a ROI from blob analysis.

The function performs a blob analysis on src image with the parameters specified and plot the resulting blobs on the roi

Parameters

[in]	roi	Pointer to the ROI.
[in]	gl	Gray level to be set.
[in]	src	Image for blob analysis.
[in]	par	Blob analysis par.
[in]	start_point	Starting point for blob extraction: if NULL all the blobs are extracted and printed on the roi.
[in]	fill_holes	Fill the holes of the blob.
[in]	hole_area	Range of area of the holes to be filled in.
[in]	analysis_rect	roi rectangle, NULL to analyze the whole image

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

sb_roi_set_circle()

sb_t_err sb_roi_set_circle	(	sb_t_roi *const	roi,
		unsigned char	gl,
		int	center_x,
		int	center_y,
		int	radius,
		int	reset_roi
	)

Sets a circular ROI.

Each pixel of the ROI belonging to the circle is set to the value.

Parameters

[in]	roi	Pointer to the ROI, it may be encoded.
[in]	gl	Gray level to be set.

Warning

The function updates the sb_t_roi::bounding_box when gl is greater than 0,
but when gl is 0, ie a part of roi is being deleted, the sb_t_roi::bounding_box is not updated.
You should call sb_roi_evaluate_bounding_box to update sb_t_roi::bounding_box.

Parameters

[in]	center_x	x-coordinate of the center of the circle.
[in]	center_y	x-coordinate of the center of the circle.
[in]	radius	Radius, in pixel, of the circle.
[in]	reset_roi	Set to 1 if you need to reset the ROI before the new circle is drawn.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_set_rect

sb_roi_set_circular_crown

sb_roi_set_ellipse

sb_roi_evaluate_bounding_box

sb_roi_set_circular_crown()

sb_t_err sb_roi_set_circular_crown	(	sb_t_roi *const	roi,
		unsigned char	gl,
		int	center_x,
		int	center_y,
		int	radius_min,
		int	radius_max,
		int	start_angle,
		int	end_angle,
		int	reset_roi
	)

Sets an angular circular crown ROI.

Each pixel of the ROI belonging to circular region delimited by start_angle and end_angle is set to the value.

Parameters

[in]	roi	Pointer to the ROI, it may be encoded.
[in]	gl	Gray level to be set.

Warning

The function updates the sb_t_roi::bounding_box when gl is greater than 0,
but when gl is 0, ie a part of roi is being deleted, the sb_t_roi::bounding_box is not updated.
You should call sb_roi_evaluate_bounding_box to update sb_t_roi::bounding_box.

Parameters

[in]	center_x	x-coordinate of the center of the circle.
[in]	center_y	x-coordinate of the center of the circle.
[in]	radius_min	Radius min, in pixel, of the circular crown.
[in]	radius_max	Radius max, in pixel, of the circular crown.
[in]	start_angle	Starting angle [0-359] of the circular crown sector.
[in]	end_angle	Ending angle [0-359] of the circular crown sector.
[in]	reset_roi	Set to 1 if you need to reset the ROI before the new circle is drawn.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_set_rect

sb_roi_set_cirle

sb_roi_set_ellipse

sb_roi_evaluate_bounding_box

sb_roi_set_data()

sb_t_err sb_roi_set_data	(	sb_t_roi *const	roi,
		unsigned char *const	data
	)

Sets the pointer of the ROI data into the ROI.

Parameters

[in]	roi	Pointer to the ROI.
[in]	data	Pointer of the array.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_set_ellipse()

sb_t_err sb_roi_set_ellipse	(	sb_t_roi *const	roi,
		unsigned char	gl,
		int	center_x,
		int	center_y,
		int	radius_x,
		int	radius_y,
		int	reset_roi
	)

Sets an elliptical ROI.

Each pixel of the ROI belonging to the ellipse is set to the value.

Parameters

[in]	roi	Pointer to the ROI, it may be encoded.
[in]	gl	Gray level to be set.

Warning

The function updates the sb_t_roi::bounding_box when gl is greater than 0,
but when gl is 0, ie a part of roi is being deleted, the sb_t_roi::bounding_box is not updated.
You should call sb_roi_evaluate_bounding_box to update sb_t_roi::bounding_box.

Parameters

[in]	center_x	x-coordinate of the center of the ellipse.
[in]	center_y	x-coordinate of the center of the ellipse.
[in]	radius_x	X Radius, in pixel, of the ellipse.
[in]	radius_y	Y Radius, in pixel, of the ellipse.
[in]	reset_roi	Set to 1 if you need to reset the ROI before the new ellipse is drawn.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_set_rect

sb_roi_set_circle

sb_roi_set_circular_crown

sb_roi_evaluate_bounding_box

sb_roi_set_rect()

sb_t_err sb_roi_set_rect	(	sb_t_roi *const	roi,
		unsigned char	gl,
		sb_t_rect	rect,
		int	reset_roi
	)

Sets a rectangular ROI.

Each pixel of the ROI belonging to the rectangle is set to value.

Parameters

[in]	roi	Pointer to the ROI, it may be encoded.
[in]	gl	Gray level to be set.

Warning

The function updates the sb_t_roi::bounding_box when gl is greater than 0,
but when gl is 0, ie a part of roi is being deleted, the sb_t_roi::bounding_box is not updated.
You should call sb_roi_evaluate_bounding_box to update sb_t_roi::bounding_box.

Parameters

[in]	rect	Rectangle.
[in]	reset_roi	Set to 1 is you need to reset the ROI before the new rectangle is drawn.

Returns

If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

See also

ROI management

sb_roi_set_circle

sb_roi_set_circular_crown

sb_roi_set_ellipse

sb_roi_evaluate_bounding_box