Update TorusGeometry with thetaStart and thetaLength

[3dpk-interactive]

Fixed #32759

TorusGeometry does not currently support thetaStart and thetaLength properties to allow the creation of a "semi torus" such that the torus is "sliced" horizontally in half like a bagel.

This commit adds support for specifying a thetaStart and thetaLength in TorusGeometry to allow a specified "sweep" of the tube or "semi torus".

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	355.34 84.48	355.34 84.48	+0 B +0 B
WebGPU	621.09 172.46	621.09 172.46	+0 B +0 B
WebGPU Nodes	619.7 172.22	619.7 172.22	+0 B +0 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	487.57 119.37	487.57 119.37	+0 B +0 B
WebGPU	692.03 187.85	692.03 187.85	+0 B +0 B
WebGPU Nodes	641.83 175.02	641.83 175.02	+0 B +0 B

[Mugen87]

Tested the PR locally and it works as expected.

Do you mind making the new parameters configurable in the geomtry browser? It's this code block:

https://github.com/mrdoob/three.js/blob/04b1f836b50c36dd012705c57133eaa78cd5df18/docs/scenes/geometry-browser.html#L554C5-L584

If you do that, users can play with the parameters in the doc page:

https://threejs.org/docs/#TorusGeometry

@mrdoob @WestLangley Do you support these new parameters?

[3dpk-interactive]

Yes I certainly can, I'll do this now, would you like me to update the docs with these parameters my side also?

On an extended note I've also configured code that creates an "internalWall" which is run when a boolean constructor parameter "internalWall" is set to true and "thetaLength" is less than Math.PI * 2 ( creating a solid ring type shape), however I have omitted this for the time being to keep things simple and for a few other reasons as follows...

1. I'd need some advice how best to format and include the "createInternalWall" function within the current structure of the class,
2. The "internalWall" function does not yet account for "end caps" if the arc is also less than Math.PI * 2.
3. This addition may abstract the class too far away from being categorised as a "TorusGeometry", I'd be open to opinions to see if this would be a logical addition ( if so I'd also need to build out the "end cap" logic which may need to be included as another boolean parameter).

[WestLangley]

Do you support these new parameters?

The parameters are difficult to both name and describe, and should probably be more akin to those of SphereGeometry

phiStart = 0, phiLength = Math.PI * 2, thetaStart = 0, thetaLength = Math.PI

But that requires an API change for something that has had no demand.

Perhaps leave the code as-is, and the OP can create a generalized version, and share it online as an add-on?

[3dpk-interactive]

Do you mind making the new parameters configurable in the geomtry browser?

@Mugen87 I have included these parameters in the geometry browser of this PR for testing as requested.

The parameters are difficult to both name and describe,

@WestLangley I agree with this, I also had difficulty finding the correct definitions of the parameters here, for example... creating the shapes in the following images by setting the "thetaStart" to Math.PI / 4 is more like the "twist" parameter for Torus Geometry in Maya...

whereas the technical terminology for the dimension being manipulated on the torus here is mathematically referred to as the "Poloidal direction" or in this case would be the "poloidal angle" ("poloidal start" and "poloidal length") which again would be Inconsistent with the naming used for SphereGeometry, CylinderGeometry and the likes...

OP can create a generalized version, and share it online as an add-on

I'm OK to close this PR if the consensus is that it's not useful, I needed to expose these parameters for a personal project but also thought it may help follow suit with the parameters of other geometries such as SphereGeometry and CylinderGeometry, let me know what's best and I'll proceed as advised.

[Mugen87]

would you like me to update the docs with these parameters my side also?

Updating the JSDoc is sufficient. And you have already done that.

[mrdoob]

I like the improvement but my ADHD brain is annoyed with the order of parameters 😅

( radius, tube, radialSegments, tubularSegments, arc, thetaStart, thetaLength )

Guess there isn't much we can do....

[Mugen87]

We have discussed in the past more than once if enhancements of geometry generators are okay since they already have a certain complexity. I still like the policy that these modules should focus on the most important use cases since it's not complicated to create a custom generator for more specific requirements. But to me, this particular enhancement looks appropriate so I vote for a merge.

[Mugen87]

BTW: The CI fails since the geometry browser has been updated and the respective file is in the "protected" docs folder (see 3a84165).

We could update github/workflows/protected-folders.yml and exclude docs/scenes*/ but given that almost no PR updates these files, it's maybe okay to just use the simple rule.