# Bubblify: Interactive URDF Spherization Tool
<p align="center">
<img src="https://github.com/bheijden/bubblify/tree/master/public/spherization_xarm6.png" width="45%"/>
<img src="https://github.com/bheijden/bubblify/tree/master/public/spherization_openarm.png" width="35.9%"/>
</p>
## Overview
Bubblify is an interactive tool for creating spherical approximations of robot geometries directly from Universal Robot Description Format (URDF) specifications. It provides an intuitive 3D interface for placing collision spheres on robot links, enabling efficient collision checking for motion planning applications.
Spherized meshes can significantly reduce the computational load of collision detection, have better support across simulators, and maintain accurate approximations of the source robot model while fixing mesh defects.
## Installation
<p align="left">
<a href="https://pypi.org/project/viser/">
<img alt="codecov" src="https://img.shields.io/pypi/pyversions/viser" />
</a>
</p>
Install Bubblify directly from PyPI:
```bash
pip install bubblify
```
## Usage
### Basic Usage
Launch Bubblify with a URDF file:
```bash
bubblify --urdf_path path/to/your/robot.urdf
```
### Command Line Options
- `--urdf_path` (required): Path to the URDF file to spherize
- `--spherization_yml` (optional): Load an existing spherization configuration
- `--port` (optional): Port for the web interface (default: 8080)
- `--show_collision` (optional): Display collision meshes (default: False)
### Example Commands
```bash
# Basic usage
bubblify --urdf_path ./assets/xarm6/xarm6_rs.urdf
# Load with existing spherization
bubblify --urdf_path ./assets/xarm6/xarm6_rs.urdf --spherization_yml ./config/xarm6_spheres.yml
# Custom port and show collision meshes
bubblify --urdf_path ./robot.urdf --port 8081 --show_collision
```
## Interactive Features
### Demo Video
<p align="center">
<video width="80%" controls onloadedmetadata="this.defaultPlaybackRate=2; this.playbackRate=2;">
<source src="https://github.com/bheijden/bubblify/tree/master/public/bubblify_demo.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
</p>
## Benefits for Motion Planning
Spherical approximations offer several key advantages for robotics applications:
### Computational Efficiency
- **Fast Collision Detection**: Sphere-sphere and sphere-primitive collision checks are computationally simple
- **Reduced Query Time**: Orders of magnitude faster than mesh-based collision detection
- **Real-time Planning**: Enables real-time motion planning for complex robots
### Robustness
- **Numerical Stability**: Spheres eliminate mesh artifacts and numerical precision issues
- **Consistent Geometry**: Uniform collision representation across different simulators
- **Simplified Physics**: More stable physics simulation with primitive shapes
### Motion Planning Integration
- **Sampling-based Planners**: Faster collision checking enables more thorough space exploration
- **Optimization-based Methods**: Smooth distance gradients improve trajectory optimization
- **Multi-robot Systems**: Efficient collision checking scales better with robot count
### Compatible Motion Planning Libraries
Bubblify's spherized URDFs and YAMLs work with modern motion planning frameworks:
- **[cuRobo](https://curobo.org/)**: NVIDIA's CUDA-accelerated motion planning library
- **[VAMP](https://github.com/KavrakiLab/vamp)**: Vectorized Approximate Motion Planning
## File Formats
### Input
- **URDF Files**: Standard Robot Description Format with visual and collision meshes
### Output
- **Spherized URDF**: New URDF file with collision geometries replaced by spheres
- **Configuration YAML**: Spherization parameters for reproducible results
### Example Configuration
```yaml
spheres:
- link: "base_link"
position: [0.0, 0.0, 0.1]
radius: 0.08
- link: "link1"
position: [0.0, 0.0, 0.15]
radius: 0.06
```
## Contributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
Raw data
{
"_id": null,
"home_page": null,
"name": "bubblify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "robotics, urdf, collision, spherization, viser, gui",
"author": null,
"author_email": "Bas van der Heijden <b.heijden@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/86/58/94b29e254a75dd6ac33e8e03899355b73b734ceb8b8e6b465a0724016b34/bubblify-0.1.0.tar.gz",
"platform": null,
"description": "\n# Bubblify: Interactive URDF Spherization Tool\n\n<p align=\"center\">\n <img src=\"https://github.com/bheijden/bubblify/tree/master/public/spherization_xarm6.png\" width=\"45%\"/>\n <img src=\"https://github.com/bheijden/bubblify/tree/master/public/spherization_openarm.png\" width=\"35.9%\"/>\n</p>\n\n\n\n## Overview\n\nBubblify is an interactive tool for creating spherical approximations of robot geometries directly from Universal Robot Description Format (URDF) specifications. It provides an intuitive 3D interface for placing collision spheres on robot links, enabling efficient collision checking for motion planning applications.\n\nSpherized meshes can significantly reduce the computational load of collision detection, have better support across simulators, and maintain accurate approximations of the source robot model while fixing mesh defects.\n\n## Installation\n<p align=\"left\">\n<a href=\"https://pypi.org/project/viser/\">\n <img alt=\"codecov\" src=\"https://img.shields.io/pypi/pyversions/viser\" />\n</a>\n</p>\n\nInstall Bubblify directly from PyPI:\n\n```bash\npip install bubblify\n```\n\n## Usage\n\n### Basic Usage\n\nLaunch Bubblify with a URDF file:\n\n```bash\nbubblify --urdf_path path/to/your/robot.urdf\n```\n\n### Command Line Options\n\n- `--urdf_path` (required): Path to the URDF file to spherize\n- `--spherization_yml` (optional): Load an existing spherization configuration\n- `--port` (optional): Port for the web interface (default: 8080)\n- `--show_collision` (optional): Display collision meshes (default: False)\n\n### Example Commands\n\n```bash\n# Basic usage\nbubblify --urdf_path ./assets/xarm6/xarm6_rs.urdf\n\n# Load with existing spherization\nbubblify --urdf_path ./assets/xarm6/xarm6_rs.urdf --spherization_yml ./config/xarm6_spheres.yml\n\n# Custom port and show collision meshes\nbubblify --urdf_path ./robot.urdf --port 8081 --show_collision\n```\n\n## Interactive Features\n\n### Demo Video\n<p align=\"center\">\n <video width=\"80%\" controls onloadedmetadata=\"this.defaultPlaybackRate=2; this.playbackRate=2;\">\n <source src=\"https://github.com/bheijden/bubblify/tree/master/public/bubblify_demo.mp4\" type=\"video/mp4\">\n Your browser does not support the video tag.\n </video>\n</p>\n\n## Benefits for Motion Planning\n\nSpherical approximations offer several key advantages for robotics applications:\n\n### Computational Efficiency\n- **Fast Collision Detection**: Sphere-sphere and sphere-primitive collision checks are computationally simple\n- **Reduced Query Time**: Orders of magnitude faster than mesh-based collision detection\n- **Real-time Planning**: Enables real-time motion planning for complex robots\n\n### Robustness\n- **Numerical Stability**: Spheres eliminate mesh artifacts and numerical precision issues\n- **Consistent Geometry**: Uniform collision representation across different simulators\n- **Simplified Physics**: More stable physics simulation with primitive shapes\n\n### Motion Planning Integration\n- **Sampling-based Planners**: Faster collision checking enables more thorough space exploration\n- **Optimization-based Methods**: Smooth distance gradients improve trajectory optimization\n- **Multi-robot Systems**: Efficient collision checking scales better with robot count\n\n### Compatible Motion Planning Libraries\nBubblify's spherized URDFs and YAMLs work with modern motion planning frameworks:\n- **[cuRobo](https://curobo.org/)**: NVIDIA's CUDA-accelerated motion planning library\n- **[VAMP](https://github.com/KavrakiLab/vamp)**: Vectorized Approximate Motion Planning\n\n## File Formats\n\n### Input\n- **URDF Files**: Standard Robot Description Format with visual and collision meshes\n\n### Output\n- **Spherized URDF**: New URDF file with collision geometries replaced by spheres\n- **Configuration YAML**: Spherization parameters for reproducible results\n\n### Example Configuration\n```yaml\nspheres:\n - link: \"base_link\"\n position: [0.0, 0.0, 0.1]\n radius: 0.08\n - link: \"link1\"\n position: [0.0, 0.0, 0.15]\n radius: 0.06\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues, feature requests, or pull requests.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Interactive URDF spherization tool using Viser for collision approximation",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"robotics",
" urdf",
" collision",
" spherization",
" viser",
" gui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25119b0f0c3a23c77364723ed7368b4b2ee16f9d3aa66b8a0cb9d0bb8323f50f",
"md5": "6e05e135d96a648f84bf172ed7835264",
"sha256": "39d419a4021788181cb5f0004234d8f73c9d75701d89526d0c91079850fdf232"
},
"downloads": -1,
"filename": "bubblify-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e05e135d96a648f84bf172ed7835264",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17341,
"upload_time": "2025-09-09T08:48:28",
"upload_time_iso_8601": "2025-09-09T08:48:28.406120Z",
"url": "https://files.pythonhosted.org/packages/25/11/9b0f0c3a23c77364723ed7368b4b2ee16f9d3aa66b8a0cb9d0bb8323f50f/bubblify-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "865894b29e254a75dd6ac33e8e03899355b73b734ceb8b8e6b465a0724016b34",
"md5": "a3bff5da6b1701244b603707ed518e2a",
"sha256": "4fa6edeafea65fa0d1c21b2fdc63967f9a009b12a338a14bded099c3ddd458a3"
},
"downloads": -1,
"filename": "bubblify-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a3bff5da6b1701244b603707ed518e2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29296,
"upload_time": "2025-09-09T08:48:29",
"upload_time_iso_8601": "2025-09-09T08:48:29.882082Z",
"url": "https://files.pythonhosted.org/packages/86/58/94b29e254a75dd6ac33e8e03899355b73b734ceb8b8e6b465a0724016b34/bubblify-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 08:48:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bubblify"
}
JSON