Renaming Joints

[NauticalMile64]

After the discussion in issue #25, I've decided to start a new thread for the potential re-naming of many of the box2d joints. As some Joints could be interpreted in similar ways (e.g. RevoluteJoint and WeldJoint) it makes sense think about the entire set of names and how they might overlap or be confused with one another. I created a Classeur markdown document with a table containing .gifs` of most of the joints, documentation text from Box2D and Unity, as well as my thoughts on new names.

I'm not quite finished yet, but most of my thoughts are there. Please comment, I want to end up with names that work for everyone!

[louis-langholtz]

Not to confuse matters but in case it's interesting... Bullet Physics's calls joints "Constraints". For details, see the Bullet 2.83 Physics SDK Manual. One of its constraints is "Generic 6 Dof Constraint" where "Dof" is for degrees-of-freedom. It occurs to me that degrees-of-freedom seems like a desirable trait at least to mention in the Doxygen API comments. But maybe it also has some relevance to joint names?

[NauticalMile64]

Hmm... you're right, constraint is another good word. In fact, the word constraint is technically more accurate than the word joint for the objects that we're dealing with. Some joints lend themselves really well to this naming convention, and others not so well:

Box2D Joint	Constraint Name
RevoluteJoint	AxisConstraint
PrismaticJoint	AngleConstraint
DistanceJoint	DistanceConstraint
WheelJoint	DistanceAngleConstraint
RopeJoint	MaxDistanceConstraint
WeldJoint	FixedConstraint
FrictionJoint	FrictionConstraint?
MotorJoint	PoseConstraint
GearJoint	LinearAngularRatioConstraint?
PulleyJoint	PulleyConstraint?
MouseJoint	PositionConstraint

The word joint is more tangible though 😔 . What do you think?

Note that the quantity describing the position and orientation of a geometric object is called a pose. I any case, I think it's worth mentioning the degrees of freedom in the docs; it will help people coming from a mechanical background.

[NauticalMile64]

The more I think about it I realize that, regardless of the naming, the clarity of the manual, the testbed, any tutorials, and, to a lesser extent, the documentation will have a much larger impact on the understanding of these joints. While the names are still important, I'll refocus on the manual for now.

[louis-langholtz]

@NauticalMile64 I think leaving the term Joint in the name is fine for now; it's shorter too than constraint. And I agree that, like you said, the documentation will have a larger impact on understanding of these joints. Especially if the documentation is online in a format that supports the animated GIFs I think you've used. I really love those GIF's by the way as I think the animations are super helpful at understanding what the joints are better for or more intended for.

The other thing that comes to mind for me regarding the joint concepts, is my belief that functionality like rotational motors or linear motors should be able to be pulled out into separate joints for use through composition instead of as much subclassing. That'd be my preference at least.

A way I see towards better recognizing from a coding standpoint the intentions in the joint code, is getting Mat22 and Mat33 into being templates that can take the unit-type as their types. That's not a huge step forward IMO but I love little steps like this and believe - longer term - that they'll help with deriving answers to questions like naming of the joint classes.

C++17 introduces std::variant which may also play into this. Tagged union can be done manually already.

From a cache perspective, I think it'd be more efficient to refactor apart the joints so that their "tmp" member data was separated off from base joint information somewhat like the current Contact decomposes in the solver to VelocityConstraint/PositionConstraint. This also I think will play a part that I'm excited about.

[louis-langholtz]

@NauticalMile64 Any chance you're willing to contribute any of your joint GIF images/files to the PlayRho/Documentation/images/ folder via a Pull Request ? That'd be super awesome!! I'd love for them to be available for use in documentation.

There are image files in the images folder for some of the joints, but none for Weld Rope Mouse Motor or Friction joints. I see you have images though for these in the referenced Classeur markdown document.

[louis-langholtz]

Towards helping users understand the differences and meanings of the different joint types I'm excited to announce that I've now added a new Testbed test JointsTest.hpp. Running it provides a display of all the different joints in action all in one place. Here's a screenshot:

[louis-langholtz]

I see again now that Unity calls the d2::MouseJoint a TargetJoint2D. I agree too that calling the mouse joint a target joint (i.e. d2::TargetJoint) makes good sense. I'll make this change shortly.