Dictionary

The Dictionary type is primarily intended to be sent to an external program. It is in some way similar to a Group variable. The difference is that from a programming point a Group is a structure with pre-defined variables but a Dictionary is a data structure where the entries might or might be defined.

ImageTank uses a strongly typed approach. What that means is that expressions can be validated even if there is no data. This means that a lot of problems can be detected before the data starts to flow. This means that the structure of variables such as what the names of the channels of an Image are and what the name and type of every column in a Table is is known.

The issue with the strongly typed approach is that if you are sending a parameter set into an eternal program using a Group variable, you have to regenerate the glue code every time you add or remove a parameter from the group.

You create a Dictionary from the Misc menu in the toolbar, in the same menu as you use to create a Group. For simple cases things look very similar. Note however that the order of the variables are different. The group has an order that is specified, while the Dictionary always sorts the names alphabetically.

The Dictionary also has a lot fewer data types. The Group can contain any data type that can be saved into a data file, but the Dictionary type can only contain a number, text, list of numbers or a dictionary.

The Number menu is a way to create a simple UI for specifying parameters. For code you often have a limited number of options for a parameter. Maybe you want to toggle between two options inside your code. Rather then having to remember the magic numbers/labels you can put the magic numbers into a menu and use a more descriptive label for them.

Use inside ImageTank

You can reference Dictionaries inside ImageTank by using the local variable mechanism. If you click on the + button int the local variable list you add a Dictionary reference to get to the numerical values defined inside the Dictionary.

You can drag the Dictionary object onto the + button as well to both create and select the variable. To show the difference between the typed approach of a Group and the dynamic nature of a Dictionary consider an entry where you import both types.

Since the Group variable has a known structure the “a” entry is automatically imported and you can use it. However even though the flag variable exists in the Dictionary, since it is Dynamic ImageTank does not know that. The Dictionary could come from a JSON object and ImageTank does not require you to specify the structure that comes in.

What you need to do is to specify which variables you want to extract from the Dictionary

Convert to Group

You can convert a Dictionary to a Group by using the gear menu. This will allow you to select which entries you want to include. You can only pick from entries that exist for the dictionary that is displayed. If at a later point the variable is not saved it will cause a run time error message.

Use in external programs

The main use for a Dictionary is in external programs to simplify input arguments. Instead of sending in a large number of parameters that will clutter the argument list, it is better to send all of the parameters as a single object. You can then hand this object into other functions and in your code pick the value you want dynamically.

Let’s go through a C++ example. You hand in the Dictionary the same way as any other variable.

void Computation(const DTDictionary &parameters)
{
    double a = parameters("a");
    std::string label = parameters("label");
    if (parameter.Contains("flag")) {
        int flag = parameters("flag");
    }
    double optional = parameters.GetNumber("optional",0);
}

If the parameter doesn’t exist or exists but has a different type you get a run-time warning. You can check if a parameter name exists and what the type is (not shown in the code above). The GetNumber(name,fallback) function is a way to specify that a parameter should be used if it is defined, but otherwise quietly use the second argument.