SAM Particle Counter

日本語版READMEはこちら / Japanese README

Left: original / Right: final overlay

SAM Particle Counter is a desktop application for counting particles from image data using SAM2-assisted segmentation and napari-based visualization.

Online manual is available here

Prerequisites

Before setup, confirm the following requirements.

• Python: >=3.11.6 (defined in pyproject.toml)
• Required tool: uv for dependency and virtual environment management
• GPU/CUDA:
  • GPU is optional. The app can run on CPU, but performance may be slower.
  • For GPU acceleration, use a CUDA-compatible NVIDIA GPU and install a CUDA-compatible PyTorch build for your environment.
  • Verify CUDA and PyTorch compatibility for your OS/driver before running setup.
• OS notes:
  • Windows: Use PowerShell commands shown below and run .bat setup scripts.
  • macOS: Use shell commands shown below and run .sh setup scripts.
  • Linux: Use shell commands shown below and run .sh setup scripts.

Get Started

Clone the repository

Clone the repository, then set up the virtual environment and install dependencies.

uv sync

By default, uv sync resolves torch from PyPI. On some platforms (for example Linux x86_64), the PyPI wheel may already include CUDA runtime dependencies, while other platforms/environments may get CPU-only builds.

Always verify your installed build first, then switch to a specific CPU/CUDA index only when needed (see examples below).

Switch PyTorch build (CPU / CUDA)

You can keep the same project and swap PyTorch builds to match your PC.

• Confirm current build:

uv run python -c "import torch; print('torch=', torch.__version__, 'cuda=', torch.version.cuda, 'available=', torch.cuda.is_available())"

• Reinstall CPU build explicitly:

uv pip install --upgrade --index-url https://download.pytorch.org/whl/cpu torch torchvision torchaudio

• Reinstall CUDA 12.1 build (example):

uv pip install --upgrade --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio

Note 1: --upgrade replaces the currently installed torch* packages in the same uv environment, so running this after uv sync is meaningful.

Note 2: You can check the driver-supported CUDA runtime with nvidia-smi (CUDA Version: ...), then select a compatible PyTorch CUDA wheel (for example cu121).

You can find the appropriate PyTorch installation command here. Use uv pip instead of pip3.

Setup SAM2

Setup the Segment Anything Model2 (SAM2).

Windows

setup\setup_sam2.bat

macOS/Linux

./setup/setup_sam2.sh

Launch the application

uv run main.py

Quick Start Workflow

This is the typical operation flow for particle counting in napari. The wording matches the main.py UI button names so users can map README steps directly to the UI.

1. Load an image
   Open an image in napari (drag and drop, or File > Open...). When the first image is added, the corresponding ROI layer (<image_name>_ROI) is created automatically.
2. Create/select the ROI layer and draw a rectangle
   Select the *_ROI layer, then draw one rectangular ROI with the Shapes tool (if multiple ROIs exist, the most recently drawn ROI is used).
3. Run crop
   Execute Crop to ROI in the right dock to create the <image_name>_cropped layer.
4. Run SAM2 auto segmentation
   Select the <image_name>_cropped image layer, then execute Run SAM2 auto segmentation in the right dock. Adjust parameters such as Output mode as needed.
5. Check particle counts and export
   After reviewing segmentation results, execute Export segmentation artifacts in the right dock. In the completion message, sam2=... and final=... indicate particle counts.

How to cite

If you use SAM Particle Counter in your research, please cite the software release:

Kaede Konrai. (2026). maple60/sam-particle-counter: v0.1.0 (v0.1.0). Zenodo. https://doi.org/10.5281/zenodo.19678863

You can also find citation metadata in CITATION.cff.

Acknowledgements

This project depends heavily on many open-source software projects. In particular, I would like to thank the developers and contributors of napari, Segment Anything Model 2 (SAM 2), OpenCV, NumPy, grasbey, and pandas.

This software was also inspired in part by existing plant image analysis workflows and tools, including Samplify (Bente et al., 2026).

AI Assistant

AI tools, including GitHub Copilot and OpenAI tools (ChatGPT/Codex), were used to assist in drafting code and revising documentation.

All methodological decisions and validations were conducted by the author. The author assumes full responsibility for the scientific correctness and reproducibility of this software.

License

This project is licensed under the BSD 3-Clause License. See LICENSE for details.