AutoMorphoTrack 1.0.0__py3-none-any.whl

AutoMorphoTrack-1.0.0.dist-info/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Armin Bayati
+
+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.

AutoMorphoTrack-1.0.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.1
+Name: AutoMorphoTrack
+Version: 1.0.0
+Summary: AutoMorphoTrack is an open-source Python package for automated detection, morphology classification, motility tracking, and colocalization analysis of organelles in multichannel fluorescence microscopy data.
+Home-page: https://github.com/abayatibrain/AMTpackage
+Author: Armin Bayati
+Author-email: a.bayati.brain@gmail.com
+License: MIT
+Project-URL: Documentation, https://github.com/abayatibrain/AMTpackage
+Project-URL: Source, https://github.com/abayatibrain/AMTpackage
+Project-URL: Tracker, https://github.com/abayatibrain/AMTpackage/issues
+Platform: UNKNOWN
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy (>=1.23.0)
+Requires-Dist: pandas (>=1.5.0)
+Requires-Dist: matplotlib (>=3.6.0)
+Requires-Dist: seaborn (>=0.12.0)
+Requires-Dist: opencv-python (>=4.6.0)
+Requires-Dist: scikit-image (>=0.19.0)
+Requires-Dist: scipy (>=1.9.0)
+Requires-Dist: tifffile (>=2022.8.12)
+
+# AutoMorphoTrack
+
+**AutoMorphoTrack** is an open-source Python package for automated detection, morphology classification, shape profiling, motility tracking, and colocalization analysis of subcellular organelles in multichannel fluorescence microscopy data.  
+
+This package represents the fully modular version of the **AutoMorphoTrack pipeline**, originally developed as a Jupyter Notebook by **Armin Bayati, Ph.D.**, and now distributed as an installable Python framework.  
+Repository: [https://github.com/abayatibrain/automorphotrack](https://github.com/abayatibrain/automorphotrack)
+
+---
+
+## 🧬 Overview
+
+AutoMorphoTrack automates quantitative analysis of time-lapse `.tif` image stacks—typically dual-channel recordings of mitochondria and lysosomes—and generates publication-ready visual and numerical outputs at every step of the analysis pipeline.
+
+**Pipeline stages:**
+
+1. **Detection** – Organelle segmentation and outline visualization  
+2. **Lysosomal Counting** – Per-frame lysosome enumeration and temporal profiling  
+3. **Morphology Classification** – Elongated vs. punctate mitochondria  
+4. **Shape Feature Extraction** – Area, circularity, solidity, aspect ratio, orientation  
+5. **Tracking** – Cumulative organelle trajectories (mitochondria, lysosomes, composite)  
+6. **Motility Analysis** – Velocity, displacement, and trajectory-based statistics  
+7. **Colocalization** – Bright-blue overlap overlays and correlation metrics  
+8. **Integrated Summary** – Correlation matrices linking morphology, motility, and overlap  
+
+Each stage outputs high-resolution figures, videos, and CSV data tables stored in standardized subdirectories, ensuring reproducibility and compatibility with any image dataset.
+
+---
+
+## 📦 Installation
+
+Install directly from PyPI:
+
+```bash
+pip install AutoMorphoTrack
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/abayatibrain/automorphotrack.git
+cd automorphotrack
+pip install -e .
+```
+
+---
+
+## 🚀 Basic Usage
+
+```python
+from automorphotrack import *
+
+tif_path = "Composite.tif"
+
+detect_organelles(tif_path)
+count_lysosomes_per_frame(tif_path)
+classify_morphology(tif_path)
+analyze_shape_features(tif_path)
+track_organelles(tif_path)
+analyze_motility()
+analyze_colocalization(tif_path)
+summarize_integrated_data()
+```
+
+Each function automatically generates visual and quantitative outputs at every step.
+
+---
+
+## 📁 Outputs
+
+| Step | Output Type | Example Files |
+|------|--------------|---------------|
+| Detection | PNG + MP4 | `Mito_Frame0.png`, `Mitochondria_Detection.mp4` |
+| Lysosome Count | PNG + CSV + MP4 | `Lyso_Count_Plot.png`, `Lysosome_Counts.csv` |
+| Morphology | PNG + MP4 + CSV | `Morphology_Frame0_Labeled.png`, `Morphology_Labeled.mp4` |
+| Shape Features | PNG + CSV | `Shape_Distributions.png`, `Mito_ShapeMetrics.csv` |
+| Tracking | PNG + MP4 + CSV | `Cumulative_Mito.png`, `Mito_Tracks.csv` |
+| Motility | PNG + CSV | `Motility_Distributions.png`, `Motility_Scatter.png` |
+| Colocalization | PNG + MP4 + CSV | `Colocalization_Frame0.png`, `Colocalization.csv` |
+| Summary | PNG + CSV | `Integrated_CorrelationMatrix.png`, `Integrated_Merged_Data.csv` |
+
+---
+
+## 🔧 Dependencies
+
+- Python ≥ 3.9  
+- numpy, pandas, matplotlib, seaborn, opencv-python, scikit-image, scipy, tifffile
+
+---
+
+## 🧩 Citation
+
+If you use **AutoMorphoTrack** in your research, please cite:
+
+> **Bayati, A. (2025)**. AutoMorphoTrack: An accessible Python framework for automated analysis of organelle morphology and motility.  
+> *GitHub Repository:* [https://github.com/abayatibrain/automorphotrack](https://github.com/abayatibrain/automorphotrack)
+
+

AutoMorphoTrack-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+automorphotrack/__init__.py,sha256=DsfyrpqWJhF3J2QtP0fz7td1GkTT-kYRazKX8zg3m90,2570
+automorphotrack/colocalization.py,sha256=ot1Gmnx_x9Bmhshnhi8irf3SFIFPnbqSJzyOLv7y_-U,5026
+automorphotrack/detection.py,sha256=DBKHLXBD_6yphaB4_msUbAVP7h9VfUrgrnI8-5oE9Yk,2880
+automorphotrack/lyso_count.py,sha256=4Z2OUGZO5On7Q4NHniQUJV2sgU-vHfZV92mlEUO3VZc,3395
+automorphotrack/morphology.py,sha256=b0HXCUY79zaCeZL0qlFoUrYvwhD0X2ivefqz7RwxqEg,5576
+automorphotrack/motility.py,sha256=NNf_G68IMRMctNbv0gzsTW6u_vXJL_BrO08fKfjvJwY,4272
+automorphotrack/shape_features.py,sha256=pKFQcJvlKwk8HNY9AjuVMLWCsnhDqnnGelExv0oWv0A,4203
+automorphotrack/shape_profiling.py,sha256=XXYEUFByzybXcNZR57hYnNC17jVxuZGhIqaXyL6jqnQ,1863
+automorphotrack/summary.py,sha256=aNE0JAe-QJf06YAyiLO4BQTk2ckS1sftH5ImpzhnHGI,2940
+automorphotrack/tracking.py,sha256=NgjjmxiZulyuOCpuQnE0WNSaKbw7tGNu_gv4FSGPvIQ,5681
+automorphotrack/tracking_overlay.py,sha256=LgBwLOI6rj9D71DxdjJIexyKG6R6WqFjaRsz-V0q9Wo,5426
+automorphotrack/utils.py,sha256=2BjQnNTetzUNuHgoseAaktZ1EbBZiHzSktvQZ6sBWZE,1207
+AutoMorphoTrack-1.0.0.dist-info/LICENSE.md,sha256=C2loTUG_HnWtD719BDxgquwzwWYCpJtpMILJEktYUos,1069
+AutoMorphoTrack-1.0.0.dist-info/METADATA,sha256=81YtYarqVqx_0NMxUbOff_SEYuGkdG7ZhMEX4s6QShk,4877
+AutoMorphoTrack-1.0.0.dist-info/WHEEL,sha256=LRS-GSFNyYPLBJaJJ6kxdk4Urtb4kEVXWc5DpA8iv6o,97
+AutoMorphoTrack-1.0.0.dist-info/top_level.txt,sha256=t2gMCx-ewdtS91D7S7vPeSrRV5OnidZvXAowk5Cbros,16
+AutoMorphoTrack-1.0.0.dist-info/RECORD,,

AutoMorphoTrack-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.32.3)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

AutoMorphoTrack-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+automorphotrack

automorphotrack/__init__.py

@@ -0,0 +1,75 @@
+# ============================================================
+# AutoMorphoTrack – Automated Organelle Detection and Tracking
+# ============================================================
+# Author: Armin Bayati, Ph.D.
+# Description:
+#     AutoMorphoTrack is a modular image-analysis package for
+#     mitochondria and lysosome tracking, morphology, shape,
+#     motility, and colocalization analysis in fluorescence microscopy.
+#
+# Core Pipeline:
+#     1. Detection (detection.py)
+#     2. Lysosome counting (lyso_count.py)
+#     3. Morphology classification (morphology.py)
+#     4. Shape feature extraction (shape_features.py)
+#     5. Shape profiling (shape_profiling.py)
+#     6. Organelle tracking (tracking.py / tracking_overlay.py)
+#     7. Motility analysis (motility.py)
+#     8. Colocalization analysis (colocalization.py)
+#     9. Integrated summary (summary.py)
+#
+# Package structure follows:
+#     from automorphotrack import (
+#         detect_organelles,
+#         count_lysosomes_per_frame,
+#         classify_morphology,
+#         analyze_shape_features,
+#         profile_shape_data,
+#         track_organelles,
+#         track_overlay,
+#         analyze_motility,
+#         analyze_colocalization,
+#         summarize_integrated_data
+#     )
+# ============================================================
+
+__version__ = "1.0.0"
+__author__ = "Armin Bayati"
+
+# --- Utility Imports ---
+from automorphotrack.utils import (
+    ensure_dir,
+    save_high_dpi,
+    upscale_frame,
+    write_video
+)
+
+# --- Core Functional Imports ---
+from automorphotrack.detection import detect_organelles
+from automorphotrack.lyso_count import count_lysosomes_per_frame
+from automorphotrack.morphology import classify_morphology
+from automorphotrack.shape_features import analyze_shape_features
+from automorphotrack.shape_profiling import profile_shape_data
+from automorphotrack.tracking import track_organelles
+from automorphotrack.tracking_overlay import track_overlay
+from automorphotrack.motility import analyze_motility
+from automorphotrack.colocalization import analyze_colocalization
+from automorphotrack.summary import summarize_integrated_data
+
+# --- Convenience Alias (optional shortcut API) ---
+__all__ = [
+    "ensure_dir",
+    "save_high_dpi",
+    "upscale_frame",
+    "write_video",
+    "detect_organelles",
+    "count_lysosomes_per_frame",
+    "classify_morphology",
+    "analyze_shape_features",
+    "profile_shape_data",
+    "track_organelles",
+    "track_overlay",
+    "analyze_motility",
+    "analyze_colocalization",
+    "summarize_integrated_data"
+]

automorphotrack/colocalization.py

@@ -0,0 +1,128 @@
+# ============================================================
+# AutoMorphoTrack – Colocalization Analysis (Manders + Pearson)
+# ============================================================
+
+import tifffile, cv2, numpy as np, pandas as pd, matplotlib.pyplot as plt
+from skimage.filters import threshold_otsu
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, save_high_dpi
+
+def analyze_colocalization(
+    tif_path="Composite.tif",
+    mito_channel=0,
+    lyso_channel=1,
+    out_dir="Colocalization_Outputs",
+    fps=5,
+    upscale=2.0,
+    overlay_alpha=0.6):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(tif_path)
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for colocalization analysis")
+
+    # ---------- Helpers ----------
+    def upscale_frame(img):
+        h, w = img.shape[:2]
+        return cv2.resize(img, (int(w * upscale), int(h * upscale)), interpolation=cv2.INTER_CUBIC)
+
+    def write_video(frames, out_path, fps):
+        h, w = frames[0].shape[:2]
+        out = cv2.VideoWriter(str(out_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
+        for fr in frames:
+            out.write(cv2.cvtColor(fr, cv2.COLOR_RGB2BGR))
+        out.release()
+
+    frames_out = []
+    overlap_percent, m1_list, m2_list = [], [], []
+    pearson_r, overlap_R = [], []
+    mito_sum, lyso_sum = [], []
+
+    for f in range(n_frames):
+        mito = stack[f][..., mito_channel].astype(float)
+        lyso = stack[f][..., lyso_channel].astype(float)
+
+        # Background correction
+        mito -= np.percentile(mito, 5)
+        lyso -= np.percentile(lyso, 5)
+        mito, lyso = np.clip(mito, 0, None), np.clip(lyso, 0, None)
+
+        # Binary masks
+        thr_m, thr_l = threshold_otsu(mito), threshold_otsu(lyso)
+        mito_mask, lyso_mask = mito > thr_m, lyso > thr_l
+        overlap_mask, union_mask = mito_mask & lyso_mask, mito_mask | lyso_mask
+
+        # Metrics
+        overlap_ratio = (overlap_mask.sum() / union_mask.sum() * 100) if union_mask.sum() else 0
+        overlap_percent.append(overlap_ratio)
+        M1 = mito[lyso_mask].sum() / mito.sum() if mito.sum() > 0 else 0
+        M2 = lyso[mito_mask].sum() / lyso.sum() if lyso.sum() > 0 else 0
+        m1_list.append(M1)
+        m2_list.append(M2)
+
+        flat_m, flat_l = mito.flatten(), lyso.flatten()
+        if np.std(flat_m) > 0 and np.std(flat_l) > 0:
+            pearson_r.append(np.corrcoef(flat_m, flat_l)[0, 1])
+        else:
+            pearson_r.append(0)
+        denom = np.sqrt((mito**2).sum() * (lyso**2).sum())
+        overlap_R.append((mito * lyso).sum() / denom if denom > 0 else 0)
+
+        mito_sum.append(mito.sum())
+        lyso_sum.append(lyso.sum())
+
+        # Visualization with bright-blue overlay
+        mito_norm = (mito / mito.max() * 255).astype(np.uint8)
+        lyso_norm = (lyso / lyso.max() * 255).astype(np.uint8)
+        rgb = np.zeros((*mito.shape, 3), np.uint8)
+        rgb[..., 0], rgb[..., 1] = mito_norm, lyso_norm
+
+        mask = overlap_mask.astype(bool)
+        bright_blue_overlay = np.full_like(rgb[mask], (0, 150, 255), dtype=np.uint8)
+        rgb[mask] = cv2.addWeighted(rgb[mask], 1 - overlay_alpha, bright_blue_overlay, overlay_alpha, 0)
+
+        frames_out.append(upscale_frame(rgb))
+
+    # ---------- Save metrics ----------
+    csv_path = Path(out_dir) / "Colocalization.csv"
+    pd.DataFrame({
+        "Frame": np.arange(n_frames),
+        "Percent_Overlap": overlap_percent,
+        "Manders_M1": m1_list,
+        "Manders_M2": m2_list,
+        "Pearson_r": pearson_r,
+        "Overlap_R": overlap_R,
+        "Mito_TotalIntensity": mito_sum,
+        "Lyso_TotalIntensity": lyso_sum
+    }).to_csv(csv_path, index=False)
+    print(f"Saved metrics → {csv_path}")
+
+    # ---------- Save video ----------
+    video_path = Path(out_dir) / "Colocalization_BrightBlueOverlay.mp4"
+    write_video(frames_out, video_path, fps=fps)
+
+    # ---------- Save frame 0 still ----------
+    frame0_path = Path(out_dir) / "Colocalization_Frame0.png"
+    cv2.imwrite(str(frame0_path),
+                cv2.cvtColor(frames_out[0], cv2.COLOR_RGB2BGR),
+                [cv2.IMWRITE_PNG_COMPRESSION, 0])
+
+    # ---------- Plot metrics ----------
+    plot_path = Path(out_dir) / "Colocalization_MetricsPlot.png"
+    fig, ax = plt.subplots(figsize=(10, 9))
+    ax.plot(m1_list, 'r-', label='Manders M1 (mito→lyso)')
+    ax.plot(m2_list, 'g-', label='Manders M2 (lyso→mito)')
+    ax.plot(np.array(overlap_percent) / 100, 'b--', label='Overlap fraction')
+    ax.plot(pearson_r, 'k-.', label='Pearson r')
+    ax.plot(overlap_R, 'm:', label='Normalized R')
+    ax.set_xlabel("Frame")
+    ax.set_ylabel("Coefficient / Fraction (0–1)")
+    ax.set_ylim(0, 1)
+    ax.legend()
+    ax.set_title("Colocalization Metrics Over Time")
+    plt.tight_layout()
+    save_high_dpi(fig, plot_path)
+
+    print(f"Colocalization analysis complete — results saved in {Path(out_dir).resolve()}")

automorphotrack/detection.py

@@ -0,0 +1,65 @@
+# ============================================================
+# AutoMorphoTrack – Organelle Detection
+# ============================================================
+
+import tifffile, numpy as np, cv2
+from skimage.filters import threshold_otsu
+from skimage.morphology import remove_small_objects, binary_opening, disk
+from skimage.segmentation import clear_border
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, write_video, upscale_frame
+
+def detect_mask(frame, ch, thr_factor=0.8, min_size=3):
+    """Threshold and clean a single channel."""
+    img = frame[..., ch].astype(float)
+    img = (img - img.min()) / (img.ptp() + 1e-12)
+    thr = threshold_otsu(img) * thr_factor
+    mask = clear_border(binary_opening(img > thr, footprint=disk(1)))
+    mask = remove_small_objects(mask, min_size)
+    return (mask * 255).astype(np.uint8), img
+
+def detect_organelles(
+    tif_path="Composite.tif",
+    out_dir="Detection_Outputs",
+    mito_channel=0,
+    lyso_channel=1,
+    upscale_factor=2,
+    fps=5):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(str(tif_path))
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for detection")
+
+    mito_frames, lyso_frames = [], []
+
+    for f in range(n_frames):
+        # ----- Mitochondria (relaxed detection) -----
+        mito_mask, mito_img = detect_mask(stack[f], mito_channel, thr_factor=0.6, min_size=0.5)
+        mito_gray = (mito_img * 255).astype(np.uint8)
+        mito_rgb = cv2.cvtColor(mito_gray, cv2.COLOR_GRAY2RGB)
+        cnts, _ = cv2.findContours(mito_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        cv2.drawContours(mito_rgb, cnts, -1, (255, 0, 0), 1, cv2.LINE_AA)
+        mito_frames.append(upscale_frame(mito_rgb, upscale_factor))
+
+        # ----- Lysosomes (standard detection) -----
+        lyso_mask, lyso_img = detect_mask(stack[f], lyso_channel, thr_factor=0.8, min_size=2)
+        lyso_gray = (lyso_img * 255).astype(np.uint8)
+        lyso_rgb = cv2.cvtColor(lyso_gray, cv2.COLOR_GRAY2RGB)
+        cnts, _ = cv2.findContours(lyso_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        cv2.drawContours(lyso_rgb, cnts, -1, (0, 255, 0), 1, cv2.LINE_AA)
+        lyso_frames.append(upscale_frame(lyso_rgb, upscale_factor))
+
+    # Save representative frames
+    cv2.imwrite(str(Path(out_dir) / "Mito_Frame0.png"),
+                cv2.cvtColor(mito_frames[0], cv2.COLOR_RGB2BGR))
+    cv2.imwrite(str(Path(out_dir) / "Lyso_Frame0.png"),
+                cv2.cvtColor(lyso_frames[0], cv2.COLOR_RGB2BGR))
+
+    # Save videos
+    write_video(mito_frames, Path(out_dir) / "Mitochondria_Detection.mp4", fps=fps)
+    write_video(lyso_frames, Path(out_dir) / "Lysosomes_Detection.mp4", fps=fps)
+
+    print(f"Detection complete — outputs saved in {Path(out_dir).resolve()}")

automorphotrack/lyso_count.py

@@ -0,0 +1,84 @@
+# ============================================================
+# AutoMorphoTrack – Lysosomal Counting per Frame
+# ============================================================
+
+import tifffile, numpy as np, cv2, pandas as pd, matplotlib.pyplot as plt
+from skimage.filters import threshold_otsu
+from skimage.morphology import remove_small_objects, binary_opening, disk
+from skimage.segmentation import clear_border
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, write_video, upscale_frame
+
+def detect_mask(frame, ch, thr_factor=0.8, min_size=2):
+    """Detect lysosomes in a single channel frame."""
+    img = frame[..., ch].astype(float)
+    img = (img - img.min()) / (img.ptp() + 1e-12)
+    thr = threshold_otsu(img) * thr_factor
+    mask = clear_border(binary_opening(img > thr, footprint=disk(1)))
+    mask = remove_small_objects(mask, min_size)
+    return (mask * 255).astype(np.uint8), img
+
+def count_lysosomes_per_frame(
+    tif_path="Composite.tif",
+    out_dir="Lyso_Count_Outputs",
+    lyso_channel=1,
+    upscale_factor=2,
+    fps=5):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(str(tif_path))
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for lysosomal counting")
+
+    lyso_counts, lyso_frames = [], []
+
+    for f in range(n_frames):
+        lyso_mask, lyso_img = detect_mask(stack[f], lyso_channel, thr_factor=0.8, min_size=2)
+        cnts, _ = cv2.findContours(lyso_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        lyso_count = len(cnts)
+        lyso_counts.append({"Frame": f, "Lysosome_Count": lyso_count})
+
+        lyso_gray = (lyso_img * 255).astype(np.uint8)
+        lyso_rgb = cv2.cvtColor(lyso_gray, cv2.COLOR_GRAY2RGB)
+        cv2.drawContours(lyso_rgb, cnts, -1, (0, 255, 0), 1, cv2.LINE_AA)
+
+        # Add small green numbers at each lysosome position
+        for i, c in enumerate(cnts):
+            M = cv2.moments(c)
+            if M["m00"] != 0:
+                cx, cy = int(M["m10"] / M["m00"]), int(M["m01"] / M["m00"])
+                cv2.putText(lyso_rgb, str(i + 1), (cx, cy),
+                            cv2.FONT_HERSHEY_SIMPLEX, 0.35, (0, 255, 0), 1, cv2.LINE_AA)
+
+        # Add total count label in white (small font)
+        cv2.putText(lyso_rgb, f"Count: {lyso_count}", (10, 18),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.4, (255, 255, 255), 1, cv2.LINE_AA)
+
+        lyso_frames.append(upscale_frame(lyso_rgb, upscale_factor))
+
+    # Save representative frame
+    cv2.imwrite(str(Path(out_dir) / "Lyso_Frame0_Count.png"),
+                cv2.cvtColor(lyso_frames[0], cv2.COLOR_RGB2BGR))
+
+    # Save video
+    write_video(lyso_frames, Path(out_dir) / "Lyso_Count_Video.mp4", fps=fps)
+
+    # Save CSV
+    df = pd.DataFrame(lyso_counts)
+    csv_path = Path(out_dir) / "Lysosome_Counts.csv"
+    df.to_csv(csv_path, index=False)
+
+    # Plot counts over frames
+    plt.figure(figsize=(6, 4))
+    plt.plot(df["Frame"], df["Lysosome_Count"], "-o", color="green")
+    plt.xlabel("Frame")
+    plt.ylabel("Lysosome Count")
+    plt.title("Lysosome Count per Frame")
+    plt.grid(True, linestyle="--", alpha=0.5)
+    plt.tight_layout()
+    plt.savefig(Path(out_dir) / "Lyso_Count_Plot.png", dpi=200)
+    plt.close()
+
+    print(f"Lysosomal counting complete — outputs saved in {Path(out_dir).resolve()}")

automorphotrack/morphology.py

@@ -0,0 +1,140 @@
+# ============================================================
+# AutoMorphoTrack – Mitochondrial Morphology Classification
+# ============================================================
+
+import tifffile, numpy as np, cv2, matplotlib.pyplot as plt, pandas as pd
+from skimage.measure import regionprops, label
+from skimage.filters import threshold_otsu
+from skimage.morphology import remove_small_objects, binary_opening, disk
+from skimage.segmentation import clear_border
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, upscale_frame, save_high_dpi
+
+def detect_mask(frame, ch, thr_factor=0.8, min_size=10):
+    """Threshold a channel to obtain clean mitochondrial mask."""
+    img = frame[..., ch].astype(float)
+    img = (img - img.min()) / (img.ptp() + 1e-12)
+    thr = threshold_otsu(img) * thr_factor
+    mask = clear_border(binary_opening(img > thr, footprint=disk(1)))
+    mask = remove_small_objects(mask, min_size)
+    return (mask * 255).astype(np.uint8), img
+
+def draw_text_with_outline(img, text, pos, font_scale, color, thickness, outline_color):
+    x, y = int(pos[0]), int(pos[1])
+    cv2.putText(img, text, (x, y), cv2.FONT_HERSHEY_SIMPLEX,
+                font_scale, outline_color, thickness + 2, cv2.LINE_AA)
+    cv2.putText(img, text, (x, y), cv2.FONT_HERSHEY_SIMPLEX,
+                font_scale, color, thickness, cv2.LINE_AA)
+
+def classify_morphology(
+    tif_path="Composite.tif",
+    out_dir="Morphology_Outputs",
+    mito_channel=0,
+    area_thresh_elongated=0.12,
+    ecc_thresh_elongated=0.80,
+    area_thresh_punctate=0.03,
+    ecc_thresh_punctate=0.60,
+    upscale_factor=2,
+    fps=5):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(tif_path)
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    if stack.shape[-1] == 3:
+        stack = stack[..., :2]
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for morphology classification")
+
+    thr_stack, gray_stack = [], []
+    for f in range(n_frames):
+        m, g = detect_mask(stack[f], mito_channel)
+        thr_stack.append(m)
+        gray_stack.append(g)
+
+    results, summary_counts = [], []
+
+    for f in range(n_frames):
+        lbl = label(thr_stack[f])
+        props = regionprops(lbl, intensity_image=gray_stack[f])
+        frame_res = []
+        for p in props:
+            ecc, area = p.eccentricity, p.area
+            if area >= area_thresh_elongated and ecc >= ecc_thresh_elongated:
+                morph = "Elongated"
+            elif area >= area_thresh_punctate and ecc <= ecc_thresh_punctate:
+                morph = "Punctate"
+            else:
+                morph = "Intermediate"
+            frame_res.append({
+                "Frame": f,
+                "Label": p.label,
+                "Area": area,
+                "Eccentricity": ecc,
+                "Morphology": morph
+            })
+        results += frame_res
+        summary_counts.append({
+            "Frame": f,
+            "Elongated": sum(r["Morphology"] == "Elongated" for r in frame_res),
+            "Punctate": sum(r["Morphology"] == "Punctate" for r in frame_res)
+        })
+
+    # Save CSV outputs
+    pd.DataFrame(results).to_csv(Path(out_dir) / "Morphology_AllFrames.csv", index=False)
+    pd.DataFrame(summary_counts).to_csv(Path(out_dir) / "Morphology_Summary.csv", index=False)
+    print("Saved morphology classification CSVs")
+
+    # Visualization: E/P-labeled video and frame 0
+    video_frames = []
+    font_scale = 0.45
+    font_thickness = 1
+    font_color_E = (0, 255, 0)
+    font_color_P = (255, 255, 0)
+    outline_color = (0, 0, 0)
+
+    for f in range(n_frames):
+        mito_gray = gray_stack[f]
+        lbl = label(thr_stack[f])
+        props = regionprops(lbl, intensity_image=mito_gray)
+        base = (mito_gray * 255).astype(np.uint8)
+        base_rgb = cv2.cvtColor(base, cv2.COLOR_GRAY2BGR)
+        base_up = upscale_frame(base_rgb, upscale_factor)
+
+        elong_cnts, punct_cnts = [], []
+        for p in props:
+            cnt_mask = (lbl == p.label).astype(np.uint8)
+            cnts, _ = cv2.findContours(cnt_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+            for c in cnts:
+                c[:] *= upscale_factor
+                if p.eccentricity >= ecc_thresh_elongated:
+                    elong_cnts.append(c)
+                else:
+                    punct_cnts.append(c)
+
+        overlay = base_up.copy()
+        cv2.drawContours(overlay, elong_cnts, -1, font_color_E, 2, cv2.LINE_AA)
+        cv2.drawContours(overlay, punct_cnts, -1, font_color_P, 2, cv2.LINE_AA)
+
+        for p in props:
+            y, x = p.centroid
+            x, y = int(x * upscale_factor), int(y * upscale_factor)
+            morph = "E" if p.eccentricity >= ecc_thresh_elongated else "P"
+            col = font_color_E if morph == "E" else font_color_P
+            draw_text_with_outline(overlay, morph, (x, y),
+                                   font_scale, col, font_thickness, outline_color)
+
+        video_frames.append(cv2.cvtColor(overlay, cv2.COLOR_RGB2BGR))
+
+    # Write labeled video
+    video_path = Path(out_dir) / "Morphology_Labeled.mp4"
+    h, w = video_frames[0].shape[:2]
+    writer = cv2.VideoWriter(str(video_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
+    for fr in video_frames:
+        writer.write(fr)
+    writer.release()
+
+    # Save labeled frame 0 still
+    out_path = Path(out_dir) / "Morphology_Frame0_Labeled.png"
+    cv2.imwrite(str(out_path), cv2.cvtColor(video_frames[0], cv2.COLOR_RGB2BGR))
+    print(f"Morphology visualization saved → {out_path}")

automorphotrack/motility.py

@@ -0,0 +1,102 @@
+# ============================================================
+# AutoMorphoTrack – Motility Analysis
+# ============================================================
+
+import pandas as pd, numpy as np, matplotlib.pyplot as plt, seaborn as sns
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, save_high_dpi
+
+def analyze_motility(
+    mito_tracks_path="Tracking_Outputs/Mito_Tracks.csv",
+    lyso_tracks_path="Tracking_Outputs/Lyso_Tracks.csv",
+    out_dir="Motility_Outputs",
+    fps=5):
+
+    ensure_dir(out_dir)
+
+    # ---------- Load data ----------
+    mito_df = pd.read_csv(mito_tracks_path)
+    lyso_df = pd.read_csv(lyso_tracks_path)
+    print(f"Loaded {len(mito_df)} mitochondrial and {len(lyso_df)} lysosomal coordinates")
+
+    # ---------- Compute displacement & velocity ----------
+    def compute_motility(df, label):
+        df = df.sort_values(["Organelle", "Frame"])
+        df["DX"] = df.groupby("Organelle")["X"].diff()
+        df["DY"] = df.groupby("Organelle")["Y"].diff()
+        df["Displacement"] = np.sqrt(df["DX"]**2 + df["DY"]**2)
+        df["Velocity"] = df["Displacement"]
+
+        # Per-organelle summary
+        summary = (
+            df.groupby("Organelle")
+            .agg({
+                "Displacement": ["mean", "sum"],
+                "Velocity": "mean"
+            })
+            .reset_index()
+        )
+        summary.columns = ["Organelle", "Mean_Displacement",
+                           "Total_Displacement", "Mean_Velocity"]
+        summary["Organelle_Type"] = label
+
+        # Per-frame mean values
+        frame_summary = (
+            df.groupby("Frame")[["Displacement", "Velocity"]]
+            .mean()
+            .reset_index()
+            .rename(columns={
+                "Displacement": "Mean_Displacement",
+                "Velocity": "Mean_Velocity"
+            })
+        )
+        frame_summary["Organelle_Type"] = label
+        return df, summary, frame_summary
+
+    mito_full, mito_summary, mito_frame = compute_motility(mito_df, "Mitochondria")
+    lyso_full, lyso_summary, lyso_frame = compute_motility(lyso_df, "Lysosomes")
+
+    # ---------- Combine summaries ----------
+    combined_summary = pd.concat([mito_summary, lyso_summary], ignore_index=True)
+    combined_frame = pd.concat([mito_frame, lyso_frame], ignore_index=True)
+
+    # ---------- Save CSVs ----------
+    summary_csv = Path(out_dir) / "Motility_Summary.csv"
+    frame_csv = Path(out_dir) / "Motility_PerFrame.csv"
+    combined_summary.to_csv(summary_csv, index=False)
+    combined_frame.to_csv(frame_csv, index=False)
+
+    print(f"Saved organelle summary → {summary_csv}")
+    print(f"Saved per-frame summary → {frame_csv}")
+
+    # ---------- Distribution Plots ----------
+    fig, axes = plt.subplots(1, 2, figsize=(20, 8))
+    sns.kdeplot(mito_summary["Mean_Velocity"], color="red", fill=True, ax=axes[0], label="Mitochondria")
+    sns.kdeplot(lyso_summary["Mean_Velocity"], color="green", fill=True, alpha=0.4, ax=axes[0], label="Lysosomes")
+    axes[0].set_title("Mean Velocity Distribution")
+    axes[0].set_xlabel("Velocity (px/frame)")
+    axes[0].legend()
+
+    sns.kdeplot(mito_summary["Total_Displacement"], color="red", fill=True, ax=axes[1], label="Mitochondria")
+    sns.kdeplot(lyso_summary["Total_Displacement"], color="green", fill=True, alpha=0.4, ax=axes[1], label="Lysosomes")
+    axes[1].set_title("Total Displacement Distribution")
+    axes[1].set_xlabel("Displacement (px)")
+    axes[1].legend()
+
+    plt.tight_layout()
+    save_high_dpi(fig, Path(out_dir) / "Motility_Distributions.png")
+
+    # ---------- Scatter Plot ----------
+    fig, ax = plt.subplots(figsize=(12, 10))
+    sns.scatterplot(data=mito_summary, x="Total_Displacement", y="Mean_Velocity",
+                    color="red", s=30, label="Mitochondria")
+    sns.scatterplot(data=lyso_summary, x="Total_Displacement", y="Mean_Velocity",
+                    color="green", s=30, alpha=0.6, label="Lysosomes")
+    ax.set_xlabel("Total Displacement (px)")
+    ax.set_ylabel("Mean Velocity (px/frame)")
+    ax.set_title("Motility Scatter Plot")
+    ax.legend()
+    plt.tight_layout()
+    save_high_dpi(fig, Path(out_dir) / "Motility_Scatter.png")
+
+    print(f"Motility analysis complete — outputs saved in {Path(out_dir).resolve()}")

automorphotrack/shape_features.py

@@ -0,0 +1,100 @@
+# ============================================================
+# AutoMorphoTrack – Organelle Shape Feature Extraction
+# ============================================================
+
+import tifffile, numpy as np, pandas as pd, cv2, seaborn as sns, matplotlib.pyplot as plt
+from skimage.measure import regionprops, label
+from skimage.filters import threshold_otsu
+from skimage.morphology import remove_small_objects, binary_opening, disk
+from skimage.segmentation import clear_border
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, save_high_dpi, upscale_frame
+
+def detect_mask(frame, ch, min_size=3, thr_factor=0.8):
+    """Threshold and clean a single channel."""
+    img = frame[..., ch].astype(float)
+    img = (img - img.min()) / (img.ptp() + 1e-12)
+    thr = threshold_otsu(img) * thr_factor
+    mask = clear_border(binary_opening(img > thr, footprint=disk(1)))
+    mask = remove_small_objects(mask, min_size)
+    return (mask > 0).astype(np.uint8), img
+
+def analyze_shape_features(
+    tif_path="Composite.tif",
+    out_dir="Shape_Feature_Outputs",
+    mito_channel=0,
+    lyso_channel=1):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(tif_path)
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for shape feature extraction")
+
+    mito_records, lyso_records = [], []
+
+    for f in range(n_frames):
+        # ---------- Mitochondria ----------
+        mito_mask, mito_img = detect_mask(stack[f], mito_channel, min_size=5, thr_factor=0.85)
+        lbl_m = label(mito_mask)
+        for p in regionprops(lbl_m):
+            if p.area < 5:
+                continue
+            circ = (4 * np.pi * p.area) / (p.perimeter ** 2 + 1e-9)
+            aspect = p.major_axis_length / (p.minor_axis_length + 1e-9)
+            mito_records.append({
+                "Frame": f,
+                "Area": p.area,
+                "Eccentricity": p.eccentricity,
+                "Solidity": p.solidity,
+                "Circularity": circ,
+                "Aspect_Ratio": aspect,
+                "Orientation": p.orientation,
+            })
+
+        # ---------- Lysosomes ----------
+        lyso_mask, lyso_img = detect_mask(stack[f], lyso_channel, min_size=2, thr_factor=0.85)
+        lbl_l = label(lyso_mask)
+        for p in regionprops(lbl_l):
+            if p.area < 5:
+                continue
+            circ = (4 * np.pi * p.area) / (p.perimeter ** 2 + 1e-9)
+            aspect = p.major_axis_length / (p.minor_axis_length + 1e-9)
+            lyso_records.append({
+                "Frame": f,
+                "Area": p.area,
+                "Eccentricity": p.eccentricity,
+                "Solidity": p.solidity,
+                "Circularity": circ,
+                "Aspect_Ratio": aspect,
+                "Orientation": p.orientation,
+            })
+
+    mito_df = pd.DataFrame(mito_records)
+    lyso_df = pd.DataFrame(lyso_records)
+
+    mito_csv = Path(out_dir) / "Mito_ShapeMetrics.csv"
+    lyso_csv = Path(out_dir) / "Lyso_ShapeMetrics.csv"
+    mito_df.to_csv(mito_csv, index=False)
+    lyso_df.to_csv(lyso_csv, index=False)
+    print(f"Saved shape metrics for {len(mito_df)} mitochondria and {len(lyso_df)} lysosomes")
+
+    # ---------- KDE Distribution Plots ----------
+    fig, axes = plt.subplots(1, 2, figsize=(20, 8))
+    sns.kdeplot(mito_df["Circularity"], ax=axes[0], color="red", fill=True, alpha=0.5, label="Mito")
+    sns.kdeplot(lyso_df["Circularity"], ax=axes[0], color="green", fill=True, alpha=0.4, label="Lyso")
+    axes[0].set_title("Circularity Distribution")
+    axes[0].set_xlabel("Circularity (4πA/P²)")
+    axes[0].legend(frameon=False)
+
+    sns.kdeplot(mito_df["Solidity"], ax=axes[1], color="red", fill=True, alpha=0.5, label="Mito")
+    sns.kdeplot(lyso_df["Solidity"], ax=axes[1], color="green", fill=True, alpha=0.4, label="Lyso")
+    axes[1].set_title("Solidity Distribution")
+    axes[1].set_xlabel("Solidity")
+    axes[1].legend(frameon=False)
+
+    plt.tight_layout()
+    save_high_dpi(fig, Path(out_dir) / "Shape_Distributions.png")
+
+    print(f"Shape feature analysis complete — results saved in {Path(out_dir).resolve()}")

automorphotrack/shape_profiling.py

@@ -0,0 +1,51 @@
+# ============================================================
+# AutoMorphoTrack – Shape Profiling (Combined Organelle Metrics)
+# ============================================================
+
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+from pathlib import Path
+from automorphotrack.utils import ensure_dir, save_high_dpi
+
+def profile_shape_data(
+    mito_shape_path="Shape_Feature_Outputs/Mito_ShapeMetrics.csv",
+    lyso_shape_path="Shape_Feature_Outputs/Lyso_ShapeMetrics.csv",
+    out_dir="Shape_Profiling_Outputs"):
+
+    ensure_dir(out_dir)
+
+    # ---------- Load and label datasets ----------
+    mito_df = pd.read_csv(mito_shape_path).assign(Type="Mitochondria")
+    lyso_df = pd.read_csv(lyso_shape_path).assign(Type="Lysosomes")
+    combined_df = pd.concat([mito_df, lyso_df], ignore_index=True)
+
+    # ---------- Save combined CSV ----------
+    combined_csv_path = Path(out_dir) / "Combined_ShapeData.csv"
+    combined_df.to_csv(combined_csv_path, index=False)
+    print(f"Saved combined shape data CSV → {combined_csv_path}")
+
+    # ---------- Violin plots ----------
+    fig, axes = plt.subplots(1, 3, figsize=(30, 9))
+    metrics = ["Circularity", "Solidity", "Aspect_Ratio"]
+
+    for ax, metric in zip(axes, metrics):
+        sns.violinplot(
+            data=combined_df,
+            x="Type",
+            y=metric,
+            palette={"Mitochondria": "red", "Lysosomes": "green"},
+            cut=0,
+            inner="quartile",
+            ax=ax
+        )
+        ax.set_title(metric)
+        ax.set_xlabel("")
+        ax.set_ylabel(metric)
+        ax.grid(True, linestyle="--", alpha=0.5)
+
+    plt.tight_layout()
+    out_path = Path(out_dir) / "Shape_ViolinPlots.png"
+    save_high_dpi(fig, out_path)
+
+    print(f"Shape profiling complete — violin plots and combined CSV saved in {Path(out_dir).resolve()}")

automorphotrack/summary.py

@@ -0,0 +1,72 @@
+# ============================================================
+# AutoMorphoTrack – Integrated Summary and Correlation Analysis
+# ============================================================
+
+import pandas as pd, numpy as np, matplotlib.pyplot as plt, seaborn as sns
+from pathlib import Path
+from automorphotrack.utils import ensure_dir
+
+def summarize_integrated_data(
+    shape_metrics_path="Shape_Feature_Outputs/Mito_ShapeMetrics.csv",
+    motility_path="Motility_Outputs/Motility_PerFrame.csv",
+    colocalization_path="Colocalization_Outputs/Colocalization.csv",
+    out_dir="Summary_Outputs"):
+
+    print("Starting integrated summary analysis...")
+    ensure_dir(out_dir)
+
+    # ---------- Load data ----------
+    try:
+        shape_df = pd.read_csv(shape_metrics_path)
+        print(f"Loaded shape metrics ({len(shape_df)} rows)")
+        mot_df = pd.read_csv(motility_path)
+        print(f"Loaded motility data ({len(mot_df)} rows)")
+        col_df = pd.read_csv(colocalization_path)
+        print(f"Loaded colocalization data ({len(col_df)} rows)")
+    except Exception as e:
+        print("Error reading one of the input files:", e)
+        return None, None
+
+    # ---------- Aggregate by frame ----------
+    if "Frame" not in shape_df or "Frame" not in mot_df or "Frame" not in col_df:
+        print("Missing 'Frame' column in one or more input files.")
+        return None, None
+
+    shape_summary = shape_df.groupby("Frame").mean(numeric_only=True).reset_index()
+    print(f"Aggregated shape metrics into {len(shape_summary)} frames")
+
+    # ---------- Merge datasets ----------
+    merged = (
+        shape_summary
+        .merge(mot_df, on="Frame", how="inner")
+        .merge(col_df, on="Frame", how="inner")
+        .dropna()
+    )
+    print(f"Merged dataset dimensions: {merged.shape[0]} rows × {merged.shape[1]} columns")
+
+    # ---------- Correlation computation ----------
+    numeric_cols = merged.select_dtypes(include=[np.number])
+    corr = numeric_cols.corr().round(2)
+    print("Correlation matrix computed")
+
+    # ---------- Save results ----------
+    out_dir = Path(out_dir)
+    merged_csv = out_dir / "Integrated_Merged_Data.csv"
+    corr_csv = out_dir / "Integrated_CorrelationMatrix.csv"
+    merged.to_csv(merged_csv, index=False)
+    corr.to_csv(corr_csv)
+    print(f"Saved merged data → {merged_csv}")
+    print(f"Saved correlation matrix → {corr_csv}")
+
+    # ---------- Plot correlation heatmap ----------
+    fig, ax = plt.subplots(figsize=(28, 20))
+    sns.heatmap(corr, annot=True, fmt=".2f", cmap="coolwarm", square=True)
+    ax.set_title("Integrated Correlation Matrix – Shape, Motility, Colocalization", fontsize=14)
+    plt.tight_layout()
+    heatmap_path = out_dir / "Integrated_CorrelationMatrix.png"
+    plt.savefig(heatmap_path, dpi=300)
+    plt.close(fig)
+
+    print(f"Saved heatmap → {heatmap_path}")
+    print("Integrated summary analysis complete.")
+    return merged, corr

automorphotrack/tracking.py

@@ -0,0 +1,121 @@
+# ============================================================
+# AutoMorphoTrack – Organelle Tracking (Cumulative Paths)
+# ============================================================
+
+import numpy as np, cv2, pandas as pd, tifffile
+from pathlib import Path
+from scipy.spatial import cKDTree
+from skimage.measure import label, regionprops
+from automorphotrack.utils import ensure_dir, write_video, upscale_frame
+from automorphotrack.shape_features import detect_mask
+
+def track_organelles(
+    tif_path="Composite.tif",
+    out_dir="Tracking_Outputs",
+    mito_channel=0,
+    lyso_channel=1,
+    fps=5,
+    max_dist=15):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(tif_path)
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for organelle tracking")
+
+    # ---------- Helper functions ----------
+    def get_centroids(mask):
+        lbl = label(mask)
+        return np.array([p.centroid for p in regionprops(lbl)]) if lbl.max() > 0 else np.empty((0, 2))
+
+    def nearest_neighbor(prev, curr, max_dist=15):
+        if len(prev) == 0 or len(curr) == 0:
+            return {}
+        tree = cKDTree(curr)
+        dists, idx = tree.query(prev, distance_upper_bound=max_dist)
+        return {i: j for i, j in enumerate(idx) if j < len(curr)}
+
+    mito_tracks, lyso_tracks = [], []
+    mito_data, lyso_data = [], []
+
+    # ---------- Collect centroids per frame ----------
+    for f in range(n_frames):
+        mito_mask, _ = detect_mask(stack[f], mito_channel, min_size=2, thr_factor=0.65)
+        lyso_mask, _ = detect_mask(stack[f], lyso_channel, min_size=2, thr_factor=0.85)
+
+        mito_curr = get_centroids(mito_mask)
+        lyso_curr = get_centroids(lyso_mask)
+        mito_tracks.append(mito_curr)
+        lyso_tracks.append(lyso_curr)
+
+        for i, (y, x) in enumerate(mito_curr):
+            mito_data.append([f, i, x, y])
+        for i, (y, x) in enumerate(lyso_curr):
+            lyso_data.append([f, i, x, y])
+
+    # ---------- Save centroid coordinates ----------
+    df_mito = pd.DataFrame(mito_data, columns=["Frame", "Organelle", "X", "Y"])
+    df_lyso = pd.DataFrame(lyso_data, columns=["Frame", "Organelle", "X", "Y"])
+    df_mito.to_csv(Path(out_dir) / "Mito_Tracks.csv", index=False)
+    df_lyso.to_csv(Path(out_dir) / "Lyso_Tracks.csv", index=False)
+
+    # ---------- Compute displacement and velocity ----------
+    def compute_disp_vel(df):
+        disps, vels = [], []
+        for oid in df["Organelle"].unique():
+            sub = df[df["Organelle"] == oid].sort_values("Frame")
+            if len(sub) > 1:
+                dx, dy = np.diff(sub["X"]), np.diff(sub["Y"])
+                disp = np.sqrt(dx ** 2 + dy ** 2)
+                disps.append([oid, disp.sum()])
+                vels.append([oid, disp.mean() * fps])
+        return (pd.DataFrame(disps, columns=["Organelle", "Total_Displacement"]),
+                pd.DataFrame(vels, columns=["Organelle", "Mean_Velocity"]))
+
+    mito_disp, mito_vel = compute_disp_vel(df_mito)
+    lyso_disp, lyso_vel = compute_disp_vel(df_lyso)
+
+    mito_disp.to_csv(Path(out_dir) / "Mito_Displacement.csv", index=False)
+    mito_vel.to_csv(Path(out_dir) / "Mito_Velocity.csv", index=False)
+    lyso_disp.to_csv(Path(out_dir) / "Lyso_Displacement.csv", index=False)
+    lyso_vel.to_csv(Path(out_dir) / "Lyso_Velocity.csv", index=False)
+
+    # ---------- Build cumulative frames ----------
+    mito_paths, lyso_paths = [], []
+    mito_frames, lyso_frames, composite_frames = [], [], []
+
+    for f in range(n_frames):
+        frame_rgb = np.zeros_like(stack[f][..., :3])
+        if f > 0:
+            if len(mito_tracks[f - 1]) and len(mito_tracks[f]):
+                for k, v in nearest_neighbor(mito_tracks[f - 1], mito_tracks[f], max_dist).items():
+                    mito_paths.append((mito_tracks[f - 1][k], mito_tracks[f][v]))
+            if len(lyso_tracks[f - 1]) and len(lyso_tracks[f]):
+                for k, v in nearest_neighbor(lyso_tracks[f - 1], lyso_tracks[f], max_dist).items():
+                    lyso_paths.append((lyso_tracks[f - 1][k], lyso_tracks[f][v]))
+
+        mito_frame, lyso_frame, comp_frame = frame_rgb.copy(), frame_rgb.copy(), frame_rgb.copy()
+
+        for p1, p2 in mito_paths:
+            cv2.line(mito_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])), (255, 0, 0), 1)
+            cv2.line(comp_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])), (255, 0, 0), 1)
+        for p1, p2 in lyso_paths:
+            cv2.line(lyso_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])), (0, 255, 0), 1)
+            cv2.line(comp_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])), (0, 255, 0), 1)
+
+        mito_frames.append(upscale_frame(mito_frame))
+        lyso_frames.append(upscale_frame(lyso_frame))
+        composite_frames.append(upscale_frame(comp_frame))
+
+    # ---------- Save videos ----------
+    write_video(mito_frames, Path(out_dir) / "Mito_CumulativeTracks.mp4", fps=fps)
+    write_video(lyso_frames, Path(out_dir) / "Lyso_CumulativeTracks.mp4", fps=fps)
+    write_video(composite_frames, Path(out_dir) / "Composite_CumulativeTracks.mp4", fps=fps)
+
+    # ---------- Save final stills ----------
+    cv2.imwrite(str(Path(out_dir) / "Cumulative_Mito.png"), cv2.cvtColor(mito_frames[-1], cv2.COLOR_RGB2BGR))
+    cv2.imwrite(str(Path(out_dir) / "Cumulative_Lyso.png"), cv2.cvtColor(lyso_frames[-1], cv2.COLOR_RGB2BGR))
+    cv2.imwrite(str(Path(out_dir) / "Cumulative_Composite.png"), cv2.cvtColor(composite_frames[-1], cv2.COLOR_RGB2BGR))
+
+    print(f"Tracking complete — outputs saved in {Path(out_dir).resolve()}")

automorphotrack/tracking_overlay.py

@@ -0,0 +1,123 @@
+# ============================================================
+# AutoMorphoTrack – Organelle Tracking with Real-Intensity Overlays
+# ============================================================
+
+import numpy as np, cv2, tifffile
+from pathlib import Path
+from skimage.measure import label, regionprops
+from scipy.spatial import cKDTree
+from automorphotrack.utils import ensure_dir
+from automorphotrack.shape_features import detect_mask
+
+def track_overlay(
+    tif_path="Composite.tif",
+    out_dir="TrackingOverlay_Outputs",
+    mito_channel=0,
+    lyso_channel=1,
+    fps=10,
+    upscale=2.0,
+    line_thickness=1):
+
+    ensure_dir(out_dir)
+    stack = tifffile.imread(tif_path)
+    if stack.ndim == 3:
+        stack = stack[..., np.newaxis]
+    if stack.shape[1] == 3 and stack.shape[-1] != 3:
+        stack = np.moveaxis(stack, 1, -1)
+    n_frames = stack.shape[0]
+    print(f"Loaded {n_frames} frames for tracking overlays")
+
+    # ---------- Helper functions ----------
+    def get_centroids(mask):
+        lbl = label(mask)
+        return np.array([p.centroid for p in regionprops(lbl)]) if lbl.max() > 0 else np.empty((0, 2))
+
+    def nearest_neighbor(prev, curr, max_dist=15):
+        if len(prev) == 0 or len(curr) == 0:
+            return {}
+        tree = cKDTree(curr)
+        dists, idx = tree.query(prev, distance_upper_bound=max_dist)
+        return {i: j for i, j in enumerate(idx) if j < len(curr)}
+
+    def upscale_frame(img):
+        h, w = img.shape[:2]
+        return cv2.resize(img, (int(w * upscale), int(h * upscale)), interpolation=cv2.INTER_CUBIC)
+
+    def write_video(frames, out_path, fps):
+        h, w = frames[0].shape[:2]
+        out = cv2.VideoWriter(str(out_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
+        for fr in frames:
+            out.write(cv2.cvtColor(fr, cv2.COLOR_RGB2BGR))
+        out.release()
+
+    # ---------- Extract centroid tracks ----------
+    mito_tracks, lyso_tracks = [], []
+    for f in range(n_frames):
+        mito_mask, _ = detect_mask(stack[f], mito_channel, min_size=2, thr_factor=0.65)
+        lyso_mask, _ = detect_mask(stack[f], lyso_channel, min_size=2, thr_factor=0.85)
+        mito_tracks.append(get_centroids(mito_mask))
+        lyso_tracks.append(get_centroids(lyso_mask))
+
+    # ---------- Build cumulative trajectory frames ----------
+    mito_paths, lyso_paths = [], []
+    mito_frames, lyso_frames, composite_frames = [], [], []
+
+    for f in range(n_frames):
+        mito_mask, _ = detect_mask(stack[f], mito_channel, min_size=2, thr_factor=0.65)
+        lyso_mask, _ = detect_mask(stack[f], lyso_channel, min_size=2, thr_factor=0.85)
+
+        mito_img = stack[f, :, :, mito_channel]
+        lyso_img = stack[f, :, :, lyso_channel]
+
+        mito_norm = cv2.normalize(mito_img, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
+        lyso_norm = cv2.normalize(lyso_img, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
+
+        mito_base = cv2.cvtColor(mito_norm, cv2.COLOR_GRAY2RGB)
+        lyso_base = cv2.cvtColor(lyso_norm, cv2.COLOR_GRAY2RGB)
+        comp_merge = np.clip(mito_norm * 0.5 + lyso_norm * 0.5, 0, 255).astype(np.uint8)
+        comp_base = cv2.cvtColor(comp_merge, cv2.COLOR_GRAY2RGB)
+
+        if f > 0:
+            prev_m, curr_m = mito_tracks[f - 1], mito_tracks[f]
+            prev_l, curr_l = lyso_tracks[f - 1], lyso_tracks[f]
+            if len(prev_m) and len(curr_m):
+                nn = nearest_neighbor(prev_m, curr_m)
+                for k, v in nn.items():
+                    mito_paths.append((prev_m[k], curr_m[v]))
+            if len(prev_l) and len(curr_l):
+                nn = nearest_neighbor(prev_l, curr_l)
+                for k, v in nn.items():
+                    lyso_paths.append((prev_l[k], curr_l[v]))
+
+        mito_frame = mito_base.copy()
+        lyso_frame = lyso_base.copy()
+        comp_frame = comp_base.copy()
+
+        for p1, p2 in mito_paths:
+            cv2.line(mito_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])),
+                     (255, 0, 0), line_thickness, cv2.LINE_AA)
+            cv2.line(comp_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])),
+                     (255, 0, 0), line_thickness, cv2.LINE_AA)
+        for p1, p2 in lyso_paths:
+            cv2.line(lyso_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])),
+                     (0, 255, 0), line_thickness, cv2.LINE_AA)
+            cv2.line(comp_frame, tuple(np.int32(p1[::-1])), tuple(np.int32(p2[::-1])),
+                     (0, 255, 0), line_thickness, cv2.LINE_AA)
+
+        mito_frames.append(upscale_frame(mito_frame))
+        lyso_frames.append(upscale_frame(lyso_frame))
+        composite_frames.append(upscale_frame(comp_frame))
+
+    # ---------- Save outputs ----------
+    write_video(mito_frames, Path(out_dir) / "Mito_CumulativeTracks.mp4", fps=fps)
+    write_video(lyso_frames, Path(out_dir) / "Lyso_CumulativeTracks.mp4", fps=fps)
+    write_video(composite_frames, Path(out_dir) / "Composite_CumulativeTracks.mp4", fps=fps)
+
+    for name, frames in zip(["Mito", "Lyso", "Composite"],
+                             [mito_frames, lyso_frames, composite_frames]):
+        out_path = Path(out_dir) / f"Cumulative_{name}.png"
+        cv2.imwrite(str(out_path),
+                    cv2.cvtColor(frames[-1], cv2.COLOR_RGB2BGR),
+                    [cv2.IMWRITE_PNG_COMPRESSION, 0])
+
+    print(f"Tracking overlay complete — results saved in {Path(out_dir).resolve()}")

automorphotrack/utils.py

@@ -0,0 +1,37 @@
+# ============================================================
+# AutoMorphoTrack Utilities
+# ============================================================
+
+import os
+from pathlib import Path
+import cv2
+import numpy as np
+import matplotlib.pyplot as plt
+
+def ensure_dir(path):
+    """Create directory if missing."""
+    Path(path).mkdir(parents=True, exist_ok=True)
+
+def save_high_dpi(fig, path, dpi=600):
+    """Save Matplotlib figure with high resolution."""
+    fig.savefig(path, dpi=dpi, bbox_inches="tight")
+    plt.close(fig)
+    print(f"Saved figure: {path}")
+
+def upscale_frame(img, scale=2):
+    """Upscale an image for high-quality visualization."""
+    h, w = img.shape[:2]
+    return cv2.resize(img, (w*scale, h*scale), interpolation=cv2.INTER_CUBIC)
+
+def write_video(frames, path, fps=5):
+    """Write RGB frames into an MP4 video."""
+    if not frames:
+        print("No frames provided for video.")
+        return
+    h, w = frames[0].shape[:2]
+    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+    out = cv2.VideoWriter(str(path), fourcc, fps, (w, h))
+    for fr in frames:
+        out.write(cv2.cvtColor(fr.astype(np.uint8), cv2.COLOR_RGB2BGR))
+    out.release()
+    print(f"Saved video: {path}")