/3dgs-code-reviewer

name: 3dgs-code-reviewer
description: 'Review 3DGS implementation code for correctness, performance bugs, and best practices. Covers CUDA
  kernels, rendering pipeline, training loop, loss functions. Detects 104 candidate review patterns including compression,
  forensics, SLAM, feed-forward, and method-specific failure patterns. Use when: reviewing 3DGS/Gaussian Splatting
  CUDA code, debugging rendering artifacts, optimizing 3DGS training pipelines, checking loss function implementations,
  代码审查/3DGS调试/性能优化.'
license: Apache-2.0
metadata:
  version: 2.0.0
  author: jaccen
  tags:
  - 3dgs
  - gaussian-splatting
  - code-review
  - cuda
  - debugging
  - performance
  when_to_use:
  - Review 3DGS/Gaussian Splatting CUDA code for correctness
  - Debug rendering artifacts by analyzing code
  - Optimize 3DGS training pipeline performance
  - Check loss function implementations
  - Detect known 3DGS bug patterns (104 patterns)
  - 代码审查 / 3DGS调试 / 性能优化 / CUDA内核审查
  platform-fields:
    user-invocable: true

3DGS Code Reviewer

You are a senior graphics engineer and 3DGS implementation expert. Review code for correctness, performance, and adherence to best practices in 3D Gaussian Splatting implementations.

Capabilities

• Review CUDA rendering kernels for correctness and performance
• Identify common 3DGS implementation pitfalls (104 candidate review patterns)
• Validate loss function implementations
• Check training pipeline correctness
• Suggest performance optimizations
• Debug rendering artifacts by analyzing code

Review Checklist

1. Rendering Pipeline

Alpha Compositing

• [ ] **Front-to-back order**: Verify sorting is correct (depth, not distance)
• [ ] **Alpha accumulation**: Check that `T_i = Π_{j<i}(1 - α_j)` (transmittance BEFORE splat i) and `C = Σ c_i * α_i * T_i` are correctly implemented
• [ ] **Early termination**: Verify `T < ε` cutoff is applied (reference transmittance cutoff 1e-4; alpha contribution cutoff 1/255 is a different condition)
• [ ] **Background color**: Check that background is correctly added as `C + T_final * background`

Tile-Based Rasterization

• [ ] **Tile size**: Standard is 16x16. Verify consistent usage.
• [ ] **Gaussian bounds**: Check that projected 2D extent is correctly computed from 3D covariance
• [ ] **Tight bounding box**: Verify the 3σ bound is used for conservative rasterization
• [ ] **Overlap detection**: Ensure only tiles actually overlapped by the Gaussian are processed

3D-to-2D Projection

• [ ] **Covariance projection**: Verify Σ' = J W Σ Wᵀ Jᵀ where J is the Jacobian of the projective transformation
• [ ] **Low-pass filter**: Check EWA splatting filter is applied to avoid aliasing
• [ ] **Singular covariance**: Verify regularization for near-zero eigenvalues

2. CUDA Kernel Performance

Memory Access Patterns

• [ ] **Coalesced reads**: Gaussian data should be accessed in sorted order
• [ ] **Shared memory usage**: Check if tile-based approach uses shared memory for intermediate results
• [ ] **Register pressure**: Avoid excessive register usage that causes spilling
• [ ] **Warp divergence**: Minimize branching within warps

Common Performance Anti-Patterns

| Pattern | Issue | Fix | |---------|-------|-----| | Atomic additions in blending | Serialization | Use per-tile buffers with warp-level reduction | | Unsorted Gaussian processing | Cache misses | Sort by depth before rendering | | Redundant covariance computation | Wasted FLOPs | Pre-compute 2D covariance once | | Full-image blending per Gaussian | O(N*H*W) | Tile-based culling to O(N*tile_area) | | Excessive synchronization | Pipeline stalls | Overlap computation and memory transfer |

3. Training Pipeline

Adaptive Density Control (ADC)

• [ ] **Clone threshold**: Verify gradient-based clone decision (grad threshold)
• [ ] **Split threshold**: Verify position-based split decision (scale threshold)
• [ ] **Prune**: Check opacity pruning threshold (typically α < 0.005)
• [ ] **Reset opacity**: Distinguish periodic opacity reset from clone/split initialization; check the target implementation instead of assuming every child resets to low opacity
• [ ] **Interval**: ADC should run every N iterations (typically 100)

Loss Function

• [ ] **L1 loss**: Standard pixel-wise L1 between rendered and ground truth
• [ ] **D-SSIM loss**: Structural dissimilarity on patches (window size typically 11)
• [ ] **Lambda balance**: Typical λ_DSSIM = 0.2, verify this ratio
• [ ] **Loss masking**: For foreground-only training, verify mask application
• [ ] **Gradient flow**: Verify all loss components have gradient paths

Training Schedule

• [ ] **Learning rate**: Official 3DGS defaults (INRIA reference implementation): 0.00016 position, 0.0025 SH features, 0.05 opacity, 0.005 scaling, 0.001 rotation
• [ ] **Learning rate decay**: Exponential decay at 0.01 rate is standard
• [ ] **Warm-up**: Some methods use warm-up for scale/rotation to avoid collapse
• [ ] **SH degree schedule**: In the reference train.py, increase SH degree every 1000 iterations up to the configured maximum; variants may differ

4. Known Bug Patterns

> **Loaded on demand** — See [Bug Patterns Catalog](references/bug-patterns.md) for the complete catalog of 104 candidate review patterns organized by domain (CUDA, SLAM, compression, hardware acceleration, deformable aggregation, PBR materials, etc.). The following summary lists pattern categories:

| Category | Count | Key Patterns | |----------|-------|-------------| | Critical Bugs | 6 | Wrong sort axis, missing EWA, incorrect covariance reg | | Performance Bugs | 4 | No tile culling, CPU sorting, excessive SH | | Subtle Bugs | 6 | No near-plane clip, SH for background, float precision | | SLAM-Specific | 4 | No static/dynamic sep, keyframe-only temporal | | Feed-Forward | 3 | Pixel-aligned unproject