bulletlab 0.1.0__tar.gz

bulletlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ranasurya Ghosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bulletlab-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include bulletlab *.py *.yaml *.yml *.urdf *.json
+recursive-include docs *.md *.yaml *.yml *.png
+recursive-include examples *.py *.urdf *.yaml

bulletlab-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: bulletlab
+Version: 0.1.0
+Summary: A high-level robotics simulation and experimentation framework built on PyBullet.
+Author-email: Ranasurya Ghosh <ranasuryaghosh@gmail.com>
+Maintainer: Ranasurya Ghosh
+License-Expression: MIT
+Project-URL: Repository, https://github.com/NuclearVenom/BulletLab
+Keywords: robotics,simulation,pybullet,reinforcement-learning,physics,ImGui,3D,graphics,research,telemetry,robot-control,robotics-framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering
+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: license-file
+
+# BulletLab
+Developed by [Ranasurya Ghosh](https://github.com/NuclearVenom)
+
+>**A fast, extensible robotics experimentation framework built on PyBullet, designed for rapid prototyping, testing, simulation and learning.**
+
+[![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`
+
+![BulletLab example UI](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.

bulletlab-0.1.0/README.md

@@ -0,0 +1,230 @@
+# BulletLab
+Developed by [Ranasurya Ghosh](https://github.com/NuclearVenom)
+
+>**A fast, extensible robotics experimentation framework built on PyBullet, designed for rapid prototyping, testing, simulation and learning.**
+
+[![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`
+
+![BulletLab example UI](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.

bulletlab-0.1.0/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-0.1.0/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"]