3D Tiles and point clouds

GeoLens can host two 3D data types: 3D Tiles tilesets and COPC point clouds. Each becomes a dataset in the catalog with its own page, search entry, visibility setting and API-key access. External clients such as CesiumJS, QGIS and Potree load the data from GeoLens.

What you can upload

Type	File	Accepted content
3D Tiles	`.3tz` or `.zip` archive, by file or by URL	A tileset that declares `asset.version` `1.0` or `1.1`, with `tileset.json` at the archive root or inside one folder
COPC point cloud	`.laz`, by file	A COPC file: LAS 1.4, point format 6, 7 or 8, with a coordinate reference system that has an EPSG code

Both appear in the Upload File tab of Import as a choice under What are you uploading?. Pick 3D Tiles tileset or COPC point cloud before you drop the file. A .3tz or .laz dropped in the Geospatial files choice is refused with a message that names the right one. A zip is ambiguous (it could be a Shapefile), so a tileset zip is only treated as a tileset when you choose that option.

The 3D Tiles tileset choice is also available in the File URL tab, so the server can fetch a tileset archive from a link.

Over the API, send kind=tiles3d or kind=pointcloud with the upload. See Writing to the catalog.

What GeoLens checks

3D Tiles. GeoLens reads the archive’s directory and tileset.json, then validates the layout, every tile’s content and every URI the tiles point to. Absolute or path-escaping URIs are refused. It records the content types it finds (such as b3dm, i3dm, pnts, cmpt, glb and implicit-tiling subtrees) and any required extensions. The tileset is stored unpacked and served as is.
COPC. GeoLens validates the header, the hierarchy and every point before it publishes the file. A file that fails any of these is refused with a reason.

Converting LAS and LAZ to COPC

GeoLens does not convert point clouds yet. A plain LAS or LAZ file is refused with a message that says it is not COPC. Convert it first with PDAL’s writers.copc or untwine, then upload the result. Open work on in-app conversion is tracked in geolens-io/geolens#2883.

Limits

Archive or file size. The upload limit applies: UPLOAD_MAX_SIZE_MB, default 500 MB. See Upload mode.
Unpacked tileset size. MAX_TILESET_UNPACKED_MB (default 20480) and MAX_TILESET_ENTRIES (default 100000) bound a tileset. Both are checked against the archive’s directory before anything is unpacked.
Storage quota. A tileset counts at its unpacked size, a point cloud at its file size. The quota is checked again when you commit the import.
Allowed extensions. .3tz and .laz are in the default UPLOAD_ALLOWED_EXTENSIONS, but an admin-saved list takes precedence. If an instance saved its list before these types existed, the choices show as unavailable until an admin adds the extensions in Admin → Storage. See the Configuration reference.

The dataset page

After the import job completes, open the dataset. The overview shows the facts GeoLens recorded, and the Access tab shows the URL and client examples.

Type	Facts shown
3D Tiles	Version, root geometric error, bounding volume, extent, unpacked size, tile content types, required extensions
COPC	Point count, file size, point format, geographic bounds, horizontal and vertical CRS, elevation range

The extent is outlined on a map preview when the dataset has one. A tileset whose root bounding volume is a georeferenced box or sphere gets an extent. One that is not georeferenced may show “No extent recorded.”

Both types are also advertised in the dataset detail response, OGC API Records and the DCAT feeds.

Opening a dataset in a client

The Access tab gives the dataset’s file URL. For a tileset that is /api/datasets/{id}/tiles3d/tileset.json on a default install, and for a point cloud it is a versioned .copc.laz URL. Copy it from the page; a replaced point cloud file gets a new URL and the old one answers 404.

Authentication

A public dataset needs no credentials. For anything else, send a read-only API key in the X-Api-Key header. Create one under your account settings, and see API Authentication for the options. The examples on the dataset page contain a placeholder, never your key.

A query-string api_key authenticates only the request it is on. A 3D Tiles client resolves relative tile URIs against the tileset, so the key is lost unless the client carries it over. CesiumJS does this through Resource headers or query parameters. Prefer the header wherever the client can send it.

CesiumJS (3D Tiles)

const tileset = await Cesium.Cesium3DTileset.fromUrl(
  new Cesium.Resource({
    url: "https://your-geolens.example/api/datasets/DATASET_ID/tiles3d/tileset.json",
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }),
);
viewer.scene.primitives.add(tileset);

For a public tileset, pass the URL alone and omit headers. CesiumJS sends the key with every request it makes while loading, so use a read-only key.

QGIS (COPC)

In QGIS, choose Layer → Add Layer → Add Point Cloud Layer, set Source type to Protocol: HTTP(S), cloud, etc., and paste the COPC URL. QGIS 3.26 or later opens a public file. A private file needs QGIS 4.0 or later, which supports API Header authentication: add the header X-Api-Key with your key.

Potree and copc.js (COPC)

// Potree
Potree.loadPointCloud(
  "https://your-geolens.example/api/datasets/DATASET_ID/copc/ATTEMPT_ID/data.copc.laz",
  "Point cloud",
  (event) => {
    viewer.scene.addPointCloud(event.pointcloud);
    viewer.fitToScreen();
  },
);

Potree cannot send an X-Api-Key header for COPC. For a private point cloud, append ?api_key=YOUR_API_KEY to the URL and treat the resulting URL as a secret. copc.js can send the header from a custom range reader: wrap fetch with a Range: bytes=begin-end header and X-Api-Key, and pass that function to Copc.create.

Loading from another website

A page on another origin can read a public tileset or COPC file without credentials, including by byte range. Sending credentials is different:

A page that sends X-Api-Key or Authorization headers to the API must have its origin in CORS_ALLOWED_ORIGINS. Add it in Admin → Settings → Network, or set the variable. See the Configuration reference.
For COPC files, the bundled web server accepts credentialed headers from any origin. The API on its own accepts them only from the allowlist.

Private datasets answer 404 to callers without access, and a missing or replaced point cloud also answers 404.

COPC reads are rate limited per client: 1200 reads a minute, plus a byte budget for ranged reads. A request over a limit answers 429. The API reference lists the exact figures on the file route.

Current limits

No in-app rendering. A viewer on the dataset page comes first and is tracked in geolens-io/geolens#2797.
No LAS or LAZ conversion. Upload COPC only. See geolens-io/geolens#2883.
A point cloud can be uploaded by file only. The File URL tab accepts tilesets, not point clouds.
Replacing a tileset or point cloud keeps no previous version, so keep a copy of the source.