maplibre-copc-layer 0.0.1

package/README.md

@@ -0,0 +1,124 @@
+# maplibre-copc-layer
+
+[![npm version](https://img.shields.io/npm/v/maplibre-copc-layer)](https://www.npmjs.com/package/maplibre-copc-layer)
+[![license](https://img.shields.io/npm/l/maplibre-copc-layer)](https://github.com/spatialty-io/maplibre-copc-layer/blob/main/LICENSE)
+
+Render massive point clouds on [MapLibre GL JS](https://maplibre.org/) — powered by [COPC](https://copc.io/) and [Three.js](https://threejs.org/).
+
+Stream [Cloud-Optimized Point Cloud (COPC)](https://copc.io/) data directly into MapLibre as a custom layer. Only the tiles visible on screen are fetched and rendered, enabling smooth visualization of billion-point datasets in the browser.
+
+## Highlights
+
+- **Streaming LOD** — Screen-space error (SSE) based level-of-detail fetches only what you see
+- **Web Worker parsing** — COPC decoding and coordinate reprojection run off the main thread
+- **LRU cache** — Configurable node count and memory limits keep the GPU lean
+- **Eye-Dome Lighting** — EDL post-processing for depth perception without normals
+- **Color modes** — RGB, height ramp, intensity, and flat white
+- **Zero config** — Drop in a single `CopcLayer` class and go
+
+## Demo
+
+**[Live Demo](https://maplibre-copc-layer.spatialty.workers.dev/?copc=https%3A%2F%2Fgsvrg.ipri.aist.go.jp%2F3ddb-pds%2Fcopc%2F114112.copc.laz#17.95/35.657894/139.746455/-83.4/60)**
+
+## Install
+
+```bash
+npm install maplibre-copc-layer
+```
+
+Peer dependencies:
+
+```bash
+npm install maplibre-gl three
+```
+
+## Quick Start
+
+```ts
+import maplibregl from 'maplibre-gl';
+import { CopcLayer } from 'maplibre-copc-layer';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: 'https://demotiles.maplibre.org/style.json',
+  center: [139.7, 35.7],
+  zoom: 14,
+});
+
+const layer = new CopcLayer('https://example.com/pointcloud.copc.laz', {
+  colorMode: 'rgb',
+  pointSize: 4,
+  enableEDL: true,
+  onInitialized: ({ center }) => map.flyTo({ center, zoom: 16 }),
+});
+
+map.on('load', () => map.addLayer(layer));
+```
+
+## API
+
+### `CopcLayer`
+
+```ts
+new CopcLayer(url: string, options?: CopcLayerOptions, layerId?: string)
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `pointSize` | `number` | `6` | Point size in pixels |
+| `colorMode` | `'rgb' \| 'height' \| 'intensity' \| 'white'` | `'rgb'` | Coloring mode |
+| `sseThreshold` | `number` | `8` | SSE threshold for LOD — lower values load more detail |
+| `depthTest` | `boolean` | `true` | Enable depth testing |
+| `maxCacheSize` | `number` | `100` | Max cached nodes |
+| `maxCacheMemory` | `number` | `104857600` | Max cache memory in bytes (100 MB) |
+| `enableEDL` | `boolean` | `false` | Enable Eye-Dome Lighting |
+| `edlStrength` | `number` | `0.4` | EDL effect strength |
+| `edlRadius` | `number` | `1.5` | EDL sampling radius |
+| `wasmPath` | `string` | `undefined` | Custom path to `laz-perf.wasm` |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `onInitialized` | `(msg) => void` | — | Called with `{ nodeCount, center }` after COPC header loads |
+
+#### Methods
+
+| Method | Description |
+|---|---|
+| `setPointSize(size)` | Update point size |
+| `setSseThreshold(threshold)` | Update SSE threshold |
+| `setDepthTest(enabled)` | Toggle depth testing |
+| `setEDLEnabled(enabled)` | Toggle Eye-Dome Lighting |
+| `updateEDLParameters({ strength?, radius? })` | Update EDL parameters |
+| `updateCacheConfig(config)` | Update cache limits at runtime |
+| `clearCache()` | Clear all cached nodes |
+| `getPointSize()` | Get current point size |
+| `getColorMode()` | Get current color mode |
+| `getSseThreshold()` | Get current SSE threshold |
+| `getDepthTest()` | Get depth test state |
+| `getEDLParameters()` | Get EDL parameters |
+| `getOptions()` | Get all current options |
+| `isLoading()` | Whether data is currently being fetched |
+| `getNodeStats()` | Returns `{ loaded, visible }` node counts |
+
+### `GlobeControl`
+
+A MapLibre `IControl` that toggles between Mercator and Globe projections.
+
+```ts
+import { GlobeControl } from 'maplibre-copc-layer';
+
+map.addControl(new GlobeControl());
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm dev       # Dev server with demo app
+pnpm test      # Run tests
+pnpm build     # Build library
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,176 @@
+import maplibregl from "maplibre-gl";
+import * as THREE from "three";
+
+//#region src/cache-manager.d.ts
+interface CachedNodeData {
+  nodeId: string;
+  positions: Float64Array;
+  colors: Float32Array;
+  pointCount: number;
+  geometry?: THREE.BufferGeometry;
+  points?: THREE.Points;
+  materialConfig: {
+    colorMode: string;
+    pointSize: number;
+    depthTest: boolean;
+  };
+  lastAccessed: number;
+  sizeBytes: number;
+}
+interface CacheManagerOptions {
+  maxNodes?: number;
+  maxMemoryBytes?: number;
+  debug?: boolean;
+}
+declare class CacheManager {
+  private cache;
+  private memoryUsage;
+  private options;
+  constructor(options?: CacheManagerOptions);
+  get(nodeId: string): CachedNodeData | null;
+  set(nodeData: CachedNodeData, protectedNodes?: Set<string>): void;
+  has(nodeId: string): boolean;
+  delete(nodeId: string): boolean;
+  clear(): void;
+  updateOptions(newOptions: Partial<CacheManagerOptions>, protectedNodes?: Set<string>): void;
+  getCachedNodeIds(): string[];
+  size(): number;
+  static estimateNodeSize(positions: Float64Array | Float32Array, colors: Float32Array): number;
+  static createNodeData(nodeId: string, positions: Float64Array, colors: Float32Array, materialConfig: CachedNodeData['materialConfig']): CachedNodeData;
+  private ensureCacheLimits;
+  private disposeNodeResources;
+  private formatBytes;
+  private log;
+}
+//#endregion
+//#region src/copclayer.d.ts
+type ColorMode = 'rgb' | 'height' | 'intensity' | 'white';
+interface CopcLayerOptions {
+  pointSize?: number;
+  colorMode?: ColorMode;
+  maxCacheSize?: number;
+  sseThreshold?: number;
+  depthTest?: boolean;
+  maxCacheMemory?: number;
+  debug?: boolean;
+  enableEDL?: boolean;
+  edlStrength?: number;
+  edlRadius?: number;
+  /** Path to laz-perf.wasm file for LAZ decompression */
+  wasmPath?: string;
+  onInitialized?: (message: {
+    nodeCount: number;
+    center: [number, number];
+  }) => void;
+}
+interface NodeStats {
+  loaded: number;
+  visible: number;
+}
+declare class CopcLayer implements maplibregl.CustomLayerInterface {
+  readonly id: string;
+  readonly type: 'custom';
+  readonly renderingMode: '3d';
+  readonly url: string;
+  map?: maplibregl.Map;
+  readonly camera: THREE.Camera;
+  readonly scene: THREE.Scene;
+  renderer?: THREE.WebGLRenderer;
+  readonly worker: Worker;
+  readonly cacheManager: CacheManager;
+  private readonly options;
+  private visibleNodes;
+  private workerInitialized;
+  private pendingRequests;
+  private requestQueue;
+  private lastCameraPosition;
+  private sceneCenter;
+  private colorTarget?;
+  private depthTarget?;
+  private edlMaterial?;
+  private edlQuadScene?;
+  private edlQuadCamera?;
+  private readonly _tempMatrix1;
+  private readonly _tempMatrix2;
+  private _lastEdlWidth;
+  private _lastEdlHeight;
+  private _lastUpdatePointsTime;
+  constructor(url: string, options?: CopcLayerOptions, layerId?: string);
+  private setupWorkerMessageHandlers;
+  private handleNodeLoaded;
+  private updateVisibleNodes;
+  private requestNodeData;
+  private needsMaterialUpdate;
+  private updateNodeMaterial;
+  private rebuildAllMaterials;
+  private removeFromRequestQueue;
+  private cancelAllPendingRequests;
+  private prioritizeNodeRequests;
+  onAdd(map: maplibregl.Map, gl: WebGLRenderingContext): Promise<void>;
+  updateCacheConfig(config: Partial<CopcLayerOptions>): void;
+  setPointSize(size: number): void;
+  setSseThreshold(threshold: number): void;
+  setDepthTest(enabled: boolean): void;
+  /**
+   * Compute camera altitude in meters above sea level.
+   * MapLibre's getCameraAltitude() returns NaN in Globe mode because
+   * the Globe transform's internal _pixelPerMeter is never initialized.
+   * We replicate the formula using publicly accessible values.
+   */
+  private computeCameraAltitude;
+  private updatePoints;
+  render(_gl: WebGLRenderingContext, options: maplibregl.CustomRenderMethodInput): void;
+  private shouldUpdateSceneCenter;
+  onRemove(_map: maplibregl.Map, _gl: WebGLRenderingContext): void;
+  private setupEDL;
+  private updateEDLSize;
+  private createPointMaterial;
+  getPointSize(): number;
+  getColorMode(): ColorMode;
+  getSseThreshold(): number;
+  getDepthTest(): boolean;
+  getOptions(): Readonly<CopcLayerOptions>;
+  isLoading(): boolean;
+  getNodeStats(): NodeStats;
+  clearCache(): void;
+  setEDLEnabled(enabled: boolean): void;
+  updateEDLParameters(params: {
+    strength?: number;
+    radius?: number;
+  }): void;
+  getEDLParameters(): {
+    enabled: boolean;
+    strength: number;
+    radius: number;
+  };
+}
+//#endregion
+//#region src/globe-control.d.ts
+/**
+ * A MapLibre control that toggles between Mercator and Globe projections.
+ */
+declare class GlobeControl implements maplibregl.IControl {
+  private map?;
+  private container?;
+  private button?;
+  private isGlobe;
+  onAdd(map: maplibregl.Map): HTMLElement;
+  onRemove(): void;
+  getDefaultPosition(): maplibregl.ControlPosition;
+  private toggle;
+  private updateIcon;
+}
+//#endregion
+//#region src/worker/sse.d.ts
+type Vec3 = [number, number, number];
+/**
+ * Calculates Screen Space Error (SSE) for a point cloud node.
+ * Higher SSE = more visible error = should render with higher detail.
+ *
+ * @param maxDistance - Optional maximum effective distance. When the camera is
+ *   extremely far away (e.g. Globe View at low zoom), the distance is capped
+ *   to this value so that SSE does not approach 0.
+ */
+declare function computeScreenSpaceError(cameraCenter: Vec3, center: Vec3, fov: number, geometricError: number, screenHeight: number, maxDistance?: number): number;
+//#endregion
+export { CacheManager, type CacheManagerOptions, type CachedNodeData, type ColorMode, CopcLayer, type CopcLayerOptions, GlobeControl, type NodeStats, type Vec3, computeScreenSpaceError };