adding paper code and updating readme

Author: carsen-stringer

.github/workflows/test_and_deploy.yml

@@ -43,28 +43,28 @@ jobs:
       - name: Coverage
         uses: codecov/codecov-action@v4
 
-  # deploy:
-  #   # this will run when you have tagged a commit, starting with "v*"
-  #   # and requires that you have put your twine API key in your 
-  #   # github secrets (see readme for details)
-  #   needs: [test]
-  #   runs-on: ubuntu-latest
-  #   if: contains(github.ref, 'tags')
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #     - name: Set up Python
-  #       uses: actions/setup-python@v4
-  #       with:
-  #         python-version: "3.x"
-  #     - name: Install dependencies
-  #       run: |
-  #         python -m pip install --upgrade pip
-  #         pip install -U setuptools setuptools_scm wheel twine
-  #     - name: Build and publish
-  #       env:
-  #         TWINE_USERNAME: __token__
-  #         TWINE_PASSWORD: ${{ secrets.TWINE_API_KEY }}
-  #       run: |
-  #         git tag
-  #         python setup.py sdist bdist_wheel
-  #         twine upload dist/*
+  deploy:
+    # this will run when you have tagged a commit, starting with "v*"
+    # and requires that you have put your twine API key in your 
+    # github secrets (see readme for details)
+    needs: [test]
+    runs-on: ubuntu-latest
+    if: contains(github.ref, 'tags')
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U setuptools setuptools_scm wheel twine
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TWINE_API_KEY }}
+        run: |
+          git tag
+          python setup.py sdist bdist_wheel
+          twine upload dist/*

README.md

@@ -16,23 +16,25 @@
 [![GitHub stars](https://img.shields.io/github/stars/MouseLand/cellpose?style=social)](https://github.com/MouseLand/cellpose/)
 [![GitHub forks](https://img.shields.io/github/forks/MouseLand/cellpose?style=social)](https://github.com/MouseLand/cellpose/)
 
-A generalist algorithm for cell and nucleus segmentation (v1.0) that can be optimized for your own data (v2.0) and (**NEW**) perform image restoration (v3.0).
+**Cellpose-SAM: cell and nucleus segmentation with superhuman generalization. It can be optimized for your own data, applied in 3D, works on noisy and blurry images.**
 
-Cellpose was written by Carsen Stringer and Marius Pachitariu. To learn about Cellpose3 (image restoration), read the [paper](https://www.nature.com/articles/s41592-025-02595-5) or watch the [talk](https://youtu.be/TZZZlGk6AKo). To learn about Cellpose 2.0 (human-in-the-loop), read the [paper](https://www.nature.com/articles/s41592-022-01663-4) or watch the [talk](https://www.youtube.com/watch?v=3ydtAhfq6H0). To learn about Cellpose 1.0, read the [paper](https://t.co/kBMXmPp3Yn?amp=1) or watch the [talk](https://t.co/JChCsTD0SK?amp=1). For support, please open an [issue](https://github.com/MouseLand/cellpose/issues). 
+To learn about Cellpose-SAM read the [paper](https://www.biorxiv.org/content/10.1101/2025.04.28.651001v1) or watch the [talk](https://t.co/JChCsTD0SK?amp=1). For info on fine-tuning a model, watch this [tutorial talk](https://youtu.be/5qANHWoubZU), and see this example [video](https://youtu.be/3Y1VKcxjNy4) of human-in-the-loop training. For support, please open an [issue](https://github.com/MouseLand/cellpose/issues). 
 
-Please see install instructions [below](README.md/#Installation), and also check out the detailed documentation at [**cellpose.readthedocs.io**](https://cellpose.readthedocs.io/en/latest/) for more information. Example notebooks:
+Please see install instructions [below](README.md/#Installation), and also check out the detailed documentation at <font size="4">[**cellpose.readthedocs.io**](https://cellpose.readthedocs.io/en/latest/)</font>.
 
-* [run_cellpose3.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/run_cellpose3.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_cellpose3.ipynb): run image restoration and segmentation with Cellpose3
-* [run_cyto3.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/run_cellpose3.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_cyto3.ipynb): segment with the new super-generalist "cyto3" model
-* [run_cellpose_2.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/run_cellpose_2.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_cellpose_2.ipynb): train your own models with Cellpose2
-* [run_cellpose_GPU.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/run_cellpose_GPU.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_cellpose_GPU.ipynb): run Cellpose segmentation in 2D and 3D
-* [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/Cellpose_cell_segmentation_2D_prediction_only.ipynb): a user-friendly notebook for 2D segmentation written by [@pr4deepr](https://github.com/pr4deepr)
-* [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/HenriquesLab/ZeroCostDL4Mic/blob/master/Colab_notebooks/Beta%20notebooks/Cellpose_2D_ZeroCostDL4Mic.ipynb): a user-friendly [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic) notebook that includes training cellpose models, written by [@guijacquemet](https://github.com/guijacquemet)
+Example notebooks:
 
-:triangular_flag_on_post: All models in Cellpose, except `yeast_BF_cp3`, `yeast_PhC_cp3`, and `deepbacs_cp3`, are trained on some amount of data that is **CC-BY-NC**. The Cellpose annotated dataset is also CC-BY-NC.
+* [run_Cellpose-SAM.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/run_Cellpose-SAM.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_Cellpose-SAM.ipynb): run Cellpose-SAM on your own data, mounted in google drive
+* [test_Cellpose-SAM.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/test_Cellpose-SAM.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/test_Cellpose-SAM.ipynb): shows running Cellpose-SAM using example data in 2D and 3D
+* [train_Cellpose-SAM.ipynb](https://github.com/MouseLand/cellpose/blob/main/notebooks/train_Cellpose-SAM.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/train_Cellpose-SAM.ipynb): train Cellpose-SAM on your own labeled data (also optional example data provided)
+
+:triangular_flag_on_post: The Cellpose-SAM model is trained on data that is licensed under **CC-BY-NC**. The Cellpose annotated dataset is also CC-BY-NC.
 
 ### CITATION
 
+**If you use Cellpose-SAM, please cite the Cellpose-SAM [paper](https://www.biorxiv.org/content/10.1101/2025.04.28.651001v1):**
+Pachitariu, M., Rariden, M., & Stringer, C. (2025). Cellpose-SAM: superhuman generalization for cellular segmentation. <em>bioRxiv</em>.
+
 **If you use Cellpose 1, 2 or 3, please cite the Cellpose 1.0 [paper](https://t.co/kBMXmPp3Yn?amp=1):**  
 Stringer, C., Wang, T., Michaelos, M., & Pachitariu, M. (2021). Cellpose: a generalist algorithm for cellular segmentation. <em>Nature methods, 18</em>(1), 100-106.
 
@@ -42,9 +44,9 @@ Pachitariu, M. & Stringer, C. (2022). Cellpose 2.0: how to train your own model.
 **If you use the new image restoration models or cyto3, please also cite the Cellpose3 [paper](https://www.nature.com/articles/s41592-025-02595-5):**  
 Stringer, C. & Pachitariu, M. (2025). Cellpose3: one-click image restoration for improved segmentation. <em>Nature Methods</em>.
 
-### v3.1+ update (Feb 2025)
+## Old updates
 
-`pip install cellpose --upgrade` to get all the new features and bug fixes!
+### v3.1+ update (Feb 2025)
 
 * support for **big data** contributed by [@GFleishman](https://github.com/GFleishman), usage info [here](https://cellpose.readthedocs.io/en/latest/distributed.html)
 * new options to improve 3D segmentation like `flow3D_smooth` and `pretrained_model_ortho`, more info [here](https://cellpose.readthedocs.io/en/latest/do3d.html#segmentation-settings)
@@ -58,12 +60,6 @@ Cellpose3 enables image restoration in the GUI, API and CLI (saved to `_seg.npy`
 * Tutorial [talk](https://youtu.be/TZZZlGk6AKo) about the algorithm and how to use it
 * API documentation [here](https://cellpose.readthedocs.io/en/latest/restore.html)
 
-<img src="http://www.cellpose.org/static/images/poisson_cp3.gif?raw=True" width="350" title="cellpose denoising" alt="cellpose denoising examples">
-
-<img src="http://www.cellpose.org/static/images/blur_cp3.gif?raw=True" width="350" title="cellpose deblurring" alt="cellpose deblurring examples">
-
-<img src="http://www.cellpose.org/static/images/downsample_cp3.gif?raw=True" width="350" title="cellpose upsampling" alt="cellpose upsampling examples">
-
 ### :star2: v2.0 (April 2022) :star2:
 
 Cellpose 2.0 allows human-in-the-loop training of models! To learn more, check out the twitter [thread](https://twitter.com/marius10p/status/1511415409047650307?s=20&t=umTVIG1CFKIWHYMrQqFKyQ), [paper](https://www.nature.com/articles/s41592-022-01663-4), [review](https://www.nature.com/articles/s41592-022-01664-3), [short talk](https://youtu.be/wB7XYh4QRiI), and the [tutorial talk](https://youtu.be/5qANHWoubZU) which goes through running Cellpose 2.0 in the GUI and a jupyter notebook. Check out the full human-in-the-loop [video](https://youtu.be/3Y1VKcxjNy4). See how to use it yourself in the [docs](https://cellpose.readthedocs.io/en/latest/gui.html#training-your-own-cellpose-model) and also check out the help info in the `Models` menu in the GUI.
@@ -82,15 +78,15 @@ Linux, Windows and Mac OS are supported for running the code. For running the gr
 cellpose relies on the following excellent packages (which are automatically installed with conda/pip if missing):
 - [pytorch](https://pytorch.org/)
 - [pyqtgraph](http://pyqtgraph.org/)
-- [PyQt5](http://pyqt.sourceforge.net/Docs/PyQt5/)
-- [numpy](http://www.numpy.org/) (>=1.16.0)
-- [numba](http://numba.pydata.org/numba-doc/latest/user/5minguide.html)
+- [PyQt6](https://www.riverbankcomputing.com/software/pyqt/) or PySide
+- [numpy](http://www.numpy.org/) (>=1.20.0)
 - [scipy](https://www.scipy.org/)
 - [natsort](https://natsort.readthedocs.io/en/master/)
 - [tifffile](https://github.com/cgohlke/tifffile)
 - [imagecodecs](https://github.com/cgohlke/imagecodecs)
 - [roifile](https://github.com/cgohlke/roifile)
 - [fastremap](https://github.com/seung-lab/fastremap/)
+- [fill_voids](https://github.com/seung-lab/fill_voids/)
 
 ### Option 1: Installation Instructions with conda 
 

cellpose/vit_sam.py

@@ -1,3 +1,7 @@
+"""
+Copyright © 2025 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
+"""
+
 import torch
 from segment_anything import sam_model_registry
 torch.backends.cuda.matmul.allow_tf32 = True

docs/do3d.rst

@@ -24,16 +24,12 @@ incorrect. If drag-and-drop works (you can see a tiff with multiple planes),
 then the GUI will automatically run 3D segmentation and display it in the GUI. Watch 
 the command line for progress. It is recommended to use a GPU to speed up processing.
 
-In the CLI/notebook, you can specify the ``z_axis`` and optionally the ``channel_axis``
+In the CLI/notebook, you need to specify the ``z_axis`` and the ``channel_axis``
 parameters to specify the axis (0-based) of the image which corresponds to the image channels and to the z axis. 
 For example an image with 2 channels of shape (1024,1024,2,105,1) can be 
-specified with ``channel_axis=2`` and ``z_axis=3``. If ``channel_axis=None`` 
-cellpose will try to automatically determine the channel axis by choosing 
-the dimension with the minimal size after squeezing. If ``z_axis=None`` 
-cellpose will automatically select the first non-channel axis of the image 
-to be the Z axis. These parameters can be specified using the command line 
+specified with ``channel_axis=2`` and ``z_axis=3``. These parameters can be specified using the command line 
 with ``--channel_axis`` or ``--z_axis`` or as inputs to ``model.eval`` for 
-the ``Cellpose`` or ``CellposeModel`` model.
+the ``CellposeModel`` model.
 
 Volumetric stacks do not always have the same sampling in XY as they do in Z. 
 Therefore you can set an ``anisotropy`` parameter in CLI/notebook to allow for differences in 

docs/index.rst

@@ -5,20 +5,21 @@ cellpose
 
 cellpose is an anatomical segmentation algorithm written in Python 3 
 by Carsen Stringer and Marius Pachitariu. For support, please open 
-an `issue`_.
-
-We make pip installable releases of cellpose, here is the `pypi`_. You
+an `issue`_. We make pip installable releases of cellpose available on `pypi`_. You
 can install it as ``pip install cellpose[gui]``.
 
-You can try it out without installing at `https://huggingface.co/spaces/mouseland/cellpose`_. 
+**Cellpose-SAM is now available!**
 
-Also check out these resources:
+You can run Cellpose-SAM in the cloud (no install) at `Hugging Face <https://huggingface.co/spaces/mouseland/cellpose>`_. 
 
 Cellpose-SAM: superhuman generalization for cellular segmentation
 
 - `paper <https://www.biorxiv.org/content/10.1101/2025.04.28.651001v1>`_ on biorxiv
 
 
+Old releases:
+-----------------------------
+
 Cellpose3: one-click image restoration for improved cellular segmentation
 
 - `paper <https://www.biorxiv.org/content/10.1101/2024.02.10.579780v1>`_ on biorxiv

docs/installation.rst

@@ -110,39 +110,4 @@ If you are on Yosemite Mac OS or earlier, PyQt doesn't work and you won't be abl
 to use the graphical interface for cellpose. More recent versions of Mac
 OS are fine. The software has been heavily tested on Windows 10 and
 Ubuntu 18.04, and less well tested on Mac OS. Please post an issue if
-you have installation problems.
-
-
-Dependencies
-~~~~~~~~~~~~~~~~~~~~~~
-
-cellpose relies on the following excellent packages (which are
-automatically installed with pip if missing):
-
--  `pytorch`_
--  `pyqtgraph`_
--  `PyQt5`_ or pyside or PyQt6
--  `numpy`_ (>=1.16.0)
--  `numba`_
--  `scipy`_
--  `tifffile`_
--  `natsort`_
--  `fastremap`_
--  `roifile`_
--  `superqt`_
-
-.. _Anaconda: https://www.anaconda.com/download/
-.. _environment.yml: https://github.com/MouseLand/cellpose/blob/master/environment.yml?raw=true
-.. _here: https://pypi.org/project/cellpose/
-
-.. _pytorch: https://pytorch.org/
-.. _pyqtgraph: http://pyqtgraph.org/
-.. _PyQt5: http://pyqt.sourceforge.net/Docs/PyQt5/
-.. _numpy: http://www.numpy.org/
-.. _numba: http://numba.pydata.org/numba-doc/latest/user/5minguide.html
-.. _scipy: https://www.scipy.org/
-.. _tifffile: https://pypi.org/project/tifffile/
-.. _natsort: https://natsort.readthedocs.io/en/master/
-.. _fastremap: https://github.com/seung-lab/fastremap
-.. _roifile: https://github.com/cgohlke/roifile
-.. _superqt: https://github.com/pyapp-kit/superqt
+you have installation problems.

notebooks/Cellpose_cell_segmentation_2D_prediction_only.ipynb

@@ -3,11 +3,11 @@
     {
       "cell_type": "markdown",
       "metadata": {
-        "id": "view-in-github",
-        "colab_type": "text"
+        "colab_type": "text",
+        "id": "view-in-github"
       },
       "source": [
-        "<a href=\"https://colab.research.google.com/github/MouseLand/cellpose_dev/blob/main/notebooks/run_Cellpose-SAM.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
+        "<a href=\"https://colab.research.google.com/github/MouseLand/cellpose/blob/main/notebooks/run_Cellpose-SAM.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
       ]
     },
     {
@@ -111,7 +111,7 @@
       },
       "outputs": [],
       "source": [
-        "!pip install git+https://www.github.com/mouseland/cellpose_dev.git"
+        "!pip install git+https://www.github.com/mouseland/cellpose.git"
       ]
     },
     {
@@ -139,13 +139,12 @@
         "import matplotlib.pyplot as plt\n",
         "from natsort import natsorted\n",
         "\n",
+        "io.logger_setup() # run this to get printing of progress\n",
         "\n",
         "#Check if colab notebook instance has GPU access\n",
         "if core.use_gpu()==False:\n",
         "  raise ImportError(\"No GPU access, change your runtime\")\n",
         "\n",
-        "io.logger_setup() # run this to get printing of progress\n",
-        "\n",
         "model = models.CellposeModel(gpu=True)"
       ]
     },
@@ -322,8 +321,8 @@
   "metadata": {
     "accelerator": "GPU",
     "colab": {
-      "provenance": [],
-      "include_colab_link": true
+      "include_colab_link": true,
+      "provenance": []
     },
     "kernelspec": {
       "display_name": "cellpose",
@@ -345,4 +344,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 0
-}
+}