maplibre gl lidar - Moses Yebei

The Problem

Displaying massive LiDAR point clouds in a web map requires on‑the‑fly loading, CRS conversion, and interactive styling. Existing MapLibre plugins handle raster tiles only, so developers must write custom loaders, manage streaming, and build UI controls for color schemes, filters, and point picking.

What This Does

The repo delivers a MapLibre GL JS plugin (src/index.ts) that wraps a Deck.gl PointCloudLayer. Core logic lives in src/lib/core/LidarControl.ts (control lifecycle, state handling) and the streaming loaders src/lib/loaders/CopcStreamingLoader.ts and src/lib/loaders/EptStreamingLoader.ts. GUI components such as the classification legend and range sliders are in src/lib/gui/.

Example entry points – examples/basic/main.ts, examples/ept/main.ts, and the React demo examples/react/main.tsx – show how to instantiate LidarControl (vanilla) or LidarControlReact (React hook) and call loadPointCloud() with a COPC/EPT URL. The plugin ships CSS (src/lib/styles/lidar-control.css) and WebAssembly binaries (public/*.wasm) for LAZ decoding.

How It Is Wired

Execution begins in an example file, e.g. examples/react/main.tsx → App component (line 14). The component calls useLidarState() (from src/lib/hooks/useLidarState.ts) which internally creates a LidarControlReact instance (src/lib/core/LidarControlReact.tsx).

When loadPointCloud(url) is invoked, the call path is:

LidarControlReact.loadPointCloud → LidarControl.loadPointCloud (src/lib/core/LidarControl.ts).
LidarControl decides the loader based on URL and creates either CopcStreamingLoader or EptStreamingLoader (src/lib/loaders/*).
The loader calls createBufferGetter → WebAssembly laz-perf (public/laz-perf.wasm) to decode LAS/LAZ chunks.
Decoded buffers flow to PointCloudManager (src/lib/layers/PointCloudManager.ts) which builds a Deck.gl PointCloudLayer and registers it on the MapLibre map.
UI updates (point size, color scheme) travel through PanelBuilder (src/lib/gui/PanelBuilder.ts) and the React hook useLidarState, which ultimately call setState (found 23 callers) and emit events via _emit (24 callers).

The blast‑radius modules are:

src/lib/core/LidarControl.ts – 64 internal functions, called from 4 files, emits events, holds the main state machine.
src/lib/loaders/CopcStreamingLoader.ts – 32 functions, creates buffers and attribute arrays, called from 3 files.
src/lib/core/types.ts – a pure type hub with 15 dependents; changes here affect most of the code base.

No circular imports were detected, but the high instability scores (e.g., LidarControl 0.83) indicate many downstream dependencies.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/maplibre-gl-lidar
cd maplibre-gl-lidar

# Install dependencies
npm ci

# Run a demo (basic example)
npm run dev -- --config vite.examples.config.ts   # uses Vite to serve examples/basic

The package.json defines the dev script via Vite; the vite.examples.config.ts configures the example server.

For containerised builds:

docker build -t maplibre-gl-lidar .
docker run -p 5173:5173 maplibre-gl-lidar   # serves the Vite dev server inside the container

The plugin CSS must be imported (import "maplibre-gl-lidar/style.css"). No additional environment variables are required—point‑cloud URLs are passed directly to loadPointCloud().

Real‑World Use

A municipal GIS portal can embed the plugin in a React dashboard:

import { LidarControlReact, useLidarState } from "maplibre-gl-lidar/react";

function CityLidar() {
  const { setColorScheme, setPointSize } = useLidarState();
  return (
    <LidarControlReact
      url="https://s3.amazonaws.com/city/streets.copc.laz"
      onLoad={() => setColorScheme("classification")}
      pointSize={3}
    />
  );
}

The control streams only the viewport‑visible nodes, keeping bandwidth low while allowing analysts to toggle classification layers and adjust Z‑offset for alignment with orthophotos.

Code Health & Issues

High – Pin GitHub Action versions to commit SHAs (.github/workflows/*).
Medium – Declare least‑privilege GITHUB_TOKEN permissions (publish.yml).
Medium – Pin Docker base images by digest (Dockerfile).
Medium – Add a dependency‑vulnerability scan to CI.
Medium – Set persist-credentials: false on checkout (deploy-pages.yml).
Medium – Run container as non‑root (Dockerfile).
Medium – Test coverage is low (2 test files vs 41 source files).
Low – Define job timeouts in workflows (deploy-pages.yml).

Additional observations: the three oversized modules (LidarControl.ts, PointCloudLoader.ts, CopcStreamingLoader.ts) each exceed 1 400 lines, making single‑file changes high‑risk. Repeated 6‑line blocks appear across examples and the library entry point, suggesting a DRY refactor. The hub module src/lib/core/types.ts has the highest fan‑in; keeping it stable is critical.

The Bottom Line

maplibre-gl-lidar provides a functional, TypeScript‑first plugin for streaming LiDAR into MapLibre, with both vanilla and React APIs. It works out‑of‑the‑box for demos, but the core codebase is large, tightly coupled, and under‑tested, which raises maintenance overhead. It suits teams that need quick visualisation of COPC/EPT clouds and are prepared to invest in refactoring and test expansion for production use.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

69 files

TypeScript41
YAML6
HTML5
JSON4
TSX2
CSS2

ReactDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>35 modules"] g1["examples<br/>3 modules"] g2["(root)<br/>3 modules"] g3["tests<br/>2 modules"] g1 -->|3| g0 g3 -->|1| g0

Module dependencies

The 10 most depended-upon modules of 44, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_lib_core_types["types"] n1_src_lib_loaders_types["types"] n2__lib_loaders_streaming_types["streaming-types"] n3_src_lib_utils_helpers["helpers"] n4_c_lib_colorizers_ColorScheme["ColorScheme"] n5_src_lib_core_LidarControl["LidarControl"] n6_lib_loaders_PointCloudLoader["PointCloudLoader"] n7_src_lib_layers_types["types"] n8_src_index["index"] n9_lib_layers_PointCloudManager["PointCloudManager"] n8_src_index --> n5_src_lib_core_LidarControl n8_src_index --> n6_lib_loaders_PointCloudLoader n8_src_index --> n9_lib_layers_PointCloudManager n8_src_index --> n4_c_lib_colorizers_ColorScheme n8_src_index --> n0_src_lib_core_types n8_src_index --> n1_src_lib_loaders_types n8_src_index --> n2__lib_loaders_streaming_types n8_src_index --> n7_src_lib_layers_types n4_c_lib_colorizers_ColorScheme --> n1_src_lib_loaders_types n4_c_lib_colorizers_ColorScheme --> n0_src_lib_core_types n4_c_lib_colorizers_ColorScheme --> n3_src_lib_utils_helpers n5_src_lib_core_LidarControl --> n0_src_lib_core_types n5_src_lib_core_LidarControl --> n7_src_lib_layers_types n5_src_lib_core_LidarControl --> n2__lib_loaders_streaming_types n5_src_lib_core_LidarControl --> n6_lib_loaders_PointCloudLoader n5_src_lib_core_LidarControl --> n9_lib_layers_PointCloudManager n5_src_lib_core_LidarControl --> n3_src_lib_utils_helpers n5_src_lib_core_LidarControl --> n4_c_lib_colorizers_ColorScheme

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5, docker/build-push-action@v6

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/publish.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:20-alpine, nginx:alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy-pages.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium2 occurrences

2 test files against 41 source files (ratio 0.049)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/deploy-pages.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.