dropdrop 1.1.0__tar.gz

dropdrop-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dropdrop-1.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Cache
+.cache/

dropdrop-1.1.0/.python-version

@@ -0,0 +1 @@
+3.12

dropdrop-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oleksii Stroganov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dropdrop-1.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: dropdrop
+Version: 1.1.0
+Summary: Python pipeline script for detecting droplets with beads and other inclusions via cellpose
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: cellpose>=4.0.6
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: tqdm>=4.67.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DropDrop
+
+Automated Python pipeline for detecting droplets and inclusions (beads) in microscopy z-stacks using Cellpose segmentation and morphological analysis.
+
+Tailored for the EVOS M5000 Imaging System.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv pip install dropdrop
+
+# Using pip
+pip install dropdrop
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/dropdrop.git
+cd dropdrop
+uv pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Run with interactive prompts
+dropdrop ./images
+
+# Run with settings
+dropdrop ./images --settings "d=1000,p=on,l=experiment1"
+
+# Process only first 5 frames (for testing)
+dropdrop ./images -n 5
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Run pipeline with compact settings
+dropdrop ./images --settings "d=1000,p=on,c=6.5e5,l=experiment1"
+
+# Custom output directory
+dropdrop ./images ./results/my_project --settings "d=500"
+
+# Interactive viewer (view results after processing)
+dropdrop ./images --view
+
+# Interactive editor (manually correct inclusions)
+dropdrop ./images --interactive
+
+# Archive output as tar.gz
+dropdrop ./images -z
+```
+
+### Settings Format
+
+Compact settings string: `d=dilution,p=poisson,c=count,l=label`
+
+| Key | Full name | Description | Default |
+|-----|-----------|-------------|---------|
+| `d` | `dilution` | Dilution factor | 500 |
+| `p` | `poisson` | Enable Poisson analysis (on/off) | on |
+| `c` | `count` | Stock bead count per uL | 6.5e5 |
+| `l` | `label` | Project label for output naming | None |
+
+### Cache Control
+
+```bash
+dropdrop ./images --no-cache       # Disable caching
+dropdrop ./images --clear-cache    # Clear cache before run
+```
+
+## Interactive Editor
+
+The editor allows manual correction of detected inclusions:
+
+| Key | Action |
+|-----|--------|
+| Left-click | Add inclusion |
+| Right-click (hold) | Remove inclusions |
+| `s` | Toggle droplet selection (hover over droplet) |
+| `u` | Undo last action |
+| `c` | Clear all inclusions in frame |
+| `d` | Toggle droplet visibility |
+| Arrow keys / Space | Navigate frames |
+| `q` / Esc | Exit |
+
+Disabled droplets (gray with X) are excluded from the final results.
+
+## Output Structure
+
+```
+results/<YYYYMMDD>_<label>/
+  data.csv                  # Raw detection data
+  summary.txt               # Settings and statistics
+  size_distribution.png     # Droplet diameter histogram
+  poisson_comparison.png    # Bead distribution vs theoretical
+```
+
+### data.csv columns
+
+| Column | Description |
+|--------|-------------|
+| `frame` | Frame index |
+| `droplet_id` | Droplet ID within frame |
+| `center_x`, `center_y` | Droplet center coordinates (px) |
+| `diameter_px`, `diameter_um` | Droplet diameter |
+| `area_px`, `area_um2` | Droplet area |
+| `inclusions` | Number of inclusions detected |
+
+## Configuration
+
+Create `config.json` in your working directory to customize detection parameters:
+
+```json
+{
+  "cellpose_flow_threshold": 0.4,
+  "cellpose_cellprob_threshold": 0.0,
+  "erosion_pixels": 5,
+  "kernel_size": 7,
+  "tophat_threshold": 30,
+  "min_inclusion_area": 7,
+  "max_inclusion_area": 50,
+  "edge_buffer": 5,
+  "min_droplet_diameter": 80,
+  "max_droplet_diameter": 200,
+  "px_to_um": 1.14,
+  "cache": {
+    "enabled": true,
+    "max_frames": 100
+  }
+}
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `cellpose_flow_threshold` | Cellpose flow threshold for segmentation |
+| `cellpose_cellprob_threshold` | Cellpose cell probability threshold |
+| `erosion_pixels` | Pixels to erode droplet mask before inclusion detection |
+| `kernel_size` | Morphological kernel size for black-hat transform |
+| `tophat_threshold` | Threshold for inclusion detection |
+| `min/max_inclusion_area` | Inclusion size constraints (px) |
+| `edge_buffer` | Buffer from image edge to ignore inclusions |
+| `min/max_droplet_diameter` | Droplet size constraints (px) |
+| `px_to_um` | Pixel to micrometer conversion factor |
+
+## Requirements
+
+- Python 3.12+
+- CUDA-capable GPU (recommended for Cellpose)
+
+## License
+
+MIT

dropdrop-1.1.0/README.md

@@ -0,0 +1,160 @@
+# DropDrop
+
+Automated Python pipeline for detecting droplets and inclusions (beads) in microscopy z-stacks using Cellpose segmentation and morphological analysis.
+
+Tailored for the EVOS M5000 Imaging System.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv pip install dropdrop
+
+# Using pip
+pip install dropdrop
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/dropdrop.git
+cd dropdrop
+uv pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Run with interactive prompts
+dropdrop ./images
+
+# Run with settings
+dropdrop ./images --settings "d=1000,p=on,l=experiment1"
+
+# Process only first 5 frames (for testing)
+dropdrop ./images -n 5
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Run pipeline with compact settings
+dropdrop ./images --settings "d=1000,p=on,c=6.5e5,l=experiment1"
+
+# Custom output directory
+dropdrop ./images ./results/my_project --settings "d=500"
+
+# Interactive viewer (view results after processing)
+dropdrop ./images --view
+
+# Interactive editor (manually correct inclusions)
+dropdrop ./images --interactive
+
+# Archive output as tar.gz
+dropdrop ./images -z
+```
+
+### Settings Format
+
+Compact settings string: `d=dilution,p=poisson,c=count,l=label`
+
+| Key | Full name | Description | Default |
+|-----|-----------|-------------|---------|
+| `d` | `dilution` | Dilution factor | 500 |
+| `p` | `poisson` | Enable Poisson analysis (on/off) | on |
+| `c` | `count` | Stock bead count per uL | 6.5e5 |
+| `l` | `label` | Project label for output naming | None |
+
+### Cache Control
+
+```bash
+dropdrop ./images --no-cache       # Disable caching
+dropdrop ./images --clear-cache    # Clear cache before run
+```
+
+## Interactive Editor
+
+The editor allows manual correction of detected inclusions:
+
+| Key | Action |
+|-----|--------|
+| Left-click | Add inclusion |
+| Right-click (hold) | Remove inclusions |
+| `s` | Toggle droplet selection (hover over droplet) |
+| `u` | Undo last action |
+| `c` | Clear all inclusions in frame |
+| `d` | Toggle droplet visibility |
+| Arrow keys / Space | Navigate frames |
+| `q` / Esc | Exit |
+
+Disabled droplets (gray with X) are excluded from the final results.
+
+## Output Structure
+
+```
+results/<YYYYMMDD>_<label>/
+  data.csv                  # Raw detection data
+  summary.txt               # Settings and statistics
+  size_distribution.png     # Droplet diameter histogram
+  poisson_comparison.png    # Bead distribution vs theoretical
+```
+
+### data.csv columns
+
+| Column | Description |
+|--------|-------------|
+| `frame` | Frame index |
+| `droplet_id` | Droplet ID within frame |
+| `center_x`, `center_y` | Droplet center coordinates (px) |
+| `diameter_px`, `diameter_um` | Droplet diameter |
+| `area_px`, `area_um2` | Droplet area |
+| `inclusions` | Number of inclusions detected |
+
+## Configuration
+
+Create `config.json` in your working directory to customize detection parameters:
+
+```json
+{
+  "cellpose_flow_threshold": 0.4,
+  "cellpose_cellprob_threshold": 0.0,
+  "erosion_pixels": 5,
+  "kernel_size": 7,
+  "tophat_threshold": 30,
+  "min_inclusion_area": 7,
+  "max_inclusion_area": 50,
+  "edge_buffer": 5,
+  "min_droplet_diameter": 80,
+  "max_droplet_diameter": 200,
+  "px_to_um": 1.14,
+  "cache": {
+    "enabled": true,
+    "max_frames": 100
+  }
+}
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `cellpose_flow_threshold` | Cellpose flow threshold for segmentation |
+| `cellpose_cellprob_threshold` | Cellpose cell probability threshold |
+| `erosion_pixels` | Pixels to erode droplet mask before inclusion detection |
+| `kernel_size` | Morphological kernel size for black-hat transform |
+| `tophat_threshold` | Threshold for inclusion detection |
+| `min/max_inclusion_area` | Inclusion size constraints (px) |
+| `edge_buffer` | Buffer from image edge to ignore inclusions |
+| `min/max_droplet_diameter` | Droplet size constraints (px) |
+| `px_to_um` | Pixel to micrometer conversion factor |
+
+## Requirements
+
+- Python 3.12+
+- CUDA-capable GPU (recommended for Cellpose)
+
+## License
+
+MIT

dropdrop-1.1.0/config.json

@@ -0,0 +1,18 @@
+{
+  "cellpose_flow_threshold": 0.4,
+  "cellpose_cellprob_threshold": 0.0,
+  "erosion_pixels": 5,
+  "kernel_size": 7,
+  "tophat_threshold": 30,
+  "min_inclusion_area": 7,
+  "max_inclusion_area": 50,
+  "edge_buffer": 5,
+  "min_droplet_diameter": 80,
+  "max_droplet_diameter": 200,
+  "px_to_um": 1.14,
+  "cache": {
+    "enabled": true,
+    "max_frames": 100,
+    "strategy": "lru"
+  }
+}

dropdrop-1.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "dropdrop"
+version = "1.1.0"
+description = """Python pipeline script for detecting droplets with beads and
+other inclusions via cellpose"""
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "cellpose>=4.0.6",
+    "matplotlib>=3.10.6",
+    "numpy>=2.3.3",
+    "opencv-python>=4.11.0.86",
+    "pandas>=2.3.3",
+    "scipy>=1.16.2",
+    "seaborn>=0.13.2",
+    "tqdm>=4.67.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+dropdrop = "dropdrop.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dropdrop"]

dropdrop-1.1.0/src/dropdrop/__init__.py

@@ -0,0 +1,16 @@
+"""DropDrop - Droplet and Inclusion Detection Pipeline."""
+
+from .cache import CacheManager
+from .config import load_config
+from .pipeline import DropletInclusionPipeline
+from .stats import DropletStatistics
+from .ui import BaseWindow, InclusionEditor, Viewer
+
+__all__ = [
+    "CacheManager",
+    "DropletInclusionPipeline",
+    "DropletStatistics",
+    "InclusionEditor",
+    "Viewer",
+    "load_config",
+]

dropdrop-1.1.0/src/dropdrop/cache.py

@@ -0,0 +1,133 @@
+"""Cache management for expensive computations."""
+
+import hashlib
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+import numpy as np
+
+
+class CacheManager:
+    """Global LRU cache for expensive computations, stored in project root."""
+
+    def __init__(self, config, cache_dir=None):
+        cache_cfg = config.get("cache", {})
+        self.enabled = cache_cfg.get("enabled", True)
+        self.max_frames = cache_cfg.get("max_frames", 100)
+        # Cache in project root by default
+        if cache_dir:
+            self.cache_dir = Path(cache_dir)
+        else:
+            self.cache_dir = Path(__file__).parent.parent.parent / ".cache"
+        self.metadata_path = self.cache_dir / "metadata.json"
+        self.metadata = self._load_metadata()
+        self.config = config
+
+    def _load_metadata(self):
+        """Load cache metadata from disk."""
+        if self.metadata_path.exists():
+            try:
+                with open(self.metadata_path) as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, IOError):
+                return self._default_metadata()
+        return self._default_metadata()
+
+    def _default_metadata(self):
+        """Return default metadata structure."""
+        return {"version": "1.0", "config_hash": None, "frames": {}, "access_order": []}
+
+    def _save_metadata(self):
+        """Save cache metadata to disk."""
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        with open(self.metadata_path, "w") as f:
+            json.dump(self.metadata, f, indent=2)
+
+    def _enforce_lru(self):
+        """Remove oldest frames if over max_frames limit."""
+        while len(self.metadata["access_order"]) > self.max_frames:
+            oldest_key = self.metadata["access_order"].pop(0)
+            cache_file = self.cache_dir / f"{oldest_key}.npz"
+            if cache_file.exists():
+                cache_file.unlink()
+            self.metadata["frames"].pop(oldest_key, None)
+
+    def get_config_hash(self):
+        """Hash detection-related config keys that affect caching."""
+        keys = [
+            "cellpose_flow_threshold",
+            "cellpose_cellprob_threshold",
+            "min_droplet_diameter",
+            "max_droplet_diameter",
+        ]
+        data = {k: self.config.get(k) for k in keys}
+        return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()[:16]
+
+    def _get_cache_key(self, source_filename):
+        """Generate cache key from source filename (not full path)."""
+        name = Path(source_filename).stem
+        return hashlib.sha256(name.encode()).hexdigest()[:16]
+
+    def is_valid(self, source_filename):
+        """Check if cache is valid for frame by source filename."""
+        if not self.enabled:
+            return False
+        current_hash = self.get_config_hash()
+        if self.metadata.get("config_hash") != current_hash:
+            return False
+        cache_key = self._get_cache_key(source_filename)
+        cache_file = self.cache_dir / f"{cache_key}.npz"
+        return cache_file.exists()
+
+    def load_frame(self, source_filename):
+        """Load cached data by source filename and update access order."""
+        cache_key = self._get_cache_key(source_filename)
+        cache_file = self.cache_dir / f"{cache_key}.npz"
+        data = np.load(cache_file, allow_pickle=True)
+
+        # Update LRU order
+        if cache_key in self.metadata["access_order"]:
+            self.metadata["access_order"].remove(cache_key)
+        self.metadata["access_order"].append(cache_key)
+        self._save_metadata()
+
+        return {
+            "min_projection": data["min_projection"],
+            "droplet_coords": list(data["droplet_coords"]),
+        }
+
+    def save_frame(self, source_filename, min_proj, droplet_coords):
+        """Save frame data by source filename and enforce LRU limit."""
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_key = self._get_cache_key(source_filename)
+        cache_file = self.cache_dir / f"{cache_key}.npz"
+
+        np.savez(
+            cache_file,
+            min_projection=min_proj,
+            droplet_coords=np.array(droplet_coords, dtype=object),
+        )
+
+        # Update metadata
+        self.metadata["config_hash"] = self.get_config_hash()
+        self.metadata["frames"][cache_key] = {
+            "source": str(source_filename),
+            "cached_at": datetime.now().isoformat(),
+        }
+
+        # Update LRU order
+        if cache_key in self.metadata["access_order"]:
+            self.metadata["access_order"].remove(cache_key)
+        self.metadata["access_order"].append(cache_key)
+
+        self._enforce_lru()
+        self._save_metadata()
+
+    def clear(self):
+        """Clear entire cache."""
+        if self.cache_dir.exists():
+            shutil.rmtree(self.cache_dir)
+        self.metadata = self._default_metadata()
+        print("Cache cleared.")