Creating objects and writing output object parameters🔗
This section describes routines for creating new iconic objects in the HALCON database of iconic objects and for writing output iconic parameters of a HALCON operator, see Basic routines for creating new iconic objects and writing output iconic parameters. Note that regions, gray value channels, and XLDs are all stored as individual iconic objects within the database. Thus, for example different image objects can share the same gray value channels (image matrices) or domains (areas of definition). Therefore, in order to return iconic objects as the result of a HALCON operator you have to
- store the computed regions, channels, and XLDs in the HALCON database of iconic objects,
- combine regions and channels to image objects,
- and add the appropriate iconic objects to the corresponding output iconic parameters.
Names
Synopsis
#include "Halcon.h"
HCrObj( Hproc_handle proc_handle,
int par_num,
Hkey *obj_key)
HCopyObj( Hproc_handle proc_handle,
Hkey obj_key,
int par_num,
Hkey *obj_key)
HPutDRL( Hproc_handle proc_handle,
Hkey obj_key,
Hrlregion *region,
Hkey *rl_key)
HPutImage( Hproc_handle proc_handle,
Himage *image,
bool copy,
Hkey *obj_key)
Names
Synopsis
#include "Halcon.h"
HDefObj( Hproc_handle proc_handle,
Hkey obj_key,
Hkey comp_key,
int comp)
HPutDImage( Hproc_handle proc_handle,
Hkey obj_key,
int comp,
Himage *image,
bool copy,
Hkey *image_key)
Herror HCrImage( Hproc_handle proc_handle,
Hkey image_key_in,
int index,
int type,
HIMGDIM width,height,
Hkey *image_key_out,
Himage *image_out)
HCrXLD( Hproc_handle proc_handle,
int par_num,
XLD *xld,
int xld_type,
Hkey *used_xlds,
int num_used_xlds,
DBFreeProc free_proc,
Hkey *obj_key)
HCrObj🔗
HCrObj (see Basic routines for creating new iconic objects and writing output iconic parameters) creates a new image object in the HALCON database of iconic objects and adds it to the list of iconic objects in the output iconic parameter with the index par_num.
Note that more than one image object can be returned in the same output parameter by iterating calls of HCrObj using the same par_num: Each call appends the database key of the new iconic object at the end of the iconic object list for the parameter.
The new image object contains the following default image components:
- The region component specifying the area of definition, i.e., the domain of the image, is set to the empty region.
This component can be changed using
HPutDRL(seeHPutDRL) orHPutRect(seeHPutRect). - All channels are marked as undefined, i.e., the new image object contains no gray value components.
Channels can be added to the iconic object using
HPutImage(seeHPutImage) andHDefObj(seeHDefObj) orHPutDImage(seeHPutDImage).
Application of HAllComp: Rotate all channels of all image objects of the first input iconic parameter and Creating a new image object using basic Extension Package Interface routines show examples how to use HCrObj.
Note that HCrObj automatically checks the result state of the underlying procedure with the macro HCkP, (see HCkP).
Thus, you must not use HCkP on HCrObj yourself.
HCopyObj🔗
HCopyObj (see Basic routines for creating new iconic objects and writing output iconic parameters) creates a new iconic object (image, region, or XLD) that contains the same components as an already existing iconic object specified by its database key obj_key.
The new iconic object is stored in the HALCON database of iconic objects and appended to the list of iconic objects in the output iconic parameter with the index par_num.
The database key of the new image object is returned in obj_key.
Note that HCopyObj automatically checks the result state of the underlying procedure with the macro HCkP.
Thus, you must not use HCkP on HCopyObj yourself.
Hkey obj_key_in,obj_key_out,reg_key_out;
Hrlregion *region_in;
Hrlregion *region_out;
INT4_8 num_objs;
...
par_in = 1; /* index of input parameter */
par_out = 1; /* index of output parameter */
HReadGVA(proc_handle,HGnum_obj,&num_objs,par_in);
for (o=1; o<=num_objs; o++) {
HGetObj(proc_handle,par_in,o,&obj_key_in);
HGetFDRL(proc_handle,obj_key_in,®ion_in);
/* compute some region transformation ... */
transform(region_in,region_out);
HCopyObj(proc_handle,obj_key_in,par_out,&obj_key_out);
HPutDRL(proc_handle,obj_key_out,region_out,®_key_out);
}
Similar to HCrObj, the components of a new image object can be reassigned using HDefObj etc.
HCopyObj is especially useful, when output iconic objects hardly differ from the corresponding input objects.
HPutDRL🔗
HPutDRL (see Basic routines for creating new iconic objects and writing output iconic parameters) stores region data encoded in the Hrlregion structure region in the HALCON database of iconic objects and returns the database key of the new iconic object.
Note that HPutDRL actually copies the data itself, not only a pointer to the data.
In addition to that, the region object is assigned to the image object specified by the database key obj_key as the region component.
The latter might have been created before by using HCrObj or HCopyObj, see Create an image object with HCopyObj and insert a region component and Creating a new image object using basic Extension Package Interface routines.
Note that HPutDRL automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutDRL yourself.
HPutImage🔗
HPutImage (see Basic routines for creating new iconic objects and writing output iconic parameters) stores the gray value channel (image matrix) image in the database of iconic objects and returns the corresponding database key in the parameter obj_key.
This key can be used to insert the gray value channel (now encapsulated in a database object) as a component of an arbitrary number of image objects (see HDefObj in HDefObj).
The parameter copy (false or true) specifies, whether the pixel data is copied to the HALCON database1 or only the address of the data is passed to the database object.
Creating a new image object using basic Extension Package Interface routines shows a typical example for how to use HPutImage.
Note that HPutImage automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutImage yourself.
Himage image;
Hrlregion *region;
Hkey image_key,obj_key;
...
/* processed image data: image */
/* processed region data: region */
par_num = 1;
HPutImage(proc_handle,&image,true,&image_key);
HCrObj(proc_handle,par_num,&obj_key);
HDefObj(proc_handle,obj_key,image_key,IMAGE_INDEX);
HPutDRL(proc_handle,obj_key,region,®ion_key);
HDefObj🔗
HDefObj (see Basic routines for creating new iconic objects and writing output iconic parameters) reassigns the component comp (0 … n) of an image object given by its database key comp_key.
A typical application of this routine is shown in Creating a new image object using basic Extension Package Interface routines: Image data is stored in a database object using HPutImage.
Furthermore, a new image object is created by HCrObj.
This new object does not contain any gray value channels, see HCrObj.
Using HDefObj, the previously stored image data is assigned as default gray value component 1 (IMAGE_INDEX) of the new image object.
Note that HDefObj automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HDefObj yourself.
HPutDImage🔗
HPutDImage (see Basic routines for creating new iconic objects and writing output iconic parameters) combines HPutImage and HDefObj.
It stores the gray value channel (image matrix) image in the HALCON database of iconic objects and returns the corresponding database key in image_key.
The parameter copy (false or true) is used as in HPutImage and specifies, whether the pixel data is copied2 or only a pointer to the data is passed to the database.
Moreover, the gray value channel is inserted into the image object obj_key as component comp (1 … n).
Creating a new image object using HPutDImage and HPutDRL shows a typical application of this routine.
Note that HPutDImage automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutDImage yourself.
Hkey obj_key,k;
Himage image;
Hrlregion *region;
...
/* image: processed gray value data */
/* region: region data */
HCrObj(proc_handle,par_num,&obj_key);
HPutDImage(proc_handle,obj_key,IMAGE_INDEX,&image,false,&k);
HPutDRL(proc_handle,obj_key,region,&k);
HCrImage🔗
HCrImage (see Basic routines for creating new iconic objects and writing output iconic parameters) is used for creating output images especially in the context of filter3 operations.
As you know, HALCON image objects can share the underlying image matrices (gray value channels).
Thus, input image objects of a filter operation might only differ in their domain (i.e., in their region component), but not in their gray values.
Such objects have different database keys and different regions, but contain references to the same gray value channels.
Obviously, it is very desirable to propagate this relation to the resulting output image objects as well.
HCrImage allocates memory for the image matrix within the Himage structure image_out (similar to HNewImage in Global data).
The parameters type (BYTE_IMAGE, LONG_IMAGE, FLOAT_IMAGE, etc.; see Definitions of pixel types, width and height allow to specify the pixel type and the size of the new matrix.
Note that new matrices are by default initialized with 0.
However, this can be suppressed from outside or inside of the operator, see the discussion of HNewImage in Global data for details.
Furthermore, HCrImage creates a new database object encapsulating this image data and returns the corresponding database key in image_key_out (similar to HPutImage in HPutImage).
Hkey obj_key,image_key_in,image_key_out,key_out;
Hrlregion *region;
Himage image_in,image_out;
...
HGetSPar(proc_handle,1,LONG_PAR,&Rows,1); /* height: filter mask */
HGetSPar(proc_handle,2,LONG_PAR,&Cols,1); /* width: filter mask */
HAllObj(proc_handle,1,obj_key,i) { /* all input images */
HGetFDRL(proc_handle,obj_key,®ion); /* get region data */
HGetComp(proc_handle,obj_key,IMAGE1,&image_key_in);
if (image_key_in == UNDEFINED)
return(H_ERR_UNDI); /* 'undefined image' */
HGetImage(proc_handle,image_key_in,&image_in); /*get image data*/
HCkP(HCrImage(proc_handle,image_key_in,1,image_in.kind,
image_in.width,image_in.height,
&image_key_out,&image_out));
HCkP(IPFilterOperation(&image_in,region,Rows,Cols,&image_out));
HCopyObj(proc_handle,obj_key,1,&key_out); /* create result obj.*/
HDefObj(proc_handle,key_out,image_key_out,IMAGE1);
/* insert the result image in output object */
}
Finally, HCrImage establishes a link between the original input image data (referenced by the database key image_key_in) and this new iconic object to avoid the allocation of multiple output matrices per input matrix.
HCrImage checks, whether there already exists an output matrix with the specified index index (see below) for a given input image image_key_in.
If there is any, only a reference to it is returned in image_out and image_key_out instead of creating a new matrix.
Without this mechanism, a new matrix would be created again and again within the loop over all input iconic objects (HAllObj).
The parameter index is only of importance, if more than one output matrix per input matrix is needed: This is necessary for example, if an edge filter is performed in x- and y-direction independently.
In this case, HCrImage must be called several times for every input component – one time for each output matrix to be created.
Assign increasing indices (1, 2, 3, …) to the parameter index to indicate a new output matrix.
If there is only one matrix to create for the output image, set index to 1.
A typical example for using HCrImage: Providing an empty image matrix for a filter operation shows an exemplary application of HCrImage.
Note that HCrImage is no macro, i.e., it does not check the result state of the underlying procedure using HCkP (see HCkP).
Thus, you must call HCkP on HCrImage yourself as shown in the example.
HCrXLD🔗
HCrXLD (see Basic routines for creating new iconic objects and writing output iconic parameters) is used for creating XLD objects in the HALCON database of iconic objects.
The parameter xld_type allows to specify the kind of XLD to be created: It has to be set to XLD_CONTOUR_ID in case of a contour and to XLD_POLYGON_ID in case of a polygon.
Corresponding to the selected type, HCrXLD expects a pointer to Hcont or a pointer to Hpoly in the parameter xld.
In both cases, not the underlying XLD data but only the pointers to the data are copied to the database.
Thus, you must not deallocate or overwrite the XLD structures after calling HCrXLD.
Note that HCrXLD automatically checks the result state of the underlying procedure with the macro HCkP (see HCkP).
Thus, you must not use HCkP on HCrXLD yourself.
Hcpar rows[99], cols[99];
INT4_8 i,num_points;
Hkey key_out;
Hcont *cont;
...
HGetCPar(proc_handle,1,DOUBLE_PAR,rows,1,99,&num_points);
HGetCPar(proc_handle,2,DOUBLE_PAR,cols,1,99,&num_points);
/* create a contour (in general, this should be done */
/* calling an appropriate action procedure) */
HCkP(HAllocXLDCont(proc_handle,&cont,num_points));
for (i=0; i < num_points; i++ {
cont->row[i] = rows[i].par.d;
cont->col[i] = cols[i].par.d;
}
cont->num = num_points;
HCrXLD(proc_id,1,cont,XLD_CONTOUR_ID,NULL,0,
(DBFreeProc)HXLDFreeContour,&key_out);
HCrXLD expects an appropriate deallocation routine for the XLD data in the parameter free_proc.
For XLD contours, please use
For XLD polygons allocated based on HAlloc use
Finally, HCrXLD not only creates a new database object, but also appends this object to the output iconic parameter with index par_num.
A typical example for using HCrXLD: Create an XLD contour from a list of points shows a typical application of HCrXLD.
-
This is necessary if the original data is stored in temporary memory or if the data will be modified later on. ↩
-
This is necessary, if the pixel data was stored in temporary memory or if it will be modified later on. ↩
-
This is due to the fact, that filtering only modifies the gray values but not the regions of image objects. ↩