Project Page | Paper | Docs

hsplat-warp is a NVIDIA Warp-extended fork of hsplat for primitive-based computer-generated holography research.

The codebase still keeps the package/module path hsplat on disk for compatibility, but this fork should be understood and referenced as hsplat-warp in documentation.

Primitive-based scene content is converted into a holographic wavefront through Gaussian Wave Splatting, then propagated and encoded for computer-generated holography rendering.

• Getting Started
• Documentation
• Repository Layout
• NVIDIA Warp Backend
• Citation
• Contact

hsplat-warp emphasizes:

• safer optional acceleration paths
• better long-term maintainability for custom kernels
• stronger extensibility for future researchers building on the fast Gaussian path

Changes in this fork:

• pycolmap parser compatibility update for recent API versions (SceneManager import path replaced with Reconstruction-based loading).
• gsplat.spherical_harmonics mask-shape compatibility fix in 2DGS loading (radii from [C, N, 2] collapsed to boolean visibility mask [C, N]).
• Getting Started updates for this fork (requirements.txt workflow and recommended version combination).
• NVIDIA Warp backend added for the Gaussian naive_fast kernel path, making kernel iteration safer and easier for future researchers while preserving the original CUDA-extension path as the default-compatible option.

Naming note

• Project/fork name: hsplat-warp
• Current package/directory name: hsplat
• Reason: preserve compatibility with the upstream layout, imports, scripts, and paths

Suyeon Choi*, Brian Chao*, Jacqueline Yang, Manu Gopakumar, Gordon Wetzstein
*denotes equal contribution

git clone https://github.com/cinescope-wkr/hsplat.git
cd hsplat
git submodule update --init --recursive

Use Python 3.10+ and install dependencies required by hsplat-warp:

pip install -r requirements.txt

Optional extra tooling:

pip install -r requirements-extra.txt
mkdocs serve

Recommended version combination:

• Python 3.10
• torch 2.9.1 (CUDA 12.8 build)
• pytorch3d 0.7.9
• gsplat 1.5.3

Pinned versions in requirements.txt reflect a known working environment.

• torch (CUDA build recommended for GPU execution)
• numpy, matplotlib, imageio, tyro, rich
• pytorch3d
• trimesh (for mesh/point sampling paths)
• pycolmap (for COLMAP parser)
• gsplat (for 2DGS loading and rendering)

Optional accelerated backend:

• warp-lang for the NVIDIA Warp Gaussian kernel backend
• install with pip install -r requirements-extra.txt
• this backend is optional; the existing CUDA extension remains supported

Download Mip-NeRF 360 and NeRF synthetic, then place datasets in hsplat/data.

Place pretrained Gaussian checkpoints in hsplat/models (example path: hsplat/models/blender_default/lego/10000/ckpts/ckpt_29999.pt). Pre-optimized checkpoints are available here.

Run from the repo’s hsplat/ package directory:

cd hsplat
bash scripts/main_gws_light.sh

• README.md: concise repository overview and quick start
• docs/: MkDocs-based structured documentation for hsplat-warp
• hosted docs: cinescope-wkr.github.io/hsplat-warp

The repository is organized as follows:

• The dsplat folder contains the phase encoding function (e.g., DPAC) for the SLMs, from the complex-valued wavefront output of hsplat-warp.
• The gsplat folder contains the gsplat library.
• The hsplat folder contains the core implementation used by hsplat-warp.

The main quick-start command is shown above in Getting Started. Additional experiment scripts include:

bash scripts/main_pc.sh  # point cloud
bash scripts/main_meshes.sh  # polygon-based CGH
bash scripts/main_gws.sh  # GWS matcinhg number of primitives

hsplat-warp supports an NVIDIA Warp backend for method=naive_fast.

Why this exists:

• Improve maintainability by moving custom-kernel development closer to Python.
• Improve research extensibility by making the Gaussian fast kernel easier to modify, prototype, and compare against the legacy CUDA extension.
• Keep the integration low-risk by limiting Warp to the custom Gaussian accumulation kernel instead of rewriting the whole pipeline.

Why it matters:

• It gives future contributors a clearer path to extend the fast Gaussian renderer.
• It reduces coupling between research iteration and handwritten PyTorch C++/CUDA bindings.
• It preserves backward compatibility because the existing CUDA extension still works and remains the first choice in gaussian_backend=auto when available.

Why this is part of the fork identity:

• It is the clearest architectural distinction between upstream hsplat and hsplat-warp.

• It signals that this fork is aimed at maintainable research iteration, not only one-off reproduction.

• It gives collaborators an obvious place to add future kernel experiments without replacing the full pipeline.

• Default: gaussian_backend=auto

• Explicit backends: gaussian_backend=cuda_ext or gaussian_backend=warp

• Safety behavior: if auto is selected and neither accelerated backend is available, naive_fast falls back to naive_slow with a warning instead of crashing.

Example:

cd hsplat
python main.py --method naive_fast --gaussian-backend warp

Notes:

• Warp is only used for the custom Gaussian accumulation kernel.
• FFT propagation and most orchestration stay in PyTorch.
• gsplat is still used in data-loading paths where applicable.
• If WARP_CACHE_DIR is not set, the backend uses a writable temp cache directory by default.
• Warp installation and driver requirements follow the official installation guide.

If you find our work useful in your research, please cite:

@article{choi2025gaussian,
  title={Gaussian wave splatting for computer-generated holography},
  author={Choi, Suyeon and Chao, Brian and Yang, Jacqueline and Gopakumar, Manu and Wetzstein, Gordon},
  journal={ACM Transactions on Graphics (TOG)},
  volume={44},
  number={4},
  pages={1--13},
  year={2025},
  publisher={ACM New York, NY, USA}
}

For hsplat-warp issues, documentation, and fork-specific backend questions, please contact Jinwoo Lee.

For questions about the original paper and the upstream hsplat method, please refer to the original authors, including Suyeon Choi and Brian Chao.