# CUDA Extensions Required for the LingBot-Map Batch Rendering Pipeline and Build Instructions

> Discover the CUDA extensions needed for the LingBot-Map batch rendering pipeline. Learn how to compile voxel_morton_ext and frustum_cull_ext from source with setuptools.

- Repository: [Robbyant/lingbot-map](https://github.com/Robbyant/lingbot-map)
- Tags: how-to-guide
- Published: 2026-07-29

---

**The LingBot-Map batch rendering pipeline requires two custom CUDA extensions—`voxel_morton_ext` for Morton-code voxel hashing and `frustum_cull_ext` for GPU frustum culling—which are compiled from `.cu` source files using the setuptools script at [`demo_render/render_cuda_ext/setup.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/render_cuda_ext/setup.py).**

The offline batch rendering system in the LingBot-Map repository relies on GPU-accelerated operations that cannot be efficiently executed through standard PyTorch operations alone. To enable high-performance spatial hashing and geometry culling, the pipeline requires two native CUDA kernels that must be compiled as Python extensions before running [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py).

## The Two Required CUDA Extensions

### voxel_morton_ext (Voxel Morton Encoding)

Located at `demo_render/render_cuda_ext/voxel_morton/voxel_morton.cu`, this extension encodes 3-D voxel coordinates into **Morton (Z-order) codes**. The resulting codes enable fast spatial hashing operations used throughout the geometry processing pipeline in the batch renderer.

### frustum_cull_ext (Frustum Culling)

Found in `demo_render/render_cuda_ext/frustum_cull/frustum_cull.cu`, this kernel performs GPU-accelerated frustum culling of point clouds. It efficiently discards points outside the camera view before rendering, significantly reducing computational overhead when processing large scenes in the batch pipeline.

## Prerequisites for Building the CUDA Extensions

Before compiling the extensions, ensure your environment meets these requirements:

- A functional CUDA toolkit installation that matches your PyTorch CUDA version (the repository recommends PyTorch 2.8.0 with CUDA 12.8)
- Standard Python build tools including `pip`, `setuptools`, and `wheel`
- The LingBot-Map repository cloned locally with the `demo_render/render_cuda_ext/` directory structure intact

## How to Build the CUDA Extensions

Navigate to the extensions directory and invoke the setuptools build command from the repository root:

```bash
cd demo_render/render_cuda_ext && \
python setup.py build_ext --inplace && \
cd ../..

```

This command compiles `voxel_morton.cu` and `frustum_cull.cu` into shared libraries within the same directory. The `--inplace` flag ensures the compiled modules (`voxel_morton_ext` and `frustum_cull_ext`) remain importable by the Python code in `rgbd_render.geometry.voxel` and `rgbd_render.geometry.culling`.

## Verifying the Installation

After successful compilation, verify the extensions by checking for compiled shared-object files and testing the imports:

```bash
ls demo_render/render_cuda_ext/*.so

```

You should observe files matching the pattern `voxel_morton_ext.cpython-311-x86_64-linux-gnu.so` and `frustum_cull_ext.cpython-311-x86_64-linux-gnu.so` (exact names vary by Python version and platform).

Test the imports in a Python REPL:

```python
from voxel_morton import voxel_morton_ext
from frustum_cull import frustum_cull_ext

```

If both imports execute without `ImportError` or CUDA-related exceptions, the extensions are correctly built and ready for the batch renderer.

## Running the Batch Rendering Pipeline

With the CUDA extensions compiled, execute the batch rendering pipeline using [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py). The following example processes an indoor walkthrough video:

```bash
python demo_render/batch_demo.py \
    --video_path /data/demo_videos/indoor_travel.MP4 \
    --output_folder /data/outputs/indoor_travel/ \
    --model_path /path/to/lingbot-map.pt \
    --config demo_render/config/indoor.yaml \
    --mode windowed --window_size 128 \
    --keyframe_interval 10 --overlap_keyframes 8 \
    --sky_mask_dir /data/outputs/sky_masks \
    --sky_mask_visualization_dir /data/outputs/sky_mask_viz \
    --camera_vis default --keyframes_only_points \
    --frame_tag --frame_tag_position top_right \
    --save_predictions

```

## Summary

- The LingBot-Map batch rendering pipeline requires two specific CUDA extensions: `voxel_morton_ext` for spatial hashing and `frustum_cull_ext` for view-frustum culling.
- Source files reside in `demo_render/render_cuda_ext/voxel_morton/voxel_morton.cu` and `demo_render/render_cuda_ext/frustum_cull/frustum_cull.cu`.
- Build both extensions using `python setup.py build_ext --inplace` from within the `demo_render/render_cuda_ext` directory.
- Successful compilation produces `.so` files that enable importable Python modules used by [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py).
- The extensions represent the only native CUDA components required; the remaining pipeline operates through PyTorch, FlashInfer, and Kaolin.

## Frequently Asked Questions

### What CUDA toolkit version is required for LingBot-Map?

The repository recommends PyTorch 2.8.0 paired with CUDA 12.8. Your installed CUDA toolkit must match the CUDA version of your PyTorch installation to ensure binary compatibility during the extension build process.

### Can I run the batch rendering pipeline without building these CUDA extensions?

No. The [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) entry point explicitly imports `voxel_morton_ext` and `frustum_cull_ext` through the `rgbd_render.geometry` submodules. Without these compiled extensions, the pipeline raises `ModuleNotFoundError` upon initialization.

### Where are the compiled extension files located after building?

The [`setup.py`](https://github.com/Robbyant/lingbot-map/blob/main/setup.py) script places the compiled shared-object files (e.g., `voxel_morton_ext.cpython-311-x86_64-linux-gnu.so`) directly inside `demo_render/render_cuda_ext/` when using the `--inplace` flag. These files must remain in this location for the relative imports within `rgbd_render` to function correctly.

### Do I need to rebuild the extensions if I update PyTorch?

Yes. CUDA extensions are compiled against specific PyTorch and CUDA versions. Upgrading either component requires rerunning the build command `python setup.py build_ext --inplace` to ensure ABI compatibility and prevent segmentation faults or undefined symbol errors.