BulletLab 0.1.2__py3-none-any.whl

bulletlab/utils/__init__.py

@@ -0,0 +1,26 @@
+"""
+BulletLab utils subpackage.
+
+Provides mathematical helpers, URDF discovery utilities, and simulation timers.
+"""
+
+from bulletlab.utils.math_utils import (
+    quaternion_to_euler,
+    euler_to_quaternion,
+    normalize,
+    clamp,
+    lerp,
+)
+from bulletlab.utils.timer import SimTimer
+from bulletlab.utils.urdf_utils import find_urdf, list_available_urdfs
+
+__all__ = [
+    "quaternion_to_euler",
+    "euler_to_quaternion",
+    "normalize",
+    "clamp",
+    "lerp",
+    "SimTimer",
+    "find_urdf",
+    "list_available_urdfs",
+]

bulletlab/utils/math_utils.py

@@ -0,0 +1,183 @@
+"""
+Mathematical utilities for BulletLab.
+
+Provides quaternion/Euler conversion, vector normalization, clamping,
+and linear interpolation — all without external dependencies beyond NumPy.
+
+Example::
+
+    from bulletlab.utils.math_utils import quaternion_to_euler, euler_to_quaternion
+
+    roll, pitch, yaw = quaternion_to_euler((0, 0, 0, 1))
+    q = euler_to_quaternion(0.1, 0.2, 0.3)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence
+
+import numpy as np
+
+
+def quaternion_to_euler(
+    q: Sequence[float],
+) -> tuple[float, float, float]:
+    """Convert a quaternion to Euler angles (roll, pitch, yaw).
+
+    Uses the ZYX (yaw-pitch-roll) convention, matching PyBullet's
+    ``getEulerFromQuaternion``.
+
+    Args:
+        q: Quaternion ``(x, y, z, w)``.
+
+    Returns:
+        Euler angles ``(roll, pitch, yaw)`` in radians.
+
+    Example::
+
+        roll, pitch, yaw = quaternion_to_euler(robot.base_orientation)
+    """
+    x, y, z, w = float(q[0]), float(q[1]), float(q[2]), float(q[3])
+
+    # Roll (rotation around X)
+    sinr_cosp = 2.0 * (w * x + y * z)
+    cosr_cosp = 1.0 - 2.0 * (x * x + y * y)
+    roll = math.atan2(sinr_cosp, cosr_cosp)
+
+    # Pitch (rotation around Y)
+    sinp = 2.0 * (w * y - z * x)
+    sinp = max(-1.0, min(1.0, sinp))  # clamp for numerical safety
+    pitch = math.asin(sinp)
+
+    # Yaw (rotation around Z)
+    siny_cosp = 2.0 * (w * z + x * y)
+    cosy_cosp = 1.0 - 2.0 * (y * y + z * z)
+    yaw = math.atan2(siny_cosp, cosy_cosp)
+
+    return (roll, pitch, yaw)
+
+
+def euler_to_quaternion(
+    roll: float,
+    pitch: float,
+    yaw: float,
+) -> tuple[float, float, float, float]:
+    """Convert Euler angles (roll, pitch, yaw) to a quaternion.
+
+    Uses the ZYX (yaw-pitch-roll) convention, matching PyBullet's
+    ``getQuaternionFromEuler``.
+
+    Args:
+        roll: Rotation around X axis in radians.
+        pitch: Rotation around Y axis in radians.
+        yaw: Rotation around Z axis in radians.
+
+    Returns:
+        Quaternion ``(x, y, z, w)``.
+
+    Example::
+
+        q = euler_to_quaternion(0.0, 0.0, math.pi / 2)
+    """
+    cr = math.cos(roll * 0.5)
+    sr = math.sin(roll * 0.5)
+    cp = math.cos(pitch * 0.5)
+    sp = math.sin(pitch * 0.5)
+    cy = math.cos(yaw * 0.5)
+    sy = math.sin(yaw * 0.5)
+
+    w = cr * cp * cy + sr * sp * sy
+    x = sr * cp * cy - cr * sp * sy
+    y = cr * sp * cy + sr * cp * sy
+    z = cr * cp * sy - sr * sp * cy
+
+    return (x, y, z, w)
+
+
+def normalize(v: Sequence[float]) -> np.ndarray:
+    """Return the unit vector of a vector.
+
+    Args:
+        v: Input vector (any length).
+
+    Returns:
+        Unit vector as a NumPy array, or the zero vector if norm is zero.
+
+    Example::
+
+        direction = normalize([1.0, 2.0, 3.0])
+    """
+    arr = np.asarray(v, dtype=np.float64)
+    norm = np.linalg.norm(arr)
+    if norm == 0.0:
+        return arr
+    return arr / norm
+
+
+def clamp(value: float, lo: float, hi: float) -> float:
+    """Clamp a scalar value to the range ``[lo, hi]``.
+
+    Args:
+        value: Input value.
+        lo: Lower bound.
+        hi: Upper bound.
+
+    Returns:
+        Clamped value.
+
+    Example::
+
+        safe_speed = clamp(desired_speed, -10.0, 10.0)
+    """
+    return max(float(lo), min(float(hi), float(value)))
+
+
+def lerp(a: float, b: float, t: float) -> float:
+    """Linear interpolation between two scalar values.
+
+    Args:
+        a: Start value.
+        b: End value.
+        t: Interpolation parameter in ``[0, 1]``.
+
+    Returns:
+        Interpolated value ``a + t * (b - a)``.
+
+    Example::
+
+        mid = lerp(0.0, 10.0, 0.5)   # → 5.0
+    """
+    return float(a) + float(t) * (float(b) - float(a))
+
+
+def wrap_angle(angle: float) -> float:
+    """Wrap an angle to the range ``[-π, π]``.
+
+    Args:
+        angle: Angle in radians.
+
+    Returns:
+        Wrapped angle in radians.
+
+    Example::
+
+        wrapped = wrap_angle(4.0)   # → 4.0 - 2π ≈ -2.28
+    """
+    return math.atan2(math.sin(angle), math.cos(angle))
+
+
+def vec3_magnitude(v: Sequence[float]) -> float:
+    """Return the magnitude (L2 norm) of a 3D vector.
+
+    Args:
+        v: Vector ``(x, y, z)``.
+
+    Returns:
+        Scalar magnitude.
+
+    Example::
+
+        speed = vec3_magnitude(robot.base_velocity)
+    """
+    return math.sqrt(v[0] ** 2 + v[1] ** 2 + v[2] ** 2)

bulletlab/utils/timer.py

@@ -0,0 +1,107 @@
+"""
+SimTimer – a utility for tracking simulation time and wall-clock time.
+
+Example::
+
+    from bulletlab.utils.timer import SimTimer
+
+    timer = SimTimer(timestep=1/240)
+    for _ in range(1000):
+        sim.step()
+        timer.tick()
+    print(f"Sim time: {timer.sim_time:.3f}s  Wall time: {timer.wall_time:.3f}s")
+"""
+
+from __future__ import annotations
+
+import time
+
+
+class SimTimer:
+    """Tracks simulation step count, simulated time, and wall-clock time.
+
+    Args:
+        timestep: Simulation timestep in seconds (should match
+            :attr:`Simulation.timestep`).
+
+    Example::
+
+        timer = SimTimer(timestep=1/240)
+        timer.tick()                  # call each sim step
+        print(timer.sim_time)         # time in seconds
+        print(timer.wall_time)        # real-world elapsed seconds
+        print(timer.step_count)       # total ticks
+    """
+
+    def __init__(self, timestep: float = 1.0 / 240.0) -> None:
+        self._timestep = timestep
+        self._step_count: int = 0
+        self._start_time: float = time.monotonic()
+        self._last_tick_time: float = self._start_time
+
+    def tick(self) -> None:
+        """Advance the timer by one simulation step.
+
+        Call this once per call to :meth:`Simulation.step`.
+
+        Example::
+
+            timer.tick()
+        """
+        self._step_count += 1
+        self._last_tick_time = time.monotonic()
+
+    def reset(self) -> None:
+        """Reset all counters to zero.
+
+        Example::
+
+            timer.reset()
+        """
+        self._step_count = 0
+        self._start_time = time.monotonic()
+        self._last_tick_time = self._start_time
+
+    @property
+    def step_count(self) -> int:
+        """Total number of :meth:`tick` calls since creation or last :meth:`reset`."""
+        return self._step_count
+
+    @property
+    def sim_time(self) -> float:
+        """Simulated elapsed time in seconds (``step_count * timestep``)."""
+        return self._step_count * self._timestep
+
+    @property
+    def wall_time(self) -> float:
+        """Real-world elapsed time in seconds since creation or last :meth:`reset`."""
+        return time.monotonic() - self._start_time
+
+    @property
+    def timestep(self) -> float:
+        """The configured simulation timestep in seconds."""
+        return self._timestep
+
+    @timestep.setter
+    def timestep(self, value: float) -> None:
+        self._timestep = float(value)
+
+    @property
+    def real_time_factor(self) -> float:
+        """Ratio of simulated time to wall-clock time.
+
+        A value of 1.0 means the simulation runs in real-time.
+        A value > 1.0 means the simulation is running faster than real-time.
+        """
+        wt = self.wall_time
+        if wt == 0.0:
+            return 0.0
+        return self.sim_time / wt
+
+    def __repr__(self) -> str:
+        return (
+            f"SimTimer(step={self._step_count}, "
+            f"sim_t={self.sim_time:.3f}s, "
+            f"wall_t={self.wall_time:.3f}s, "
+            f"rtf={self.real_time_factor:.2f})"
+        )

bulletlab/utils/urdf_utils.py

@@ -0,0 +1,114 @@
+"""
+URDF discovery utilities for BulletLab.
+
+Provides helpers for finding URDF files in the pybullet_data asset library
+and scanning user-provided search paths.
+
+Example::
+
+    from bulletlab.utils.urdf_utils import find_urdf, list_available_urdfs
+
+    path = find_urdf("kuka_iiwa/model.urdf")
+    print(list_available_urdfs())
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import pybullet_data
+
+
+def get_pybullet_data_path() -> Path:
+    """Return the path to the pybullet_data asset directory.
+
+    Returns:
+        :class:`pathlib.Path` pointing to pybullet_data.
+
+    Example::
+
+        data_path = get_pybullet_data_path()
+    """
+    return Path(pybullet_data.getDataPath())
+
+
+def find_urdf(
+    filename: str,
+    extra_search_paths: list[str | Path] | None = None,
+) -> Path:
+    """Search for a URDF file by name.
+
+    Searches in the following order:
+    1. Absolute path (if ``filename`` is absolute and exists)
+    2. Extra user-provided search paths
+    3. pybullet_data directory (recursively)
+
+    Args:
+        filename: Filename or relative path (e.g. ``"kuka_iiwa/model.urdf"``).
+        extra_search_paths: Additional directories to search.
+
+    Returns:
+        Resolved :class:`pathlib.Path` to the URDF.
+
+    Raises:
+        FileNotFoundError: If the file cannot be found in any search location.
+
+    Example::
+
+        path = find_urdf("plane.urdf")
+        path = find_urdf("kuka_iiwa/model.urdf")
+    """
+    # 1. Absolute path
+    p = Path(filename)
+    if p.is_absolute() and p.exists():
+        return p
+
+    # 2. Extra search paths
+    search_roots: list[Path] = []
+    if extra_search_paths:
+        search_roots.extend(Path(sp) for sp in extra_search_paths)
+
+    # 3. pybullet_data
+    search_roots.append(get_pybullet_data_path())
+
+    for root in search_roots:
+        # Direct join
+        candidate = root / filename
+        if candidate.exists():
+            return candidate
+        # Recursive search by basename
+        basename = Path(filename).name
+        for found in root.rglob(basename):
+            if found.is_file():
+                return found
+
+    raise FileNotFoundError(
+        f"URDF/MJCF file not found: {filename!r}. "
+        f"Searched: {[str(r) for r in search_roots]}"
+    )
+
+
+def list_available_urdfs(max_results: int = 200) -> list[str]:
+    """List URDF and MJCF files available in pybullet_data.
+
+    Args:
+        max_results: Maximum number of results to return.
+
+    Returns:
+        List of relative paths (relative to pybullet_data root).
+
+    Example::
+
+        for name in list_available_urdfs():
+            print(name)
+    """
+    root = get_pybullet_data_path()
+    results: list[str] = []
+    for ext in ("*.urdf", "*.xml", "*.sdf"):
+        for path in root.rglob(ext):
+            rel = str(path.relative_to(root))
+            results.append(rel)
+            if len(results) >= max_results:
+                return sorted(results)
+    return sorted(results)

bulletlab-0.1.2.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: BulletLab
+Version: 0.1.2
+Summary: A high-level robotics simulation and experimentation framework built on PyBullet.
+Home-page: https://github.com/NuclearVenom/BulletLab
+Author: Ranasurya Ghosh
+Author-email: Ranasurya Ghosh <ranasuryaghosh@gmail.com>
+Maintainer-email: Ranasurya Ghosh <ranasuryaghosh@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NuclearVenom/BulletLab
+Project-URL: Documentation, https://nuclearvenom.bulletlab.docs
+Project-URL: Repository, https://github.com/NuclearVenom/BulletLab
+Project-URL: Issues, https://github.com/NuclearVenom/BulletLab/issues
+Keywords: robotics,simulation,pybullet,reinforcement-learning,telemetry,imgui,physics,research,robot-control,robotics-framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pybullet>=3.2.6
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: imgui[glfw]>=2.0.0
+Requires-Dist: pyqtgraph>=0.13.3
+Requires-Dist: PyQt5>=5.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: mkdocs>=1.5.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.23.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.4.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+
+<h1>
+  <img src="https://raw.githubusercontent.com/NuclearVenom/BulletLab/main/assets/logo.png" width="40" align="center" alt="[logo]">
+  BulletLab
+</h1>
+
+Developed by [Ranasurya Ghosh](https://github.com/NuclearVenom)
+
+
+>**A robotics experimentation framework that transforms PyBullet robots into intuitive Python objects, with modern ImGui-based controls, telemetry, visualization, and reinforcement learning workflows.**
+
+[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**Install BulletLab library:** `pip install bulletlab`<br><br>
+[Read Documentation](https://nuclearvenom.github.io/BulletLab/)
+<br><br>
+
+![BulletLab example UI](https://raw.githubusercontent.com/NuclearVenom/BulletLab/main/assets/bulletlab_ui.png)
+
+---
+
+## What is BulletLab?
+
+BulletLab provides a high-level object-oriented interface to [PyBullet](https://pybullet.org/wordpress/) that simplifies robotics experimentation by exposing joints, links, sensors, and environments as intuitive Python objects instead of raw physics engine IDs. It combines real-time simulation with a [ImGui](https://www.dearimgui.com/)-powered modern interface for interactive control, parameter tuning, telemetry visualization, and experiment management, while also offering reinforcement learning integration for training and evaluating autonomous robotic systems within a unified workflow.
+
+**Instead of this:**
+```python
+p.setJointMotorControl2(
+    robot_id, joint_index,
+    controlMode=p.VELOCITY_CONTROL,
+    targetVelocity=15,
+    force=100
+)
+```
+
+**You write this:**
+```python
+robot.joints["motor"].velocity = 15
+```
+
+---
+
+## Architecture
+
+BulletLab uses a **two-window architecture**:
+
+| Window | Purpose |
+|--------|---------|
+| PyBullet Native Window | Physics simulation, 3D rendering, camera |
+| BulletLab ImGui Window | Control panels, telemetry, live plots, console |
+
+These windows communicate through Python objects. BulletLab does **not** attempt to replace PyBullet's renderer or embed ImGui inside the simulation viewport.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install bulletlab
+# or from source:
+pip install -e .
+```
+
+### Basic Example
+
+```python
+from bulletlab import Simulation, Robot
+from bulletlab.ui import BulletLabUI
+
+# Create simulation
+sim = Simulation()
+sim.start()
+
+# Load robot
+robot = Robot.load("path/to/robot.urdf", sim=sim)
+
+# Control joints by name
+robot.joints["wheel_left"].velocity = 10
+robot.joints["wheel_right"].velocity = 10
+
+# Modify physics parameters
+robot.links["chassis"].mass = 5.0
+robot.links["wheel_fl"].friction = 1.2
+
+# Get robot state
+state = robot.get_state()
+print(f"Position: {robot.base_position}")
+print(f"Roll: {robot.roll:.2f}°")
+
+# Build UI
+ui = BulletLabUI(sim=sim)
+ui.register_panel(...)
+ui.run()
+```
+
+### Telemetry & Logging
+
+```python
+from bulletlab.telemetry import TelemetryManager
+from bulletlab.logging import DataLogger
+
+telemetry = TelemetryManager()
+telemetry.watch("Speed", lambda: robot.base_velocity[0])
+telemetry.watch("Roll",  lambda: robot.roll)
+
+logger = DataLogger()
+logger.watch("speed", lambda: robot.base_velocity[0])
+logger.start("run1.csv")
+
+for _ in range(1000):
+    sim.step()
+    telemetry.update()
+    logger.step()
+
+logger.stop()
+```
+
+### Live Plotting
+
+```python
+from bulletlab.plotting import LivePlot
+
+plot = LivePlot(title="Robot Speed")
+plot.watch("Speed", lambda: robot.base_velocity[0], color="#00ff88")
+plot.start()
+
+for _ in range(1000):
+    sim.step()
+    plot.update()
+```
+
+### ImGui Control Panel
+
+```python
+from bulletlab.ui import BulletLabUI
+from bulletlab.ui import widgets as ui
+
+app = BulletLabUI(sim=sim, robots=[robot])
+
+@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 Enabled", lambda: motors_on,
+                setter=lambda v: toggle_motors(v))
+
+app.run()
+```
+
+---
+
+## Supported Robot Types
+
+BulletLab is completely generic — no code assumes a specific robot type:
+
+- Cars & rovers
+- Drones & quadrotors
+- Robotic arms
+- Self-balancing robots
+- Quadrupeds
+- Humanoids
+- Custom mechanisms
+
+---
+
+## Reinforcement Learning
+
+BulletLab exposes clean state/action interfaces without depending on any ML framework:
+
+```python
+# Compatible with any RL approach
+state = robot.get_state()      # → numpy array
+action = my_policy(state)      # → numpy array
+robot.apply_action(action)     # → updates joints
+
+# Manual Q-learning, SARSA, evolutionary algorithms — all supported
+```
+
+---
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| `examples/01_differential_drive_rover.py` | Rover with wheel velocity control |
+| `examples/02_robotic_arm.py` | Joint position control with ImGui sliders |
+| `examples/03_self_balancing_robot.py` | PD controller for balance |
+| `examples/04_drone_parameter_tuning.py` | Thrust/mass parameter exploration |
+| `examples/05_generic_robot_inspector.py` | Load any URDF and inspect it |
+
+Run any example:
+```bash
+python examples/01_differential_drive_rover.py
+```
+
+---
+
+## Documentation
+
+```bash
+pip install -e ".[dev]"
+mkdocs serve
+```
+
+Then visit http://localhost:8000
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v --cov=bulletlab --cov-report=term-missing
+```
+
+---
+
+## Technology Stack
+
+| Component | Library |
+|-----------|---------|
+| Physics | PyBullet |
+| UI | Dear ImGui (pyimgui) |
+| Data | NumPy, Pandas |
+| Config | PyYAML |
+| Plotting | PyQtGraph |
+| Testing | PyTest |
+| Docs | MkDocs + mkdocstrings |
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.