> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Point Cloud Rendering

> Octree spatial indexing, chunked loading, and background workers for large point clouds

Avala's point cloud rendering pipeline is built to handle datasets with millions of points while maintaining interactive frame rates. It combines octree spatial indexing, chunk-based streaming, background workers for off-main-thread computation, and GPU-accelerated spatial queries to deliver responsive visualization at scale.

## Architecture Overview

```
Raw Point Cloud Data
        |
        v
  Chunk-Based Loading (streaming)
        |
        v
  Background Workers (Squadron)
        |
        v
  Octree Construction (spatial index)
        |
        v
  Frustum Culling + LOD Selection
        |
        v
  GPU Rendering (WebGPU or WebGL)
```

## Octree Spatial Indexing

The point cloud is organized into an octree -- a hierarchical tree structure that recursively subdivides 3D space into eight octants. Each node in the tree represents a cubic region of space and contains either child nodes (for internal nodes) or point data (for leaf nodes).

### How It Works

1. **Root node** -- Encompasses the full bounding box of the point cloud
2. **Subdivision** -- Each node that exceeds a point threshold is split into eight children, each covering one octant of the parent's space
3. **Leaf storage** -- Points are stored at leaf nodes, grouped by spatial proximity
4. **Level-of-detail hierarchy** -- Each internal node stores a representative subset of its children's points, enabling multi-resolution rendering

### Benefits

| Feature              | Benefit                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| Spatial locality     | Points near each other in 3D are stored near each other in memory, improving cache performance |
| Hierarchical culling | Entire branches of the tree can be skipped when their bounding box is outside the view frustum |
| Level of detail      | Internal nodes provide progressively coarser representations, enabling smooth LOD transitions  |
| Spatial queries      | Nearest-neighbor and range queries run in O(log n) rather than O(n)                            |

## Chunk-Based Loading

Rather than loading the entire point cloud into memory at once, the viewer streams data in chunks. This enables visualization to begin immediately while remaining data loads in the background.

<Steps>
  <Step title="Initial load">
    The viewer loads metadata and the first chunk of points, which typically covers the area around the initial camera position.
  </Step>

  <Step title="Octree construction begins">
    A background worker begins building the octree as chunks arrive. The tree grows incrementally as new data is ingested.
  </Step>

  <Step title="Progressive refinement">
    As more chunks load, the octree fills in and the rendered scene gains detail. The viewer displays whatever data is available at each frame.
  </Step>

  <Step title="Full resolution">
    Once all chunks have loaded and the octree is complete, the full-resolution point cloud is available for rendering and spatial queries.
  </Step>
</Steps>

<Tip>
  Chunk-based loading means you can begin exploring a point cloud immediately after opening it. You do not need to wait for the entire dataset to download.
</Tip>

## Background Workers

Heavy computation runs in background threads using Squadron workers, keeping the main rendering thread responsive. Two primary workers handle point cloud processing:

| Worker                      | Responsibility                                                                                                                                 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Octree Worker**           | Constructs and updates the octree spatial index from incoming point data. Handles node subdivision, point insertion, and LOD level generation. |
| **Points Processor Worker** | Transforms, filters, and prepares point data for rendering. Handles coordinate transformations, attribute computation, and format conversion.  |

### How Workers Operate

Workers run in separate threads (Web Workers in the browser). Communication between the main thread and workers uses message passing:

1. The main thread sends a chunk of raw point data to the worker
2. The worker processes the data (builds octree nodes, transforms coordinates)
3. The worker returns the processed result to the main thread
4. The main thread uploads the result to the GPU for rendering

This architecture ensures that octree construction and point processing never block the rendering loop, even for datasets with tens of millions of points.

## GPU Spatial Queries

When WebGPU is available, spatial queries (such as frustum culling and nearest-neighbor lookups) can be accelerated on the GPU using a bounding volume hierarchy (BVH) derived from the octree structure.

### Frustum Culling

Before each frame, the viewer tests octree nodes against the camera's view frustum:

1. Start at the root node
2. Test the node's bounding box against the frustum planes
3. If the box is entirely outside the frustum, skip the node and all its children
4. If the box is entirely inside the frustum, render all points
5. If the box partially intersects the frustum, recurse into child nodes

This hierarchical test eliminates large portions of the point cloud early, before any per-point processing occurs. With GPU-accelerated culling (when `gpuFrustumCulling` is enabled), the frustum tests run in a compute shader for maximum throughput.

### Nearest-Neighbor Queries

Spatial queries like "find the closest point to this click position" use the octree to narrow the search space:

1. Identify the leaf node containing the query point
2. Search neighboring nodes within a radius
3. Return the closest match

This enables interactive point selection and snapping, even in dense point clouds.

## Level-of-Detail Rendering

The LOD system adjusts rendering detail based on distance from the camera:

| Distance | Detail Level    | Description                                          |
| -------- | --------------- | ---------------------------------------------------- |
| Near     | Full resolution | All points in the leaf nodes are rendered            |
| Mid      | Reduced         | Internal octree nodes provide a subset of points     |
| Far      | Coarse          | Higher-level nodes render representative points only |

LOD transitions are smooth -- as the camera moves, the viewer traverses deeper or shallower levels of the octree, gradually adding or removing detail. When `gpuLod` is enabled, the LOD selection logic runs on the GPU for zero CPU overhead.

<Tip>
  For very large point clouds (10M+ points), the combination of octree culling and LOD rendering keeps the rendered point count manageable regardless of the total dataset size.
</Tip>

## Performance Characteristics

| Dataset Size      | Typical Behavior                                                    |
| ----------------- | ------------------------------------------------------------------- |
| Under 1M points   | Loads fully in seconds, full resolution at all times                |
| 1M -- 10M points  | Chunk loading takes a few seconds, LOD active at distance           |
| 10M -- 50M points | Progressive loading over 10--30 seconds, aggressive LOD and culling |
| 50M+ points       | Streaming with visible progressive refinement, LOD essential        |

## Related

* [WebGPU Acceleration](/docs/visualization/rendering/webgpu-acceleration) -- GPU feature flags and compute shader details
* [Visualization Modes](/docs/visualization/rendering/visualization-modes) -- Coloring modes for point cloud data
* [Point Cloud Panel](/docs/visualization/panels/point-cloud-panel) -- Panel configuration and view controls