OrbitControls: support more flexible azimuthal limits

[WestLangley]

Continues #19266 and #19296.

Here is what I came up with last week... You guys can fight it out. :-)

Known limitation: If the azimuthal gap is very narrow, it can "jump across the gap" and continue to rotate, particularly with larger values of the damping factor. Not worth fixing, IMO.

Full disclosure: this was based on the work of @sciecode.

[munrocket]

I like that we don't do anything, when we don't have limits. Because it's the most popular usage.

if ( isFinite ( min ) && isFinite( max ) ) {

This branch will be never reached if we will say that one angle need to be in range [-pi, pi].

;else if ( min > Math.PI ) min -= twoPI;

WestLangley stole a commit from ScieCode without references :D

[sciecode]

I'm fine with any of the proposed PRs.

But to be honest, we are only struggling to find a good solution to this simple problem, because we are having to fight against a really bad API. The current API forces us to make a bunch of unnecessary checks and data-manipulation inside update, because we allow the user to directly alter the values. And, IMO, it's still non-intuitive for the users to reason about it.

That's really all I have to say about this.

[munrocket]

I like your approach, just need to update documentation.

Also good enchantment is vertical scroll since OrbitControls also MapControls.

[DefinitelyMaybe]

noted.

[WestLangley]

if we will say that one angle need to be in range [-pi, pi].

Actually, I did not say that... From the in-line comments in this PR:

// If set, the interval [ min, max ] must be a sub-interval of [ - 2 PI, 2 PI ], with ( max - min < 2 PI )

Although not explicitly stated, min is always less than max -- as one would typically assume.

This is backwards-compatible, and IMO, it is a perfectly-fine API. But, we can use a different API if that is preferred.

[WestLangley]

@sciecode It seems this will only be merged if you are OK with it.

[sciecode]

As the hip kids say, ship it.

[mrdoob]

Thanks!