added dd06 test support, organized 2d viewer and 3d viewer code organization.

examples/gui/__init__.py

@@ -1,20 +1,29 @@
-"""Public GUI entry points for finger examples."""
+"""Public GUI entry points for Orisys example apps.
 
-from .dashboard import FingerDashboardWindow, run_dashboard
-from .layout import (
-    LOG_CONFIG,
-    LOG_PANEL,
+Two apps live under ``examples/gui``:
+
+- Finger 3D dashboard: ``from gui import run_dashboard`` (also ``gui.viewer3d``)
+- 2D sensor monitor: ``from gui.viewer2d import run_viewer``
+
+Acquisition adapters (no widgets) live in ``gui.sensors``.
+Shared bootstrap: ``gui.app``, ``gui.app_paths``, ``gui.log_config``, ``gui.widgets``.
+"""
+
+from .log_config import LOG_CONFIG, LogConfig
+from .viewer3d import (
+    FingerDashboardWindow,
     LAYOUT,
+    LOG_PANEL,
     MESH_CONTACT_ARROW,
     MESH_LIGHTING,
     PANEL_SETUP,
     TOP_ROW,
     DashboardLayout,
-    LogConfig,
     MeshLighting,
     PanelRow,
     PanelSetup,
     PanelSlot,
+    run_dashboard,
     top_row_splitter_sizes,
     top_row_slot_index,
 )

examples/gui/log_config.py

@@ -0,0 +1,52 @@
+"""Shared log-panel configuration for Qt viewers (2D and 3D)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LogConfig:
+    """Log panel — edit LOG_CONFIG or DashboardLayout.log_config."""
+
+    status_enabled: bool = True
+    max_lines: int = 2000
+    font_family: str = "Cascadia Mono"
+    font_pt: int = 12
+    show_flow: bool = True
+    show_mask: bool = True
+
+    def format_status(
+        self,
+        *,
+        fps: float,
+        fnormal: float,
+        fshearx: float,
+        fsheary: float,
+        flow_rms: float = 0.0,
+        mask_coverage: float = 0.0,
+        wall_fps: float | None = None,
+        contact_xyz_mm: tuple[float, float, float] | None = None,
+    ) -> str:
+        shear_mag = float((fshearx**2 + fsheary**2) ** 0.5)
+        if wall_fps is not None:
+            parts = [f"FPS={wall_fps:.1f}", f"sdk={fps:.1f}"]
+        else:
+            parts = [f"FPS={fps:.1f}"]
+        parts.extend(
+            [
+                f"Fn={fnormal:.1f}",
+                f"|(Fx,Fy)|={shear_mag:.1f}",
+                f"Fx, Fy=({fshearx:.1f}, {fsheary:.1f})",
+            ]
+        )
+        force_line = "  ".join(parts)
+        if contact_xyz_mm is None:
+            contact_line = "contact=---"
+        else:
+            cx, cy, cz = contact_xyz_mm
+            contact_line = f"contact=({cx:.1f}, {cy:.1f}, {cz:.1f}) mm"
+        return f"{force_line}\n{contact_line}"
+
+
+LOG_CONFIG = LogConfig()

examples/gui/preference.json

@@ -1,5 +1,5 @@
 {
-  "video_source": "0",
+  "video_source": "D:/repo/orisys-sdk/data/dd02-0703/1.mp4",
   "config_path": "./config/dd02-ov.json",
   "finger_assets_dir": "D:/repo/orisys-sdk/assets/finger/30fps-0703",
   "csv_save_dir": "./outputs/csv",

examples/gui/sensors/__init__.py

@@ -0,0 +1,23 @@
+"""Sensor acquisition adapters for Qt / multi-sensor viewers (no Qt widgets)."""
+
+from .adapter import (
+    Dd06RoiAdapter,
+    FrameSnapshot,
+    OrisysSensorAdapter,
+    SensorAdapter,
+    calibrate_normal_force,
+    create_sensor_adapter,
+    _snapshot_from_sensor,
+)
+from . import roi_geometry
+
+__all__ = [
+    "Dd06RoiAdapter",
+    "FrameSnapshot",
+    "OrisysSensorAdapter",
+    "SensorAdapter",
+    "calibrate_normal_force",
+    "create_sensor_adapter",
+    "roi_geometry",
+    "_snapshot_from_sensor",
+]

examples/gui/sensors/adapter.py

@@ -0,0 +1,330 @@
+"""Sensor adapters that normalize frames for Qt / multi-sensor viewers."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import cv2
+import numpy as np
+import orisys
+
+from .roi_geometry import (
+    build_roi_warp,
+    load_json_config,
+    load_roi_polygon,
+    open_video_source,
+    rectified_output_size,
+    warp_roi_to_rectangle,
+)
+
+
+NORMAL_FORCE_CAL_SLOPE = 3.92685554668795e-05
+NORMAL_FORCE_CAL_OFFSET = 0.0217596967278535
+
+
+@dataclass
+class FrameSnapshot:
+    """Normalized per-frame payload consumed by the Qt viewer."""
+
+    image: Optional[np.ndarray] = None
+    flow: Optional[np.ndarray] = None
+    depth: Optional[np.ndarray] = None
+    contour: Optional[np.ndarray] = None
+    centroid: Any = None
+    # Raw SDK force channels used for curves (same units for FN/FX/FY).
+    normal_force: float = 0.0
+    shear_x: float = 0.0
+    shear_y: float = 0.0
+    # Optional calibrated FN in Newtons for export/display overlays.
+    normal_force_calibrated: float = 0.0
+    fps: float = 0.0
+    timestamp: float = 0.0
+    raw_image: Optional[np.ndarray] = None
+    processed_image: Optional[np.ndarray] = None
+    flow_overlay: Optional[np.ndarray] = None
+    record_frame: Optional[np.ndarray] = None
+
+
+def calibrate_normal_force(raw_value: float) -> float:
+    """Convert raw normal-force reading to Newtons using y = mx + c."""
+    return NORMAL_FORCE_CAL_SLOPE * float(raw_value) + NORMAL_FORCE_CAL_OFFSET
+
+
+class SensorAdapter(ABC):
+    """Common interface between Qt and concrete sensor backends."""
+
+    @abstractmethod
+    def start(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def read(self) -> Optional[FrameSnapshot]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def reset(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def close(self) -> None:
+        raise NotImplementedError
+
+
+def _bgr_from_gray_or_bgr(img: np.ndarray) -> np.ndarray:
+    if img is None:
+        return None
+    if img.ndim == 2:
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    if img.ndim == 3 and img.shape[2] == 1:
+        return cv2.cvtColor(img[:, :, 0], cv2.COLOR_GRAY2BGR)
+    return img
+
+
+def _snapshot_from_sensor(
+    sensor,
+    *,
+    raw_image=None,
+    processed_image=None,
+) -> Optional[FrameSnapshot]:
+    """Build a FrameSnapshot with HHD/forces refreshed every frame."""
+    if sensor is None or sensor.img is None:
+        return None
+
+    # Always decompose so FN/FX/FY update every frame (motion gating freezes forces).
+    sensor.compute_deformation(decompose=True, check_motion=False)
+    sensor.compute_contact()
+
+    fps, flow, vnormal, img, contour, centroid, depth_map, fnormal, fshearx, fsheary = (
+        sensor.read_info(
+            sensor.info.FPS,
+            sensor.info.VRAW,
+            sensor.info.VNORMAL,
+            sensor.info.IMG,
+            sensor.info.CONTOUR,
+            sensor.info.CENTROID,
+            sensor.info.DEPTH,
+            sensor.info.FNORMAL,
+            sensor.info.FSHEARX,
+            sensor.info.FSHEARY,
+        )
+    )
+
+    image_bgr = _bgr_from_gray_or_bgr(img)
+    processed = processed_image if processed_image is not None else image_bgr
+    record = None
+    if getattr(sensor, "frame", None) is not None:
+        record = _bgr_from_gray_or_bgr(sensor.frame)
+    elif processed is not None:
+        record = processed
+
+    flow_overlay = None
+    if image_bgr is not None and flow is not None:
+        flow_overlay = orisys.util.draw_arrows(
+            image_bgr,
+            flow,
+            threshold=2,
+            grid_spacing=20,
+            arrow_scale=0.5,
+            below_threshold_color=(160, 160, 160),
+        )
+
+    fn_raw = float(fnormal)
+    return FrameSnapshot(
+        image=image_bgr,
+        flow=flow,
+        depth=depth_map,
+        contour=contour,
+        centroid=centroid,
+        normal_force=fn_raw,
+        shear_x=float(fshearx),
+        shear_y=float(fsheary),
+        normal_force_calibrated=calibrate_normal_force(fn_raw),
+        fps=float(fps),
+        timestamp=time.time(),
+        raw_image=raw_image,
+        processed_image=processed,
+        flow_overlay=flow_overlay,
+        record_frame=record,
+    )
+
+
+class OrisysSensorAdapter(SensorAdapter):
+    """Direct orisys.Sensor capture path (compound-eye / single-camera)."""
+
+    def __init__(
+        self,
+        video,
+        config_name,
+        cal_path=None,
+        verbose=True,
+        *,
+        rotate_ccw90=False,
+        motion_threshold=1,
+    ):
+        self.video = video
+        self.config_name = config_name
+        self.cal_path = cal_path
+        self.verbose = verbose
+        self.rotate_ccw90 = bool(rotate_ccw90)
+        self.motion_threshold = motion_threshold
+        self.sensor = None
+
+    def start(self) -> None:
+        src = self.video
+        try:
+            src = int(str(src).strip())
+        except (TypeError, ValueError):
+            pass
+        self.sensor = orisys.Sensor(
+            src,
+            config_name=self.config_name,
+            cal_path=self.cal_path,
+            verbose=self.verbose,
+        )
+
+    def read(self) -> Optional[FrameSnapshot]:
+        if self.sensor is None:
+            return None
+        img = self.sensor.get_img()
+        if img is None:
+            return None
+
+        if self.rotate_ccw90:
+            self.sensor.img = cv2.rotate(self.sensor.img, cv2.ROTATE_90_COUNTERCLOCKWISE)
+            if self.sensor.frame is not None:
+                self.sensor.frame = cv2.rotate(
+                    self.sensor.frame, cv2.ROTATE_90_COUNTERCLOCKWISE
+                )
+
+        return _snapshot_from_sensor(
+            self.sensor,
+            raw_image=_bgr_from_gray_or_bgr(self.sensor.frame)
+            if self.sensor.frame is not None
+            else None,
+            processed_image=_bgr_from_gray_or_bgr(self.sensor.img),
+        )
+
+    def reset(self) -> None:
+        if self.sensor is not None:
+            self.sensor.reset()
+
+    def close(self) -> None:
+        if self.sensor is not None:
+            self.sensor.disconnect()
+            self.sensor = None
+
+
+class Dd06RoiAdapter(SensorAdapter):
+    """DD06 path: external capture + polygon ROI rectify + already_processed Sensor."""
+
+    def __init__(self, video, config_name, verbose=True, *, motion_threshold=0):
+        self.video = video
+        self.config_name = config_name
+        self.verbose = verbose
+        self.motion_threshold = motion_threshold
+        self.sensor = None
+        self.cap = None
+        self.roi_points = None
+        self.roi_image_size = None
+        self.out_size = None
+        self.warp_matrix = None
+        self.warp_src = None
+        self.last_frame_size = None
+        self._source = None
+
+    def start(self) -> None:
+        config = load_json_config(self.config_name)
+        self.roi_points, self.roi_image_size = load_roi_polygon(config)
+        self.out_size = rectified_output_size(config, self.roi_points)
+        self.sensor = orisys.Sensor(
+            "external",
+            config_name=self.config_name,
+            verbose=self.verbose,
+        )
+        self.cap, self._source = open_video_source(self.video)
+        self.warp_matrix = None
+        self.last_frame_size = None
+        if self.verbose:
+            print(
+                f"DD06 adapter: ROI points={len(self.roi_points)} "
+                f"source_size={self.roi_image_size} output={self.out_size} "
+                f"video={self._source}"
+            )
+
+    def read(self) -> Optional[FrameSnapshot]:
+        if self.sensor is None or self.cap is None:
+            return None
+
+        ok, frame = self.cap.read()
+        if not ok or frame is None:
+            return None
+
+        frame_h, frame_w = frame.shape[:2]
+        frame_size = (frame_w, frame_h)
+        if self.warp_matrix is None or self.last_frame_size != frame_size:
+            self.warp_matrix, self.warp_src, _ = build_roi_warp(
+                self.roi_points,
+                self.roi_image_size,
+                frame_size,
+                self.out_size,
+            )
+            self.last_frame_size = frame_size
+            if self.verbose:
+                print(f"Built ROI warp for frame {frame_w}x{frame_h}")
+
+        rectified = warp_roi_to_rectangle(frame, self.warp_matrix, self.out_size)
+        self.sensor.get_img(frame=rectified, already_processed=True)
+        return _snapshot_from_sensor(
+            self.sensor,
+            raw_image=frame,
+            processed_image=rectified,
+        )
+
+    def reset(self) -> None:
+        if self.sensor is not None:
+            self.sensor.reset()
+
+    def close(self) -> None:
+        if self.cap is not None:
+            self.cap.release()
+            self.cap = None
+        if self.sensor is not None:
+            self.sensor.disconnect()
+            self.sensor = None
+
+
+def create_sensor_adapter(
+    sensor_type: str,
+    *,
+    video,
+    config_name,
+    cal_path=None,
+    verbose=True,
+) -> SensorAdapter:
+    """Factory for Qt / demo viewers."""
+    kind = str(sensor_type or "orisys").strip().lower()
+    if kind in ("orisys", "direct", "default", "compound_eye", "single_camera"):
+        # Preserve historical Wuxi viewer rotation for compound-eye demos.
+        rotate = kind in ("orisys", "direct", "default", "compound_eye")
+        return OrisysSensorAdapter(
+            video,
+            config_name,
+            cal_path=cal_path,
+            verbose=verbose,
+            rotate_ccw90=rotate,
+            motion_threshold=1,
+        )
+    if kind in ("dd06", "dd06-ov", "roi", "polygon_roi"):
+        return Dd06RoiAdapter(
+            video,
+            config_name,
+            verbose=verbose,
+            motion_threshold=0,
+        )
+    raise ValueError(
+        f"Unknown sensor_type={sensor_type!r}; expected 'orisys' or 'dd06'"
+    )

examples/gui/sensors/roi_geometry.py

@@ -0,0 +1,140 @@
+"""Polygon ROI geometry helpers for rectifying tactile sensor frames."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+def load_json_config(path):
+    path = Path(path)
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def load_roi_polygon(config):
+    """Return (points Nx2 float32, image_size [w,h]) from nested or legacy ROI fields."""
+    roi = config.get("roi") if isinstance(config.get("roi"), dict) else config
+    if not isinstance(roi, dict):
+        raise ValueError("Config has no usable ROI section")
+
+    image_size = roi.get("image_size") or config.get("camera", {}).get("resolution_raw")
+    if image_size is None:
+        raise ValueError("ROI image_size is missing")
+
+    points = roi.get("points") or roi.get("polygon") or roi.get("roi_polygon")
+    if points is None and roi.get("xyxy") is not None:
+        x1, y1, x2, y2 = [int(v) for v in roi["xyxy"]]
+        points = [[x1, y1], [x2, y1], [x2, y2], [x1, y2]]
+    if not points:
+        raise ValueError("ROI points are missing")
+
+    pts = np.asarray(points, dtype=np.float32).reshape(-1, 2)
+    if pts.shape[0] < 4:
+        raise ValueError(f"ROI needs at least 4 points, got {pts.shape[0]}")
+    return pts, [int(image_size[0]), int(image_size[1])]
+
+
+def scale_points(points, source_size, target_size):
+    source_w, source_h = float(source_size[0]), float(source_size[1])
+    target_w, target_h = float(target_size[0]), float(target_size[1])
+    pts = np.asarray(points, dtype=np.float32).reshape(-1, 2).copy()
+    if source_w > 0 and source_h > 0 and (source_w, source_h) != (target_w, target_h):
+        pts[:, 0] *= target_w / source_w
+        pts[:, 1] *= target_h / source_h
+    return pts
+
+
+def order_quad_points(points):
+    """Order 4 points as TL, TR, BR, BL for perspective transforms."""
+    pts = np.asarray(points, dtype=np.float32).reshape(-1, 2)
+    if pts.shape[0] != 4:
+        hull = cv2.convexHull(pts.astype(np.float32))
+        rect = cv2.minAreaRect(hull)
+        pts = cv2.boxPoints(rect).astype(np.float32)
+
+    s = pts.sum(axis=1)
+    diff = np.diff(pts, axis=1).reshape(-1)
+    ordered = np.zeros((4, 2), dtype=np.float32)
+    ordered[0] = pts[np.argmin(s)]  # top-left
+    ordered[2] = pts[np.argmax(s)]  # bottom-right
+    ordered[1] = pts[np.argmin(diff)]  # top-right
+    ordered[3] = pts[np.argmax(diff)]  # bottom-left
+    return ordered
+
+
+def rectified_output_size(config, points=None):
+    """Prefer camera.resolution_stitch; fall back to ROI bounding box size."""
+    stitch = config.get("camera", {}).get("resolution_stitch")
+    if stitch is not None and len(stitch) >= 2:
+        return int(stitch[0]), int(stitch[1])
+    if points is not None:
+        pts = np.asarray(points, dtype=np.float32).reshape(-1, 2)
+        width = max(
+            int(np.linalg.norm(pts[1] - pts[0])),
+            int(np.linalg.norm(pts[2] - pts[3])),
+            1,
+        )
+        height = max(
+            int(np.linalg.norm(pts[3] - pts[0])),
+            int(np.linalg.norm(pts[2] - pts[1])),
+            1,
+        )
+        return width, height
+    raise ValueError("Cannot determine rectified output size")
+
+
+def build_roi_warp(points, source_image_size, frame_size, output_size):
+    """
+    Build a perspective transform that maps the ROI polygon in frame coords
+    onto a rectangle of ``output_size`` (width, height).
+    """
+    frame_w, frame_h = int(frame_size[0]), int(frame_size[1])
+    scaled = scale_points(points, source_image_size, (frame_w, frame_h))
+    src = order_quad_points(scaled)
+    out_w, out_h = int(output_size[0]), int(output_size[1])
+    dst = np.array(
+        [
+            [0.0, 0.0],
+            [out_w - 1.0, 0.0],
+            [out_w - 1.0, out_h - 1.0],
+            [0.0, out_h - 1.0],
+        ],
+        dtype=np.float32,
+    )
+    matrix = cv2.getPerspectiveTransform(src, dst)
+    return matrix, src, (out_w, out_h)
+
+
+def warp_roi_to_rectangle(frame, matrix, output_size):
+    out_w, out_h = int(output_size[0]), int(output_size[1])
+    return cv2.warpPerspective(
+        frame,
+        matrix,
+        (out_w, out_h),
+        flags=cv2.INTER_LINEAR,
+        borderMode=cv2.BORDER_REPLICATE,
+    )
+
+
+def open_video_source(video):
+    """Open a camera index or video file. Returns (cap, resolved_source)."""
+    text = str(video).strip()
+    if text.isdigit():
+        source = int(text)
+        cap = cv2.VideoCapture(source, cv2.CAP_DSHOW)
+        if not cap.isOpened():
+            cap.release()
+            cap = cv2.VideoCapture(source)
+    else:
+        path = Path(text)
+        if not path.exists():
+            raise FileNotFoundError(f"Video not found: {path}")
+        source = str(path)
+        cap = cv2.VideoCapture(source)
+    if not cap.isOpened():
+        raise RuntimeError(f"Failed to open video source: {video}")
+    return cap, source

examples/gui/viewer2d/__init__.py

@@ -0,0 +1,24 @@
+"""2D Qt sensor monitor (image + force curves; no finger 3D mesh)."""
+
+from .backend import (
+    ForceHistory,
+    ForcePlotState,
+    QtViewerBackend,
+    ViewerFrame,
+    image_shape_meta,
+    panel_width_for_aspect,
+    select_display_image,
+)
+from .window import QtViewerWindow, run_viewer
+
+__all__ = [
+    "ForceHistory",
+    "ForcePlotState",
+    "QtViewerBackend",
+    "QtViewerWindow",
+    "ViewerFrame",
+    "image_shape_meta",
+    "panel_width_for_aspect",
+    "run_viewer",
+    "select_display_image",
+]

examples/gui/viewer2d/backend.py

@@ -0,0 +1,312 @@
+"""Qt-facing display backend for sensor viewer snapshots.
+
+Separates acquisition (`gui.sensors.FrameSnapshot`) from Qt display state:
+normalized images, force history / filtering, and aspect-ratio metadata.
+Does not import camera, ROI, or `orisys.Sensor`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Tuple
+
+import cv2
+import numpy as np
+from scipy.signal import butter, filtfilt
+
+FORCE_SAMPLE_RATE_HZ = 30.0
+PLOT_BUFFER_POINTS = 120
+PLOT_WINDOW_SEC = PLOT_BUFFER_POINTS / FORCE_SAMPLE_RATE_HZ
+Y_AXIS_MIN_SPAN = 20000.0
+
+
+@dataclass
+class ViewerFrame:
+    """Normalized display payload for one UI tick."""
+
+    display_image: np.ndarray
+    image_height: int
+    image_width: int
+    aspect_ratio: float  # width / height
+    depth: Optional[np.ndarray]
+    normal_force: float
+    shear_x: float
+    shear_y: float
+    normal_force_calibrated: float
+    fps: float
+    timestamp: float
+    record_frame: Optional[np.ndarray]
+
+
+@dataclass
+class ForcePlotState:
+    """Filtered force series ready for pyqtgraph curves."""
+
+    times: np.ndarray  # shape (n,)
+    values: np.ndarray  # shape (n, 3)  FN, FX, FY
+    sample_count: int
+    x_range: Tuple[float, float]
+    y_ranges: Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]
+
+
+def lowpass_filter(
+    data,
+    cutoff_hz: float,
+    sample_rate_hz: float = FORCE_SAMPLE_RATE_HZ,
+    order: int = 2,
+) -> np.ndarray:
+    """Zero-phase Butterworth low-pass for uniformly sampled 1-D data."""
+    y = np.asarray(data, dtype=np.float64)
+    if cutoff_hz == 0:
+        return y.copy()
+    if y.size == 0:
+        return y
+
+    nyquist = 0.5 * sample_rate_hz
+    if cutoff_hz < 0 or cutoff_hz >= nyquist:
+        raise ValueError(
+            f"cutoff_hz must be in (0, {nyquist}) for sample_rate_hz={sample_rate_hz}"
+        )
+
+    b, a = butter(order, cutoff_hz / nyquist, btype="low")
+    padlen = 3 * (max(len(b), len(a)) - 1)
+    if y.size <= padlen:
+        return y.copy()
+    return filtfilt(b, a, y)
+
+
+def ensure_bgr(img: Optional[np.ndarray]) -> Optional[np.ndarray]:
+    if img is None:
+        return None
+    if img.ndim == 2:
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    if img.ndim == 3 and img.shape[2] == 1:
+        return cv2.cvtColor(img[:, :, 0], cv2.COLOR_GRAY2BGR)
+    return img
+
+
+def image_shape_meta(img: np.ndarray) -> Tuple[int, int, float]:
+    """Return (height, width, width/height) from a display image."""
+    h, w = int(img.shape[0]), int(img.shape[1])
+    aspect = float(w) / float(h) if h > 0 else 1.0
+    return h, w, aspect
+
+
+def select_display_image(snapshot) -> np.ndarray:
+    """Pick flow overlay / processed / raw image for the left panel."""
+    arrows = getattr(snapshot, "flow_overlay", None)
+    if arrows is not None:
+        out = ensure_bgr(arrows)
+        if out is not None:
+            return out
+
+    for attr in ("processed_image", "image", "raw_image"):
+        base = getattr(snapshot, attr, None)
+        out = ensure_bgr(base)
+        if out is not None:
+            return out
+
+    return np.zeros((400, 400, 3), dtype=np.uint8)
+
+
+def bgr_to_rgb_bytes(img_bgr: np.ndarray) -> Tuple[np.ndarray, int, int]:
+    """Convert BGR uint8 image to contiguous RGB for QImage."""
+    rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)
+    if not rgb.flags["C_CONTIGUOUS"]:
+        rgb = np.ascontiguousarray(rgb)
+    h, w = rgb.shape[:2]
+    return rgb, h, w
+
+
+def scale_bgr_to_fit(
+    img_bgr: np.ndarray,
+    max_w: int,
+    max_h: int,
+) -> np.ndarray:
+    """Resize preserving aspect ratio to fit inside (max_w, max_h)."""
+    if max_w <= 0 or max_h <= 0:
+        return img_bgr
+    h, w = img_bgr.shape[:2]
+    if h <= 0 or w <= 0:
+        return img_bgr
+    scale = min(max_w / float(w), max_h / float(h))
+    if abs(scale - 1.0) < 1e-6:
+        return img_bgr
+    nw = max(1, int(round(w * scale)))
+    nh = max(1, int(round(h * scale)))
+    return cv2.resize(img_bgr, (nw, nh), interpolation=cv2.INTER_AREA)
+
+
+def panel_width_for_aspect(
+    available_height: int,
+    aspect_ratio: float,
+    *,
+    min_size: int = 160,
+) -> int:
+    """Preferred left-panel width given available height and image aspect."""
+    h = max(int(available_height), min_size)
+    w = int(round(h * float(aspect_ratio)))
+    return max(w, min_size)
+
+
+class ForceHistory:
+    """Ring-style force history buffer with filtering and y-range smoothing."""
+
+    def __init__(
+        self,
+        npoints: int = PLOT_BUFFER_POINTS,
+        *,
+        sample_rate_hz: float = FORCE_SAMPLE_RATE_HZ,
+        lowpass_cutoff_hz: float = 10.0,
+        y_axis_min_span: float = Y_AXIS_MIN_SPAN,
+        y_range_alpha: float = 0.5,
+    ):
+        self.npoints = int(npoints)
+        self.sample_rate_hz = float(sample_rate_hz)
+        self.lowpass_cutoff_hz = float(lowpass_cutoff_hz)
+        self.y_axis_min_span = float(y_axis_min_span)
+        self.y_range_alpha = float(y_range_alpha)
+        self.window_sec = self.npoints / self.sample_rate_hz
+        self.reset()
+
+    def reset(self) -> None:
+        self.data = np.full((self.npoints, 2, 3), np.nan, dtype=np.float64)
+        self.sample_count = 0
+        self._y_range_smooth = [None, None, None]
+
+    def push(self, t: float, fn: float, fx: float, fy: float) -> None:
+        values = (float(fn), float(fx), float(fy))
+        if self.sample_count < self.npoints:
+            idx = self.sample_count
+            self.data[idx, 0, :] = t
+            self.data[idx, 1, :] = values
+            self.sample_count += 1
+            return
+
+        self.data[:-1, 0, :] = self.data[1:, 0, :]
+        self.data[:-1, 1, :] = self.data[1:, 1, :]
+        self.data[-1, 0, :] = t
+        self.data[-1, 1, :] = values
+
+    def _smooth_y_range(self, channel: int, ymin: float, ymax: float) -> Tuple[float, float]:
+        if self._y_range_smooth[channel] is None:
+            smoothed = (ymin, ymax)
+        else:
+            prev_min, prev_max = self._y_range_smooth[channel]
+            alpha = self.y_range_alpha
+            ymin = alpha * ymin + (1.0 - alpha) * prev_min
+            ymax = alpha * ymax + (1.0 - alpha) * prev_max
+            smoothed = (ymin, ymax)
+
+        span = smoothed[1] - smoothed[0]
+        if span < self.y_axis_min_span:
+            mid = 0.5 * (smoothed[0] + smoothed[1])
+            half = self.y_axis_min_span / 2.0
+            smoothed = (mid - half, mid + half)
+
+        self._y_range_smooth[channel] = smoothed
+        pad = max((smoothed[1] - smoothed[0]) * 0.12, 0.01)
+        return smoothed[0] - pad, smoothed[1] + pad
+
+    def plot_state(self) -> Optional[ForcePlotState]:
+        n = self.sample_count
+        if n == 0:
+            return None
+
+        data_plot = self.data[:n].copy()
+        for i in range(3):
+            data_plot[:, 1, i] = lowpass_filter(
+                data_plot[:, 1, i],
+                self.lowpass_cutoff_hz,
+                sample_rate_hz=self.sample_rate_hz,
+            )
+
+        times = data_plot[:, 0, 0].copy()
+        values = data_plot[:, 1, :].copy()
+        y_ranges = tuple(
+            self._smooth_y_range(i, float(values[:, i].min()), float(values[:, i].max()))
+            for i in range(3)
+        )
+
+        if n < self.npoints:
+            x_range = (0.0, self.window_sec)
+        else:
+            x0 = float(times[0])
+            x1 = float(times[-1])
+            if x1 <= x0:
+                x1 = x0 + self.window_sec
+            x_range = (x0, x1)
+
+        return ForcePlotState(
+            times=times,
+            values=values,
+            sample_count=n,
+            x_range=x_range,
+            y_ranges=y_ranges,  # type: ignore[arg-type]
+        )
+
+
+class QtViewerBackend:
+    """Normalize FrameSnapshot into display images + force history."""
+
+    def __init__(
+        self,
+        *,
+        npoints: int = PLOT_BUFFER_POINTS,
+        lowpass_cutoff_hz: float = 10.0,
+        y_axis_min_span: float = Y_AXIS_MIN_SPAN,
+    ):
+        self.force_history = ForceHistory(
+            npoints=npoints,
+            lowpass_cutoff_hz=lowpass_cutoff_hz,
+            y_axis_min_span=y_axis_min_span,
+        )
+        self._start_time: Optional[float] = None
+        self.last_viewer_frame: Optional[ViewerFrame] = None
+
+    def reset(self) -> None:
+        self.force_history.reset()
+        self._start_time = None
+        self.last_viewer_frame = None
+
+    def ingest(self, snapshot, *, now: Optional[float] = None) -> ViewerFrame:
+        """Convert a FrameSnapshot into ViewerFrame and update force history."""
+        display = select_display_image(snapshot)
+        h, w, aspect = image_shape_meta(display)
+
+        fn = float(getattr(snapshot, "normal_force", 0.0))
+        fx = float(getattr(snapshot, "shear_x", 0.0))
+        fy = float(getattr(snapshot, "shear_y", 0.0))
+        fn_cal = float(getattr(snapshot, "normal_force_calibrated", 0.0))
+        fps = float(getattr(snapshot, "fps", 0.0))
+        ts = float(getattr(snapshot, "timestamp", 0.0) or 0.0)
+        if now is None:
+            now = ts if ts > 0 else 0.0
+
+        if self._start_time is None:
+            self._start_time = now
+        t = now - self._start_time
+        self.force_history.push(t, fn, fx, fy)
+
+        record = ensure_bgr(getattr(snapshot, "record_frame", None))
+        depth = getattr(snapshot, "depth", None)
+
+        frame = ViewerFrame(
+            display_image=display,
+            image_height=h,
+            image_width=w,
+            aspect_ratio=aspect,
+            depth=depth,
+            normal_force=fn,
+            shear_x=fx,
+            shear_y=fy,
+            normal_force_calibrated=fn_cal,
+            fps=fps,
+            timestamp=ts,
+            record_frame=record,
+        )
+        self.last_viewer_frame = frame
+        return frame
+
+    def plot_state(self) -> Optional[ForcePlotState]:
+        return self.force_history.plot_state()

examples/gui/viewer2d/styles.py

@@ -0,0 +1,120 @@
+"""Styles for the 2D Qt sensor monitor."""
+
+CURVE_THEME_COLOR = "#00E5FF"
+
+STYLE = """
+QMainWindow {
+    background-color: #000000;
+}
+
+/* ---- 图像面板 ---- */
+QLabel#arrowsLabel {
+    border: 1px solid #262626;
+    border-radius: 4px;
+    background-color: #0b0b0b;
+}
+
+/* ---- 顶栏按钮 & 输入 ---- */
+QPushButton {
+    background-color: #1a1a1a;
+    color: #999999;
+    border: 1px solid #333333;
+    border-radius: 4px;
+    padding: 6px 16px;
+    font-family: "SimHei";
+    font-size: 13px;
+}
+QPushButton:hover {
+    background-color: #262626;
+    color: #cccccc;
+    border: 1px solid #555555;
+}
+QPushButton#btnStart {
+    background-color: #0d2818;
+    color: #4caf84;
+    border: 1px solid #1a4d30;
+}
+QPushButton#btnStart:hover {
+    background-color: #143d24;
+    color: #6fd4a0;
+}
+QPushButton#btnStart:disabled {
+    background-color: #0f0f0f;
+    color: #333333;
+    border: 1px solid #222222;
+}
+QPushButton#btnStop {
+    background-color: #2b1010;
+    color: #e05555;
+    border: 1px solid #4d1a1a;
+}
+QPushButton#btnStop:hover {
+    background-color: #3d1818;
+    color: #f07070;
+}
+QPushButton#btnStop:disabled {
+    background-color: #0f0f0f;
+    color: #333333;
+    border: 1px solid #222222;
+}
+QLineEdit {
+    background-color: #0d0d0d;
+    color: #999999;
+    border: 1px solid #333333;
+    border-radius: 4px;
+    padding: 5px 10px;
+    font-size: 13px;
+}
+
+/* ---- 力曲线容器 ---- */
+GraphicsLayoutWidget {
+    border: 1px solid #262626;
+    border-radius: 4px;
+}
+
+/* ---- 日志面板 ---- */
+QPlainTextEdit {
+    background-color: #0b0b0b;
+    color: #777777;
+    border: 1px solid #262626;
+    border-radius: 4px;
+    font-family: "Cascadia Code", "Consolas", "Courier New", monospace;
+    font-size: 13px;
+    padding: 8px;
+    selection-background-color: #1a3a4a;
+    selection-color: #cccccc;
+}
+
+QPlainTextEdit QScrollBar:vertical {
+    background-color: #0b0b0b;
+    width: 6px;
+    margin: 1px;
+    border-radius: 3px;
+}
+QPlainTextEdit QScrollBar::handle:vertical {
+    background-color: #262626;
+    border-radius: 3px;
+    min-height: 30px;
+}
+QPlainTextEdit QScrollBar::handle:vertical:hover {
+    background-color: #3a3a3a;
+}
+QPlainTextEdit QScrollBar::add-line:vertical,
+QPlainTextEdit QScrollBar::sub-line:vertical {
+    height: 0px;
+}
+QPlainTextEdit QScrollBar::add-page:vertical,
+QPlainTextEdit QScrollBar::sub-page:vertical {
+    background: none;
+}
+
+QSplitter::handle {
+    background-color: #1a1a1a;
+}
+QSplitter::handle:vertical {
+    height: 1px;
+}
+QSplitter::handle:horizontal {
+    width: 1px;
+}
+"""

examples/gui/viewer2d/window.py

@@ -0,0 +1,491 @@
+"""2D Qt sensor monitor window (image + force curves)."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+import cv2
+from PyQt5.QtCore import Qt, QTimer
+from PyQt5.QtGui import QFont, QIcon
+from PyQt5.QtWidgets import (
+    QApplication,
+    QFileDialog,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QMainWindow,
+    QPushButton,
+    QSplitter,
+    QVBoxLayout,
+    QWidget,
+)
+
+try:
+    import pyqtgraph as pg
+except Exception as exc:  # pragma: no cover
+    raise ImportError(
+        "PyQtGraph is not installed. Please install it using 'pip install pyqt5 pyqtgraph'."
+    ) from exc
+
+from gui.sensors import create_sensor_adapter
+from gui.widgets.log_panel import TeeStream, WidgetLogHandler, make_log_widget
+from gui.widgets.qt_pixmap import ndarray_to_pixmap, pixmap_keep_aspect
+
+from .backend import PLOT_BUFFER_POINTS, PLOT_WINDOW_SEC, QtViewerBackend, panel_width_for_aspect
+from .styles import CURVE_THEME_COLOR, STYLE
+
+
+class QtViewerWindow(QMainWindow):
+    """2D monitor: flow/image panel + FN/FX/FY curves driven by QtViewerBackend."""
+
+    def __init__(self, args, log_file):
+        super().__init__()
+        self.setWindowTitle("Orisys SDK")
+        self.setStyleSheet(STYLE)
+
+        logo_path = Path(__file__).resolve().parents[3] / "logo.png"
+        if logo_path.exists():
+            self.setWindowIcon(QIcon(str(logo_path)))
+
+        self.sensor_adapter = None
+        self._last_snapshot = None
+        self._last_viewer_frame = None
+        self._display_aspect = 1.0
+        self._source_pixmap = None
+        self.args = args
+
+        self.is_save = False
+        self.frame_count = 0
+        self.writer = None
+        self.save_path = None
+
+        self.viewer_backend = QtViewerBackend(
+            npoints=PLOT_BUFFER_POINTS,
+            lowpass_cutoff_hz=getattr(args, "cutoff", 10.0),
+        )
+
+        self._setup_ui()
+        self._create_plots()
+
+        self.camera_edit.setText(args.video)
+        self.config_edit.setText(args.config)
+        self.cal_edit.setText(args.cal)
+
+        self.log_handler = WidgetLogHandler(self.log_widget)
+        sys.stdout = TeeStream(log_file, self.log_handler)
+        sys.stderr = sys.stdout
+
+        self.timer = QTimer()
+        self.timer.timeout.connect(self._on_timer)
+        self._running = False
+
+    def _setup_ui(self):
+        central = QWidget()
+        self.setCentralWidget(central)
+        root_layout = QVBoxLayout(central)
+        root_layout.setContentsMargins(6, 6, 6, 6)
+        root_layout.setSpacing(6)
+
+        bar = QHBoxLayout()
+        bar.setSpacing(8)
+
+        self.btn_camera = QPushButton("摄像机")
+        self.btn_camera.setObjectName("btnCamera")
+        self.btn_camera.clicked.connect(self._select_camera)
+        bar.addWidget(self.btn_camera)
+        self.camera_edit = QLineEdit("1")
+        self.camera_edit.setPlaceholderText("摄像头编号 或 视频路径")
+        bar.addWidget(self.camera_edit, 1)
+
+        self.btn_config = QPushButton("配置")
+        self.btn_config.setObjectName("btnConfig")
+        self.btn_config.clicked.connect(self._select_config)
+        bar.addWidget(self.btn_config)
+        self.config_edit = QLineEdit("./config/ddjx01.json")
+        bar.addWidget(self.config_edit, 1)
+
+        self.btn_reset = QPushButton("重置")
+        self.btn_reset.setObjectName("btnReset")
+        self.btn_reset.setEnabled(False)
+        self.btn_reset.clicked.connect(self._on_reset)
+        bar.addWidget(self.btn_reset)
+        self.cal_edit = QLineEdit("./config/ddjx01.npy")
+        bar.addWidget(self.cal_edit, 1)
+
+        self.btn_start = QPushButton("启动")
+        self.btn_start.setObjectName("btnStart")
+        self.btn_start.clicked.connect(self._on_start)
+        bar.addWidget(self.btn_start)
+
+        self.btn_stop = QPushButton("暂停")
+        self.btn_stop.setObjectName("btnStop")
+        self.btn_stop.setEnabled(False)
+        self.btn_stop.clicked.connect(self._on_stop)
+        bar.addWidget(self.btn_stop)
+
+        root_layout.addLayout(bar)
+
+        v_splitter = QSplitter(Qt.Vertical)
+        h_splitter = QSplitter(Qt.Horizontal)
+
+        left = QWidget()
+        left_layout = QVBoxLayout(left)
+        left_layout.setContentsMargins(0, 0, 0, 0)
+        left_layout.setSpacing(6)
+
+        self.arrows_label = QLabel()
+        self.arrows_label.setObjectName("arrowsLabel")
+        self.arrows_label.setMinimumSize(160, 160)
+        self.arrows_label.setScaledContents(False)
+        self.arrows_label.setAlignment(Qt.AlignCenter)
+        left_layout.addWidget(self.arrows_label)
+
+        h_splitter.addWidget(left)
+
+        pg.setConfigOption("background", "#000000")
+        pg.setConfigOption("foreground", "#777777")
+        pg.setConfigOptions(antialias=True)
+        self.graph_widget = pg.GraphicsLayoutWidget()
+        self.graph_widget.setMinimumWidth(300)
+        h_splitter.addWidget(self.graph_widget)
+
+        self.h_splitter = h_splitter
+        v_splitter.addWidget(h_splitter)
+
+        from gui.log_config import LOG_CONFIG
+
+        self.log_widget = make_log_widget(LOG_CONFIG)
+        v_splitter.addWidget(self.log_widget)
+
+        v_splitter.setStretchFactor(0, 4)
+        v_splitter.setStretchFactor(1, 1)
+        root_layout.addWidget(v_splitter)
+
+    def _create_plots(self):
+        titles = ["法向力 (raw)", "切向力 X", "切向力 Y"]
+        self.plots = []
+        self.curves = []
+        self.dot_glows = []
+        self.dot_cores = []
+
+        axis_pen = pg.mkPen(color=(38, 38, 38), width=1)
+        label_font = QFont("SimHei", 9)
+
+        for i, title in enumerate(titles):
+            p = self.graph_widget.addPlot(title=None)
+            p.setTitle(title, color="#999999", size="14pt")
+            p.titleLabel.setFont(QFont("SimHei", 14))
+            p.setLabel("bottom", "时间", units="s")
+            p.getAxis("bottom").label.setFont(label_font)
+            p.showAxis("top", False)
+            p.showAxis("right", False)
+            p.getAxis("left").setPen(axis_pen)
+            p.getAxis("bottom").setPen(axis_pen)
+            p.showGrid(x=False, y=True, alpha=0.12)
+
+            tick_font = QFont("Consolas", 11)
+            tick_font.setStyleHint(QFont.Monospace)
+            p.getAxis("left").setTickFont(tick_font)
+            p.getAxis("bottom").setTickFont(tick_font)
+
+            line_pen = pg.mkPen(color=CURVE_THEME_COLOR, width=2)
+            curve = p.plot(pen=line_pen, fillLevel=0)
+            dot_glow = p.plot(
+                [],
+                [],
+                pen=None,
+                symbol="o",
+                symbolSize=8,
+                symbolPen=None,
+                symbolBrush=(0, 229, 255, 76),
+            )
+            dot_core = p.plot(
+                [],
+                [],
+                pen=None,
+                symbol="o",
+                symbolSize=4,
+                symbolPen=None,
+                symbolBrush=(255, 255, 255, 255),
+            )
+
+            p.setXRange(0, PLOT_WINDOW_SEC, padding=0)
+            p.enableAutoRange(x=False, y=False)
+
+            self.plots.append(p)
+            self.curves.append(curve)
+            self.dot_glows.append(dot_glow)
+            self.dot_cores.append(dot_core)
+
+            if i < 2:
+                self.graph_widget.nextRow()
+
+    def adjust_image_panel(self):
+        """Size the left panel from the current image aspect ratio."""
+        top_bar_h = 48
+        log_h = self.log_widget.height()
+        spacing = 20
+        available = max(self.height() - top_bar_h - log_h - spacing, 160)
+        image_w = panel_width_for_aspect(available, self._display_aspect, min_size=160)
+        max_w = max(self.width() // 2, 160)
+        image_w = min(image_w, max_w)
+        self.h_splitter.setSizes([image_w, max(self.width() - image_w, 200)])
+        self._render_display_pixmap()
+
+    def resizeEvent(self, event):
+        super().resizeEvent(event)
+        self._render_display_pixmap()
+
+    def _render_display_pixmap(self):
+        if self._source_pixmap is None or self._source_pixmap.isNull():
+            return
+        target = self.arrows_label.size()
+        if target.width() < 2 or target.height() < 2:
+            return
+        self.arrows_label.setPixmap(pixmap_keep_aspect(self._source_pixmap, target))
+
+    def _on_timer(self):
+        if self.sensor_adapter is None:
+            return
+
+        snapshot = self.sensor_adapter.read()
+        if snapshot is None:
+            print("Failed to get image")
+            return
+        self._last_snapshot = snapshot
+
+        viewer_frame = self.viewer_backend.ingest(snapshot, now=time.time())
+        self._last_viewer_frame = viewer_frame
+        first_image = self._source_pixmap is None
+        aspect_changed = abs(viewer_frame.aspect_ratio - self._display_aspect) > 1e-3
+        self._display_aspect = viewer_frame.aspect_ratio
+
+        if self.is_save and self.writer is not None and snapshot.record_frame is not None:
+            self.frame_count += 1
+            save_img = snapshot.record_frame
+            if len(save_img.shape) == 2 or (
+                len(save_img.shape) == 3 and save_img.shape[2] == 1
+            ):
+                if len(save_img.shape) == 3:
+                    save_img = save_img.squeeze(2)
+                save_img = cv2.cvtColor(save_img, cv2.COLOR_GRAY2BGR)
+            self.writer.write(save_img)
+
+        print(
+            f"FPS={viewer_frame.fps:.2f}, "
+            f"法向力(raw)={viewer_frame.normal_force:.4f}, "
+            f"切向力X={viewer_frame.shear_x:.4f}, "
+            f"切向力Y={viewer_frame.shear_y:.4f}, "
+            f"法向力(N)={viewer_frame.normal_force_calibrated:.6f}"
+        )
+
+        self._source_pixmap = ndarray_to_pixmap(viewer_frame.display_image, bgr=True)
+        if first_image or aspect_changed:
+            self.adjust_image_panel()
+        else:
+            self._render_display_pixmap()
+
+        plot_state = self.viewer_backend.plot_state()
+        if plot_state is None:
+            return
+
+        for i, curve in enumerate(self.curves):
+            x = plot_state.times
+            y = plot_state.values[:, i]
+            curve.setData(x, y)
+            ymin, ymax = plot_state.y_ranges[i]
+            self.plots[i].setYRange(ymin, ymax)
+            self.dot_glows[i].setData(x[-1:], y[-1:])
+            self.dot_cores[i].setData(x[-1:], y[-1:])
+
+        x0, x1 = plot_state.x_range
+        for p in self.plots:
+            p.setXRange(x0, x1, padding=0)
+
+    def _on_start(self):
+        if self._running:
+            return
+        self.btn_start.setText("启动中...")
+        self.btn_start.setEnabled(False)
+        QApplication.processEvents()
+
+        try:
+            src = self.camera_edit.text()
+            cfg = self.config_edit.text()
+            cal = self.cal_edit.text()
+            verbose = getattr(self.args, "verbose", True)
+            sensor_type = getattr(self.args, "sensor_type", "orisys")
+            self.sensor_adapter = create_sensor_adapter(
+                sensor_type,
+                video=src,
+                config_name=cfg,
+                cal_path=cal,
+                verbose=verbose,
+            )
+            self.sensor_adapter.start()
+        except Exception as e:
+            self.btn_start.setText("启动")
+            self.btn_start.setEnabled(True)
+            self.sensor_adapter = None
+            print(f"启动失败: {e}")
+            return
+
+        self.viewer_backend.reset()
+        self._running = True
+        self.timer.start(10)
+        self.btn_start.setText("启动")
+        self.btn_stop.setEnabled(True)
+        self.btn_reset.setEnabled(True)
+        print(
+            f"▶ 启动 — sensor_type={getattr(self.args, 'sensor_type', 'orisys')}, "
+            f"摄像机={src}, 配置={cfg}, 标定={cal}"
+        )
+
+    def _on_stop(self):
+        if not self._running:
+            return
+        self._running = False
+        self.timer.stop()
+        self.btn_stop.setText("停止中...")
+        self.btn_stop.setEnabled(False)
+        QApplication.processEvents()
+
+        if self.sensor_adapter is not None:
+            self.sensor_adapter.close()
+            self.sensor_adapter = None
+        self._last_snapshot = None
+
+        self.btn_start.setEnabled(True)
+        self.btn_stop.setText("暂停")
+        self.btn_reset.setEnabled(False)
+        print("⏸ 已暂停")
+
+    def _select_camera(self):
+        path, _ = QFileDialog.getOpenFileName(
+            self,
+            "选择视频文件",
+            "data",
+            "视频 (*.mp4 *.avi *.mov);;所有文件 (*)",
+        )
+        if path:
+            self.camera_edit.setText(path)
+
+    def _select_config(self):
+        path, _ = QFileDialog.getOpenFileName(
+            self,
+            "选择配置文件",
+            "config",
+            "JSON (*.json);;所有文件 (*)",
+        )
+        if path:
+            self.config_edit.setText(path)
+
+    def _on_reset(self):
+        if self.sensor_adapter is None or not self._running:
+            print("请先启动传感器后再重置追踪器。")
+            return
+        self.sensor_adapter.reset()
+        print("追踪器已重置。")
+
+    def keyPressEvent(self, event):
+        key = event.key()
+        if key == Qt.Key_Escape:
+            if self.isFullScreen():
+                self.showNormal()
+            else:
+                self.showFullScreen()
+        elif key == Qt.Key_Q:
+            print("\n正在退出示例程序...")
+            self.close()
+        elif key == Qt.Key_S:
+            self._start_recording()
+        elif key == Qt.Key_E:
+            self._stop_recording()
+        elif key == Qt.Key_R:
+            self._on_reset()
+        else:
+            super().keyPressEvent(event)
+
+    def _start_recording(self):
+        if self.sensor_adapter is None:
+            print("请先启动采集")
+            return
+        self.save_path = "./data/pulse_test.mp4"
+        os.makedirs(os.path.dirname(self.save_path), exist_ok=True)
+
+        save_img = None
+        if self._last_snapshot is not None:
+            save_img = self._last_snapshot.record_frame
+        if save_img is None:
+            print("当前没有可用帧，无法确定录像尺寸。")
+            return
+
+        temp_img = save_img.copy()
+        if len(temp_img.shape) == 2 or (
+            len(temp_img.shape) == 3 and temp_img.shape[2] == 1
+        ):
+            if len(temp_img.shape) == 3:
+                temp_img = temp_img.squeeze(2)
+            temp_img = cv2.cvtColor(temp_img, cv2.COLOR_GRAY2BGR)
+
+        fh, fw = temp_img.shape[:2]
+        self.writer = cv2.VideoWriter(
+            self.save_path,
+            cv2.VideoWriter_fourcc(*"mp4v"),
+            30,
+            (fw, fh),
+        )
+        if self.writer.isOpened():
+            self.is_save = True
+            print(f"开始录像：{self.save_path}")
+        else:
+            print(f"无法创建录像文件：{self.save_path}")
+            self.writer = None
+
+    def _stop_recording(self):
+        self.is_save = False
+        if self.writer is not None:
+            self.writer.release()
+            self.writer = None
+        if self.save_path is not None:
+            print(f"录像结束：{self.save_path}，总帧数：{self.frame_count}")
+        else:
+            print(f"录像结束，总帧数：{self.frame_count}")
+        self.frame_count = 0
+
+    def closeEvent(self, event):
+        self.timer.stop()
+        if self.writer is not None:
+            self.writer.release()
+        if self.sensor_adapter is not None:
+            self.sensor_adapter.close()
+            self.sensor_adapter = None
+        event.accept()
+
+
+def run_viewer(args, *, log_dir: str | Path | None = None) -> int:
+    """Launch the 2D Qt viewer and block until the window closes."""
+    from gui.app import get_or_create_qapp
+
+    if log_dir is None:
+        log_dir = Path(__file__).resolve().parents[3] / "scripts" / "logs"
+    else:
+        log_dir = Path(log_dir)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = log_dir / f"qt_viewer_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
+    log_file = open(log_path, "w", encoding="utf-8")
+    sys.stdout = log_file
+    sys.stderr = sys.stdout
+
+    print("\n按键说明：Q 退出 | R 重置追踪器 | S 开始录像 | E 结束录像 | ESC 全屏")
+
+    app = get_or_create_qapp("Orisys SDK")
+    window = QtViewerWindow(args, log_file)
+    window.showFullScreen()
+    QApplication.processEvents()
+    window.adjust_image_panel()
+    return app.exec_()

examples/gui/viewer3d/__init__.py

@@ -0,0 +1,36 @@
+"""Finger 3D Qt dashboard (mesh + UV arrows + force charts)."""
+
+from .dashboard import FingerDashboardWindow, run_dashboard
+from .layout import (
+    LOG_PANEL,
+    LAYOUT,
+    MESH_CONTACT_ARROW,
+    MESH_LIGHTING,
+    PANEL_SETUP,
+    TOP_ROW,
+    DashboardLayout,
+    MeshLighting,
+    PanelRow,
+    PanelSetup,
+    PanelSlot,
+    top_row_splitter_sizes,
+    top_row_slot_index,
+)
+
+__all__ = [
+    "DashboardLayout",
+    "FingerDashboardWindow",
+    "LAYOUT",
+    "LOG_PANEL",
+    "MESH_CONTACT_ARROW",
+    "MESH_LIGHTING",
+    "MeshLighting",
+    "PANEL_SETUP",
+    "TOP_ROW",
+    "PanelRow",
+    "PanelSetup",
+    "PanelSlot",
+    "run_dashboard",
+    "top_row_splitter_sizes",
+    "top_row_slot_index",
+]

examples/gui/viewer3d/dashboard.py

@@ -21,7 +21,7 @@ from pipeline.config import PipelineConfig
 from pipeline.csv_recorder import CsvRecorder
 from pipeline.service import FingerPipeline
 
-from .app_paths import resource_path
+from gui.app_paths import resource_path
 from .camera_discovery import list_cameras, pick_default_camera
 from .preferences import get_preferred_video_source, load_preferences, save_preferences
 from .layout import (
@@ -33,14 +33,12 @@ from .layout import (
 )
 from .mesh_view_state import MeshViewState
 from .styles import STYLE
+from gui.widgets import TeeStream, WidgetLogHandler, make_log_widget
 from .widgets import (
     ArrowPanelWidget,
     ForceChartWidget,
     MeshViewportWidget,
     SettingsPanelWidget,
-    TeeStream,
-    WidgetLogHandler,
-    make_log_widget,
 )
 
 
@@ -689,7 +687,7 @@ class FingerDashboardWindow(QMainWindow):
 
 def run_dashboard(config: PipelineConfig, *, layout: DashboardLayout = LAYOUT) -> int:
     """Launch the unified finger dashboard and block until the window closes."""
-    from .app import get_or_create_qapp
+    from gui.app import get_or_create_qapp
 
     print("\n按键说明：Q 退出 | R 重置追踪器 | S 开始录像 | E 结束录像 | ESC 全屏")
     print("GUI：Record CSV / Stop CSV 写入接触点与力到所选目录。")

examples/gui/viewer3d/layout.py

@@ -47,6 +47,7 @@ import math
 from dataclasses import dataclass
 from typing import Literal
 
+from gui.log_config import LOG_CONFIG, LogConfig
 from viz.contact_arrow import ContactArrowStyle, DEFAULT_CONTACT_ARROW_STYLE
 from viz.flow_arrow import FlowArrowStyle
 from viz.render_2d import ArrowBackground, ArrowCanvasColors
@@ -193,53 +194,6 @@ ARROW_CANVAS_COLORS = ArrowCanvasColors(
 )
 
 
-@dataclass(frozen=True)
-class LogConfig:
-    """Log panel — edit LOG_CONFIG or DashboardLayout.log_config."""
-
-    status_enabled: bool = True
-    max_lines: int = 2000
-    font_family: str = "Cascadia Mono"
-    font_pt: int = 12
-    show_flow: bool = True
-    show_mask: bool = True
-
-    def format_status(
-        self,
-        *,
-        fps: float,
-        fnormal: float,
-        fshearx: float,
-        fsheary: float,
-        flow_rms: float = 0.0,
-        mask_coverage: float = 0.0,
-        wall_fps: float | None = None,
-        contact_xyz_mm: tuple[float, float, float] | None = None,
-    ) -> str:
-        shear_mag = float((fshearx**2 + fsheary**2) ** 0.5)
-        if wall_fps is not None:
-            parts = [f"FPS={wall_fps:.1f}", f"sdk={fps:.1f}"]
-        else:
-            parts = [f"FPS={fps:.1f}"]
-        parts.extend(
-            [
-                f"Fn={fnormal:.1f}",
-                f"|(Fx,Fy)|={shear_mag:.1f}",
-                f"Fx, Fy=({fshearx:.1f}, {fsheary:.1f})",
-            ]
-        )
-        force_line = "  ".join(parts)
-        if contact_xyz_mm is None:
-            contact_line = "contact=---"
-        else:
-            cx, cy, cz = contact_xyz_mm
-            contact_line = f"contact=({cx:.1f}, {cy:.1f}, {cz:.1f}) mm"
-        return f"{force_line}\n{contact_line}"
-
-
-LOG_CONFIG = LogConfig()
-
-
 @dataclass(frozen=True)
 class DashboardLayout:
     """Window chrome, chart styling, and panel hierarchy."""

examples/gui/viewer3d/preferences.py

@@ -1,4 +1,4 @@
-"""Load/save dashboard user preferences near this module."""
+"""Load/save dashboard user preferences for the finger 3D viewer."""
 
 from __future__ import annotations
 
@@ -6,15 +6,16 @@ import json
 from pathlib import Path
 from typing import Any
 
-from .app_paths import resource_path
+from gui.app_paths import resource_path
 
 PREFERENCE_FILE = "preference.json"
 LEGACY_CAMERA_SELECTION_FILE = "camera_selection.json"
-_GUI_DIR = Path(__file__).resolve().parent
+# Keep preference.json at examples/gui/ for backward compatibility.
+_GUI_DIR = Path(__file__).resolve().parents[1]
 
 
 def preference_path() -> Path:
-    # Keep preference file beside this module: examples/gui/preference.json
+    # Keep preference file at examples/gui/preference.json
     return _GUI_DIR / PREFERENCE_FILE
 
 

examples/gui/viewer3d/widgets/__init__.py

@@ -0,0 +1,15 @@
+"""Finger-specific Qt widgets for the 3D dashboard."""
+
+from .arrow_image import ArrowPanelWidget
+from .force_charts import ForceChartWidget
+from .image_panel import ImagePanel
+from .mesh_viewport import MeshViewportWidget
+from .settings_panel import SettingsPanelWidget
+
+__all__ = [
+    "ArrowPanelWidget",
+    "ForceChartWidget",
+    "ImagePanel",
+    "MeshViewportWidget",
+    "SettingsPanelWidget",
+]

examples/gui/viewer3d/widgets/arrow_image.py

@@ -9,7 +9,7 @@ from viz.render_2d import ArrowBackground, ArrowCanvasColors, render_uv_arrows
 
 from ..layout import DashboardLayout, LAYOUT
 from .image_panel import ImagePanel
-from .qt_pixmap import ndarray_to_pixmap
+from gui.widgets.qt_pixmap import ndarray_to_pixmap
 
 
 class ArrowPanelWidget(ImagePanel):

examples/gui/viewer3d/widgets/force_charts.py

@@ -6,8 +6,8 @@ import numpy as np
 from PyQt5.QtGui import QFont
 from PyQt5.QtWidgets import QSizePolicy
 
-from gui.layout import DashboardLayout, LAYOUT
-from gui.styles import LOG_FONT_PRIMARY, UI_FONT_PRIMARY
+from ..layout import DashboardLayout, LAYOUT
+from ..styles import LOG_FONT_PRIMARY, UI_FONT_PRIMARY
 from pipeline.frame import FingerFrameView
 from viz.signal_filters import lowpass_filter
 

examples/gui/viewer3d/widgets/image_panel.py

@@ -6,7 +6,7 @@ from PyQt5.QtCore import Qt
 from PyQt5.QtGui import QPixmap
 from PyQt5.QtWidgets import QLabel, QSizePolicy, QVBoxLayout, QWidget
 
-from .qt_pixmap import pixmap_keep_aspect
+from gui.widgets.qt_pixmap import pixmap_keep_aspect
 
 
 class ImagePanel(QWidget):

examples/gui/viewer3d/widgets/mesh_viewport.py

@@ -11,7 +11,7 @@ from viz.offscreen_mesh import OffscreenFingerMeshRenderer
 from ..layout import DashboardLayout, LAYOUT
 from ..mesh_view_state import MeshViewState
 from ..mesh_render_worker import MeshRenderWorker
-from .qt_pixmap import ndarray_to_pixmap
+from gui.widgets.qt_pixmap import ndarray_to_pixmap
 from .image_panel import ImagePanel
 
 _VIEW_ROTATE_SENSITIVITY = 0.35

examples/gui/widgets/__init__.py

@@ -1,19 +1,9 @@
-"""Qt widgets for the finger dashboard."""
+"""Shared Qt widgets used by 2D and 3D viewers."""
 
-from .settings_panel import SettingsPanelWidget
-from .force_charts import ForceChartWidget
 from .log_panel import TeeStream, WidgetLogHandler, make_log_widget
-from .mesh_viewport import MeshViewportWidget
-from .arrow_image import ArrowPanelWidget
 from .qt_pixmap import ndarray_to_pixmap, pixmap_keep_aspect
-from .image_panel import ImagePanel
 
 __all__ = [
-    "ArrowPanelWidget",
-    "SettingsPanelWidget",
-    "ForceChartWidget",
-    "MeshViewportWidget",
-    "ImagePanel",
     "TeeStream",
     "WidgetLogHandler",
     "make_log_widget",

examples/gui/widgets/log_panel.py

@@ -86,7 +86,7 @@ class WidgetLogHandler:
 
 def make_log_widget(config=None) -> QPlainTextEdit:
     if config is None:
-        from ..layout import LOG_CONFIG
+        from ..log_config import LOG_CONFIG
 
         config = LOG_CONFIG
     widget = QPlainTextEdit()