add lazy imports for DeepLabCut, with clear warning message / installation instructions

Author: deruyter92

animals/demo/vis_animals.py

@@ -46,7 +46,15 @@
     from fmpose3d.models import get_model
     CFM = get_model(args.model_type)
 
-from deeplabcut.pose_estimation_pytorch.apis import superanimal_analyze_images
+try:
+    from deeplabcut.pose_estimation_pytorch.apis import (  # pyright: ignore[reportMissingImports]
+        superanimal_analyze_images,
+    )
+except ImportError:
+    raise ImportError(
+        "DeepLabCut is required for the animal demo. "
+        "Install it with: pip install \"fmpose3d[animals]\""
+    ) from None
 
 superanimal_name = "superanimal_quadruped"
 model_name = "hrnet_w32"

fmpose3d/inference_api/fmpose3d.py

@@ -189,6 +189,20 @@ def _compute_valid_frames_mask(
 }
 
 
+def _require_superanimal_analyze_images() -> Callable[..., object]:
+    """Return DeepLabCut's SuperAnimal API or raise a clear ImportError."""
+    try:
+        from deeplabcut.pose_estimation_pytorch.apis import (  # pyright: ignore[reportMissingImports]
+            superanimal_analyze_images,
+        )
+    except ImportError:
+        raise ImportError(
+            "DeepLabCut is required for the animal 2D estimator. "
+            "Install it with: pip install \"fmpose3d[animals]\""
+        ) from None
+    return superanimal_analyze_images
+
+
 class SuperAnimalEstimator:
     """2D pose estimator for animals: DeepLabCut SuperAnimal.
 
@@ -236,9 +250,7 @@ def predict(
         """
         import cv2
         import tempfile
-        from deeplabcut.pose_estimation_pytorch.apis import (
-            superanimal_analyze_images,
-        )
+        superanimal_analyze_images = _require_superanimal_analyze_images()
 
         cfg = self.cfg
         num_frames = frames.shape[0]

tests/fmpose3d_api/conftest.py

@@ -23,6 +23,7 @@
 
 import os
 import socket
+from importlib.util import find_spec
 
 import pytest
 
@@ -72,12 +73,7 @@ def weights_ready(filename: str) -> bool:
 HUMAN_WEIGHTS_READY: bool = weights_ready(HUMAN_WEIGHTS_FILENAME)
 ANIMAL_WEIGHTS_READY: bool = weights_ready(ANIMAL_WEIGHTS_FILENAME)
 
-try:
-    import deeplabcut  # noqa: F401
-
-    DLC_AVAILABLE: bool = True
-except ImportError:
-    DLC_AVAILABLE = False
+DLC_AVAILABLE: bool = find_spec("deeplabcut") is not None
 
 # ---------------------------------------------------------------------------
 # Reusable skip markers

tests/fmpose3d_api/test_fmpose3d.py

@@ -741,6 +741,18 @@ def test_pose3d_result(self):
 
 
 class TestSuperAnimalPrediction:
+    def test_predict_raises_clear_error_without_deeplabcut(self):
+        """Missing DLC should raise a clear installation hint."""
+        estimator = SuperAnimalEstimator()
+        frames = np.random.randint(0, 255, (1, 64, 64, 3), dtype=np.uint8)
+
+        with patch(
+            "fmpose3d.inference_api.fmpose3d.importlib.util.find_spec",
+            return_value=None,
+        ):
+            with pytest.raises(ImportError, match=r"fmpose3d\[animals\]"):
+                estimator.predict(frames)
+
     def test_predict_returns_zeros_when_no_bodyparts(self):
         """When DLC detects nothing, keypoints are zero-filled."""
         pytest.importorskip("deeplabcut")