# What APIs Does LingBot‑Map Expose? Complete Guide to Python Package and CLI Tools

> Explore the LingBot-Map APIs in this comprehensive guide. Discover the Python package and CLI tools for 3D streaming reconstruction, core models, loaders, and visualization wrappers.

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

---

**LingBot‑Map exposes a comprehensive Python package (`lingbot_map`) with programmatic interfaces for 3‑D streaming reconstruction, including core model classes, utility loaders, visualization wrappers, and command‑line tools for interactive demos and batch processing.**

The Robbyant/lingbot-map repository provides a modular framework for real-time 3-D mapping and streaming reconstruction. Understanding what APIs lingbot-map exposes is essential for integrating the system into custom pipelines or running evaluation benchmarks on datasets like KITTI and Oxford.

## Python Package API (lingbot_map)

The primary programmatic interface is the `lingbot_map` Python package, organized into models, utilities, and visualization modules.

### Core Model Classes

At the heart of the API are the streaming transformer models defined in `lingbot_map/models/`:

- **GCTBase** – Abstract base class for all streaming transformers, located in [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py). This defines the interface that all specialized models must implement.
- **GCTStream** – Standard streaming model implementation found in [`lingbot_map/models/gct_stream.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream.py), suitable for most real-time reconstruction tasks.
- **GCTStreamWindow** and **GCTStreamWindowV2** – Windowed streaming variants in [`lingbot_map/models/gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window.py) designed for processing very long sequences with limited memory.

### Utility Functions

Helper utilities for data preprocessing and geometry handling reside in `lingbot_map/utils/`:

- **Checkpoint loading**: `load_checkpoint()` and `load_images()` in [`lingbot_map/utils/load_fn.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/utils/load_fn.py) handle model weight initialization and image preprocessing.
- **Geometry processing**: Functions like `apply_visibility_filter()` in [`lingbot_map/utils/geometry.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/utils/geometry.py) manage point cloud filtering and pose encoding utilities in [`lingbot_map/utils/pose_enc.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/utils/pose_enc.py).

### Visualization and Sky Masking

The visualization API wraps the `viser` library for interactive 3-D viewing:

- **Viser wrapper**: `viser_wrapper()` in [`lingbot_map/vis/viser_wrapper.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/vis/viser_wrapper.py) launches a browser-based viewer on `http://localhost:8080` for inspecting frames, point clouds, and camera trajectories.
- **Sky segmentation**: [`lingbot_map/vis/sky_segmentation.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/vis/sky_segmentation.py) provides functions to download, cache, and apply an ONNX sky-segmentation model for masking sky pixels during reconstruction.

## Command-Line Interface (CLI) Tools

Beyond the Python package, lingbot-map exposes several executable scripts for end-to-end workflows.

### Interactive Demo (demo.py)

The [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) script at the repository root launches an interactive browser viewer. It accepts arguments like `--model_path`, `--image_folder`, and `--mask_sky` to load pretrained weights and visualize reconstructions in real time.

### Batch Rendering Pipeline (batch_demo.py)

For offline processing of long video sequences, [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) exposes a batch rendering API with configuration via YAML files. Key parameters include `window_size`, `keyframe_interval`, and `overlap_keyframes` for managing memory on extended sequences.

### Benchmarking Scripts

The `benchmark/` directory contains evaluation entry points:

- [`benchmark/run.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/run.py) – Executes inference on standard datasets.
- [`benchmark/evaluate.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/evaluate.py) – Computes metrics against ground truth.
- [`benchmark/prepare.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/prepare.py) – Dataset preprocessing.

Configuration files in `benchmark/config/*.yaml` define dataset-specific parameters for KITTI, Oxford, and other benchmarks.

## Practical Implementation Examples

Here are concrete implementations using the lingbot-map API.

Loading a pretrained checkpoint:

```python
from lingbot_map.models.gct_stream import GCTStream
from lingbot_map.utils.load_fn import load_checkpoint

model = GCTStream()
checkpoint_path = "/path/to/lingbot-map-long.pt"
load_checkpoint(model, checkpoint_path)

```

Launching the interactive viewer:

```python
from lingbot_map.vis.viser_wrapper import viser_wrapper

viser_wrapper(
    model=model,
    image_folder="example/courthouse",
    mask_sky=True,
    port=8080,
)

```

Running offline batch rendering:

```python
from demo_render.batch_demo import main as render_batch

render_batch(
    video_path="/data/demo_videos/indoor_travel.MP4",
    output_folder="/data/outputs/indoor_travel/",
    model_path="/path/to/lingbot-map.pt",
    config="demo_render/config/indoor.yaml",
    mode="windowed",
    window_size=128,
    keyframe_interval=10,
    overlap_keyframes=8,
    mask_sky=True,
)

```

## Summary

- **LingBot‑Map** exposes both programmatic Python APIs and command-line tools for 3-D streaming reconstruction.
- Core model classes (`GCTBase`, `GCTStream`, `GCTStreamWindow`) are defined in `lingbot_map/models/`.
- Utility functions for loading and geometry processing reside in `lingbot_map/utils/`.
- The visualization API includes `viser_wrapper()` for interactive viewing and sky-segmentation tools.
- CLI tools include [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) for interactive demos and [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) for batch processing.
- Benchmark scripts in `benchmark/` provide standardized evaluation pipelines.

## Frequently Asked Questions

### What is the base class for all streaming models in lingbot-map?

**GCTBase**, defined in [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py), serves as the abstract base class that all streaming transformers inherit from, establishing the common interface for model initialization and forward passes.

### How do I programmatically launch the interactive viewer without using the CLI?

Import `viser_wrapper` from `lingbot_map.vis.viser_wrapper` and pass your initialized model along with the image folder path. This function handles the `viser` server setup and opens the viewer at `http://localhost:8080` by default.

### Does lingbot-map support processing videos longer than the model's context window?

Yes. Use the **GCTStreamWindow** or **GCTStreamWindowV2** classes from [`lingbot_map/models/gct_stream_window.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_stream_window.py), or invoke the batch rendering pipeline via [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) with `mode="windowed"` and appropriate `window_size` parameters.

### Where are the configuration files for running standard benchmarks located?

Benchmark configurations are stored in `benchmark/config/*.yaml`, with entry points in [`benchmark/run.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/run.py) and [`benchmark/evaluate.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/evaluate.py) supporting datasets like KITTI and Oxford.