# icub-models
Repository containing URDF and SDF models of iCub humanoid robots.
The model contained in this repo are licensed under the [Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0) ](https://creativecommons.org/licenses/by-sa/4.0/).
## Installation
### conda (recommended)
You can easily install the `icub-models` and the C++ and Python helper libraries via [`conda-forge`](https://conda-forge.org) using the following command
~~~
conda install -c conda-forge icub-models
~~~
If you are not familiar with conda or conda-forge, you can read an introduction document in [conda-forge overview](https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#conda-forge-overview).
### robotology-superbuild (advanced)
If you use apt to install your dependencies or if you are install `icub-models` for use as part of [iCub humanoid robot software installation](https://icub-tech-iit.github.io/documentation/sw_installation/), you may want to install icub-models through the [robotology-superbuild](https://github.com/robotology/robotology-superbuild), an easy way to download, compile and install the robotology software on multiple operating systems, using the [CMake](https://www.cmake.org) build system and its extension [YCM](http://robotology.github.io/ycm). `icub-models` is always installed by `robotology-superbuild`.
### Build from source (advanced)
If you want to build icub-models directly from source of from the repo, you can check the documentation in [`build-from-source.md`](doc/build-from-source.md).
## Model Details
The models contained in `icub-models` are listed in the following table. Most models are identified by a name like `iCub<Something><Number>`, that we refer as `YARP_ROBOT_NAME`. Historically, on iCub robot setups, the `YARP_ROBOT_NAME` env variable identified the specific robot to use.
| `YARP_ROBOT_NAME` | `package:/`-URI | Notes |
|:--------------------:|:------------:|:-------------------------------:|
| `iCubErzelli02` | `package://iCub/robots/iCubErzelli02/model.urdf` | v2.5.5 |
| `iCubGazeboV2_5` | `package://iCub/robots/iCubGazeboV2_5/model.urdf` | v2.5.5, joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |
| `iCubGazeboV2_5_visuomanip` | `package://iCub/robots/iCubGazeboV2_5/model.urdf` | v2.5.5 with hands and eyes, base_link fixed to the ground and legs disabled. |
| `iCubGazeboV2_5_KIT_007`| `package://iCub/robots/iCubGazeboV2_5_KIT_007/model.urdf` | v2.5 + [KIT_007](https://icub-tech-iit.github.io/documentation/upgrade_kits/ankle_for_stairs/support/) with backpack, joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |
| `iCubGazeboV2_6` | `package://iCub/robots/iCubGazeboV2_6/model.urdf` | v2.6 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |
| `iCubGazeboV2_7` | `package://iCub/robots/iCubGazeboV2_7/model.urdf` | v2.7 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |
| `iCubGazeboV3` | `package://iCub/robots/iCubGazeboV3/model.urdf` | v3 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |
| `iCubGazeboV3_visuomanip` | `package://iCub/robots/iCubGazeboV3_visuomanip/model.urdf` | v3 with hands and eyes |
| `iCubGenova02` | `package://iCub/robots/iCubGenova02/model.urdf` | v2.5.5 + [KIT_007](https://icub-tech-iit.github.io/documentation/upgrade_kits/ankle_for_stairs/support/) with backpack |
| `iCubGenova03` | `package://iCub/robots/iCubGenova03/model.urdf` | v2 with legs v1 and feet v2.5 |
| `iCubGenova11` | `package://iCub/robots/iCubGenova11/model.urdf` | v2.7 |
| `iCubLisboa01` | `package://iCub/robots/iCubLisboa01/model.urdf` | v1 with head v2 |
| `iCubNancy01` | `package://iCub/robots/iCubNancy01/model.urdf` | v2.5 with arms v1 and head v2 |
| `iCubWaterloo11` | `package://iCub/robots/iCubWaterloo11/model.urdf` | v2.7 |
## Usage
### Use the models with ROS
Models contained in `icub-models` can be used using the `package:/`-URI listed in previous table. This URI always follow the structure `package://iCub/robots/<name>/model.urdf`, where `<name>` is `iCubErzelli02`, `iCubGazeboV2_5` or a similar identifier.
### Use the models with Classic Gazebo
Note that only the models that are known to work fine with the default physics engine settings of Classic Gazebo (the one that start with `iCubGazebo`)
are installed. If you want to make available in Gazebo all the models, enable the `ICUB_MODELS_INSTALL_ALL_GAZEBO_MODELS` CMake option.
To include the model in a Classic Gazebo world, use the following SDF:
~~~xml
<include>
<pose>0 0 0.5 0 -0.1 3.14</pose>
<uri>model://iCubGazeboV2_5</uri>
</include>
~~~
The `model:/` string is used to include the model, following the structure `model://<name>`, where `<name>` is `iCubGazeboV2_5`, `iCubGazeboV2_7` or a similar identifier. Note that you can also use the structure `model://iCub/robots/<name>`.
### Use the models from C++ helper library
In order to use these models in `c++` application you can exploit the `icub-models` library.
`icub-models` provides native `CMake` support which allows the library to be easily used in `CMake` projects.
**icub-models** exports a CMake target called `icub-models::icub-models` which can be imported using the `find_package` CMake command and used by calling `target_link_libraries` as in the following example:
```cmake
cmake_minimum_required(VERSION 3.5)
project(myproject)
find_package(icub-models REQUIRED)
add_executable(example example.cpp)
target_link_libraries(example icub-models::icub-models)
```
The `example.cpp` will contains
```cpp
#include <iCubModels/iCubModels.h>
#include <iostream>
int main()
{
std::cout << "Models have been installed in: " << iCubModels::getModelsPath() << std::endl;
std::cout << "Available robots: " << std::endl;
for (const auto& robot : iCubModels::getRobotNames())
{
std::cout << " - " << robot << ": " << iCubModels::getModelFile(robot) << std::endl;
}
return EXIT_SUCCESS;
}
```
***Note: The ABI and the API of the C++ helper library has breaking changes only at major releases of the `icub-models` package.***
### Use the models from C++ using YARP
To find the model in C++ using YARP, you just need to make sure that `YARP_ROBOT_NAME` environment variable is set, and search for the `model.urdf` file:
~~~
std::string modelAbsolutePath =yarp::os::ResourceFinder::getResourceFinderSingleton().findFileByName("model.urdf");
~~~
### Use the models from Python icub-models library
The following script can be used to locate the models
```python
import icub_models
print(f"Models have been installed in: {icub_models.get_models_path()}")
print(f"Available robots: {icub_models.get_robot_names()}")
for robot_name in icub_models.get_robot_names():
print(f"{robot_name}: {icub_models.get_model_file(robot_name)}")
```
### Use the models from Python using resolve-robotics-uri-py
First of all, make sure that you installed [`resolve-robotics-uri-py`](https://github.com/ami-iit/resolve-robotics-uri-py) python library. Then, you can find the `icub-models` models using `package:/` or `model:/` URIs, as you would use with Gazebo or ROS:
~~~
absolute_path = resolve_robotics_uri_py.resolve_robotics_uri("package://iCub/robots/iCubGazeboV2_7/model.urdf")
~~~
or
~~~
absolute_path = resolve_robotics_uri_py.resolve_robotics_uri("model://iCub/robots/iCubGazeboV2_7/model.urdf")
~~~
## FAQs
### Change the orientation of the root frame
The iCub robot `root frame` is defined as [`x-backward`][1], meaning that the x-axis points behind the robot. Nevertheless, in the robotics community, sometimes the root frame of a robot is defined as [`x-forward`][2]. As a consequence, to use the iCub models with software developed for the `x-forward` configuration (e.g. [IHMC-ORS][3]), might be necessary to quickly update the root frame orientation.
For this purpose, locate the joint `<joint name="base_fixed_joint" type="fixed">` in the `URDF` model and perform the following substitution in the `origin` section:
```
- <origin xyz="0 0 0" rpy="0 -0 0"/>
+ <origin xyz="0 0 0" rpy="0 -0 3.14159265358979323846"/>
```
[1]:http://wiki.icub.org/wiki/ICubForwardKinematics
[2]:http://www.ros.org/reps/rep-0103.html#axis-orientation
[3]:https://github.com/ihmcrobotics/ihmc-open-robotics-software
Raw data
{
"_id": null,
"home_page": "https://github.com/robotolgy/icub-models",
"name": "icub-models",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "robotics,gazebo,urdf,ros,icub,gazebo-models,gazebo-simulators",
"author": "Giulio Romualdi",
"author_email": "giulio.romualdi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a8/e6/dbb7a0738557bd6a81912a99b2a2d1a6114e977ecdd6400f36c9d62ab2b1/icub_models-2.5.0.tar.gz",
"platform": "any",
"description": "# icub-models\n\nRepository containing URDF and SDF models of iCub humanoid robots.\n\nThe model contained in this repo are licensed under the [Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0) ](https://creativecommons.org/licenses/by-sa/4.0/).\n\n## Installation\n\n### conda (recommended) \n\nYou can easily install the `icub-models` and the C++ and Python helper libraries via [`conda-forge`](https://conda-forge.org) using the following command\n~~~\nconda install -c conda-forge icub-models\n~~~\n\nIf you are not familiar with conda or conda-forge, you can read an introduction document in [conda-forge overview](https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#conda-forge-overview).\n\n### robotology-superbuild (advanced)\n\nIf you use apt to install your dependencies or if you are install `icub-models` for use as part of [iCub humanoid robot software installation](https://icub-tech-iit.github.io/documentation/sw_installation/), you may want to install icub-models through the [robotology-superbuild](https://github.com/robotology/robotology-superbuild), an easy way to download, compile and install the robotology software on multiple operating systems, using the [CMake](https://www.cmake.org) build system and its extension [YCM](http://robotology.github.io/ycm). `icub-models` is always installed by `robotology-superbuild`.\n\n### Build from source (advanced)\n\nIf you want to build icub-models directly from source of from the repo, you can check the documentation in [`build-from-source.md`](doc/build-from-source.md).\n\n## Model Details\n\nThe models contained in `icub-models` are listed in the following table. Most models are identified by a name like `iCub<Something><Number>`, that we refer as `YARP_ROBOT_NAME`. Historically, on iCub robot setups, the `YARP_ROBOT_NAME` env variable identified the specific robot to use.\n\n| `YARP_ROBOT_NAME` | `package:/`-URI | Notes |\n|:--------------------:|:------------:|:-------------------------------:|\n| `iCubErzelli02` | `package://iCub/robots/iCubErzelli02/model.urdf` | v2.5.5 |\n| `iCubGazeboV2_5` | `package://iCub/robots/iCubGazeboV2_5/model.urdf` | v2.5.5, joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |\n| `iCubGazeboV2_5_visuomanip` | `package://iCub/robots/iCubGazeboV2_5/model.urdf` | v2.5.5 with hands and eyes, base_link fixed to the ground and legs disabled. |\n| `iCubGazeboV2_5_KIT_007`| `package://iCub/robots/iCubGazeboV2_5_KIT_007/model.urdf` | v2.5 + [KIT_007](https://icub-tech-iit.github.io/documentation/upgrade_kits/ankle_for_stairs/support/) with backpack, joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |\n| `iCubGazeboV2_6` | `package://iCub/robots/iCubGazeboV2_6/model.urdf` | v2.6 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |\n| `iCubGazeboV2_7` | `package://iCub/robots/iCubGazeboV2_7/model.urdf` | v2.7 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |\n| `iCubGazeboV3` | `package://iCub/robots/iCubGazeboV3/model.urdf` | v3 with joint damping, and inertias of some links increased in a non realistic way to run smoothly in Gazebo Classic (ODE). |\n| `iCubGazeboV3_visuomanip` | `package://iCub/robots/iCubGazeboV3_visuomanip/model.urdf` | v3 with hands and eyes |\n| `iCubGenova02` | `package://iCub/robots/iCubGenova02/model.urdf` | v2.5.5 + [KIT_007](https://icub-tech-iit.github.io/documentation/upgrade_kits/ankle_for_stairs/support/) with backpack |\n| `iCubGenova03` | `package://iCub/robots/iCubGenova03/model.urdf` | v2 with legs v1 and feet v2.5 |\n| `iCubGenova11` | `package://iCub/robots/iCubGenova11/model.urdf` | v2.7 |\n| `iCubLisboa01` | `package://iCub/robots/iCubLisboa01/model.urdf` | v1 with head v2 |\n| `iCubNancy01` | `package://iCub/robots/iCubNancy01/model.urdf` | v2.5 with arms v1 and head v2 |\n| `iCubWaterloo11` | `package://iCub/robots/iCubWaterloo11/model.urdf` | v2.7 |\n\n\n## Usage\n\n### Use the models with ROS\n\nModels contained in `icub-models` can be used using the `package:/`-URI listed in previous table. This URI always follow the structure `package://iCub/robots/<name>/model.urdf`, where `<name>` is `iCubErzelli02`, `iCubGazeboV2_5` or a similar identifier.\n\n### Use the models with Classic Gazebo\n\nNote that only the models that are known to work fine with the default physics engine settings of Classic Gazebo (the one that start with `iCubGazebo`)\nare installed. If you want to make available in Gazebo all the models, enable the `ICUB_MODELS_INSTALL_ALL_GAZEBO_MODELS` CMake option.\n\nTo include the model in a Classic Gazebo world, use the following SDF:\n\n~~~xml\n<include>\n <pose>0 0 0.5 0 -0.1 3.14</pose>\n <uri>model://iCubGazeboV2_5</uri>\n</include>\n~~~\n\nThe `model:/` string is used to include the model, following the structure `model://<name>`, where `<name>` is `iCubGazeboV2_5`, `iCubGazeboV2_7` or a similar identifier. Note that you can also use the structure `model://iCub/robots/<name>`.\n\n### Use the models from C++ helper library\n\nIn order to use these models in `c++` application you can exploit the `icub-models` library.\n`icub-models` provides native `CMake` support which allows the library to be easily used in `CMake` projects.\n**icub-models** exports a CMake target called `icub-models::icub-models` which can be imported using the `find_package` CMake command and used by calling `target_link_libraries` as in the following example:\n```cmake\ncmake_minimum_required(VERSION 3.5)\nproject(myproject)\nfind_package(icub-models REQUIRED)\nadd_executable(example example.cpp)\ntarget_link_libraries(example icub-models::icub-models)\n```\n\nThe `example.cpp` will contains\n```cpp\n#include <iCubModels/iCubModels.h>\n#include <iostream>\n\nint main()\n{\n std::cout << \"Models have been installed in: \" << iCubModels::getModelsPath() << std::endl;\n\n std::cout << \"Available robots: \" << std::endl;\n for (const auto& robot : iCubModels::getRobotNames())\n {\n std::cout << \" - \" << robot << \": \" << iCubModels::getModelFile(robot) << std::endl;\n }\n\n return EXIT_SUCCESS;\n}\n```\n\n***Note: The ABI and the API of the C++ helper library has breaking changes only at major releases of the `icub-models` package.***\n\n### Use the models from C++ using YARP\n\nTo find the model in C++ using YARP, you just need to make sure that `YARP_ROBOT_NAME` environment variable is set, and search for the `model.urdf` file:\n\n~~~\nstd::string modelAbsolutePath =yarp::os::ResourceFinder::getResourceFinderSingleton().findFileByName(\"model.urdf\");\n~~~\n\n### Use the models from Python icub-models library\n\nThe following script can be used to locate the models\n```python\nimport icub_models\n\nprint(f\"Models have been installed in: {icub_models.get_models_path()}\")\n\nprint(f\"Available robots: {icub_models.get_robot_names()}\")\n\nfor robot_name in icub_models.get_robot_names():\n print(f\"{robot_name}: {icub_models.get_model_file(robot_name)}\")\n```\n\n### Use the models from Python using resolve-robotics-uri-py\n\nFirst of all, make sure that you installed [`resolve-robotics-uri-py`](https://github.com/ami-iit/resolve-robotics-uri-py) python library. Then, you can find the `icub-models` models using `package:/` or `model:/` URIs, as you would use with Gazebo or ROS:\n\n~~~\nabsolute_path = resolve_robotics_uri_py.resolve_robotics_uri(\"package://iCub/robots/iCubGazeboV2_7/model.urdf\")\n~~~\n\nor\n\n~~~\nabsolute_path = resolve_robotics_uri_py.resolve_robotics_uri(\"model://iCub/robots/iCubGazeboV2_7/model.urdf\")\n~~~\n \n\n## FAQs\n\n### Change the orientation of the root frame\nThe iCub robot `root frame` is defined as [`x-backward`][1], meaning that the x-axis points behind the robot. Nevertheless, in the robotics community, sometimes the root frame of a robot is defined as [`x-forward`][2]. As a consequence, to use the iCub models with software developed for the `x-forward` configuration (e.g. [IHMC-ORS][3]), might be necessary to quickly update the root frame orientation. \nFor this purpose, locate the joint `<joint name=\"base_fixed_joint\" type=\"fixed\">` in the `URDF` model and perform the following substitution in the `origin` section:\n\n```\n- <origin xyz=\"0 0 0\" rpy=\"0 -0 0\"/>\n+ <origin xyz=\"0 0 0\" rpy=\"0 -0 3.14159265358979323846\"/>\n```\n\n[1]:http://wiki.icub.org/wiki/ICubForwardKinematics\n[2]:http://www.ros.org/reps/rep-0103.html#axis-orientation\n[3]:https://github.com/ihmcrobotics/ihmc-open-robotics-software\n",
"bugtrack_url": null,
"license": "Creative Commons Attribution Share Alike 4.0 International",
"summary": "Official URDF and SDF models of the iCub humanoid robot.",
"version": "2.5.0",
"project_urls": {
"Changelog": "https://github.com/robotology/icub-models/releases",
"Homepage": "https://github.com/robotolgy/icub-models",
"Source": "https://github.com/robotology/icub-models",
"Tracker": "https://github.com/robotology/icub-models/issues"
},
"split_keywords": [
"robotics",
"gazebo",
"urdf",
"ros",
"icub",
"gazebo-models",
"gazebo-simulators"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4b1d6380bb14052479953dc7b30cdc69e74a7cfcdb2ae2d736784ed8dc4aed02",
"md5": "a6570aea89b5b573b5a14c1bdc11b655",
"sha256": "0c739686adc230130934d0f3794c81abbc364975f0feebc87798072c4083ca3c"
},
"downloads": -1,
"filename": "icub_models-2.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6570aea89b5b573b5a14c1bdc11b655",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19648901,
"upload_time": "2024-02-06T14:33:08",
"upload_time_iso_8601": "2024-02-06T14:33:08.478572Z",
"url": "https://files.pythonhosted.org/packages/4b/1d/6380bb14052479953dc7b30cdc69e74a7cfcdb2ae2d736784ed8dc4aed02/icub_models-2.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8e6dbb7a0738557bd6a81912a99b2a2d1a6114e977ecdd6400f36c9d62ab2b1",
"md5": "20c2574e43c5324fe83ab09f6dfdd6fb",
"sha256": "69841be4bdb58f32225dd7634d3842d0ca00af532e873d4bd8f7945efbc503d8"
},
"downloads": -1,
"filename": "icub_models-2.5.0.tar.gz",
"has_sig": false,
"md5_digest": "20c2574e43c5324fe83ab09f6dfdd6fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22942993,
"upload_time": "2024-02-06T14:33:12",
"upload_time_iso_8601": "2024-02-06T14:33:12.046834Z",
"url": "https://files.pythonhosted.org/packages/a8/e6/dbb7a0738557bd6a81912a99b2a2d1a6114e977ecdd6400f36c9d62ab2b1/icub_models-2.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 14:33:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robotolgy",
"github_project": "icub-models",
"github_not_found": true,
"lcname": "icub-models"
}
JSON
