BulletLab 0.1.2__py3-none-any.whl

bulletlab/ui/panels/properties.py

@@ -0,0 +1,265 @@
+"""
+PropertiesPanel – editable property inspector for the selected object.
+
+Detects the type of the selected object (Simulation, Robot, Joint, or Link)
+and renders appropriate editable fields. All changes are applied immediately
+to the simulation.
+
+Example::
+
+    from bulletlab.ui.panels.properties import PropertiesPanel
+
+    props = PropertiesPanel()
+    props.set_target(robot.links["wheel"])
+    props.render()
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, TYPE_CHECKING
+
+try:
+    import imgui
+
+    _HAS_IMGUI = True
+except ImportError:  # pragma: no cover
+    imgui = None  # type: ignore[assignment]
+    _HAS_IMGUI = False
+
+if TYPE_CHECKING:
+    from bulletlab.core.simulation import Simulation
+    from bulletlab.robot.robot import Robot
+    from bulletlab.robot.joint import Joint
+    from bulletlab.robot.link import Link
+
+
+class PropertiesPanel:
+    """Renders editable properties for the currently selected object.
+
+    Automatically detects whether the target is a :class:`~bulletlab.core.simulation.Simulation`,
+    :class:`~bulletlab.robot.robot.Robot`, :class:`~bulletlab.robot.joint.Joint`, or
+    :class:`~bulletlab.robot.link.Link` and renders the appropriate fields.
+
+    Example::
+
+        props = PropertiesPanel()
+        props.set_target(selected_object)
+        props.render()
+    """
+
+    def __init__(self) -> None:
+        self._target: Any = None
+
+    def set_target(self, obj: Any) -> None:
+        """Set the object whose properties will be displayed.
+
+        Args:
+            obj: A Simulation, Robot, Joint, Link, or ``None`` to clear.
+
+        Example::
+
+            props.set_target(robot.joints["wheel_left"])
+        """
+        self._target = obj
+
+    def render(self) -> None:
+        """Draw the properties panel contents.
+
+        Must be called inside an active ImGui window context.
+        """
+        if not _HAS_IMGUI:
+            return
+
+        if self._target is None:
+            imgui.text_colored("Select an item in the Explorer.", 0.5, 0.5, 0.5, 1.0)
+            return
+
+        # Route to appropriate renderer
+        type_name = type(self._target).__name__
+        imgui.text(f"Type: {type_name}")
+        imgui.separator()
+
+        if type_name == "Simulation":
+            self._render_simulation(self._target)
+        elif type_name == "Robot":
+            self._render_robot(self._target)
+        elif type_name == "Joint":
+            self._render_joint(self._target)
+        elif type_name == "Link":
+            self._render_link(self._target)
+        else:
+            imgui.text(str(self._target))
+
+    # ------------------------------------------------------------------
+    # Simulation properties
+    # ------------------------------------------------------------------
+
+    def _render_simulation(self, sim: "Simulation") -> None:
+        imgui.text(f"Status: {'Paused' if sim.is_paused else 'Running'}")
+        imgui.text(f"Steps: {sim.step_count}")
+        imgui.text(f"Sim Time: {sim.elapsed_time:.3f} s")
+        imgui.separator()
+
+        # Gravity
+        gx, gy, gz = sim.gravity
+        changed_gz, new_gz = imgui.drag_float("Gravity Z##sim_gz", gz, 0.1, -20.0, 20.0)
+        if changed_gz:
+            sim.gravity = (gx, gy, new_gz)
+
+        # Timestep
+        changed_ts, new_ts = imgui.drag_float("Timestep##sim_ts", sim.timestep, 0.0001, 0.0001, 0.1, "%.5f")
+        if changed_ts:
+            sim.timestep = float(new_ts)
+
+        imgui.separator()
+        if sim.is_paused:
+            if imgui.button("Resume##sim_resume"):
+                sim.resume()
+        else:
+            if imgui.button("Pause##sim_pause"):
+                sim.pause()
+        imgui.same_line()
+        if imgui.button("Reset##sim_reset"):
+            sim.reset()
+
+    # ------------------------------------------------------------------
+    # Robot properties
+    # ------------------------------------------------------------------
+
+    def _render_robot(self, robot: "Robot") -> None:
+        imgui.text(f"Name: {robot.name}")
+        imgui.text(f"Joints: {robot.num_joints}  (controllable: {robot.num_controllable_joints})")
+        imgui.text(f"Links: {len(robot.links)}")
+        imgui.separator()
+
+        pos = robot.base_position
+        vel = robot.base_velocity
+        roll_deg = math.degrees(robot.roll)
+        pitch_deg = math.degrees(robot.pitch)
+        yaw_deg = math.degrees(robot.yaw)
+
+        imgui.text(f"Position:  ({pos[0]:.3f}, {pos[1]:.3f}, {pos[2]:.3f})")
+        imgui.text(f"Velocity:  ({vel[0]:.3f}, {vel[1]:.3f}, {vel[2]:.3f})")
+        imgui.text(f"Roll:  {roll_deg:.2f}°")
+        imgui.text(f"Pitch: {pitch_deg:.2f}°")
+        imgui.text(f"Yaw:   {yaw_deg:.2f}°")
+        imgui.text(f"Speed: {robot.speed:.3f} m/s")
+        imgui.separator()
+
+        if imgui.button("Reset Robot##robot_reset"):
+            robot.reset()
+
+    # ------------------------------------------------------------------
+    # Joint properties
+    # ------------------------------------------------------------------
+
+    def _render_joint(self, joint: "Joint") -> None:
+        imgui.text(f"Name: {joint.name}")
+        imgui.text(f"Index: {joint.index}")
+        imgui.text(f"Type: {joint.joint_type.name if hasattr(joint.joint_type, 'name') else joint.joint_type}")
+        imgui.separator()
+
+        imgui.text(f"Position: {joint.position:.4f} rad")
+        imgui.text(f"Velocity: {joint.velocity:.4f} rad/s")
+        imgui.text(f"Torque:   {joint.torque:.4f} N·m")
+        lo, hi = joint.limits
+        imgui.text(f"Limits: [{lo:.3f}, {hi:.3f}]")
+        imgui.separator()
+
+        # Max force
+        changed_mf, new_mf = imgui.drag_float(
+            "Max Force##jnt_mf", joint.max_force, 1.0, 0.0, 5000.0
+        )
+        if changed_mf:
+            joint.max_force = float(new_mf)
+
+        # Max velocity
+        changed_mv, new_mv = imgui.drag_float(
+            "Max Velocity##jnt_mv", joint.max_velocity, 0.1, 0.0, 200.0
+        )
+        if changed_mv:
+            joint.max_velocity = float(new_mv)
+
+        imgui.separator()
+
+        # Target velocity control
+        changed_vel, new_vel = imgui.drag_float(
+            "Target Velocity##jnt_vel", joint.velocity, 0.1, -200.0, 200.0
+        )
+        if changed_vel:
+            joint.velocity = float(new_vel)
+
+        # Position control
+        lo2, hi2 = joint.limits
+        range_lo = lo2 if lo2 != 0.0 or hi2 != 0.0 else -6.28
+        range_hi = hi2 if lo2 != 0.0 or hi2 != 0.0 else 6.28
+        changed_pos, new_pos = imgui.slider_float(
+            "Target Position##jnt_pos", joint.position, range_lo, range_hi
+        )
+        if changed_pos:
+            joint.set_position(float(new_pos))
+
+        imgui.separator()
+        if imgui.button("Reset Joint##jnt_reset"):
+            joint.reset()
+        imgui.same_line()
+        if joint.is_enabled:
+            if imgui.button("Disable##jnt_disable"):
+                joint.disable()
+        else:
+            if imgui.button("Enable##jnt_enable"):
+                joint.enable()
+
+    # ------------------------------------------------------------------
+    # Link properties
+    # ------------------------------------------------------------------
+
+    def _render_link(self, link: "Link") -> None:
+        imgui.text(f"Name: {link.name}")
+        imgui.text(f"Index: {link.index}")
+        imgui.separator()
+
+        # Mass
+        changed_mass, new_mass = imgui.drag_float(
+            "Mass (kg)##lnk_mass", link.mass, 0.01, 0.0001, 1000.0
+        )
+        if changed_mass:
+            link.mass = float(new_mass)
+
+        # Friction
+        changed_fric, new_fric = imgui.drag_float(
+            "Lateral Friction##lnk_fric", link.friction, 0.01, 0.0, 10.0
+        )
+        if changed_fric:
+            link.friction = float(new_fric)
+
+        # Restitution
+        changed_rest, new_rest = imgui.slider_float(
+            "Restitution##lnk_rest", link.restitution, 0.0, 1.0
+        )
+        if changed_rest:
+            link.restitution = float(new_rest)
+
+        # Linear damping
+        changed_ld, new_ld = imgui.drag_float(
+            "Linear Damping##lnk_ld", link.linear_damping, 0.001, 0.0, 10.0
+        )
+        if changed_ld:
+            link.linear_damping = float(new_ld)
+
+        # Angular damping
+        changed_ad, new_ad = imgui.drag_float(
+            "Angular Damping##lnk_ad", link.angular_damping, 0.001, 0.0, 10.0
+        )
+        if changed_ad:
+            link.angular_damping = float(new_ad)
+
+        imgui.separator()
+        pos = link.position
+        vel = link.velocity
+        imgui.text(f"Position: ({pos[0]:.3f}, {pos[1]:.3f}, {pos[2]:.3f})")
+        imgui.text(f"Velocity: ({vel[0]:.3f}, {vel[1]:.3f}, {vel[2]:.3f})")
+
+    def __repr__(self) -> str:
+        return f"PropertiesPanel(target={type(self._target).__name__ if self._target else None})"

bulletlab/ui/panels/telemetry.py

@@ -0,0 +1,105 @@
+"""
+TelemetryPanel – displays live robot telemetry data.
+
+Shows all channels registered in a TelemetryManager as a table with
+the most recent values. Optionally shows units.
+
+Example::
+
+    from bulletlab.ui.panels.telemetry import TelemetryPanel
+    from bulletlab.telemetry import TelemetryManager
+
+    telemetry = TelemetryManager()
+    telemetry.watch("Speed", lambda: robot.speed, unit="m/s")
+
+    panel = TelemetryPanel(telemetry)
+    panel.render()
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, TYPE_CHECKING
+
+try:
+    import imgui
+
+    _HAS_IMGUI = True
+except ImportError:  # pragma: no cover
+    imgui = None  # type: ignore[assignment]
+    _HAS_IMGUI = False
+
+if TYPE_CHECKING:
+    from bulletlab.telemetry.manager import TelemetryManager
+
+
+class TelemetryPanel:
+    """Renders a live key-value table of telemetry channel values.
+
+    Args:
+        telemetry: The :class:`~bulletlab.telemetry.manager.TelemetryManager` to display.
+
+    Example::
+
+        panel = TelemetryPanel(telemetry)
+        # In render loop:
+        panel.render()
+    """
+
+    def __init__(self, telemetry: "TelemetryManager") -> None:
+        self._telemetry = telemetry
+
+    def render(self) -> None:
+        """Draw the telemetry panel contents.
+
+        Must be called inside an active ImGui window context.
+        """
+        if not _HAS_IMGUI:
+            return
+
+        if not self._telemetry.channel_names:
+            imgui.text_colored("No channels registered.", 0.5, 0.5, 0.5, 1.0)
+            imgui.text("Use telemetry.watch(...) to add channels.")
+            return
+
+        # Table header
+        imgui.columns(3, "telemetry_table", border=True)
+        imgui.text("Channel")
+        imgui.next_column()
+        imgui.text("Value")
+        imgui.next_column()
+        imgui.text("Unit")
+        imgui.next_column()
+        imgui.separator()
+
+        for name, channel in self._telemetry.channels.items():
+            val = channel.latest
+            unit = channel.unit
+
+            imgui.text(name)
+            imgui.next_column()
+
+            # Format value
+            if val is None:
+                val_str = "—"
+            elif isinstance(val, float):
+                if math.isnan(val):
+                    val_str = "NaN"
+                elif math.isinf(val):
+                    val_str = "Inf"
+                else:
+                    val_str = f"{val:.4f}"
+            elif isinstance(val, (list, tuple)):
+                val_str = "(" + ", ".join(f"{v:.3f}" for v in val) + ")"
+            else:
+                val_str = str(val)
+
+            imgui.text(val_str)
+            imgui.next_column()
+            imgui.text(unit)
+            imgui.next_column()
+
+        imgui.columns(1)
+
+    def __repr__(self) -> str:
+        return f"TelemetryPanel(channels={self._telemetry.channel_names})"

bulletlab/ui/widgets.py

@@ -0,0 +1,348 @@
+"""
+Widget helper functions for building BulletLab custom panels.
+
+Provides a minimal, boilerplate-free API for common ImGui widgets.
+All functions must be called from within an ImGui window context (i.e.,
+between imgui.begin() and imgui.end()).
+
+Example::
+
+    from bulletlab.ui import widgets as ui
+
+    @app.custom_panel("My Controls")
+    def my_panel():
+        ui.button("Reset", robot.reset)
+        ui.slider("Wheel Mass", robot.links["wheel"].mass, 0.1, 20,
+                  setter=lambda v: setattr(robot.links["wheel"], "mass", v))
+        ui.checkbox("Motors On", lambda: motors_on,
+                    setter=lambda v: set_motors(v))
+        ui.text("Speed", f"{robot.speed:.2f} m/s")
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+# ImGui is optional — graceful fallback
+try:
+    import imgui
+
+    _HAS_IMGUI = True
+except ImportError:  # pragma: no cover
+    imgui = None  # type: ignore[assignment]
+    _HAS_IMGUI = False
+
+
+def _check_imgui() -> bool:
+    """Return True if imgui is available, warn otherwise."""
+    if not _HAS_IMGUI:
+        return False
+    return True
+
+
+# ------------------------------------------------------------------
+# Basic widgets
+# ------------------------------------------------------------------
+
+
+def button(label: str, callback: Callable[[], Any] | None = None) -> bool:
+    """Render a clickable button.
+
+    Args:
+        label: Button text label.
+        callback: Function to call when the button is clicked.
+
+    Returns:
+        ``True`` if the button was clicked this frame.
+
+    Example::
+
+        ui.button("Reset Robot", robot.reset)
+    """
+    if not _check_imgui():
+        return False
+    clicked = imgui.button(label)
+    if clicked and callback is not None:
+        callback()
+    return clicked
+
+
+def text(label: str, value: Any = "") -> None:
+    """Render a read-only text label with an optional value.
+
+    Args:
+        label: Field label.
+        value: Value to display (converted to string).
+
+    Example::
+
+        ui.text("Speed", f"{robot.speed:.2f} m/s")
+    """
+    if not _check_imgui():
+        return
+    if value != "":
+        imgui.text(f"{label}: {value}")
+    else:
+        imgui.text(str(label))
+
+
+def separator(label: str = "") -> None:
+    """Render a horizontal separator, optionally with a label.
+
+    Args:
+        label: Optional section label.
+
+    Example::
+
+        ui.separator("Physics")
+    """
+    if not _check_imgui():
+        return
+    imgui.separator()
+    if label:
+        imgui.text(label)
+
+
+def same_line() -> None:
+    """Place the next widget on the same line."""
+    if _check_imgui():
+        imgui.same_line()
+
+
+# ------------------------------------------------------------------
+# Input widgets
+# ------------------------------------------------------------------
+
+
+def slider(
+    label: str,
+    getter: Callable[[], float] | float,
+    min_val: float,
+    max_val: float,
+    setter: Callable[[float], None] | None = None,
+    fmt: str = "%.3f",
+) -> float:
+    """Render a float slider.
+
+    Args:
+        label: Widget label.
+        getter: Current value or a callable returning the current value.
+        min_val: Minimum value.
+        max_val: Maximum value.
+        setter: Called with the new value when the slider changes.
+        fmt: Printf format string for display.
+
+    Returns:
+        Current slider value.
+
+    Example::
+
+        ui.slider("Wheel Mass", lambda: robot.links["wheel"].mass, 0.1, 20,
+                  setter=lambda v: setattr(robot.links["wheel"], "mass", v))
+    """
+    if not _check_imgui():
+        return 0.0
+    current = float(getter()) if callable(getter) else float(getter)
+    changed, new_val = imgui.slider_float(label, current, min_val, max_val, fmt)
+    if changed and setter is not None:
+        setter(float(new_val))
+    return float(new_val) if changed else current
+
+
+def drag_float(
+    label: str,
+    getter: Callable[[], float] | float,
+    setter: Callable[[float], None] | None = None,
+    speed: float = 0.1,
+    min_val: float = 0.0,
+    max_val: float = 0.0,
+    fmt: str = "%.3f",
+) -> float:
+    """Render a drag-to-edit float field.
+
+    Args:
+        label: Widget label.
+        getter: Current value or callable returning current value.
+        setter: Called with the new value when changed.
+        speed: Drag sensitivity.
+        min_val: Minimum value (0 = no clamp).
+        max_val: Maximum value (0 = no clamp).
+        fmt: Printf format string for display.
+
+    Returns:
+        Current value.
+
+    Example::
+
+        ui.drag_float("Mass", lambda: link.mass, setter=lambda v: setattr(link, "mass", v))
+    """
+    if not _check_imgui():
+        return 0.0
+    current = float(getter()) if callable(getter) else float(getter)
+    changed, new_val = imgui.drag_float(label, current, speed, min_val, max_val, fmt)
+    if changed and setter is not None:
+        setter(float(new_val))
+    return float(new_val) if changed else current
+
+
+def input_float(
+    label: str,
+    getter: Callable[[], float] | float,
+    setter: Callable[[float], None] | None = None,
+    step: float = 0.1,
+    fmt: str = "%.3f",
+) -> float:
+    """Render a float input field.
+
+    Args:
+        label: Widget label.
+        getter: Current value or callable.
+        setter: Called with the new value when committed.
+        step: Increment step for +/- buttons.
+        fmt: Display format string.
+
+    Returns:
+        Current value.
+
+    Example::
+
+        ui.input_float("Friction", lambda: link.friction,
+                       setter=lambda v: setattr(link, "friction", v))
+    """
+    if not _check_imgui():
+        return 0.0
+    current = float(getter()) if callable(getter) else float(getter)
+    changed, new_val = imgui.input_float(label, current, step, step * 10, fmt)
+    if changed and setter is not None:
+        setter(float(new_val))
+    return float(new_val) if changed else current
+
+
+def checkbox(
+    label: str,
+    getter: Callable[[], bool] | bool,
+    setter: Callable[[bool], None] | None = None,
+) -> bool:
+    """Render a checkbox.
+
+    Args:
+        label: Widget label.
+        getter: Current state or callable returning current state.
+        setter: Called with the new state when toggled.
+
+    Returns:
+        Current checkbox state.
+
+    Example::
+
+        ui.checkbox("Motors Enabled", lambda: motors_on,
+                    setter=lambda v: set_motors(v))
+    """
+    if not _check_imgui():
+        return False
+    current = bool(getter()) if callable(getter) else bool(getter)
+    changed, new_val = imgui.checkbox(label, current)
+    if changed and setter is not None:
+        setter(bool(new_val))
+    return bool(new_val) if changed else current
+
+
+def color_edit(
+    label: str,
+    getter: Callable[[], tuple[float, float, float]] | tuple[float, float, float],
+    setter: Callable[[tuple[float, float, float]], None] | None = None,
+) -> tuple[float, float, float]:
+    """Render an RGB color picker.
+
+    Args:
+        label: Widget label.
+        getter: Current color ``(r, g, b)`` normalized to [0, 1] or callable.
+        setter: Called with the new color when changed.
+
+    Returns:
+        Current color ``(r, g, b)``.
+
+    Example::
+
+        ui.color_edit("Light Color", lambda: color, setter=lambda c: set_color(c))
+    """
+    if not _check_imgui():
+        return (1.0, 1.0, 1.0)
+    current = tuple(getter()) if callable(getter) else tuple(getter)
+    r, g, b = float(current[0]), float(current[1]), float(current[2])
+    changed, (nr, ng, nb) = imgui.color_edit3(label, r, g, b)
+    result = (float(nr), float(ng), float(nb))
+    if changed and setter is not None:
+        setter(result)
+    return result if changed else (r, g, b)
+
+
+def combo(
+    label: str,
+    items: list[str],
+    getter: Callable[[], int] | int,
+    setter: Callable[[int], None] | None = None,
+) -> int:
+    """Render a dropdown combo box.
+
+    Args:
+        label: Widget label.
+        items: List of selectable items.
+        getter: Current selected index or callable.
+        setter: Called with new index when changed.
+
+    Returns:
+        Current selected index.
+
+    Example::
+
+        ui.combo("Mode", ["Velocity", "Position", "Torque"], lambda: mode_idx,
+                 setter=lambda i: set_mode(i))
+    """
+    if not _check_imgui():
+        return 0
+    current = int(getter()) if callable(getter) else int(getter)
+    changed, new_idx = imgui.combo(label, current, items)
+    if changed and setter is not None:
+        setter(int(new_idx))
+    return int(new_idx) if changed else current
+
+
+def collapsing_header(label: str, default_open: bool = True) -> bool:
+    """Render a collapsible section header.
+
+    Args:
+        label: Section title.
+        default_open: Whether the section starts expanded.
+
+    Returns:
+        ``True`` if the section is currently expanded.
+
+    Example::
+
+        if ui.collapsing_header("Physics Parameters"):
+            ui.drag_float("Mass", ...)
+    """
+    if not _check_imgui():
+        return True
+    flags = imgui.TREE_NODE_DEFAULT_OPEN if default_open else 0
+    return imgui.collapsing_header(label, flags=flags)
+
+
+def tooltip(text_str: str) -> None:
+    """Show a tooltip when the previous widget is hovered.
+
+    Args:
+        text_str: Tooltip text.
+
+    Example::
+
+        ui.drag_float("Mass", ...)
+        ui.tooltip("Mass of the link in kilograms")
+    """
+    if not _check_imgui():
+        return
+    if imgui.is_item_hovered():
+        imgui.begin_tooltip()
+        imgui.text(text_str)
+        imgui.end_tooltip()