Open Andlon opened 1 year ago
I see the confusion. Definitely at the very least the documentation for the compute_minimum_distance
function needs to be updated to state the returned value is a squared distance.
I originally choose not to put the word squared
in the function names to keep them short and concise, and as you said distance in the toolkit is unanimously referring to a squared distance. However, I agree this can be confusing. Let me think about how to best proceed.
Actually, one small counterpoint to the point about squared distances being unanimous: Some parameters are actually not squared, such as dhat
and dmin
, I believe.
Yes, you are right dhat and dmin are unsquared.
Just spent some time scratching my head with
CollisionConstraints::compute_minimum_distance
. The documentation says it returns the minimum distance, but I found this in the implementation:I realize that you're basically working with squared distances throughout (although for an outside user it is not clear if this holds in all cases), but it's still very confusing that "distance", which is a very unambiguously defined term in my opinion, actually means "squared distance". In my opinion, it would reduce confusion a lot for the new users and possible contributors if squared distances were always marked as such, e.g. by using naming like
compute_squared_distance
,compute_distance2
or similar.(I labeled this as "bug" as, if you take the documentation and function names at their face value, what is returned is not what the naming suggests)