Update parameter naming superanimal_name

deruyter92 · Mar 20, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
commit ae8af5a2febe7aec8593678bfd6f0622f1e892c7
diff --git a/deeplabcut/modelzoo/video_inference.py b/deeplabcut/modelzoo/video_inference.py
@@ -367,11 +367,19 @@ def video_inference_superanimal(
         if model_name.startswith("fmpose3d"):
             logger.info("Running video inference on %s using %s", videos, model_name)
 
-            if superanimal_name:
+            recommended_superanimal_name = {
+                "fmpose3d_animals": "superanimal_quadruped",
+                "fmpose3d_humans": "superanimal_humanbody",
+            }.get(model_name)
+
+            provided_superanimal_name = superanimal_name or "<not provided>"
+            if superanimal_name != recommended_superanimal_name:
                 warnings.warn(
-                    "For FMPose3D models, 'superanimal_name' is ignored for pipeline "
-                    f"selection (selected model_name={model_name!r}, "
-                    f"superanimal_name={superanimal_name!r}).",
+                    "For FMPose3D models, model selection is driven by 'model_name'. But for API "
+                    "consistency, it is recommended to set 'superanimal_name' to the corresponding value."
+                    f"Provided superanimal_name={provided_superanimal_name!r} differs from the "
+                    f"recommended value for {model_name!r}: "
+                    f"{recommended_superanimal_name!r}.",
                     stacklevel=2,
                 )
 

diff --git a/docs/ModelZoo.md b/docs/ModelZoo.md
@@ -95,8 +95,10 @@ deeplabcut.video_inference_superanimal([video_path],
 ### Practical example: FMPose3D monocular 3D inference
 
 For FMPose3D models, use `model_name="fmpose3d_animals"` or
-`model_name="fmpose3d_humans"`. The parameter `superanimal_name` is
-accepted for API compatibility but ignored for model selection. 
+`model_name="fmpose3d_humans"`. Model selection is still determined by
+`model_name`, but to stay aligned with SuperAnimal naming conventions use:
+`superanimal_name="superanimal_quadruped"` for `fmpose3d_animals`, and
+`superanimal_name="superanimal_humanbody"` for `fmpose3d_humans`.
 
 Like the 2D superanimal models, this inference branch writes
 intermediate 2D predictions to `<video>_DLC_fmpose3d_*.h5` and `<video>_DLC_fmpose3d_*.json`. In addition, 3D predictions are saved to
@@ -109,7 +111,7 @@ import deeplabcut
 video_path = "demo-video.mp4"
 result = deeplabcut.video_inference_superanimal(
     videos=[video_path],
-    superanimal_name="",  # ignored for fmpose3d models
+    superanimal_name="superanimal_quadruped",
     model_name="fmpose3d_animals",
     batch_size=8,
     fmpose_return_3d=True,  # include 3D dataframe in returned payload