Skip to content

Home

Jump to bottom
Mallory Wittwer edited this page Aug 28, 2026 · 4 revisions

LuTuFlow | User guide

This Wiki will take you through the different functionalities offered by LuTuFlow.

screenshot

This page describes how to use LuTuFlow in Napari. For usage as a command-line interface, see CLI.

Outline

Launching the Napari plugin

Make sure to have a working installation of LuTuFlow. Otherwise, refer to the installation instrutions.

If you have installed the software as a standalone app, simply run the executable file. If you have installed the software as a Python package, you can start Napari from the command-line:

napari

Then, access the plugin's functionalities from the menu via the menu Plugins > LuTuFlow.

Sample images

We provide two samples under File > Open Sample > LuTuFlow to test the package's functionality:

  • Mouse lung CT scan: An example CT scan, in its original size (shape: (512, 512, 512)).
  • Lung ROI series (TZYX): An example of 5 concatenated scans, after ROI extraction (shape: (5, 262, 349, 330)).

LuTuFlow algorithms

To run individual algorithms from LuTuFlow, open Plugins > LuTuFlow > Algorithms. Then, select the workflow step to run from the Algorithm menu:

  • 1. Crop original scans: Automatically crop 3D CT scans around the lungs ROI.
  • 2. Segment tumors: Segments tumor nodules in a CT scan image of the lungs ROI.
  • 3. Combine CT scans: Create a 4D time series (TZYX) from CT images.
  • 3. Combine tumor masks: Create a 4D time series (TZYX) from tumor masks.
  • 4. Track tumors: Tracks tumors in a 4D tumor masks series.
  • 5. Save tracking table: Save tracking results as a CSV file.

Utility widgets

A few other utility widgets are available from the menu Plugins > LuTuFlow:

  • Color picker: Display a segmentation mask in a chosen color.
  • Manual cropping: Crop CT scans by setting limits in the X, Y and Z directions.
  • Convert to tracks: Displays tracks from a segmentation mask layer.
  • Data table: Display tumor labels and volumes in a table.
  • Remove objects: Remove individual tumors by clicking on them in the viewer.

OMERO interface

Plugins > LuTuFlow > Omero interface

To use the OMERO-related functionalities, you need to have access to an OMERO server with permissions to create and edit projects and upload data.

Connecting to OMERO

Login panel

You can connect to an OMERO server via the Login panel. If needed, specify the server URL, group, and port in the OMERO server panel. Then, enter your credentials (username and password) and click Login. If successful, you should be taken to the OMERO project panel.

Changing the default OMERO parameters

You can change the default OMERO server parameters (host, port, group, and user) by writing them into a configuration file config.yaml, which should be saved in the default configuration directory of your computer:

  • Windows: C:\Users\<user>\AppData\Local\lutuflow\config.yaml
  • MacOS: ~/Library/Application Support/lutuflow/config.yaml
  • Linux: $HOME/.config/lutuflow/config.yaml

Example config.yaml:

host: "omero-server.uni.edu"
port: 4064
group: "mice-lab"
default_user: "micky"

OMERO project panel

First, select an OMERO project to work on. If you have logged in to OMERO, the projects you have access to should appear in the dropdown list.

Project selection

Selecting an OMERO project will trigger the software to analyze the data available in that project, examine how the files are tagged, and will organize the results accordingly throughout the rest of the interface.

Clicking on Update will trigger this "project scanning" operation manually. This can sometimes be used to ensure that the Napari plugin remains in sync with the data on the OMERO server (for example, when data is added or removed from the OMERO server while the Napari plugin is running).

Tumor detection

In the tumor detection panel, you can select a tumor detection model and run tumor detection on the selected OMERO project.

Tumor detection

Clicking the button will initiate a series of operations designed to identify, compute, and save the regions of interest (lung ROIs), as well as any tumor masks that may be missing, for each CT scan image. The sequence of steps is as follows:

  • The OMERO project is scanned again to ensure that it is up to date.
  • On OMERO, files tagged image (the original CT scans) that do not have an associated file tagged roi (lungs ROI) are identifed. These missing roi files are computed, and uploaded to the project.
  • Files tagged roi that do not have an associated file tagged raw_pred (tumor masks) are identified. The missing tumors are computed, and upload to OMERO.
  • The project is scanned again to update the Napari layout.

Once the workflow is completed, the CT scan images should all have an associated ROI file and tumor mask saved on OMERO. The detection workflow will only compute missing data; it will not re-run and overwrite previously saved ROIs or tumor masks.

In this workflow, both the ROI and tumor detection computations are performed locally using functions from lutuflow. The images are first downloaded from OMERO, then processed locally, and the results are sent back to OMERO.

Scan data

This panel allows you to select a case (mouse ID), a scan time, and a data category.

Scan data

Clicking Download will retreive the corresponding data from OMERO and display it in the Napari viewer.

Case IDs should start with C***** or Animal***** and represent the mouse being studied.

There can be up to four scan times (SCAN1, SCAN2, SCAN3, SCAN4).

The data categories are:

  • image: The raw CT scan image (large field of view, loaded as an Image layer).
  • roi: The ROI around the lungs (loaded as an Image layer).
  • raw_pred: The raw tumor prediction mask (loaded as a Labels layer).
  • corrected_pred: A corrected tumor prediction mask (loaded as a Labels layer).
OMERO tags

The data identification is based on OMERO tags. Valid files on OMERO should be tagged according to the case, scan time, data category, and project they belongs to.

OMERO tags

Relevant tags are automatically added when uploading new scans, running the tumor detection workflow, or uploading corrected tumor masks via the Napari plugin.

Tumor corrections

For a selected case, a corrected tumor mask (for example, a mask edited to remove false positive tumors or in which missing tumors have been manually annotated) can be uploaded to OMERO via this interface.

Corrections

In this case, it is tagged corrected_pred, and the corrected data takes precedence over the equivalent raw_pred when assembling tumor time series for analysis.

Time series

When a case contains multiple scans at different times, the corresponding image and tumor series can be retreived from this panel.

Time series

The data is downloaded as 4D arrays (TZYX) and displayed in the Napari viewer. This allows you to view and compare multiple scans and visualize tumor progression by moving the axis slider corresponding to the scan time.

Importantly, the tumors are not tracked at this stage: the tumor series is simply the concatenation of the tumor predictions at each scan time. To perform tumor tracking automatically, the tumor series can subsequently be used as input to the tracking function in lutuflow.

New scan

This panel allows you to upload a new scan from an image loaded in the Napari viewer, by specifying the corresponding case and scan time.

New scan

After uploading a new scan, you may need to click the 🔄 Update button next to the project selection dropdown for the changes to take effect.

To upload several new scans in batch, you can use the function Upload new scans in batch in the Other operations panel. However, this function expects a very specific file structure based on conventions (e.g., including the case name and scan time in the file names). The "New scan" function is more flexible, but only allows to upload one scan at a time and requires to manually specify the case name and scan time.

Other operations

Upload new scans in batch

You can use this function to upload a series of new CT scans in batch to OMERO. Clicking the button will prompt you to select a directory from which to upload the new scans. The structure of this directory, as well as the file names and formats, must strictly adhere to convention below:

<root_directory>/
├── <case_name>/
│   ├── <exp_name>_<scan_tag>_<case_name>~_rec<...>01.tif
│   ├── <exp_name>_<scan_tag>_<case_name>~_rec<...>02.tif
│   └── ...
├── <case_name>/
│   └── ...
└── ...

The root directory should contain subfolders named according to case_name. Each subfolder should contain a series of 2D TIFF files named according to exp_name, scan_time, and case_name. It must be possible to sort the 2D TIFF files numerically so that a coherent 3D Z stack can be reconstructed from them.

Files corresponding to this structure are extracted and loaded as a 3D-ZYX image. This 3D image is then uploaded to OMERO, tagged as image, and additional tags are added based on the scan time and case name specified in the file names.

Download project locally

Clicking this button will prompt you to select a folder where to save the project locally. The image and tumor series will be saved in this folder according to the following struture:

<selected_dir>/
├── <project_name>/
|   |── <case>/
│       ├── rois_timeseries.tif
│       ├── tumors_untracked.tif

In the saved project folder, the data is organized by case (one subfolder per case), and each case contains a roi_timeseries.tif and a tumors_untracked.tif file.

Download / upload

This panel provides generic functions for transferring images between Napari and OMERO.

New scan

More specifically, you can:

  • Download an image file from an OMERO dataset and displaying it in a Napari Image layer.
  • Upload an image or mask from a Napari layer to an OMERO dataset, where it is imported as an OME-TIFF file.

These functions are not part of the main workflow and should only be used in specific cases where the flexibility that they offer is necessary.

Clone this wiki locally