vlalab 0.1.0__py3-none-any.whl

vlalab/schema/run.py

@@ -0,0 +1,162 @@
+"""
+VLA-Lab Run Schema
+
+Defines the metadata structure for a deployment run.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+import json
+
+
+@dataclass
+class CameraConfig:
+    """Camera configuration."""
+    name: str
+    resolution: Optional[List[int]] = None  # [width, height]
+    fps: Optional[float] = None
+    camera_type: Optional[str] = None  # "realsense", "usb", etc.
+    serial_number: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {"name": self.name}
+        if self.resolution is not None:
+            d["resolution"] = self.resolution
+        if self.fps is not None:
+            d["fps"] = self.fps
+        if self.camera_type is not None:
+            d["camera_type"] = self.camera_type
+        if self.serial_number is not None:
+            d["serial_number"] = self.serial_number
+        return d
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CameraConfig":
+        return cls(**data)
+
+
+@dataclass
+class RunMeta:
+    """Metadata for a deployment run."""
+    # Required fields
+    run_name: str
+    start_time: str  # ISO format timestamp
+    
+    # Model info
+    model_name: str = "unknown"
+    model_path: Optional[str] = None
+    model_type: Optional[str] = None  # "diffusion_policy", "groot", etc.
+    
+    # Task info
+    task_name: str = "unknown"
+    task_prompt: Optional[str] = None
+    
+    # Robot info
+    robot_name: str = "unknown"
+    robot_type: Optional[str] = None  # "franka", "ur5", etc.
+    
+    # Camera info
+    cameras: List[CameraConfig] = field(default_factory=list)
+    
+    # Inference config
+    inference_freq: Optional[float] = None  # Hz
+    action_dim: Optional[int] = None
+    action_horizon: Optional[int] = None
+    
+    # Deployment info
+    server_config: Dict[str, Any] = field(default_factory=dict)
+    client_config: Dict[str, Any] = field(default_factory=dict)
+    
+    # Statistics (updated during/after run)
+    end_time: Optional[str] = None
+    total_steps: int = 0
+    total_duration_s: Optional[float] = None
+    
+    # Version info
+    vlalab_version: str = "0.1.0"
+    framework_version: Optional[str] = None
+    
+    # Extra fields
+    extra: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "run_name": self.run_name,
+            "start_time": self.start_time,
+            "model_name": self.model_name,
+            "task_name": self.task_name,
+            "robot_name": self.robot_name,
+            "cameras": [cam.to_dict() for cam in self.cameras],
+            "total_steps": self.total_steps,
+            "vlalab_version": self.vlalab_version,
+        }
+        
+        # Add optional fields if set
+        optional_fields = [
+            "model_path", "model_type", "task_prompt", "robot_type",
+            "inference_freq", "action_dim", "action_horizon",
+            "end_time", "total_duration_s", "framework_version",
+        ]
+        for field_name in optional_fields:
+            value = getattr(self, field_name)
+            if value is not None:
+                d[field_name] = value
+        
+        if self.server_config:
+            d["server_config"] = self.server_config
+        if self.client_config:
+            d["client_config"] = self.client_config
+        if self.extra:
+            d["extra"] = self.extra
+        
+        return d
+    
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+    
+    def save(self, path: str):
+        """Save metadata to JSON file."""
+        with open(path, "w") as f:
+            f.write(self.to_json())
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "RunMeta":
+        cameras = [
+            CameraConfig.from_dict(cam) if isinstance(cam, dict) else cam
+            for cam in data.get("cameras", [])
+        ]
+        
+        return cls(
+            run_name=data["run_name"],
+            start_time=data["start_time"],
+            model_name=data.get("model_name", "unknown"),
+            model_path=data.get("model_path"),
+            model_type=data.get("model_type"),
+            task_name=data.get("task_name", "unknown"),
+            task_prompt=data.get("task_prompt"),
+            robot_name=data.get("robot_name", "unknown"),
+            robot_type=data.get("robot_type"),
+            cameras=cameras,
+            inference_freq=data.get("inference_freq"),
+            action_dim=data.get("action_dim"),
+            action_horizon=data.get("action_horizon"),
+            server_config=data.get("server_config", {}),
+            client_config=data.get("client_config", {}),
+            end_time=data.get("end_time"),
+            total_steps=data.get("total_steps", 0),
+            total_duration_s=data.get("total_duration_s"),
+            vlalab_version=data.get("vlalab_version", "0.1.0"),
+            framework_version=data.get("framework_version"),
+            extra=data.get("extra", {}),
+        )
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> "RunMeta":
+        return cls.from_dict(json.loads(json_str))
+    
+    @classmethod
+    def load(cls, path: str) -> "RunMeta":
+        """Load metadata from JSON file."""
+        with open(path, "r") as f:
+            return cls.from_json(f.read())

vlalab/schema/step.py

@@ -0,0 +1,177 @@
+"""
+VLA-Lab Step Schema
+
+Defines the data structure for a single inference step.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Optional, Dict, Any, Union
+from datetime import datetime
+import json
+
+
+@dataclass
+class ImageRef:
+    """Reference to an image artifact file."""
+    path: str  # Relative path from run_dir
+    camera_name: str = "default"
+    shape: Optional[List[int]] = None  # [H, W, C]
+    encoding: str = "jpeg"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ImageRef":
+        return cls(**data)
+
+
+@dataclass
+class ObsData:
+    """Observation data for a step."""
+    state: List[float] = field(default_factory=list)  # Low-dim state (pose, gripper, etc.)
+    images: List[ImageRef] = field(default_factory=list)  # Image references
+    
+    # Optional detailed state breakdown
+    pose: Optional[List[float]] = None  # [x, y, z, qx, qy, qz, qw] or [x, y, z, qw, qx, qy, qz]
+    gripper: Optional[float] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "state": self.state,
+            "images": [img.to_dict() for img in self.images],
+        }
+        if self.pose is not None:
+            d["pose"] = self.pose
+        if self.gripper is not None:
+            d["gripper"] = self.gripper
+        return d
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ObsData":
+        images = [ImageRef.from_dict(img) for img in data.get("images", [])]
+        return cls(
+            state=data.get("state", []),
+            images=images,
+            pose=data.get("pose"),
+            gripper=data.get("gripper"),
+        )
+
+
+@dataclass
+class ActionData:
+    """Action data for a step."""
+    values: List[List[float]] = field(default_factory=list)  # Action chunk: [[a1], [a2], ...]
+    
+    # Optional metadata
+    action_dim: Optional[int] = None
+    chunk_size: Optional[int] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {"values": self.values}
+        if self.action_dim is not None:
+            d["action_dim"] = self.action_dim
+        if self.chunk_size is not None:
+            d["chunk_size"] = self.chunk_size
+        return d
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ActionData":
+        return cls(
+            values=data.get("values", []),
+            action_dim=data.get("action_dim"),
+            chunk_size=data.get("chunk_size"),
+        )
+
+
+@dataclass
+class TimingData:
+    """Timing data for a step (all times in milliseconds or Unix timestamps)."""
+    # Timestamps (Unix time, float)
+    client_send: Optional[float] = None
+    server_recv: Optional[float] = None
+    infer_start: Optional[float] = None
+    infer_end: Optional[float] = None
+    send_timestamp: Optional[float] = None
+    
+    # Computed latencies (milliseconds)
+    transport_latency_ms: Optional[float] = None
+    inference_latency_ms: Optional[float] = None
+    total_latency_ms: Optional[float] = None
+    message_interval_ms: Optional[float] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {}
+        for k, v in asdict(self).items():
+            if v is not None:
+                d[k] = v
+        return d
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TimingData":
+        return cls(
+            client_send=data.get("client_send"),
+            server_recv=data.get("server_recv"),
+            infer_start=data.get("infer_start"),
+            infer_end=data.get("infer_end"),
+            send_timestamp=data.get("send_timestamp"),
+            transport_latency_ms=data.get("transport_latency_ms"),
+            inference_latency_ms=data.get("inference_latency_ms"),
+            total_latency_ms=data.get("total_latency_ms"),
+            message_interval_ms=data.get("message_interval_ms"),
+        )
+    
+    def compute_latencies(self):
+        """Compute latency values from timestamps."""
+        if self.server_recv is not None and self.client_send is not None:
+            self.transport_latency_ms = (self.server_recv - self.client_send) * 1000
+        
+        if self.infer_end is not None and self.infer_start is not None:
+            self.inference_latency_ms = (self.infer_end - self.infer_start) * 1000
+        
+        if self.send_timestamp is not None and self.client_send is not None:
+            self.total_latency_ms = (self.send_timestamp - self.client_send) * 1000
+
+
+@dataclass
+class StepRecord:
+    """A single step record in the inference log."""
+    step_idx: int
+    obs: ObsData = field(default_factory=ObsData)
+    action: ActionData = field(default_factory=ActionData)
+    timing: TimingData = field(default_factory=TimingData)
+    
+    # Optional fields
+    tags: Dict[str, Any] = field(default_factory=dict)
+    prompt: Optional[str] = None  # For language-conditioned models
+    
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "step_idx": self.step_idx,
+            "obs": self.obs.to_dict(),
+            "action": self.action.to_dict(),
+            "timing": self.timing.to_dict(),
+        }
+        if self.tags:
+            d["tags"] = self.tags
+        if self.prompt is not None:
+            d["prompt"] = self.prompt
+        return d
+    
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StepRecord":
+        return cls(
+            step_idx=data["step_idx"],
+            obs=ObsData.from_dict(data.get("obs", {})),
+            action=ActionData.from_dict(data.get("action", {})),
+            timing=TimingData.from_dict(data.get("timing", {})),
+            tags=data.get("tags", {}),
+            prompt=data.get("prompt"),
+        )
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> "StepRecord":
+        return cls.from_dict(json.loads(json_str))

vlalab/viz/__init__.py

@@ -0,0 +1,9 @@
+"""
+VLA-Lab Visualization Module
+
+Provides visualization utilities including matplotlib font setup.
+"""
+
+from vlalab.viz.mpl_fonts import setup_matplotlib_fonts, FontSetupResult
+
+__all__ = ["setup_matplotlib_fonts", "FontSetupResult"]

vlalab/viz/mpl_fonts.py

@@ -0,0 +1,161 @@
+"""
+Matplotlib 字体配置工具
+
+目标：
+- 自动选择可用的中文字体（优先 WenQuanYi / Noto / Source Han）
+- 必要时通过字体文件路径 addfont（绕过 matplotlib 缓存导致的"明明装了字体却找不到"）
+- 抑制常见的 Glyph missing / findfont 噪音警告
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional
+
+
+@dataclass(frozen=True)
+class FontSetupResult:
+    chosen_font: Optional[str]
+    available_chinese_like_fonts: list[str]
+
+
+def _unique_preserve_order(items: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for x in items:
+        if x and x not in seen:
+            out.append(x)
+            seen.add(x)
+    return out
+
+
+def setup_matplotlib_fonts(verbose: bool = True) -> FontSetupResult:
+    """
+    配置 matplotlib 中文字体。
+
+    返回：
+    - chosen_font: 选中的字体名称；若为 None 表示未找到合适中文字体
+    - available_chinese_like_fonts: 检测到的"疑似中文字体"列表（用于诊断）
+    """
+    import os
+    import warnings
+
+    import matplotlib as mpl
+    import matplotlib.font_manager as fm
+
+    # 抑制字体相关噪音 warning（不影响实际渲染）
+    warnings.filterwarnings("ignore", category=UserWarning, message=".*Glyph.*missing.*")
+    warnings.filterwarnings("ignore", category=UserWarning, message="findfont: Font family.*")
+    warnings.filterwarnings("ignore", category=UserWarning, module="matplotlib.font_manager")
+
+    # 常见中文字体文件路径（存在则 addfont，避免缓存/扫描问题）
+    font_paths = [
+        # WenQuanYi
+        "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
+        "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
+        # Noto CJK（不同发行版路径/后缀会不同，尽量覆盖）
+        "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttf",
+        "/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf",
+        "/usr/share/fonts/opentype/noto/NotoSansCJKtc-Regular.otf",
+        "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/truetype/noto/NotoSansCJKsc-Regular.otf",
+        "/usr/share/fonts/truetype/noto/NotoSansCJKtc-Regular.otf",
+        # Source Han
+        "/usr/share/fonts/opentype/source-han-sans/SourceHanSansCN-Regular.otf",
+        "/usr/share/fonts/opentype/source-han-sans/SourceHanSansSC-Regular.otf",
+        "/usr/share/fonts/opentype/source-han-sans/SourceHanSansTC-Regular.otf",
+    ]
+
+    for p in font_paths:
+        if os.path.exists(p):
+            try:
+                fm.fontManager.addfont(p)
+            except Exception:
+                # addfont 失败不应中断主流程
+                pass
+
+    # 重新获取字体列表（包含 addfont 后的新字体）
+    all_fonts = [f.name for f in fm.fontManager.ttflist]
+    all_fonts_lower = [n.lower() for n in all_fonts]
+
+    # 首选字体名称（按优先级）
+    preferred_names = [
+        "WenQuanYi Micro Hei",
+        "WenQuanYi Zen Hei",
+        "Noto Sans CJK SC",
+        "Noto Sans CJK TC",
+        "Source Han Sans CN",
+        "Source Han Sans SC",
+        "Source Han Sans TC",
+        # Windows/macOS 常见
+        "SimHei",
+        "Microsoft YaHei",
+        "PingFang SC",
+        "STHeiti",
+    ]
+
+    chosen: Optional[str] = None
+
+    # 1) 先严格按名称匹配
+    available_set = set(all_fonts)
+    for name in preferred_names:
+        if name in available_set:
+            chosen = name
+            break
+
+    # 2) 再做一次"模糊匹配"（不同系统字体命名略有差异）
+    if chosen is None:
+        preferred_keywords = [
+            "wenquanyi",
+            "wqy",
+            "noto sans cjk",
+            "noto cjk",
+            "source han sans",
+            "simhei",
+            "yahei",
+            "pingfang",
+            "stheiti",
+            "cjk",
+        ]
+        for kw in preferred_keywords:
+            for i, name_l in enumerate(all_fonts_lower):
+                if kw in name_l:
+                    chosen = all_fonts[i]
+                    break
+            if chosen is not None:
+                break
+
+    # 诊断信息：列出"疑似中文字体"
+    chinese_like = []
+    chinese_keywords = [
+        "wenquanyi",
+        "wqy",
+        "noto",
+        "cjk",
+        "source han",
+        "simhei",
+        "yahei",
+        "pingfang",
+        "heiti",
+    ]
+    for i, name_l in enumerate(all_fonts_lower):
+        if any(k in name_l for k in chinese_keywords):
+            chinese_like.append(all_fonts[i])
+    chinese_like = sorted(set(chinese_like))
+
+    if chosen is not None:
+        # 注意：不要覆盖掉用户可能已有的 font.sans-serif 配置，采用"前置 + 去重"
+        current = list(mpl.rcParams.get("font.sans-serif", []))
+        mpl.rcParams["font.family"] = "sans-serif"
+        mpl.rcParams["font.sans-serif"] = _unique_preserve_order([chosen, *current, "DejaVu Sans"])
+        mpl.rcParams["axes.unicode_minus"] = False
+        if verbose:
+            print(f"[字体] 使用字体: {chosen}")
+    else:
+        # 没找到中文字体也不报错，只提示（图里中文会是方块）
+        mpl.rcParams["axes.unicode_minus"] = False
+        if verbose:
+            print("[字体] 警告: 未找到可用中文字体，中文可能显示为方块")
+
+    return FontSetupResult(chosen_font=chosen, available_chinese_like_fonts=chinese_like)