Add more notebooks to docs (#699)

* Add more notebooks to docs (#698) * Fix missing links and update content * Add new notebooks
talmolab · Apr 4, 2022 · 51a6af4 · 51a6af4
1 parent fc050f1
commit 51a6af4
Show file tree

Hide file tree

Showing 10 changed files with 4,239 additions and 59 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,15 +16,16 @@
 import sys
 import shutil
 import docs.utils
+from datetime import date
 
 sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "SLEAP"
-author = "Talmo D. Pereira"
-copyright = "2019–2022, Talmo Lab"
+author = "SLEAP Developers"
+copyright = f"2019–{date.today().year}, Talmo Lab"
 
 # The short X.Y version
 version = "1.2.2"
@@ -162,6 +163,9 @@ def linkcode_resolve(domain, info):
     "tasklist",
 ]
 
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors
+myst_heading_anchors = 3
+
 html_logo = "_static/logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/guides/gui.rst b/docs/guides/gui.rst
@@ -64,6 +64,10 @@ View
 
 "**Apply Distinct Colors To**" allows you to determine whether distinct colors are used for distinct tracks (instance identities), nodes, or edges. Try it!
 
+"**Show Instances**" toggles the visibility of all instances in the frame. Useful for quickly hiding overlapping predictions.
+
+"**Show Non-Visible Nodes**" toggles the visibility of "non-visible" nodes. Non-visible here means they are landmarks that were manually marked as occluded or not present. Hiding them is useful when inspecting manual labels with many missing nodes.
+
 "**Show Node Names**" allows you to toggle the visibility of the node names. This is useful if you have lots of nearby instances or very dense skeletons and the node names make it hard to see where the nodes are located.
 
 "**Show Edges**" allows you to toggle the visibility of the edges which connect the nodes. This can be useful when you have lots of edges which make it hard to see the features of animals in your video.

diff --git a/docs/help.md b/docs/help.md
@@ -7,7 +7,7 @@ Stuck? Can't get SLEAP to run? Crashing? Try the recommended tips below.
 
 ### I can't get SLEAP to install!
 
-Have you tried all of the steps in the {ref}`installation instructions <installation>`?
+Have you tried all of the steps in the [installation instructions](installation)?
 
 If so, please feel free to [open an issue](https://github.com/murthylab/sleap/issues) and tell us how you're trying to install it, what error messages you're getting and which operating system you're on.
 
@@ -17,7 +17,7 @@ Yes! You can install SLEAP as you normally would using the `conda` or `pip`-base
 
 ### What if I already have CUDA set up on my system?
 
-You can use the system CUDA installation by simply using the {ref}`pip <pip install>` installation method.
+You can use the system CUDA installation by simply using the [](./installation.md#pip-package) installation method.
 
 Note that you will need to use a version compatible with **TensorFlow 2.6+** (**CUDA Toolkit v11.3** and **cuDNN v8.2**).
 

diff --git a/docs/notebooks/Data_structures.ipynb b/docs/notebooks/Data_structures.ipynb
diff --git a/docs/notebooks/Interactive_and_realtime_inference.ipynb b/docs/notebooks/Interactive_and_realtime_inference.ipynb
diff --git a/docs/notebooks/Interactive_and_resumable_training.ipynb b/docs/notebooks/Interactive_and_resumable_training.ipynb
diff --git a/docs/notebooks/Post_inference_tracking.ipynb b/docs/notebooks/Post_inference_tracking.ipynb
diff --git a/docs/notebooks/index.rst b/docs/notebooks/index.rst
@@ -5,29 +5,60 @@ Notebooks
 
 Here are Jupyter notebooks you can run to try SLEAP on `Google Colaboratory <https://colab.research.google.com>`_ (Colab). Colab is great for running training and inference on your data if you don't have access to a local machine with a supported GPU.
 
+Basic usage
+------------
+
 `Training and inference on an example dataset <./Training_and_inference_on_an_example_dataset.html>`_
--------------------------------------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In this notebook we'll show you how to install SLEAP on Colab, download a dataset from the `repository of sample datasets <https://github.com/murthylab/sleap-datasets>`_, run training and inference on that dataset using the SLEAP command-line interface, and then download the predictions.
 This notebook can be a good place to start since you'll be able to see how training and inference work without any of your own data and without having to edit anything in the notebook to get it to run correctly.
 
 
 `Training and inference on your own data using Google Drive <./Training_and_inference_using_Google_Drive.html>`_
------------------------------------------------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Once you're ready to run training and inference on your own SLEAP dataset, this notebook walks you through the process of using `Google Drive <https://www.google.com/drive>`_ to copy data to and from Colab (as well as running training and inference on your dataset).
 
 
-`Model evaluation <./Model_evaluation.html>`_
-------------------------------------------------
+`Analysis examples <./Analysis_examples.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After you've trained several models, you may want to compute some metrics for benchmarking and comparisons. This notebook walks through some of the types of metrics that SLEAP can compute for you, as well as how to recompute them.
+Once you've used SLEAP to successfully estimate animal pose and track animals in your videos, you'll want to use the resulting data. This notebook walks you through some analysis examples which illustrate how to read and interpret the data in the analysis HDF5 files which you can export from SLEAP.
 
+Advanced SLEAPing
+------------------
 
-`Analysis examples <./Analysis_examples.html>`_
-------------------------------------------------
+`Data structures <./Data_structures.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once you've used SLEAP to successfully estimate animal pose and track animals in your videos, you'll want to use the resulting data. This notebook walks you through some analysis examples which illustrate how to read and interpret the data in the analysis HDF5 files which you can export from SLEAP.
+SLEAP uses a set of core data structures that contain labels, predictions and other metadata. In this notebook we show you how to use them to develop custom analysis scripts and applications.
+
+We demonstrate how to work with these data structures by interactively generating predictions from a trained model.
+
+
+`Post-inference tracking <./Post_inference_tracking.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this notebook, we show how to use the tracking functionality within SLEAP to re-track existing predictions. This is useful when experimenting with new ID tracking parameters without having to re-run pose estimation.
+
+
+`Interactive and resumable training <./Interactive_and_resumable_training.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Training in SLEAP can be done via the GUI, CLI or interactively in Python. Here we show how to use SLEAP's Python API to enable customizable training workflows, including resumable training for initialization from existing models.
+
+
+`Interactive and realtime inference <./Interactive_and_realtime_inference.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have trained models, you can run inference via the GUI, CLI or interactively in Python. Here we show how to load trained models, use them to predict on new frames, and implement a basic version of a realtime SLEAP tracker for closed-loop applications.
+
+
+`Model evaluation <./Model_evaluation.html>`_
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you've trained several models, you may want to compute some metrics for benchmarking and comparisons. This notebook walks through some of the types of metrics that SLEAP can compute for you, as well as how to recompute them.
 
 
 .. toctree::
@@ -36,4 +67,8 @@ Once you've used SLEAP to successfully estimate animal pose and track animals in
     Training_and_inference_on_an_example_dataset
     Training_and_inference_using_Google_Drive
     Model_evaluation
-    Analysis_examples
+    Analysis_examples
+    Data_structures
+    Post_inference_tracking
+    Interactive_and_resumable_training
+    Interactive_and_realtime_inference
diff --git a/docs/tutorials/new-project.md b/docs/tutorials/new-project.md
@@ -0,0 +1,81 @@
+---
+substitutions:
+  image0: |-
+    ```{image} ../_static/add-video.gif
+    ```
+  image1: |-
+    ```{image} ../_static/video-options.gif
+    ```
+  image2: |-
+    ```{image} ../_static/add-skeleton.gif
+    ```
+---
+
+(new-project)=
+
+# Creating a project
+
+## Starting SLEAP
+
+If you haven't installed SLEAP yet, see [](../installation) for instructions.
+
+Once you have SLEAP installed, start by opening a terminal. If you installed via the recommended [](../installation.md#conda-package) method, activate the environment with:
+
+```
+conda activate sleap
+```
+
+````{hint}
+To open a terminal:
+
+**Windows:** Open the *Start menu* and search for the *Anaconda Command Prompt* (if using Miniconda) or the *Command Prompt* if not.
+```{note}
+On Windows, our personal preference is to use alternative terminal apps like [Cmder](https://cmder.net) or [Windows Terminal](https://aka.ms/terminal).
+```
+
+**Linux:** Launch a new terminal by pressing <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>T</kbd>.
+
+**Mac:** Launch a new terminal by pressing <kbd>Cmd</kbd> + <kbd>Space</kbd> and searching for *Terminal*.
+````
+
+To launch the GUI, simply enter in the terminal:
+```
+sleap-label
+```
+
+When you first start SLEAP you’ll see a new, empty project.
+
+## Opening a video
+
+Add a video by clicking the “**Add Video**” button in the “**Videos**” panel
+on the right side of the main window, or by dragging-and-dropping your video file from its
+folder into the SLEAP GUI.
+
+{{ image0 }}
+
+You’ll then be able to select one or more video files and click “**Open**”.
+SLEAP currently supports mp4, avi, and h5 files. For mp4 and avi files,
+you’ll be asked whether to import the video as grayscale. For h5 files,
+you’ll be asked the dataset and whether the video is stored with
+channels first or last.
+
+{{ image1 }}
+
+(new-skeleton)=
+
+## Creating a Skeleton
+
+Create a new **skeleton** using the “Skeleton” panel on the right side
+of the main window.
+
+Use the “**New Node**” button to add a node (i.e., joint or body part).
+Double-click the node name to rename it (hit enter after you type the
+new name). Repeat until you have created all your nodes. You then need
+to connect the nodes with edges. Directly to the left of the “Add edge”
+button you’ll see two drop-down menus. Use these to select a pair of
+nodes, and then click “**Add Edge**”. Repeat until you’ve entered all the
+edges.
+
+{{ image2 }}
+
+Continue to {ref}`initial-labeling`.
diff --git a/docs/tutorials/new-project.rst b/docs/tutorials/new-project.rst