Incorrect displacement for stereo convergence distance

[Robert Rasmussen]

The code for creating stereo lenses implements a frustum skew with a displacement of 1/(4*Convergence_Distance). Working through the geometry, the correct displacement should be equal to Interocular_Distance/(2*Convergence_Distance*tan(Horizontal_FOV_Angle/2))

[rdb (rdb)]

Hmm, I'll have to ask David Rose about how they've been using stereo cameras at Disney.

I ran some tests and found that the convergence is indeed correct with your corrected calculations, assuming that the distance is given in world coordinates.

However, perhaps this assumption is wrong. Could it be that the intent was for this value to be specified in film coordinates? The reason why I'm thinking that is because of the way we calculate the film size given a particular focal length:
film_width = 2 * focal_length * tan(hfov / 2)
This looks an awful lot like your calculation above, which makes me suspect it's perhaps supposed to be specified differently. Does this make sense at all to you?

[Robert Rasmussen (rgr10)]

That is possible, although I would find it unusual for the IOD input being expected in world coordinates whereas the convergence distance expected in film coordinates. The doc-string for the setconvergencedistance you posted in the forums seems to suggest that it expects world coordinates as the input:
// Function: Lens::set_convergence_distance
// Access: Published
// Description: Sets the distance between between the camera plane
// and the point in the distance that the left and right
// eyes are both looking at. This distance is used to
// apply a stereo effect when the lens is rendered on a
// stereo display region. It only has an effect on a
// PerspectiveLens.
//
// This parameter must be greater than 0, but may be as
// large as you like. It controls the amount to which
// the two eyes are directed inwards towards each other,
// which is a normal property of stereo vision. It is a
// distance, not an angle; normally this should be set
// to the distance from the camera to the area of
// interest in your scene. If you want to simulate
// parallel stereo, set this value to a very large
// number.

[rdb (rdb)]

Okay, I've been running more tests and your calculations seem spot-on, whereas the old ones are only reasonably OK for certain distances using a certain configuration of FOV and IOD.

I had a bit of correspondence with David and we concluded that we should replace the broken calculations, but leave a configuration variable called "stereo-lens-old-convergence" (default=false) that can be toggled on to switch back to the old calculations, since there are people who may rely on the old settings.

I checked in corrected calculations to CVS and updated the documentation appropriately. I especially changed the in-source documentation not to mislead people into thinking that setting a convergence distance enabled toe-in rendering.

Many thanks for reporting this bug and providing the corrected formula!