@@ -30,6 +30,13 @@ nf-test test --profile debug,test_mesmer,docker --verbose
 nf-test test --profile debug,test_cellpose,docker --verbose
 ```
 
+KRONOS module tests run in stub mode by default to avoid downloading large model checkpoints. To run the KRONOS integration module test, set a pre-downloaded model directory (must contain a `.pt` checkpoint) and run:
+
+```bash
+export KRONOS_MODEL_DIR=/path/to/kronos_model_dir
+nf-test test modules/local/kronosembeddings/tests/main.nf.test --profile debug,test,apptainer --verbose
+```
+
 When you create a pull request with changes, [GitHub Actions](https://github.com/features/actions) will run automatic tests.
 Typically, pull-requests are only fully reviewed when these tests are passing, though of course we can help out before then.
 
 
@@ -92,7 +92,6 @@ jobs:
       - name: "Run pipeline with test data ${{ matrix.NXF_VER }} | ${{ matrix.test_name }} | ${{ matrix.profile }}"
         run: |
           mkdir -p work && chmod 777 work
-          mkdir -p $HOME/.gradle && chmod 777 $HOME/.gradle
           if [ "${{ matrix.profile }}" == "singularity" ]; then
             export NXF_SINGULARITY_HOME_MOUNT=true
           fi
 
@@ -0,0 +1,39 @@
+name: Python unit tests
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - "bin/**.py"
+      - "tests/python/**.py"
+      - "pyproject.toml"
+      - "uv.lock"
+  pull_request:
+    paths:
+      - "bin/**.py"
+      - "tests/python/**.py"
+      - "pyproject.toml"
+      - "uv.lock"
+
+jobs:
+  pytest:
+    name: pytest
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out pipeline code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run Python unit tests
+        run: uv run pytest tests/python/ -v
@@ -8,3 +8,4 @@ testing*
 *.pyc
 null/
 .nf-test*
+*.egg-info
@@ -46,7 +46,7 @@ org_path: null
 repository_type: pipeline
 template:
   author: WEHI SODA Hub
-  description: Cell segmentation and downstream analysis pipeline for the COMET and MIBI spatial platforms
+  description: Cell segmentation and downstream analysis pipeline for the COMET, MIBI, and OPAL spatial platforms
   force: true
   is_nfcore: true
   name: spatialproteomics
 
@@ -3,6 +3,53 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.4.0 - 2026-04-20
+
+### Changed
+
+- **cellmeasurement: Python replaces Groovy as the only implementation.** The original Groovy app
+  (`https://github.com/WEHI-SODA-Hub/cellmeasurement`) is no longer used. All measurement logic
+  is now in `bin/cellmeasurement.py`.
+
+- **cellmeasurement: erosion measurement column names have changed.** The Groovy app produced
+  columns named `{Channel}: {Compartment}: Eroded_{N}px: Mean/Median` where N was a fixed pixel
+  depth. The Python implementation uses 5 _equal-area_ bins and names them
+  `{Compartment}: ErosionBin_{N}: Mean/Median`. If you have existing Groovy-generated GeoJSON
+  that you compare with new Python output, expect different column names.
+
+- **cellmeasurement: `--erosion-steps` no longer accepts pixel-depth values.** Passing numeric
+  values such as `--erosion-steps=4,7,11,14,18` (Groovy API) is not supported. Use the boolean
+  flag `--erosion-steps` to enable the 5 equal-area bins.
+
+### Added
+
+- **KRONOS embedding output**: new `kronosembeddings` module extracts per-cell embeddings using
+  the KRONOS foundation model. Produces `*_kronos_embeddings.csv` (cell IDs + 384 embedding
+  dimensions), `*_marker_report.txt` (channel-to-marker match summary), and optionally
+  `*_kronos_merged.geojson` (embeddings merged into the cellmeasurement GeoJSON).
+  Controlled by `skip_kronos`, `kronos_model_path`, `kronos_marker_metadata`, and related
+  `kronos_*` parameters. Disabled by default (`skip_kronos = true`).
+
+- **CellSAM segmentation**: new `cellsam_segment` module adds support for the CellSAM foundation
+  model as a third segmentation option alongside Mesmer and Cellpose. Supports tiled (WSI) and
+  non-tiled inference via `cellsam_use_wsi`. Controlled by `cellsam_bbox_threshold`,
+  `cellsam_block_size`, `cellsam_overlap`, `cellsam_iou_threshold`, and `cellsam_use_wsi`
+  parameters.
+
+- **Mask smoothing (`smooth_masks`)**: new optional `smoothmasks` module reduces polygon
+  complexity. Two methods: `morphological` (disk close+open, default) and
+  `shapely` (Douglas-Peucker polygon simplification). Enabled via `smooth_masks
+= true`; tunable with `smooth_method` and `smooth_kernel_size`.
+
+- `dist_threshold` pipeline parameter: controls the maximum centroid distance (pixels) for
+  matching a nucleus to a whole-cell ROI in cellmeasurement (default: 10.0).
+- `downsample_factor` pipeline parameter: integer downsample factor applied to image and masks
+  before cellmeasurement to speed up processing on very large images (default: 1.0 = disabled).
+
+### Removed
+
+- `gradle_cache_dir` parameter and all references removed (leftover from the Groovy era).
+
 ## v0.3.0 - 2025-11-13
 
 - Rename to sp_segment
 
@@ -19,12 +19,12 @@
 ## Introduction
 
 **WEHI-SODA-Hub/sp_segment** is a pipeline for running cell segmentation
-on COMET and MIBI data. For COMET, background subtraction can be performed
-followed by patched cellpose segmentation, or non-patched mesmer segmentation.
-For MIBI, mesmer segmentation can be run. Whole-cell and nuclear segmentations
-are run separately, and then consolidated into whole cells with nuclei with full
-shape and intensity measurements per compartment. The output GeoJSON files can
-be viewed in QuPath.
+on COMET, MIBI, and OPAL data. For COMET, background subtraction can be performed
+followed by patched cellpose segmentation, non-patched mesmer segmentation, or
+CellSAM foundation model segmentation. For MIBI, mesmer or CellSAM segmentation
+can be run. Whole-cell and nuclear segmentations are run separately, and then
+consolidated into whole cells with nuclei with full shape and intensity
+measurements per compartment. The output GeoJSON files can be viewed in QuPath.
 
 <details>
   <summary>Click to view Mermaid diagram</summary>
@@ -69,9 +69,13 @@ The pipeline uses the following tools:
   -- background subtraction tool for COMET.
 - [MesmerSegmentation](https://github.com/WEHI-SODA-Hub/mesmersegmentation) -- a
   CLI for running Mesmer segmentation of MIBI and OME-XML TIFFs.
+- [CellSAM](https://github.com/vanvalenlab/cellSAM) -- a foundation model for
+  cell segmentation across diverse imaging modalities.
 - [cellmeasurement](https://github.com/WEHI-SODA-Hub/cellmeasurement) -- a
-  Groovy app that matches whole-cell segmentations with nuclei, and uses the
-  QuPath API to calculate compartment measurements and intensities.
+  Python app that matches whole-cell segmentations with nuclei and calculates
+  compartment measurements and intensities.
+- [KRONOS](https://github.com/mahmoodlab/KRONOS) -- a foundation model for
+  multiplex spatial proteomics that extracts rich embeddings for each cell.
 - [sopa](https://github.com/gustaveroussy/sopa) -- we use the sopa CLI tool to
   patchify images and perform cellpose segmentation.
 - [spatialVis](https://github.com/WEHI-SODA-Hub/spatialVis) -- R package for spatial
@@ -86,9 +90,6 @@ Please see the [docs for more detailed information on pipeline usage and output]
 
 If you are running this pipeline from WEHI, it has been set up to run on [Seqera Platform](https://seqera.services.biocommons.org.au/).
 
-> [!NOTE]
-> If you don't have a .gradle directory in your home, make sure you create it with `mkdir $HOME/.gradle` before runnning the pipeline. You con't need to do this if you are running via WEHI's Seqera Platform mentioned above.
-
 Usage will depend on your desired steps. See [usage docs](docs/usage.md) for more detailed information.
 
 ### Background subtraction
@@ -101,9 +102,9 @@ Prepare a sample sheet as follows:
 `samplesheet.csv`:
 
 ```csv
-sample,run_backsub,run_mesmer,run_cellpose,tiff
-sample1,true,true,false,/path/to/sample1.tiff
-sample2,true,false,true,/path/to/sample2.tiff
+sample,run_backsub,run_mesmer,run_cellpose,run_cellsam,tiff
+sample1,true,true,false,false,/path/to/sample1.tiff
+sample2,true,false,false,true,/path/to/sample2.tiff
 ```
 
 You may also prefer to use YAML for your samplesheet, either is supported:
@@ -115,19 +116,20 @@ You may also prefer to use YAML for your samplesheet, either is supported:
   run_backsub: true
   run_mesmer: true
   run_cellpose: false
+  run_cellsam: false
   tiff: /path/to/sample1.tiff
 - sample: sample2
   run_backsub: true
   run_mesmer: true
   run_cellpose: false
+  run_cellsam: false
   tiff: /path/to/sample2.tiff
 ```
 
 > [!WARNING]
-> Please ensure that your image name and all directories in your file path do not contain spaces.
+> Please ensure that your image name and all directories in your path do not contain spaces.
 
-If you don't specify any segmentation algorithm to run (mesmer or cellpose), the
-pipeline will run a background subtraction only.
+If you don't specify any segmentation algorithm to run (mesmer, cellpose, or cellsam), the pipeline will run a background subtraction only.
 
 Now, you can run the pipeline using:
 
@@ -167,10 +169,8 @@ You can also set the segmentation parameters for mesmer either via CLI
 (e.g., `--combine_method prod` or in a config file pass to the workflow
 via `-c`. See [usage](docs/usage.md) for a full list.
 
-> [!WARNING]
-> You cannot run both Mesmer and Cellpose segmentation on the same sample (with
-> the same name). If you want to run both on a sample, put it on a different
-> line and give it a different sample name.
+> [!NOTE]
+> You cannot run multiple segmentation methods (Mesmer, Cellpose, or CellSAM) on the same sample (with the same name). If you want to run multiple methods on a sample, put it on a different line and give it a different sample name.
 
 ### Cellpose segmentation
 
@@ -195,6 +195,110 @@ parameters.
 If you want to skip measurements (this may take some time for large images), you
 can use set the parameter `skip_measurements` to `true`.
 
+### KRONOS embeddings
+
+KRONOS is a foundation model for multiplex spatial proteomics that extracts rich embeddings for each cell. These embeddings capture cellular phenotype and microenvironment context, enabling downstream analysis like clustering, classification, and spatial analysis.
+
+To enable KRONOS embeddings:
+
+```bash
+nextflow run main.nf \
+  --input samplesheet.csv \
+  --skip_kronos false \
+  --kronos_model_path /path/to/kronos_model \
+  --kronos_marker_metadata /path/to/marker_metadata.csv \
+  --kronos_merge_geojson true \
+  ...
+```
+
+#### KRONOS parameters
+
+- `--skip_kronos` (default: true): Set to `false` to enable KRONOS embedding extraction
+- `--kronos_model_path` (required): Path to the KRONOS model checkpoint (.pt file)
+- `--kronos_config_path` (optional): Path to KRONOS `config.json` (auto-detected from model directory if not set)
+- `--kronos_marker_metadata` (required): Path to marker metadata CSV file mapping marker IDs to names
+- `--kronos_merge_geojson` (default: false): Merge embeddings into the cellmeasurement GeoJSON output
+- `--kronos_patch_size` (default: 64): Patch size for cell-centered crops
+- `--kronos_batch_size` (default: 32): Batch size for model inference
+- `--kronos_num_workers` (default: 4): Number of DataLoader workers for parallel data loading
+- `--kronos_max_value` (default: 65535): Maximum intensity value for normalization
+- `--kronos_marker_mapping` (optional): JSON string mapping image marker names to KRONOS marker names
+- `--kronos_distance_threshold` (default: 5.0): Maximum centroid distance (pixels) used for GeoJSON merge fallback matching
+
+#### Embeddings for filtered data with KRONOS
+
+When `--kronos_merge_geojson` is enabled, the pipeline automatically creates a new segmentation mask directly from the GeoJSON polygons.
+
+#### Output files
+
+KRONOS produces the following outputs:
+
+- `*_kronos_embeddings.csv`: CSV file with cell IDs, centroids, and 384 embedding dimensions
+- `*_marker_report.txt`: Report showing which image channels were matched to KRONOS markers
+- `*_kronos_merged.geojson` (if `--kronos_merge_geojson=true`): GeoJSON file with embeddings added as cell properties
+
+The merged GeoJSON file contains all original cell measurements plus additional features (`kronos_emb_0` through `kronos_emb_#`), enabling integrated analysis of morphology, intensity, and KRONOS embeddings.
+
+#### Marker matching
+
+KRONOS expects specific marker names based on its training data. The pipeline automatically performs case-insensitive matching between your image channel names and the KRONOS marker metadata. For markers that don't auto-match, use `--kronos_marker_mapping`:
+
+```bash
+--kronos_marker_mapping '{"CD3e": "CD3E", "PanCK": "PANCK"}'
+```
+
+For COMET data with fluorophore suffixes in channel names, you can map them like this:
+
+```bash
+--kronos_marker_mapping '{"DAPI": "DAPI", "FOXP3_T - TRITC": "FOXP3", "CD3_T - Cy5": "CD3"}'
+```
+
+For more information about KRONOS, see the [KRONOS GitHub repository](https://github.com/mahmoodlab/KRONOS).
+
+### CellSAM segmentation
+
+CellSAM is a foundation model for cell segmentation that works across different
+imaging modalities. To use CellSAM as your segmentation algorithm, specify a
+config file like so:
+
+```csv
+sample,run_backsub,run_cellsam,tiff,nuclear_channel,membrane_channels
+sample1,true,true,/path/to/sample1.tiff,DAPI,CD45:CD8
+sample2,false,true,/path/to/sample2.tiff,DAPI,CD45
+```
+
+Nuclear channels only support one entry; membrane channels may have multiple
+values separated by `:` characters. If your channels have spaces in them, make
+sure that you surround your channel name with quotes.
+
+CellSAM uses a tiling approach for large images and supports the following
+parameters:
+
+- `--cellsam_bbox_threshold` (default: 0.4): Confidence threshold for cell detection
+- `--cellsam_block_size` (default: 600): Size of tiles for processing
+- `--cellsam_overlap` (default: 56): Tile overlap for merging
+- `--cellsam_iou_threshold` (default: 0.5): IOU threshold for label merging
+- `--cellsam_use_wsi` (default: true): Enable tiling for large images
+
+#### Model weights
+
+CellSAM can automatically download the latest model weights (v1.2) from
+[users.deepcell.org](https://users.deepcell.org). To use the latest weights:
+
+1. Create an account at [users.deepcell.org](https://users.deepcell.org)
+2. Generate your access token
+3. Set it as a Nextflow secret:
+   ```bash
+   nextflow secrets set DEEPCELL_ACCESS_TOKEN $YOUR_TOKEN
+   ```
+
+If the token is not set, CellSAM will use the default bundled model weights.
+
+> [!NOTE]
+> You cannot run both Mesmer/Cellpose and CellSAM segmentation on the same sample
+> (with the same name). If you want to run multiple methods on a sample, put it
+> on a different line and give it a different sample name.
+
 ## Dealing with large images
 
 You can run the pipeline with different profiles for different size images:
 
@@ -1,2 +1,2 @@
-sample,run_backsub,run_cellpose,run_mesmer,tiff,nuclear_channel,membrane_channels
-SAMPLE,boolean,boolean,boolean,/path/to/image.tif,nuclear_channel,membrane_channel1:membrane_channel2
+sample,run_backsub,run_cellpose,run_mesmer,run_cellsam,tiff,nuclear_channel,membrane_channels
+SAMPLE,boolean,boolean,boolean,boolean,/path/to/image.tif,nuclear_channel,membrane_channel1:membrane_channel2
@@ -28,6 +28,11 @@
                 "default": false,
                 "errorMessage": "Run cellpose must be a boolean"
             },
+            "run_cellsam": {
+                "type": "boolean",
+                "default": false,
+                "errorMessage": "Run cellsam must be a boolean"
+            },
             "tiff": {
                 "type": "string",
                 "format": "file-path",