Skip to content

Commit 7f5f31e

Browse files
traversarotraversaro
authored
Update
1 parent be7e2ed commit 7f5f31e

File tree

2 files changed

+72
-56
lines changed

2 files changed

+72
-56
lines changed

‎README.md

Lines changed: 54 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -23,68 +23,53 @@ If you use apt to install your dependencies or if you are install `icub-models`
2323

2424
If you want to build icub-models directly from source of from the repo, you can check the documentation in [`doc/build-from-source.md`](doc/build-from-source.md).
2525

26-
## Usage
27-
28-
The model in the repo can be used either directly from the repo, or by installing them.
26+
## Model Details
2927

30-
While the files can be used directly by pointing your software to their location, they are
31-
tipically used by software that uses either YARP, ROS or Gazebo. For this reason, the models
32-
are installed as part of the `iCub` ROS package ([instructions](https://github.com/gerkey/ros1_external_use#installing-for-use-by-tools-like-roslaunch)) and following the [YARP guidelines on installing configuration files](http://www.yarp.it/yarp_data_dirs.html).
28+
The model contained in `icub-models` are listed in the following table. Most model is identified by a name like `iCub<Something><Number>`, that we refer as `YARP_ROBOT_NAME` as historically on iCub robot setups the robot to use was identified by setting the `YARP_ROBOT_NAME` env variable to that name.
3329

34-
To make sure that this models are found by the software even when they are not installed in
35-
system directories, tipically the [`YARP_DATA_DIRS`](http://www.yarp.it/yarp_data_dirs.html) for [YARP](https://github.com/robotology/yarp),
36-
[`ROS_PACKAGE_PATH`](http://wiki.ros.org/ROS/EnvironmentVariables#ROS_PACKAGE_PATH) for [ROS1](https://www.ros.org/), [`AMENT_PREFIX_PATH`](http://design.ros2.org/articles/ament.html) for [ROS2](https://index.ros.org/doc/ros2/) and the [`GAZEBO_MODEL_PATH`](http://gazebosim.org/tutorials?tut=components#EnvironmentVariables) for [SDFormat](http://sdformat.org/) enviromental variables are modified appropriatly.
30+
| `YARP_ROBOT_NAME` | `package:/`-URI | Notes |
31+
|:--------------------:|:------------:|:-------------------------------:|
32+
| `iCubErzelli02` | `package://iCub/robots/iCubErzelli02/model.urdf` | v2.5.5 |
33+
| `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). |
34+
| `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). |
35+
| `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). |
36+
| `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). |
37+
| `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). |
38+
| `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 |
39+
| `iCubGenova03` | `package://iCub/robots/iCubGenova03/model.urdf` | v2 with legs v1 and feet v2.5 |
40+
| `iCubLisboa01` | `package://iCub/robots/iCubLisboa01/model.urdf` | v1 with head v2 |
41+
| `iCubNancy01` | `package://iCub/robots/iCubNancy01/model.urdf` | v2.5 with arms v1 and head v2 |
3742

3843

39-
### From the source repo
40-
41-
In the case models are used from the repo, the first step is configure it with the following commands:
44+
## Usage
4245

43-
```sh
44-
mkdir build
45-
cd build
46-
cmake ..
47-
```
46+
### Use the models with ROS
4847

49-
If `<icub-models>` is the location of the repo, some folders need to be appended to the mentioned env variables. On *nix system, this can be achived by adding to the `.bashrc` or equivalent file the following three lines:
48+
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.
5049

51-
```sh
52-
export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<icub-models>/build/iCub
53-
export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<icub-models>/build
54-
```
50+
### Use the models with Classic Gazebo
5551

56-
### By installing the models
52+
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`)
53+
are installed. If you want to make available in Gazebo all the models, enable the `ICUB_MODELS_INSTALL_ALL_GAZEBO_MODELS` CMake option.
5754

58-
To install the models instead, execute:
55+
To include the model in a Classic Gazebo world, include it with the following SDF :
5956

60-
```sh
61-
mkdir build
62-
cd build
63-
cmake -DCMAKE_INSTALL_PREFIX=<prefix> ..
64-
cmake --build . --target install
65-
```
57+
~~~xml
58+
<include>
59+
<pose>0 0 0.5 0 -0.1 3.14</pose>
60+
<uri>model://iCubGazeboV2_5</uri>
61+
</include>
62+
~~~
6663

67-
Once the models are installed into a given prefix, edit the env variables as follows:
68-
69-
```sh
70-
export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<prefix>/share/iCub
71-
export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<prefix>/share
72-
export AMENT_PREFIX_PATH=${AMENT_PREFIX_PATH}:<prefix>
73-
```
74-
### Use the models with Gazebo
75-
In order to use these models in Gazebo, set up the simulation environment following the instructions provided in the [icub-gazebo](https://github.com/robotology/icub-gazebo) repository, and add the following line to your ``.bashrc``:
76-
```
77-
export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:<prefix>/share/iCub/robots:<prefix>/share
78-
```
79-
Note that only the models that are known to work fine with the default physics engine settings of Gazebo (`iCubGazeboV2_5` and `iCubGazeboV2_5_plus`)
80-
are installed. If you want to make available in Gazebo all the models, enable the `ICUB_MODELS_INSTALL_ALL_GAZEBO_MODELS` CMake option.
64+
the `model:/` used to include the model follow 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>`.
8165

8266
### Use the models from C++ helper library
67+
8368
In order to use these models in `c++` application you can exploit the `icub-models` library.
8469
`icub-models` provides native `CMake` support which allows the library to be easily used in `CMake` projects.
8570
**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:
8671
```cmake
87-
cmake_minimum_required(VERSION 3.0)
72+
cmake_minimum_required(VERSION 3.5)
8873
project(myproject)
8974
find_package(icub-models REQUIRED)
9075
add_executable(example example.cpp)
@@ -112,17 +97,13 @@ int main()
11297

11398
***Note: The ABI and the API of the C++ helper library has breaking changes only at major releases of the `icub-models` package.***
11499

115-
### Use the models from Python helper library
116-
In order to use these models in `python` application you can exploit the `icub-models` module.
117-
`icub-models` provides a `python` package to called `icub_models`. You can install it via `cmake`
118-
```
119-
cmake -DCMAKE_INSTALL_PREFIX=<path/where/you/want/to/install> \
120-
-DCMAKE_BUILD_TYPE=Release \
121-
-DICUB_MODELS_USES_PYTHON:BOOL=ON ..
122-
cmake --build . --config Release --target install
123-
```
100+
### Use the models from C++ using YARP
101+
102+
To find the model using YARP
103+
104+
### Use the models from Python icub-models library
124105

125-
Then the following script can be used to locate the models
106+
The following script can be used to locate the models
126107
```python
127108
import icub_models
128109

@@ -134,7 +115,24 @@ for robot_name in icub_models.get_robot_names():
134115
print(f"{robot_name}: {icub_models.get_model_file(robot_name)}")
135116
```
136117

137-
## Change the orientation of the root frame
118+
### Use the models from Python using resolve-robotics-uri-py
119+
120+
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:
121+
122+
~~~
123+
absolute_path = resolve_robotics_uri_py.resolve_robotics_uri("package://iCub/robots/iCubGazeboV2_7/model.urdf")
124+
~~~
125+
126+
or
127+
128+
~~~
129+
absolute_path = resolve_robotics_uri_py.resolve_robotics_uri("model://iCub/robots/iCubGazeboV2_7/model.urdf")
130+
~~~
131+
132+
133+
## FAQs
134+
135+
### Change the orientation of the root frame
138136
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.
139137
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:
140138

‎build-from-source.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Build icub-models from source
2+
3+
To install the icub-models, execute:
4+
5+
```sh
6+
mkdir build
7+
cd build
8+
cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release -DICUB_MODELS_USES_PYTHON:BOOL=ON ..
9+
cmake --build . --config Release --target install
10+
```
11+
12+
Once the models are installed into a given prefix, edit the env variables as follows to ensure that they can be found.
13+
14+
```sh
15+
export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<prefix>/share/iCub
16+
export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<prefix>/share
17+
export AMENT_PREFIX_PATH=${AMENT_PREFIX_PATH}:<prefix>
18+
```

0 commit comments

Comments
 (0)