| name | quality |
| description | Image quality analysis, artifact detection, convergence diagnostics, noise decomposition, and parameter corrections. Use when: diagnosing image quality problems, running ppt_diagnose, analyzing convergence, identifying bottlenecks, tuning render parameters via feedback, or comparing A/B renders. |
Quality
The ppt_diagnose executable and in-render diagnostics system.
Source Map
| Location | Files | Purpose |
|---|
src/diagnose/ | diagnose_main.cpp | ppt_diagnose entry point: loads EXR, runs analysis, prints JSON |
src/diagnose/ | image_oracle.h/.cpp | Main analysis engine: no-reference and reference-based |
src/diagnose/ | artifact_detector.h | 6 artifact types with severity scoring |
src/diagnose/ | noise_analyzer.h | Laplacian variance, spatial autocorrelation |
src/diagnose/ | image_metrics.h | PSNR, SSIM, RMSE computation |
src/diagnose/ | image_verdict.h | Verdict + ArtifactReport + Correction structs |
src/diagnose/ | diagnostics.h/.cpp | In-render convergence analysis |
src/diagnose/ | variance_tracker.h/.cpp | Per-pixel variance tracking from GPU buffers |
src/diagnose/ | convergence_analyzer.h | Convergence rate estimation (log-log fit) |
src/diagnose/ | bottleneck_report.h | Bottleneck identification + parameter recommendations |
Tool: ppt_diagnose
ppt_diagnose <render.exr> [render_log.json]
Loads rendered EXR, runs image oracle, prints JSON to stdout:
{
"quality": { "noise_level", "convergence_rate", "summary" },
"artifacts": [{ "type", "severity", "description" }],
"corrections": [{ "target", "parameter", "current", "recommended", "rationale" }]
}
Artifact Detection (6 Types)
| Type | Detection | Threshold | Correction Target |
|---|
| Firefly | Pixel > K × local median | K=3–6 (adaptive per SPP) | path-integrator (clamp), post-processing (filter) |
| Splotch | Spatial autocorrelation ρ(lag=8) > 0.15 | 0.15 | path-guide (more training iters, lower split threshold) |
| HighNoise | Laplacian variance (Immerkaer 1996) | σ > scene-dependent | guide_fraction increase, more SPP |
| EnergyLoss | Mean luminance < expected (over-clamping) | 15% deviation | raise clamping thresholds |
| Banding | Gradient quantization | histogram peaks | increase precision / dithering |
| SlowConvergence | Rate α < 0.3 in log-log fit MSE∝N^(-α) | α < 0.3 | guide, photon, or scene-specific tuning |
Convergence Analysis
- Rate α: Log-log fit of MSE vs SPP; α≈1.0 = ideal MC; α<0.3 = stalled; α>1.0 = biased
- Variance decomposition: direct% / indirect% / photon% / firefly% — bottleneck = max fraction
- Bottleneck mapping: direct>50%→NEE tuning; indirect>50%→guide tuning; photon>30%→budget; firefly>5%→filter
- Per-bounce analysis: Identifies noisiest bounce level
- SPP predictor: Given rate α and target quality, estimate SPP needed
- Convergence sweep:
photon_tracer --sweep renders at multiple SPP levels (default: 16,64,256,512,1024,2048), saves checkpoint images and a _sweep.json report with per-level noise + mean luminance. Use to diagnose noise reduction effectiveness across sample counts. See orchestrator skill for full details.
Parameter Isolation
When diagnosing artifacts or evaluating parameter changes, vary one parameter at a time. Render multiple values of that single parameter (ideally as --sweep runs), compare metrics, then lock the best value before moving to the next parameter. Changing multiple parameters simultaneously prevents attributing improvements or regressions to their cause. Only combine parameters after their individual effects are understood. See the orchestrator skill's "Single-Variable Isolation Strategy" for the full workflow.
Feedback Loop
ppt_analyze scene.pbrt > profile.json
photon_tracer --config profile.json scene.pbrt → output.exr + render_log.json
ppt_diagnose output.exr render_log.json > report.json
# Apply corrections from report.json → re-render (up to 3 iterations)
Image Metrics
- PSNR: Peak signal-to-noise ratio vs reference (dB)
- SSIM: Structural similarity index (0–1)
- RMSE: Root mean squared error
- Noise level: Normalized Laplacian variance [0–1]
