SB SDK 1.11
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]roiPointer to the ROI.
[in]lutPointer 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]dstPointer to the pointer of the ROI destination.
On successful return, this parameter will be updated with the pointer of the structure.
[in]srcPointer 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-Lenght Encoding) method.
The function frees the pointer data of the ROI and allocates the pointer seg.

Parameters
[in]roiPointer 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]roiPointer to the pointer of the ROI, On successful return, this parameter will be updated with the pointer to the ROI.
[in]widthWidth, in pixel of the ROI.
[in]heightHeight, 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]roiPointer to the pointer of the ROI, On successful return, this parameter will be updated with the pointer to the ROI.
[in]widthWidth, in pixel of the ROI.
[in]heightHeight, in pixel, of the ROI.
[in]width_stepNumber 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]roiPointer 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]roiPointer 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]roiPointer 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]imagePointer to the image.
[in]roiRoi.
[in]lutLut to select the level to be shown. If NULL the roi lut is used.
[in]colorColor 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]roiPointer 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]roiPointer to the ROI.
[in]glGray level to be set.
[in]srcImage for blob analysis.
[in]parBlob analysis par.
[in]start_pointStarting point for blob extraction: if NULL all the blobs are extracted and printed on the roi.
[in]fill_holesFill the holes of the blob.
[in]hole_areaRange of area of the holes to be filled in.
[in]analysis_rectroi rect, 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]roiPointer to the ROI, it may be encoded.
[in]glGray 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_xx-coordinate of the center of the circle.
[in]center_yx-coordinate of the center of the circle.
[in]radiusRadius, in pixel, of the circle.
[in]reset_roiSet 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]roiPointer to the ROI, it may be encoded.
[in]glGray 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_xx-coordinate of the center of the circle.
[in]center_yx-coordinate of the center of the circle.
[in]radius_minRadius min, in pixel, of the circular crown.
[in]radius_maxRadius max, in pixel, of the circular crown.
[in]start_angleStarting angle [0-359] of the circular crown sector.
[in]end_angleEnding angle [0-359] of the circular crown sector.
[in]reset_roiSet 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]roiPointer to the ROI.
[in]dataPointer 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]roiPointer to the ROI, it may be encoded.
[in]glGray 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_xx-coordinate of the center of the ellipse.
[in]center_yx-coordinate of the center of the ellipse.
[in]radius_xX Radius, in pixel, of the ellipse.
[in]radius_yY Radius, in pixel, of the ellipse.
[in]reset_roiSet 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]roiPointer to the ROI, it may be encoded.
[in]glGray 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]rectRectangle.
[in]reset_roiSet 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