Loop macros🔗
A frequently needed task is to process all image objects (images or regions) passed to an operator by one or two input iconic object parameters. This is true for most filter and many segmentation operators. Loop macros provide a framework for this problem, see also Loop macros for accessing single input objects.
The following table contains an overview of all loop macros, their areas of application, and the provided image data. Their syntax is defined in Convenience loop macros to access iconic objects. “&” denotes output parameters of the macros. This is only a special notation to make clear that these parameters are changed by the macros. So do not pass pointers to variables but the variables itself to the macro.
| Macro | Application | Image Data Provided |
|---|---|---|
HAllReg |
region shape features, region transformation, binary morphology |
region data (Hrlregion) of input image object |
HAllSegm |
gray value features, segmentation |
region and image data (Hrlregion and Himage) of input image object |
HAllFilter |
filter, image transformations |
region and image data (Hrlregion and Himage) of input image object, image data structure (Himage) for image output object |
HAllFilter2 |
filter, segmentation, arithmetic with two input images |
intersection of the regions of both input image objects (Hrlregion), the image data of both objects, and a image data structure (Himage) for the image output object |
Names
Synopsis
#include "Halcon.h"
HAllReg( Hproc_handle proc_handle,
Hrlregion **region,
INT4_8 obj_index)
HAllSegm( Hproc_handle proc_handle,
Hrlregion **region,
Himage *image,
int max_channels,
INT4_8 obj_index)
HAllFilter( Hproc_handle proc_handle,
Hrlregion **region,
Himage *image_in,
Himage *image_out,
int max_channels,
INT4_8 obj_index)
HAllFilter2( Hproc_handle proc_handle,
Hrlregion *region,
Himage *image_in1,
Himage *image_in2,
Himage *image_out,
int max_channels,
INT4_8 obj_index)
All macros described in this section have in common that they implement a loop over all image objects within the first input iconic parameter.
HAllFilter2 also includes a parallel loop over all objects within the second input object parameter.
It is assumed that the operator does not have any more input iconic parameters.
The macros provide users with the region (domain) and the pixel data of each image object so that they can work on the data within the loop.
Some also create output image objects.
The macros return the index of the current object obj_index (1 … n) within the input iconic object parameter.
Thus, obj_index can be seen as a reference parameter of the macro and therefore is notated1 with ‘&obj_index’.
The macros return all regions as pointers to the original region data within the HALCON database.
So the programmer is only allowed to read them.
The only exception is again HAllFilter2 that computes the intersection of the region data of both input images and stores it in a new region.
HAllReg🔗
HAllReg (see Convenience loop macros to access iconic objects. “&” denotes output parameters of the macros. This is only a special notation to make clear that these parameters are changed by the macros. So do not pass pointers to variables but the variables itself to the macro) implements a loop over all iconic objects of the first input image parameter.
For every object within this parameter, it returns the region of the iconic object (domain) in region2.
All gray value channels are ignored.
HAllReg is a combination of HAllObj (see HAllObj) and HGetFDRL (see HGetFDRL).
It is typically used within feature extraction operators: A list of input regions have to be examined concerning special features.
Some HALCON operators of this kind are circularity, area_center, or contlength, for example .
Moreover, it is possible to return new region(s) by using the interface macro HNewRegion (see HNewRegion) as it is done, for example, by erosion_rectangle1 or shape_trans.
Herror CIPCenter(Hproc_handle proc_handle)
{
Hcpar *Row,*Col;
INT4_8 num;
double row,col;
INT4_8 area;
INT4_8 i;
Hrlregion *region;
/* allocate memory corresponding to the number of regions. */
HGetObjNum(proc_handle,1,&num);
HCkP(HAlloc(proc_handle,sizeof(*Row)*num,&Row);
HCkP(HAlloc(proc_handle,sizeof(*Col)*num,&Col);
/* get the regions of all input iconic objects in the first param. */
HAllReg(proc_handle,®ion,i)
{
HCkP(HRLArea(proc_handle,region,&area,&row,&col));
Row[i-1].type = DOUBLE_PAR; /* par. type is float */
Row[i-1].par.d = row; /* resulting row */
Col[i-1].type = DOUBLE_PAR; /* par. type is float */
Col[i-1].par.d = col; /* resulting column */
}
HPutPPar(proc_handle,1,Row,i); /* return result */
HPutPPar(proc_handle,2,Col,i); /* return result */
return(H_MSG_TRUE);
}
An application of HAllReg: Compute the center of gravity for all input regions in the first input iconic object parameter illustrates the application of HAllReg showing a complete supply procedure for a hypothetical operator center that computes the center of gravity of all input regions.
The operator has one input iconic object parameter that exclusively contains regions and two output control parameters for returning the results as tuples of floating-point numbers (the coordinates of the centers of gravity of all regions).
The corresponding DEF file (short version) might look like this:
center may be called with one or more regions as input.
HAllReg implements a loop over all of them, sets the loop index i to the current index of the region (1 … n), and passes a pointer to the region to the action procedure that performs the center of gravity.
In our case the action procedure is the internal HALCON procedure HRLArea.
The result values are written into two arrays of the type Hcpar and returned by HPutCPar (see HPutCPar).
HAllSegm🔗
HAllSegm (see Convenience loop macros to access iconic objects. “&” denotes output parameters of the macros. This is only a special notation to make clear that these parameters are changed by the macros. So do not pass pointers to variables but the variables itself to the macro) extends HAllReg: Not only the region but also all gray value channels of an object within the first input image object parameter are accessed within a loop.
Thus, HAllSegm is a combination/modification of HAllObj (see HAllObj), HGetFDRL (see HGetFDRL), and HAllComp (see HAllComp).
It is especially useful for segmentation operators (transition of gray value channels to regions).
Some typical HALCON operators that make use of HAllSegm are threshold, regiongrowing, auto_threshold, or label_to_region.
A HALCON image object (in short a HALCON image) consists of one region (domain) that specifies its area of definition and of one or more channels (gray value components) containing the pixel data.
All channels of an image are of the same size, but may have different pixel types.
The data contained in a channel (pixel type, the image matrix, etc.) is stored in a structure of type Himage (see Pixel data (Himage)).
If the image has only one channel, the address of a variable of the type Himage is passed to HAllSegm.
For multi-channel images an array of the type Himage[max_channels] must be passed.
The maximal number of channels to be accessed by HAllSegm is specified by the parameter max_channels, see The parameters image and max_channels of HAllSegm.
Himage images[3];
HAllSegm(proc_handle,region,images,3,i) {
...
Himage image;
HAllSegm(proc_handle,region,&image,1,i) {
...
The parameter max_channels only specifies the maximum number of channels.
If an image contains less channels, the corresponding Himage elements in the image array are undefined.
The actual number of channels can be accessed using HNumOfChannels, for example (see HNumOfChannels).
An image must contain at least one channel.
Otherwise, HAllSegm returns an error.
If the number of channels exceeds max_channels, the remaining channels are ignored.
Furthermore, the size of all channels is checked for equality3.
Herror IPSegm(Hproc_handle proc_handle, /* HALCON proc. handle */
Hrlregion *region, /* domain (area of definition) */
Himage *image, /* input image */
Hrlregion *out) /* segmentation result */
{
/* compute region "out" from "region" and "image" */
return(H_MSG_OK);
}
Herror CIPSegm(Hproc_handle proc_handle)
{
INT4_8 i;
Hrlregion *region, *new_region;
Himage image;
HCkP(HAllocRLTmp(proc_handle,&new_region)); /* allocate memory*/
HAllSegm(proc_handle,®ion,&image,1,i) { /* all inp. images*/
HCkP(IPSegm(region,&image,new_region));
HNewRegion(proc_handle,new_region); /* allocate new */
} /* region */
HCkP(HFreeRLTmp(proc_handle,new_region)); /* free memory */
return(H_MSG_TRUE);
}
A typical application of HAllSegm: A segmentation operator shows a framework for a supply procedure for a segmentation operator using HAllSegm.
The corresponding hypothetical operator segm has one input object parameter for input images containing at least one channel.
The DEF file (short version) might look like
The macro HAllSegm used in CIPSegm performs a loop over all image objects within the first input object parameter Image of segm.
With every pass of the loop it returns the image data of the current input object in the variables region (domain) and image (first gray value channel).
The results of the segmentation (new_region) are stored via the macro HNewRegion (see HNewRegion) as new objects of the HALCON database and returned in the (first) output object parameter (Region).
Note that this simple operator has no control parameters.
A new region is allocated for the action procedure via HAllocRLTmp (see Temporary data) before entering the loop.
This region is used as temporary memory for the computation result and must be deallocated (via HFreeRLTmp) before exiting the supply procedure.
HAllFilter🔗
HAllFilter (see Convenience loop macros to access iconic objects. “&” denotes output parameters of the macros. This is only a special notation to make clear that these parameters are changed by the macros. So do not pass pointers to variables but the variables itself to the macro) further extends the loop macros introduced so far: For every input image object a new output image object is created (and added to the first output object parameter) with
- the same number of channels (components),
- the same pixel type (of the corresponding channels),
- the same image size and
- the same area of definition (region, domain).
Thus, HAllFilter is a combination/modification of HAllObj (see HAllObj), HGetFDRL (see HGetFDRL), HAllComp (see HAllComp), HCopyObj (see HCopyObj), and HPutDImage (see HPutDImage).
It has been designed for filter operators that typically create a modified result image for every input image.
The region remains unmodified.
Typical examples for this functionality are the HALCON operators sobel_amp, mean_image, scale_image_max, or texture_laws.
Herror IPScaleNew(Hrlregion *region,
Himage *image_in,
Himage *image_out,
{
INT4_8 i,l,end;
double h;
for (i=0; i<region->num; i++) {
end = CE(region->rl,i,image_in->width);
for (l=CB(region->rl,i,image_in->width); l<=end; l++) {
HDFImage(h,image_in,l);
HImageFD(image_out,h*mult,l);
} }
return(H_MSG_OK);
}
Herror CIPScaleNew(Hproc_handle proc_handle)
{
Hcpar mult;
Hrlregion *region;
Himage image_in,image_out;
INT4_8 i;
HGetSPar(proc_handle,1,DOUBLE_PAR,&mult,1);
HAllFilter(proc_handle,®ion,&image_in,&image_out,1,i) {
HCkP(IPScaleNew(region,&image_in,mult.par.d,&image_out));
}
return(H_MSG_TRUE);
}
A typical application of HAllFilter: A filter operator shows a typical application of HAllFilter – a hypothetical operator scale_new that multiplies all gray values of the input objects within the first input object parameter with a constant.
The corresponding DEF file (short version) might look like
The operator has one input object parameter (Image) that contains one or more input image objects (each consisting of one or more gray value channels and one region as domain, i.e., area of definition).
With every pass of the loop an image object is accessed and its components are transferred to region and image_in, see also HAllSegm in HAllSegm.
These components are passed to the action procedure IPScaleNew.
In this example only the first channel of each input object is used.
HAllFilter also creates output objects (in the HALCON database) to return the modified data.
Furthermore, these objects are added to the list of objects for the first output object parameter (here ImageScaled).
Their underlying image matrices are accessible via image_out.
Those are also passed to the action procedure IPScaleNew within the loop.
IPScaleNew calculates the new gray values for all pixels within the domain of the input image and writes them into the provided image components image_out4.
The regions of the image objects remain unmodified so that all pixels of output objects lying outside the region are undefined.
Note that HAllFilter creates all necessary image matrices, combines them with the input regions to new image objects, and returns those in the first output object parameter.
So the programmer of the supply procedure needs not to bother about the handling of image objects etc.
To access the input control parameter, HGetSPar (see HGetSPar) is used in the example.
The structure image_in may contain different pixel types.
There are several ways to handle this within an operator:
- The simplest method is to implement the operator just for the most common pixel type
BYTE_IMAGEand return an error message (H_ERR_WIT) for any other pixel type. - Another way is to provide several action procedures – one for every pixel type – and call the appropriate procedure via
switch(image_in.kind). - The third (generic) method makes use of the macros
HDFImageandHImageFD, see Auxiliary macros for generic access to pixel data. “&” denotes an output parameter of HDFImage. This is only a special notation to make clear that this parameter is changed by the macro. So do not pass a pointer to double but the double variable itself to the macro. They encapsulate the access to gray values by buffering them in adoublevariable. By writing pixel values viaHImageFD, thedoublevaluevalis converted into the current pixel type ofimage_in(and therefore may be clipped) and stored in the pixel specified by the linear coordinatelin_coord, see Pixel data (Himage). The other way around, the specified pixel value is converted todoubleand returned invalwhen usingHDFImageto read image data.
The third method has been used in our example, as it allows a very compact source code.
But this variant naturally shows drawbacks in terms of computation time: Two type conversions have to be computed with every pixel access and all pixel arithmetic has to be done in double.
Names
Synopsis
#include "Halcon.h"
HDFImage( double &val,
Himage *image,
INT4_8 lin_coord)
HImageFD( Himage *image,
double val,
INT4_8 lin_coord)
HAllFilter2🔗
The macro HAllFilter2 (see Convenience loop macros to access iconic objects. “&” denotes output parameters of the macros. This is only a special notation to make clear that these parameters are changed by the macros. So do not pass pointers to variables but the variables itself to the macro) is a variation of HAllFilter introduced in the previous section.
It facilitates the implementation of filters with two input object parameters.
Examples for this technique are the HALCON operators add_image, mult_image, bit_and, and max_image.
HAllFilter2 extends HAllFiter so that with every image object of the first input object parameter also the corresponding image object (with the same object index obj_index) of the second input object parameter is provided.
Moreover, it checks the image sizes of both image objects for equality.
If the sizes are equal, the images are provided in the loop variables image_in1 and image_in2, otherwise an error is returned.
Moreover, HAllFilter2 computes a new input region (region) by intersecting the domains (areas of definition) of both input images.
Note that memory for this region must have been allocated before (e.g. with HAllocRLTmp).
Furthermore, region must be deallocated at the end of the supply procedure (HFreeRLTmp).
Output image objects are created and returned in the first output object parameter in the same way as described for HAllFilter in HAllFilter.
A typical application of HAllFilter2 shows a typical application of HAllFilter2 – the implementation of an operator that adds the gray values of two input images.
As in procedure IPScaleNew in A typical application of HAllFilter: A filter operator, the macros HDFImage and HImageFD are used to read and write pixel values.
This example exhibits the additional advantage that the operator can even add the gray values of two images with different pixel types.
Herror IPAddNew(Hproc_handle proc_handle,
Hrlregion *region,
Himage *image_in1,*image_in2,*image_out)
{
INT4_8 i,l,end;
double h1,h2;
for (i=0; i<region->num; i++) {
end = CE(region->rl,i,image_in->width);
for (l=CB(region->rl,i,image_in->width); l<=end; l++) {
HDFImage(h1,image_in1,l);
HDFImage(h2,image_in2,l);
HImageFD(image_out,h1+h2,l);
} }
return(H_MSG_OK);
}
Herror CIPAddNew(Hproc_handle proc_handle)
{
Hrlregion *region;
Himage image_in1,image_in2,image_out;
INT4_8 i;
HCkP(HAllocRLTmp(proc_handle,®ion));
HAllFilter2(proc_handle,region,&image_in1,
&image_in2,&image_out,1,i) {
HCkP(IPAddNew(proc_handle,region,&image_in1,
&image_in2,&image_out));
}
HCkP(HFreeRLTmp(proc_handle,region));
return(H_MSG_TRUE);
}
-
Note that this is a specific notation only - do not pass pointers to the macros! ↩
-
Remember: HALCON image objects consist of one region specifying the domain (area of definition) and an arbitrary number of gray value channels containing the pixel data ↩
-
Remember: The sizes must be equal, whereas the pixel types of different channels may vary ↩
-
Note that
image_outcontains a pointer to a pixel matrix with the same size and pixel type asimage_in. ↩