Skip to content

Additional routines for accessing input image objects🔗

This section introduces some routines that ease the programming of supply procedures in many applications, see Additional routines for accessing input image objects. Basically they are combinations of the routines described in Basic access to iconic input objects. These additional routines only require the database keys of the input iconic objects that can be extracted by using the routines HGetObj or HAllObj. For HGetURL, even this step can be omitted.

Names

HGetDRL, HGetFDRL, HGetURL, HGetDImage, HGetObjNum

Synopsis

Additional routines for accessing input image objects
#include "Halcon.h"

HGetDRL(   Hproc_handle     proc_handle,
           Hkey             obj_key,
           Hrlregion        *region)

HGetFDRL(  Hproc_handle     proc_handle,
           Hkey             obj_key,
           Hrlregion        **region)

HGetURL(   Hproc_handle     proc_handle,
           int              par_num,
           Hrlregion        *region)

HGetDImage(Hproc_handle     proc_handle,
           Hkey             obj_key,
           int              channel,
           Himage           *image)

HGetObjNum(Hproc_handle     proc_handle,
           int              par_num,
           INT4_8           *num)

HGetDRL🔗

Application of HGetDRL
Hrlregion  *region;
Hkey       obj_key;
...
HCkP(HAllocRLTmp(proc_handle,&region));
HGetObj(proc_handle,par_num,obj_num,&obj_key);
HGetDRL(proc_handle,obj_key,region);
/* processing (in general this should be done calling an action proc.) */
area = 0;
for (i=0; i<region->num; i++)
  area += region->rl[i].ce - region->rl[i].cb + 1;
HCkP(HFreeRLTmp(proc_handle,region));

HGetDRL (see Additional routines for accessing input image objects) combines HGetComp and HGetRL. It reads the runlength encoding of a region (type: Hrlregion, see Region data (Hrlregion)) specified by the database key obj_key of an image object. The region data is copied to region, which must have been allocated before with a suitable size (for example, by using HAllocRLTmp, see Temporary data). Therefore, this region data can be overwritten without side effects. On the other hand, the memory must be deallocated at the end of the supply procedure (for example, by using HFreeRLTmp). Application of HGetDRL shows an example application of HGetDRL.

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

HGetFDRL🔗

Application of HGetFDRL
Hkey       obj_key;
Hrlregion  *region;
...
HGetFDRL(proc_handle,obj_key,&region);
/* processing (in general this should be done calling an action proc.) */
area = 0;
for (i=0; i<region->num; i++)
  area += region->rl[i].ce - region->rl[i].cb + 1;

In contrast to HGetDRL, only a pointer to the region data is returned by HGetFDRL (see Additional routines for accessing input image objects). So there is no need to allocate memory for the data. On the other hand, only read access to the data is allowed. An example application of HGetFDRL can be seen in Application of HGetFDRL.

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

HGetURL🔗

HGetURL (see Additional routines for accessing input image objects) reads all regions passed in the input iconic parameter with the index par_num, computes the union of all these regions, and returns the resulting region in region. The Hrlregion data referenced by region must have been allocated before with a suitable size (for example, by using HAllocRLTmp, see Temporary data, which can be increased for example, by using HIncrRL, see HIncrRL). Therefore, this region data can be overwritten without side effects. On the other hand, the memory must be deallocated at the end of the supply procedure (for example, by using HFreeRLTmp). Application of HGetURL shows an application of HGetURL. Note that the area calculated in the example may differ from the sum of the areas of all single regions, because the single regions may overlap.

Note that HGetURL automatically checks the result state of the underlying procedure with the macro HCkP. Thus, you must not use HCkP on HGetURL yourself.
If you do not want to have the result state checked with HCkP, use HPGetURL instead. HPGetURL and HGetURL only differ regarding HCkP.

Application of HGetURL
Hrlregion  *region;
...
HCkP(HAllocRLTmp(proc_handle,&region));
HGetURL(proc_handle,par_num,region);
/* processing (in general this should be done calling an action proc.) */
area = 0;
for (i=0; i<region->num; i++)
  area += region->rl[i].ce - region->rl[i].cb + 1;
HCkP(HFreeRLTmp(proc_handle,region));

HGetDImage🔗

HGetDImage (see Additional routines for accessing input image objects) combines HGetComp (HGetComp) and HGetImage (HGetImage). It reads the data of the gray value component channel of the image object specified by the database key obj_key and returns it in the Himage structure (image).

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

Application of HGetDImage: Return the gray value at position (row,col) in the first channel of the input iconic object obj_key
Himage  image;
Hcpar   row,col,gray;
...
HGetSPar(proc_handle,1,LONG_PAR,&row,1);     /* row    */
HGetSPar(proc_handle,2,LONG_PAR,&col,1);     /* column */
coord = HLinCoor(row.par.l,col.par.l,image.width);
HGetDImage(proc_handle,obj_key,IMAGE_INDEX,&image);
/* processing (in general this should be done calling an action proc.) */
switch (image.kind) {
  case BYTE_IMAGE:
    gray.par.l = image.pixel.b[coord];
    gray.type  = LONG_PAR;
    break;
  case FLOAT_IMAGE:
    gray.par.d = image.pixel.f[coord];
    gray.type  = DOUBLE_PAR;
    break;
  default:
    return(H_ERR_WIT);   /* wrong image type */
}
HPutCPar(proc_handle,1,&gray,1);

For the sake of efficiency, only a pointer to the image matrix is copied to image, instead of copying the data itself. So, only read access to the image data is recommended in order to avoid unpredictable side effects. Application of HGetDImage: Return the gray value at position (row,col) in the first channel of the input iconic object obj_key shows an application of HGetDImage.

HGetObjNum🔗

HGetObjNum (see Additional routines for accessing input image objects) returns the number of iconic objects which are stored in the input iconic parameter denoted by its index par_num (from 1 to n). It is an alternative to the usage of HReadGVA (compare HGetObj). By using HGetObjNum, the example of Example for HGetObj: Database keys of all iconic objects of all input object parameters looks as follows (see Application of HGetObjNum: Access the number of iconic objects of an input iconic parameter).

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

Application of HGetObjNum: Access the number of iconic objects of an input iconic parameter
int     inp_pars;
INT4_8  num_objs;
Hkey    key;
int     p,o;
...
/* get number of input iconic parameters:                     */
/* note: This number is known in general - it is specified by */
/* the operator header in the corresponding DEF file of the   */
/* operator                                                   */
HReadGV(proc_handle,HGinp_obj,&inp_pars);
for (p=1; p<=inp_pars; p++) {
   /* get number of iconic objects per input iconic parameter: */
   HGetObjNum(proc_handle,p,&num_objs);
   for (o=1; o<=num_objs; o++) {
      HGetObj(proc_handle,p,o,&key); /* get key of iconic object   */
      /* further processing ... */
   }
}