Add configurable skeleton styling and UI integration

Introduce a first-class SkeletonStyle and SkeletonColorMode (and BGR alias) in config, and wire them through the GUI and skeleton utilities. Updates include:
- dlclivegui/config.py: add BGR type, SkeletonColorMode enum, Pydantic SkeletonStyle model, expose skeleton fields on VisualizationSettings and with_overlays on RecordingSettings, and helper color accessors.
- dlclivegui/gui/main_window.py: add _apply_viz_settings_to_ui/_apply_viz_settings_to_skeleton, create a unified _draw_skeleton_on_frame renderer, read/write skeleton style from UI, refactor and simplify skeleton enable/disable and model heuristics, and wire recording.with_overlays.
- dlclivegui/gui/misc/color_dropdowns.py: reuse BGR from config.
- dlclivegui/utils/skeleton.py: remove duplicate style/type definitions, import style and enums from config, and add module docstring.

These changes centralize skeleton styling, enable UI control and persistence of style, and clean up duplicate definitions across modules.

Author: C-Achard

dlclivegui/config.py

@@ -12,6 +12,25 @@
 TileLayout = Literal["auto", "2x2", "1x4", "4x1"]
 Precision = Literal["FP32", "FP16"]
 ModelType = Literal["pytorch", "tensorflow"]
+BGR = tuple[int, int, int]  # (B, G, R) color format
+
+
+class SkeletonColorMode(str, Enum):
+    SOLID = "solid"
+    GRADIENT_KEYPOINTS = "gradient_keypoints"  # use endpoint keypoint colors
+
+
+class SkeletonStyle(BaseModel):
+    mode: SkeletonColorMode = SkeletonColorMode.SOLID
+    color: BGR = (0, 255, 255)  # default if SOLID
+    thickness: int = 2  # base thickness in pixels
+    gradient_steps: int = 16  # segments per edge when gradient
+    scale_with_zoom: bool = True  # scale thickness with (sx, sy)
+
+    def effective_thickness(self, sx: float, sy: float) -> int:
+        if not self.scale_with_zoom:
+            return max(1, int(self.thickness))
+        return max(1, int(round(self.thickness * min(sx, sy))))
 
 
 class CameraSettings(BaseModel):
@@ -301,12 +320,22 @@ class VisualizationSettings(BaseModel):
     colormap: str = "hot"
     bbox_color: tuple[int, int, int] = (0, 0, 255)
 
+    show_pose: bool = True
+    show_skeleton: bool = False
+    skeleton_style: SkeletonStyle = Field(default_factory=SkeletonStyle)
+
     def get_bbox_color_bgr(self) -> tuple[int, int, int]:
         """Get bounding box color in BGR format"""
         if isinstance(self.bbox_color, (list, tuple)) and len(self.bbox_color) == 3:
             return tuple(int(c) for c in self.bbox_color)
         return (0, 0, 255)  # default red
 
+    def get_skeleton_color_bgr(self) -> tuple[int, int, int]:
+        c = self.skeleton_style.color
+        if isinstance(c, (list, tuple)) and len(c) == 3:
+            return tuple(int(v) for v in c)
+        return (0, 255, 255)  # default yellow
+
 
 class RecordingSettings(BaseModel):
     enabled: bool = False
@@ -315,6 +344,7 @@ class RecordingSettings(BaseModel):
     container: Literal["mp4", "avi", "mov"] = "mp4"
     codec: str = "libx264"
     crf: int = Field(default=23, ge=0, le=51)
+    with_overlays: bool = False
 
     def output_path(self) -> Path:
         """Return the absolute output path for recordings."""

dlclivegui/gui/main_window.py

@@ -63,6 +63,7 @@
     VisualizationSettings,
 )
 
+from ..config import SkeletonColorMode, SkeletonStyle
 from ..processors.processor_utils import (
     default_processors_dir,
     instantiate_from_scan,
@@ -891,6 +892,45 @@ def _connect_signals(self) -> None:
 
     # ------------------------------------------------------------------
     # Config
+    # ------------------------------------------------------------------
+    def _apply_viz_settings_to_ui(self, viz: VisualizationSettings) -> None:
+        """Set UI state from VisualizationSettings (does not require skeleton to exist)."""
+        # Pose toggle
+        self.show_predictions_checkbox.blockSignals(True)
+        self.show_predictions_checkbox.setChecked(bool(viz.show_pose))
+        self.show_predictions_checkbox.blockSignals(False)
+
+        # Skeleton toggle (may remain disabled until skeleton exists)
+        self.show_skeleton_checkbox.blockSignals(True)
+        self.show_skeleton_checkbox.setChecked(bool(viz.show_skeleton))
+        self.show_skeleton_checkbox.blockSignals(False)
+
+        # Skeleton style controls (combo/spin) - set values even if disabled
+        if hasattr(self, "skeleton_color_combo"):
+            mode = viz.skeleton_style.mode.value  # "solid" or "gradient_keypoints"
+            color = tuple(viz.skeleton_style.color)
+            color_ui.set_skeleton_combo_from_style(self.skeleton_color_combo, mode=mode, color=color)
+
+        if hasattr(self, "skeleton_thickness_spin"):
+            self.skeleton_thickness_spin.blockSignals(True)
+            self.skeleton_thickness_spin.setValue(int(viz.skeleton_style.thickness))
+            self.skeleton_thickness_spin.blockSignals(False)
+
+    def _apply_viz_settings_to_skeleton(self, viz: VisualizationSettings) -> None:
+        """Apply VisualizationSettings onto the active runtime Skeleton, if present."""
+        if self._skeleton is None:
+            return
+
+        # Copy style fields
+        self._skeleton.style.mode = skel.SkeletonColorMode(viz.skeleton_style.mode.value)
+        self._skeleton.style.color = tuple(viz.skeleton_style.color)
+        self._skeleton.style.thickness = int(viz.skeleton_style.thickness)
+        self._skeleton.style.gradient_steps = int(viz.skeleton_style.gradient_steps)
+        self._skeleton.style.scale_with_zoom = bool(viz.skeleton_style.scale_with_zoom)
+
+        # Enable/disable UI controls now that skeleton exists
+        self._sync_skeleton_controls_from_model()
+
     def _apply_config(self, config: ApplicationSettings) -> None:
         # Update active cameras label
         self._update_active_cameras_label()
@@ -907,6 +947,7 @@ def _apply_config(self, config: ApplicationSettings) -> None:
         self.output_directory_edit.setText(recording.directory)
         self.filename_edit.setText(recording.filename)
         self.container_combo.setCurrentText(recording.container)
+        self.record_with_overlays_checkbox.setChecked(recording.with_overlays)
         codec_index = self.codec_combo.findText(recording.codec)
         if codec_index >= 0:
             self.codec_combo.setCurrentIndex(codec_index)
@@ -937,6 +978,7 @@ def _apply_config(self, config: ApplicationSettings) -> None:
         viz = config.visualization
         self._p_cutoff = viz.p_cutoff
         self._colormap = viz.colormap
+        self._apply_viz_settings_to_ui(viz)
         if hasattr(self, "cmap_combo"):
             color_ui.set_cmap_combo_from_name(self.cmap_combo, self._colormap, fallback="viridis")
         self._bbox_color = viz.get_bbox_color_bgr()
@@ -945,6 +987,7 @@ def _apply_config(self, config: ApplicationSettings) -> None:
         ## Skeleton
         if resolved_model_path.strip():
             self._configure_skeleton_for_model(resolved_model_path)
+        self._apply_viz_settings_to_skeleton(viz)
 
         # Update DLC camera list
         self._refresh_dlc_camera_list()
@@ -1007,6 +1050,7 @@ def _recording_settings_from_ui(self) -> RecordingSettings:
             container=self.container_combo.currentText().strip() or "mp4",
             codec=self.codec_combo.currentText().strip() or "libx264",
             crf=int(self.crf_spin.value()),
+            with_overlays=self.record_with_overlays_checkbox.isChecked(),
         )
 
     def _bbox_settings_from_ui(self) -> BoundingBoxSettings:
@@ -1019,10 +1063,29 @@ def _bbox_settings_from_ui(self) -> BoundingBoxSettings:
         )
 
     def _visualization_settings_from_ui(self) -> VisualizationSettings:
+        # Read skeleton mode+color from combo
+        mode_str, color = color_ui.get_skeleton_style_from_combo(
+            self.skeleton_color_combo,
+            fallback_mode="solid",
+            fallback_color=(0, 255, 255),
+        )
+
+        # Build SkeletonStyle (pydantic)
+        style = SkeletonStyle(
+            mode=SkeletonColorMode(mode_str),  # or SkeletonColorMode.GRADIENT_KEYPOINTS if mode_str matches
+            color=tuple(color) if color else (0, 255, 255),
+            thickness=int(self.skeleton_thickness_spin.value()),
+            gradient_steps=getattr(self._skeleton.style, "gradient_steps", 16) if self._skeleton else 16,
+            scale_with_zoom=getattr(self._skeleton.style, "scale_with_zoom", True) if self._skeleton else True,
+        )
+
         return VisualizationSettings(
             p_cutoff=self._p_cutoff,
             colormap=self._colormap,
             bbox_color=self._bbox_color,
+            show_pose=self.show_predictions_checkbox.isChecked(),
+            show_skeleton=self.show_skeleton_checkbox.isChecked(),
+            skeleton_style=style,
         )
 
     # ------------------------------------------------------------------
@@ -1286,28 +1349,16 @@ def _on_show_skeleton_changed(self, _state: int) -> None:
             self._display_frame(self._current_frame, force=True)
 
     def _on_skeleton_style_changed(self, _value: int = 0) -> None:
-        """Apply UI skeleton styling to the current Skeleton instance."""
         if self._skeleton is None:
             return
 
-        mode, color = color_ui.get_skeleton_style_from_combo(
-            self.skeleton_color_combo,
-            fallback_mode="solid",
-            fallback_color=self._skeleton.style.color,
-        )
-
-        # Update style mode
-        if mode == "gradient_keypoints":
-            self._skeleton.style.mode = skel.SkeletonColorMode.GRADIENT_KEYPOINTS
-        else:
-            self._skeleton.style.mode = skel.SkeletonColorMode.SOLID
-            if color is not None:
-                self._skeleton.style.color = tuple(color)
+        mode_str, color = color_ui.get_skeleton_style_from_combo(self.skeleton_color_combo)
+        self._skeleton.style.mode = skel.SkeletonColorMode(mode_str)
+        if self._skeleton.style.mode == skel.SkeletonColorMode.SOLID and color is not None:
+            self._skeleton.style.color = tuple(color)
 
-        # Thickness
         self._skeleton.style.thickness = int(self.skeleton_thickness_spin.value())
 
-        # Redraw
         if self._current_frame is not None:
             self._display_frame(self._current_frame, force=True)
 
@@ -1469,17 +1520,12 @@ def _render_overlays_for_recording(self, cam_id, frame):
                 offset=offset,
                 scale=scale,
             )
-
-            if self._skeleton and hasattr(self, "show_skeleton_checkbox") and self.show_skeleton_checkbox.isChecked():
-                pose_arr = np.asarray(self._last_pose.pose)
-                if pose_arr.ndim == 3:
-                    st = self._skeleton.draw_many(output, pose_arr, self._p_cutoff, offset, scale)
-                else:
-                    self._skeleton.draw(output, self._last_pose.pose, self._p_cutoff, offset, scale)
-                if st.should_disable:
-                    self.show_skeleton_checkbox.blockSignals(True)
-                    self.show_skeleton_checkbox.setChecked(False)
-                    self.show_skeleton_checkbox.blockSignals(False)
+            self._draw_skeleton_on_frame(
+                output,
+                self._last_pose.pose,
+                offset=offset,
+                scale=scale,
+            )
 
         if self._bbox_enabled:
             output = draw_bbox(
@@ -1795,7 +1841,7 @@ def _configure_skeleton_for_model(self, model_path: str) -> None:
 
         root = p if p.is_dir() else p.parent
         cfg = root / "config.yaml"
-        if cfg.exists():
+        if cfg.exists() and self._skeleton is None:
             try:
                 sk = skel.load_dlc_skeleton(cfg)
             except Exception as e:
@@ -1808,7 +1854,15 @@ def _configure_skeleton_for_model(self, model_path: str) -> None:
                 if hasattr(self, "show_skeleton_checkbox"):
                     self.show_skeleton_checkbox.setEnabled(True)
                 self.statusBar().showMessage("Skeleton available: DLC config.yaml", 3000)
-                return
+
+        if self._skeleton is not None:
+            try:
+                viz = self._config.visualization
+                self._apply_viz_settings_to_skeleton(viz)
+            except Exception as e:
+                logger.warning(f"Failed to apply visualization settings to skeleton: {e}")
+                pass
+            return
 
         # None found
         self.statusBar().showMessage("No skeleton definition available for this model.", 3000)
@@ -2126,51 +2180,59 @@ def _on_dlc_error(self, message: str) -> None:
         self._stop_inference(show_message=False)
         self._show_error(message)
 
-    def _try_draw_skeleton(self, overlay: np.ndarray, pose: np.ndarray) -> None:
+    def _draw_skeleton_on_frame(
+        self,
+        overlay: np.ndarray,
+        pose: np.ndarray,
+        *,
+        offset: tuple[int, int],
+        scale: tuple[float, float],
+        allow_auto_disable: bool = True,
+    ) -> skel.SkeletonRenderStatus | None:
+        """Draw skeleton on overlay with correct style. Optionally auto-disables UI on mismatch."""
         if self._skeleton is None:
-            return
+            return None
         if not self.show_skeleton_checkbox.isChecked():
-            return
+            return None
         if self._skeleton_auto_disabled:
-            return
+            return None
 
         pose_arr = np.asarray(pose)
 
-        # Compute keypoint colors only if gradient mode is active
+        # Provide keypoint_colors iff gradient mode is active
         kp_colors = None
-        try:
-            if self._skeleton.style.mode == skel.SkeletonColorMode.GRADIENT_KEYPOINTS:
-                n_kpts = pose_arr.shape[1] if pose_arr.ndim == 3 else pose_arr.shape[0]
-                kp_colors = keypoint_colors_bgr(self._colormap, int(n_kpts))
+        if self._skeleton.style.mode == skel.SkeletonColorMode.GRADIENT_KEYPOINTS:
+            n_kpts = pose_arr.shape[1] if pose_arr.ndim == 3 else pose_arr.shape[0]
+            kp_colors = keypoint_colors_bgr(self._colormap, int(n_kpts))
 
+        try:
             if pose_arr.ndim == 3:
                 status = self._skeleton.draw_many(
                     overlay,
                     pose_arr,
                     p_cutoff=self._p_cutoff,
-                    offset=self._dlc_tile_offset,
-                    scale=self._dlc_tile_scale,
+                    offset=offset,
+                    scale=scale,
                     keypoint_colors=kp_colors,
                 )
             else:
                 status = self._skeleton.draw(
                     overlay,
                     pose_arr,
                     p_cutoff=self._p_cutoff,
-                    offset=self._dlc_tile_offset,
-                    scale=self._dlc_tile_scale,
+                    offset=offset,
+                    scale=scale,
                     keypoint_colors=kp_colors,
                 )
-
         except Exception as e:
             status = skel.SkeletonRenderStatus(
                 code=skel.SkeletonRenderCode.POSE_SHAPE_INVALID,
                 message=f"Skeleton rendering error: {e}",
             )
 
-        if status.should_disable:
+        if allow_auto_disable and status.should_disable:
             self._skeleton_auto_disabled = True
-            msg = status.message or "Skeleton disabled due to keypoint mismatch."
+            msg = status.message or "Skeleton disabled due to mismatch."
             if msg != self._last_skeleton_disable_msg:
                 self._last_skeleton_disable_msg = msg
                 self.statusBar().showMessage(f"Skeleton disabled: {msg}", 6000)
@@ -2179,6 +2241,8 @@ def _try_draw_skeleton(self, overlay: np.ndarray, pose: np.ndarray) -> None:
             self.show_skeleton_checkbox.setChecked(False)
             self.show_skeleton_checkbox.blockSignals(False)
 
+        return status
+
     def _update_video_display(self, frame: np.ndarray) -> None:
         display_frame = frame
 
@@ -2192,7 +2256,12 @@ def _update_video_display(self, frame: np.ndarray) -> None:
                 scale=self._dlc_tile_scale,
             )
 
-            self._try_draw_skeleton(display_frame, self._last_pose.pose)
+            self._draw_skeleton_on_frame(
+                display_frame,
+                self._last_pose.pose,
+                offset=self._dlc_tile_offset,
+                scale=self._dlc_tile_scale,
+            )
 
         if self._bbox_enabled:
             display_frame = draw_bbox(

dlclivegui/gui/misc/color_dropdowns.py

@@ -24,7 +24,8 @@
     QStyleOptionComboBox,
 )
 
-BGR = tuple[int, int, int]
+from dlclivegui.config import BGR
+
 TEnum = TypeVar("TEnum")