Home

Awesome

ilastik ImageJ modules

Build Status

Originally developed by Carsten Haubold, Adrian Wolny, Image Analysis and Learning Lab, HCI/IWR, University of Heidelberg._ Current development and maintenance by the ilastik team, Kreshuk Lab, CBB, European Molecular Biology Laboratory Heidelberg.

This repository contains ImageJ2 plugins that wrap ilastik workflows for usage in ImageJ and KNIME. Data transfer is managed through temporary HDF5 file export/import, which can also be performed individually. The ilastik workflows are invoked by running the ilastik headless mode from the command line.

Currently, three workflows are wrapped: Pixel classification, Autocontext, Object classification, Boundary-based Segmentation with Multicut, and Tracking.

Contents

Installation

Within ImageJ/Fiji you can install the plugin via the Help -> Update menu and select the ilastik site.

Note: The plugins need Java 1.8, if you see error messages popping up that might be caused by an older Java version.

Compatibility note:: We try to keep the plugin backwards compatible. Some versions of ilastik are not compatible with the current plugin: 1.3.3b2, 1.3.3rc2, 1.3.3, 1.3.3post1, 1.3.3post2, 1.4.0b27. We recommend to update to the latest stable version!. If you need to stick with 1.3.3x for some reason, please use 1.3.3post3.

User documentation

The ilastik workflows, as well as importer and exporter, can be found in ImageJ under Plugins -> ilastik, or in KNIME in the Community Contributions -> KNIME Image Processing -> ImageJ2 -> Plugins -> ilastik.

ImageJ Menu

General

All Plugins output status information to log files, so we suggest to keep an eye at the ImageJ Windows -> Console. You can find example macros for the different plugin commands in the examples directory.

Import

Found at Plugins -> ilastik -> Import HDF5.

HDF5 files can contain multiple datasets. Thus, when you import an HDF5 file containing more than one dataset, you will have to select which dataset you want to import by selecting the Dataset Name:

ImageJ Menu

Here you should double check the correct meaning of the different Dimensions of the dataset by specifying the Axes. At least x and y must be present, and the number of characters (x,y,z spatial, c channels and t time) must be equal to the number of dimensions listed in the description above.

Example Macro usage

The macro below demonstrates how to import many .h5 files that were generated with ilastik using a macro.

input = "/absolute/path/to/some/directory/src/test/resources/2d_cells_apoptotic_1channel.h5";

datasetname = "/data";
axisorder = "tzyxc";

run("Import HDF5", "select=[" + input + "] datasetname=[" + datasetname + "] axisorder=[" + axisorder + "]");

see also ./examples/import.ijm

Export

Found at Plugins -> ilastik -> Export HDF5.

If you want to save the currently opened image to an HDF5 file that can be immediately opened in ilastik, use this export option. Additionally to the location where the file should be saved, you could specify the output data set name as well as how much the dataset should be compressed. Use 0 for raw data because it doesn't compress well, but 9 for segmentations etc, where many pixel values are equal. The plugin uses (lossless) gzip compression.

ImageJ Menu

Example Macro usage

You can find a simple example macro in ./examples/export.ijm. Furthermore, there is an example macro demonstrating how to convert a whole folder of .tiff files to .h5 in ./examples/convert_tiff_to_ilastik_h5.ijm.

How to train an ilastik project for use in the plugins

In general you can use any project of the supported workflows that you trained. However, there are some things to keep in mind:

Ideally, you train your ilastik already with .h5 files manually generated by the above export functionality. The export creates files with maximum compatibility with ilastik - and you will also get the best performance during training. With this you make sure that the whole processing chain will work.

Configuration for running ilastik from within Fiji

Found at Plugins -> ilastik -> Configure ilastik executable location.

configuration dialog

Note: When running the plugin for pre-trained ilastik projects, the project files (.ilp) have to be closed (i.e. can not be open in ilastik at the same time).

Pixel Classification and Autocontext

Pixel Classification and Autocontext workflow have similar input settings.

The Pixel Classification Workflow can be found at Plugins -> ilastik -> Run Pixel Classification Prediction, the Autocontext Workflow at Plugins -> ilastik -> Run Autocontext Prediction.

Pixel Classification Dialog

Inputs:

Output:

Example macro usage

A simple example macro that opens a .tif file and processes it with a pre-trained ilastik pixel classification project would look like the following:

project = "/absolute/path/to/some/directory/pixel_class_2d_cells_apoptotic.ilp";
input = "/absolute/path/to/some/directory/2d_cells_apoptotic.tif";

type = "Probabilities";

open(input);
run("Run Pixel Classification Prediction", "projectfilename=[" + project + "] input=[" + input + "] pixelclassificationtype=[" + type + "]");

A more complex example can be found in ./examples/pixel_classification.ijm.

Object Classification

Command to run pretrained Object Classification: Plugins -> ilastik -> Run Object Classification Prediction.

Object Classification Dialog

Inputs:

Output:

Example macro usage

A basic macro example for running object classification on a single image can be found in ./examples/object_classification.ijm.

Boundary-based Segmentation with Multicut

Command for Boundary-based Segmentation with Multicut: Plugins -> ilastik -> Run Multicut.

Multicut Dialog

Inputs:

Output:

Example macro usage

A basic macro example for running Multicut on a single image can be found in ./examples/multicut.ijm.

Tracking

Found at Plugins -> ilastik -> Run Tracking.

Tracking Dialog

Inputs:

Output:

Example macro usage

A basic macro example for running Tracking on a single image can be found in ./examples/tracking.ijm.

Usage in KNIME

KNIME Workflow

Developer documentation

The workflow wrappers are ImageJ2 plugins (see https://imagej.net/Writing_plugins), annotated with @Plugin for automated discovery by the scijava plugin architecture, and derived from Command to be an executable item. Each command can have multiple @Parameters, which are to be provided by the user in an auto-generated GUI (see https://imagej.net/Script_Parameters for a list of which parameters are allowed). One can have multiple Datasets as input parameters, but the output should be an ImgPlus (an ImageJ2 datastructure wrapping an ImgLib2 Img with metadata) so that the result pops up as new window. A Dataset is a wrapper around an ImgPlus.

Attention: there are ImageJ 1 and ImageJ 2 containers for images. In ImageJ 1, images were stored as ImagePlus, containing ImageProcessors to access the underlying data. We try to use ImageJ 2 containers everywhere which are roughly wrapped as Dataset > ImgPlus > Img > RandomAccessibleInterval.

Examples

If you want to run workflows from your own Java code, have a look at src/test/java/org/ilastik/ilastik4ij/Demo.java. Example macros can be found in the examples directory.

Manually test in a local Fiji installation

Run scripts/fiji-deploy.py to build project and copy the newly built plugin to Fiji.

Deployment

We follow the setup of other scijava modules and use their Travis setup that allows us to automatically deploy Maven artifacts (built modules) as explained here. The project configuration, including dependencies, is contained in the pom.xml file. To create a new release, use the release-version.sh script from https://github.com/scijava/scijava-scripts, which goes a long way of ensuring that the project is ready to be published. Once it is released, the nightly build of KNIME Image Processing (KNIP) will pick it up and wrap it as well.