count_relationcount_relationCountRelationCountRelation (Operator)


count_relationcount_relationCountRelationCountRelation — Number of entries in the HALCON database.


count_relation( : : RelationName : NumOfTuples)

Herror count_relation(const char* RelationName, Hlong* NumOfTuples)

Herror T_count_relation(const Htuple RelationName, Htuple* NumOfTuples)

void CountRelation(const HTuple& RelationName, HTuple* NumOfTuples)

static Hlong HSystem::CountRelation(const HString& RelationName)

static Hlong HSystem::CountRelation(const char* RelationName)

static Hlong HSystem::CountRelation(const wchar_t* RelationName)   (Windows only)

static void HOperatorSet.CountRelation(HTuple relationName, out HTuple numOfTuples)

static int HSystem.CountRelation(string relationName)


count_relationcount_relationCountRelationCountRelationCountRelation returns the number of entries NumOfTuplesNumOfTuplesNumOfTuplesNumOfTuplesnumOfTuples in the relation RelationNameRelationNameRelationNameRelationNamerelationName of the HALCON database since the database was switched on with the set_systemset_systemSetSystemSetSystemSetSystem parameter 'database'"database""database""database""database". If the database is disabled, NumOfTuplesNumOfTuplesNumOfTuplesNumOfTuplesnumOfTuples is 0 and in addition a warning is raised if 'do_low_error'"do_low_error""do_low_error""do_low_error""do_low_error" is set with set_systemset_systemSetSystemSetSystemSetSystem. The state of the database can be queried by the parameter 'database'"database""database""database""database" of get_systemget_systemGetSystemGetSystemGetSystem.

The HALCON database is organized in five tables called relations. The entries in this relations are called tuples (not to mix up with HALCON tuples naming object arrays). If enabled, the HALCON database contains the basic relations for region data, image matrices, and XLDs, as well as the container relations for HALCON objects and HALCON tuples (i.e., object arrays). The HALCON objects region and image are constructed from elements from the region-data relations and the image-matrix relations. A region consists of a pointer to a tuple in the region-data relation. An image consists of a pointer to a tuple in the region-data relation and additionally of one or more pointers to tuples in the matrix relation. Multi-channel images have multiple matrix pointers.

Both regions and images are called objects. A region can be considered as the special case of an iconic object having no image matrices. For reasons of an efficient memory management, the tuples of the region-data relation and the image-matrix relation will be used by different objects together. Therefore there may be more images than image matrices. Only the three low-level relations 'image'"image""image""image""image", 'region'"region""region""region""region", and 'XLD'"XLD""XLD""XLD""XLD" are of relevance to the memory consumption. Image objects (regions as well as images) consist only of references on region and matrix data and therefore only need a couple of bytes of memory.

Possible values for RelationNameRelationNameRelationNameRelationNamerelationName:


Image matrices. One matrix may be the component of multiple images (no redundant storage).


Regions and image domains. One region may be the component of multiple image objects (no redundant storage).


eXtended Line Description: Contours, polygons, parallels, lines, etc. XLD data types don't have gray values and are stored with subpixel accuracy.


Iconic objects. Composed of a region (see 'region') and optionally image matrices (see 'image').


In the compact mode, tuples of iconic objects are stored as a surrogate in this relation. Instead of working with the individual object keys, only this tuple key is used. It depends on the host language, whether the objects are passed individually (e.g., C++) or as tuples (e.g., C).

Certain database objects will be created already by the operator reset_obj_dbreset_obj_dbResetObjDbResetObjDbResetObjDb and therefore have to be available all the time (the undefined gray value component, the objects 'full' (FULL_REGION in HALCON/C) and 'empty' (EMPTY_REGION in HALCON/C) as well as the herein included empty and full region). By calling get_channel_infoget_channel_infoGetChannelInfoGetChannelInfoGetChannelInfo, the operator therefore appears correspondingly also as 'creator' of the full and empty region. The operator can be used for example to check the completeness of the clear_objclear_objClearObjClearObjClearObj operation.


Collecting database information is not threadsafe when passing iconic objects between threads, meaning when deleting objects in a different thread than generating them.

Execution Information


RelationNameRelationNameRelationNameRelationNamerelationName (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Relation of interest of the HALCON database.

Default value: 'object' "object" "object" "object" "object"

List of values: 'XLD'"XLD""XLD""XLD""XLD", 'image'"image""image""image""image", 'object'"object""object""object""object", 'region'"region""region""region""region", 'tuple'"tuple""tuple""tuple""tuple"

NumOfTuplesNumOfTuplesNumOfTuplesNumOfTuplesnumOfTuples (output_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of tuples in the relation.

Example (HDevelop)

* Close the graphics window in order to close the graphics stack,
* which would influence the measurement.
dev_close_window ()
* Enable the measurement.
set_system ('database','true')
count_relation ('image', I1)
count_relation ('region', R1)
count_relation ('XLD', X1)
count_relation ('object', O1)
count_relation ('tuple', T1)
* Result:
* I1 = 0
* R1 = 0
* X1 = 0
* O1 = 0
* T1 = 0
read_image (Patras, 'patras')
count_relation ('image', I2)
count_relation ('region', R2)
count_relation ('XLD', X2)
count_relation ('object', O2)
count_relation ('tuple', T2)
* I2 = 3  (three channels of the rgb image 'patras')
* R2 = 1  (the image domain of the image 'patras')
* X2 = 0  (no XLD data)
* O2 = 1  (the iconic object holding the channels and the domain)
* T2 = 0  (no empty object or object array )


If the parameter is correct, the operator count_relationcount_relationCountRelationCountRelationCountRelation returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Possible Predecessors


Possible Successors


See also