COPC-Cesium

A TypeScript library for streaming Cloud Optimized Point Cloud (COPC) files directly into CesiumJS without pre-tiling.

Features

• ✅ Direct COPC file streaming without 3D Tiles conversion
• ✅ Camera-based LOD (Level of Detail) management and frustum culling
• ✅ HTTP Range Request streaming with concurrency limiting, priority ordering, and cancellation
• ✅ Optional Web Worker-based LAZ decoding (off the main thread)
• ✅ GPU-accelerated rendering
• ✅ Multiple styling options (RGB, Intensity, Classification, Elevation)
• ✅ Coordinate system transformation support (WKT VLR, incl. compound CRS)
• ✅ Memory-usage-capped LRU cache for off-screen nodes (maximumMemoryUsage)

Quick Start

Installation

git clone <this-repo>
cd copc-cesium

# Install dependencies
npm install

# Build library
npm run build

Development

# Start the demo dev server
npm run dev

# Opens http://localhost:5173/autzen.html

Usage

import { COPCPointCloudProvider } from 'copc-cesium';
import { Viewer } from 'cesium';

// Create Cesium viewer
const viewer = new Viewer('cesiumContainer');

// Create COPC provider
const copcLayer = new COPCPointCloudProvider({
    url: 'https://example.com/data.copc.laz',
    colorMode: 'rgb',
    pointSize: 2,
    maximumScreenSpaceError: 16
});

// Initialize and load the root node
await copcLayer.initialize();
await copcLayer.loadRootNode();

// Add the provider's primitive collection to the scene
viewer.scene.primitives.add(copcLayer.getPrimitive());

// Drive camera-based LOD/culling every frame (not automatic - see API.md)
viewer.scene.postRender.addEventListener(() => {
  copcLayer.update(viewer.scene.frameState);
});

Documentation

• QUICKSTART.md - Quick start guide
• RUN.md - Run guide
• SETUP.md - Detailed setup guide (install, build, test)
• API.md - API documentation

Project Structure

copc-cesium/
├── src/               # TypeScript source code
│   ├── core/          # COPC parsing & loading
│   ├── render/        # GPU rendering
│   ├── network/       # HTTP Range Request
│   ├── culling/       # LOD & Frustum Culling
│   ├── cache/         # Memory management
│   ├── transform/     # Coordinate transformation
│   └── workers/       # Web Worker pool + LAZ decoder worker script
├── demo/              # Demo page
└── examples/          # Usage examples

Available Scripts

npm run build       # Build library to dist/
npm run dev         # Start development server
npm test           # Run tests

Examples

Different Color Modes

// RGB colors
new COPCPointCloudProvider({
  url: 'data.copc.laz',
  colorMode: 'rgb'
});

// Elevation-based coloring
new COPCPointCloudProvider({
  url: 'data.copc.laz',
  colorMode: 'elevation'
});

// Classification coloring
new COPCPointCloudProvider({
  url: 'data.copc.laz',
  colorMode: 'classification'
});

Web Worker Decoding

Off by default (LAZ decoding runs on the main thread). Opt in by pointing workerUrl at src/workers/laz-decoder.worker.ts (bundled with your own tooling - see demo/autzen.html for a Vite example):

new COPCPointCloudProvider({
  url: 'data.copc.laz',
  workerUrl: new URL('./laz-decoder.worker.ts', import.meta.url),
  workerPoolSize: 4 // optional, default 4
});

Browser Support

• Modern browsers with WebGL support
• HTTP Range Request support required
• Web Workers required only if you opt into workerUrl

License

MIT