The Problem
Users needing to visualize USGS 3DEP LiDAR COPC data from Microsoft Planetary Computer face significant complexity in integrating point cloud visualization with MapLibre GL JS. The ecosystem lacks a unified plugin that handles search, footprint rendering, and streaming point cloud loading without custom glue code.
What This Does
This repo provides a MapLibre GL JS plugin for searching and visualizing USGS 3DEP LiDAR data. The core logic lives in src/lib/adapters/UsgsLidarLayerAdapter.ts, which mediates between the MapLibre control and COPC point cloud streaming. Search functionality is handled by src/lib/stac/StacSearcher.ts, which queries Microsoft Planetary Computer's STAC API. The UI panel is built in src/lib/gui/PanelBuilder.ts, and state management is exposed via src/lib/hooks/useUsgsLidarState.ts for React integration. Two example directories demonstrate usage: examples/basic/ for vanilla TypeScript and examples/react/ for React components.
How To Use It
Setup
The project uses npm as its package manager (per package.json). Install with: npm install maplibre-gl-usgs-lidar maplibre-gl maplibre-gl-lidar
Configuration
No API keys are required—access to Microsoft Planetary Computer is handled server-side. The control styles are in src/lib/styles/usgs-lidar-control.css. The React wrapper expects a MapLibre map instance; see src/lib/core/UsgsLidarControlReact.tsx for the component API.
Running it
Start the development server with npm run dev (configured in vite.config.ts). The vanilla entry point is examples/basic/index.html with logic in examples/basic/main.ts; the React example uses examples/react/index.html and examples/react/main.tsx. Docker builds are configured in Dockerfile with GitHub Actions workflows in .github/workflows/.
Real-World Use
A geospatial analytics team could embed UsgsLidarControl into an existing MapLibre-based web map to allow analysts to search USGS 3DEP LiDAR coverage by extent, inspect item footprints, and stream COPC point clouds for elevation analysis. The useUsgsLidarState hook simplifies React integration, while the vanilla UsgsLidarControl class suits custom frameworks. A typical workflow: instantiate the map, add the control, listen for searchcomplete to retrieve dataset metadata, then load selected point clouds via the control's load method.
Code Health & Issues
Tests: 3 test files exist under tests/ with a Vitest configuration (vitest.config.ts). Coverage is limited to the STAC searcher; no tests exercise the control's event pipeline or point cloud loading. CI/CD: GitHub Actions workflows are configured for Docker publishing and Pages deployments (deploy-pages.yml, docker-publish.yml, publish.yml). Type safety: Full TypeScript definitions are provided; 23 .ts/.tsx files indicate a well-typed codebase. Risks: The adapter layer (UsgsLidarLayerAdapter.ts) assumes COPC streaming succeeds without explicit error boundaries; network failures during fetch could leave the UI in an inconsistent state. No input validation is visible on bounding box parameters passed to the STAC searcher.
The Bottom Line
A focused, type-safe plugin that eliminates the boilerplate of integrating USGS LiDAR with MapLibre GL JS. It's well-suited for teams building geospatial web applications that need to display 3DEP data without building STAC search and COPC streaming logic from scratch. Teams already invested in the MapLibre ecosystem will find the quickest path to value here.