Merge branch 'main' of https://github.com/MouseLand/cellpose

Author: Jiadalee

cellpose/__main__.py

@@ -98,8 +98,6 @@ def main():
         logger.warning("the '--invert' flag is deprecated in v4.0.1+ and no longer used")
     if args.chan2_restore:
         logger.warning("the '--chan2_restore' flag is deprecated in v4.0.1+ and no longer used")
-    if not args.no_resample:
-        logger.warning("the '--no_resample' flag is deprecated in v4.0.1+ and no longer used")
     if args.diam_mean:
         logger.warning("the '--diam_mean' flag is deprecated in v4.0.1+ and no longer used")
     if args.train_size:
@@ -228,6 +226,7 @@ def _evaluate_cellposemodel_cli(args, logger, imf, device, pretrained_model, nor
                 min_size=args.min_size,
                 batch_size=args.batch_size,
                 bsize=args.bsize,
+                resample=not args.no_resample,
                 normalize=normalize,
                 channel_axis=channel_axis, 
                 z_axis=z_axis,

cellpose/cli.py

@@ -134,8 +134,8 @@ def get_arg_parser():
 
     # TODO: remove deprecated in future version
     algorithm_args.add_argument(
-        "--no_resample", action="store_true", help=
-        'Deprecated in v4.0.1+, not used. ')
+        "--no_resample", action="store_true", 
+        help="disables flows/cellprob resampling to original image size before computing masks. Using this flag will make more masks more jagged with larger diameter settings.")
     algorithm_args.add_argument(
         "--no_interp", action="store_true",
         help="do not interpolate when running dynamics (was default)")

cellpose/models.py

@@ -151,7 +151,7 @@ def __init__(self, gpu=False, pretrained_model="cpsam", model_type=None,
             self.net.load_model(self.pretrained_model, device=self.device)
 
 
-    def eval(self, x, batch_size=8, resample=None, channels=None, channel_axis=None,
+    def eval(self, x, batch_size=8, resample=True, channels=None, channel_axis=None,
              z_axis=None, normalize=True, invert=False, rescale=None, diameter=None,
              flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None,
              flow3D_smooth=0, stitch_threshold=0.0, 
@@ -165,7 +165,6 @@ def eval(self, x, batch_size=8, resample=None, channels=None, channel_axis=None,
             batch_size (int, optional): number of 256x256 patches to run simultaneously on the GPU
                 (can make smaller or bigger depending on GPU memory usage). Defaults to 64.
             resample (bool, optional): run dynamics at original image size (will be slower but create more accurate boundaries). 
-                deprecated in v4.0.1+, resample is not used
             channel_axis (int, optional): channel axis in element of list x, or of np.ndarray x. 
                 if None, channels dimension is attempted to be automatically determined. Defaults to None.
             z_axis  (int, optional): z axis in element of list x, or of np.ndarray x. 
@@ -327,7 +326,9 @@ def eval(self, x, batch_size=8, resample=None, channels=None, channel_axis=None,
 
         if resample:
             # upsample flows before computing them: 
-            raise NotImplementedError
+            dP = self._resize_gradients(dP, to_y_size=Ly_0, to_x_size=Lx_0, to_z_size=Lz_0)
+            cellprob = self._resize_cellprob(cellprob, to_x_size=Lx_0, to_y_size=Ly_0, to_z_size=Lz_0)
+
 
         if compute_masks:
             niter0 = 200
@@ -343,6 +344,10 @@ def eval(self, x, batch_size=8, resample=None, channels=None, channel_axis=None,
 
         # undo resizing:
         if image_scaling is not None or anisotropy is not None:
+
+            dP = self._resize_gradients(dP, to_y_size=Ly_0, to_x_size=Lx_0, to_z_size=Lz_0) # works for 2 or 3D: 
+            cellprob = self._resize_cellprob(cellprob, to_x_size=Lx_0, to_y_size=Ly_0, to_z_size=Lz_0)
+
             if do_3D:
                 if compute_masks:
                     # Rescale xy then xz:
@@ -351,29 +356,96 @@ def eval(self, x, batch_size=8, resample=None, channels=None, channel_axis=None,
                     masks = transforms.resize_image(masks, Ly=Lz_0, Lx=Lx_0, no_channels=True, interpolation=cv2.INTER_NEAREST)
                     masks = masks.transpose(1, 0, 2)
 
-                # cellprob is the same
-                cellprob = transforms.resize_image(cellprob, Ly=Ly_0, Lx=Lx_0, no_channels=True)
-                cellprob = cellprob.transpose(1, 0, 2)
-                cellprob = transforms.resize_image(cellprob, Ly=Lz_0, Lx=Lx_0, no_channels=True)
-                cellprob = cellprob.transpose(1, 0, 2)
-
-                # dP has gradients that can be treated as channels:
-                dP = dP.transpose(1, 2, 3, 0) # move gradients last:
-                dP = transforms.resize_image(dP, Ly=Ly_0, Lx=Lx_0, no_channels=False)
-                dP = dP.transpose(1, 0, 2, 3) # switch axes to resize again
-                dP = transforms.resize_image(dP, Ly=Lz_0, Lx=Lx_0, no_channels=False)
-                dP = dP.transpose(3, 1, 0, 2) # undo transposition
-
             else:
                 # 2D or 3D stitching case:
                 if compute_masks:
                     masks = transforms.resize_image(masks, Ly=Ly_0, Lx=Lx_0, no_channels=True, interpolation=cv2.INTER_NEAREST)
-                cellprob = transforms.resize_image(cellprob, Ly=Ly_0, Lx=Lx_0, no_channels=True)
-                dP = np.moveaxis(dP, 0, -1) # Put gradients last
-                dP = transforms.resize_image(dP, Ly=Ly_0, Lx=Lx_0, no_channels=False)
-                dP = np.moveaxis(dP, -1, 0) # Put gradients first
 
         return masks, [plot.dx_to_circ(dP), dP, cellprob], styles
+    
+
+    def _resize_cellprob(self, prob: np.ndarray, to_y_size: int, to_x_size: int, to_z_size: int = None) -> np.ndarray:
+        """
+        Resize cellprob array to specified dimensions for either 2D or 3D.
+
+        Parameters:
+            prob (numpy.ndarray): The cellprobs to resize, either in 2D or 3D. Returns the same ndim as provided.
+            to_y_size (int): The target size along the Y-axis.
+            to_x_size (int): The target size along the X-axis.
+            to_z_size (int, optional): The target size along the Z-axis. Required
+                for 3D cellprobs.
+
+        Returns:
+            numpy.ndarray: The resized cellprobs array with the same number of dimensions
+            as the input.
+
+        Raises:
+            ValueError: If the input cellprobs array does not have 3 or 4 dimensions.
+        """
+        prob_shape = prob.shape
+        prob = prob.squeeze()
+        squeeze_happened = prob.shape != prob_shape
+        prob_shape = np.array(prob_shape)
+
+        if prob.ndim == 2:
+            # 2D case:
+            prob = transforms.resize_image(prob, Ly=to_y_size, Lx=to_x_size, no_channels=True)
+            if squeeze_happened:
+                prob = np.expand_dims(prob, int(np.argwhere(prob_shape == 1))) # add back empty axis for compatibility
+        elif prob.ndim == 3:
+            # 3D case: 
+            prob = transforms.resize_image(prob, Ly=to_y_size, Lx=to_x_size, no_channels=True)
+            prob = prob.transpose(1, 0, 2)
+            prob = transforms.resize_image(prob, Ly=to_z_size, Lx=to_x_size, no_channels=True)
+            prob = prob.transpose(1, 0, 2)
+        else:
+            raise ValueError(f'gradients have incorrect dimension after squeezing. Should be 2 or 3, prob shape: {prob.shape}')
+        
+        return prob
+
+
+    def _resize_gradients(self, grads: np.ndarray, to_y_size: int, to_x_size: int, to_z_size: int = None) -> np.ndarray:
+        """
+        Resize gradient arrays to specified dimensions for either 2D or 3D gradients.
+
+        Parameters:
+            grads (np.ndarray): The gradients to resize, either in 2D or 3D. Returns the same ndim as provided.
+            to_y_size (int): The target size along the Y-axis.
+            to_x_size (int): The target size along the X-axis.
+            to_z_size (int, optional): The target size along the Z-axis. Required
+                for 3D gradients.
+
+        Returns:
+            numpy.ndarray: The resized gradient array with the same number of dimensions
+            as the input.
+
+        Raises:
+            ValueError: If the input gradient array does not have 3 or 4 dimensions.
+        """
+        grads_shape = grads.shape
+        grads = grads.squeeze()
+        squeeze_happened = grads.shape != grads_shape
+        grads_shape = np.array(grads_shape)
+
+        if grads.ndim == 3:
+            # 2D case, with XY flows in 2 channels:
+            grads = np.moveaxis(grads, 0, -1) # Put gradients last
+            grads = transforms.resize_image(grads, Ly=to_y_size, Lx=to_x_size, no_channels=False)
+            grads = np.moveaxis(grads, -1, 0) # Put gradients first
+
+            if squeeze_happened:
+                grads = np.expand_dims(grads, int(np.argwhere(grads_shape == 1))) # add back empty axis for compatibility
+        elif grads.ndim == 4:
+            # dP has gradients that can be treated as channels:
+            grads = grads.transpose(1, 2, 3, 0) # move gradients last:
+            grads = transforms.resize_image(grads, Ly=to_y_size, Lx=to_x_size, no_channels=False)
+            grads = grads.transpose(1, 0, 2, 3) # switch axes to resize again
+            grads = transforms.resize_image(grads, Ly=to_z_size, Lx=to_x_size, no_channels=False)
+            grads = grads.transpose(3, 1, 0, 2) # undo transposition
+        else:
+            raise ValueError(f'gradients have incorrect dimension after squeezing. Should be 3 or 4, grads shape: {grads.shape}')
+        
+        return grads
 
 
     def _run_net(self, x, 

docs/faq.rst

@@ -66,3 +66,49 @@ FAQ
     using `torch.set_num_threads <https://pytorch.org/docs/stable/generated/torch.set_num_threads.html>`_ or through the environment
     variables ``OMP_NUM_THREADS`` or ``MKL_NUM_THREADS`` as described
     `here <https://pytorch.org/docs/stable/threading_environment_variables.html>`_.
+
+
+**Q: How does HITL work?**
+
+    In cellpose HITL training always starts from a pretrained model but incorporates more training 
+    data with each iteration. To start, only a single image is used as training data. 
+    After an iteration another image is included in the training data. Since there is more 
+    training data, the model should be more accurate on subsequent images.
+
+    The goal of HITL training is to produce a model that is finetuned on your data and also generalist
+    enough to segment new images not in the training set. One of the problems with annotating 
+    images is that it can be time-consuming to annotate your images to produce a finetuned model. 
+    Cellpose also circumvents this tedium by using the already generalist-trained model to predict 
+    your image segmentation. This prediction will be better than nothing, and it will get some 
+    segmentation masks correct. That is helpful becuase you can accept the correct masks, and add 
+    or edit the incorrect ones. Now you have a new image that can be used for training a new finetuned
+    model. This new finetuned model can then also predict segmentation for an image in your dataset, 
+    and, since it's finetuned on your data, will do somewhat better than the 'base' cellpose model. 
+    You can repeat these steps, (predict using the latest model, annotate the predictions, train, 
+    and predict again) until you have a model that performs well enough on your data.
+
+
+**Q: What is a 'model'?**
+
+    A model is the neural network architecture and parameters (fitted numbers) in that architecture. 
+    The CPSAM model we distribute is a 'model', and you can have another 'model' made from finetuning
+    on your data. These models are similar becuase they have the same architecture, but distinct 
+    because they have different weights. 
+
+
+**Q: How can I do HITL without the GUI? (I don't have GPU hardware on my machine, but I want to use 
+colab/a cluster)**
+
+    You can do the following steps:
+
+    1. Load the images onto the remote machine. 
+
+    2. Use a script to segment the image using the pretrained model. 
+
+    3. Download the segmented image masks and annotate it with the cellpose GUI.
+
+    4. Load the annotated masks onto the remote machine and train a model with all the images in the folder (only 1 at first)
+
+    5. Evaluate the trained model on the next image.
+
+    6. Repeat 3-5 until you have a working fine-tuned model. 

docs/index.rst

@@ -11,7 +11,7 @@ can install it as ``pip install cellpose[gui]``.
 
 - run Cellpose-SAM in the cloud (no install) at `Hugging Face <https://huggingface.co/spaces/mouseland/cellpose>`_. 
 - `paper <https://www.biorxiv.org/content/10.1101/2025.04.28.651001v1>`_ on biorxiv
-- talk 
+- `talk <https://www.youtube.com/watch?v=KIdYXgQemcI>`_
 
 
 

docs/installation.rst

@@ -62,6 +62,7 @@ Common issues
 If you receive an issue with Qt "xcb", you may need to install xcb libraries, e.g.:
 
 :: 
+
    sudo apt install libxcb-cursor0
    sudo apt install libxcb-xinerama0
 
@@ -90,6 +91,7 @@ If you are having other issues with the graphical interface and QT, see some adv
 If you have errors related to OpenMP and libiomp5, then try 
 
 ::
+   
    conda install nomkl
 
 If you receive an error associated with **matplotlib**, try upgrading

docs/settings.rst

@@ -8,7 +8,7 @@ See the :ref:`cpmclass` for all run options.
 
 .. warning:: 
     Cellpose 3 used ``models.Cellpose`` class which has been removed in Cellpose 4. Users should
-    now only use the ``models.CellposeModel``` class. 
+    now only use the ``models.CellposeModel`` class. 
 
 Here is an example of calling the ``CellposeModel`` class and
 running a list of images for reference:

tests/test_output.py

@@ -38,25 +38,28 @@ def clear_output(data_dir, image_names):
             os.remove(npy_output)
 
 
-@pytest.mark.parametrize('compute_masks, resample', 
+@pytest.mark.parametrize('compute_masks, resample, diameter', 
                          [
-                             (True, True), 
-                             (False, True),
-                             (False, False,)
+                             (True, True, 40), 
+                             (True, True, None), 
+                             (False, True, None),
+                             (False, False, None)
                          ]
 )
-def test_class_2D_one_img(data_dir, image_names, cellposemodel_fixture_24layer, compute_masks, resample):
+def test_class_2D_one_img(data_dir, image_names, cellposemodel_fixture_24layer, compute_masks, resample, diameter):
     clear_output(data_dir, image_names)
 
     img_file = data_dir / '2D' / image_names[0]
 
     img = io.imread_2D(img_file)
     # flowps = io.imread(img_file.parent / (img_file.stem + "_cp4_gt_flowps.tif"))
 
-    masks_pred, _, _ = cellposemodel_fixture_24layer.eval(img, normalize=True, compute_masks=compute_masks, resample=resample)
+    masks_pred, _, _ = cellposemodel_fixture_24layer.eval(img, normalize=True, compute_masks=compute_masks, resample=resample, diameter=diameter)
 
-    if not compute_masks:
-        return # just check that not compute_masks works: 
+    if not compute_masks or diameter:
+        # not compute_masks won't return masks so can't check
+        # different diameter will give different masks, so can't check
+        return 
 
     io.imsave(data_dir / '2D' / (img_file.stem + "_cp_masks.png"), masks_pred)
     # flowsp_pred = np.concatenate([flows_pred[1], flows_pred[2][None, ...]], axis=0)