Proposal for iCub naming conventions

[traversaro]

In the process of producing software-friendly models for the iCub robot directly from the Creo CAD models in a semi-automatically, we needed a convention for naming the different elements that constitute the robot. I will proposed a convention extending existing naming schemes, and I will be happy to get any feedback. Sharing a common convention in existing software would help to reduce incompatibilities and integration problems.

Joints

1-DOF Joints

Note: it could be useful to distinguish between the two different concepts of degree of freedom and joint. For simplicity we decide to ignore for the time being this difference, that is relevant for multi-DOF joints and closed kinematic structures.

The joints are mechanism that connect two different links (as defined in the following section) of the robot. 1-DOF joints allow motion only along one direction between the two connected links.

For joints an existing convention is introduced in http://eris.liralab.it/wiki/ICub_joints . I do not know if this names are actually used anywhere in the code and/or documentation (@barbalberto perhaps in IAxisInfo implementation?). Unfortunately in that convention the names are not unique across the robot, so for example knee is used to refer to both left and right knee. So we propose to use that convention, with an additional l_ or r_ prefix for joints that come in symmetric pairs. Disregarding for the moment eyes and hands, then we have the following joint names:

Yarp ControlBoard name	Joint name
left_leg	l_hip_pitch
left_leg	l_hip_roll
left_leg	l_hip_yaw
left_leg	l_knee
left_leg	l_ankle_pitch
left_leg	l_ankle_roll
right_leg	r_hip_pitch
right_leg	r_hip_roll
right_leg	r_hip_yaw
right_leg	r_knee
right_leg	r_ankle_pitch
right_leg	r_ankle_roll
torso	torso_pitch
torso	torso_roll
torso	torso_yaw
head	neck_pitch
head	neck_roll
head	neck_yaw
left_arm	l_shoulder_pitch
left_arm	l_shoulder_roll
left_arm	l_shoulder_yaw
left_arm	l_elbow
left_arm	l_wrist_prosup
left_arm	l_wrist_pitch
left_arm	l_wrist_yaw
right_arm	r_shoulder_pitch
right_arm	r_shoulder_roll
right_arm	r_shoulder_yaw
right_arm	r_elbow
right_arm	r_wrist_prosup
right_arm	r_wrist_pitch
right_arm	r_wrist_yaw

I am personally ok with this names, but perhaps someone (@luca-fiorio ?) has some comments and may thinks that this names are misleading.

Fixed (0-DOFs) Joints

When dealing with 6-axis FT sensors, it is convenient to model them as joints that do not allow any motion between the two connected links.

In the iCub can be mounted up to 6 6-axis ft sensors.

Yarp AnalogSensor name	Fixed joint name
left_arm	l_arm_ft_sensor
right_arm	r_arm_ft_sensor
left_leg	l_leg_ft_sensor
left_foot	l_foot_ft_sensor
right_leg	r_leg_ft_sensor
right_foot	r_foot_ft_sensor

Links

The links are the physical rigid bodies that constitute the robot. Each link is characterised by a mass (represented in models by the inertial parameters) and a physical shape (represented in models by meshes).

For defining the links we are representing the robot as a directed tree, where the root_link is the body that can be attached to the pole, and the meaning of the other links can be deduced by their parent joint, as defined in the previous section.

The main idea behind this naming scheme is that "big" links (roughly speaking, the one that can reasonably interact with the user) are named with intuitive names such as upper_arm, forearm, upper_leg, lower_leg, chest, head, foot, hand. All the little links that instead are part of more complex linkages, take their name from the articulation, such as torso_1, torso_2.

Link Name	Parent Joint	Parent Link
root_link
l_hip_1	l_hip_pitch	root_link
l_hip_2	l_hip_roll	l_hip_1
l_hip_3	l_leg_ft_sensor	l_hip_2
l_upper_leg	l_hip_yaw	l_hip_3
l_lower_leg	l_knee	l_upper_leg
l_ankle_1	l_ankle_pitch	l_lower_leg
l_ankle_2	l_ankle_roll	l_ankle_1
l_foot	l_foot_ft_sensor	l_ankle_2
r_hip_1	r_hip_pitch	root_link
r_hip_2	r_hip_roll	r_hip_1
r_hip_3	r_leg_ft_sensor	r_hip_2
r_upper_leg	r_hip_yaw	r_hip_3
r_lower_leg	r_knee	r_upper_leg
r_ankle_1	r_ankle_pitch	r_lower_leg
r_ankle_2	r_ankle_roll	r_ankle_1
r_foot	r_foot_ft_sensor	r_ankle_2
torso_1	torso_pitch	root_link
torso_2	torso_roll	torso_1
chest	torso_yaw	torso_2
l_shoulder_1	l_shoulder_pitch	chest
l_shoulder_2	l_shoulder_roll	l_shoulder_1
l_shoulder_3	l_shoulder_yaw	l_shoulder_2
l_upper_arm	l_arm_ft_sensor	l_shoulder_3
l_elbow_1	l_elbow	l_forearm
l_forearm	l_wrist_prosup	l_elbow_1
l_wrist_1	l_wrist_pitch	l_forearm
l_hand	l_wrist_yaw	l_wrist_1
r_shoulder_1	r_shoulder_pitch	chest
r_shoulder_2	r_shoulder_roll	r_shoulder_1
r_shoulder_3	r_shoulder_yaw	r_shoulder_2
r_upper_arm	r_arm_ft_sensor	r_shoulder_3
r_elbow_1	r_elbow	r_arm
r_forearm	r_wrist_prosup	r_elbow_1
r_wrist_1	r_wrist_pitch	r_forearm
r_hand	r_wrist_yaw	r_wrist_1

Frames

In literature and in robotics software, the links and frames concepts are often confused, because every link is usually associated with a frame rigidly attached to it. However this link frame definition is dependent on the formalism that one uses for describing the robot. For example, if the Denavit Hartenberg convention is used the link frame origin is required to be placed on the axis of the child joint, while if the Modified Denavit Hartenberg convention or the URDF format the link frame origin is required to be place on the axis of the parent joint.
To avoid inconsistency, I think it is better to clearly separate frame and link concepts.
For the iCub, it could be useful to explicitly state the frame used for defining the kinematic chains used in the iKin library.
In particular a useful set of frames could be:

Frame Name	Link	Explanation
root_frame	root_link	Root reference frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
imu_frame	head	Inertial sensor (XSens MTx) reference frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
l_hand_dh_frame	l_hand	Left hand frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
r_hand_dh_frame	r_hand	Right hand frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
l_foot_dh_frame	l_foot	Left foot frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
r_foot_dh_frame	r_foot	Right foot frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
l_eye_frame	--- (missing at the moment)	Left eye frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
r_eye_frame	--- (missing at the moment)	Right eye frame, as defined in http://eris.liralab.it/wiki/ICubForwardKinematics
l_arm_ft_frame	l_upper_arm,l_arm	Left Arm FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor
r_arm_ft_frame	r_upper_arm,r_arm	Right Arm FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor
l_leg_ft_frame	l_hip_2,l_hip_3	Left Leg FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor
l_foot_ft_frame	l_upper_foot,l_foot	Left Foot FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor
r_leg_ft_frame	r_hip_2,r_hip_3	Right Leg FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor
r_foot_ft_frame	r_upper_foot,r_foot	Right Foot FT sensor frame, as defined in http://wiki.icub.org/wiki/FT_sensor

Skin Frames

An interesting set of frame is the frame defined by the iKin convention ( http://eris.liralab.it/wiki/ICubForwardKinematics ). This reference frames are used by the skin system to express contact points, force and torques (in skinDynLib data structures) and taxel positions.
The one currently used by the skin system are:

Frame Name	Link	Explanation
l_foot_dh_frame	l_foot	Frame of LEFT_FOOT SkinPart
r_foot_dh_frame	r_foot	Frame of RIGHT_FOOT SkinPart
l_upper_arm_dh_frame	l_upper_arm	Frame of SKIN_LEFT_UPPER_ARM SkinPart
l_forearm_dh_frame	l_forearm	Frame of SKIN_LEFT_FOREARM SkinPart
l_hand_dh_frame	l_hand	Frame of SKIN_LEFT_HAND SkinPart
r_upper_arm_dh_frame	r_upper_arm	Frame of SKIN_RIGHT_UPPER_ARM SkinPart
r_forearm_dh_frame	r_forearm	Frame of SKIN_RIGHT_FOREARM SkinPart
r_hand_dh_frame	r_hand	Frame of SKIN_RIGHT_HAND SkinPart

SkinPart RIGHT_LEG_UPPER, LEFT_LEG_UPPER, RIGHT_LEG_LOWER, LEFT_LEG_LOWER and SKIN_FRONT_TORSO are not currently correctly processed by the system and they are not assigned any frame. In particular SKIN_FRONT_TORSO is problematic because the Torso link for the DH convention used by iKin for frame placement has three different frames, depending on which chain is considered (if head, right arm or left arm).

For all this frames, an alternative naming could be:
"linkName_ikin_frame", to have a name that is directly related to the iKin software.

Other frames

Probably some other intermediate frame could also be useful, as something related to the neck.

Additional frames could be defined to improve compliance with REP-120 that is already used for different humanoids URDFs (Nao, Romeo, HRP-2, Coman).

This is an initial proposal that is not discussing several important aspects (eyes, hands, accelerometers, gyroscopes), but I guess it is already ready for getting some feedback.

cc @EnricoMingo @jeljaik @arocchi @hu-yue

[jeljaik]

👍 Nice summary!
There are only two things I personally dislike.
One is the word 'shank' to describe the part of the lower limb from knee to ankle. I know it's meant to sound more anatomically correct, but then neither 'leg' should be used to describe the entire lower limb, as it is also defined as the part between the knee and ankle (it's a synonym actually).
I also don't like 'l' and 'r' for left and right. More proper acronyms such as rt, lft, lt look better IMHO, e.g. lt_foot as opposed to l_foot. It also removes ambiguity between letters like 'l' and 'I' (capital i and l).

[traversaro]

If we want to improve readability I would personally go for the complete prefix, like right_knee. The only problem that in this case we would get some name clash, for example we will have the right_arm yarp control board and the right_arm link, but I guess it is not a big problem.

[lornat75]

Nice work @traversaro.

I vote +1 for left right instead of the shortened l and r.

I propose we put this convention in the iCub wiki extending http://eris.liralab.it/wiki/ICub_joints

[lornat75]

Actually: checking http://www.ros.org/reps/rep-0120.html looks like the use l and r so I maybe it would be better to use this convention.

[traversaro]

To wrap up the contributions:

• *_shank --> *_leg (I already updated the proposal).
• For using l_ and r_ instead of left_,right_ I must say that a lot of models around (such as the one for Aldebaran robots [1]) already use their own naming scheme, and they use l_,r_ only for REP-120 frames. The Atlas model [2] that is created at OSRF instead follows the l_,r_ scheme. I am indifferent to the question.
• We could update the names in http://eris.liralab.it/wiki/ICub_joints to be unique in the robot, and possibly implement IAxisInfo interface in CanBusMotionControl and embObjMotionControl. @barbalberto

[1] Romeo/Nao: https://github.com/laas/romeo/blob/master/romeo_description/urdf/romeo.urdf
Atlas: https://bitbucket.org/osrf/drcsim/src/d8b694402689bd5f359f2bf0d2d3845d8afc5f42/atlas_description/urdf/atlas.urdf?at=default

[traversaro]

Sorry for the supporter of left_, but eventually l_ and r_ reached the larger consensus.

[traversaro]

cc @luca-fiorio @johnlaser

[traversaro]

@johnlaser correctly pointed out that the lap_belt_1, lap_belt_2 names are really confusing. Perhaps we can stick with torso_1 and torso_2 to be coherent with the naming scheme that we use in the shoulder ?

[miggia]

... is an horrible and misleading name

I would propose torso_1 e torso_2

[traversaro]

Yeah, the fact that we came up with the same name indipendently mean this names are ok, implementing the changes.

[traversaro]

Regarding additional frame for compliance with REP-120 , we recently discussed with @hu-yue that for working on locomotion she needs a stable reference frame fixed with the sole of the robot.
I then propose that we define the two frames l_sole and r_sole.
The origin of the this two frames should be defined as the projection of the origin of the ankle FT sensor to the sole (it this coherent with coman @EnricoMingo @arocchi ?) and consistently with REP-120 the direction axes should be X-FORWARD (of the robot), Y-LEFT (of the robot), Z-UP.

[traversaro]

@johnlaser correctly pointed out that r_upper_arm can be confusing, given that sometimes the whole r_arm is named "upper_arm", for example in the SkinPart enum ( http://wiki.icub.org/iCub/main/dox/html/namespaceiCub_1_1skinDynLib.html#ad9eb09d94574e8020c27676ca5e9bdfc ). It is then a better idea to rename *_upper_arm to *_shoulder_3.

[alecive]

@traversaro I don't get it. For the SkinPart enum the SKIN_*_UPPER_ARM is indeed referring to the third joint of the shoulder (the one whose link is between the shoulder and the elbow and is covered with the skin). Why are you saying that it considers that as the whole *_arm?

[iron76]

Same concern as @alecive here. upper_arm seems to me (anatomically) very clear.

[traversaro]

@alecive In the current proposal *_leg and *_arm are used to identify specific links in the structure. These can lead with confusion with the whole "part", so perhaps a better name should be used.

Notice that this mismatch is present even in port names of the skin : http://wiki.icub.org/wiki/Tactile_sensors_%28aka_Skin%29

Possible alternative names are:
*_arm --> *_upper_arm
*_leg --> *_lower_leg (as done in SkinPart enum) or _shank (that @jeljaik disliked).

[iron76]

Proposal for the more important rigid links: upper_arm, fore_arm, upper_leg, lower_leg, chest, head, foot, hand.

[traversaro]

I guess forearm should be a a complete word.

[traversaro]

The other "important" rigid link is the root_link. Any doubt on this name?
For all other links, they are clearly not so big so the general idea is to name them as articulation_number, as in torso_1,torso_2.

[alecive]

Ok I got what you mean. Regarding the port names in the skin manager, at least for me that is a bug, especially since the SkinPart enum clearly uses upper_arm (therefore, also the port should stick to that convention).

Therefore, I would rather go with @iron76 's proposal (but I'd use forearm instead of fore_arm and torso instead of chest).

[iron76]

fore_arm was meant to be consistent with other names (e.g. upper_arm). But I agree forearm is the correct choice.

[traversaro]

Given the feedback received, I have prepared a new proposal for Link naming, that I report in the following.

Please note that changing names involve some changes in a lot of configuration files that we use in codyco software, so reaching a consensus as soon as possible simplifies things.

@alecive torso used as a link name could create some confusion with the joints that are named torso_jointname and the little links torso_1, torso_2 that are connecting the root_link to the chest.

[iron76]

👍 @traversaro

[alecive]

@traversaro got it . And I agree with you 👍

[lornat75]

+1 Small comment: chest breaks symmetry -- why don't we use torso instead?

[traversaro]

@lornat75 torso used as a link name could create some confusion with the joints that are named torso_jointname and the little links torso_1, torso_2 that are connecting the root_link to the chest.

[lornat75]

It was just a small comment. I am fine with chest.

[traversaro]

I migrated the proposal that we discussed here in http://wiki.icub.org/wiki/ICub_Model_naming_conventions .
The documentation can be improved in many ways (integration with existing pages in the manual, better visual feedback) but I think that for now we can close this discussion.

[pattacini]

👍