copcesium

Autzen Stadium — Oregon, USA · ~81 MB PDAL/data · CC-BY-4.0

Niagara Region — Ontario, Canada · ~140 MB Natural Resources Canada · OGL-Canada

한국어 README

CesiumJS provider for real-time COPC (Cloud Optimized Point Cloud) streaming and rendering.

▶ Try the live demo — streams multi-gigabyte public COPC files straight from S3 in your browser. No install, no Cesium Ion token.

• Streaming, not loading: only the octree nodes visible to the current camera are fetched, over HTTP Range Requests — never the whole file.
• Off the main thread: LAZ decompression and coordinate transforms run in a pool of reused Web Workers, so decoding never blocks the UI.
• Level of detail: a screen-space-error-driven octree walk decides what to subdivide, so point density matches what the camera can actually resolve, and a node is only ever swapped out once its replacement is ready to show — no flash of empty space mid-transition.
• CRS-aware: auto-detects the source coordinate system (including compound CRSes with a non-meter vertical unit) from the file's own WKT metadata, with a proj4-backed EPSG fallback table.
• Live-tunable: pixelSize, sseThreshold, and the whole styling API can be adjusted on a running data source with no reload.
• Genuinely drop-in: the published package is a single self-contained .mjs file — the Worker and its laz-perf WASM module are compiled inline at build time, so there's no separate asset for your bundler to lose track of.

📖 In-depth documentation lives in the wiki: Architecture · Options & Tuning · Coordinate Systems · Converting to COPC · Troubleshooting. This README is the quick reference.

• Demo
• Installation
• Setup
• Quick start
• Options
• API reference
• Requirements: HTTP Range Requests and CORS
• Coordinate systems
• Example
• Roadmap
• Credits
• License

copcesium.vercel.app runs the advanced-viewer example against public COPC datasets — from the ~81 MB Autzen Stadium survey up to New York City (26.5 GB, 4.76 B points) and Montréal (51.9 GB, 9.72 B points). Nothing is downloaded up front: pan and zoom, and watch only the octree nodes the camera can see get fetched.

It opens on the WGS84 ellipsoid with OpenStreetMap imagery, so no Cesium Ion token is needed. Supply one and Cesium World Terrain and satellite imagery become selectable from the Global tab.

Every dataset it streams is public, and credited individually in examples/DATA_SOURCES.md.

npm install copcesium cesium

cesium is a peer dependency (>=1.100.0) — install whichever version your app already uses. copcesium is ESM-only (no CommonJS build): the Worker and its laz-perf WASM are inlined into a single .mjs at build time, which needs import.meta.url semantics that require() can't provide.

copcesium itself needs no setup — its Worker and WASM are inlined into the published .mjs, so there's no side asset to wire up. CesiumJS does: it fetches Workers/, Assets/, Widgets/, and ThirdParty/ at runtime, and a bundler won't find those on its own. Skipping this step leaves a blank page and 404s in the console.

With Vite, vite-plugin-cesium handles it:

npm install -D vite-plugin-cesium

// vite.config.ts
import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium';

export default defineConfig({ plugins: [cesium()] });

Cesium also renders into an element you provide, which needs an explicit height — a container with no height produces a 0px canvas, which looks exactly like a broken build:

<!-- index.html -->
<style>
  html, body, #cesiumContainer { margin: 0; width: 100%; height: 100%; overflow: hidden; }
</style>

<div id="cesiumContainer"></div>
<script type="module" src="/main.ts"></script>

On another bundler, do the same two things by hand: copy node_modules/cesium/Build/Cesium/{Assets,ThirdParty,Widgets,Workers} into your static output, and point Cesium at them before the first import:

window.CESIUM_BASE_URL = '/cesium/';

import * as Cesium from 'cesium';
import { CopcDataSource } from 'copcesium';

const viewer = new Cesium.Viewer('cesiumContainer');

const dataSource = await CopcDataSource.load(
  'https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz',
  viewer,
);

That's it — load() fetches the COPC hierarchy, auto-detects the source coordinate system from the file's WKT (when present), flies the camera to the dataset, and starts streaming nodes as the camera moves. See examples/basic-viewer/main.ts for a slightly larger example with a URL input, live pixelSize/sseThreshold sliders, and error handling.

If the file's WKT doesn't fully describe the CRS (or is missing), pass it explicitly:

const dataSource = await CopcDataSource.load(url, viewer, {
  proj: 'EPSG:2992',
  projDef:
    '+proj=lcc +lat_1=43 +lat_2=45.5 +lat_0=41.75 +lon_0=-120.5' +
    ' +x_0=399999.9999999999 +y_0=0 +datum=NAD83 +units=ft +no_defs',
  geoidOffset: -20, // meters, local geoid separation from the WGS84 ellipsoid
});

When you're done with a data source:

dataSource.destroy();

All fields on the third argument to CopcDataSource.load() are optional.

interface CopcDataSourceOptions {
  proj?: string;
  projDef?: string | null;
  geoidOffset?: number;
  concurrency?: number;
  maxConcurrentRequests?: number;
  debounceMs?: number;
  maxCacheNodes?: number;
  maxCacheBytes?: number;
  maxVisibleNodes?: number;
  maxPoints?: number;
  pixelSize?: number;
  sseThreshold?: number;
  zFactor?: number;
  xyFactor?: number;
  autoFrame?: boolean;
  colorMode?: 'rgb' | 'intensity' | 'classification' | 'elevation';
  opacity?: number;
  classificationFilter?: number[];
  intensityRange?: [number, number];
}

Static factory — CopcDataSource has no public constructor. Resolves once the hierarchy is loaded (and, if autoFrame is enabled, once the camera has finished flying to the dataset).

• url: string — URL of the .copc.laz file. Must support HTTP Range Requests (see below).
• viewer: Cesium.Viewer
• options?: CopcDataSourceOptions — see Options.
• workerPool?: WorkerPool — an existing pool to decode in, instead of load() spinning up its own. WorkerPool is exported from the package; share one across data sources or across reloads to avoid re-spawning workers, since each carries its own laz-perf WASM instance. When you pass one, concurrency is ignored and destroy() leaves the pool alone. Omit it and each load() gets a private pool sized by concurrency.

class CopcDataSource {
  pixelSize: number;
  sseThreshold: number;
  colorMode: ColorMode;
  opacity: number;
  classificationFilter: number[] | undefined;
  intensityRange: [number, number];
  heightOffset: number;
  readonly maxDepth: number;
  readonly nodeCount: number;
  readonly cacheSize: number;
  readonly stats: CopcStats;
  zoomTo(): Promise<void>;
  destroy(): void;
}

dataSource.stats returns a CopcStats snapshot, so the streaming claim can be measured rather than taken on trust:

const { fileBytes, transferredBytes, requestCount } = ds.stats;
const pct = ((transferredBytes / fileBytes) * 100).toFixed(2);
console.log(`${pct}% of the file pulled, over ${requestCount} range requests`);

upload is timed on the first frame a node is actually drawn, so upload.count trails decode.count by however many nodes decoded but never made it on screen — that gap is information, not a dropped sample.

The Benchmark tab in examples/advanced-viewer is built on this.

Every point ships to the GPU with its colour, raw intensity, classification, and normalized elevation, and the colour is chosen in the vertex shader. Switching modes or filters is therefore a uniform update — no HTTP request, no LAZ decode, and the node cache is untouched.

const ds = await CopcDataSource.load(url, viewer);

ds.colorMode = 'classification';   // 'rgb' | 'intensity' | 'classification' | 'elevation'
ds.classificationFilter = [2, 6];  // draw only ground and buildings
ds.classificationFilter = undefined; // ...and back to everything
ds.opacity = 0.5;                  // 0..1, alpha blending below 1

The classification palette covers the ASPRS codes below; anything else draws in light grey.

Filtered-out points are discarded in the vertex shader, so filtering hides points rather than reclaiming their GPU memory.

copcesium fetches only the bytes it needs (COPC header, hierarchy pages, individual node point data) via HTTP Range Requests, not the whole file. Wherever you host .copc.laz files, the server must:

• Support Range request headers and respond with 206 Partial Content (Amazon S3, most static hosts, and CDNs do this by default).
• Send CORS headers (Access-Control-Allow-Origin) permitting your app's origin, since these are cross-origin fetch() calls unless the file is served from the same origin as your app.

For CORS, Range Request, and misplaced-cloud problems, see the Troubleshooting wiki page.

CopcDataSource auto-detects the source CRS and unit-conversion factors from the COPC file's WKT VLR when present — including compound CRSes (separate horizontal + vertical definitions, e.g. a state-plane CRS in feet with a NAVD88 vertical datum). If detection fails or you need to override it, pass proj/projDef explicitly (see Options).

Full details — the detection flow, the proj4 fallback table, vertical-unit (zFactor) handling, and a coordinate-debugging checklist — are on the Coordinate Systems wiki page.

examples/basic-viewer is a minimal, standalone project that installs copcesium from the npm registry (not from this repo's src/) — a URL input, pixelSize/sseThreshold sliders, a colorMode picker, per-class filter checkboxes, a "Remove & reload" button, and an on-screen error area. It loads a public sample dataset (Autzen Stadium) automatically.

examples/advanced-viewer is the fuller reference built on the same public API — a collapsible icon rail and tabbed sidebar, preset datasets, per-color-mode legends, terrain/imagery pickers, a camera/FPS HUD, and light/dark theming. This is what the live demo runs.

copcesium is framework-agnostic, but a large share of Cesium usage happens through React — two more examples show that integration:

• examples/react/react-viewer — the same minimal viewer, from a plain React component (useRef/useEffect, no wrapper library).
• examples/react/react-resium-viewer — a styled sidebar viewer built on resium, reaching copcesium's imperative API via resium's useCesium() hook.

git clone https://github.com/Jangmyun/copcesium.git
cd copcesium/examples/basic-viewer
npm install
cp .env.example .env   # optionally set VITE_CESIUM_TOKEN for Cesium Ion imagery
npm run dev

Then open the printed local URL in a browser. Each example under examples/ is run the same way — npm install && npm run dev from its own directory.

• Auto-tuning cache size and concurrency for very large point clouds, and optimizing for mobile and low-end GPUs. maxCacheNodes/maxCacheBytes, concurrency, and maxConcurrentRequests are static values you currently pick per dataset and per target device.
• Splitting workers and in-flight requests across several simultaneous data sources is still the caller's job. The pieces are exposed — load() takes a WorkerPool as its fourth argument, and concurrency/maxConcurrentRequests are options — but copcesium applies no policy of its own when more than one source is on screen.
• Staying a single file that works with no bundler configuration. Already true of the published package — the Worker and its laz-perf WASM are inlined into one .mjs at build time — and a constraint we intend to keep as the library grows.

Contributions are welcome — see CONTRIBUTING.md for how to build, test, and submit a pull request. This project follows a Code of Conduct. To report a security vulnerability, see SECURITY.md.

• copc — COPC parsing (header/hierarchy/point data, over HTTP Range Requests)
• laz-perf — WASM LAZ decompression
• proj4 — coordinate system transforms
• CesiumJS — 3D globe rendering

The live demo and all four examples stream public lidar surveys that other people flew, processed, and published. Per-dataset attribution, licences, and the method used to verify each origin are in examples/DATA_SOURCES.md. Where the original capturing organization could not be confirmed, that document says so explicitly rather than guessing.

These datasets are used here for demonstration only; copcesium's own MIT licence does not cover them. Check each source's terms before reusing the data.

copcesium is MIT licensed. The distributed build bundles third-party open-source code whose licenses and notices are collected in THIRD_PARTY_LICENSES.md. See CHANGELOG.md for release history.