LiKiSeg is a QuPath-integrated toolkit for deep learning-based segmentation of liver and kidney histopathological whole-slide images (WSIs). It provides ready-to-use nnU-Netv2 models, a QuPath graphical interface, local preprocessing and post-processing controls, batch processing, editable QuPath annotation outputs, and optional model extension by fine-tuning or training new compatible models.
This repository provides the release files for LiKiSeg:
- QuPath extension JAR files for Windows and Linux
- User documentation
- Optional test images folder
- Fine-tuning and training-from-scratch helper files
Pretrained model files are hosted separately on Zenodo because they are large:
Model archive: https://zenodo.org/records/20875313
Download only the model folders you need and place them into the LiKiSeg model folder after installation.
Download the correct JAR for your operating system:
Alternatively, download the JARs from the repository Releases page.
The LiKiSeg JAR file is an open-source QuPath extension wrapper and installer. It is not a closed-source segmentation binary. During first-time initialization, the JAR extracts the LiKiSeg runtime scripts into the local QuPath user directory. These extracted Groovy, Python, PowerShell, and shell scripts remain visible and editable by users after installation.
The segmentation workflow is therefore script-based after extraction: users can inspect or modify the extracted source files, including the QuPath GUI script, preprocessing scripts, nnU-Netv2 prediction scripts, and environment setup scripts.
- Requirements
- Installation with the QuPath extension JAR
- Downloading pretrained models
- Running segmentation in QuPath
- Installed LiKiSeg folder structure
- Available model IDs
- Optional folders in this repository
- Using your own models
- Troubleshooting
- Citation and license
LiKiSeg JAR installation was tested with:
- QuPath 0.7.0
Tested platforms:
- Windows 10 / 11
- Ubuntu Linux
LiKiSeg creates a local Python/nnU-Net environment during the first initialization.
Recommended Python versions:
- Python 3.11
- Python 3.12
Python 3.13 is not recommended for this release because compatible PyTorch builds may not be available for all required configurations.
Install Python 3.11 or 3.12 from the official Python installer and check Add Python to PATH
If Python is already installed but not available in the command line, see:
documents/Add_Python_to_PATH_Windows.md
Install Python and virtual-environment support:
sudo apt update
sudo apt install -y python3 python3-venv python3-pip python-is-python3
python3 --version
python --versionThe first LiKiSeg initialization needs an internet connection to create the Python virtual environment and install PyTorch, nnU-Netv2, and Python dependencies.
LiKiSeg can run on CPU-only systems. NVIDIA/CUDA inference is recommended for large WSIs and faster processing. If no CUDA-capable GPU is detected, LiKiSeg uses CPU inference.
Use one of the links above:
- Windows:
qupath-extension-likiseg-windows-0.1.1.jar - Linux:
qupath-extension-likiseg-linux-0.1.3.jar
Do not rename the file unless you know what you are doing.
Start QuPath normally.
Drag the downloaded JAR file into the main QuPath window.
If drag-and-drop does not work:
- Open QuPath.
- Go to Extensions → Manage extensions.
- Click Open extension directory.
- Copy the JAR file into that directory.
- Restart QuPath.
After the JAR is loaded, LiKiSeg extracts its runtime files into the QuPath user directory and starts first-time initialization. A log window should appear.
Do not close QuPath or the initialization log window until initialization finishes.
Expected messages include environment creation, PyTorch installation, nnU-Netv2 installation, and successful completion.
After the first installation, restart QuPath. The menu item should remain available:
Extensions → LiKiSeg
You do not need to drag the JAR again after successful installation.
Pretrained LiKiSeg models are hosted on Zenodo:
https://zenodo.org/records/20875313
Download each required model separately. Model folders should have names such as:
Dataset200_CD45
Dataset300_CD45_light
Dataset207_GS
Dataset307_GS_light
Place downloaded model folders into:
C:\Users\<your_user_name>\QuPath\v0.7\LiKiSeg\model\nnUNet_results\
/home/<your_user_name>/QuPath/v0.7/LiKiSeg/model/nnUNet_results/
If you are not sure where your QuPath user directory is, open Extensions → LiKiSeg once and check the "Log" in QuPath.
- Open QuPath.
- Open or create a QuPath project.
- Add images to the project if the project is empty.
- Download and place the required model folders under
model/nnUNet_results/as described above. - Click:
Extensions → LiKiSeg
-
In the LiKiSeg window:
- click Select model;
- choose a
DatasetXXXmodel; - check or edit preprocessing parameters;
- check or edit post-processing thresholds;
- select one or more project images;
- click Start processing selected images.
-
Wait until the log reports that batch processing has completed.
-
Open the processed images in QuPath and inspect the imported annotations.
The segmentation output is imported as editable QuPath annotation objects. You can manually correct, export, measure, or use them for downstream analysis inside QuPath.
After installation, LiKiSeg creates a local folder under the QuPath user directory:
<QuPath user directory>/LiKiSeg/
Typical contents include:
LiKiSeg/
├── Startup.groovy
├── Enhance_IHC_DAB.py
├── Split_tif.py
├── init_env.ps1 or init_env_linux.sh
├── nnUNetv2_pred.ps1 or nnUNetv2_pred_linux.sh
├── model/
│ ├── nnUNet_raw/
│ ├── nnUNet_preprocessed/
│ └── nnUNet_results/
├── export/
│ ├── original_imagesTs/
│ ├── imagesTs/
│ └── pred_results/
└── venv_LiKiSeg/
Users may edit the extracted scripts if they want to customize the workflow.
For example, editing:
<QuPath user directory>/LiKiSeg/Startup.groovy
changes the GUI or processing logic the next time Extensions → LiKiSeg is clicked. Editing the Python or shell/PowerShell helper scripts changes the corresponding preprocessing, prediction, or environment steps.
The Java JAR itself only acts as the QuPath extension wrapper and installer. The segmentation workflow remains script-based and editable after extraction.
LiKiSeg provides standard and light model variants. Standard models use 5-fold prediction by default; light models use single-fold prediction for faster runtime and lower memory use.
| Task / model | Standard ID | Light ID |
|---|---|---|
| CD45 | 200 | 300 |
| CK19 | 201 | 301 |
| CD13 | 202 | 302 |
| Sirius Red fibrosis | 203 | 303 |
| NTCP | 204 | 304 |
| RGN | 205 | 305 |
| OAT | 206 | 306 |
| GS | 207 | 307 |
| RHBG | 208 | 308 |
| CPS1 | 209 | 309 |
| Arginase | 210 | 310 |
| Glomeruli, Sirius Red | 230 | 330 |
| Glomeruli, MECA-32 | 231 | 331 |
| Glomeruli, H&E | 232 | 332 |
| Glomeruli, generalized H&E/MECA-32/Sirius Red | 233 | 333 |
Use the model that matches your tissue, staining, and target. Models should be validated before quantitative use on new cohorts, scanners, species, organs, or staining protocols.
These folders are provided for users who want additional material beyond the JAR installer.
documents/
Additional documentation and technical notes.
test_images/
Example images for testing LiKiSeg segmentation output. This folder can be expanded with demonstration images.
fine_tuning/
Helper files and instructions for fine-tuning an existing LiKiSeg model on user data.
training_from_scratch/
Helper files and instructions for preparing a new dataset, training a new compatible nnU-Netv2 model from scratch, and registering it in LiKiSeg.
LiKiSeg can be extended in two ways:
- Fine-tuning an existing LiKiSeg model on user-provided images and annotations.
- Training a compatible model from scratch using nnU-Netv2 and registering it under LiKiSeg.
For fine-tuning, see:
fine_tuning/FINETUNE.md
For training from scratch, see:
training_from_scratch/README.md
For both workflows, models must follow the nnU-Netv2 folder structure and be copied into:
<QuPath user directory>/LiKiSeg/model/nnUNet_results/
Once the model folder is present, restart LiKiSeg or click Select model again. The model should appear in the model-selection window.
Try one of the following:
- restart QuPath;
- check that the JAR is in the QuPath extension directory;
- remove old LiKiSeg JAR versions from the extension directory;
- reinstall by dragging the correct JAR into QuPath.
This is expected. LiKiSeg creates a Python virtual environment and installs PyTorch, nnU-Netv2, and required Python packages. Installation time depends on internet speed, CPU, disk speed, and whether pip has cached packages.
Check that model folders were placed under:
<QuPath user directory>/LiKiSeg/model/nnUNet_results/
The immediate subfolder should be a model folder such as Dataset207_GS or Dataset307_GS_light, not an extra nested folder.
The Linux JAR attempts to set executable permission automatically. If shell scripts still cannot run, execute:
chmod +x ~/QuPath/v0.7/LiKiSeg/init_env_linux.sh
chmod +x ~/QuPath/v0.7/LiKiSeg/nnUNetv2_pred_linux.shAvoid creating the LiKiSeg Python environment on NTFS/exFAT external drives. Use the default QuPath user directory under /home/<user>/QuPath/v0.7/LiKiSeg/.
This is expected for large images. Use a CUDA-enabled NVIDIA GPU if available, or use light model variants where appropriate.
If you use LiKiSeg in your work, please cite the LiKiSeg manuscript and the archived pretrained model record.
The LiKiSeg source code, QuPath extension JAR files, documentation, and extracted runtime scripts are released under the GNU General Public License v3.0. See LICENSE.
Pretrained LiKiSeg model files are distributed separately through Zenodo and are released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.
DOI: https://doi.org/10.5281/zenodo.20875313
Deng, Z., Friebel, A., Siddiqui, Q., Hobloss, Z., Myllys, M., Hengstler, J. G., Ghallab, A., & Hoehme, S. (2026). LiKiSeg pretrained models for liver and kidney whole-slide image segmentation (v1.1.0). Zenodo. https://doi.org/10.5281/zenodo.20875313