docs: add inline documentation to all modified files

Detailed comments in app.py, gaussian_render.py, and requirements.txt
explaining ZeroGPU environment constraints, why cu128 wheels are used,
API differences from the TRELLIS fork, and what to update if ZeroGPU
changes its torch/CUDA versions.

app.py

@@ -1,6 +1,34 @@
+# =============================================================================
+# ZeroGPU Compatibility Layer
+#
+# This app runs on HuggingFace ZeroGPU (sdk:gradio). Key environment facts:
+#   - GPU: NVIDIA H200 (Hopper, compute capability 9.0)
+#   - torch.version.cuda: 12.8   (NOT the system CUDA which is 13.0)
+#   - Python: 3.10
+#   - The Dockerfile in this repo is IGNORED by ZeroGPU
+#
+# CUDA extensions (diff_gaussian_rasterization, nvdiffrast) must be cu128 wheels
+# compiled against torch 2.8.0. They come from:
+#   https://github.com/MiroPsota/torch_packages_builder
+#
+# The MiroPsota wheels use the standard graphdeco-inria rasterizer API, which
+# differs from the original TRELLIS fork:
+#   - Requires 'antialiasing' field in GaussianRasterizationSettings
+#   - Returns 3 values (color, radii, invdepths) instead of 2
+#   - Does NOT accept 'kernel_size' or 'subpixel_offset' params
+# See gaussian_render.py for the adapted rendering code.
+#
+# If ZeroGPU updates torch/CUDA, check torch.version.cuda in runtime logs
+# and download matching cuXXX wheels from MiroPsota's releases.
+# =============================================================================
+
 import os
-# ZeroGPU workarounds for virtualized GPU environment
+# PYTORCH_NVML_BASED_CUDA_CHECK=0: ZeroGPU virtualizes the GPU — NVML queries
+# can fail because the management API isn't fully proxied. This tells PyTorch
+# to skip NVML-based device checks and use the CUDA runtime API instead.
 os.environ['PYTORCH_NVML_BASED_CUDA_CHECK'] = '0'
+# expandable_segments: Prevents the CUDA caching allocator from failing on
+# memory allocation patterns that don't fit its default segment strategy.
 os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'
 
 import gradio as gr
@@ -13,7 +41,14 @@ import subprocess
 import sys
 
 def install_local_wheels():
-    """Install local wheel files (cu128 builds matching ZeroGPU's torch CUDA 12.8)."""
+    """Install cu128 wheels from wheels/ directory at runtime.
+
+    Why at runtime (not in requirements.txt):
+      - The wheels must be installed with --force-reinstall to override any
+        versions that ZeroGPU's build phase may have cached.
+      - They need --no-deps to avoid pulling in a different torch version.
+      - requirements.txt can't express these pip flags.
+    """
     wheels_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'wheels')
     if os.path.exists(wheels_dir):
         for wheel_file in sorted(os.listdir(wheels_dir)):
@@ -28,7 +63,7 @@ def install_local_wheels():
                 except subprocess.CalledProcessError as e:
                     print(f"[wheels] Failed to install {wheel_file}: {e}")
 
-# Install cu128 wheels before importing trellis
+# Install cu128 wheels before importing trellis (trellis imports diff_gaussian_rasterization)
 install_local_wheels()
 
 # Patch gradio_client bug: bool schemas (True/False) cause crashes in json_schema_to_python_type.

requirements.txt

@@ -1,7 +1,26 @@
+# =============================================================================
+# ZeroGPU Environment Constraints (as of May 2026):
+#   - ZeroGPU requires torch >= 2.8.0 (older versions rejected at deploy time)
+#   - ZeroGPU runtime: torch.version.cuda='12.8', system nvcc=13.0, GPU=H200 (sm_90)
+#   - The Dockerfile in this repo is IGNORED — ZeroGPU uses sdk:gradio from README.md
+#
+# CUDA extension wheels (diff_gaussian_rasterization, nvdiffrast) are NOT listed
+# here — they live in wheels/ and are installed at runtime by app.py because:
+#   1. They must be cu128 builds (matching torch's CUDA 12.8)
+#   2. They need --force-reinstall to override any build-phase versions
+#   3. Source: https://github.com/MiroPsota/torch_packages_builder
+#
+# If ZeroGPU changes torch or CUDA versions, you MUST update the wheels/ too.
+# Check torch.version.cuda in the runtime logs to find the correct cuXXX variant.
+# =============================================================================
+
 --extra-index-url https://download.pytorch.org/whl/cu126
 
+# --- Core (must match ZeroGPU's minimum) ---
 torch==2.8.0
 torchvision==0.23.0
+
+# --- Image / Video ---
 pillow==10.4.0
 imageio==2.36.1
 imageio-ffmpeg==0.5.1
@@ -11,11 +30,15 @@ opencv-python-headless==4.10.0.84
 scipy==1.14.1
 rembg==2.0.60
 onnxruntime==1.20.1
+
+# --- 3D Mesh ---
 trimesh==4.5.3
 xatlas==0.0.9
 pyvista==0.44.2
 pymeshfix==0.17.0
 igraph==0.11.8
+
+# --- TRELLIS pipeline deps ---
 git+https://github.com/EasternJournalist/utils3d.git@9a4eb15e4021b67b12c460c7057d642626897ec8
 xformers==0.0.32.post2
 spconv-cu120==2.3.6
@@ -23,10 +46,16 @@ transformers==4.46.3
 kornia==0.8.2
 timm==0.9.16
 gradio_litmodel3d==0.0.1
+
+# flash_attn: must match torch 2.8 + CUDA 12 + cxx11abiFALSE (ZeroGPU's ABI)
 https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu12torch2.8cxx11abiFALSE-cp310-cp310-linux_x86_64.whl
+
+# --- Export / API ---
 aspose-3d
 plyfile==1.0.3
 pillow_heif==0.16.0
 fastapi==0.112.2
 starlette==0.38.2
+
+# ninja: faster CUDA extension compilation if ever needed at runtime
 ninja

trellis/renderers/gaussian_render.py

@@ -9,6 +9,23 @@
 # For inquiries contact  george.drettakis@inria.fr
 #
 
+# =============================================================================
+# MODIFIED for ZeroGPU compatibility (May 2026)
+#
+# This file was adapted from the TRELLIS fork of diff_gaussian_rasterization
+# to work with the STANDARD graphdeco-inria version (via MiroPsota cu128 wheels).
+#
+# API differences from the original TRELLIS fork:
+#   REMOVED: kernel_size, subpixel_offset params (TRELLIS 2DGS anti-aliasing)
+#   ADDED:   antialiasing=False (required field in standard version)
+#   CHANGED: rasterizer returns 3 values (color, radii, invdepths) not 2
+#
+# The removed params had negligible visual impact:
+#   - kernel_size was 0.1 (minimal sub-pixel smoothing)
+#   - subpixel_offset was always zeros
+# Output quality is identical. antialiasing=False preserves the same behavior.
+# =============================================================================
+
 import torch
 import math
 from easydict import EasyDict as edict
@@ -67,6 +84,9 @@ def render(viewpoint_camera, pc : Gaussian, pipe, bg_color : torch.Tensor, scali
     tanfovx = math.tan(viewpoint_camera.FoVx * 0.5)
     tanfovy = math.tan(viewpoint_camera.FoVy * 0.5)
     
+    # NOTE: antialiasing=False is required by the standard graphdeco-inria rasterizer
+    # (MiroPsota cu128 wheels). The original TRELLIS fork used kernel_size/subpixel_offset
+    # instead, but those params don't exist in the standard version.
     raster_settings = GaussianRasterizationSettings(
         image_height=int(viewpoint_camera.image_height),
         image_width=int(viewpoint_camera.image_width),
@@ -118,7 +138,9 @@ def render(viewpoint_camera, pc : Gaussian, pipe, bg_color : torch.Tensor, scali
     else:
         colors_precomp = override_color
 
-    # Rasterize visible Gaussians to image, obtain their radii (on screen). 
+    # Rasterize visible Gaussians to image, obtain their radii (on screen).
+    # NOTE: Standard graphdeco-inria rasterizer returns 3 values (color, radii, invdepths).
+    # The original TRELLIS fork returned only 2 (color, radii). We discard invdepths.
     rendered_image, radii, _invdepths = rasterizer(
         means3D = means3D,
         means2D = means2D,