Merge pull request #1210 from MouseLand/docs_update

add to faq, some formatting

Author: mrariden

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: