Add common Three.js primitive geometries, polar_grid scene parameter, and rotate(order=...)

[Jepson2k]

Motivation

ui.scene is missing several commonly-used Three.js primitives (Plane, Cone, Torus, Capsule), a Line-with-vertex-colors-and-dashing primitive (Polyline), and a surface-of-revolution primitive (Lathe). Many 3D visualizations also benefit from a circular polar floor instead of a rectangular grid.

This PR fills those gaps and generalizes Object3D.rotate(...) to support all six intrinsic Euler orders rather than only the implicit 'XYZ'.

Implementation

• New geometry primitives: Polyline (with optional per-vertex colors and dashed material), Lathe, Plane, Cone (with open_ended / theta_start / theta_length), Torus (with optional partial arc), Capsule. Each is a module in objects/ like the existing primitives: Plane, Cone, Torus, Capsule and Lathe return their Three.js geometry from create_geometry, and Polyline builds its own Line in create_mesh so it can carry per-vertex colors and dashing.
• Polar grid: Scene(polar_grid=(radius, sectors, rings)) or (radius, sectors, rings, divisions), where divisions sets how smooth each ring is (default 64). Replaces the rectangular grid with PolarGridHelper. Mutually exclusive with grid (polar takes precedence).
• Euler rotation order: Object3D.rotate(..., order='ZYX') accepts any of {'XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX'}. Default 'XYZ' is bit-for-bit unchanged. Matrix is composed Python-side so the rotation survives a re-send to the client.

Progress

• The PR title is a short phrase starting with a verb like "Add ...", "Fix ...", "Update ...", "Remove ...", etc.
• The implementation is complete.
• This PR does not address a security issue.
• Pytests have been added.
• Documentation has been added.
• No breaking changes to the public API.

[evnchn]

Thanks @Jepson2k — really nice work here. The feature code is correct (I re-derived the rotation math against numpy for all 6 orders + legacy 3-arg, and checked every new primitive's args against its Three.js constructor), the tests are a cut above, and CI's green. Two notes:

1. The STL-loader rework fixes a real crash — let's get it out ahead of the rest

Nice catch reworking the STL path (empty-BufferGeometry → deferred-material THREE.Group, mirroring the gltf path). I built a minimal repro to understand it, and it's better than it looks: it fixes a hard crash on main, not just a cosmetic glitch.

Minimal repro (12-triangle cube STL, wireframe=True):

from nicegui import app, ui

@ui.page('/')
def index():
    app.add_static_file(local_file='cube.stl', url_path='/cube.stl')
    with ui.scene() as scene:
        scene.stl('/cube.stl', wireframe=True)

ui.run()

	main (3.13.0.post24.dev0+c40f3e3f)	this PR
object registered	❌ objects.get(id) → undefined	✅ a Group
console	❌ 2× Uncaught TypeError	✅ clean
renders	❌ nothing	✅ edges (EdgesGeometry, non-empty)

Same app, same cube.stl — main renders nothing, this PR renders the wireframe cube:

main — wireframe STL crashes, renders nothing	this PR — wireframe renders correctly

On main, EdgesGeometry is handed an empty BufferGeometry, so it throws reading .count of an undefined position attribute during creation (the object never even gets added), and the async load callback then throws again setting .geometry on the never-assigned mesh. Your version — building EdgesGeometry inside the load callback + deferring material via pendingMaterialInfo — is the correct fix.

Because this is a genuine bugfix to an existing, broken public-API path (wireframe=True on scene.stl), I think it's worth landing sooner than the rest of this PR rather than riding along with the new geometry work. Two ways to do that:

• (b) — my suggestion: split it into its own tiny PR. The repro + test below are already a complete bug report, so it can go green and merge quickly on its own, and the primitives here aren't held up by it. I'm happy to open that PR (with the test + a tests/media/cube.stl fixture) and credit you.
• (a) or keep it here, add the STL test below, and call the fix out in the PR description so it's not a silent change.

Ready-to-use regression test (crashes on main as above, passes here):

def test_stl_wireframe(screen: Screen):
    """A wireframe STL must render as edges: a LineSegments whose geometry is EdgesGeometry."""
    scene = None
    obj = None

    @ui.page('/')
    def page():
        nonlocal scene, obj
        app.add_static_file(local_file=TEST_DIR / 'media' / 'cube.stl', url_path='/cube.stl')
        with ui.scene() as scene:
            obj = scene.stl('/cube.stl', wireframe=True)

    screen.open('/')
    screen.wait(1.0)
    result = screen.selenium.execute_script(
        f'const o = getElement({scene.id}).objects.get("{obj.id}");'
        'const child = o.children && o.children[0];'
        'return {'
        '  root_type: o.type,'
        '  child_geometry: child ? child.geometry.type : null,'
        '  edge_count: (child && child.geometry.attributes.position) ? child.geometry.attributes.position.count : 0,'
        '};'
    )
    assert result['root_type'] == 'Group', f'expected a Group wrapper, got {result}'
    assert result['child_geometry'] == 'EdgesGeometry', f'expected EdgesGeometry child, got {result}'
    assert result['edge_count'] > 0, f'expected non-empty edges, got {result}'

2. rotate docs say "intrinsic" but the implementation is extrinsic

The demo (and the PR description) describe the order as "intrinsic", but the implementation is extrinsic: order='XYZ' → Rz @ Ry @ Rx, i.e. Rx applied first about the fixed world axes. The method docstring gets this right ("the leftmost letter rotates first about the world frame"). Since extrinsic-XYZ ≡ intrinsic-ZYX, calling the 'XYZ' string "intrinsic" is misleading — it'd point users at the wrong order string. Just align the demo/description wording with the (correct) method docstring.

Everything I verified

• Rotation math: all 6 orders + legacy 3-arg re-derived against an independent numpy reference — all match. Default 'XYZ' reduces exactly to the prior Rz @ Ry @ Rx (backward-compatible). Bad-order ValueError guard present. Ran the pure-Python tests locally: 5 passed.
• Primitive arg alignment: clean — cone/plane/torus/capsule/lathe/polyline all line up positionally with the Three.js constructors (three@^0.180.0).
• Polyline vertex colors: material(color=None) → JS vertexColors = (color === null) → neutral white + vertexColors=true; does not clobber per-vertex colors. traverse predicate correctly widened to isMesh || isLine.
• polar_grid: rotateX(π/2) + translateZ(-0.01) + object_id="ground" match the existing rectangular-grid branch, so click/picking is unchanged; if (polarGrid) … else if (grid) gives it precedence, matching the docstring.
• STL differential run on both branches: crash on main (2× Uncaught TypeError, object unregistered) vs pass on this PR. Chrome 149, headless.
• CI: mypy / pylint / pre-commit / quick-test all green.

[evnchn]

@falkoschindler You may want to look at the real bug fixed also by this PR and see how to proceed, in this PR or break-out

[Jepson2k]

@evnchn @falkoschindler the STL fix was split out to #6137 and docs updated as well.

[evnchn]

Thanks @Jepson2k — that closes out both notes cleanly:

• STL crash fix → split into Fix crash when loading STL with wireframe=True #6137, with the repro/analysis credit carried across, so it can land on its own timeline ahead of the feature work here. 👍
• rotate order wording → the demo now reads "extrinsic" + "the leftmost letter rotates first about the world frame", which matches the (already-correct) method docstring. Exactly the fix — no more pointing users at the wrong order string.

Feature code was already correct on my end, so with the docs squared away this PR is in good shape from my side. Merge-order/timing between this and #6137 I'll leave to @falkoschindler.