v0.4.0: Higher-fidelity renderer (VTK or trimesh-scene swap)

[digispark-bot]

Goal

Current 3D renders use matplotlib's Poly3DCollection with per-face Lambertian shading — "good enough to confirm not garbage" but flat-looking, no real depth occlusion, no surface-finish cues. For parts where the visible finish matters (cosmetic enclosures, display pieces), a better renderer would catch issues the iso view hides.

Concrete deliverable

Swap or augment the 3D render path with a higher-fidelity backend. Two candidates:

Option A — trimesh scene renderer (trimesh.Scene.save_image)

• Already have trimesh as a dep; uses pyglet/pyrender under the hood
• Needs a headless GL context (EGL/OSMesa) in the container — adds apt deps
• Better occlusion + lighting than matplotlib

Option B — VTK offscreen

• Heavier dep, but best-in-class CAD-style rendering
• Offscreen rendering well-supported headless

Decision criteria (resolve during spike)

• Does it work cleanly headless in the existing slim container without ballooning image size? (matplotlib/Agg's whole appeal was zero GL deps — see renderer.py docstring "No Xvfb, no VTK, no OSMesa")
• Is the fidelity gain worth the dep weight + container complexity, given the perimeter/small-over-capable principles?

This may resolve as "not worth it." The matplotlib renderer was a deliberate small-over-capable choice. Only swap if a real design's review actually needed finish detail the iso view couldn't show. Spike first, decide, document the decision either way.

Out of scope

• Photorealistic/ray-traced output — marketing material, not design review
• Animation / turntable GIFs

Why

Per ROADMAP Theme 2 (output fidelity). Lowest-priority Theme 2 item and the most likely to be declined on cost/benefit — filed for completeness so the decision is tracked, not forgotten.

Tracked in ROADMAP.md Theme 2.

[digispark-bot]

Status after Sprint A (Theme 2): kept open as a future option, not scheduled.

The other two Theme 2 items shipped — section fill + topology deltas (v0.3.3, #13) and dimensioned drawings (v0.3.4, #12). This renderer swap is intentionally left for later rather than built now.

Why not now: VTK/OSMesa (or a trimesh-scene/pyrender path) buys photorealistic-ish previews at the cost of a heavier image and a system-library footprint (GL/OSMesa) that breaks the current "works in any vanilla container, no Xvfb/VTK/OSMesa" guarantee. That cuts against the project's small over capable principle, and the matplotlib Agg renderer is already "good enough to confirm not garbage" for FDM homelab parts.

Revisit when a real design actually needs surface-finish-quality previews — e.g. evaluating visible-surface aesthetics, draft/texture, or fillet blends where the flat-shaded matplotlib render genuinely can't answer the question. At that point, weigh:

• a trimesh built-in scene render (scene.save_image, needs pyglet/OpenGL) vs. full VTK — prefer the lighter option;
• whether it can be an optional extra (separate image tag / extra dependency group) so the default slim container stays lean;
• whether better matplotlib lighting/material shading closes enough of the gap without any new dependency.

No action needed until that demand shows up.