Merge branch 'master' into devel

robotology · Jan 9, 2024 · d90fe58 · d90fe58
2 parents b2391b9 + 453d9ed
commit d90fe58
Show file tree

Hide file tree

Showing 5 changed files with 110 additions and 55 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,12 +5,25 @@ The format of this document is based on [Keep a Changelog](https://keepachangelo
 
 ## [Unreleased]
 
+# [2.4.1] - 2023-10-30
+
+### Fixed
+* Fixed version number in CMakeLists.txt and package.xml (https://github.com/robotology/icub-models/pull/222).
+
+# [2.4.0] - 2023-10-30
+
 ### Changed
 * Enable publishing of robot joints in ROS 2 via `controlBoard_nws_ros2` for `iCubGazeboV2_5_visuomanip` (https://github.com/robotology/icub-models/pull/211).
 * CMake: Permit to explictly specify Python installation directory by setting the `ICUB_MODELS_PYTHON_INSTALL_DIR` CMake variable (https://github.com/robotology/icub-models/pull/218).
+* Delete unused files (https://github.com/robotology/icub-models-generator/pull/236).
+* Remove iCubGenova04_plus model  and rename iCubGazeboV2_5_plus to iCubGazeboV2_5_KIT_007 (https://github.com/robotology/icub-models-generator/pull/250).
 
 ### Fixed
 * Fixed wrong simulated finger hall effect sensors port names prefix for `iCubGazeboV2_5_visuomanip` (https://github.com/robotology/icub-models/pull/215).
+* Fixed compatibility with Python 3.12 and various issues with recent Python versions (https://github.com/robotology/icub-models/pull/217, https://github.com/robotology/icub-models/pull/218, https://github.com/robotology/icub-models/pull/219).
+* Change `*_hand_fingers` to `*_hand_finger` in `iCubGazeboV2_5_visuomanip` for consistency with the real robot (https://github.com/robotology/icub-models/pull/213).
+* Fix location of collision element in iCubGazeboV3 model (https://github.com/robotology/icub-models-generator/pull/251).
+
 
 # [2.3.0] - 2023-09-11
 

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -5,7 +5,7 @@
 cmake_minimum_required(VERSION 3.8...3.16)
 
 project(icub-models
-  VERSION 2.3.0)
+  VERSION 2.4.1)
 
 include(GNUInstallDirs)
 

diff --git a/README.md b/README.md
@@ -1,71 +1,77 @@
 # icub-models
 
-Repository containing models [automatically](https://github.com/robotology-playground/icub-model-generator/blob/master/.travis.yml#L76) generated from the CAD file by [icub-model-generator](https://github.com/robotology-playground/icub-model-generator).
+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/).
 
-## Usage
+## Installation
 
-The model in the repo can be used either directly from the repo, or by installing them.
+### conda (recommended) 
 
-While the files can be used directly by pointing your software to their location, they are
-tipically used by software that uses either YARP, ROS or Gazebo. For this reason, the models
-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).
+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
+~~~
 
-To make sure that this models are found by the software even when they are not installed in
-system directories, tipically the [`YARP_DATA_DIRS`](http://www.yarp.it/yarp_data_dirs.html) for [YARP](https://github.com/robotology/yarp), 
-[`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.
+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)
 
-### From the source repo
+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`.
 
-In the case models are used from the repo, the first step is configure it with the following commands:
+### Build from source (advanced)
 
-```sh
-mkdir build
-cd build
-cmake ..
-```
+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).
 
-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:
+## Model Details
 
-```sh
-export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<icub-models>/build/iCub
-export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<icub-models>/build
-```
+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.
 
-### By installing the models
+|  `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   |
+| `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   |
 
-To install the models instead, execute:
 
-```sh
-mkdir build
-cd build
-cmake -DCMAKE_INSTALL_PREFIX=<prefix> ..
-cmake --build . --target install
-```
+## Usage
 
-Once the models are installed into a given prefix, edit the env variables as follows:
+### Use the models with ROS
 
-```sh
-export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<prefix>/share/iCub
-export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<prefix>/share
-export AMENT_PREFIX_PATH=${AMENT_PREFIX_PATH}:<prefix>
-```
-### Use the models with Gazebo
-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``:
-```
-export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:<prefix>/share/iCub/robots:<prefix>/share
-```
-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`)
+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.0)
+cmake_minimum_required(VERSION 3.5)
 project(myproject)
 find_package(icub-models REQUIRED)
 add_executable(example example.cpp)
@@ -93,17 +99,17 @@ int main()
 
 ***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 Python helper library
-In order to use these models in `python` application you can exploit the `icub-models` module.
-`icub-models` provides a `python` package to called `icub_models`. You can install it via `cmake`
-```
-cmake -DCMAKE_INSTALL_PREFIX=<path/where/you/want/to/install> \
-      -DCMAKE_BUILD_TYPE=Release \
-      -DICUB_MODELS_USES_PYTHON:BOOL=ON ..
-cmake --build . --config Release --target install
-```
+### 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
 
-Then the following script can be used to locate the models
+The following script can be used to locate the models
 ```python
 import icub_models
 
@@ -115,7 +121,24 @@ for robot_name in icub_models.get_robot_names():
     print(f"{robot_name}: {icub_models.get_model_file(robot_name)}")
 ```
 
-## Change the orientation of the root frame
+### 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:
 

diff --git a/build-from-source.md b/build-from-source.md
@@ -0,0 +1,19 @@
+# Build icub-models from source
+
+To install the icub-models, execute the following commands from within the ``icub-models`` folder:
+
+
+```sh
+mkdir build
+cd build
+cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release -DICUB_MODELS_USES_PYTHON:BOOL=ON ..
+cmake --build . --config Release --target install
+```
+
+Once the models are installed into a given prefix, edit the env variables as follows to ensure that they can be found.
+
+```sh
+export YARP_DATA_DIRS=${YARP_DATA_DIRS}:<prefix>/share/iCub
+export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:<prefix>/share
+export AMENT_PREFIX_PATH=${AMENT_PREFIX_PATH}:<prefix>
+```
diff --git a/iCub_manual/package.xml b/iCub_manual/package.xml
@@ -1,6 +1,6 @@
 <package>
   <name>iCub</name>
-  <version>2.3.0</version>
+  <version>2.4.1</version>
   <description>
     This is not an actual package, but rather a placeholder to 
     make sure that the share/iCub directory is found as the