# opof-sbmp
[OPOF](https://github.com/opoframework/opof) Sampling-based motion planning (SBMP) domains for high-DoF robots to accomplish real-world picking tasks. They include the optimization of planner hyperparameters, sampling distributions, and projections.
[](https://github.com/opoframework/opof-sbmp/actions/workflows/build_and_test.yml)
`opof-sbmp` is maintained by the [Kavraki Lab](https://www.kavrakilab.org/) at Rice University.
### Installation
```console
$ pip install opof-sbmp
```
`opof-sbmp` is officially tested and supported for Python 3.9, 3.10, 3.11 and Ubuntu 20.04, 22.04.
## Domain: `SBMPHyp[env,planner]`
```python
from opof_sbmp.domains import SBMPHyp
# Creates a SBMPHyp domain instance for the "Bookshelf" environment using the "RRTConnect" planner.
domain = SBMPHyp("Bookshelf", "RRTConnect")
```
##### Description
We explore doing sampling-based motion planning in a specified [environment](#environments) using a specified [planner](#planners).
Unlike the grid world domains, these planners are much more complex and the relationship between the choice of planning parameters and planner performance is unclear.
This makes it particularly suitable for OPOF, since we treat the planner as closed black-box function and specifically assume no knowledge of the planner's internals.
##### Planner optimization problem
The robot is tasked with moving its arm(s) from a start configuration to a goal configuration by running a sampling-based motion planner.
The planner optimization problem is to find a generator $G_\theta(c)$ that maps a problem instance $c$
(in this case, the combination of obstacle poses in the environment and the start and goal robot configurations) to a set of planner hyperparameters
(which depend on the planner used), such that the time taken for the motion planner to find a path is minimized.
##### Planning objective
$\boldsymbol{f}(x; c)$ is given as $-time$, where $time$ is the time taken for the motion planner to find a collision-free path
from the start to goal robot configuration.
#### Problem instance distribution
The training set and testing set contain $1000$ and $100$ problem instances respectively.
These problem instances are adapted from [MotionBenchMaker](https://github.com/KavrakiLab/motion_bench_maker).
Obstacle positions are sampled according to a predefined distribution,
while start and goal configurations are sampled using inverse kinematics for some environment-specific task.
## Environments
### `Cage`
<p align="left">
<img src="https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/cage_goal.png?raw=true" width="350px"/>
</p>
##### Description
A \(6\)-dof UR5 robot is tasked to pick up a block (green) in a cage, starting from a random robot configuration.
The position and orientation of the cage, as well as the position of the block in the cage, are randomized.
### `Bookshelf`
<p align="left">
<img src="https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/bookshelf_goal.png?raw=true" width="350px"/>
</p>
##### Description
A \(8\)-dof Fetch robot is tasked to reach for a cylinder in a bookshelf, starting from a random robot configuration.
The position and orientation of the bookshelf and cylinders, as well as the choice of cylinder to reach for, are randomized.
### `Table`
<p align="left">
<img src="https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/table_goal.png?raw=true" width="350px"/>
</p>
##### Description
A \(14\)-dof dual-arm Baxter robot must fold its arms crossed in a constricted space underneath a table and in between two vertical bars,
starting from a random robot configuration. The lateral positions of the vertical bars are randomized.
## Planners
### [`RRTConnect`](https://ompl.kavrakilab.org/classompl_1_1geometric_1_1RRTConnect.html#gRRTC)
##### Description
We grow two random search trees from the start and the goal configurations toward randomly sampled target points in the free space, until the two trees connect.
##### Planner hyperparameters
We tune the following parameters:
- _range_ $\in [0.01, 5.00]$ parameter, which limits how much to extend the trees at each step; and
- a _weight_ vector $\in \mathbb{R}^{50}$ with non-negative entries summing to $1$, which controls the sampling of target points using the experience-based sampling scheme adapted from [here](https://ieeexplore.ieee.org/abstract/document/9832486).
### [`LBKPIECE1`](https://ompl.kavrakilab.org/classompl_1_1geometric_1_1LBKPIECE1.html#gLBKPIECE1)
##### Description
Two random search trees are grown from the start and the goal configurations, but controls the exploration of the configuration space using grid-based projections.
##### Planner hyperparemeters
We tune the following parameters:
- _range_ $\in [0.01, 5.00]$ which determines ho wmuch to extend the trees at each step;
- _border_fraction_ $\in [0.001, 1]$ which determins how much to focus exploration on unexplored cells;
- _min_valid_path_fraction_ $\in [0.001, 1]$ which determins the threshold for which partially valid extensions are allowed; and
- a _projection_ vector $[0, 1]^{2 \times d} \subset \mathbb{R}^{2 \times d}$ which corresponds to the linear projection function used to induce the 2-dimensional exploration grid, where $d$ is the robot's number of degrees of freedom.
####
## Citing
TBD
## License
`opof-sbmp` is licensed under the [BSD-3 license](https://github.com/opoframework/opof-sbmp/blob/master/LICENSE.md).
`opof-sbmp` includes a copy of the following libraries as dependencies. These copies are protected and distributed according to the corresponding original license.
- [Boost](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/boost) ([homepage](https://github.com/boostorg/boost)): [Boost Software License](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/boost/LICENSE)
- [Eigen](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/Eigen) ([homepage](https://github.com/bolderflight/eigen)): [MPL2](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/Eigen/LICENSE)
- [OMPL](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/ompl) ([homepage](https://github.com/ompl/ompl)): [BSD-3](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/ompl/LICENSE)
`opof-sbmp` is maintained by the [Kavraki Lab](https://www.kavrakilab.org/) at Rice University, funded in part by NSF RI 2008720 and Rice University funds.
Raw data
{
"_id": null,
"home_page": "https://github.com/opoframework/opof-sbmp",
"name": "opof-sbmp",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "opof,optimization,machine learning,reinforcement learning,planning,motion planning,robotics",
"author": "Yiyuan Lee",
"author_email": "yiyuan.lee@rice.edu",
"download_url": "",
"platform": null,
"description": "# opof-sbmp\n\n[OPOF](https://github.com/opoframework/opof) Sampling-based motion planning (SBMP) domains for high-DoF robots to accomplish real-world picking tasks. They include the optimization of planner hyperparameters, sampling distributions, and projections.\n\n[](https://github.com/opoframework/opof-sbmp/actions/workflows/build_and_test.yml)\n\n`opof-sbmp` is maintained by the [Kavraki Lab](https://www.kavrakilab.org/) at Rice University.\n\n### Installation\n```console\n$ pip install opof-sbmp\n```\n\n`opof-sbmp` is officially tested and supported for Python 3.9, 3.10, 3.11 and Ubuntu 20.04, 22.04.\n\n## Domain: `SBMPHyp[env,planner]`\n\n```python\nfrom opof_sbmp.domains import SBMPHyp\n# Creates a SBMPHyp domain instance for the \"Bookshelf\" environment using the \"RRTConnect\" planner.\ndomain = SBMPHyp(\"Bookshelf\", \"RRTConnect\") \n```\n\n##### Description\nWe explore doing sampling-based motion planning in a specified [environment](#environments) using a specified [planner](#planners). \nUnlike the grid world domains, these planners are much more complex and the relationship between the choice of planning parameters and planner performance is unclear. \nThis makes it particularly suitable for OPOF, since we treat the planner as closed black-box function and specifically assume no knowledge of the planner's internals.\n\n##### Planner optimization problem\nThe robot is tasked with moving its arm(s) from a start configuration to a goal configuration by running a sampling-based motion planner. \nThe planner optimization problem is to find a generator $G_\\theta(c)$ that maps a problem instance $c$ \n(in this case, the combination of obstacle poses in the environment and the start and goal robot configurations) to a set of planner hyperparameters \n(which depend on the planner used), such that the time taken for the motion planner to find a path is minimized. \n\n##### Planning objective\n$\\boldsymbol{f}(x; c)$ is given as $-time$, where $time$ is the time taken for the motion planner to find a collision-free path \nfrom the start to goal robot configuration. \n\n#### Problem instance distribution\nThe training set and testing set contain $1000$ and $100$ problem instances respectively. \nThese problem instances are adapted from [MotionBenchMaker](https://github.com/KavrakiLab/motion_bench_maker). \nObstacle positions are sampled according to a predefined distribution, \nwhile start and goal configurations are sampled using inverse kinematics for some environment-specific task.\n\n## Environments\n\n### `Cage`\n\n<p align=\"left\">\n <img src=\"https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/cage_goal.png?raw=true\" width=\"350px\"/>\n</p>\n\n##### Description\nA \\(6\\)-dof UR5 robot is tasked to pick up a block (green) in a cage, starting from a random robot configuration. \nThe position and orientation of the cage, as well as the position of the block in the cage, are randomized. \n\n### `Bookshelf`\n\n<p align=\"left\">\n <img src=\"https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/bookshelf_goal.png?raw=true\" width=\"350px\"/>\n</p>\n\n##### Description\nA \\(8\\)-dof Fetch robot is tasked to reach for a cylinder in a bookshelf, starting from a random robot configuration. \nThe position and orientation of the bookshelf and cylinders, as well as the choice of cylinder to reach for, are randomized. \n\n### `Table`\n\n<p align=\"left\">\n <img src=\"https://github.com/opoframework/opof-sbmp/blob/master/docs/_static/table_goal.png?raw=true\" width=\"350px\"/>\n</p>\n\n##### Description\nA \\(14\\)-dof dual-arm Baxter robot must fold its arms crossed in a constricted space underneath a table and in between two vertical bars, \nstarting from a random robot configuration. The lateral positions of the vertical bars are randomized.\n\n## Planners\n\n### [`RRTConnect`](https://ompl.kavrakilab.org/classompl_1_1geometric_1_1RRTConnect.html#gRRTC)\n\n##### Description\nWe grow two random search trees from the start and the goal configurations toward randomly sampled target points in the free space, until the two trees connect. \n\n##### Planner hyperparameters\nWe tune the following parameters: \n- _range_ $\\in [0.01, 5.00]$ parameter, which limits how much to extend the trees at each step; and\n- a _weight_ vector $\\in \\mathbb{R}^{50}$ with non-negative entries summing to $1$, which controls the sampling of target points using the experience-based sampling scheme adapted from [here](https://ieeexplore.ieee.org/abstract/document/9832486).\n\n### [`LBKPIECE1`](https://ompl.kavrakilab.org/classompl_1_1geometric_1_1LBKPIECE1.html#gLBKPIECE1)\n\n##### Description\nTwo random search trees are grown from the start and the goal configurations, but controls the exploration of the configuration space using grid-based projections. \n\n##### Planner hyperparemeters\nWe tune the following parameters: \n- _range_ $\\in [0.01, 5.00]$ which determines ho wmuch to extend the trees at each step; \n- _border_fraction_ $\\in [0.001, 1]$ which determins how much to focus exploration on unexplored cells; \n- _min_valid_path_fraction_ $\\in [0.001, 1]$ which determins the threshold for which partially valid extensions are allowed; and\n- a _projection_ vector $[0, 1]^{2 \\times d} \\subset \\mathbb{R}^{2 \\times d}$ which corresponds to the linear projection function used to induce the 2-dimensional exploration grid, where $d$ is the robot's number of degrees of freedom. \n\n####\n\n## Citing\n\nTBD\n\n## License\n\n`opof-sbmp` is licensed under the [BSD-3 license](https://github.com/opoframework/opof-sbmp/blob/master/LICENSE.md).\n\n`opof-sbmp` includes a copy of the following libraries as dependencies. These copies are protected and distributed according to the corresponding original license.\n- [Boost](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/boost) ([homepage](https://github.com/boostorg/boost)): [Boost Software License](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/boost/LICENSE)\n- [Eigen](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/Eigen) ([homepage](https://github.com/bolderflight/eigen)): [MPL2](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/Eigen/LICENSE)\n- [OMPL](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/ompl) ([homepage](https://github.com/ompl/ompl)): [BSD-3](https://github.com/opoframework/opof-sbmp/tree/master/ompl_core/ompl/LICENSE)\n\n`opof-sbmp` is maintained by the [Kavraki Lab](https://www.kavrakilab.org/) at Rice University, funded in part by NSF RI 2008720 and Rice University funds.\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "OPOF domains for sampling-based robot motion planning",
"version": "0.2.0",
"split_keywords": [
"opof",
"optimization",
"machine learning",
"reinforcement learning",
"planning",
"motion planning",
"robotics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86872589b846d07ba650ba45c9962986be241b52ff124a9bdf18fa9d6780bf65",
"md5": "b31441be5670206dc8b0a77af88979f9",
"sha256": "a83f4550babac5771980a7bbbf0ae2c0ef5021cca7dd10ccf79cb5b15b97b8c1"
},
"downloads": -1,
"filename": "opof_sbmp-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "b31441be5670206dc8b0a77af88979f9",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 56739969,
"upload_time": "2023-03-12T21:53:32",
"upload_time_iso_8601": "2023-03-12T21:53:32.754988Z",
"url": "https://files.pythonhosted.org/packages/86/87/2589b846d07ba650ba45c9962986be241b52ff124a9bdf18fa9d6780bf65/opof_sbmp-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a394a75e22625ccb0fed1d99ab2c2bfa9668a6958f6cad3f81247f0b7ee61745",
"md5": "3e05c1deb63a20a833b0599031a30435",
"sha256": "8b4f438cfc0e032802a277f3ecb70414edbc91d3d5697e5b326c68ee3ec8b600"
},
"downloads": -1,
"filename": "opof_sbmp-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "3e05c1deb63a20a833b0599031a30435",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 56739966,
"upload_time": "2023-03-12T21:54:15",
"upload_time_iso_8601": "2023-03-12T21:54:15.129254Z",
"url": "https://files.pythonhosted.org/packages/a3/94/a75e22625ccb0fed1d99ab2c2bfa9668a6958f6cad3f81247f0b7ee61745/opof_sbmp-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "632d4a2502266b37bca05d84a9d99a71f76412b04cd53aa7691b6de4584e82b6",
"md5": "9dead7e789994e07d3c97ef801684fb6",
"sha256": "3b4ec83c0eb795e9c14d2aa24cc6605cd2660cc444c9f59d13a22812354a7d2f"
},
"downloads": -1,
"filename": "opof_sbmp-0.2.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "9dead7e789994e07d3c97ef801684fb6",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 56739969,
"upload_time": "2023-03-12T21:54:58",
"upload_time_iso_8601": "2023-03-12T21:54:58.054129Z",
"url": "https://files.pythonhosted.org/packages/63/2d/4a2502266b37bca05d84a9d99a71f76412b04cd53aa7691b6de4584e82b6/opof_sbmp-0.2.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-12 21:53:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "opoframework",
"github_project": "opof-sbmp",
"lcname": "opof-sbmp"
}
JSON
