Skip to content

RUN.md

Latest commit

 

History

History
267 lines (194 loc) · 6.06 KB

RUN.md

File metadata and controls

267 lines (194 loc) · 6.06 KB
Raw

🚀 COPC-Cesium Run Guide

✅ Installation Complete!

Dependencies have been installed successfully.

📝 How to Run

1️⃣ Start the Dev Server (Recommended)

npm run dev

After running:

Other demos are available too - see Project Structure below.

2️⃣ Build the Library

npm run build

Build output:

dist/
├── index.cjs          # CommonJS bundle
├── index.esm.js       # ES Module bundle
├── index.d.ts          # TypeScript type definitions
└── *.map                # Source maps

3️⃣ Test with a Static Server

# After building
npm run build

# Start an HTTP server
npx http-server . -p 8080

# Open in browser
# http://localhost:8080/examples/basic.html

💻 Usage Example

JavaScript/TypeScript

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

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

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

// Initialize and load
await provider.initialize();
await provider.loadRootNode();

// Add to the scene (pass getPrimitive()'s return value, not the provider itself)
viewer.scene.primitives.add(provider.getPrimitive());

// Camera-based LOD/culling isn't automatic - drive it yourself every frame
viewer.scene.postRender.addEventListener(() => {
  provider.update(viewer.scene.frameState);
});

🎨 Configuration Options

Color Modes

colorMode: 'rgb'             // RGB color (default)
colorMode: 'elevation'       // Elevation-based color
colorMode: 'intensity'       // Intensity-based color
colorMode: 'classification'  // Classification-based color

Memory Settings

maximumMemoryUsage is the budget (in MB) for the LRU cache that holds decoded data for nodes that have scrolled out of view. Nodes currently visible on screen are never evicted regardless of this budget - a wide view with many simultaneously-visible nodes can still use more memory than this value.

Web Worker Decoding (main thread by default)

workerUrl: new URL('../src/workers/laz-decoder.worker.ts', import.meta.url),
workerPoolSize: 4  // optional, default 4

LOD Quality

maximumScreenSpaceError: 32  // faster loading
maximumScreenSpaceError: 16  // balanced (default)
maximumScreenSpaceError: 4   // higher quality

Point Size

pointSize: 1  // small (dense data)
pointSize: 2  // medium (default)
pointSize: 4  // large (sparse data)

🔍 Troubleshooting

Dev server won't start

# If the port is already in use
npm run dev -- --port 5174

# Or kill the process and retry
lsof -ti:5173 | xargs kill -9
npm run dev

Build errors

# Reinstall node_modules
rm -rf node_modules package-lock.json
npm install

# Clear the build output
rm -rf dist
npm run build

CORS errors

# Use a server that allows CORS
npx http-server . -p 8080 --cors

📂 Project Structure

copc-cesium/
├── src/                      # Source code
│   ├── index.ts              # Entry point
│   ├── types.ts              # Type definitions
│   ├── COPCPointCloudProvider.ts
│   ├── core/                 # COPC parsing
│   ├── render/                # GPU rendering
│   ├── network/                # HTTP Range requests
│   ├── culling/                # LOD & frustum culling
│   ├── cache/                  # Memory management
│   ├── transform/               # Coordinate transforms
│   └── workers/                # Worker pool + laz-decoder.worker.ts
├── demo/                     # Demo pages
│   ├── autzen.html           # Autzen Stadium COPC (LOD/culling walkthrough)
│   ├── canelevation.html     # CanElevation LiDAR (remote S3 streaming)
│   ├── sofi.html             # SoFi Stadium LiDAR (large ~364M point file)
│   └── with-3d-tiles.html    # COPC + a native Cesium3DTileset in one scene
├── examples/                 # Examples
│   └── basic.html
└── dist/                     # Build output (generated)

📚 Further Reading

⚙️ System Requirements

  • ✅ Node.js 18+
  • ✅ npm 9+
  • ✅ A modern browser (WebGL support)
  • ✅ HTTP Range Request support
  • Web Workers support is only needed if you use the workerUrl option

🎯 Next Steps

  1. Start the dev server

    npm run dev

  2. Check out the example files

    • examples/basic.html
    • demo/autzen.html (the main working demo)

  3. Test with your own COPC file

    • Place a COPC file in a public/data/ folder (served by Vite's publicDir)
    • Point the url option at /data/your-file.copc.laz

  4. Read the docs

    • See API.md for the full list of options
    • See SETUP.md for advanced configuration

📌 Notes

Cesium Ion Token

The demos work out of the box using CesiumJS's bundled default community token - no setup required. If you use your own Cesium Ion assets (World Terrain/Imagery, etc.) in production, get your own token:

  1. Create a free account at https://cesium.com/ion/signup
  2. Copy your token
  3. Set it on the page that uses it: 
    Cesium.Ion.defaultAccessToken = 'YOUR_TOKEN_HERE';

Hosting COPC Files

COPC files must be hosted on a server that supports HTTP Range Requests:

  • ✅ AWS S3
  • ✅ Google Cloud Storage
  • ✅ Azure Blob Storage
  • ✅ A local http-server (for development)

🚀 Get Started Now

npm run dev

Happy Coding! 🎉