Per-Pixel Decision Graph Filter Reference

The per-pixel decision graph filter allows the user to specify a ruleset that makes classification decisions based on channel values of pixels.

Category	Classification
Node
Parameters	Number of inputs: how many inputs to use for this filter Decision Graph: the decision graph itself (see below)
Inputs	Input #1 (up to Input #4): the pixel-based input data to apply the decision graph to
Outputs	Class / Quality: the result of the decision graph

Effect of the Filter

The filter takes one or more inputs of pixel type. If more than one input is used, the pixels of each input must come from the same origin, but may have different preprocessing steps. (Each pixel in the first input must be able to be matched against the same pixel in each other input.)

On each pixel the filter will then apply a user-specified classification ruleset, and the result of that will be the output of the filter.

The user may choose what output should be generated:

It may output a class for each pixel, so that each pixel is assigned either a unique group from the list of groups in the model (or be marked as “unclassified”).

It may output one or more quality values for each pixel, which are arbitrary numbers whose meaning the user can define themselves.

Outputting a class

fluxTrainer models allow for the definition of groups that may be used to label input data. Certain classification filters allow for the use of machine learning algorithms to determine the best group that matches input data and automatically assign it to either individual pixels or objects as a class.

The per-pixel decision graph filter extends this by allowing the user to manually assign a previously defined group as a class to a pixel, but using a fixed ruleset instead of a machine learning algorithm.

The groups that are assigned by this filter in this way do not need to have any input data assigned to them, they may only exist as a possible classification result.

Assigning quality values

As an alternative to assigning a class to each pixel it is also possible to define quality parameters that are set based on the specified ruleset.

Quality parameters are an array of one or more integers. The type of integer (8, 16, 32, or 64 bit; signed or unsigned) and the number of quality parameters are specified by the user.

For example, it is possible to define a single 16bit unsigned integer as a quality parameter, or to use two signed 32bit integers. When editing the decision graph (see below) the user may specify these parameters as well as the ruleset that fills these values.

The semantics of these quality parameters are completely up to the user.

Example of Filter Effect

As an example, take the following image as the input of the decision graph filter:

_images/perpixeldecisiongraph_input_pixels.png

When applying a decision graph that generates a class as its result, the resulting classification image may look like this:

_images/perpixeldecisiongraph_output_class.png

Decision Graphs

Decision graphs may be edited by clicking on the Edit… button of the Decision Graph parameter of the filter. It will open a new window that allows for editing the decision graph.

Note

The input of the filter should be connected before opening the editor so that the editor can know which input channels may be used for conditions.

The decision graph editor of an empty decision graph will look like the following screenshot:

_images/perpixeldecisiongraph_editor_plain.png

The editor is divided into four regions:

On the top left the user may specify what type of result it outputs. This may either be Quality Values or Classification Result.

At the left center the user may configure either the default classification result if no defined rule matches a pixel, or they may configure a set of quality parameters together with their default values.

On the bottom left there is a list of elements (conditions, actions, and logical operations) that may be added to the decision graph. The individual elements will be described below.

On the right side of the editor the decision graph itself is displayed. Initially this will be an empty canvas the user has to fill with the nodes required for the ruleset.

The following sub-sections describe how the decision graph editor works.

Decision Graph Nodes

A decision graph consists of nodes that form the graph. To add a node they can be dragged from the list of available nodes into the canvas:

_images/perpixeldecisiongraph_editor_drag_node.png

There are three types of nodes that may be added to a decision graph:

All nodes have their inputs on the left hand side and their outputs on the right hand side. To connect two nodes drag a line from the output of one node to the input of another node.

In a decision graph all inputs of each node must be connected for the decision graph to be valid. Outputs of nodes may be left unconnected if they are not used.

Nodes that have outputs may either be true or false. For example, a condition node that determines if a specific channel of an input pixel is larger than 42 may either be true for that pixel (if that channel is indeed larger than 42) or false for that pixel (if it is not). If the node does evaluate to true, the True output will be true and the False output will be false. If the node evaluates to false, the True output will be false and the False output will be true. Having each node always have both True and False outputs avoids the need to have a separate node for logical not operations.

Nodes may be edited by the user by using the controls shown within the node. Condition and action nodes both have buttons with a ... caption that allow the user to edit these in a new window. Action nodes additionally allow the user to set the nodes priority (see below) within the node directly. Logic nodes allow the user to swtich between logical and and logical or via a dropdown.

The number displayed next to the node caption in parenthesis (for example (1) or (2)) is generated automatically, has no semantic meaning, and is present only for error reporting purposes: if there is an error in a decision graph, the number of the node will be shown in the error message, allowing the user to more easily track down the node that has the specific issue. The number does not correspond to any kind of evaluation order of the graph.

A decision graph may not have cycles: it is not allowed to connect the output of a node to one of its inputs, or to the input of another node that itself feeds the node directly or indirectly.

The various types of nodes will be described in the sections Conditions, Logical Operations, and Actions.

Defining Quality Parameters

In order to define the quality parameters one must first indicate that quality parameters is desired Output Type of the filter in the top-left corner of the edit widget. Then the user should select the data type. Signed and unsigned integers from 8bit to 64bit are available as possible data types for the quality parameters.

_images/perpixeldecisiongraph_editor_quality_datatype.png

All quality parameters will use the same data type.

After selecting the appropriate data type, one may add a quality parameter be clicking on the + button. After clicking on that button a new entry will be added to the list of quality parameters. By default a name of the form QualityX will be assigned, where X will be replaced by a number:

_images/perpixeldecisiongraph_editor_quality_add1.png

It is possible to change the name of a quality parameter by starting to type when the table cell containing the name is selected. (Pressing F2 or double-clicking the cell will also activate the editor that modifies the cell’s contents.)

It is important to note that the name of the quality parameter is only present in the editor of the decision graph, so that is very easy to see which quality value is being assigned by an action. When processing the pixels the quality values will simply be the output channels for each of the pixels in the output.

In addition to the name it is also possible to set the default value of the quality parameter.

_images/perpixeldecisiongraph_editor_quality_default1.png

If no actions change a given quality parameter (because no conditions apply) this will be the value that is stored in the quality parameter instead. See the section Default Values and Action Priorities for further details on this.

The following screenshot shows what happens after adding a second quality parameter to the list.

_images/perpixeldecisiongraph_editor_quality_default2.png

The number of quality parameters is limited by the amount of RAM available on the system.

Conditions

Condition nodes allow for matching of pixel channel values. After clicking on the ... button in the condition node, a new dialog will open that allows the user to specify the condition in detail:

_images/perpixeldecisiongraph_editor_dialog_condition.png

The input selector allows the user to select which of the inputs of the filter to look at for this condition. For example, the following screenshot shows how to match against the first input: column:

_images/perpixeldecisiongraph_editor_dialog_condition_input.png

The entry selector allows for indexing into the channels of the input data. Since conditions always apply to individual numbers, and inputs may have multiple channels, this allows the user to determine which channel they want to match against. If the channel has an additional label associated with it (such as a wavelength), that label is displayed here as well.

The condition dropdown allows the user to select which type of comparison should be made. The following conditions are available:

== to determine if a value is exactly equal to the comparison value. Please note that for floating point numbers exact equality is often not very useful and may lead to surprising results. (For integers exact equality is very useful though.) != is the opposite and determines if a value is distinct from the comparison value.

< to determine if a value is smaller than the comparison value, <= if it is smaller than or equal to, > if it is larger, and >= if it is larger than or equal to.

The range-based options determine whether a value is within a given range or not. Instead of a single comparison value there are two comparison values and they define a range. The inside range variants will be true if the value is within the specified range and the outside range variants will be true if the value is outside of the specified range. The included and excluded options determine if the edges of the ranges are considered part of the range, or not. inside range (included) thus evaluates to value >= lower and value <= upper, outside range (included) evaluates to value < lower or value > upper, inside range (excluded) evaluates to value > lower and value < upper, and outside range (excluded) evaluates to value <= lower or value >= upper.

Finally, the comparison value or range allows the user to specify against which the selected field the value should be compared against.

Note

It is important that the input of the Per-Pixel Decision Graph Filter in the model is connected. Otherwise the input selector will not be able to provide a list of available inputs, and the entry selector will not be able to provide a list of channels.

Logical Operations

A logic node is a node that performs a boolean logic operation on its inputs. It allows for combining conditions in various manners. There are two boolean operations available: And and Or:

For an And node to evaluate to true both of its inputs, A and B, must be true.

For an Or node to evaluate to true one or both of its inputs, A or B, must be true.

Actions

Action nodes are used to update the classification in response to a given condition. An action is only executed for a given obejct if its input evaluates to true for that pixel, otherwise it will be ignored.

Clicking on the ... button within the node opens a dialog that allows the user to select what class or quality value to set. The following screenshot shows how the dialog looks like when the output of the decision graph is a class:

_images/perpixeldecisiongraph_editor_dialog_action_class.png

If the user has chosen to output quality values instead of a class, the dialog will provide the user with a selection of which quality value to update, plus the numerical value to set it to:

_images/perpixeldecisiongraph_editor_dialog_action_quality.png

After setting what should happen for this action, the user may also specify a priority for the action in the node. If more than one action is to be executed for a given pixel, the order is determined by the priority, where lower numbers are executed first. See the next section for further details on this.

Default Values and Action Priorities

When the decision graph is applied to a given pixel, the following steps are performed:

First the specified default values are set for the output for that pixel.

After setting the default values, all conditions and logical operations are evaluated in the appropriate order.

Finally all actions whose inputs have evaluated to true are applied. The order of the actions is given by the user-specified priority. Actions with lower numbers are applied first, actions with higher numbers are applied later. If two actions modify the same quality parameter (or both actions modify the class of the pixel), and both of their inputs evaluate to true, the action with the highest priority will be the last action to be applied, and that value will be stored.

If two actions have the same priority, the ordering between the actions is not specified, and may change whenever the decision graph is stored again. In that case the user has no control over which action will go first. If both actions modify different quality parameters this is not an issue, but if both actions modify the same quality parameter (or both modify the class) either value may be used as the result of the decision graph.

Simple Example

The following simple example demonstrates how a decision graph may work:

_images/perpixeldecisiongraph_editor_example.png

In this case the Quality2 quality parameter would depend only on whether the first channel value of the only input is above 0.3. If input1[0] < 0.3 then Quality2 would be 0, otherwise it would be 1.

The Quality1 parameter is more complicated though. Initially it only depends on whether the third channel value of the only input is above 0.5. If that is the case then Quality1 would be set to 3, otherwise it would be set to 4. However, the first condition detecting the first channel value also influences the quality parameter: if the first channel value is less than 0.3, Quality1 will be set to 2 instead. However, if the third channel value is also larger than 0.5 in addition to the first channel value being less than 0.3, Quality1 will instead be set to 1. This logic demonstrates how priority values are applied in this case, since the priority of the actions that set Quality1 to 3 or 4 is 100, which is lower than the priority of the action that sets it to 2 (101), which is even lower than the priority of the action that sets it to 1 (102).

This demonstrates how a combination of boolean logic and priorities may be used to assign a specific quality value depending on a combination of various conditions.