MapLibre GL GeoPhoto

A MapLibre GL JS plugin for visualizing geo-tagged photos and streetview imagery. Users can load trajectory data from a local folder or ZIP file, and the plugin renders GPS camera positions on the map with an interactive image viewer panel.

Features

• Local Data Loading - Load trajectory data from folders (File System Access API) or ZIP files (JSZip)
• Interactive Image Viewer - Browse streetview images with prev/next/play controls and lightbox enlargement
• GPS Visualization - Camera positions rendered as interactive map points with connecting path line
• Directional Path Arrows - Optional directional arrows along the path line
• Object Detection Layer - Optional display of detected objects from objects.geojson
• Resizable Panel - Drag the panel edge to resize with configurable max height
• TypeScript Support - Full TypeScript support with type definitions
• React Integration - React wrapper component and custom hooks

Installation

npm install maplibre-gl-geophoto

Quick Start

Vanilla JavaScript/TypeScript

import maplibregl from 'maplibre-gl';
import { GeoPhotoControl } from 'maplibre-gl-geophoto';
import 'maplibre-gl-geophoto/style.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
  center: [-122.274, 47.671],
  zoom: 15,
});

map.on('load', () => {
  const control = new GeoPhotoControl({
    title: 'Street View',
    collapsed: false,
    panelWidth: 360,
    maxHeight: 600,
    showPath: true,
    showPathDirectionArrows: true,
    pathDirectionArrowSpacing: 40,
    pathDirectionArrowSize: 12,
    preloadUrl: 'https://example.com/datasets/streetview.zip',
    showObjects: true,
    fitBoundsOnLoad: true,
  });

  map.addControl(control, 'top-right');
});

React

import { useEffect, useRef, useState } from 'react';
import maplibregl, { Map } from 'maplibre-gl';
import { GeoPhotoControlReact, useGeoPhoto } from 'maplibre-gl-geophoto/react';
import 'maplibre-gl-geophoto/style.css';

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState<Map | null>(null);
  const { selectedCamera, cameraIndex, totalCameras, handleCameraSelect, handleDataLoaded } = useGeoPhoto();

  useEffect(() => {
    if (!mapContainer.current) return;
    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
      center: [-122.274, 47.671],
      zoom: 15,
    });
    mapInstance.on('load', () => setMap(mapInstance));
    return () => mapInstance.remove();
  }, []);

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />
      {map && (
        <GeoPhotoControlReact
          map={map}
          title="Street View"
          collapsed={false}
          panelWidth={360}
          maxHeight={600}
          showPath={true}
          showPathDirectionArrows={true}
          pathDirectionArrowSpacing={40}
          pathDirectionArrowSize={12}
          preloadUrl="https://example.com/datasets/streetview.zip"
          showObjects={true}
          fitBoundsOnLoad={true}
          onCameraSelect={handleCameraSelect}
          onDataLoaded={handleDataLoaded}
        />
      )}
    </div>
  );
}

Data Format

The plugin expects trajectory data in the following structure:

dataset/
├── trajectory.geojson       # Camera positions (required)
├── trajectory.json          # Shot metadata with timestamps (optional)
├── objects.geojson           # Detected objects (optional)
└── images/                  # Streetview photos (optional)
    ├── uuid1.jpg
    ├── uuid2.jpg
    └── ...

Note: trajectory.geojson uses [latitude, longitude, elevation] coordinate ordering. The plugin automatically swaps to standard GeoJSON [longitude, latitude].

ZIP URL preload note: preloadUrl loads a ZIP from the browser, so the remote server must allow cross-origin requests (CORS).

API

GeoPhotoControl

The main control class implementing MapLibre's IControl interface.

Constructor Options

Option	Type	Default	Description
collapsed	boolean	true	Whether the panel starts collapsed
position	string	'top-right'	Control position on the map
title	string	'GeoPhoto'	Title displayed in the panel header
panelWidth	number	360	Initial width of the panel in pixels
maxHeight	number	500	Maximum panel height in pixels
showPath	boolean	true	Show line connecting camera positions
showPathDirectionArrows	boolean	false	Show directional arrows along the path
pathDirectionArrowSpacing	number	48	Spacing between path direction arrows (pixels)
pathDirectionArrowSize	number	11	Path direction arrow size (pixels)
pathDirectionArrowColor	string	pathColor	Path direction arrow color
preloadUrl	string	''	ZIP dataset URL to auto-load when the control is added
showObjects	boolean	true	Show detected objects layer
fitBoundsOnLoad	boolean	true	Auto-fit map to data bounds
fitBoundsPadding	number	50	Padding for fitBounds in pixels
pathColor	string	'#4a90d9'	Path line color
pointColor	string	'#4a90d9'	Camera point color
selectedPointColor	string	'#f97316'	Selected camera point color
imageFadeDuration	number	300	Cross-fade duration between images in ms (0 to disable)

Methods

• openFolder() - Open folder picker dialog to load data
• openZip(file) - Load data from a ZIP file
• loadZipFromUrl(zipUrl) - Load data from a ZIP file URL
• loadFromUrls(geojsonUrl, jsonUrl?, objectsUrl?, imageBasePath?) - Load data from URLs
• selectCamera(index) - Select a camera by index
• nextCamera() / prevCamera() - Navigate to next/previous camera
• firstCamera() / lastCamera() - Jump to first/last camera
• play() / stop() / togglePlay() - Auto-play controls
• clearData() - Clear loaded data and return to file picker
• toggle() / expand() / collapse() - Panel visibility
• on(event, handler) / off(event, handler) - Event handling

Events

• cameraselect - Fired when a camera is selected
• dataloaded - Fired when trajectory data is loaded
• datacleared - Fired when data is cleared
• collapse / expand / statechange - Panel state events

Development

# Clone the repository
git clone https://github.com/opengeos/maplibre-gl-geophoto.git
cd maplibre-gl-geophoto

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Run tests
npm test

Project Structure

maplibre-gl-geophoto/
├── src/
│   ├── index.ts              # Main entry point
│   ├── react.ts              # React entry point
│   ├── index.css             # Root styles
│   └── lib/
│       ├── core/             # GeoPhotoControl, React wrapper, types
│       ├── data/             # File reader (folder/ZIP/URL), parser
│       ├── hooks/            # React hooks (useGeoPhoto, usePluginState)
│       ├── utils/            # Utilities (geo, helpers)
│       └── styles/           # Component styles
├── tests/                    # Test files
├── examples/                 # Example applications
│   ├── streetview/           # Vanilla JS streetview example
│   └── streetview-react/     # React streetview example
└── .github/workflows/        # CI/CD workflows

Docker

# Pull and run
docker pull ghcr.io/opengeos/maplibre-gl-geophoto:latest
docker run -p 8080:80 ghcr.io/opengeos/maplibre-gl-geophoto:latest

# Or build locally
docker build -t maplibre-gl-geophoto .
docker run -p 8080:80 maplibre-gl-geophoto

Then open http://localhost:8080/maplibre-gl-geophoto/ in your browser.

License

MIT License - see LICENSE for details.