A Python library for extracting comprehensive morphological features from cell segmentation masks in microscopy time-series data. Allowing for morphokinetic analysis of cell and organelle shape dynamics.

Cellmorph processes segmented cell image masks (TIFF stacks) to compute 260+ morphological features per cell, including:

• Static features: Area, perimeter, circularity, eccentricity, Hu moments, convex hull properties
• Dynamic features: Centroid velocity, orientation changes, MSD-based diffusive/directed velocity
• Boundary features: Multi-scale curvature, spectral analysis, wavelet decomposition
• Protrusion detection: Peak detection with Fourier contour reconstruction
• Shape descriptors: Elliptical Fourier descriptors, deformation metrics

The pipeline includes Bayesian cell tracking to maintain cell identity across frames, allowing for processing of multi-cell time-lapse datasets.

# Clone the repository
git clone https://github.com/L-kuehl/cellmorph.git
cd cellmorph

# Install with uv (recommended)
uv sync

# Or with pip
pip install -r requirements.txt

python run_extraction.py /path/to/experiment /path/to/output

python run_extraction.py /path/to/experiment /path/to/output --debug

This limits processing to 10 frames and 3 cells for quick testing.

cellmorph expects the following directory structure:

experiment_dir/
├── condition1/
│   ├── sample1_Cell.tif
│   ├── sample1_Nucleus.tif
│   └── sample2_Cell.tif
├── condition2/
│   └── sample3_Cell.tif

• TIFF files: 2D or 3D (time-series) segmentation masks
• Naming convention: {sample_name}_{SegmentationType}.tif
• Segmentation types: Cell, Nucleus, Tissue, Granule

For each sample, cellmorph generates:

import pandas as pd

# Load feature DataFrame
df = pd.read_pickle("output/condition1/20241229_sample1_Cell_feature_df.pkl")

# Each row = one cell in one frame
print(df.columns)  # 260+ feature columns
print(df.head())

cellmorph supports flexible configuration via environment variables and .env files.

# Copy the example configuration
cp .env.example .env

# Edit with your settings
nano .env

Settings are resolved in this order (highest to lowest priority):

1. Command line arguments
2. Environment variables
3. .env file in current directory
4. Default values

# Paths
CELLMORPH_EXPERIMENT_DIR=/data/microscopy/experiment1
CELLMORPH_SAVE_DIR=/data/features/experiment1

# Adjust for your microscope
CELLMORPH_SCALE_FACTOR_UM_PX=0.1032

# Filter settings
CELLMORPH_MIN_CELL_SIZE=100
CELLMORPH_MIN_TRACK_LENGTH=50

# Use 8 cores
CELLMORPH_N_WORKERS=8

from src.config import get_config, CellmorphConfig
from src.extract_features import Processor

# Load from .env file
config = get_config(env_file="production.env")

# Or create programmatically
config = CellmorphConfig.default()
config.processing.scale_factor_um_px = 0.2
config.processing.min_cell_size = 150

# Use with Processor
processor = Processor(
    experiment_dir="/path/to/data",
    save_dir="/path/to/output",
    config=config,
)

src/
├── extract_features.py   # Main pipeline orchestrator
├── feature_classes.py    # Data structures (CellFeatures, SampleFeatures)
├── static_features.py    # Per-frame morphological features
├── dynamic_features.py   # Time-series derived features
├── boundary_features.py  # Curvature and boundary analysis
├── protrusion_features.py# Protrusion detection and tracking
├── tracking.py           # Cell tracking (btrack wrapper)
├── elliptical_fourier.py # Fourier shape descriptors
├── curvature.py          # Gradient-based curvature
└── utils.py              # Utility functions

• btrack: Bayesian cell tracking
• spatial-efd: Elliptical Fourier descriptors
• trackpy: Particle/protrusion tracking
• scikit-image: Image processing
• scipy: Signal processing, optimization
• pywavelets: Wavelet analysis

Usage: cellmorph [OPTIONS] [EXPERIMENT_DIR] [SAVE_DIR]

  Extract morphological features from microscopy segmentation data.

Arguments:
  EXPERIMENT_DIR  Path to directory containing experiment data (optional if set in .env)
  SAVE_DIR        Path to directory where features will be saved (optional if set in .env)

Options:
  -d, --debug / --no-debug     Enable debug mode (10 frames, 3 cells)
  -c, --create-dirs            Create save directory if needed (default: True)
  -n, --n-workers INTEGER      Number of parallel workers (default: all cores)
  -e, --env-file PATH          Path to .env configuration file
  -l, --log-level [DEBUG|INFO|WARNING|ERROR]
                               Logging level
  --help                       Show this message and exit

Examples:
  # Using command line arguments
  $ cellmorph /path/to/experiment /path/to/output --debug

  # Using .env file only (paths configured in .env)
  $ cellmorph --env-file config.env

  # Mix: CLI args override .env file settings
  $ cellmorph /data/exp1 /data/output --env-file production.env --debug

MIT License - see LICENSE for details.

If you use cellmorph in your research, please cite:

@software{cellmorph,
  author = {Kühl, Lucas},
  title = {cellmorph: Comprehensive Cell Morphology Feature Extraction},
  year = {2025},
  url = {https://github.com/L-kuehl/cellmorph}
}

Complete list of all extracted features organized by category.

Basic shape measurements computed from the binary mask in each frame.

Shape Indices

Centroid and Position

Bounding Geometry

Convex Hull Properties

Feret Diameters (Caliper Measurements)

Radial Distance Statistics

Hu Moments

Temporal features computed from changes between consecutive frames.

Velocity Features

Rate of Change Features

MSD-Based Velocity Features

Computed by fitting MSD = d×t + v²×t² to centroid trajectories in sliding windows.

Boundary Dynamics

Features describing the shape and complexity of the cell boundary.

Basic Boundary Properties

Multi-Scale Curvature

Curvature computed at different smoothing scales (5, 10, 20 interpolation points).

Curvature Statistics

Spectral Curvature Analysis

FFT-based analysis of the curvature signal.

Curvature Zero-Crossings

Curvature Persistence

Analysis of continuous positive/negative curvature segments.

Local Curvature Extrema

Scale-Space Curvature

Autocorrelation Features

Shape Index Classification

Boundary regions classified by normalized curvature values.

Multifractal Analysis

Wavelet-based multifractal analysis of curvature.

Boundary Tortuosity and Anisotropy

Wavelet Boundary Features

Wavelet decomposition of the centroid-to-boundary distance signal.

Local Boundary Variation

Rolling window analysis of boundary point positions.

Centroid Asymmetry

Asymmetry of boundary distances in different quadrants.

Features describing cell protrusions detected via Fourier contour reconstruction.

Per-Frame Protrusion Detection

Aggregated Protrusion Statistics (per frame)

Tracked Protrusion Dynamics

Features from tracking individual protrusions over time using trackpy.

Elliptical Fourier descriptor features using spatial_efd.