Home

A napari-based graphical user interface (GUI) for fully reproducible extraction, orientation, and morphometric analysis of leaf outlines.
This tool allows researchers to perform every processing step interactively — from setting image scale to exporting normalized Elliptic Fourier Descriptors (EFDs) — all within a single, unified environment.

Key Features

  • User-friendly yet fully reproducible workflow
    A complete graphical interface built on napari enables users to perform every step — from image loading to EFD export — without writing code.
    All parameters, transformations, and processing histories are automatically stored as structured metadata (JSON/CSV), ensuring full reproducibility.

  • Biologically consistent leaf orientation
    Leaf images are aligned based on manually defined base–tip landmarks, guaranteeing consistent orientation across samples.
    This allows for direct comparison of leaf outlines across individuals, species, and populations.

  • Oriented True Normalized Elliptic Fourier Descriptors (EFDs)
    Implements a customized version of the true normalized EFDs following Wu et al., (2024), enabling the computation of oriented descriptors that preserve biologically meaningful shape orientation and symmetry.

  • Flexible and editable segmentation options
    Provides both traditional Otsu thresholding (Otsu 1979) and deep-learning–based SAM2 segmentation (Ravi et al. 2024), ensuring robust contour extraction under diverse imaging conditions.
    Users can interactively adjust threshold values or manually refine segmentation masks using napari’s built-in painting, polygon, and erasing tools, achieving precise control while maintaining reproducibility.

  • Comprehensive metadata export
    Every processing step — scale calibration, ROI cropping, landmark placement, rotation, binarization, contour extraction, and EFD computation — is saved in machine-readable form, supporting transparent and reproducible shape analysis pipelines.

Installation

There are three ways to install and run the Leaf Shape Analysis Tool. Choose the method that best fits your environment.

Method Description Recommended for
Standalone App Ready-to-use executable for Windows and macOS. No Python required. General users
Setup Script Automatically creates a reproducible environment via uv and installs dependencies. Reproducible workflows
Manual Setup Build the environment from scratch for development or debugging. Developers

2. Setup Script

Clone the repository and launch the tool using the provided script.

git clone https://github.com/maple60/morphometrics-tool.git
cd morphometrics-tool
  • Windows
setup\setup_windows.bat
  • macOS / Linux (In preparation)
bash setup/setup_unix.sh

This script automatically:

  • Creates a virtual environment (uv venv)
  • Installs all dependencies from uv.lock
  • Clones and installs SAM2
  • Verifies checkpoints for SAM2 models
  • Launches the tool

3. Manual Setup (Developers)

If you prefer to configure everything manually:

uv venv
.venv\Scripts\activate       # source .venv/bin/activate  (macOS/Linux)
uv sync
git clone https://github.com/facebookresearch/sam2.git
cd sam2
uv pip install -e .
cd ..

If you plan to use Segment Anything Model 2 (SAM2) for segmentation, make sure its checkpoints are downloaded into sam2/checkpoints/. For details about each model, refer to the following page:

After installation, launch the tool with:

leaf-shape-tool
Note

For full setup instructions (including uv, git, and checkpoint downloads), see the Installation Guide.

Workflow & Usage

---
config:
  layout: dagre
---
flowchart TD
    A["Load image"] --> B{"Set scale?"}
    B -- Yes --> B1["Set the scale"]
    B -- No --> C["Add ROI layer"]
    B1 --> C
    C --> D["Add landmarks"]
    D --> E["Rotate image"]
    E --> F["Binarize image"]
    F --> G{"Edit needed?"}
    G -- Yes --> G1["Edit the binarized label layer"]
    G1 --> H["Extract contour"]
    G -- No --> H
    H --> J["Reset viewer"]
    J --> L{"Process next ROI?"}
    L -- Yes --> C
    L -- No --> M["Reset all layers"]
    M --> N{"Process next image?"}
    N -- Yes --> A
    N -- No --> O["Done"]

Each processing step corresponds to a dedicated GUI widget,
and all results (images, contours, metadata, EFDs) are automatically exported to the output/ directory.

For a detailed step-by-step guide, please refer to the Usage page.

Citation

Currently in preparation

Acknowledgements

This tool is built upon the following open-source frameworks:

  • napari: interactive image viewer framework
  • scikit-image: image processing library
  • numpy: numerical computation library
  • pandas: data analysis library
  • matplotlib: visualization and plotting library

The design and implementation of this tool were inspired by the methodology and GUI software developed by (2024), particularly the ElliShape interface (https://www.plantplus.cn/ElliShape/).

We also acknowledge the contributions of many other open-source tools and studies
that have advanced automated leaf image analysis.
A summary of related software can be found on the Related Tools page.

We express our sincere gratitude to the open-source community and all contributors
whose work made this tool possible.

License

Distributed under the BSD 3-Clause License. See LICENSE for more information.

References

Otsu, Nobuyuki. 1979. “A Threshold Selection Method from Gray-Level Histograms.” IEEE Transactions on Systems, Man, and Cybernetics 9 (1): 62–66. https://doi.org/10.1109/TSMC.1979.4310076.
Ravi, Nikhila, Valentin Gabeur, Yuan-Ting Hu, Ronghang Hu, Chaitanya Ryali, Tengyu Ma, Haitham Khedr, et al. 2024. “SAM 2: Segment Anything in Images and Videos.” https://arxiv.org/abs/2408.00714.
Wu, Hui, Jia-Jie Yang, Chao-Qun Li, Jin-Hua Ran, Ren-Hua Peng, and Xiao-Quan Wang. 2024. “Reliable and Superior Elliptic Fourier Descriptor Normalization and Its Application Software ElliShape with Efficient Image Processing.” https://arxiv.org/abs/2412.10795.