BulletLab 0.1.2__tar.gz

bulletlab-0.1.2/BulletLab.egg-info/PKG-INFO

@@ -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.

bulletlab-0.1.2/BulletLab.egg-info/SOURCES.txt

@@ -0,0 +1,75 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+BulletLab.egg-info/PKG-INFO
+BulletLab.egg-info/SOURCES.txt
+BulletLab.egg-info/dependency_links.txt
+BulletLab.egg-info/requires.txt
+BulletLab.egg-info/top_level.txt
+bulletlab/__init__.py
+bulletlab/core/__init__.py
+bulletlab/core/simulation.py
+bulletlab/core/world.py
+bulletlab/logging/__init__.py
+bulletlab/logging/csv_writer.py
+bulletlab/logging/json_writer.py
+bulletlab/logging/logger.py
+bulletlab/plotting/__init__.py
+bulletlab/plotting/live_plot.py
+bulletlab/robot/__init__.py
+bulletlab/robot/joint.py
+bulletlab/robot/link.py
+bulletlab/robot/robot.py
+bulletlab/telemetry/__init__.py
+bulletlab/telemetry/channel.py
+bulletlab/telemetry/manager.py
+bulletlab/ui/__init__.py
+bulletlab/ui/app.py
+bulletlab/ui/widgets.py
+bulletlab/ui/panels/__init__.py
+bulletlab/ui/panels/console.py
+bulletlab/ui/panels/explorer.py
+bulletlab/ui/panels/plots.py
+bulletlab/ui/panels/properties.py
+bulletlab/ui/panels/telemetry.py
+bulletlab/utils/__init__.py
+bulletlab/utils/math_utils.py
+bulletlab/utils/timer.py
+bulletlab/utils/urdf_utils.py
+docs/index.md
+docs/quickstart.md
+docs/api/joint.md
+docs/api/link.md
+docs/api/logging.md
+docs/api/plotting.md
+docs/api/robot.md
+docs/api/simulation.md
+docs/api/telemetry.md
+docs/api/ui.md
+docs/developer/architecture.md
+docs/developer/developer_guide.md
+docs/guides/example_guide.md
+docs/guides/plotting_guide.md
+docs/guides/rl_guide.md
+docs/guides/robot_guide.md
+docs/guides/telemetry_guide.md
+docs/guides/ui_guide.md
+examples/01_differential_drive_rover.py
+examples/02_robotic_arm.py
+examples/03_self_balancing_robot.py
+examples/04_drone_parameter_tuning.py
+examples/05_generic_robot_inspector.py
+examples/06_irregular_terrain.py
+examples/demo_ui_control.py
+examples/assets/quadrotor.urdf
+tests/test_joint.py
+tests/test_link.py
+tests/test_logging.py
+tests/test_plotting.py
+tests/test_robot.py
+tests/test_simulation.py
+tests/test_telemetry.py
+tests/test_ui_panels.py
+tests/test_utils.py

bulletlab-0.1.2/BulletLab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bulletlab-0.1.2/BulletLab.egg-info/requires.txt

@@ -0,0 +1,15 @@
+pybullet>=3.2.6
+numpy>=1.24.0
+pandas>=2.0.0
+pyyaml>=6.0
+imgui[glfw]>=2.0.0
+pyqtgraph>=0.13.3
+PyQt5>=5.15.0
+
+[dev]
+pytest>=7.4.0
+pytest-cov>=4.1.0
+pytest-mock>=3.11.0
+mkdocs>=1.5.0
+mkdocstrings[python]>=0.23.0
+mkdocs-material>=9.4.0

bulletlab-0.1.2/BulletLab.egg-info/top_level.txt

@@ -0,0 +1 @@
+bulletlab

bulletlab-0.1.2/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.2/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.2/PKG-INFO

@@ -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.