# LingBot-Map CUDA Extensions Explained: voxel_morton_ext and frustum_cull_ext in the Render Pipeline

> Understand LingBot-Map CUDA extensions voxel_morton_ext and frustum_cull_ext accelerate point-cloud rendering with GPU Morton encoding and frustum culling. Optimize your pipeline.

- Repository: [Robbyant/lingbot-map](https://github.com/Robbyant/lingbot-map)
- Tags: internals
- Published: 2026-07-31

---

**The `voxel_morton_ext` and `frustum_cull_ext` CUDA extensions accelerate LingBot-Map's point-cloud rendering pipeline by performing GPU-based Morton encoding for spatial indexing and real-time frustum culling to discard invisible points before rasterization.**

LingBot-Map leverages custom CUDA kernels to handle millions of points in real time when rendering dense 3D reconstructions. These CUDA extension dependencies—compiled as shared libraries and loaded through PyTorch's `torch.ops` interface—delegate heavy-weight spatial operations to the GPU, enabling hierarchical level-of-detail selection and efficient visibility testing. By offloading Morton encoding and view-frustum culling to CUDA, the pipeline keeps memory usage low and ensures only relevant geometry reaches the rasterization stage.

## What Are the voxel_morton_ext and frustum_cull_ext Extensions?

The LingBot-Map repository includes two specialized CUDA extensions packaged within the `render_cuda_ext` module:

- **`voxel_morton_ext`**: Converts 3D coordinates into Morton (Z-order) space-filling curves for fast spatial sorting and voxel-based neighbor queries.
- **`frustum_cull_ext`**: Performs GPU-accelerated geometric culling to filter point clouds against camera view frustums before projection.

Both extensions are implemented as `.cu` CUDA kernels with PyTorch C++ bindings, allowing Python code to invoke high-performance GPU routines directly without intermediate data copying.

## voxel_morton_ext: Morton Encoding for Spatial Indexing

### Purpose and Technical Implementation

The `voxel_morton_ext` extension generates **Morton codes** (also known as Z-order codes) from 3D point coordinates. These codes map 3D spatial positions to a 1D space-filling curve, preserving locality such that points close in 3D space remain close in the encoded 1D array. According to the LingBot-Map source code, this encoding enables rapid voxel-based neighbor queries and spatial hashing required for octree construction.

The extension exposes functions such as `voxelmorton.encode`, which accepts NumPy arrays or tensors of 3D points and returns 64-bit Morton codes suitable for GPU sorting algorithms.

### Role in the Render Pipeline

In the render pipeline, Morton encoding serves three critical functions:

1. **Octree Hierarchy Construction**: By sorting points according to their Morton codes, the system builds hierarchical spatial data structures that support level-of-detail (LOD) selection.
2. **Spatial Sorting**: The Z-order curve ensures cache-friendly memory access patterns when traversing neighboring voxels during surface reconstruction.
3. **Fast Lookup**: Encoded indices allow constant-time retrieval of voxel neighbors without expensive 3D distance calculations.

```python

# Octree construction workflow using voxel_morton_ext

morton_codes = voxelmorton.encode(points.cpu().numpy())
sorted_idx = np.argsort(morton_codes)
points = points[sorted_idx]  # Spatially sorted for cache efficiency

```

## frustum_cull_ext: GPU-Accelerated View Frustum Culling

### Geometric Culling Implementation

The `frustum_cull_ext` extension implements a CUDA kernel that tests each point against the six planes of a camera's view frustum. Points lying outside the frustum or behind the near clipping plane are flagged for removal before any projection operations occur. The kernel is exposed to Python as `render_cuda_ext.frustum_cull` and is defined in `preprocess/points_visibility/frustum_cull.cu`.

The implementation performs per-point visibility tests using camera intrinsics (`fx`, `fy`, `cx`, `cy`) and extrinsics (`R_t`, `t_t`), comparing depths against configurable `near` and `far` planes (defaulting to 0.1 and 200.0 meters).

### Integration with the Render Pipeline

Frustum culling reduces GPU memory bandwidth and computational load by filtering invisible geometry at the earliest possible stage. The pipeline invokes this extension in two contexts:

**Preprocessing Stage**: In [`preprocess/oxford.py`](https://github.com/Robbyant/lingbot-map/blob/main/preprocess/oxford.py), the extension culls static point clouds against individual camera frames before depth-map generation.

**Runtime Rendering**: The [`demo_render/rgbd_render/geometry/culling.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/rgbd_render/geometry/culling.py) module calls the extension dynamically to cull points on-the-fly during interactive rendering.

```python

# preprocess/oxford.py - Preprocessing visibility check

depth_map, winner_map = _vis_ext.frustum_cull(
    pts_t, R_t, t_t, fx, fy, cx, cy, W, H, near=0.1, far=200.0
)

```

The function returns a depth map and winner map (indicating which points survived the cull) that feed directly into subsequent texture projection and shading stages without Python-level loops.

## Key Source Files and Implementation Details

The CUDA extensions are implemented across several files in the repository:

- **`preprocess/points_visibility/frustum_cull.cu`**: Contains the CUDA kernel implementing fast frustum plane calculations and point-inclusion tests.
- **[`preprocess/points_visibility/visibility.cpp`](https://github.com/Robbyant/lingbot-map/blob/main/preprocess/points_visibility/visibility.cpp)**: Registers the `frustum_cull` function with PyTorch's operator library, bridging C++ and Python.
- **[`preprocess/oxford.py`](https://github.com/Robbyant/lingbot-map/blob/main/preprocess/oxford.py)**: High-level Python wrapper that orchestrates batch frustum culling during dataset preparation.
- **[`demo_render/rgbd_render/geometry/culling.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/rgbd_render/geometry/culling.py)**: Runtime geometry processor that invokes culling for live rendering.
- **`render_cuda_ext`**: The compiled shared library (`.so`) that exports both `voxel_morton_ext` and `frustum_cull_ext` symbols, loaded automatically when importing the LingBot-Map renderer.

Both extensions require a CUDA-capable GPU and are compiled using PyTorch's JIT extension loader or setuptools, linking against the PyTorch C++ API.

## Summary

- **`voxel_morton_ext`** accelerates spatial indexing by converting 3D coordinates to Morton codes, enabling efficient octree construction and cache-friendly neighbor queries during surface reconstruction.
- **`frustum_cull_ext`** eliminates invisible geometry through GPU-accelerated view frustum testing, significantly reducing data transfer to the rasterizer and improving real-time rendering performance.
- Both extensions are accessed via the `render_cuda_ext` module, with bindings defined in [`preprocess/points_visibility/visibility.cpp`](https://github.com/Robbyant/lingbot-map/blob/main/preprocess/points_visibility/visibility.cpp) and kernels located in `.cu` files.
- The extensions integrate at distinct pipeline stages: Morton encoding during data structure preparation, and frustum culling during both preprocessing and runtime rendering.

## Frequently Asked Questions

### What is Morton encoding and why does LingBot-Map use it?

Morton encoding maps 3D coordinates to a 1D space-filling curve (Z-order) that preserves spatial locality. LingBot-Map uses this via `voxel_morton_ext` to sort point clouds spatially, which accelerates octree construction and enables hierarchical level-of-detail selection without expensive 3D distance calculations between points.

### How does frustum_cull_ext improve rendering performance?

The `frustum_cull_ext` extension filters point clouds on the GPU before they reach the rasterization stage, discarding points outside the camera's view frustum. This reduces memory bandwidth usage and ensures only visible points participate in depth-map generation and texture projection, allowing the system to handle millions of points in real time.

### Are these CUDA extensions mandatory for running LingBot-Map?

Yes. The `render_cuda_ext` module containing both `voxel_morton_ext` and `frustum_cull_ext` is required for the full rendering pipeline, particularly for real-time visualization and large-scale dataset preprocessing. The system will fail to import or run rendering commands without these compiled shared libraries.

### Where are the CUDA kernels for these extensions located?

The frustum culling CUDA kernel is located at `preprocess/points_visibility/frustum_cull.cu`, while the Morton encoding kernels reside within the `voxel_morton_ext` compilation unit (part of the same `render_cuda_ext` build target). The PyTorch bindings that expose these to Python are implemented in [`preprocess/points_visibility/visibility.cpp`](https://github.com/Robbyant/lingbot-map/blob/main/preprocess/points_visibility/visibility.cpp).