Merge pull request #52 from funkelab/docs

Update docs with videos and longer descriptions

docs/source/conf.py

@@ -1,16 +1,21 @@
-project = 'Motile Plugin'
-copyright = '2024, Howard Hughes Medical Institute'
-author = 'Caroline Malin-Mayor'
+project = "Motile Plugin"
+copyright = "2024, Howard Hughes Medical Institute"
+author = "Caroline Malin-Mayor"
 
-extensions = ['sphinx.ext.autodoc', 'myst_parser', 'autoapi.extension', 'sphinx_rtd_theme']
-autoapi_dirs = ['../../src/motile_plugin']
+extensions = [
+    "sphinx.ext.autodoc",
+    "myst_parser",
+    "autoapi.extension",
+    "sphinx_rtd_theme",
+    "sphinxcontrib.video",
+]
+autoapi_dirs = ["../../src/motile_plugin"]
 
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 # html_static_path = ['_static']

docs/source/getting_started.rst

@@ -2,7 +2,7 @@ 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
@@ -14,8 +14,18 @@ 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.
 
+Tutorial video
+**************
+This video walks through tracking an example dataset from the `Cell Tracking Challenge`_,
+covering most of the same information as the rest of this getting started guide.
+
+.. raw:: html
+
+  <iframe src="https://drive.google.com/file/d/1zHvO9inHw0Hlbwq5zmRX4qUnVuO21neo/preview" width="640" height="480" allow="autoplay"></iframe>
+
+
 Input data
-----------
+**********
 The motile plugin does not perform detection: you must provide a Labels layer or a Points layer
 containing the objects you want to track.
 The Labels layer must have time as the
@@ -32,15 +42,51 @@ for bounding box tracking) - please react to
 of shape linking you want.
 
 Running tracking
-----------------
-The motile plugin by default opens to the ``Run Editor`` view. In this section,
+****************
+The motile plugin by default opens to the ``Run Editor`` view. In this view,
 you can pick a name for your run, select an input 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 Tracking`` button to start tracking.
+of the element. All hyperparameters are explained in more detail below.
+When you are ready, click the ``Run Tracking`` button to start tracking.
+
+Hyperparameters
+---------------
+The hyperparameters set up constraints on the optimization problem.
+These constraints will never be violated by the solution.
+
+- ``Max Move Distance`` - The maximum distance an object center can move between time frames, in pixels. This should be an upper bound, as nothing further will be connected.
+- ``Max Children`` - The maximum number of objects in the next time frames that an object can be linked to. Set this to 1 for tracking problems without divisions.
+
+Constant Costs
+--------------
+The constant costs contribute to the objective function that the optimization
+problem will minimize. They are the same for all possible links in the
+tracking problem, and should be set based on general properties of the problem.
+Unchecking the checkbox will not include the cost in the objective at all,
+while changing the weight values will change how much each cost contributes
+to the objective.
+
+- ``Edge Selection`` - A cost for linking any two objects between time frames. If you do not have many false positive detections, this value should be quite negative to encourage selecting as many linking edges as possible. If none of your costs are negative, the objective function will be minimized by selecting nothing (which has cost 0), so this cost can control generally how many edges/links are selected.
+- ``Appear`` - A cost for starting a new track. Assuming tracks should be long and continuous, the appear cost should be positive. A high appear cost encourages continuing tracks where possible, but can lead to not selecting short tracks at all.
+- ``Division`` - A cost for dividing, where a higher division cost will lead to fewer divisions. If your task does not have divisions, this cost does not matter - you can un-check it for clarity, but including it will do nothing.
+
+Attribute weights
+-----------------
+The attribute-based costs also contribute to the objective function that
+the optimizer will minimize. Every possible link in the tracking problem
+will have a different cost based on the specific attributes (distance or IoU)
+of that pair of detections. Unchecking the checkbox will not include the
+feature in the objective. The user-provided weight values will be multiplied by
+the attribute values to generate the cost for linking a specific pair of
+detections.
+
+- ``Distance`` - Use the distance between objects as a feature for linking. The provided weight will be multiplied by the distance between objects to get the cost for linking the two objects. This weight should usually be positive, so that higher distances are more costly.
+- ``IoU`` - Use the Intersection over Union between objects as a feature for linking. This option only applies if your input is a segmentation. The provided weights will be multiplied by the IoU to get the cost for linking two objects. This weight should usually be negative, so that higher IoUs are more likely to be linked.
+
 
 Viewing run results
--------------------
+*******************
 Clicking the ``Run Tracking`` button will automatically take you to the ``Run Viewer``.
 It contains the following:
 

docs/source/index.rst

@@ -1,12 +1,27 @@
-.. include:: ../../README.md
-   :parser: myst_parser.sphinx_
+Motile Napari Plugin
+====================
+
+|source code| |tests|
+
+.. |source code| image:: https://img.shields.io/badge/GitHub-100000?logo=github&logoColor=white
+   :target: https://github.com/funkelab/motile_napari_plugin
+
+.. |tests| image:: https://github.com/funkelab/motile-napari-plugin/workflows/tests/badge.svg
+   :target: https://github.com/funkelab/motile-napari-plugin/actions
+
+.. video:: images/results_demo_720p.mp4
+   :width: 720
+
+A plugin for tracking with `motile`_ in napari.
+Motile is a library that makes it easy to solve tracking problems using optimization
+by framing the task as an Integer Linear Program (ILP).
+See the `motile documentation`_ for more details on the concepts and method.
 
 .. toctree::
    :maxdepth: 3
 
    getting_started
 
-Indices and tables
-==================
-
-* :ref:`search`
+.. _motile: https://github.com/funkelab/motile
+.. _github link: https://github.com/funkelab/motile_napari_plugin
+.. _motile documentation: https://funkelab.github.io/motile

setup.cfg

@@ -70,6 +70,7 @@ docs =
     sphinx-autoapi
     sphinx_rtd_theme
     myst-parser
+    sphinxcontrib-video
 
 [options.package_data]
 * = *.yaml