colmap-viewer

Browser-based 3D viewer for COLMAP reconstruction results, built on Three.js.

Visualizes point clouds, camera frustums, and coordinate axes from COLMAP binary output files. Works as a drop-in Web Component or as a programmatic TypeScript/JavaScript API.

Install

npm install @thethingteam/colmap-viewer

Peer dependencies — install these alongside the package:

npm install three @thethingteam/colmap-wasm

Quick Start — Web Component

The easiest way to embed the viewer. Point it at your COLMAP binary files and it renders into the element.

<!-- index.html -->
<script type="module">
  import '@thethingteam/colmap-viewer'
</script>

<colmap-viewer
  style="width: 100%; height: 600px;"
  cameras-url="/data/cameras.bin"
  images-url="/data/images.bin"
  points3d-url="/data/points3D.bin"
></colmap-viewer>

The element registers itself as <colmap-viewer> on import. The points3d-url attribute is optional — omit it if you only want to visualize cameras.

Programmatic API — ColmapRenderer

Use ColmapRenderer directly when you need lifecycle control or want to load from pre-fetched buffers.

Load from URLs:

import { ColmapRenderer } from '@thethingteam/colmap-viewer'

const container = document.getElementById('viewer')!

const renderer = new ColmapRenderer(container, {
  showThemeToggle: true,
  showAxisLegend: true,
  showControlsHint: true,
})

await renderer.loadFromUrls({
  cameras: '/data/cameras.bin',
  images: '/data/images.bin',
  points3d: '/data/points3D.bin', // optional
})

// Clean up when done
renderer.dispose()

Load from ArrayBuffer:

import { ColmapRenderer } from '@thethingteam/colmap-viewer'

const renderer = new ColmapRenderer(container)

await renderer.loadFromBuffers({
  cameras: camerasBuffer,   // ArrayBuffer
  images: imagesBuffer,     // ArrayBuffer
  points3d: points3dBuffer, // ArrayBuffer, optional
})

Options Reference

| Attribute (Web Component) | Option (JS) | Type | Default | Description | |---|---|---|---|---| | cameras-url | — | string | — | URL of cameras.bin (required) | | images-url | — | string | — | URL of images.bin (required) | | points3d-url | — | string | — | URL of points3D.bin (optional) | | show-theme-toggle | showThemeToggle | boolean | true | Show light/dark mode toggle in the HUD | | show-axis-legend | showAxisLegend | boolean | true | Show XYZ axis legend overlay | | show-controls-hint | showControlsHint | boolean | true | Show mouse controls hint at the bottom |

Boolean attributes on the Web Component follow standard HTML conventions — presence means true, set to "false" to disable:

<colmap-viewer
  cameras-url="/data/cameras.bin"
  images-url="/data/images.bin"
  show-theme-toggle="false"
  show-controls-hint="false"
></colmap-viewer>

Lower-level Exports

For advanced use cases, the library also exports its internal building blocks individually:

import { parse, buildScene, createHud } from '@thethingteam/colmap-viewer'
import type { ColmapFiles, HudOptions, LayerKey } from '@thethingteam/colmap-viewer'

• parse(files) — parses raw COLMAP binary buffers into structured data
• buildScene(container, result, imageFiles, onProgress) — constructs the Three.js scene
• createHud(container, options) — mounts the HUD overlay and returns a dispose function

License

MIT