Annotations I: Filtering
Explains the processes of annotating with image properties, and filtering based on annotations
Tutorial: Annotations I (Filtering)
Load the project file of this tutorial into JIPipe.
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).
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.
Annotate with image properties node on the workspace (red arrow 1). Disconnect the
Import image node from the
Split channels node (red arrow 2).
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)
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).
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).
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.
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.
Add the new node next to the
Annotate with image properties (red arrow 1) node and connect them (red arrow 2).
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.
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).
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
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
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:
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.
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
- 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.
- You will see a tab
Function Convert to number
- Set the type of the
Variable, because we want to convert a variable to a number (red arrows 2 and 3)
- Type in the name of the variable ( = annotation column in this case), which is
Image composite channel count
- Click the
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).
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.
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.
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.
Split channels node and observe its cache (red arrow 1) to demonstrate that the newly installed filtering function indeed worked (red line 2).