Basic tutorials

Working with annotations: filtering


Explains the processes of annotating with image properties, and filtering based on annotations

Tutorial data

This tutorial has accompanying data. Please download the data if you want to follow the guide.

Step 1

Load the project file of this tutorial into JIPipe.

Select the Import image node (red arrow 1), we will use the image properties provided by this node to annotate the data. Use the Annotations tab (red arrow 2) to seek the necessary node in the Annotations > Generate menu (red arrow 3).

Add the node Annotate with image properties (red arrow 4).

Step 2

Position the Annotate with image properties node on the workspace (red arrow 1). Disconnect the Import image node from the Split channels node (red arrow 2).

Step 3

Move the Split channels node lower and position the annotations node in between (red arrow 1). Connect the node to the Import image node above (red arrow 2) and the Split channels node below (red arrow 3)

Step 4

Select the Annotate with image properties node (red arrow 1) and go to the Parameters tab (red arrow 2). Select as many image properties from the list as you like; as an example, we selected five properties as shown in the figure (red arrows 3 to 7).

Step 5

Run the Annotate with image properties node (red arrow 1) and observe the cache (red arrow 2).

The annotations table in the cache browser now contains the image properties that were previously selected (red arrow 3 to 7).

Step 6

Now we will filter the incoming images based on image properties. Since the next node will be a Split channel operation, we will need to limit our processing to images with three channels. For this we will use an annotations-based filter node.

Do a search in the upper search bar (red arrow 2) for filters and annotations. The first hit is an example of the node that we need (red arrow 3), this will provide an example of the syntax for filtering.

Step 7

Add the new node next to the Annotate with image properties (red arrow 1) node and connect them (red arrow 2).

Step 8

Go to the Parameters tab and examine the filter expression in the category Filters (red arrow 1).

The figure shows an expression (by default the expression is empty)

TO_NUMBER($"Image composite channel count") == 3

This text is called an expression and determines the filter conditions that determine whether an input data item is pass through the output.

In the following steps, we will briefly explain the functionality behind the expression.

Step 9

Let’s examine how this expression was arrived at. The parameter that we need to filter for is the channel number.

The exact name can be read out from the Annotate by image properties node (red arrow 1).

Step 10

We use this value for filtering in an expression, where we look for channel numbers equaling 3.

The figure now shows the default configuration of the Split & filter by annotations node that can be opened by selecting the node (red arrow 1) and going to the Parameters tab.

Please observe the examples that are provided in the description field (red arrow 2) and in the expression field (red arrow 3):

One filter is created for each output slot of this node. The filter is an expression that should return a boolean value that indicates whether a data item should be put into the corresponding output.Annotation values are available as variables. If an annotation has spaces special characters, use $ to access its value.
#Dataset CONTAINS "Raw" AND condition EQUALS "mock"
TO_NUMBER($"my column") 10

Step 11

To simplify the creation of expressions, JIPipe includes an expression editor component that shows all available functions and validates the code.

Open the expression editor by clicking the Edit f(x) button (red arrow 1) that opens a new window (red arrow 2).

But before we proceed, we need to establish some fundamentals on how the annotation system and the splitter work:

Step 12

Begin by deleting the existing example expression. The expression will now be

TO_NUMBER($"Image composite channel count") == 3

We will now use the function builder component of the expression editor to convert the annotation value of Image composite channel count to a number that can be tested to be equal to 3:

  1. Use the search field to look for functions that work with numbers by using the search word number (red arrow 1), which will yield a function TO_NUMBER (red arrow 3). Select the item in the list.
  2. You will see a tab Function Convert to number
  3. Set the type of the value editor to Variable, because we want to convert a variable to a number (red arrows 2 and 3)
  4. Type in the name of the variable ( = annotation column in this case), which is Image composite channel count
  5. Click the Insert button

The expression now will be

TO_NUMBER($"Image composite channel count")

Finally, add the code to test if the number of channels is 3 (red arrow 6)

TO_NUMBER($"Image composite channel count") == 3

Now you can accept the changes to the expression by clicking the Accept button (red arrow 7).

Step 13

Select the filter node (red arrow 1) and observe the Output field in the Parameters tab (red arrow 2); It now contains the filtering expression.

Step 14

Run the node (red arrow 1) and observe the Cache, where the 3-channel image will appear (red line 2), indicating that the filter worked, allowing the three-channel image through.

Step 15

Insert the filter node into the pipeline by placing it in between the annotation node and the Split channels function (red arrow 1). Connect the new node to the functions above (red arrow 2) and below (red arrow 3). Make sure that the direct connection between the Annotate node and the Split channels node is removed beforehand.

Run the Split channels node and observe its cache (red arrow 1) to demonstrate that the newly installed filtering function indeed worked (red line 2).