Skip to content

Auxiliary Extension Package Interface macros and procedures🔗

In this section, a couple of auxiliary routines are described that facilitate the programming of supply or action procedures.

Names

HCkP, HCkNoObj, HRLDecomp, HNumOfChannels, HIncrRL

Synopsis

Auxiliary Extension Package Interface macros and procedures
#include "Halcon.h"

HCkP(             Herror          (*proc))

HCkNoObj(         Hproc_handle     proc_handle)

Herror HRLDecomp( Hrlregion const  *reg_in,
                  int              r1,
                  int              c1,
                  int              r2,
                  int              c2,
                  Hrlregion        *reg_inner,
                  Hrlregion        *reg_outer)

HNumOfChannels(   Hproc_handle     proc_handle,
                  INT4_8           obj_index,
                  int              *num_channels)

HError HIncrRL(   Hproc_handle     proc_handle)

HCkP🔗

The macro HCkP (see Auxiliary Extension Package Interface macros and procedures) checks the result state of a procedure call. Most of the HALCON procedures are of the type Herror. For internal HALCON procedures, the result code H_MSG_OK is returned if no error occurred, see also Handling errors in extension packages. HCkP exits the current procedure if the encapsulated procedure returns any other error code. Moreover, this error code is returned to the caller of the current procedure.

The macro is used to make source code more compact, but still safe with respect to error handling, see Error handling with HCkP: Here, the call of the procedure HRLDecomp is encapsulated within the macro. If any error occurs, the procedure exits with an appropriate error code. Otherwise the processing is continued.

Note that most of the interface routines described in this chapter internally call HCkP, i.e. they exit the current procedure returning an appropriate error code in case of an error.

Be aware that all memory permanently allocated within a procedure will not be deallocated in case of an error if you exit the procedure using HCkP. This will lead to memory leaks.

Error handling with HCkP
Herror   err;

/* without HCkP: */
err = HRLDecomp(reg_in,r1,c1,r2,c2,
                reg_inner,reg_outer);
if (err != H_MSG_OK) return err;

/* with HCkP: */
HCkP(HRLDecomp(reg_in,r1,c1,r2,c2,
               reg_inner,reg_outer));

HCkNoObj🔗

The macro HCkNoObj (see Auxiliary Extension Package Interface macros and procedures) is used to check whether all iconic input parameters of an operator contain at least one iconic object. Otherwise, the supply procedure is exited with a return code depending on the current setting of no_object_result accessible by the HALCON operators set_system and get_system. The default setting for no_object_result is H_MSG_TRUE, that means HCkNoObj reports “no error” in case of empty iconic input parameters. Note that in this case all output parameters are also empty.

We recommend to call

HCkNoObj(proc_handle);

at the beginning of the supply procedure for every operator with iconic input objects to guarantee the existence of iconic data to be processed within the operator.

HRLDecomp🔗

HRLDecomp (see Auxiliary Extension Package Interface macros and procedures) is an auxiliary procedure to ease border treatment within the action procedures of filter operators based on filter masks. It’s prototype is included in hlib\HRLClip.h.

Border treatment for a 3 × 3 filter
Herror IPBFilter(HBYTE      *in,            /* input image           */
                 Hrlregion  *region,        /* domain (area of def.) */
                 int        width,          /* image size: width     */
                 int        height,         /* image size: height    */
                 HBYTE      *out)           /* output image          */
{
  ...
  Hrlregion *inner,*outer;

  HCkP(HAllocRLNumTmp(proc_handle,&inner,region->num));
  HCkP(HAllocRLNumTmp(proc_handle,&outer,region->num*2));
  HCkP(HRLDecomp(region,1,1,height-2,width-2,inner,outer));
  /* filtering without border treatment */
  for (i=0; i<inner->num; i++)
    for (k=CB(inner->rl,i,width); k<=CE(inner->rl,i,width); k++)
      out[k] = ...
  /* filtering with border treatment */
  for (i=0; i<outer->num; i++)
    for (k=CB(outer->rl,i,width); k<=CE(outer->rl,i,width); k++)
      out[k] = ...
  HCkP(HFreeRLTmp(proc_handle,outer));
  HCkP(HFreeRLTmp(proc_handle,inner));
}

The region (respectively domain or area of definition) reg_in of the image to be processed is split into two parts: reg_inner and reg_outer. Note that both new regions must have been allocated before, see Temporary data.

reg_inner is the original region reg_in minus the pixels around the image border. It contains all pixels within the rectangle specified by the upper left corner (r1,c1) and the lower right corner (r2,c2).1 These coordinates should be selected that way, that the filter mask is completely within the image when placed on any pixel inside of the rectangle. Thus, no border treatment is necessary within reg_in.

reg_out is set to all remaining pixels within reg_in. For those pixels an appropriate (and time consuming) border treatment has to be performed. Border treatment for a 3 × 3 filter shows an application of HRLDecomp.

Note that HRLDecomp is no macro, i.e., it does not check the result state of the underlying procedure using HCkP. Thus, you must call HCkP on HRLDecomp yourself as shown in the example.

Note that the distinction of “inner” and “outer” area only refers to the image border, but not to the border of the regions specifying the domain (area of definition). So, it is only ensured that no memory access to positions outside the image matrix can happen, but there is no guarantee that all pixel values covered by the filter mask when placed on pixels within reg_inner are defined, if they do not belong to reg_in. This means, a filter might use undefined gray values along the border of the domain of the input images. The HALCON user should keep that in mind, when applying a sequence of filters to restricted regions of interest.

HNumOfChannels🔗

HNumOfChannels (see Auxiliary Extension Package Interface Macros and Procedures) returns for the first input iconic parameter of a HALCON operator the number of channels of the image object with the index obj_index. Thus, this routine is just a shortcut for using HPNumOfChannels as defined in Auxiliary routine HPNumOfChannels with par_num = 1.

Note that HNumOfChannels automatically checks the result state of the underlying procedure with the macro HCkP. Thus, you must not use HCkP on HNumOfChannels yourself.

HIncrRL🔗

HIncrRL (see Auxiliary Extension Package Interface macros and procedures) increases the value of the system parameter ‘current_runlength_number’ by 50%, not exceeding 2*(width+1)*height, where width and height are the dimensions of the largest image. These dimensions are accessible using get_system with ‘width’ and ‘height’. Note, DEF_RL_LENGTH can also be increased using set_system.

As a consequence the procedures HAllocRL (Global data), HAllocRLTmp (Temporary data), and HAllocRLLocal (Temporary data) allocate regions of increased size. Border treatment for a 3 × 3 filter shows an application of HIncrRL.

Note that HIncrRL is no macro, i.e., it does not check the result state of the underlying procedure using HCkP. Thus, you must call HCkP on HIncrRL yourself as shown in the example.

Increasing memory allocated for regions
Hrlregion   *region;
Herror      err;
HCkP(HAllocRLTmp(proc_handle, &region));
do
{
  /* Use HPGetURL instead of HGetURL, to perform explicit error handling. */
  err = HPGetURL(proc_handle, 1, region);
  if (err == H_ERR_WRRLN2)
  /* Number of chords too big, increase /*
  {
    HCkP(HFreeUpToTmp(proc_handle, region));
    HCkP(HIncrRL(proc_handle));
    HCkP(HAllocRLTmp(proc_handle, &region));
  }
  else if (err != H_MSG_OK)
  {
    HCkP(HFreeRLTmp(proc_handle, region));
    return err;
  }
} while (err == H_ERR_WRRLN2);

  1. r1 and r2 denote row coordinates, c1 and c2 column coordinates. ↩