Consolidating "Group" Terminology

[bgill92]

Hello MoveIt Community!

Here at PickNik, we are in the process reviewing the current MoveIt architectural landscape and seeing where clarifications and improvements can be made. In our current investigation, we have determined that the term "Group" is used in many places and can be considerably confusing. For example, there are "Planning Groups", "Joint Groups", "Kinematic Groups", among other places where the term "Group" is used. Some of these terms have baked in assumptions and sometimes these terms are used interchangeably, when they shouldn't be. For example, a "Joint Group" is supposed to be a set of actuatable joints, but a "Joint Group" could also contain links. "Joint Group" is also used synonymously with "Group". A "Planning Group" is a "Group" that also has a planner associated with it. A "Kinematic Group" is a "Group" that has a kinematic solver associated with it.

To remove/simplify the assumptions that are baked into these terms, we are proposing renaming "Group" explicitly into "Joint Link Group". With this renaming, as the name suggests, a "Joint Link Group" is a collection of both joints and links. Since a "Joint Link Group" is simply collection of joints and link, The "Joint Link Group" is not assumed to be plannable. It is the responsibility of the planner or the inverse kinematics plugin to determine if the "Joint Link Group" can be used. This change would also facilitate the need to phase out the terms "Planning Group" or "Kinematic Group". Instead of a "Planning Group", a planner plans a path for a "Joint Link Group" and instead of a "Kinematic Group", a inverse kinematics solver calculates the joint values for a "Joint Link Group". With this change, we hope to make it easier for people new to the codebase to understand and utilize MoveIt.

We would like to hear your thoughts on this proposal. Where do you foresee issues? Is this a change that would help newcomers? Have you been confused in the past with all of the terminology pertaining to "Groups"?

[EzraBrooks]

There's ~360 occurrences in the moveit2 repo of the "planning group" name. Are those identical to "joint model group" (~970 occurrences)? Should we start by consolidating terminology to one of the terms that already exists?

Seeing as we're wanting to elucidate that a group doesn't necessarily need to be plannable, maybe renaming all "planning group" in documentation and code to "joint model group" is the first clarifying step?

[AndyZe]

I'd go with KinematicGroup rather than JointLinkGroup, if anything. Sounds simpler, means the same.

[rhaschke]

All group termini are used interchangably in MoveIt. Actually, there exists only a single group type, namely JointModelGroup.
Surely, a group optionally can have a kinematics solver associated, which is stored in the group_kinematics_ member of the JointModelGroup. But, I have never seen the notion of a kinematic group.
Regarding planning group: this is just a synonym for a JointModelGroup. You cannot associate a planner to a group. You just plan on a group.

From my point of view, it would suffice to clearly state the definition of a JointModelGroup and clarify that all group termini can be used synonymously.

The proposed terminus "JointLinkGroup" and your definition are misleading: A JointModelGroup isn't a group of arbitrary joints and links. It is just a group of arbitrary joints (not restricted to actuatable ones) and their associated child links. The JointModelGroup constructor just takes a vector of joint models and stores the associated child links.

I added a corresponding definition years ago in MSA's planning group tab to clarify the meaning for users:

A planning group defines the set of (joint, link) pairs considered for planning and collision checking.
Define individual groups for each subset of the robot you want to plan for.
Note: when adding a link to the group, its parent joint is added too and vice versa.

[EzraBrooks]

The original SRDF specification does say that you can include arbitrary links within a group - is that not relevant in MoveIt's implementation of SRDF? This is great info, thanks!

[rhaschke]

The original SRDF specification does say that you can include arbitrary links within a group - is that not relevant in MoveIt's implementation of SRDF? This is great info, thanks!

The SRDF spec also states:

Note: When a link is included in a group, so is the corresponding parent joint (if one exists)

and

Note: When a joint is included in a group, so is the corresponding child link

[EzraBrooks]

Aha, so it's effectively an alternate syntax for specifying joints; a list of links just gets translated to a list of the parent joints of those links. Interesting! In that case it definitely sounds like consolidating terminology around JointModelGroup makes sense, since as you say it's the only group that actually exists.

At PickNik and elsewhere, we've used and heard the term "planning group" far more frequently than "joint model group", and as a result there's been some code written in MoveIt and in projects that use it that incorrectly assumes groups will/should always be plannable. So from a developer experience standpoint, we're trying to make sure everyone's on the same page here. I appreciate your help!