# Blend My Bot
<div align="center">
**Import your robot in Blender and create a nice render of it!**
<https://github.com/ami-iit/blend-my-bot/assets/29798643/c224cd56-1d90-42dd-aec5-960a13690ce7>
</div>
## 🐍 Requirements
- [`python3`](<https://wiki.python.org/moin/BeginnersGuide>)
- [`Blender 4`](<https://www.blender.org/download/lts/3-6/>)
- [`iDynTree`](<https://github.com/robotology/idyntree>)
- [`numpy`](<https://numpy.org/>)
- [`bpy 4`](<https://pypi.org/project/bpy/>)
> [!NOTE]
> You should use a Python version that matches the one supported by the Blender version.
> For example, Blender 4 supports Python 3.10
> [!NOTE]
> This library does not define the rig of the robot. For this, you can use a library such as [`blender-robotics-utils`](https://github.com/robotology/blender-robotics-utils).
## 💾 Installation
Create a conda environment and install the dependencies:
```bash
conda create -n blender_env python=3.10
conda activate blender_env
```
Create a backup of the python folder in the blender folder:
```bash
mv blender_folder/version/python blender_folder/version/python_backup
```
Run the command below in the blender python folder to create a symbolic link to the conda environment in the blender python folder:
```bash
sudo ln -s ~/mambaforge/envs/blender_env blender_folder/version/python
```
From the root of the repository install the package:
```bash
pip install blend-my-bot
```
If you want to run the scripts from `Visual Studio Code`, you need to install the `vscode python` extension and set the python interpreter to the already created conda environment.
You need an additional vscode extension: `Blender Development` which can be found [here](https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development).
Once installed, you can run Blender by typing `Ctrl+Shift+P` and then `Blender: Start`. It will ask you to select the blender executable: select the one in the folder where you extracted the blender archive (or the installed version if you installed it). Once Blender is running, you can run the script by typing `Ctrl+Shift+P` and then `Blender: Run Script`.
You can add objects, lights, and cameras as well as play with render parameters directly in Blender.
If you prefer, you can save the Blender project. Everything will be there, including the robot and its motion, so that it does not need to run your script again.
Note that you could also write a script directly in the `Scripting` tab of Blender and run it from there.
For possible issues when running the script see the [Troubleshooting](#troubleshooting) section.
## 🚀 Usage
```python
# import the library
from blend_my_bot import ModelImporter
# import the blender python API
import bpy
# ModelImporter needs 3 arguments:
# - the name you want to give to your robot
# - the path to the urdf file
# - the list of the joints you want to move in the animation
urdf_path = "path/to/urdf"
robot_name = "my_robot"
joints_list = ["joint1", "joint2", "joint3", "etc"]
# build the blender robot model
model = ModelImporter.build_model(robot_name, urdf_path, joints_list)
# you need to set the frame rate and the number of frames of the animation
# length of the animation in seconds
bpy.context.scene.render.fps_base = time_length
# number of frames
bpy.context.scene.render.fps = number_of_frames
# when the animation starts
bpy.context.scene.frame_start = 0
# when the animation ends
bpy.context.scene.frame_end = number_of_frames
# in Blender the effective frame rate is fps / fps_base
# you can now move the base and the joints of the robot
for k in range(number_of_frames):
# jet the joint trajectory at time k
s = joint_trajectory[k]
# get the base pose described by a 4x4 homogeneous matrix at time k
w_H_b = base_trajectory[k]
# update the robot model
model.update(w_H_b, s)
# set the frame
bpy.context.scene.frame_set(k)
```
Have a look at the `examples` folder for more examples.
In the `examples/jumping` folder you can find a script that generates a jumping animation of the `iCub` robot. Here the meshes are in a gray, `stl` format.
Having the meshes in an `obj` format, instead, will give a nicer and more colorful render! See the Readme of the following repository, for example!
[Whole-Body Trajectory Optimization for Robot Multimodal Locomotion](<https://github.com/ami-iit/paper_lerario_2022_humanoids_planning-multimodal-locomotion>)
## 🦿 Troubleshooting
#### FileNotFoundError when running the script
If you install a new package in the conda environment but it is not working as you expect when you run the script, try to activate it in a terminal **before** and then open `Visual Studio Code` from the terminal:
```bash
conda activate blender_env
code .
```
For example, when using [`resolve_robotics_uri_py`](https://github.com/ami-iit/resolve-robotics-uri-py) an error like the following one appears:
```
FileNotFoundError: resolve-robotics-uri-py: No file corresponding to uri "package://iCub/robots/iCubGazeboV2_7/model.urdf" found
```
This is due to the fact that environmental variables are not sourced. Activating the conda environment before opening `vscode` solves this issue!
#### Crush when running the script
If Blender crashes when running the script from `Visual Studio Code`, try to run the script from the `Scripting` tab of Blender.
## 🦸♂️ Contributing
`blend-my-bot` is an open-source project. Contributions are very welcome!
Open an issue with your feature request or if you spot a bug. Then, you can also proceed with a Pull-requests! 🚀
## 📝 Tips
Some tips to speed up your Cycle render:
<https://www.youtube.com/watch?v=FNiobzflmpA>
Feel free to add your own tips here!
Raw data
{
"_id": null,
"home_page": null,
"name": "blend-my-bot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "robotics, blender, animation",
"author": "\"Giuseppe L'Erario\"",
"author_email": "gl.giuseppelerario@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ef/99/7a877b4d1e36d2cf272c43b1ff05ae41ebed076e24454fa547fca618b32a/blend_my_bot-1.1.0.tar.gz",
"platform": null,
"description": "# Blend My Bot\n\n<div align=\"center\">\n\n**Import your robot in Blender and create a nice render of it!**\n\n<https://github.com/ami-iit/blend-my-bot/assets/29798643/c224cd56-1d90-42dd-aec5-960a13690ce7>\n\n</div>\n\n## \ud83d\udc0d Requirements\n\n- [`python3`](<https://wiki.python.org/moin/BeginnersGuide>)\n- [`Blender 4`](<https://www.blender.org/download/lts/3-6/>)\n- [`iDynTree`](<https://github.com/robotology/idyntree>)\n- [`numpy`](<https://numpy.org/>)\n- [`bpy 4`](<https://pypi.org/project/bpy/>)\n\n> [!NOTE]\n> You should use a Python version that matches the one supported by the Blender version.\n> For example, Blender 4 supports Python 3.10\n\n> [!NOTE]\n> This library does not define the rig of the robot. For this, you can use a library such as [`blender-robotics-utils`](https://github.com/robotology/blender-robotics-utils).\n\n## \ud83d\udcbe Installation\n\nCreate a conda environment and install the dependencies:\n\n```bash\nconda create -n blender_env python=3.10\nconda activate blender_env\n```\n\nCreate a backup of the python folder in the blender folder:\n\n```bash\nmv blender_folder/version/python blender_folder/version/python_backup\n```\n\nRun the command below in the blender python folder to create a symbolic link to the conda environment in the blender python folder:\n\n```bash\nsudo ln -s ~/mambaforge/envs/blender_env blender_folder/version/python\n```\n\nFrom the root of the repository install the package:\n\n```bash\npip install blend-my-bot\n```\n\nIf you want to run the scripts from `Visual Studio Code`, you need to install the `vscode python` extension and set the python interpreter to the already created conda environment.\n\nYou need an additional vscode extension: `Blender Development` which can be found [here](https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development).\n\nOnce installed, you can run Blender by typing `Ctrl+Shift+P` and then `Blender: Start`. It will ask you to select the blender executable: select the one in the folder where you extracted the blender archive (or the installed version if you installed it). Once Blender is running, you can run the script by typing `Ctrl+Shift+P` and then `Blender: Run Script`.\n\nYou can add objects, lights, and cameras as well as play with render parameters directly in Blender.\nIf you prefer, you can save the Blender project. Everything will be there, including the robot and its motion, so that it does not need to run your script again.\n\nNote that you could also write a script directly in the `Scripting` tab of Blender and run it from there.\n\nFor possible issues when running the script see the [Troubleshooting](#troubleshooting) section.\n\n## \ud83d\ude80 Usage\n\n```python\n# import the library\nfrom blend_my_bot import ModelImporter\n# import the blender python API\nimport bpy\n\n# ModelImporter needs 3 arguments:\n# - the name you want to give to your robot\n# - the path to the urdf file\n# - the list of the joints you want to move in the animation\n\nurdf_path = \"path/to/urdf\"\nrobot_name = \"my_robot\"\njoints_list = [\"joint1\", \"joint2\", \"joint3\", \"etc\"]\n\n# build the blender robot model\nmodel = ModelImporter.build_model(robot_name, urdf_path, joints_list)\n\n# you need to set the frame rate and the number of frames of the animation\n# length of the animation in seconds\nbpy.context.scene.render.fps_base = time_length\n# number of frames\nbpy.context.scene.render.fps = number_of_frames\n# when the animation starts\nbpy.context.scene.frame_start = 0\n# when the animation ends\nbpy.context.scene.frame_end = number_of_frames\n\n# in Blender the effective frame rate is fps / fps_base\n\n# you can now move the base and the joints of the robot\nfor k in range(number_of_frames):\n # jet the joint trajectory at time k\n s = joint_trajectory[k]\n # get the base pose described by a 4x4 homogeneous matrix at time k\n w_H_b = base_trajectory[k]\n # update the robot model\n model.update(w_H_b, s)\n # set the frame\n bpy.context.scene.frame_set(k)\n```\n\nHave a look at the `examples` folder for more examples.\n\nIn the `examples/jumping` folder you can find a script that generates a jumping animation of the `iCub` robot. Here the meshes are in a gray, `stl` format.\n\nHaving the meshes in an `obj` format, instead, will give a nicer and more colorful render! See the Readme of the following repository, for example!\n\n[Whole-Body Trajectory Optimization for Robot Multimodal Locomotion](<https://github.com/ami-iit/paper_lerario_2022_humanoids_planning-multimodal-locomotion>)\n\n## \ud83e\uddbf Troubleshooting\n\n#### FileNotFoundError when running the script\n\nIf you install a new package in the conda environment but it is not working as you expect when you run the script, try to activate it in a terminal **before** and then open `Visual Studio Code` from the terminal:\n\n```bash\nconda activate blender_env\ncode .\n```\n\nFor example, when using [`resolve_robotics_uri_py`](https://github.com/ami-iit/resolve-robotics-uri-py) an error like the following one appears:\n\n```\nFileNotFoundError: resolve-robotics-uri-py: No file corresponding to uri \"package://iCub/robots/iCubGazeboV2_7/model.urdf\" found\n```\n\nThis is due to the fact that environmental variables are not sourced. Activating the conda environment before opening `vscode` solves this issue!\n\n#### Crush when running the script\n\nIf Blender crashes when running the script from `Visual Studio Code`, try to run the script from the `Scripting` tab of Blender.\n\n## \ud83e\uddb8\u200d\u2642\ufe0f Contributing\n\n`blend-my-bot` is an open-source project. Contributions are very welcome!\n\nOpen an issue with your feature request or if you spot a bug. Then, you can also proceed with a Pull-requests! \ud83d\ude80\n\n## \ud83d\udcdd Tips\n\nSome tips to speed up your Cycle render:\n<https://www.youtube.com/watch?v=FNiobzflmpA>\n\nFeel free to add your own tips here!\n",
"bugtrack_url": null,
"license": null,
"summary": "A package to import URDF files into Blender",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"robotics",
" blender",
" animation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b42125c5dd2c72d6d7726b7829d0c35a81e5af4da61c201a3ed145adf01bbd0",
"md5": "8d4872227529ca1094c645bf54672c48",
"sha256": "4f31867199ec4bf12c59c9391658753d51e46fde69d77adb108667377062dafb"
},
"downloads": -1,
"filename": "blend_my_bot-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d4872227529ca1094c645bf54672c48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7445,
"upload_time": "2024-07-24T13:54:12",
"upload_time_iso_8601": "2024-07-24T13:54:12.752332Z",
"url": "https://files.pythonhosted.org/packages/7b/42/125c5dd2c72d6d7726b7829d0c35a81e5af4da61c201a3ed145adf01bbd0/blend_my_bot-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ef997a877b4d1e36d2cf272c43b1ff05ae41ebed076e24454fa547fca618b32a",
"md5": "968e70a81352e87c6d6ae47c63bb30b2",
"sha256": "fe967a2318540f871db3cac7877bbab841450bcd19e8d47cf5c63328ab23e754"
},
"downloads": -1,
"filename": "blend_my_bot-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "968e70a81352e87c6d6ae47c63bb30b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 71737,
"upload_time": "2024-07-24T13:54:13",
"upload_time_iso_8601": "2024-07-24T13:54:13.925666Z",
"url": "https://files.pythonhosted.org/packages/ef/99/7a877b4d1e36d2cf272c43b1ff05ae41ebed076e24454fa547fca618b32a/blend_my_bot-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-24 13:54:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "blend-my-bot"
}
JSON