Merge branch 'develop' into liezl/update-intallation-docs-1.4.1

.github/ISSUE_TEMPLATE/bug_report.md

@@ -28,7 +28,7 @@ Please include information about how you installed.
 - OS:
 <!-- [e.g. ubuntu 20.04, macOS 11.0] -->
 - Version(s):
-<!-- e.g. [SLEAP v1.4.1a1, python 3.8] --->
+<!-- e.g. [SLEAP v1.4.1a2, python 3.8] --->
 - SLEAP installation method (listed [here](https://sleap.ai/installation.html#)):
   - [ ] [Conda from package](https://sleap.ai/installation.html#conda-package)
   - [ ] [Conda from source](https://sleap.ai/installation.html#conda-from-source)

docs/conf.py

@@ -28,15 +28,15 @@
 copyright = f"2019–{date.today().year}, Talmo Lab"
 
 # The short X.Y version
-version = "1.4.1a1"
+version = "1.4.1a2"
 
 # Get the sleap version
 # with open("../sleap/version.py") as f:
 #     version_file = f.read()
 #     version = re.search("\d.+(?=['\"])", version_file).group(0)
 
 # Release should be the full branch name
-release = "v1.4.1a1"
+release = "v1.4.1a2"
 
 html_title = f"SLEAP ({release})"
 html_short_title = "SLEAP"
@@ -86,6 +86,7 @@
 pygments_style = "sphinx"
 pygments_dark_style = "monokai"
 
+
 # Autosummary linkcode resolution
 # https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
 def linkcode_resolve(domain, info):

docs/guides/cli.md

@@ -36,8 +36,8 @@ optional arguments:
 
 ```none
 usage: sleap-train [-h] [--video-paths VIDEO_PATHS] [--val_labels VAL_LABELS]
-                   [--test_labels TEST_LABELS] [--tensorboard] [--save_viz]
-                   [--zmq] [--run_name RUN_NAME] [--prefix PREFIX]
+                   [--test_labels TEST_LABELS] [--tensorboard] [--save_viz] 
+                   [--keep_viz] [--zmq] [--run_name RUN_NAME] [--prefix PREFIX]
                    [--suffix SUFFIX]
                    training_job_path [labels_path]
 
@@ -68,6 +68,8 @@ optional arguments:
   --save_viz            Enable saving of prediction visualizations to the run
                         folder if not already specified in the training job
                         config.
+  --keep_viz            Keep prediction visualization images in the run
+                        folder after training if --save_viz is enabled.
   --zmq                 Enable ZMQ logging (for GUI) if not already specified
                         in the training job config.
   --run_name RUN_NAME   Run name to use when saving file, overrides other run
@@ -136,7 +138,10 @@ usage: sleap-track [-h] [-m MODELS] [--frames FRAMES] [--only-labeled-frames] [-
                    [data_path]
 
 positional arguments:
-  data_path             Path to data to predict on. This can be a labels (.slp) file or any supported video format.
+  data_path             Path to data to predict on. This can be one of the following: A .slp file containing labeled data; A folder containing multiple
+                        video files in supported formats; An individual video file in a supported format; A CSV file with a column of video file paths. 
+                        If more than one column is provided in the CSV file, the first will be used for the input data paths and the next column will be
+                        used as the output paths; A text file with a path to a video file on each line
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -151,7 +156,7 @@ optional arguments:
                         Only run inference on unlabeled suggested frames when running on labels dataset. This is useful for generating predictions for
                         initialization during labeling.
   -o OUTPUT, --output OUTPUT
-                        The output filename to use for the predicted data. If not provided, defaults to '[data_path].predictions.slp'.
+                        The output filename or directory path to use for the predicted data. If not provided, defaults to '[data_path].predictions.slp'.
   --no-empty-frames     Clear any empty frames that did not have any detected instances before saving to output.
   --verbosity {none,rich,json}
                         Verbosity of inference progress reporting. 'none' does not output anything during inference, 'rich' displays an updating

docs/guides/gui.md

@@ -60,7 +60,7 @@ Note that many of the menu command have keyboard shortcuts which can be configur
 
 "**Edge Style**" controls whether edges are drawn as thin lines or as wedges which indicate the {ref}`orientation` of the instance (as well as the direction of the part affinity field which would be used to predict the connection between nodes when using a "bottom-up" approach).
 
-"**Trail Length**" allows you to show a trail of where each instance was located in prior frames (the length of the trail is the number of prior frames). This can be useful when proofreading predictions since it can help you detect swaps in the identities of animals across frames.
+"**Trail Length**" allows you to show a trail of where each instance was located in prior frames (the length of the trail is the number of prior frames). This can be useful when proofreading predictions since it can help you detect swaps in the identities of animals across frames. By default, you can only select trail lengths of up to 250 frames. You can use a custom trail length by modifying the default length in the `preferences.yaml` file. However, using trail lengths longer than about 500 frames can result in significant lag.
 
 "**Fit Instances to View**" allows you to toggle whether the view is auto-zoomed to the instances in each frame. This can be useful when proofreading predictions.
 

docs/installation.md

@@ -5,12 +5,12 @@ SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For qu
 ````{tabs}
    ```{group-tab} Windows and Linux
       ```bash
-      conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1
+      conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2
       ```
    ```
    ```{group-tab} Mac OS
       ```bash
-      conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1
+      conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a2
       ```
    ```
 ````
@@ -71,7 +71,7 @@ SLEAP can be installed three different ways: via {ref}`conda package<condapackag
       ````{tabs}
          ```{group-tab} Windows and Linux
             ```bash
-            conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a1
+            conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2
             ```  
             ```{note}
             - This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and [updated drivers](https://nvidia.com/drivers).
@@ -81,13 +81,14 @@ SLEAP can be installed three different ways: via {ref}`conda package<condapackag
          ```
          ```{group-tab} Mac OS
             ```bash
-            conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a1
+            conda create -y -n sleap -c conda-forge -c anaconda -c sleap sleap=1.4.1a2
             ```
             ```{note}
             This will also work in CPU mode if you don't have a GPU on your machine.
             ```
          ```
       ````
+
    ```
    ```{tab} conda from source
       This is the **recommended method for development**.
@@ -163,7 +164,7 @@ SLEAP can be installed three different ways: via {ref}`conda package<condapackag
                ```
             3. Finally, we can perform the `pip install`:
                ```bash
-               pip install sleap[pypi]==1.4.1a1
+               pip install sleap[pypi]==1.4.1a2
                ```
                ```{note}
                The pypi distributed package of SLEAP ships with the following extras:

docs/notebooks/Training_and_inference_on_an_example_dataset.ipynb

@@ -335,7 +335,7 @@
       "        \"runs_folder\": \"models\",\n",
       "        \"tags\": [],\n",
       "        \"save_visualizations\": true,\n",
-      "        \"delete_viz_images\": true,\n",
+      "        \"keep_viz_images\": true,\n",
       "        \"zip_outputs\": false,\n",
       "        \"log_to_csv\": true,\n",
       "        \"checkpointing\": {\n",
@@ -727,7 +727,7 @@
       "        \"runs_folder\": \"models\",\n",
       "        \"tags\": [],\n",
       "        \"save_visualizations\": true,\n",
-      "        \"delete_viz_images\": true,\n",
+      "        \"keep_viz_images\": true,\n",
       "        \"zip_outputs\": false,\n",
       "        \"log_to_csv\": true,\n",
       "        \"checkpointing\": {\n",

environment.yml

@@ -12,6 +12,7 @@ dependencies:
     # Packages SLEAP uses directly
     - conda-forge::attrs >=21.2.0  #,<=21.4.0
     - conda-forge::cattrs ==1.1.1
+    - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg
     - conda-forge::jsmin
     - conda-forge::jsonpickle ==1.2
     - conda-forge::networkx

environment_mac.yml

@@ -12,6 +12,7 @@ dependencies:
     - conda-forge::importlib-metadata <7.1.0
     - conda-forge::cattrs ==1.1.1
     - conda-forge::h5py
+    - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg
     - conda-forge::jsmin
     - conda-forge::jsonpickle ==1.2
     - conda-forge::keras <2.10.0,>=2.9.0rc0  # Required by tensorflow-macos

environment_no_cuda.yml

@@ -13,6 +13,7 @@ dependencies:
     # Packages SLEAP uses directly
     - conda-forge::attrs >=21.2.0  #,<=21.4.0
     - conda-forge::cattrs ==1.1.1
+    - conda-forge::imageio-ffmpeg # Required for imageio to read/write videos with ffmpeg
     - conda-forge::jsmin
     - conda-forge::jsonpickle ==1.2
     - conda-forge::networkx

sleap/config/pipeline_form.yaml

@@ -52,7 +52,7 @@ training:
     This pipeline uses two models: a "<u>centroid</u>" model to
     locate and crop around each animal in the frame, and a
     "<u>centered-instance confidence map</u>" model for predicted node locations
-    for each individual animal predicted by the centroid model.' 
+    for each individual animal predicted by the centroid model.'
   - label: Max Instances
     name: max_instances
     type: optional_int
@@ -217,7 +217,7 @@ training:
 - name: controller_port
   label: Controller Port
   type: int
-  default: 9000 
+  default: 9000
   range: 1024,65535
 
 - name: publish_port
@@ -286,6 +286,11 @@ training:
   type: bool
   default: true
 
+- name: _keep_viz
+  label: Keep Prediction Visualization Images After Training
+  type: bool
+  default: false
+
 - name: _predict_frames
   label: Predict On
   type: list
@@ -383,7 +388,7 @@ inference:
   tracking-only:
 
 - name: batch_size
-  label: Batch Size 
+  label: Batch Size
   type: int
   default: 4
   range: 1,512
@@ -434,7 +439,7 @@ inference:
       label: Similarity Method
       type: list
       default: instance
-      options: instance,centroid,iou
+      options: "instance,centroid,iou,object keypoint"
     - name: tracking.match
       label: Matching Method
       type: list
@@ -473,6 +478,22 @@ inference:
       label: Nodes to use for Tracking
       type: string
       default: 0,1,2
+    - type: text
+      text: '<b>Object keypoint similarity options</b>:<br />
+      Only used if this similarity method is selected.'
+    - name: tracking.oks_errors
+      label: Keypoints errors in pixels
+      help: 'Standard error in pixels of the distance for each keypoint.
+      If the list is empty, defaults to 1. If singleton list, each keypoint has
+      the same error. Otherwise, the length should be the same as the number of
+      keypoints in the skeleton.'
+      type: string
+      default:
+    - name: tracking.oks_score_weighting
+      label: Use prediction score for weighting
+      help: 'Use prediction scores to weight the similarity of each keypoint'
+      type: bool
+      default: false
     - type: text
       text: '<b>Post-tracker data cleaning</b>:'
     - name: tracking.post_connect_single_breaks
@@ -516,8 +537,8 @@ inference:
     - name: tracking.similarity
       label: Similarity Method
       type: list
-      default: iou
-      options: instance,centroid,iou
+      default: instance
+      options: "instance,centroid,iou,object keypoint"
     - name: tracking.match
       label: Matching Method
       type: list
@@ -552,6 +573,22 @@ inference:
       label: Nodes to use for Tracking
       type: string
       default: 0,1,2
+    - type: text
+      text: '<b>Object keypoint similarity options</b>:<br />
+      Only used if this similarity method is selected.'
+    - name: tracking.oks_errors
+      label: Keypoints errors in pixels
+      help: 'Standard error in pixels of the distance for each keypoint.
+      If the list is empty, defaults to 1. If singleton list, each keypoint has
+      the same error. Otherwise, the length should be the same as the number of
+      keypoints in the skeleton.'
+      type: string
+      default:
+    - name: tracking.oks_score_weighting
+      label: Use prediction score for weighting
+      help: 'Use prediction scores to weight the similarity of each keypoint'
+      type: bool
+      default: false
     - type: text
       text: '<b>Post-tracker data cleaning</b>:'
     - name: tracking.post_connect_single_breaks

sleap/config/suggestions.yaml

@@ -3,7 +3,7 @@ main:
     label: Method
     type: stacked
     default: " "
-    options: " ,image features,sample,prediction score,velocity,frame chunk"
+    options: " ,image features,sample,prediction score,velocity,frame chunk,max point displacement"
     " ":
 
     sample:
@@ -175,6 +175,13 @@ main:
         type: double
         default: 0.1
         range: 0.1,1.0
+
+    "max point displacement":
+      - name: displacement_threshold
+        label: Maximum Displacement Threshold
+        type: int
+        default: 10
+        range: 0,999
 
   - name: target
     label: Target

sleap/config/training_editor_form.yaml

@@ -44,7 +44,7 @@ model:
     label: Max Stride
     name: model.backbone.hourglass.max_stride
     type: list
-    options: 1,2,4,8,16,32,64
+    options: 1,2,4,8,16,32,64,128
   # - default: 4
   #   help: Determines the number of upsampling blocks in the network.
   #   label: Output Stride
@@ -81,7 +81,7 @@ model:
     label: Max Stride
     name: model.backbone.leap.max_stride
     type: list
-    options: 2,4,8,16,32,64
+    options: 2,4,8,16,32,64,128
   # - default: 1
   #   help: Determines the number of upsampling blocks in the network.
   #   label: Output Stride
@@ -190,7 +190,7 @@ model:
     label: Max Stride
     name: model.backbone.resnet.max_stride
     type: list
-    options: 2,4,8,16,32,64
+    options: 2,4,8,16,32,64,128
   # - default: 4
   #   help: Stride of the final output. If the upsampling branch is not defined, the
   #     output stride is controlled via dilated convolutions or reduced pooling in the
@@ -250,7 +250,7 @@ model:
     label: Max Stride
     name: model.backbone.unet.max_stride
     type: list
-    options: 2,4,8,16,32,64
+    options: 2,4,8,16,32,64,128
   # - default: 1
   #   help: Determines the number of upsampling blocks in the network.
   #   label: Output Stride