{"id":28230437,"url":"https://github.com/unikill066/xenium_cell_segmentation","last_synced_at":"2025-06-22T06:08:13.176Z","repository":{"id":289777622,"uuid":"970890425","full_name":"unikill066/xenium_cell_segmentation","owner":"unikill066","description":"End-to-end pipeline for spinal-cord microscopy segmentation with Cellpose, tiling, and mask stitching.","archived":false,"fork":false,"pushed_at":"2025-06-13T04:15:17.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T04:34:09.073Z","etag":null,"topics":["cell-segmentation","cellpose","cellpose-segmentation","xenium"],"latest_commit_sha":null,"homepage":"https://www.nature.com/articles/s41592-025-02595-5","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unikill066.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-22T17:33:01.000Z","updated_at":"2025-06-13T04:15:21.000Z","dependencies_parsed_at":"2025-06-13T04:44:22.379Z","dependency_job_id":null,"html_url":"https://github.com/unikill066/xenium_cell_segmentation","commit_stats":null,"previous_names":["unikill066/spinal_cord_segmentation","unikill066/spinal_cord_cell_segmentation","unikill066/xenium_cell_segmentation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/unikill066/xenium_cell_segmentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikill066%2Fxenium_cell_segmentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikill066%2Fxenium_cell_segmentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikill066%2Fxenium_cell_segmentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikill066%2Fxenium_cell_segmentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unikill066","download_url":"https://codeload.github.com/unikill066/xenium_cell_segmentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikill066%2Fxenium_cell_segmentation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259845447,"owners_count":22920743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cell-segmentation","cellpose","cellpose-segmentation","xenium"],"created_at":"2025-05-18T17:14:49.540Z","updated_at":"2025-06-14T16:30:58.418Z","avatar_url":"https://github.com/unikill066.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xenium Cell Segmentation Pipeline\n\n![Python](https://img.shields.io/badge/python-3.8%2B-blue?logo=python)\n![License](https://img.shields.io/github/license/unikill066/xenium_cell_segmentation)\n[![hugging face](https://huggingface.co/datasets/huggingface/badges/resolve/main/model-on-hf-md.svg)](https://huggingface.co/unikill066/drg_cellpose_sam_model)\n\n\n**End‑to‑end pipeline for segmenting spinal‑cord microscopy images using [Cellpose](https://github.com/MouseLand/cellpose).**\n\n\u003e Drag‑and‑drop GUI (Streamlit) • Headless CLI • Custom training workflow\n\n## Table of Contents\n\n* [Why this repo?](#why-this-repo)\n* [Quick Start (TL;DR)](#quick-start-tldr)\n* [Installation](#installation)\n* [Downloading Pre‑trained Weights](#downloading-pre-trained-weights)\n* [Configuring Paths \u0026 Parameters](#configuring-paths--parameters)\n* [Running the Pipeline](#running-the-pipeline)\n\n  * [Command‑line](#command-line)\n  * [Streamlit App](#streamlit-app)\n* [Training on Your Own Data](#training-on-your-own-data)\n* [Directory Structure](#directory-structure)\n* [Troubleshooting \u0026 FAQ](#troubleshooting--faq)\n* [Citing](#citing)\n* [License](#license)\n\n## Why this repo?\n\n- This repository provides a turn‑key workflow for turning raw histological slides of the Xenium Data (TIFF) into high‑quality, full‑resolution segmentation masks. \n\n- Huge TIFF slides (\u003e40k × 40k px) do not fit into GPU memory. This repo scaled down, breaks them into tiles, runs a pre-trained Cellpose-SAM model in parallel, then stitches the probability masks back together.\n\n- The same code powers a drag‑and‑drop Streamlit interface for bench scientists and a fully scriptable CLI for batch jobs.\n\n## Quick Start (TL;DR)\n\n```bash\n# 1. Clone \u0026 install\ngit clone https://github.com/unikill066/xenium_cell_segmentation.git\ncd xenium_cell_segmentation\npip install -r requirements.txt\n\n# 2. Put your slide(s) in ./data/input\n# 3. Download the model weights from huggingface/box and copy it to ./model/ model directory (see below)\n# 4. Edit utils/constants.py, with model path and config path \n# 5. Run the pipeline\npython main.py\n```\n## Quick Demo\n[![Launch Demo](https://img.shields.io/badge/Launch-Demo-red?style=for-the-badge\u0026logo=streamlit\u0026logoColor=white)](demo/xenium_seg_cellposesam_demo.mp4)\n\n\n\n## Installation\n\n### Python environment\n\n* Python ≥ 3.8\n* (Optional) CUDA‑enabled PyTorch for GPU speed‑ups\n  *Tested on CUDA 12.1 + RTX A5000.*\n\n```bash\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\n```\n\n### System packages\n\n| Dependency | Debian / Ubuntu                       | macOS (brew)           |\n| ---------- | ------------------------------------- | ---------------------- |\n| OpenCV     | `sudo apt-get install python3-opencv` | `brew install opencv`  |\n| Tiff       | `sudo apt-get install libtiff-dev`    | `brew install libtiff` |\n\nOverride any parameter at the CLI with `--param=value`. See `python main.py --help`.\n\n## Running the Pipeline\n\n### Command‑line\n\n```bash\npython main.py\n```\n\n### Streamlit App\n\n```bash\nstreamlit run streamlit_app.py\n```\n\n1. Drag a `.tif` (or folder) onto the **Upload** panel.\n2. Tune tile size \u0026 model on the sidebar.\n3. Click **Run segmentation** – outputs stream to `data/output/`.\n\nThe app supports one upload at a time; progress bars updates live. More on the steps that go into the pipeline can be found here: \u003cp align=\"left\"\u003e\n  \u003ca href=\"docs/step_process.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Step–by–Step-Docs-blue?style=for-the-badge\" alt=\"Step-by-Step Docs\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n## Training on Your Own Data\n\n1. **Annotate** nuclei or whole cells in **QuPath**\n\n   * Export objects as **GeoJSON** (`File › Object data › Export as GeoJSON`).\n   * Export the corresponding raw slide as an **OME‑TIFF**.\n\n2. **Generate training patches**\n\n   ```bash\n   python generate_training_data.py\n   ```\n\n3. **Fine‑tune Cellpose** (`cellpose/train.py`). Example:\n\n   ```python\n   python -m bin/train_cellpose_sam.py\n   ```\n\n   \u003e Note: Make sure to update the constants in `train_dir` and `model_name` in`bin/train_cellpose_sam.py`.\n\n4. Update `MODEL_PATH` and re‑run inference.\n   For hyper‑parameter suggestions see the [Cellpose docs](https://cellpose.readthedocs.io).\n\n   \u003e Note: Download and copy this model to models directory.\n   \u003e \n   \u003e Model weights are uploaded to Hugging Face: [DRG Cellpose-SAM Model](https://huggingface.co/unikill066/drg_cellpose_sam_model)\n\n## Directory Structure\n\n```\nxenium_cell_segmentation/\n├── bin/           # one‑shot utility scripts for training a new cellpose / cellpose-sam models\n├── model/         # pre‑trained \u0026 fine‑tuned weights\n├── utils/         # reusable helpers (tiling, stitching, viz, etc.)\n├── notebooks/     # jupyter demos and exploratory analysis\n├── docs/          # extra figures \u0026 extended docs\n├── data/          # auto‑generated at runtime\n│   ├── input/     # raw slides (.tif)\n│   ├── tiles/     # png tiles fed to cellpose\n│   ├── masks/     # per‑tile masks\n│   └── output/    # stitched full‑res masks\n└── streamlit_app.py\n```\n\nAdditional Documentation:\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"docs/xenium_cell_segmentation.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Xenium–Cell–Segmentation-Docs-blue?style=for-the-badge\" alt=\"Xenium Cell Segmentation Docs\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n## Troubleshooting \u0026 FAQ\n\n| Symptom                                | Fix                                                              |\n| -------------------------------------- | ---------------------------------------------------------------- |\n| **OOM on GPU**                         | Lower `--tile_px`, increase overlap.                             |\n| **No masks produced**                  | Check contrast / staining; try `--net_avg=False` with Cellpose.  |\n| **Streamlit app upload fails \u003e200 MB** | Increase `server.maxUploadSize` in `~/.streamlit/config.toml`.   |\n| **GeoJSON mis‑aligned with slide**     | Verify that QuPath export uses *Entire Image* coordinate system. |\n\n## Citing\n\nIf you use this code, please cite:\n\n```\n@article{Stringer_2025_Cellpose-SAM,\n  title={Cellpose-SAM: how to train your own model},\n  author={Stringer, Carsen and Pachitariu, Marius},\n  journal={Nat. Methods},\n  year={2025}\n}\n```\n[Cellpose-SAM paper](https://www.biorxiv.org/content/10.1101/2025.04.28.651001v1): Pachitariu, M., Rariden, M., \u0026 Stringer, C. (2025). Cellpose-SAM: superhuman generalization for cellular segmentation. bioRxiv.\n\n## License\n\nThis project is licensed under the MIT License – see `LICENSE` for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikill066%2Fxenium_cell_segmentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funikill066%2Fxenium_cell_segmentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikill066%2Fxenium_cell_segmentation/lists"}