TrackballControls: extend OrbitControls

[WestLangley]

As suggested in #17842 (comment).

#17857 is an alternate implementation. I am posting this for comparison purposes, not at as competing PR.

I was never happy that the original TrackballControls modified the camera up direction. up is not changed in this PR.

In any event, I would NOT immediately remove TrackballControls.js, since current users rely on its API, which is different from that in OrbitControls.js.

[WestLangley]

ephemeral live link

https://raw.githack.com/westlangley/three.js/dev_trackball_controls/examples/misc_controls_trackball.html

master branch: https://threejs.org/examples/misc_controls_trackball.html

[WestLangley]

I would suggest renaming TrackballControls to LegacyTrackballControls, retaining its current API, and keeping it in the library at least for awhile to gauge user response to the new alternative.

Note that LegacyTrackballControls currently supports a different API:

mouse+A: rotate
mouse+S: zoom
mouse+D: pan

//

I would merge this PR if the implementation here is preferred over that of #17857.

[WestLangley]

I would also consider renaming the file OrbitControls.js to CameraControls.js, and have the class OrbitControls extend the class CameraControls. Users would then use these patterns:

import { OrbitControls } from './jsm/controls/CameraControls.js';

import { MapControls } from './jsm/controls/CameraControls.js';

import { TrackballControls } from './jsm/controls/CameraControls.js';

[Mugen87]

I would suggest renaming TrackballControls to LegacyTrackballControls, retaining its current API, and keeping it in the library at least for awhile to gauge user response to the new alternative.

As mentioned here #17857 (comment), I would not start doing this.

I would divide this task into two parts. First, align the API in one release via #17842. Next, consolidate the implementation into a single module (CameraControls sounds fine) with the next release. And then adjust all examples and the docs. This approach appears to me as the most clear one. Especially from a user perspective.

[WestLangley]

First, align the API in one release via #17842.

@Mugen87 It makes no sense to change the API of something that will be deprecated.

If you leave it as it is, it will continue to work for everybody.

[WestLangley]

This version has different behavior and a different keyboard API. See #17858 (comment).

Users will complain it is different, so that is why It is a good idea to retain access to the legacy version for awhile.

[WestLangley]

@Mugen87 Perhaps it is not clear to you that this is NOT just a port of TrackballControls. The behavior is different.

Users will not be happy to have TrackballControls removed and then be expected to use this instead.

That is why I suggested retaining LegacyTrackballControls.

And that is why there is no need to change the API of LegacyTrackballControls now. Changing it now serves no purpose.

That is how I think about it, anyway. :-)

[Mugen87]

Well, I see this differently and think introducing LegacyTrackballControls is a mistake. Hence, I vote not to merge this PR and do what I recommend in #17858 (comment).

Merging #17842 will not change the controls behavior and prepare users for the API shift.

@mrdoob It would be great if you can make a decision here since I feel the discussion is somewhat stuck.

[sciecode]

@mrdoob do you think it would be possible to review this and the alternatives PRs( #17842, #17857 ) for TrackballControls?

I believe everyone is on-board with the final changes, we just need a decision on how to proceed with them and which implementation we should go with.

TL:DR of what's been discussed:

Given that TrackballControls logic is in essence very similar to OrbitControls, it would be advantageous to consolidate a single API.

This involves updating the "legacy" property names, like staticMoving and dynamicDampingFactor. But also altering its current behavior, different keys are used for different events and there's a noticeable sensibility difference compared with the current implementation.

There has been two proposed paths for this:

• Consolidating API (naming conventions only) this release, as per TrackballControls: Refactor API. #17842; and updating behavior and class extension on the next release.
• Directly updating full API and class extension on this release, but keeping LegacyTrackballControls for backwards compatibility purposes.

There's also the suggestion of changing the base class from OrbitControls into CameraControls, and having OrbitControls extend from it as well. As discussed on #17858 (comment)

[WestLangley]

Closing in favor of #18483.