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

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. This defines the interface that all specialized models must implement.
• GCTStream – Standard streaming model implementation found in 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 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 handle model weight initialization and image preprocessing.
• Geometry processing: Functions like apply_visibility_filter() in lingbot_map/utils/geometry.py manage point cloud filtering and pose encoding utilities in 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 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 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 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 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 – Executes inference on standard datasets.
• benchmark/evaluate.py – Computes metrics against ground truth.
• 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:

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:

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:

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 for interactive demos and 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, 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, or invoke the batch rendering pipeline via 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 and benchmark/evaluate.py supporting datasets like KITTI and Oxford.

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