# How to Contribute to the LingBot‑Map Project: A Complete Guide

> Learn how to contribute to the LingBot-Map project. Follow our guide to fork the repo, set up the environment, and submit pull requests for the 3-D streaming reconstruction model.

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

---

**To contribute to the lingbot-map project, fork the repository on GitHub, clone it locally, set up the conda/PyTorch/FlashInfer environment, verify the baseline demo runs, then submit pull requests following the established workflow for the 3-D streaming reconstruction model.**

LingBot‑Map is an open-source feed-forward 3-D foundation model designed for streaming reconstruction of large-scale scenes. Whether you want to extend the Geometric Context Transformer or improve the interactive demo interface, this guide explains exactly how to contribute to the lingbot-map project using the actual source structure and development workflow maintained in the `Robbyant/lingbot-map` repository.

## Understanding the LingBot‑Map Architecture

Before submitting changes, familiarize yourself with the three core components that define the system.

### Geometric Context Transformer (GCT)

The GCT unifies coordinate grounding, dense geometric cues, and long-range drift correction. The transformer implementation lives in the streaming window modules:

- [`lingbot_map/models/gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window.py) – Core streaming window logic
- [`lingbot_map/models/gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window_v2.py) – Optimized variant with additional performance enhancements

The "window" abstraction splits video input into overlapping KV-cache windows, with each window contributing frames in the range `[0, effective_end)` to the reconstruction.

### Backend and KV‑Cache Systems

The project supports two attention backends for streaming inference:

- **FlashInfer** (recommended) – Provides paged KV-cache attention achieving approximately 20 FPS on 518×378 inputs
- **PyTorch SDPA** – Fallback option activated via `--use_sdpa` when FlashInfer is unavailable

### Demo and Rendering Pipelines

Two entry points allow interactive exploration and offline processing:

- [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) – Browser-based interactive viewer using the **viser** UI
- [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) – Offline renderer utilizing CUDA extensions in `demo_render/render_cuda_ext`

## Setting Up Your Development Environment

A properly configured environment ensures your contributions run consistently with the existing codebase. Follow the Installation section in the README to establish the dependency chain: conda environment → PyTorch → FlashInfer → optional visualization dependencies.

Verify your setup by running the baseline demo:

```bash
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/courthouse --mask_sky

```

## Step‑by‑Step Contribution Workflow

The project follows a standard GitHub contribution model with specific verification steps for this streaming reconstruction system.

1. **Fork the repository** on GitHub to create an isolated copy under your account.

2. **Clone locally** using:
   
   ```bash
   git clone https://github.com/<your-username>/lingbot-map.git
   ```

3. **Install dependencies** following the README's Installation guide (conda → PyTorch → FlashInfer).

4. **Run the baseline demo** to confirm functionality:
   
   ```bash
   python demo.py --model_path /path/to/lingbot-map-long.pt \
       --image_folder example/courthouse --mask_sky
   ```

5. **Implement your changes** in the relevant source files, such as extending [`gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/gct_stream_window.py) for new KV-cache strategies or modifying [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) for CLI improvements.

6. **Test locally** by re-running the demo. While the repository currently lacks unit tests, manual verification through the demo scripts is required.

7. **Format your code** using `ruff` or `black` if configured, maintaining PEP 8 compliance and existing type hint conventions.

8. **Commit and push** your changes:
   
   ```bash
   git add .
   git commit -m "Brief description of changes"
   git push origin <branch-name>
   ```

9. **Open a Pull Request** comparing your branch against `Robbyant/lingbot-map:main`.

10. **Respond to review feedback** and push additional commits as needed until maintainers approve the merge.

## Making Your First Code Change

Consider adding a simple CLI flag to [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) to understand the contribution pattern. This example exposes a `--enable_foo` debugging option:

```python

# File: demo.py (excerpt)

import argparse

def parse_args():
    parser = argparse.ArgumentParser()
    # existing flags …

    parser.add_argument(
        "--enable_foo",
        action="store_true",
        help="Enable foo‑mode debugging visualisation."
    )
    return parser.parse_args()

def main():
    args = parse_args()
    # existing setup …

    if args.enable_foo:
        print("[demo] Foo mode enabled – extra debug output will be shown.")
        # Insert debugging logic here.

    # continue with normal inference …

```

Verify the new flag works without breaking existing functionality:

```bash
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/courthouse --mask_sky --enable_foo

```

## Key Source Files Every Contributor Should Know

Understanding these file locations accelerates development and ensures changes align with the architecture:

- **[`README.md`](https://github.com/Robbyant/lingbot-map/blob/main/README.md)** – Master guide containing installation steps, quick-start instructions, and model download tables.
- **[`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py)** – Interactive streaming demo entry point using the viser browser UI.
- **[`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py)** – Offline rendering pipeline for processing long sequences without interaction.
- **[`lingbot_map/models/gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window.py)** – Core streaming-window transformer implementation handling coordinate grounding and drift correction.
- **[`lingbot_map/models/gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window_v2.py)** – Updated streaming window with performance optimizations.
- **`demo_render/render_cuda_ext/`** – CUDA extensions (`voxel_morton_ext`, `frustum_cull_ext`) compiled for the offline renderer.
- **`lingbot-map_paper.pdf`** – Research paper documenting the model architecture and methodology.

## Summary

- Fork and clone the repository, then install dependencies via conda/PyTorch/FlashInfer according to the README.
- Verify your environment by running [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) with the baseline courthouse example before making changes.
- Target specific architectural components: modify [`gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/gct_stream_window.py) for transformer logic or [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) for interface changes.
- Test changes manually using the demo scripts, as the repository currently lacks automated unit tests.
- Follow PEP 8 style conventions and submit pull requests against the `main` branch for maintainer review.

## Frequently Asked Questions

### What dependencies are required to contribute to the lingbot-map project?

You need a conda environment with PyTorch and FlashInfer for optimal performance (approximately 20 FPS on 518×378 inputs). If FlashInfer installation fails, the codebase falls back to PyTorch's native SDPA attention via the `--use_sdpa` flag, though this reduces streaming performance.

### Which files should I modify to extend the transformer architecture?

Edit [`lingbot_map/models/gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window.py) or its optimized variant [`gct_stream_window_v2.py`](https://github.com/Robbyant/lingbot-map/blob/main/gct_stream_window_v2.py) to modify the Geometric Context Transformer's streaming window logic, KV-cache strategies, or coordinate grounding mechanisms.

### How do I test changes before submitting a pull request?

Run the interactive demo with: `python demo.py --model_path /path/to/lingbot-map-long.pt --image_folder example/courthouse --mask_sky`. For rendering changes, test using [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py). The repository currently does not include unit tests, so manual verification through these entry points is essential.

### Are there specific coding standards for contributions?

Maintain PEP 8 compliance and match existing type hint patterns where present. Run `ruff` or `black` if configured in the repository. When adding heavy dependencies like new CUDA kernels, update [`pyproject.toml`](https://github.com/Robbyant/lingbot-map/blob/main/pyproject.toml) and document them in the README installation section.