maplibre-gl-usgs-lidar

A MapLibre GL JS plugin for searching and visualizing USGS 3DEP LiDAR data from Microsoft Planetary Computer (COPC) and AWS Open Data (EPT).

Features

• Search USGS 3DEP LiDAR data by map extent or custom bounding box
• Supports two data sources: COPC (Planetary Computer) and EPT (AWS Open Data)
• View search results with item footprints on the map
• Load and visualize COPC and EPT point cloud data
• Dynamic streaming for efficient handling of large datasets
• Customizable color schemes (elevation, intensity, classification, RGB)
• React components and hooks for easy integration
• TypeScript support with full type definitions

Installation

npm install maplibre-gl-usgs-lidar maplibre-gl maplibre-gl-lidar

Quick Start

Vanilla JavaScript/TypeScript

import maplibregl from 'maplibre-gl';
import { UsgsLidarControl } from 'maplibre-gl-usgs-lidar';

// Import styles
import 'maplibre-gl/dist/maplibre-gl.css';
import 'maplibre-gl-lidar/style.css';
import 'maplibre-gl-usgs-lidar/style.css';

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

map.on('load', () => {
  // Add USGS LiDAR control
  const control = new UsgsLidarControl({
    title: 'USGS 3DEP LiDAR',
    collapsed: false,
    maxResults: 50,
  });

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

  // Listen for events
  control.on('searchcomplete', (event) => {
    console.log(`Found ${event.items?.length} datasets`);
  });

  control.on('loadcomplete', (event) => {
    console.log('Loaded:', event.pointCloud);
  });
});

React

import { useEffect, useRef, useState } from 'react';
import maplibregl from 'maplibre-gl';
import { UsgsLidarControlReact, useUsgsLidarState } from 'maplibre-gl-usgs-lidar/react';

// Import styles
import 'maplibre-gl/dist/maplibre-gl.css';
import 'maplibre-gl-lidar/style.css';
import 'maplibre-gl-usgs-lidar/style.css';

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState(null);
  const { state, toggle } = useUsgsLidarState({ collapsed: false });

  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: [-105.27, 40.01],
      zoom: 10,
    });

    mapInstance.on('load', () => {
      setMap(mapInstance);
    });

    return () => mapInstance.remove();
  }, []);

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />
      {map && (
        <UsgsLidarControlReact
          map={map}
          title="USGS LiDAR"
          collapsed={state.collapsed}
          onSearchComplete={(items) => console.log('Found:', items.length)}
        />
      )}
    </div>
  );
}

API

UsgsLidarControl

Main control class implementing MapLibre's IControl interface.

Options

Option	Type	Default	Description
collapsed	boolean	true	Start with panel collapsed
position	string	'top-right'	Control position
title	string	'USGS 3DEP LiDAR'	Panel title
panelWidth	number	380	Panel width in pixels
panelMaxHeight	number	600	Panel max height in pixels
maxResults	number	50	Maximum search results
showFootprints	boolean	true	Show item footprints on map
autoZoomToResults	boolean	true	Auto-zoom to results
lidarControlOptions	object	{}	Options for internal LidarControl

Methods

Method	Description
searchByExtent()	Search by current map extent
searchByBbox(bbox)	Search by bounding box
startDrawing()	Start drawing mode
stopDrawing()	Stop drawing mode
selectItem(item)	Select an item
deselectItem(item)	Deselect an item
loadItem(item)	Load item's COPC data
loadSelectedItems()	Load all selected items
unloadItem(itemId)	Unload an item
clearResults()	Clear search results
clearLoadedItems()	Clear loaded items
toggle()	Toggle panel open/closed
expand()	Expand panel
collapse()	Collapse panel

Events

Event	Description
collapse	Panel collapsed
expand	Panel expanded
statechange	State changed
searchstart	Search started
searchcomplete	Search completed
searcherror	Search error
loadstart	Loading started
loadcomplete	Loading completed
loaderror	Loading error
drawstart	Drawing started
drawend	Drawing ended

StacSearcher

STAC API client for searching Planetary Computer.

import { StacSearcher } from 'maplibre-gl-usgs-lidar';

const searcher = new StacSearcher();
const results = await searcher.search({
  bbox: [-123, 44, -122, 45],
  limit: 25,
});

Docker

The examples can be run using Docker. The image is automatically built and published to GitHub Container Registry.

Pull and Run

# Pull the latest image
docker pull ghcr.io/opengeos/maplibre-gl-usgs-lidar:latest

# Run the container
docker run -p 8080:80 ghcr.io/opengeos/maplibre-gl-usgs-lidar:latest

Then open http://localhost:8080/maplibre-gl-usgs-lidar/ in your browser to view the examples.

Build Locally

# Build the image
docker build -t maplibre-gl-usgs-lidar .

# Run the container
docker run -p 8080:80 maplibre-gl-usgs-lidar

Available Tags

Tag	Description
latest	Latest release
x.y.z	Specific version (e.g., 1.0.0)
x.y	Minor version (e.g., 1.0)

Data Sources

This plugin supports two data sources for USGS 3DEP LiDAR data:

• COPC (Cloud Optimized Point Cloud): USGS 3DEP LiDAR COPC from Microsoft Planetary Computer
• EPT (Entwine Point Tiles): USGS LiDAR from AWS Open Data via hobuinc/usgs-lidar

Dependencies

• maplibre-gl - Map rendering
• maplibre-gl-lidar - LiDAR visualization

License

MIT