read_dictT_read_dictReadDictReadDict (Operator)


read_dictT_read_dictReadDictReadDict — Read a dictionary from a file.


read_dict( : : FileName, GenParamName, GenParamValue : DictHandle)

Herror T_read_dict(const Htuple FileName, const Htuple GenParamName, const Htuple GenParamValue, Htuple* DictHandle)

void ReadDict(const HTuple& FileName, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* DictHandle)

void HDict::HDict(const HString& FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

void HDict::HDict(const HString& FileName, const HString& GenParamName, const HString& GenParamValue)

void HDict::HDict(const char* FileName, const char* GenParamName, const char* GenParamValue)

void HDict::HDict(const wchar_t* FileName, const wchar_t* GenParamName, const wchar_t* GenParamValue)   (Windows only)

void HDict::ReadDict(const HString& FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

void HDict::ReadDict(const HString& FileName, const HString& GenParamName, const HString& GenParamValue)

void HDict::ReadDict(const char* FileName, const char* GenParamName, const char* GenParamValue)

void HDict::ReadDict(const wchar_t* FileName, const wchar_t* GenParamName, const wchar_t* GenParamValue)   (Windows only)

static void HOperatorSet.ReadDict(HTuple fileName, HTuple genParamName, HTuple genParamValue, out HTuple dictHandle)

public HDict(string fileName, HTuple genParamName, HTuple genParamValue)

public HDict(string fileName, string genParamName, string genParamValue)

void HDict.ReadDict(string fileName, HTuple genParamName, HTuple genParamValue)

void HDict.ReadDict(string fileName, string genParamName, string genParamValue)


read_dictread_dictReadDictReadDictReadDict reads a dictionary from the file FileNameFileNameFileNameFileNamefileName and returns the handle of the dictionary in DictHandleDictHandleDictHandleDictHandledictHandle.

The operator supports the following file formats:


Binary HALCON format for dictionaries. Files with this format can be written by write_dictwrite_dictWriteDictWriteDictWriteDict. The default file extension for this format is 'hdict'.


JSON (JavaScript Object Notation) file format. The default file extension for this format is 'json'.

If the given file does not exist, the operator attempts to find the file by appending the default file extensions to the filename. The file type is automatically recognized based on the file content and the file ending (which have to be consistent).

A set of additional optional parameters can be set. The names and values of the parameters are passed in GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. Some of the optional parameters can only be set for a certain file type. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName are possible:

'json_value_true'"json_value_true""json_value_true""json_value_true""json_value_true", 'json_value_false'"json_value_false""json_value_false""json_value_false""json_value_false", 'json_value_null'"json_value_null""json_value_null""json_value_null""json_value_null":

Set the values that are used for JSON primitives. Valid JSON primitives are 'true'"true""true""true""true", 'false'"false""false""false""false", and 'null'"null""null""null""null". When encountering such a primitive in a JSON file, the corresponding value in the read dictionary is set to the value defined with these parameters. The value passed in GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue must be a tuple of length 1.

The default values for primitives are 1 for 'true'"true""true""true""true", 0 for 'false'"false""false""false""false", and 'HNULL'"HNULL""HNULL""HNULL""HNULL" for 'null'"null""null""null""null". These parameters only have an effect when reading a JSON file.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.


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

File name.

File extension: .hdict, .json

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

Name of the generic parameter.

Default value: []

List of values: 'json_value_false'"json_value_false""json_value_false""json_value_false""json_value_false", 'json_value_null'"json_value_null""json_value_null""json_value_null""json_value_null", 'json_value_true'"json_value_true""json_value_true""json_value_true""json_value_true"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Value of the generic parameter.

Default value: []

Suggested values: 0, 1, 'HNULL'"HNULL""HNULL""HNULL""HNULL"

DictHandleDictHandleDictHandleDictHandledictHandle (output_control)  dict HDict, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Dictionary handle.

Number of elements: DictHandle == 1


If the parameters are valid, the operator read_dictread_dictReadDictReadDictReadDict returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.

Possible Predecessors


See also

write_dictwrite_dictWriteDictWriteDictWriteDict, serialize_handleserialize_handleSerializeHandleSerializeHandleSerializeHandle, deserialize_handledeserialize_handleDeserializeHandleDeserializeHandleDeserializeHandle