☰
Navigation :

Annotations I: Filtering

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

👉 Related tutorial: Handling multi-channel images I
This guide is a followup of other tutorials.

Tutorial: Annotations I (Filtering)

small size
simple
tutorial
Accompanying data and project for the tutorial 'Annotations I: Filtering'.
Project + Data Tutorial
This guide was written for JIPipe version 1.74.0 or newer
Illustration of the tutorial step

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).

The node Annotate with image properties can create JIPipe-managed annotations from properties (width, height, physical sizes, …) of an image. As annotations are preserved during all processing steps, this allows to apply a multitude of powerful operations in later steps.

Illustration of the tutorial step

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).

Illustration of the tutorial step

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)

Illustration of the tutorial step

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).

Illustration of the tutorial step

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).

Illustration of the tutorial step

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.

The Split & filter by annotations allows to filter the incoming data by the values of their annotation columns. For example, if you provide multiple images that are annotated with the number of channels, you can setup the node to only output the images with three channels.

The node has a configurable number of outputs, each linked to a different filter. This allows to use filtering to split the incoming data into multiple pipeline branches, e.g., into a branch for three channels and one for four channels.

Illustration of the tutorial step

Step 7

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

Illustration of the tutorial step

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 wether an input data item is pass through the output.

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

The settings within the Filters category correspond to each output of the Split & filter by annotations node.

Illustration of the tutorial step

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).

Illustration of the tutorial step

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.

Examples:

#Dataset CONTAINS "Raw" AND condition EQUALS "mock"

TO_NUMBER($"my column")  10
Illustration of the tutorial step

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:

The Split & filter by annotation node iterates through each individual input data item and executes the user-provided expression where variables are set to the column value in the data table (the one you can review in the cache browser).

Annotations in JIPipe are always strings, thus also all variables that reference annotations are strings.

Illustration of the tutorial step

Step 12

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

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).

Illustration of the tutorial step

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.

Illustration of the tutorial step

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.

Illustration of the tutorial step

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).