Extract Vector glTF tile data into BufferPrimitiveCollection by danielzhong · Pull Request #13271 · CesiumGS/cesium

danielzhong · 2026-03-05T22:36:35Z

Description

This PR adds support for rendering glTF-based vector tile content using the current CESIUM_mesh_vector spec.

The runtime decodes the glTF, extracts vector data into BufferPrimitiveCollection types, and renders them through the existing buffer collection renderer path.

Supported vector primitive handling in this PR

POINTS → BufferPointCollection
LINE_STRIP → BufferPolylineCollection
- Primitive restart values are used to split a single indexed line strip into multiple polylines.
TRIANGLES → BufferPolygonCollection
- Polygon metadata is read from CESIUM_mesh_vector.
- The current implementation uses polygonAttributeOffsets, polygonIndicesOffsets, and optional hole metadata.

High-level flow

Cesium3DTileset loads a .gltf / .glb tile.
In Cesium3DTileContentFactory, glTF content is routed to VectorGltf3DTileContent when tileset.isGltfExtensionUsed("CESIUM_mesh_vector") is true.
VectorGltf3DTileContent.fromGltf() calls Model.fromGltfAsync() to decode the asset without rendering the model directly.
On the first update(), once the decoded model is ready, initializeVectorPrimitives() calls createVectorTileBuffersFromModelComponents().
createVectorTileBuffersFromModelComponents() converts glTF primitives into buffer collections:
- BufferPointCollection[]
- BufferPolylineCollection[]
- BufferPolygonCollection[]
One source mesh primitive maps to one buffer collection. Local node transforms are preserved per collection and applied through collection.modelMatrix during update.
On each frame, VectorGltf3DTileContent.update() updates each collection and calls collection.update(frameState).
Each collection uses the existing renderer path:
- renderBufferPointCollection
- renderBufferPolylineCollection
- renderBufferPolygonCollection

Issue number and link

Testing plan

Author checklist

I have submitted a Contributor License Agreement
I have added my name to CONTRIBUTORS.md
~~I have updated CHANGES.md with a short summary of my change~~
I have added or updated unit tests to ensure consistent code coverage
I have updated the inline documentation, and included code examples where relevant
I have performed a self-review of my code

…ollection-render-gl' into DanielZhong/VectorTiles

github-actions · 2026-03-05T22:36:56Z

Thank you for the pull request, @danielzhong!

✅ We can confirm we have a CLA on file for you.

…ollection-render-gl' into DanielZhong/VectorTiles

donmccurdy

@danielzhong Great progress here, I like how this is coming together! I left a few initial comments, mainly since we're writing the code and the spec in parallel just trying to make sure things align.

donmccurdy · 2026-03-06T22:13:29Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  const values = new Float64Array(indices.length * 3);
+  for (let i = 0; i < indices.length; i++) {
+    const vertexIndex = indices[i];
+    const srcOffset = vertexIndex * 3;
+    values[i * 3] = positions[srcOffset];
+    values[i * 3 + 1] = positions[srcOffset + 1];
+    values[i * 3 + 2] = positions[srcOffset + 2];
+  }
+
+  polylineCollection.add({ positions: values }, polylineView);
+  setPrimitiveFeatureId(polylineView, featureIdSource, indices[0]);


I'm hoping we'll be able to upload a range of the position array directly to the collection, but I guess the collection needs to allow more than float64array here? Opened:

BufferPrimitiveCollection: Allow any TypedArray position/index storage #13277

donmccurdy · 2026-03-06T22:14:21Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  if (primitiveType === PrimitiveType.TRIANGLE_STRIP) {
+    triangleIndices =
+      ModelReader.convertTriangleStripToTriangleIndices(indices);
+  } else if (primitiveType === PrimitiveType.TRIANGLE_FAN) {
+    triangleIndices = ModelReader.convertTriangleFanToTriangleIndices(indices);
+  }


I think it's OK just to error out if the primitive uses the vector extension with TRIANGLE_STRIP or TRIANGLE_FAN topology, since we won't be able to identify the original polygon connectivity in those cases anyway.

donmccurdy · 2026-03-06T22:14:51Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  polygonCollection.add(
+    {
+      positions: positions,
+      triangles: toUint32Array(triangleIndices),


See above, with #13277 it should be OK to use whatever the source array type is.

donmccurdy · 2026-03-06T22:16:08Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  polygonView,
+) {
+  const primitiveType = primitive.primitiveType;
+  const positions = readTransformedPositions(primitive, nodeTransform);


Do we need to transform the vertex positions? I'm hoping that we can apply the node transform to collection.modelMatrix or something like that, but not 100% sure how this all fits with the rest of the loading process!

donmccurdy · 2026-03-06T22:16:48Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  if (PrimitiveType.isLines(primitiveType) && defined(polylineCollection)) {
+    if (primitiveType === PrimitiveType.LINES) {
+      for (let i = 0; i + 1 < indices.length; i += 2) {
+        appendPolylinePrimitive(
+          polylineCollection,
+          polylineView,
+          featureIdSource,
+          positions,
+          [indices[i], indices[i + 1]],
+        );
+      }
+    } else if (primitiveType === PrimitiveType.LINE_STRIP) {
+      appendPolylinePrimitive(
+        polylineCollection,
+        polylineView,
+        featureIdSource,
+        positions,
+        indices,
+      );
+    } else if (primitiveType === PrimitiveType.LINE_LOOP) {
+      const loopIndices = new Uint32Array(indices.length + 1);
+      for (let i = 0; i < indices.length; i++) {
+        loopIndices[i] = indices[i];
+      }
+      loopIndices[indices.length] = indices[0];
+      appendPolylinePrimitive(
+        polylineCollection,
+        polylineView,
+        featureIdSource,
+        positions,
+        loopIndices,
+      );
+    }
+    return;


Here I think it's OK if we throw an error if we see any primitive types not allowed by the vector extension.

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

…ollection-typedarray' into DanielZhong/VectorTiles # Conflicts: # packages/engine/Source/Scene/BufferPolygonCollection.js

…to DanielZhong/VectorTiles

…ollection-render-gl' into DanielZhong/VectorTiles

donmccurdy

Awesome work, thanks Daniel! Just a few comments, no major concerns on my side.

I'd slightly prefer fewer defensive checks still, but that's easier to do with the // @ts-check suggestion which might be out of scope here, so not a big deal for now. Tests are working well locally.

Heads up that in earlier version of the sample tilesets I generated, the "extensionsUsed" property wasn't declared properly and the tilesets could go down the existing glTF rendering path rather than using the new vector code. I've fixed the tilesets: polylines and polygons are working as-is, there's a small fix needed for points I think (see comments).

Approving now since the comments are mostly optional stuff, the point primitive fix is the only critical thing.

donmccurdy · 2026-03-19T21:12:28Z

packages/engine/Source/Scene/Multiple3DTileContent.js

  const url = multipleContents._innerContentResources[index].url;
  const message = defined(error.message) ? error.message : error.toString();
-  if (tileset.tileFailed.numberOfListeners > 0) {
+  if (defined(tileset.tileFailed) && tileset.tileFailed.numberOfListeners > 0) {


Do you recall why this change was needed? I'm not seeing errors if I remove it currently, maybe it can be removed?

If related to my sample tilesets ... those were just thrown together with a quick script, so mostly I'm wanting to check that we're not adding workarounds for what might have been invalid data on my part. :)

donmccurdy · 2026-03-19T21:17:27Z

packages/engine/Source/Scene/VectorGltf3DTileContent.js

Entirely optional suggestion, feel very free to skip this — For new files you might find it helpful to include a // @ts-check comment at the top of the file. If you're using an editor with TypeScript Language Services enabled (like VSCode or Zed) you should start to see better autocomplete, and errors where type information is missing or conflicting. Any errors visible in the editor will also be reported by npm run tsc.

For example if #13313 happens to merge before this PR, npm run tsc would start complaining about calls to point.setColor(...) (which has been removed).

We could certainly do this in a future PR too.

donmccurdy · 2026-03-19T21:24:20Z

packages/engine/Source/Scene/VectorGltf3DTileContent.js

+    this._decodeModel = this._decodeModel && this._decodeModel.destroy();
+    this._pointCollections = undefined;
+    this._polylineCollections = undefined;
+    this._polygonCollections = undefined;
+    this._vectorBuffers = undefined;


It would be best to destroy the collections before we dereference them:

for (const collection of this._pointCollections) { collection.destroy(); } this._pointCollections = undefined;

donmccurdy · 2026-03-19T21:35:02Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+  if (points.length === 0 && polylines.length === 0 && polygons.length === 0) {
+    return undefined;
+  }
+
+  return {
+    points: points.length > 0 ? points : undefined,
+    polylines: polylines.length > 0 ? polylines : undefined,
+    polygons: polygons.length > 0 ? polygons : undefined,
+  };


Optional - I think if we allowed empty arrays here, and made the arrays non-nullable, we'd need fewer if/defined protections elsewhere in the PR. But that sort of change is easier to do safely with the // @ts-check mode on, which might be out of scope for this PR, so feel free to leave this as-is too. :)

Suggested change

if (points.length === 0 && polylines.length === 0 && polygons.length === 0) {

return undefined;

}

return {

points: points.length > 0 ? points : undefined,

polylines: polylines.length > 0 ? polylines : undefined,

polygons: polygons.length > 0 ? polygons : undefined,

};

return { points, polylines, polygons };

donmccurdy · 2026-03-19T21:38:24Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+      continue;
+    }
+
+    collection._vectorLocalModelMatrix = Matrix4.clone(nodeTransform);


Hm, I was hoping it might be possible to avoid putting extra data onto the collection, but I don't see an obvious way right now. Not sure if that should be the responsibility of the Cesium3DTiles classes or if the BufferPrimitiveCollection needs more metadata. Ok with me as-is though, no changes needed for now unless you have more thoughts on it.

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

donmccurdy · 2026-03-19T21:57:54Z

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

+function getFeatureId(featureIdSource, vertexIndex) {
+  if (!defined(featureIdSource)) {
+    return undefined;
+  }
+
+  let featureId;
+  if (defined(featureIdSource.values)) {
+    if (vertexIndex < 0 || vertexIndex >= featureIdSource.values.length) {
+      return undefined;
+    }
+    featureId = featureIdSource.values[vertexIndex];
+  } else {
+    featureId =
+      Math.floor(vertexIndex / featureIdSource.repeat) + featureIdSource.offset;
+  }
+
+  featureId = Math.trunc(featureId);
+  if (
+    defined(featureIdSource.nullFeatureId) &&
+    featureId === featureIdSource.nullFeatureId
+  ) {
+    return undefined;
+  }
+  return featureId;
+}


It seems like we're re-implementing a bit from packages/engine/Source/Scene/Model/FeatureIdPipelineStage.js here and in getFeatureIdSource above. That's probably OK, I don't see an easier way to access its results, maybe it's just worth including a TODO for later.

packages/engine/Source/Scene/Model/createVectorTileBuffersFromModelComponents.js

lilleyse

I did a quick pass, not going super deep. The approach here looks good.

danielzhong added 3 commits March 4, 2026 19:31

Merge remote-tracking branch 'origin/donmccurdy/feat/bufferprimitivec…

17d1ef0

…ollection-render-gl' into DanielZhong/VectorTiles

temp save work

e44bb16

remove GPU lookup

b270243

danielzhong requested a review from donmccurdy March 5, 2026 22:36

danielzhong changed the base branch from main to donmccurdy/feat/bufferprimitivecollection-render-gl March 5, 2026 22:37

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-render-gl to donmccurdy/feat/bufferprimitivecollection-render-gl-v2 March 5, 2026 22:38

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-render-gl-v2 to donmccurdy/feat/bufferprimitivecollection-render-gl March 5, 2026 22:39

danielzhong added 4 commits March 5, 2026 17:44

Merge remote-tracking branch 'origin/donmccurdy/feat/bufferprimitivec…

91cca30

…ollection-render-gl' into DanielZhong/VectorTiles

fix

4cd999a

lint

5480ab7

fix test

19c4052

donmccurdy reviewed Mar 6, 2026

View reviewed changes

Merge remote-tracking branch 'origin/donmccurdy/feat/bufferprimitivec…

a2e44b5

…ollection-typedarray' into DanielZhong/VectorTiles # Conflicts: # packages/engine/Source/Scene/BufferPolygonCollection.js

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-render-gl to donmccurdy/feat/bufferprimitivecollection-render-gl-v2 March 9, 2026 01:43

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-render-gl-v2 to donmccurdy/feat/bufferprimitivecollection-typedarray March 9, 2026 01:44

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-typedarray to donmccurdy/feat/bufferprimitivecollection-render-gl March 9, 2026 01:52

danielzhong added 2 commits March 8, 2026 23:57

update

49ffec7

Merge branch 'donmccurdy/feat/bufferprimitivecollection-render-gl' in…

3e75da1

…to DanielZhong/VectorTiles

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-render-gl to donmccurdy/feat/bufferprimitivecollection-typedarray March 9, 2026 04:33

danielzhong changed the base branch from donmccurdy/feat/bufferprimitivecollection-typedarray to donmccurdy/feat/bufferprimitivecollection-render-gl March 9, 2026 04:34

danielzhong added 3 commits March 9, 2026 14:38

Merge branch 'donmccurdy/feat/bufferprimitivecollection-render-gl' in…

73db7b2

…to DanielZhong/VectorTiles

Merge remote-tracking branch 'origin/donmccurdy/feat/bufferprimitivec…

ef7b1aa

…ollection-render-gl' into DanielZhong/VectorTiles

Merge remote-tracking branch 'origin/donmccurdy/feat/bufferprimitivec…

53acb4d

…ollection-render-gl' into DanielZhong/VectorTiles

Base automatically changed from donmccurdy/feat/bufferprimitivecollection-render-gl to main March 11, 2026 15:43

danielzhong and others added 5 commits March 11, 2026 11:46

Merge branch 'main' into DanielZhong/VectorTiles

9b1d15f

Cesium3DTileset: Support CESIUM_mesh_vector, add samples

631394b

Cesium3DTileset: Regenerate samples

6bb310c

extract line/polygon infos from glb files

3fdf7b0

allocate one buffer collection per source mesh primitive

eede5c8

danielzhong added 10 commits March 16, 2026 21:30

Merge branch 'main' into DanielZhong/VectorTiles

03819b9

ES6

1143deb

test sample

97bcc8e

fix

f82fa55

update

088decc

Merge branch 'main' into DanielZhong/VectorTiles

ce77229

update

ad37d1f

scratchPointPosition

94ec728

update

7a61273

update

c1f9d7b

danielzhong requested a review from donmccurdy March 17, 2026 20:20

donmccurdy mentioned this pull request Mar 17, 2026

BufferPrimitiveMaterial: Proposal for large vector collections in linear memory #13156

Closed

donmccurdy added 2 commits March 19, 2026 17:59

Remove TODO

12163a9

Fix extensions in sample tilesets

a6bf602

donmccurdy approved these changes Mar 19, 2026

View reviewed changes

donmccurdy added 2 commits March 20, 2026 09:21

Merge branch 'main' into DanielZhong/VectorTiles

a5a07b0

fix(BufferPoint): Allow non-indexed points

b976475

lilleyse reviewed Mar 20, 2026

View reviewed changes

danielzhong added 6 commits March 20, 2026 13:19

update

5fcd46f

update

373817a

update

b3e30f2

update

49bd15c

Merge branch 'main' into DanielZhong/VectorTiles

e07e785

update

b634e6d

danielzhong added this pull request to the merge queue Mar 20, 2026

Merged via the queue into main with commit 75ca7f2 Mar 20, 2026
5 checks passed

danielzhong deleted the DanielZhong/VectorTiles branch March 20, 2026 17:58

donmccurdy mentioned this pull request Mar 20, 2026

Types: Use types in VectorGltf3DTileContent #13321

Merged

6 tasks

danielzhong self-assigned this Mar 24, 2026

Conversation

danielzhong commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Supported vector primitive handling in this PR

High-level flow

Issue number and link

Testing plan

Author checklist

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

donmccurdy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

donmccurdy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danielzhong Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lilleyse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

danielzhong commented Mar 5, 2026 •

edited

Loading

danielzhong Mar 20, 2026 •

edited

Loading