---
title: "VControlLidar"
description: "LiDAR point cloud visualization control with LAS/LAZ/COPC support"
canonical_url: "https://v-maplibre.geoql.in/controls/lidar"
---
# VControlLidar

> LiDAR point cloud visualization control with LAS/LAZ/COPC support

<callout icon="i-lucide-external-link" target="_blank" to="https://mapcn-vue.geoql.in/examples/lidar-copc">

**Live Demo** - Try the LiDAR viewer with the Autzen COPC dataset

</callout>

## Overview

The `VControlLidar` component wraps [maplibre-gl-lidar](https://github.com/opengeos/maplibre-gl-lidar), providing a full-featured LiDAR point cloud viewer with:

- LAS/LAZ/COPC file support (LAS 1.0 - 1.4)
- Dynamic COPC streaming for large point clouds
- Multiple color schemes (elevation, intensity, classification, RGB)
- Classification legend with toggle visibility
- Point picking with attribute tooltips
- Z-offset adjustment for alignment
- Interactive GUI control panel

## Installation

Install the required dependency (`maplibre-gl-lidar` 0.21 or later):

```bash
pnpm add maplibre-gl-lidar
```

Import the CSS in your app:

```typescript
import 'maplibre-gl-lidar/style.css';
```

## Usage

```vue
<script setup lang="ts">
  import { VMap } from '@geoql/v-maplibre';
  import { VControlLidar } from '@geoql/v-maplibre/lidar';
  import 'maplibre-gl-lidar/style.css';

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [-123.075, 44.05],
    zoom: 14,
    pitch: 60,
    maxPitch: 85,
  };

  const lidarOptions = {
    collapsed: false,
    pointSize: 2,
    colorScheme: 'elevation',
    pickable: true,
    autoZoom: true,
  };

  const copcUrl = 'https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz';
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VControlLidar
      position="top-right"
      :options="lidarOptions"
      :default-url="copcUrl"
      @load="(info) => console.log('Loaded:', info)"
    />
  </VMap>
</template>
```

## Props

### options

- **Type:** `LidarControlOptions`
- **Required:** `false`

Configuration options for the LiDAR control.

```typescript
interface LidarControlOptions {
  collapsed?: boolean;           // Start collapsed (default: true)
  title?: string;                // Panel title (default: 'LiDAR Viewer')
  panelWidth?: number;           // Panel width in pixels (default: 365)
  panelMaxHeight?: number;       // Panel max height (default: 500)
  pointSize?: number;            // Point size in pixels (default: 2)
  opacity?: number;              // Opacity 0-1 (default: 1.0)
  colorScheme?: ColorScheme;     // Color scheme (default: 'elevation')
  usePercentile?: boolean;       // Use 2-98% percentile for coloring
  pointBudget?: number;          // Max points to display (default: 1000000)
  pickable?: boolean;            // Enable point picking (default: false)
  autoZoom?: boolean;            // Auto zoom to data (default: true)
  copcLoadingMode?: 'full' | 'dynamic';  // Loading mode for COPC
  streamingPointBudget?: number; // Max points for streaming (default: 5000000)
}

type ColorScheme = 'elevation' | 'intensity' | 'classification' | 'rgb';
```

### position

- **Type:** `'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'`
- **Required:** `false`
- **Default:** `'top-right'`

Position of the control on the map.

### defaultUrl

- **Type:** `string`
- **Required:** `false`

URL of a point cloud file to auto-load on mount.

### classificationStyles

- **Type:** `ClassificationStyles` (`Record<number, { name?: string; color?: [number, number, number] }>`)
- **Required:** `false`

Reactive display name and colour per classification code, for example custom classes (64-255) from an annotation tool. The overrides apply to point colours, the classification legend and the hover tooltip. A code without an entry keeps its ASPRS name and colour. Setting the prop to `undefined` clears the overrides.

```vue
<VControlLidar
  :classification-styles="{
    64: { name: 'Solar panel', color: [255, 196, 0] },
    65: { name: 'Antenna', color: [255, 64, 160] },
  }"
/>
```

## Events

### @load

Emitted when a point cloud has been successfully loaded.

- **Payload:** `{ pointCloud: PointCloudInfo }`

```typescript
interface PointCloudInfo {
  id: string;
  name: string;
  pointCount: number;
  bounds: PointCloudBounds;
  hasRGB: boolean;
  hasIntensity: boolean;
  hasClassification: boolean;
  source: string;
  wkt?: string;
}
```

### @loadstart

Emitted when loading begins.

### @loaderror

Emitted when loading fails.

- **Payload:** `{ error: Error }`

### @unload

Emitted when a point cloud is unloaded.

### @statechange

Emitted when control state changes.

### @stylechange

Emitted when styling changes (point size, color scheme, etc.).

### @streamingstart / @streamingstop

Emitted when COPC streaming starts or stops.

### @streamingprogress

Emitted during streaming with progress info.

### @budgetreached

Emitted when point budget limit is reached.

### @pointclick

Emitted when the user clicks a point. Needs `pickable: true` in `options`.

- **Payload:** `{ point?: PickedPointInfo }` with `pointCloudId`, `index`, `longitude`, `latitude`, `elevation`, `classification`, `intensity`, RGB, the screen `x`/`y`, and every extra attribute in `attributes`.

```vue
<VControlLidar
  :options="{ pickable: true }"
  @pointclick="({ point }) => console.log(point?.classification)"
/>
```

## Exposed Methods

Access methods via template ref:

```vue
<script setup lang="ts">
  import { ref } from 'vue';

  const lidarRef = ref();

  const loadFile = async (url: string) => {
    await lidarRef.value.loadPointCloud(url);
  };
</script>

<template>
  <VControlLidar ref="lidarRef" />
</template>
```

### loadPointCloud(source)

Load a point cloud from URL, File, or ArrayBuffer.

```typescript
await lidarRef.value.loadPointCloud('https://example.com/data.copc.laz');
```

### unloadPointCloud(id?)

Unload a point cloud by ID, or all if no ID provided.

### flyToPointCloud(id?)

Fly to a point cloud's bounds.

### setPointSize(size)

Set the point size in pixels.

### setColorScheme(scheme)

Set the color scheme: `'elevation'`, `'intensity'`, `'classification'`, or `'rgb'`.

### setOpacity(opacity)

Set opacity (0-1).

### toggle() / expand() / collapse()

Toggle, expand, or collapse the control panel.

### getState()

Get the current control state.

### getPointClouds()

Get array of loaded point clouds.

### stopStreaming(id?)

Stop streaming for a specific dataset or all.

### isStreaming(id?)

Check if streaming is active.

### pauseStreaming(id) / resumeStreaming(id)

Pause level-of-detail streaming for a COPC/EPT cloud: no new nodes load and none are evicted, so the loaded points stay in place (useful while you edit or measure them). `resumeStreaming` refreshes the nodes for the current view. `isStreamingLoading(id)` reports whether node requests are still in flight.

### loadRegion(id, bounds, options?) / clearPinnedRegion(id)

Load a COPC region `[west, south, east, north]` at full resolution and pin it, so streaming never evicts it. `options.maxPoints` caps the region size. Resolves with `{ nodes, points }`. `clearPinnedRegion` releases the region.

```typescript
const { points } = await lidarRef.value.loadRegion(
  cloudId,
  [-123.08, 44.05, -123.07, 44.06],
  { maxPoints: 2_000_000 },
);
```

### setClassificationStyles(styles) / getClassificationStyles()

Imperative form of the `classificationStyles` prop.

## Color Schemes

- **elevation**: Viridis-like color ramp based on Z values
- **intensity**: Grayscale based on intensity attribute
- **classification**: ASPRS standard classification colors
- **rgb**: Use embedded RGB colors (if available)

## COPC Streaming

For large COPC files, dynamic streaming loads only visible points:

```vue
<VControlLidar
  :options="{
    copcLoadingMode: 'dynamic',
    streamingPointBudget: 10_000_000,
  }"
/>
```

Features:

- Viewport-based loading (only loads visible octree nodes)
- Level-of-detail based on zoom level
- Center-first priority
- Configurable point budget

## Supported Formats

- LAS 1.0 - 1.4 (all versions)
- LAZ (compressed LAS)
- COPC (Cloud Optimized Point Cloud) with dynamic streaming

## TypeScript

```typescript
import type {
  LidarControlOptions,
  ColorScheme,
  CopcLoadingMode,
  PointCloudInfo,
  PointCloudBounds,
  ClassificationStyles,
  PickedPointInfo,
  LidarPointClickEventData,
  LidarRegionLoadResult,
} from '@geoql/v-maplibre/lidar';
```


## Sitemap

See the full [sitemap](https://v-maplibre.geoql.in/sitemap.md) for all pages.