MIGRATING

Already running Potree?
Your data comes as it is.

There is no reconversion step. The metadata.json, hierarchy.bin and octree.bin already on your server are what the Potree v2 driver reads — the same bytes, over the same HTTP Range requests, verified against Potree’s own implementation. What changes is the code around them.

What you point it at

Either the directory or the metadata.json inside it. The loader identifies the format from what it finds, which is why the same call keeps working if you later republish the cloud as COPC or EPT — both drivers are on npm, and registering one is a single call.

import { PointCloudViewer } from '@voxelkloud/react'

// The same directory PotreeConverter already wrote.
<PointCloudViewer
  url="/pointclouds/my-cloud/"
  lod={{ pointBudget: 3_000_000 }}
/>

Or without a framework, where the three.js scene stays yours:

import { loadPointCloud } from '@voxelkloud/loader'
import { createPointCloudView } from '@voxelkloud/view'

const { source, tree, openPoints } = await loadPointCloud('/pointclouds/my-cloud/')

const view = createPointCloudView({ canvas })
await view.init()
view.addCloud(source, tree, openPoints)
view.frameCloud()

// view.scene and view.camera are your three.js objects.
new OrbitControls(view.camera, canvas)

The two things that catch people

BROTLI clouds need a decoder

No browser exposes brotli to JavaScript — DecompressionStream handles gzip and deflate only — so a cloud converted with --encoding BROTLI needs one passed in. It is a separate subpath so the ~180 KB never lands in a bundle that does not need it.

import { brotliDecompress } from '@voxelkloud/loader/brotli'

createPointCloudView({ canvas, decompress: brotliDecompress })

Range requests are not optional

Streaming a cloud means asking for byte ranges of octree.bin. A host that answers 200 to a Range request instead of 206 cannot serve one — the same requirement Potree has, and the same misconfiguration that breaks it.

voxelkloud doctor <url> asks your host directly: whether it answers 206, whether a browser is allowed to read the range headers back, and whether something in front of it is compressing a payload that is already compressed. It grades the Potree deployment you have today and exits non-zero when one of them is wrong. In source with the drivers; not on npm yet.

What you should know before you switch