Image→3D quality pass (#764): Taubin smoothing + iso-surface reprojection + baked diffuse texture (+ Real-ESRGAN chain)

.gitignore

@@ -93,6 +93,7 @@ website/node_modules/
 docs/*
 !docs/AUTO_UPDATER_DESIGN.md
 !docs/IMAGE_TO_3D_SPIKE_764.md
+!docs/IMAGE_TO_3D_QUALITY.md
 !docs/MESH_SEGMENTATION_STRATEGY.md
 
 # minisign — never commit secret keys

docs/IMAGE_TO_3D_QUALITY.md

@@ -0,0 +1,94 @@
+# Image-to-3D quality roadmap (post-#764)
+
+Goal: close the visible gap between our local TripoSR output and commercial
+services (Meshy, Tripo3D) while staying permissive-license-clean and local.
+
+## Shipped: the quality pass (this branch)
+
+Three classical post-processing stages, ON by default, between marching cubes
+and mesh construction (`MeshGenPredictor::Options {smoothMesh, refineSurface,
+bakeTexture, textureSize}`):
+
+1. **Taubin smoothing** (`MeshRefine::taubinSmooth`) — λ|μ alternating Laplacian
+   (λ=0.5, μ=-0.53, 6 iterations). Removes the res³-grid stair-stepping that
+   reads as "AI blob" without the volume shrinkage of plain Laplacian.
+2. **Iso-surface reprojection** (`MeshRefine::isoProjectStep`) — one Newton step
+   per vertex toward the decoder's true zero level set, using forward-difference
+   gradients from 4 extra decoder probes per vertex (ε = half a grid cell, step
+   clamped to one cell). Restores detail the MC grid quantized away and undoes
+   residual smoothing drift. Cost: nv×4 extra decoder queries (~1 grid chunk).
+3. **Diffuse texture bake** (`MeshGenBaker`) — xatlas auto-unwrap, UV-space
+   triangle rasterization (barycentric texel → 3D surface point), per-texel
+   decoder colour queries, chart-border dilation. Output: UV0 + a real texture
+   (default 1024², atlas may grow to fit). Replaces per-vertex colour, whose
+   effective resolution was capped by MC vertex density AND which didn't
+   survive export to most viewers (rendered flat white). The baked texture
+   survives every export path (`MeshGenBuilder` saves the PNG + registers a
+   resource location; the CLI lands it next to the output mesh).
+
+Verified end-to-end on macOS: baseline (no pass) renders as a white unlit blob
+through the glb → turntable round-trip; the quality output renders textured and
+smooth. ~30 s total at res 192 + 1024² bake on an M-series laptop (338% CPU).
+
+Opt-outs: CLI `--no-smooth --no-refine --no-bake-texture --texture-size N`,
+MCP `smooth/refine/bake_texture/texture_size`, GUI inherits defaults.
+
+## Next: candidate upgrades (researched 2026-07, licenses verified)
+
+Ranked by (quality gain × feasibility ÷ license risk). Full license audit in
+the table below.
+
+### 1. TripoSG as a second, higher-quality geometry backend (RECOMMENDED)
+- VAST-AI `TripoSG` (SIGGRAPH 2025): **MIT code + MIT weights** (verified HF
+  card + repo LICENSE) — the only 2025-class quality jump that is fully
+  license-clean end-to-end. Same org as UniRig (#408).
+- Rectified-flow DiT (1.5B) + SDF VAE. Architecture maps onto our existing
+  ONNX pattern: DINOv2 image conditioning (export as one graph), the DiT step
+  as a second graph driven by a C++ flow loop (we already hand-roll UniRig's
+  autoregressive decode), and a query-points→SDF cross-attention decoder that
+  is nearly identical to our chunked TripoSR decode. Our MC already handles
+  SDF fields (inside-positive, iso 0).
+- Reported quality ≈ commercial Tripo 2.0 (Normal-FID 5.81 vs ~20 for
+  TripoSR-class LRMs). Geometry only → reuse this branch's bake for colour...
+  but TripoSG has no colour decoder, so texture comes from input-image
+  projection (see 3) or a texture model.
+- Cost: ~3 GB fp16 download (int8-quantize like the TripoSR tiers), minutes of
+  CPU inference (expose a steps knob; rectified flow tolerates few steps).
+  No community ONNX export exists — `scripts/export-triposg-onnx.py` is an
+  export effort comparable to the UniRig one (3 graphs + flow loop).
+- UX: `--backend triposr|triposg` (keep TripoSR as the fast/preview tier),
+  mirroring the fp32/int8 tier picker.
+
+### 2. Cheap wins still on the table for the TripoSR path
+- **Real-ESRGAN upscale of the baked texture** (infra already shipped, #405):
+  bake at 1024 → upscale 2× → sharper texture for ~8 s extra. One flag + one
+  call into `TextureUpscaler`.
+- **Input-image front-projection blend**: for texels whose surface normal faces
+  the input camera, blend the actual input pixels over the decoder colour
+  (weight = normal·view). Recovers photo-crisp detail on the front. Needs the
+  predictor-space camera convention calibrated once (render a known mesh,
+  compare projections; TripoSR's training camera is not exported with the
+  ONNX graphs).
+- **Higher default MC resolution for final exports** (256 → 320/384) now that
+  smoothing+reprojection hide grid artifacts; scale texel density with it.
+
+### 3. Rejected / parked (license or feasibility)
+
+| Model | Verdict |
+|---|---|
+| TRELLIS / TRELLIS.2-4B (MS, MIT) | Best open quality but 4B CPU-hostile, sparse attention has no clean ONNX path, and the texture stage depends on **nvdiffrast (NVIDIA non-commercial)**. Park until someone strips the NC deps (Hi3DGen proved it's possible for geometry). |
+| Hunyuan3D-2.x (Tencent) | Community license **excludes EU/UK/South Korea** + MAU cap → fails redistribution bar. |
+| SPAR3D / SF3D (Stability) | Community license revenue cap → rejected (same as #764 spike). |
+| InstantMesh (Apache) | Pipeline requires Zero123++ weights (**CC-BY-NC**) → rejected. |
+| MeshAnything, CraftsMan | NC / AGPL-tainted weights → rejected. |
+| Fine-tune TripoSG on CC-subset Objaverse (~740K permissive objects) | Feasible (PartCrafter fine-tuned the DiT only) but weeks of GPU work; only worth it for domain specialization later. |
+
+## What Meshy/Tripo actually do differently
+Multi-stage native-3D pipelines: big geometry diffusion (quad topology, part
+segmentation) + a separate multi-view **PBR texture diffusion** stage
+(albedo/normal/roughness/metallic) + retopo/UV post-stages. Open models match
+the geometry of roughly one commercial generation back (TripoSG ≈ Tripo 2.0);
+the durable gaps are texture/PBR quality and quad retopo — and the project
+already has PBRify map synthesis (#404) and QuadRetopo (#401) to chain onto
+generated meshes (`qtmesh material --texture gen_diffuse.png --generate-pbr`,
+`qtmesh retopo`).

qml/PropertiesPanel.qml

@@ -1498,10 +1498,18 @@ Rectangle {
         id: meshGenToolsComponent
 
         Column {
+            id: mgRoot
             width: parent ? parent.width : 200
             padding: 8
             spacing: 6
 
+            // Per-step progress state (see the step list below). `mgSteps` is
+            // built from the enabled checkboxes when Generate is clicked, so
+            // the list mirrors exactly the stages that will run.
+            property var mgSteps: []
+            property int mgActiveIdx: -1
+            property real mgActiveProgress: -1   // 0..1; < 0 → indeterminate
+
             // A small local button factory (raw QML — the Themed* wrappers blank
             // this dynamically-loaded panel, so we style raw controls with the
             // PropertiesPanelController palette to match the Inspector).
@@ -1545,6 +1553,45 @@ Rectangle {
                 }
             }
 
+            // Inspector-styled CheckBox (flat 16px box + checkmark, palette
+            // colors) — one factory for the pipeline-stage toggles below,
+            // matching the ThemedCheckBox look without the wrapper that breaks
+            // this dynamically-loaded panel.
+            component InspectorCheck: CheckBox {
+                id: icRoot
+                spacing: 6
+                enabled: !MeshGenController.busy
+                indicator: Rectangle {
+                    x: icRoot.leftPadding
+                    y: icRoot.height / 2 - height / 2
+                    implicitWidth: 16
+                    implicitHeight: 16
+                    radius: 2
+                    color: icRoot.checked
+                        ? PropertiesPanelController.highlightColor
+                        : PropertiesPanelController.inputColor
+                    border.color: PropertiesPanelController.borderColor
+                    border.width: 1
+                    opacity: icRoot.enabled ? 1.0 : 0.45
+                    Text {
+                        anchors.centerIn: parent
+                        visible: icRoot.checked
+                        text: "✓"
+                        color: PropertiesPanelController.textColor
+                        font.pixelSize: 12
+                        font.bold: true
+                    }
+                }
+                contentItem: Text {
+                    text: icRoot.text
+                    color: PropertiesPanelController.textColor
+                    font.pixelSize: 11
+                    leftPadding: icRoot.indicator.width + icRoot.spacing
+                    verticalAlignment: Text.AlignVCenter
+                    opacity: icRoot.enabled ? 1.0 : 0.45
+                }
+            }
+
             // Inspector-styled ComboBox (raw ComboBox re-skinned with the
             // PropertiesPanelController palette — same look as ThemedComboBox, but
             // inlined because the Themed* wrappers blank this dynamically-loaded
@@ -1706,63 +1753,148 @@ Rectangle {
                 }
             }
 
-            // Remove-background toggle — styled to match the Inspector (flat 16px
-            // box + checkmark, PropertiesPanelController palette), matching the
-            // ThemedCheckBox look without the wrapper that breaks this panel.
-            CheckBox {
+            // ---- User-selectable pipeline stages -------------------------------
+            // Each toggle maps 1:1 to a stage of the generation pipeline (see
+            // MeshGenController::generateSelected). Defaults = the polished
+            // pipeline: smooth + refine + bake + PBR maps; upscale opt-in.
+            InspectorCheck {
                 id: mgRemoveBg
                 text: "Remove background"
                 checked: true
-                enabled: !MeshGenController.busy
-                spacing: 6
-                indicator: Rectangle {
-                    x: mgRemoveBg.leftPadding
-                    y: mgRemoveBg.height / 2 - height / 2
-                    implicitWidth: 16
-                    implicitHeight: 16
-                    radius: 2
-                    color: mgRemoveBg.checked
-                        ? PropertiesPanelController.highlightColor
-                        : PropertiesPanelController.inputColor
-                    border.color: PropertiesPanelController.borderColor
-                    border.width: 1
-                    opacity: mgRemoveBg.enabled ? 1.0 : 0.45
-                    Text {
-                        anchors.centerIn: parent
-                        visible: mgRemoveBg.checked
-                        text: "✓"
-                        color: PropertiesPanelController.textColor
-                        font.pixelSize: 12
-                        font.bold: true
-                    }
-                }
-                contentItem: Text {
-                    text: mgRemoveBg.text
-                    color: PropertiesPanelController.textColor
-                    font.pixelSize: 11
-                    leftPadding: mgRemoveBg.indicator.width + mgRemoveBg.spacing
-                    verticalAlignment: Text.AlignVCenter
-                }
+            }
+            InspectorCheck {
+                id: mgSmooth
+                text: "Smooth mesh (Taubin)"
+                checked: true
+            }
+            InspectorCheck {
+                id: mgRefine
+                text: "Refine surface (re-project)"
+                checked: true
+            }
+            InspectorCheck {
+                id: mgBake
+                text: "Bake diffuse texture"
+                checked: true
+            }
+            InspectorCheck {
+                id: mgPbr
+                text: "Generate PBR maps (normal + roughness)"
+                checked: true
+                enabled: !MeshGenController.busy && mgBake.checked
+            }
+            InspectorCheck {
+                id: mgUpscale
+                text: "Upscale texture 2× (Real-ESRGAN)"
+                checked: false
+                enabled: !MeshGenController.busy && mgBake.checked
             }
 
             // Step 2: generate from the selected image. Disabled until one is
-            // picked (or while busy).
+            // picked (or while busy). Builds the per-step progress list from
+            // the enabled stages before kicking off.
             InspectorButton {
                 text: "Generate 3D"
                 clickEnabled: !MeshGenController.busy
                     && MeshGenController.selectedImagePath.length > 0
-                onClicked: MeshGenController.generateSelected(
-                    mgResCombo.resValue, mgRemoveBg.checked, mgQualityCombo.currentIndex)
-            }
-
-            // Progress bar (only while busy)
-            ProgressBar {
-                id: mgProgress
+                onClicked: {
+                    var steps = [{ key: "prep", label: "Prepare models" }]
+                    if (mgRemoveBg.checked)
+                        steps.push({ key: "background", label: "Remove background" })
+                    steps.push({ key: "encode", label: "Encode image" })
+                    steps.push({ key: "decode", label: "Reconstruct 3D" })
+                    if (mgRefine.checked)
+                        steps.push({ key: "refine", label: "Refine surface" })
+                    if (mgBake.checked)
+                        steps.push({ key: "bake", label: "Bake texture" })
+                    else
+                        steps.push({ key: "color", label: "Vertex colors" })
+                    if (mgUpscale.checked && mgBake.checked)
+                        steps.push({ key: "upscale", label: "Upscale texture 2×" })
+                    steps.push({ key: "build",
+                                 label: (mgPbr.checked && mgBake.checked)
+                                        ? "Build mesh + PBR maps" : "Build mesh" })
+                    mgRoot.mgSteps = steps
+                    mgRoot.mgActiveIdx = 0
+                    mgRoot.mgActiveProgress = -1
+
+                    MeshGenController.generateSelected(
+                        mgResCombo.resValue, mgRemoveBg.checked, mgQualityCombo.currentIndex,
+                        {
+                            "smooth": mgSmooth.checked,
+                            "refine": mgRefine.checked,
+                            "bake_texture": mgBake.checked,
+                            "generate_pbr": mgPbr.checked,
+                            "upscale_texture": mgUpscale.checked
+                        })
+                }
+            }
+
+            // Per-step progress list (only while busy): every selected stage
+            // gets its own row — ✓ when done, a live bar while active, dimmed
+            // while pending — so it's always clear WHICH phase is running.
+            Column {
                 width: parent.width - 16
-                visible: MeshGenController.busy
-                from: 0; to: 1
-                indeterminate: value <= 0
-                value: 0
+                spacing: 3
+                visible: MeshGenController.busy && mgRoot.mgSteps.length > 0
+
+                Repeater {
+                    model: mgRoot.mgSteps
+
+                    delegate: Item {
+                        required property var modelData
+                        required property int index
+                        readonly property bool stepDone: index < mgRoot.mgActiveIdx
+                        readonly property bool stepActive: index === mgRoot.mgActiveIdx
+                        width: parent ? parent.width : 200
+                        height: 18
+
+                        Text {
+                            id: stepLabel
+                            anchors.left: parent.left
+                            anchors.verticalCenter: parent.verticalCenter
+                            text: (stepDone ? "✓ " : "• ") + modelData.label
+                            color: PropertiesPanelController.textColor
+                            opacity: stepDone ? 0.9 : (stepActive ? 1.0 : 0.4)
+                            font.pixelSize: 10
+                            font.bold: stepActive
+                        }
+
+                        // Mini per-step bar: full when done, live fraction while
+                        // active (pulsing when the stage can't report a total).
+                        Rectangle {
+                            anchors.right: parent.right
+                            anchors.verticalCenter: parent.verticalCenter
+                            width: 70
+                            height: 5
+                            radius: 2
+                            color: PropertiesPanelController.inputColor
+                            border.color: PropertiesPanelController.borderColor
+                            border.width: 1
+                            Rectangle {
+                                id: stepFill
+                                anchors.left: parent.left
+                                anchors.top: parent.top
+                                anchors.bottom: parent.bottom
+                                radius: 2
+                                color: PropertiesPanelController.highlightColor
+                                width: stepDone ? parent.width
+                                     : stepActive
+                                       ? (mgRoot.mgActiveProgress >= 0
+                                          ? Math.max(3, parent.width * mgRoot.mgActiveProgress)
+                                          : parent.width)
+                                       : 0
+                                opacity: stepActive && mgRoot.mgActiveProgress < 0 ? 0.35 : 1.0
+                                SequentialAnimation on opacity {
+                                    running: stepActive && mgRoot.mgActiveProgress < 0
+                                    loops: Animation.Infinite
+                                    NumberAnimation { from: 0.2; to: 0.6; duration: 600 }
+                                    NumberAnimation { from: 0.6; to: 0.2; duration: 600 }
+                                }
+                            }
+                        }
+                    }
+                }
             }
 
             Text {
@@ -1785,14 +1917,23 @@ Rectangle {
             Connections {
                 target: MeshGenController
                 function onProgress(stage, done, total) {
-                    if (total > 0 && done >= 0) {
-                        mgProgress.indeterminate = (stage === "prep" || stage === "background")
-                        mgProgress.value = total > 0 ? (done / total) : 0
+                    // Advance the step list. Stages not in the list (e.g. the
+                    // vertex-colour fallback after a failed bake) are ignored.
+                    var idx = -1
+                    for (var i = 0; i < mgRoot.mgSteps.length; i++)
+                        if (mgRoot.mgSteps[i].key === stage) { idx = i; break }
+                    if (idx < 0)
+                        return
+                    if (idx > mgRoot.mgActiveIdx) {
+                        mgRoot.mgActiveIdx = idx
+                        mgRoot.mgActiveProgress = -1
                     }
+                    if (idx === mgRoot.mgActiveIdx)
+                        mgRoot.mgActiveProgress = total > 0 ? done / total : -1
                 }
                 function onStatusMessage(msg) { mgStatus.text = msg }
                 function onCompleted(result) {
-                    mgProgress.value = 1
+                    mgRoot.mgActiveIdx = mgRoot.mgSteps.length   // all ✓
                     mgStatus.text = "Done: " + result.vertexCount + " verts, "
                         + result.triangleCount + " tris"
                 }