[](https://codecov.io/gh/kwesiRutledge/brom_drake-py)
# brom_drake-py
Brom is a helper library for the [Drake](https://drake.mit.edu/) robotics simulation and verification library.
Its goal is to simplify common debugging and testing activities in Drake (for example, logging the outputs
of systems in your block diagrams).
Some of Brom's features:
Feature | Code | Results
:-------------------------:|:-------------------------:|:-------------------------:
The Diagram Watcher (the `DiagramWatcher` will log + plot all output ports of your `Diagram` automatically) |`add_watcher_and_build()`| 
The Drake-ify feature (converts your URDF file into a form that Drake can consume) | `drakeify_my_urdf()` | 
Scenes (partially complete robot scenarios to test your algorithms) | (See [Examples Directory](https://github.com/kwesiRutledge/brom_drake-py/tree/main/examples/scenes) or [the Wiki](https://github.com/kwesiRutledge/brom_drake-py/wiki/Scenes)) | 
(More coming soon...)
## Installation
`brom_drake` is available on PyPI and installable with pip:
```shell
pip install brom-drake
```
### Developer install
You can also install the package during local development by cloning
the repository and running the following commands from inside it:
```bash
pip install -r requirements.txt
pip install -e .
```
## Use Cases
Here are a few of the features available in `brom_drake` and how they work.
### Easily Log Your Diagram's Signals
It is recommended that you use the convenience function `add_watcher_and_build` to add a `DiagramWatcher` to your diagram.
```python
# Drake imports
from pydrake.all import (
DiagramBuilder, Simulator,
)
# All your other imports
from brom_drake.all import add_watcher_and_build
# Create a diagram builder
builder = DiagramBuilder()
# Add and connect your systems...
# Add the watcher and build the diagram
watcher, diagram, diagram_context = add_watcher_and_build(builder)
# Set up simulation
simulator = Simulator(diagram, diagram_context)
simulator.set_target_realtime_rate(1.0)
simulator.set_publish_every_time_step(False)
# Run simulation
simulator.Initialize()
simulator.AdvanceTo(15.0)
```
What will happen whenever you use this function is that:
- The `DiagramWatcher` will be created.
- It will search through all systems that the `DiagramBuilder` has added.
- For each system, the watcher will add a `VectorLogger` to each output port that is a `kVectorValued` port.
- The `DiagramWatcher` will connect all loggers to all targeted ports (in the above case, we will target all available output ports).
- After the simulation is run and the script completes, the watcher will save all data traces for each port in `.png` files. These plots will be in a new `.brom` directory.
### Watching Specific systems
If you only want to watch a specific system, then you can do so by passing in information to the "targets" argument:
```python
watcher, _, _ = add_watcher_and_build(
builder,
targets=[
("system_name", "port_name"),
"system_name2",
],
)
```
The above code tells the watcher to watch the port named `port_name` on the system named `system_name`.
(If you don't know your system's name in Drake, then you can usually find it by using the `get_name()` method.)
## Citation
Feel free to cite this project if it helped with your work!
```
@misc{bromDrake2024,
author = "Kwesi Rutledge and the Wrench Robotics Team",
title = "Brom: A Helper Library for the Drake Toolbox",
year = 2024,
}
```
## FAQs
### Why the name Brom?
[Brom the storyteller](https://inheritance.fandom.com/wiki/Brom) is a character from the
[Inheritance](https://en.wikipedia.org/wiki/Eragon) series by Christopher Paolini.
He is a wise mentor that helps Eragon (the protagonist) master dragons. ;)
### How can I support this project?
## Related Work
Some other work in the open-source drake community:
- [kinova_drake](https://github.com/vincekurtz/kinova_drake) - A Drake-based library that builds a
simple version of the manipulation station for the Kinova Gen3 robot arm.
Also works with the hardware.
- [airo-drake](https://github.com/airo-ugent/airo-drake) - A python package meant to simplify
working with Drake and the `airo-mono` repository from the AI and Robotics Lab at Ghent University.
## To-Dos
- [ ] Figure out how to tell if two systems are connected in Drake.
- [ ] Add support for abstract output ports?
- [ ] Add more readme explanations of what is going on under the hood.
- [ ] Add Documentation
- [ ] Create a method that makes each material in a URDF file have unique names if they have specific values
- [ ] Add methods for saving the state names on state plots from diagram watcher
- [X] Add methods for over or under-approximating complex mehes with cylinders or circles or other shapes.
- [ ] Allow for the user to give "Drake-unfriendly" URDFs to `ShowMeThisModel` scene
Raw data
{
"_id": null,
"home_page": "https://github.com/kwesiRutledge/brom_drake-py",
"name": "brom-drake",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "drake, robotics, testing, logging",
"author": "Kwesi Rutledge",
"author_email": "thesolitaryecrivain@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/1f/76a618c472153aa7dc9b6234490b3dad36e77ff682dc8d37aad098ea4a99/brom_drake-0.2.11.tar.gz",
"platform": null,
"description": "\n[](https://codecov.io/gh/kwesiRutledge/brom_drake-py)\n\n# brom_drake-py\nBrom is a helper library for the [Drake](https://drake.mit.edu/) robotics simulation and verification library.\nIts goal is to simplify common debugging and testing activities in Drake (for example, logging the outputs\nof systems in your block diagrams). \n\nSome of Brom's features:\n\nFeature | Code | Results\n:-------------------------:|:-------------------------:|:-------------------------:\nThe Diagram Watcher (the `DiagramWatcher` will log + plot all output ports of your `Diagram` automatically) |`add_watcher_and_build()`| \nThe Drake-ify feature (converts your URDF file into a form that Drake can consume) | `drakeify_my_urdf()` | \nScenes (partially complete robot scenarios to test your algorithms) | (See [Examples Directory](https://github.com/kwesiRutledge/brom_drake-py/tree/main/examples/scenes) or [the Wiki](https://github.com/kwesiRutledge/brom_drake-py/wiki/Scenes)) | \n\n(More coming soon...)\n\n## Installation\n\n`brom_drake` is available on PyPI and installable with pip:\n\n```shell\npip install brom-drake\n```\n\n### Developer install\n\nYou can also install the package during local development by cloning\nthe repository and running the following commands from inside it:\n\n```bash\npip install -r requirements.txt\npip install -e .\n```\n\n## Use Cases\n\nHere are a few of the features available in `brom_drake` and how they work.\n\n### Easily Log Your Diagram's Signals\n\nIt is recommended that you use the convenience function `add_watcher_and_build` to add a `DiagramWatcher` to your diagram.\n\n```python\n# Drake imports\nfrom pydrake.all import (\n DiagramBuilder, Simulator,\n)\n# All your other imports\n\nfrom brom_drake.all import add_watcher_and_build\n\n# Create a diagram builder\nbuilder = DiagramBuilder()\n\n# Add and connect your systems...\n\n# Add the watcher and build the diagram\nwatcher, diagram, diagram_context = add_watcher_and_build(builder)\n\n# Set up simulation\nsimulator = Simulator(diagram, diagram_context)\nsimulator.set_target_realtime_rate(1.0)\nsimulator.set_publish_every_time_step(False)\n\n# Run simulation\nsimulator.Initialize()\nsimulator.AdvanceTo(15.0)\n\n```\n\n\nWhat will happen whenever you use this function is that:\n- The `DiagramWatcher` will be created.\n - It will search through all systems that the `DiagramBuilder` has added.\n - For each system, the watcher will add a `VectorLogger` to each output port that is a `kVectorValued` port.\n - The `DiagramWatcher` will connect all loggers to all targeted ports (in the above case, we will target all available output ports).\n- After the simulation is run and the script completes, the watcher will save all data traces for each port in `.png` files. These plots will be in a new `.brom` directory.\n\n### Watching Specific systems\n\nIf you only want to watch a specific system, then you can do so by passing in information to the \"targets\" argument:\n```python\nwatcher, _, _ = add_watcher_and_build(\n builder,\n targets=[\n (\"system_name\", \"port_name\"),\n \"system_name2\",\n ],\n)\n```\nThe above code tells the watcher to watch the port named `port_name` on the system named `system_name`.\n(If you don't know your system's name in Drake, then you can usually find it by using the `get_name()` method.)\n\n## Citation\n\nFeel free to cite this project if it helped with your work!\n\n```\n@misc{bromDrake2024,\n author = \"Kwesi Rutledge and the Wrench Robotics Team\",\n title = \"Brom: A Helper Library for the Drake Toolbox\",\n year = 2024,\n}\n```\n\n## FAQs\n\n### Why the name Brom?\n\n[Brom the storyteller](https://inheritance.fandom.com/wiki/Brom) is a character from the\n[Inheritance](https://en.wikipedia.org/wiki/Eragon) series by Christopher Paolini.\nHe is a wise mentor that helps Eragon (the protagonist) master dragons. ;)\n\n\n\n### How can I support this project?\n \n\n## Related Work\n\nSome other work in the open-source drake community:\n- [kinova_drake](https://github.com/vincekurtz/kinova_drake) - A Drake-based library that builds a \n simple version of the manipulation station for the Kinova Gen3 robot arm.\n Also works with the hardware.\n- [airo-drake](https://github.com/airo-ugent/airo-drake) - A python package meant to simplify\n working with Drake and the `airo-mono` repository from the AI and Robotics Lab at Ghent University.\n\n## To-Dos\n\n- [ ] Figure out how to tell if two systems are connected in Drake.\n- [ ] Add support for abstract output ports?\n- [ ] Add more readme explanations of what is going on under the hood.\n- [ ] Add Documentation\n- [ ] Create a method that makes each material in a URDF file have unique names if they have specific values\n- [ ] Add methods for saving the state names on state plots from diagram watcher\n- [X] Add methods for over or under-approximating complex mehes with cylinders or circles or other shapes.\n- [ ] Allow for the user to give \"Drake-unfriendly\" URDFs to `ShowMeThisModel` scene\n",
"bugtrack_url": null,
"license": null,
"summary": "A set of convenient logging and testing tools for the Drake robotics toolbox.",
"version": "0.2.11",
"project_urls": {
"Homepage": "https://github.com/kwesiRutledge/brom_drake-py"
},
"split_keywords": [
"drake",
" robotics",
" testing",
" logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73565d472dc7d75dd61400b5d8092f7ff7521c4b338ddbc1985b38574dd276bf",
"md5": "2cedb71ac38dee7b1b899e7b092ea217",
"sha256": "66740cf39138a1ba9ee85e52f4c053c7bc54ab2bb2720755f9a28480e2092855"
},
"downloads": -1,
"filename": "brom_drake-0.2.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2cedb71ac38dee7b1b899e7b092ea217",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 101306,
"upload_time": "2024-12-13T04:15:43",
"upload_time_iso_8601": "2024-12-13T04:15:43.694048Z",
"url": "https://files.pythonhosted.org/packages/73/56/5d472dc7d75dd61400b5d8092f7ff7521c4b338ddbc1985b38574dd276bf/brom_drake-0.2.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c1f76a618c472153aa7dc9b6234490b3dad36e77ff682dc8d37aad098ea4a99",
"md5": "16320e8dbf2d773b0c0135dbf97541c8",
"sha256": "af2be17a811030ad61eac0566afd3f83b5e9f95cd200d90d3ae11ab106942ae8"
},
"downloads": -1,
"filename": "brom_drake-0.2.11.tar.gz",
"has_sig": false,
"md5_digest": "16320e8dbf2d773b0c0135dbf97541c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 64612,
"upload_time": "2024-12-13T04:15:45",
"upload_time_iso_8601": "2024-12-13T04:15:45.244083Z",
"url": "https://files.pythonhosted.org/packages/1c/1f/76a618c472153aa7dc9b6234490b3dad36e77ff682dc8d37aad098ea4a99/brom_drake-0.2.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 04:15:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kwesiRutledge",
"github_project": "brom_drake-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "drake",
"specs": []
},
{
"name": "manipulation",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "meshcat",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pycollada",
"specs": []
},
{
"name": "trimesh",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "ipdb",
"specs": []
},
{
"name": "typer",
"specs": []
},
{
"name": "loguru",
"specs": []
},
{
"name": "networkx",
"specs": []
}
],
"lcname": "brom-drake"
}
JSON
