Metadata-Version: 2.4
Name: neuro-sam
Version: 0.1.18
Summary: Neuro-SAM: Foundation Model for Dendrite and Dendritic Spine Segmentation
Author-email: Nipun Arora <nipunarora8@yahoo.com>
License: MIT
Project-URL: Homepage, https://github.com/nipunarora8/Neuro-SAM
Project-URL: Bug Tracker, https://github.com/nipunarora8/Neuro-SAM/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: napari
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: napari
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: imageio
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision>=0.15.0
Requires-Dist: hydra-core>=1.3.2
Requires-Dist: iopath>=0.1.10
Requires-Dist: pillow>=9.4.0
Requires-Dist: tqdm>=4.66.1
Requires-Dist: vispy
Requires-Dist: qtpy
Requires-Dist: superqt
Requires-Dist: magicgui
Requires-Dist: scikit-image
Requires-Dist: tifffile
Requires-Dist: numba
Requires-Dist: PyQt5
Requires-Dist: opencv-python-headless
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: flammkuchen
Requires-Dist: albumentations
Requires-Dist: wandb
Requires-Dist: tensorflow
Requires-Dist: imagecodecs

<div align="center">

# Neuro-SAM
#### Foundation Model for Dendrite and Dendritic Spine Segmentation

</div>

Neuro-SAM is a napari plugin for analysing dendritic morphology in 3D fluorescence microscopy stacks. It enables you to:

- Trace individual dendrites in a 3D volume using waypoint-guided brightest-path search
- Segment traced dendrites using a fine-tuned SAM2 model
- Detect dendritic spines along each traced path
- Segment individual spines using a dedicated fine-tuned SAM2 model

Neuro-SAM works across imaging modalities including two-photon, confocal, and STED microscopy.

---

### 🚀 Installation

Neuro-SAM requires **Python 3.10+**. We recommend using Conda/Miniconda for environment management.

```bash
pip install neuro-sam
```

Models are downloaded automatically on first use and stored in `src/neuro_sam/checkpoints/` — easy to find and delete.

To pre-download all models and the sample dataset:

```bash
neuro-sam-download
```

GPU acceleration is supported via **CUDA** and **MPS** (Apple Silicon).

---

### 📊 Usage

```bash
# Launch with the built-in benchmark dataset
neuro-sam

# Launch with your own dataset
neuro-sam --image-path /path/to/your/image.tif
```

---

### 🗃 Repository Structure

```
src/neuro_sam/
├── checkpoints/          # model weights (auto-downloaded on first use)
├── napari_utils/         # UI widgets and inference modules
│   ├── main_widget.py          # top-level plugin widget
│   ├── path_tracing_module.py  # waypoint path tracing
│   ├── segmentation_module.py  # dendrite segmentation
│   ├── segmentation_model.py   # SAM2 dendrite model wrapper
│   ├── spine_detection_module.py     # spine detection
│   ├── spine_segmentation_module.py  # spine segmentation UI
│   ├── spine_segmentation_model.py   # SAM2 spine model wrapper
│   └── anisotropic_scaling.py  # voxel spacing / scaling
├── brightest_path_lib/   # waypoint A* path tracing algorithm
├── training/             # training scripts for fine-tuning
├── plugin.py             # napari entry point
└── utils.py              # model download and shared utilities
```

---

### 🔬 Workflow

#### 1. Configure Voxel Spacing
In the **Path Tracing** tab, set accurate X, Y, Z voxel spacing (nm) for your acquisition. This ensures correct anisotropic scaling throughout the pipeline.

#### 2. Trace Dendritic Paths
- Click waypoints along dendrite structures in the viewer
- Use **Load Dataset** to switch datasets without restarting
- The algorithm finds the optimal brightest path between waypoints

#### 3. Segment Dendrites
- Go to the **Segmentation** tab
- Load the pre-trained SAM2 dendrite model
- Run segmentation on individual traced paths

#### 4. Detect Spines
- Go to the **Spine Detection** tab
- Select a segmented path
- Run automatic spine detection using tubular view analysis

#### 5. Segment Spines
- Go to the **Spine Segmentation** tab
- Load the pre-trained SAM2 spine model
- Run spine segmentation on detected spine positions
- Export spine masks as TIFF files

---

### 🗂 Models

| Model | Description |
|---|---|
| `sam2.1_hiera_small.pt` | SAM2 base checkpoint |
| `dendrite_model.torch` | Fine-tuned weights for dendrite segmentation |
| `spine_model.torch` | Fine-tuned weights for spine segmentation |

All models are downloaded from the [GitHub release](https://github.com/nipunarora8/Neuro-SAM/releases/tag/weights) on first use.

---

### 📬 Contact

- Nipun Arora — nipunarora8@yahoo.com

<div align="center">
<b>Made with ♥️ at <a href='https://anki.xyz'>Anki Lab</a> 🧠✨</b>
</div>
