Object generation🔗
This section describes the convenience routines HNewRegion, HPutRect, and HDupObj for creating new image objects, see Convenience routines for creating output objects.
HNewRegion creates a new image object in the HALCON database encapsulating the specified region and adds this object to the first output object parameter.
HPutRect inserts a rectangular region (as domain, i.e., area of definition) into an already existing output image object.
Finally, HDupObj adds an iconic input object to the object list of the first output object parameter.
Names
Synopsis
#include "Halcon.h"
HNewRegion(Hproc_handle proc_handle,
Hrlregion *region)
HPutRect( Hproc_handle proc_handle,
Hkey obj_key,
HIMGDIM width,height)
HDupObj( Hproc_handle proc_handle,
INT4_8 obj_index)
HNewRegion🔗
HNewRegion (see Convenience routines for creating output objects) is used to create a new image object in the HALCON database which is also added to the first output object parameter.
It contains a copy of region.
It is common to call an image object region, when only its region component is used.
Note that HNewRegion automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HNewRegion yourself.
Herror CIPConvex(Hproc_handle proc_handle)
{
Hrlregion *region;
Hrlregion *region_new;
HCkP(HAllocRLTmp(proc_handle,®ion_new) /* allocate memory */
HAllReg(proc_handle,®ion,i) { /* all regions */
HCkP(HRLConvex2(proc_handle,region,region_new));
/* create an output region object (first output param.) */
HNewRegion(proc_handle,region_new);
}
HCkP(HFreeRLTmp(proc_handle,region_new)); /* free memory */
return(H_MSG_TRUE);
}
Typically, HNewRegion is used within segmentation procedures (see A typical application of HAllSegm: A segmentation operator) and region transformation procedures such as the procedure CIPConvex shown in A typical application of HNewRegion: The region transformation “convex hull”.
CIPConvex corresponds to a hypothetical operator trans_convex which might be defined as
In the example, all regions within Region are provided in region by HAllReg (see HAllReg) one after the other.
The internal HALCON procedure HRLConvex2 computes the convex hull for each region and writes it to region_new.
Furthermore, a new region object in the HALCON database is created and added to the output object parameter RegionConvex.
Note that HNewRegion was also used in the example in A typical application of HAllSegm: A segmentation operator.
HPutRect🔗
HPutRect (see Convenience routines for creating output objects) inserts a rectangular region in an already existing output object with database key obj_key.
It is mostly used in connection with operators that create new image objects like in the example in A typical application of HPutRect: Grabbing an image.
Note that HPutRect automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutRect yourself.
Herror CIOGrabImage(Hproc_handle proc_handle)
{
Hkey obj_key,image_key;
Himage image;
HCrObj(proc_handle,1,&obj_key);
HCkP(HNewImage(proc_handle,&image,BYTE_IMAGE,640,480));
/* grab an NTSC image 640 x 480 pixel, 8 bit */
HCkP(IOBGrabImage(&image));
HPutDImage(proc_handle,obj_key,1,&image,false,&image_key);
HPutRect(proc_id,obj_key,image.width,image.height);
return(H_MSG_TRUE);
}
Note that HCrObj (see HCrObj) creates an object with empty region.
In many situations the default domain (area of definition) for a new image will be the full image domain, which is a rectangle.
In this situation the use of HPutRect is very convenient.
HDupObj🔗
HDupObj (see Convenience routines for creating output objects) is a combination/simplification of HGetObj (see HGetObj) and HCopyObj (see HCopyObj).
It duplicates iconic input objects (images, regions, XLD) in order to pass them directly to the first output object parameter.
The objects to be duplicated are specified by their index obj_index within the first input object parameter.
Note that this index corresponds to obj_index as defined for the loop macros (HAll*) in Loop macros.
HDupObj is typically used for operators that examine objects and select them by a given criterion.
Some HALCON operators of this kind are select_shape or select_gray.
Note that HDupObj automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HDupObj yourself.
A typical application of HDupObj: Duplicate input regions that fulfill a specific criteria (length of contour) shows an application of HDupObj: CIPUserSelect computes the length of the contour of each input region (in parameter 1).
All regions with a contour of at least the minimal length min are passed to the output.
Herror CIPUserSelect(Hproc_handle proc_handle)
{
Hrlregion *region;
Hrlregion *region_new;
double length;
Hcpar min;
INT4_8 i;
HGetSPar(proc_handle,1,DOUBLE_PAR,&min,1); /* get min. length */
HAllReg(proc_handle,®ion,i) { /* all regions */
HCkP(HRLContLength(proc_handle,region,&length)); /* length */
if (length >= min.par.d) /* length o.k. ? */
HDupObj(proc_handle,i); /* duplicate object*/
}
return(H_MSG_TRUE);
}
As HDupObj only increases the number of references to a database object instead of copying it physically, its memory costs and computational costs are neglectable.
In contrast, HNewRegion and HAllFilter always allocate new memory for the output objects, for example.
Therefore, use HDupObj whenever possible.