diff --git a/docs/source/conf.py b/docs/source/conf.py index 3fb5578..7d50994 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,5 @@ project = 'Motile Plugin' -copyright = '2024, Caroline Malin-Mayor' +copyright = '2024, Howard Hughes Medical Institute' author = 'Caroline Malin-Mayor' extensions = ['sphinx.ext.autodoc', 'myst_parser', 'autoapi.extension', 'sphinx_rtd_theme'] diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 0000000..485fd48 --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,61 @@ +Getting started with the motile plugin +====================================== + +Installation +------------ +This plugin depends on ``ilpy``, which must be installed via conda.:: + + conda create -n motile-plugin python>=3.10 + conda activate motile-plugin + conda install -c conda-forge -c funkelab -c gurobi ilpy + pip install git+https://github.com/funkelab/motile-napari-plugin.git + +If this is successful, you can then run ``napari`` from your command line, and +the motile plugin should be visible in the "Plugins" drop down menu. +Clicking this should open the motile widget on the right of the viewer. + +Input data +---------- +The motile plugin takes as input expects a Labels layer with time as the +first dimension followed by the spatial dimensions (no channels). +You can load an example 2D HeLa Dataset from the `Cell Tracking Challenge`_ +in "Files" -> "Sample Data". + +In the future, we could also support Points layers as input - please react to +`Issue #30`_ if this is important to your use case. While source images are +nice to qualitatively evaluate results, they are not necessary to run tracking. + +Running tracking +---------------- +The motile plugin by default opens to the "Run Editor" view. In this section, +you can pick a name for your run, select an input Labels layer, set +hyperparameters, and start a motile run. Hovering over the title of each +element in the widget will make a tooltip appear describing the purpose +of the element. When you are ready, click the "Run" button to start tracking. + +Viewing run results +------------------- +Clicking the "Run" button will automatically take you to the "Run Viewer". +Here you will see: + +- the solver status +- a graph of the solver gap (an optimization value that should approach zero) +- the hyperparameters of the run +- a button to save the whole run (for persistent viewing in the plugin) +- a button to export just the tracks as a CSV +- a button to return to the Run Editor + +Once the solver completes, you will also see a segmentation and a tracks layer +in the napari viewer. These are the tracking results. + +A list of "Tracking Runs" will also appear at the bottom of the widget. +These are the runs that are stored in memory - if you run tracking multiple +times with different inputs or parameters, you can click back and forth +between the results here. Deleting runs you do not want to keep viewing +is a good idea, since these are stored in memory. Runs that were saved in +previous sessions do not appear here until you load them from disk with the +"Load Run" button. + + +.. _Issue #30: https://github.com/funkelab/motile-napari-plugin/issues/30 +.. _Cell Tracking Challenge: https://celltrackingchallenge.net/ \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 3f7657e..a768964 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,6 +4,8 @@ .. toctree:: :maxdepth: 3 + getting_started + Indices and tables ==================