bulletlab 0.1.0__py3-none-any.whl

bulletlab/__init__.py

@@ -0,0 +1,48 @@
+"""
+BulletLab – A fast, extensible robotics experimentation framework built on PyBullet.
+
+Developed by Ranasurya Ghosh (https://github.com/NuclearVenom/BulletLab)
+
+BulletLab provides a high-level Python API over PyBullet, making robotics
+experimentation significantly easier by exposing robots as structured Python
+objects rather than raw physics engine primitives.
+
+Quick Start::
+
+    from bulletlab import Simulation, Robot
+
+    sim = Simulation()
+    sim.start()
+
+    robot = Robot.load("robot.urdf", sim=sim)
+    robot.joints["motor"].velocity = 15
+    robot.links["wheel"].mass = 2.5
+
+    while True:
+        sim.step()
+"""
+
+from bulletlab.core.simulation import Simulation
+from bulletlab.core.world import World
+from bulletlab.robot.robot import Robot
+from bulletlab.robot.joint import Joint
+from bulletlab.robot.link import Link
+from bulletlab.telemetry.manager import TelemetryManager
+from bulletlab.logging.logger import DataLogger
+from bulletlab.plotting.live_plot import LivePlot
+
+__version__ = "0.1.0"
+__author__ = "Ranasurya Ghosh"
+__url__ = "https://github.com/NuclearVenom/BulletLab"
+__license__ = "MIT"
+
+__all__ = [
+    "Simulation",
+    "World",
+    "Robot",
+    "Joint",
+    "Link",
+    "TelemetryManager",
+    "DataLogger",
+    "LivePlot",
+]

bulletlab/core/__init__.py

@@ -0,0 +1,10 @@
+"""
+BulletLab core subpackage.
+
+Provides the Simulation and World classes — the foundation of every BulletLab session.
+"""
+
+from bulletlab.core.simulation import Simulation
+from bulletlab.core.world import World
+
+__all__ = ["Simulation", "World"]

bulletlab/core/simulation.py

@@ -0,0 +1,377 @@
+"""
+Simulation – the central controller for a BulletLab physics session.
+
+The Simulation class manages the PyBullet physics server connection, controls
+the simulation time step, gravity, stepping, pausing, and tracks all robots
+loaded into the scene.
+
+Example::
+
+    from bulletlab import Simulation
+
+    sim = Simulation()
+    sim.start()                # connects to PyBullet GUI
+    sim.gravity = (0, 0, -9.81)
+    sim.timestep = 1.0 / 240.0
+
+    while True:
+        sim.step()
+
+    sim.stop()
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Optional
+
+import pybullet as p
+import pybullet_data
+
+if TYPE_CHECKING:
+    from bulletlab.robot.robot import Robot
+
+
+class Simulation:
+    """Central controller for a BulletLab physics simulation session.
+
+    Wraps the PyBullet physics server and provides a high-level interface
+    for connecting, stepping, pausing, resetting, and configuring the
+    simulation environment.
+
+    Args:
+        mode: PyBullet connection mode. Use ``"gui"`` for an interactive
+            window or ``"direct"`` for headless (testing/RL) mode.
+        gravity: Initial gravity vector as ``(gx, gy, gz)``.
+            Defaults to ``(0, 0, -9.81)``.
+        timestep: Physics timestep in seconds. Defaults to ``1/240``.
+        real_time: If ``True``, enable real-time simulation in GUI mode.
+
+    Example::
+
+        sim = Simulation(mode="gui")
+        sim.start()
+        sim.gravity = (0, 0, -9.81)
+
+        for _ in range(1000):
+            sim.step()
+
+        sim.stop()
+    """
+
+    GUI = p.GUI
+    DIRECT = p.DIRECT
+
+    def __init__(
+        self,
+        mode: str = "gui",
+        gravity: tuple[float, float, float] = (0.0, 0.0, -9.81),
+        timestep: float = 1.0 / 240.0,
+        real_time: bool = False,
+        hide_gui: bool = True,
+    ) -> None:
+        self._mode_str = mode.lower()
+        self._mode = p.GUI if self._mode_str == "gui" else p.DIRECT
+        self._gravity = gravity
+        self._timestep = timestep
+        self._real_time = real_time
+        self._hide_gui = hide_gui
+        self._client_id: int = -1
+        self._paused: bool = False
+        self._step_count: int = 0
+        self._robots: list["Robot"] = []
+        self._connected: bool = False
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> "Simulation":
+        """Connect to the PyBullet server and configure the environment.
+
+        Returns:
+            self, for method chaining.
+
+        Example::
+
+            sim = Simulation().start()
+        """
+        if self._connected:
+            return self
+
+        self._client_id = p.connect(self._mode)
+        p.setAdditionalSearchPath(pybullet_data.getDataPath(), physicsClientId=self._client_id)
+        p.setGravity(*self._gravity, physicsClientId=self._client_id)
+        p.setTimeStep(self._timestep, physicsClientId=self._client_id)
+
+        if self._mode == p.GUI:
+            if self._hide_gui:
+                # Remove all PyBullet built-in sidebar panels, sliders,
+                # and debug widgets. BulletLab provides its own ImGui UI.
+                p.configureDebugVisualizer(
+                    p.COV_ENABLE_GUI, 0, physicsClientId=self._client_id
+                )
+            if self._real_time:
+                p.setRealTimeSimulation(1, physicsClientId=self._client_id)
+
+        self._connected = True
+        return self
+
+
+    def stop(self) -> None:
+        """Disconnect from the PyBullet server.
+
+        Example::
+
+            sim.stop()
+        """
+        if self._connected:
+            try:
+                p.disconnect(physicsClientId=self._client_id)
+            except Exception:
+                pass
+            self._connected = False
+            self._client_id = -1
+
+    # Alias for stop()
+    disconnect = stop
+
+    def reset(self) -> None:
+        """Reset the simulation to a clean state.
+
+        Removes all objects from the world, resets the step counter,
+        and reloads the data search path. Robot references in
+        ``self.robots`` are cleared.
+
+        Example::
+
+            sim.reset()
+        """
+        if not self._connected:
+            return
+        p.resetSimulation(physicsClientId=self._client_id)
+        p.setAdditionalSearchPath(pybullet_data.getDataPath(), physicsClientId=self._client_id)
+        p.setGravity(*self._gravity, physicsClientId=self._client_id)
+        p.setTimeStep(self._timestep, physicsClientId=self._client_id)
+        self._robots.clear()
+        self._step_count = 0
+        self._paused = False
+
+    # ------------------------------------------------------------------
+    # Stepping
+    # ------------------------------------------------------------------
+
+    def step(self) -> None:
+        """Advance the simulation by one timestep.
+
+        Does nothing if the simulation is paused or not connected.
+
+        Example::
+
+            for _ in range(1000):
+                sim.step()
+        """
+        if not self._connected or self._paused:
+            return
+        p.stepSimulation(physicsClientId=self._client_id)
+        self._step_count += 1
+
+    def pause(self) -> None:
+        """Pause the simulation. Calls to :meth:`step` are no-ops while paused.
+
+        Example::
+
+            sim.pause()
+        """
+        self._paused = True
+
+    def resume(self) -> None:
+        """Resume a paused simulation.
+
+        Example::
+
+            sim.resume()
+        """
+        self._paused = False
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def gravity(self) -> tuple[float, float, float]:
+        """Gravity vector ``(gx, gy, gz)`` in m/s².
+
+        Example::
+
+            sim.gravity = (0, 0, -9.81)   # Earth gravity
+            sim.gravity = (0, 0, -1.62)   # Moon gravity
+        """
+        return self._gravity
+
+    @gravity.setter
+    def gravity(self, value: tuple[float, float, float]) -> None:
+        self._gravity = tuple(float(v) for v in value)  # type: ignore[assignment]
+        if self._connected:
+            p.setGravity(*self._gravity, physicsClientId=self._client_id)
+
+    @property
+    def timestep(self) -> float:
+        """Physics timestep in seconds.
+
+        Example::
+
+            sim.timestep = 1.0 / 480.0   # higher resolution
+        """
+        return self._timestep
+
+    @timestep.setter
+    def timestep(self, value: float) -> None:
+        self._timestep = float(value)
+        if self._connected:
+            p.setTimeStep(self._timestep, physicsClientId=self._client_id)
+
+    @property
+    def is_paused(self) -> bool:
+        """``True`` if the simulation is currently paused."""
+        return self._paused
+
+    @property
+    def is_connected(self) -> bool:
+        """``True`` if connected to a PyBullet physics server."""
+        return self._connected
+
+    @property
+    def client_id(self) -> int:
+        """The PyBullet physics server client ID.
+
+        This is an internal identifier. Most users should not need it.
+        """
+        return self._client_id
+
+    @property
+    def step_count(self) -> int:
+        """Total number of simulation steps taken since last reset."""
+        return self._step_count
+
+    @property
+    def elapsed_time(self) -> float:
+        """Simulated time elapsed in seconds since last reset."""
+        return self._step_count * self._timestep
+
+    @property
+    def robots(self) -> list["Robot"]:
+        """List of all robots currently registered in this simulation."""
+        return list(self._robots)
+
+    # ------------------------------------------------------------------
+    # Robot management
+    # ------------------------------------------------------------------
+
+    def add_robot(self, robot: "Robot") -> None:
+        """Register a robot with this simulation.
+
+        This is called automatically by :meth:`Robot.load` when ``sim`` is
+        provided, so you rarely need to call this directly.
+
+        Args:
+            robot: A :class:`~bulletlab.robot.robot.Robot` instance.
+
+        Example::
+
+            sim.add_robot(robot)
+        """
+        if robot not in self._robots:
+            self._robots.append(robot)
+
+    def remove_robot(self, robot: "Robot") -> None:
+        """Unregister a robot from this simulation.
+
+        Args:
+            robot: The robot to remove.
+        """
+        if robot in self._robots:
+            self._robots.remove(robot)
+
+    # ------------------------------------------------------------------
+    # Utilities
+    # ------------------------------------------------------------------
+
+    def add_debug_text(
+        self,
+        text: str,
+        position: tuple[float, float, float],
+        color: tuple[float, float, float] = (1.0, 1.0, 1.0),
+        size: float = 1.5,
+    ) -> int:
+        """Add a text label to the PyBullet debug visualizer.
+
+        Args:
+            text: Text to display.
+            position: 3D world position ``(x, y, z)``.
+            color: RGB color normalized to [0, 1].
+            size: Text size multiplier.
+
+        Returns:
+            Debug item ID (can be used to remove later).
+        """
+        if not self._connected:
+            return -1
+        return p.addUserDebugText(
+            text,
+            list(position),
+            textColorRGB=list(color),
+            textSize=size,
+            physicsClientId=self._client_id,
+        )
+
+    def remove_debug_item(self, item_id: int) -> None:
+        """Remove a debug visualizer item by ID.
+
+        Args:
+            item_id: ID returned by :meth:`add_debug_text` or similar.
+        """
+        if self._connected:
+            p.removeUserDebugItem(item_id, physicsClientId=self._client_id)
+
+    def set_camera(
+        self,
+        distance: float = 3.0,
+        yaw: float = 50.0,
+        pitch: float = -35.0,
+        target: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    ) -> None:
+        """Set the PyBullet debug camera position.
+
+        Args:
+            distance: Camera distance from target.
+            yaw: Camera yaw angle in degrees.
+            pitch: Camera pitch angle in degrees.
+            target: Camera target position ``(x, y, z)``.
+        """
+        if self._connected and self._mode == p.GUI:
+            p.resetDebugVisualizerCamera(
+                cameraDistance=distance,
+                cameraYaw=yaw,
+                cameraPitch=pitch,
+                cameraTargetPosition=list(target),
+                physicsClientId=self._client_id,
+            )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "Simulation":
+        self.start()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.stop()
+
+    def __repr__(self) -> str:
+        status = "connected" if self._connected else "disconnected"
+        return (
+            f"Simulation(mode={self._mode_str!r}, {status}, "
+            f"step={self._step_count}, t={self.elapsed_time:.3f}s)"
+        )

bulletlab/core/world.py

@@ -0,0 +1,173 @@
+"""
+World – helper for populating a BulletLab simulation with environment objects.
+
+The World class provides convenient methods for loading static environment
+geometry (ground planes, terrain, obstacles) into the simulation.
+
+Example::
+
+    from bulletlab import Simulation
+    from bulletlab.core.world import World
+
+    sim = Simulation().start()
+    world = World(sim)
+    world.load_plane()
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import pybullet as p
+import pybullet_data
+
+from bulletlab.core.simulation import Simulation
+
+
+class World:
+    """Helper for populating the simulation environment with static geometry.
+
+    Args:
+        sim: The :class:`~bulletlab.core.simulation.Simulation` instance to use.
+
+    Example::
+
+        sim = Simulation().start()
+        world = World(sim)
+        world.load_plane()
+        world.load_urdf("box.urdf", position=(2, 0, 0.5))
+    """
+
+    def __init__(self, sim: Simulation) -> None:
+        self._sim = sim
+        self._bodies: list[int] = []
+
+    # ------------------------------------------------------------------
+    # Loaders
+    # ------------------------------------------------------------------
+
+    def load_plane(
+        self,
+        texture_scale: float = 1.0,
+    ) -> int:
+        """Load the standard flat ground plane.
+
+        Uses the ``plane.urdf`` asset bundled with pybullet_data.
+
+        Args:
+            texture_scale: Not used currently; reserved for future texture
+                scaling support.
+
+        Returns:
+            PyBullet body ID of the plane.
+
+        Example::
+
+            world.load_plane()
+        """
+        body_id = p.loadURDF(
+            "plane.urdf",
+            physicsClientId=self._sim.client_id,
+        )
+        self._bodies.append(body_id)
+        return body_id
+
+    def load_urdf(
+        self,
+        path: str | Path,
+        position: tuple[float, float, float] = (0.0, 0.0, 0.0),
+        orientation: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0),
+        fixed: bool = True,
+        scale: float = 1.0,
+    ) -> int:
+        """Load an arbitrary URDF as a static or dynamic object.
+
+        Args:
+            path: Path to the URDF file. Can be an absolute path or a
+                filename resolvable from the pybullet_data search path.
+            position: Initial position ``(x, y, z)`` in meters.
+            orientation: Initial orientation as a quaternion ``(x, y, z, w)``.
+            fixed: If ``True``, the base link is fixed to the world frame.
+            scale: Global scale factor for the loaded model.
+
+        Returns:
+            PyBullet body ID.
+
+        Example::
+
+            box_id = world.load_urdf("cube_small.urdf", position=(1, 0, 0.5))
+        """
+        flags = p.URDF_USE_INERTIA_FROM_FILE
+        body_id = p.loadURDF(
+            str(path),
+            basePosition=list(position),
+            baseOrientation=list(orientation),
+            useFixedBase=fixed,
+            globalScaling=scale,
+            flags=flags,
+            physicsClientId=self._sim.client_id,
+        )
+        self._bodies.append(body_id)
+        return body_id
+
+    def load_sdf(
+        self,
+        path: str | Path,
+    ) -> list[int]:
+        """Load an SDF file and return all resulting body IDs.
+
+        Args:
+            path: Path to the SDF file.
+
+        Returns:
+            List of PyBullet body IDs created.
+        """
+        ids = p.loadSDF(str(path), physicsClientId=self._sim.client_id)
+        self._bodies.extend(ids)
+        return list(ids)
+
+    # ------------------------------------------------------------------
+    # Convenience factories
+    # ------------------------------------------------------------------
+
+    def set_gravity(self, gx: float = 0.0, gy: float = 0.0, gz: float = -9.81) -> None:
+        """Set simulation gravity.
+
+        Convenience shorthand for :attr:`Simulation.gravity`.
+
+        Args:
+            gx: X component in m/s².
+            gy: Y component in m/s².
+            gz: Z component in m/s².
+
+        Example::
+
+            world.set_gravity(gz=-1.62)   # Moon
+        """
+        self._sim.gravity = (gx, gy, gz)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def clear(self) -> None:
+        """Remove all objects loaded by this World instance.
+
+        Does not reset the entire simulation — only removes objects
+        that this :class:`World` instance created.
+        """
+        for body_id in self._bodies:
+            try:
+                p.removeBody(body_id, physicsClientId=self._sim.client_id)
+            except Exception:
+                pass
+        self._bodies.clear()
+
+    @property
+    def body_ids(self) -> list[int]:
+        """List of all PyBullet body IDs managed by this World."""
+        return list(self._bodies)
+
+    def __repr__(self) -> str:
+        return f"World(bodies={len(self._bodies)})"

bulletlab/logging/__init__.py

@@ -0,0 +1,9 @@
+"""
+BulletLab logging subpackage.
+
+Provides DataLogger with CSV and JSON backends for recording experiment data.
+"""
+
+from bulletlab.logging.logger import DataLogger
+
+__all__ = ["DataLogger"]

bulletlab/logging/csv_writer.py

@@ -0,0 +1,54 @@
+"""
+CSV writer backend for DataLogger.
+
+Internal module — used by :class:`~bulletlab.logging.logger.DataLogger`.
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import Any
+
+
+class CsvWriter:
+    """Writes tabular log data to a CSV file.
+
+    Args:
+        filepath: Output file path.
+        fieldnames: Column names.
+
+    Example::
+
+        writer = CsvWriter("run1.csv", ["t", "speed", "roll"])
+        writer.write_row({"t": 0.0, "speed": 1.5, "roll": 0.01})
+        writer.close()
+    """
+
+    def __init__(self, filepath: str | Path, fieldnames: list[str]) -> None:
+        self._filepath = Path(filepath)
+        self._fieldnames = fieldnames
+        self._file = open(self._filepath, "w", newline="", encoding="utf-8")
+        self._writer = csv.DictWriter(self._file, fieldnames=self._fieldnames)
+        self._writer.writeheader()
+
+    def write_row(self, row: dict[str, Any]) -> None:
+        """Write a single row to the CSV file.
+
+        Args:
+            row: Dictionary mapping column names to values.
+        """
+        self._writer.writerow(row)
+
+    def flush(self) -> None:
+        """Flush the write buffer to disk."""
+        self._file.flush()
+
+    def close(self) -> None:
+        """Close the file handle."""
+        if not self._file.closed:
+            self._file.flush()
+            self._file.close()
+
+    def __del__(self) -> None:
+        self.close()