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

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 – Core streaming window logic
• 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 – Browser-based interactive viewer using the viser UI
• 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:

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:

   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:

   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 for new KV-cache strategies or modifying 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:

   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 to understand the contribution pattern. This example exposes a --enable_foo debugging option:

# 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:

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 – Master guide containing installation steps, quick-start instructions, and model download tables.
• demo.py – Interactive streaming demo entry point using the viser browser UI.
• demo_render/batch_demo.py – Offline rendering pipeline for processing long sequences without interaction.
• 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 – 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 with the baseline courthouse example before making changes.
• Target specific architectural components: modify gct_stream_window.py for transformer logic or 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 or its optimized variant 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. 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 and document them in the README installation section.

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