# Camera Head Refinement and camera_num_iterations in LingBot-Map: Performance Impact Explained

> Discover the performance impact of camera head refinement and camera_num_iterations in LingBot-Map. Reduce iterations for 4x faster inference with minimal accuracy loss.

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

---

**Reducing `camera_num_iterations` from the default value of 4 to 1 yields approximately 4× faster inference in LingBot-Map while incurring a modest pose accuracy trade-off of typically less than 2 cm or 1 degree.**

LingBot-Map employs an iterative **CameraHead** module to refine camera pose predictions progressively. The `--camera_num_iterations` parameter (also accessible as `camera_num_iterations` in the Python API) directly controls the number of refinement passes, creating a tunable balance between computational latency and localization precision for robotic and augmented reality applications.

## How Camera Head Refinement Works

The **CameraHead** class, implemented in [`lingbot_map/heads/camera_head.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/heads/camera_head.py), performs iterative refinement of camera poses through repeated application of transformer blocks. Each iteration pass feeds intermediate representations back through the same architectural components to progressively reduce pose estimation errors. The `num_iterations` argument (lines 84-102 in [`camera_head.py`](https://github.com/Robbyant/lingbot-map/blob/main/camera_head.py)) initializes this loop, with the model storing intermediate activations in a KV-cache that scales proportionally with the iteration count.

## Performance Impact of camera_num_iterations

Adjusting the iteration count produces linear scaling effects on inference speed, memory consumption, and pose accuracy.

### Speed vs. Accuracy Trade-offs

The following configuration matrix illustrates the empirical performance characteristics observed in the LingBot-Map benchmark suite:

- **1 iteration**: Approximately 4× faster inference than default; cache shrinks by roughly 4×; introduces a small drop in pose precision (typically < 2 cm translation error or < 1° rotation error)
- **2–3 iterations**: Intermediate speed-accuracy balance; gradual improvement in pose estimates with proportional cache growth
- **4 iterations (default)**: Baseline inference speed; achieves highest pose accuracy; utilizes full KV-cache allocation as defined in [`lingbot_map/models/gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window_v2.py) (lines 232-235)

### KV-Cache Memory Implications

Each refinement iteration retains key-value tensors in the transformer cache. Consequently, reducing `camera_num_iterations` from 4 to 1 reduces the KV-cache memory footprint by approximately 75%, enabling deployment on memory-constrained devices such as mobile robots or AR headsets.

## Configuring camera_num_iterations in Practice

Users can modify the refinement depth through either command-line interfaces or direct API instantiation.

### Command-Line Interface

The [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) and [`benchmark/gct_profile.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/gct_profile.py) scripts expose the `--camera_num_iterations` flag (documented at lines 234-235 in [`gct_profile.py`](https://github.com/Robbyant/lingbot-map/blob/main/gct_profile.py)) for rapid experimentation:

```bash
python demo.py \
  --data_path /path/to/sequence \
  --camera_num_iterations 1

```

Setting this value to `1` invokes the 4× speedup configuration suitable for real-time SLAM applications.

### Python API Integration

When instantiating the model programmatically via `GCTStreamWindowV2` in [`lingbot_map/models/gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window_v2.py), pass the integer directly to the constructor:

```python
from lingbot_map.models.gct_stream_window_v2 import GCTStreamWindowV2

model = GCTStreamWindowV2(
    camera_num_iterations=2,  # Faster than default, reasonable accuracy

    # … other arguments …

)

poses = model.predict(video_frames)

```

### Benchmarking the Trade-off

To empirically measure the latency-accuracy relationship for your specific hardware, implement a timed evaluation loop:

```python
import time
import numpy as np

def benchmark(iterations, frames):
    model = GCTStreamWindowV2(camera_num_iterations=iterations)
    start = time.time()
    poses = model.predict(frames)
    elapsed = time.time() - start
    return elapsed, poses

for it in [1, 2, 4]:
    t, poses = benchmark(it, video_frames)
    print(f"Iterations={it}: {t:.2f}s inference time")

```

## Implementation Details

The default value of **4** refinement steps is hardcoded in [`gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/gct_stream_window_v2.py) as the initialization parameter for the `CameraHead` instance. The source code documentation explicitly notes that "lower = faster inference," guiding users toward the 1-iteration configuration for latency-critical deployments. The `CameraHead` class processes these iterations sequentially within its forward method, reusing the same transformer weights but accumulating context in the KV-cache across passes.

## Summary

- **Camera head refinement** in LingBot-Map iteratively improves pose estimates through repeated transformer passes controlled by `camera_num_iterations`.
- **Default configuration** (4 iterations) provides maximum accuracy but highest computational cost and memory usage.
- **Single iteration** (value of 1) delivers approximately 4× speedup with minimal accuracy degradation (< 2 cm / 1°), ideal for real-time applications.
- **KV-cache memory** scales linearly with iteration count, making lower values essential for edge deployment.
- **Configuration** is accessible via both CLI flags (`--camera_num_iterations`) and the Python API (`camera_num_iterations` parameter in `GCTStreamWindowV2`).

## Frequently Asked Questions

### What is the default value of camera_num_iterations in LingBot-Map?

The default value is **4**, as specified in the `GCTStreamWindowV2` model definition at lines 232-235 of [`lingbot_map/models/gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window_v2.py). This default provides the highest pose accuracy at the cost of maximum computational overhead and KV-cache allocation.

### How much faster is inference with camera_num_iterations set to 1?

Setting `camera_num_iterations` to **1** yields approximately **4× faster inference** compared to the default setting of 4. This speedup results from eliminating three transformer block repetitions and reducing the KV-cache size by roughly 75%, though it introduces a small accuracy penalty of typically less than 2 cm or 1 degree in pose estimation.

### Does reducing camera_num_iterations affect memory usage?

Yes, memory consumption scales directly with the iteration count. Each refinement pass stores intermediate activations in the KV-cache, so reducing the parameter from 4 to 1 decreases the cache size by approximately **4×**. This memory reduction is critical for deploying LingBot-Map on resource-constrained devices such as mobile robots or AR headsets.

### When should I use fewer than 4 camera head iterations?

Use **1 or 2 iterations** for real-time applications requiring low latency, such as on-device SLAM or live augmented reality tracking, where the modest accuracy trade-off is acceptable for the significant speed gain. Retain the **default of 4 iterations** for offline reconstruction tasks or high-precision mapping where accuracy takes precedence over inference speed.