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

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.

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.

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:

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:

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:

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. The following example processes an indoor walkthrough video:

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.
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}