Add support for GLTF extension: EXT_mesh_primitive_edge_visibility #12859

danielzhong · 2025-08-30T04:50:27Z

Description

This PR implements the proposed GLTF extension EXT_mesh_primitive_edge_visibility, enabling edge rendering for glTF mesh primitives. It adds multi-pass rendering to avoid z-fighting, and implements decoding, creation, and rendering of both hard and silhouette edges:

Parsing and handling mesh primitive data of visibility (edge type: HIDDEN, SILHOUETTE, HARD, REPEATED) and silhouette normal.
Hard edge & silhouette edge rendering.
Multi-pass rendering path (CESIUM_3D_TILE_EDGES) to draw edges before surfaces (CESIUM_3D_TILE).
Feature ID/Depth integration to ensure edges display correctly without Z fighting and overlapping.

More details: Edge Visibility

Example
(green edge = hard edge; red edge = silhouette edge):

Issue number and link

#12765

Testing plan

Added Unit test for Edge Frame Buffer, MRT & Shader Color Attachments, Decoding logic, Shader Generation, etc.
Real Time Demo
Local Test File:
super_simple_3.bim-tiles.zip

How to Run:

Download the file and host: http-server ./ --cors=X-Correlation-Id
Open sandcastle and paste:

const viewer = new Cesium.Viewer("cesiumContainer", {
 
  infoBox: false,
 
  selectionIndicator: false,
 
  shadows: true,
 
  shouldAnimate: true,
 
});
const tileset = await Cesium.Cesium3DTileset.fromUrl(
 
  "http://172.20.20.20:8081/tileset.json"
 
);
 
viewer.scene.primitives.add(tileset);
 
await viewer.zoomTo(tileset);

Make sure change your local host address in the code!

((green edge = hard edge; red edge = silhouette edge):)

🔍Review Notes

The glTF extension’s material support is not included in this PR. I'm planning to set all edges default to black.
Updated getWebGLStub.js to support MRT in coverage tests.
This PR is ready to review!

Bug Fix Summary

Edge rendering was incorrect because GL_LINES and edge primitives shared the same VAO. Fixed by creating a separate VAO for edge rendering.
Added an edge-rendering pipeline stage in modelFS.glsl. The model runtime primitive couldn’t detect the render tag (it runs too early), so I introduced a uniform flag to detect when the pipeline stage is active.
MRT couldn’t clear buffers/color attachments. Fixed by using clearCommand in EdgeFramebuffer.js.
MRT was failing unit tests. Fixed by updating getWebGLStub.js to support MRT in coverage tests.
Silhouette edges bug: in top-down views, the silhouette normal calculation wasn’t accurate enough.

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
Change outline render color back to white
Fix issue where edge should not be visible through geometry

danielzhong · 2025-09-18T00:48:42Z

@ggetz @lilleyse I’ve fixed the edge depth bug that caused geometry can see through edges. The latest screenshot have been updated in the description. Demo link will update ASAP, since not sure why there are some unrelated timeout build errors in Github. This is now ready for the next round of review, thank you!

This reverts commit bc16ca0, reversing changes made to afe6e41.

This reverts commit 7da8453.

This reverts commit bcc5f55.

This reverts commit 90699e1.

danielzhong · 2025-09-18T16:42:26Z

@ggetz @lilleyse I’ve fixed the edge depth bug that caused geometry can see through edges. The latest screenshot have been updated in the description. Demo link will update ASAP, since not sure why there are some unrelated timeout build errors in Github. This is now ready for the next round of review, thank you!

Demo Link updated as well

lilleyse

@danielzhong Excellent job with this PR!

Just a few comments from me.

lilleyse · 2025-09-19T15:00:16Z

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

+  shaderBuilder.addVarying("vec3", "v_faceNormalBView", "flat");
+
+  // Add varying for view space position for perspective-correct silhouette detection
+  shaderBuilder.addVarying("vec3", "v_positionView", "");


I don't know offhand... does Model already have a varying for this?

Yes, you are right. Fixed!

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

lilleyse · 2025-09-19T15:28:21Z

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

+ * @returns {{edgeMap:Map<string, number[]>, faceNormals:Float32Array, triangleCount:number}}
+ * @private
+ */
+function buildTriangleAdjacency(primitive) {


For this function and others that are doing a lot of math see if you can use Cartesian3 types and Cartesian3 math operations (e.g. Cartesian3.cross). Also try to use scratch variables wherever possible to avoid heap allocations.

Modified, please review again! Thanks!

lilleyse · 2025-09-19T15:32:01Z

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

+  const positions = defined(positionAttribute.typedArray)
+    ? positionAttribute.typedArray
+    : ModelReader.readAttributeAsTypedArray(positionAttribute);


Do you foresee any issues if positions are quantized?

Added, please review.

lilleyse · 2025-09-19T15:35:26Z

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

+  const renderState = clone(command.renderState, true);
+  edgeCommand.renderState = RenderState.fromCache(renderState);


Is the render state actually modified?

I forgot to clean it up. Fixed!

lilleyse · 2025-09-19T15:46:45Z

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

+  // Use a very large bounding volume to avoid culling issues
+  edgeCommand.boundingVolume = new BoundingSphere(
+    Cartesian3.ZERO,
+    Number.MAX_VALUE,
+  );


This could have some performance side effects.

createPotentiallyVisibleSet determines the near / far planes from the commands' bounding volumes and ideally we want these to be as tight as possible to avoid needing to render with multiple frustums.

I'm curious about the culling issues you were seeing, because it seems like it should be fine to use the original command's boundingVolume.

lilleyse · 2025-09-19T16:06:54Z

packages/engine/Source/Scene/OIT.js

+  //
+  // CESIUM_REDIRECTED_COLOR_OUTPUT: A general-purpose flag to indicate that this shader
+  // is a derived/modified version created by Cesium's rendering pipeline.
+  // This flag can be used to avoid color attachment conflicts when shaders
+  // need different output declarations for different rendering passes.
+  // For example, MRT (Multiple Render Targets) features can check this flag
+  // to conditionally declare their output variables only when not conflicting
+  // with the derived shader's output layout.


I'm a bit rusty here, but is the problem that the edge visibility code, even though it's not executed in the OIT pass, has output declarations that are incompatible with OIT's output declarations?

If that's the case, this seems like an okay approach, short of other approaches that would require refactoring the model pipeline.

Co-authored-by: Sean Lilley <lilleyse@gmail.com>

danielzhong · 2025-09-19T17:55:08Z

@lilleyse Not sure why I can't reference or reply. But yes, that’s the root cause. Do you think I should include the refactor in this PR, or would it be better to open a new PR for it later?

lilleyse · 2025-09-19T18:10:15Z

@danielzhong oh I think that comment is part of this comment thread: #12859 (comment)

I would just open an issue for now.

This reverts commit 335d7bc.

This reverts commit bad1aa1.

danielzhong · 2025-09-19T20:28:47Z

@lilleyse @ggetz Ready for next round review!

javagl · 2025-09-24T12:05:57Z

The EdgeVisibility.glb is invalid. The errors are

         {
                "code": "VALUE_NOT_IN_RANGE",
                "message": "Value 1 is out of range.",
                "severity": 0,
                "pointer": "/bufferViews/5/byteStride"
            },
            {
                "code": "VALUE_NOT_IN_RANGE",
                "message": "Value 1 is out of range.",
                "severity": 0,
                "pointer": "/bufferViews/12/byteStride"
            },

CesiumJS does not render anything for this model. (Opening and re-exporting it with gltf.report generates a model that can be rendered with CesiumJS. Whether or not that is related to the validation error remains to be investigated).

The model uses

  "extensionsUsed" : [
    "KHR_mesh_quantization",
    "EXT_mesh_features",
    "EXT_mesh_primitive_edge_visibility",
    "EXT_structural_metadata"
  ],

There should be test model that uses EXT_mesh_primitive_edge_visibility and only EXT_mesh_primitive_edge_visibility - no other extension that might interfere with the baseline test for this extension. Such a model would also be useful, eventually, in the context of KhronosGroup/glTF#2479 , for implementors to test.

I did not peform a thorough review of this PR! It only caught my attention due to #12914 . And when I saw https://github.com/CesiumGS/cesium/pull/12859/files/1c9ba9d2415aa507cce107d91938d10c9e707cd1#diff-20964905fdcbaf8679c56d995e848ed68a3c0f08d868ad38c5d794145b0fbbc6R70, I thought: Wait, that can hardly be right. Edge visibility and feature IDs are totally unrelated. Maybe these defines are the crux here, and maybe there is some if (hasFeatureIds) doThis(); else dont(); that I overlooked and that prevents this from being executed when no feature IDs are present. If this is the case, it should be documented more extensively. And if this is the case, then it should thoroughly explain why it can rely on the featureId_0, and not any other feature ID.
// We know that featureId_0 is present here, because [text]

danielzhong · 2025-09-25T05:51:48Z

The EdgeVisibility.glb is invalid. The errors are
         {
                "code": "VALUE_NOT_IN_RANGE",
                "message": "Value 1 is out of range.",
                "severity": 0,
                "pointer": "/bufferViews/5/byteStride"
            },
            {
                "code": "VALUE_NOT_IN_RANGE",
                "message": "Value 1 is out of range.",
                "severity": 0,
                "pointer": "/bufferViews/12/byteStride"
            },
CesiumJS does not render anything for this model. (Opening and re-exporting it with gltf.report generates a model that can be rendered with CesiumJS. Whether or not that is related to the validation error remains to be investigated).

The model uses
  "extensionsUsed" : [
    "KHR_mesh_quantization",
    "EXT_mesh_features",
    "EXT_mesh_primitive_edge_visibility",
    "EXT_structural_metadata"
  ],
There should be test model that uses EXT_mesh_primitive_edge_visibility and only EXT_mesh_primitive_edge_visibility - no other extension that might interfere with the baseline test for this extension. Such a model would also be useful, eventually, in the context of KhronosGroup/glTF#2479 , for implementors to test.

I did not peform a thorough review of this PR! It only caught my attention due to #12914 . And when I saw https://github.com/CesiumGS/cesium/pull/12859/files/1c9ba9d2415aa507cce107d91938d10c9e707cd1#diff-20964905fdcbaf8679c56d995e848ed68a3c0f08d868ad38c5d794145b0fbbc6R70, I thought: Wait, that can hardly be right. Edge visibility and feature IDs are totally unrelated. Maybe these defines are the crux here, and maybe there is some if (hasFeatureIds) doThis(); else dont(); that I overlooked and that prevents this from being executed when no feature IDs are present. If this is the case, it should be documented more extensively. And if this is the case, then it should thoroughly explain why it can rely on the featureId_0, and not any other feature ID. // We know that featureId_0 is present here, because [text]

Thanks for the feedback, it’s fixed

danielzhong added 30 commits August 6, 2025 11:31

save change

1d02adc

save work

b1970e6

save

7ee0e74

add temp test for decode gltf

3ab4db2

save

1afc12c

save

5a19ba9

test decoding with cesium outline

f79b50f

save

3f0ce2c

Proving Draw Command Succesfully

48509e6

working for quad

6e0013e

Created LUT for hard edge

8d41bfb

save normal in shader

172a3f9

showing edge color

2a28ea2

change pass

7bd1517

save

6400cef

save

07bae45

save

6a7c003

save

31ed492

save

ad8d074

save

cb73143

save

bf97892

solve bug, clean up code

549a08e

Silhoutte Normal Save

93ddaae

Edge + geometry rendering

af97e57

z fighting save

78c4d02

MRT save

7f33eee

MTR printing color

1ceba1d

MTR debuging id

0017b85

MTR fix

bf7e9fd

MTR clean up

3b136de

Revert "Merge branch 'main' into edge_line_unique_VAO"

90699e1

This reverts commit bc16ca0, reversing changes made to afe6e41.

danielzhong requested a review from ggetz September 18, 2025 00:59

danielzhong added 4 commits September 17, 2025 21:17

Revert "optimize scene edge visibility toggle"

bcc5f55

This reverts commit 7da8453.

Reapply "optimize scene edge visibility toggle"

5a00918

This reverts commit bcc5f55.

Reapply "Merge branch 'main' into edge_line_unique_VAO"

b896c22

This reverts commit 90699e1.

Merge branch 'main' into edge_line_unique_VAO

25d8eb3

lilleyse reviewed Sep 19, 2025

View reviewed changes

danielzhong and others added 3 commits September 19, 2025 13:32

Update packages/engine/Source/Scene/Model/EdgeVisibilityPipelineStage.js

04d429a

Co-authored-by: Sean Lilley <lilleyse@gmail.com>

Update packages/engine/Source/Scene/Model/EdgeVisibilityPipelineStage.js

4f4a1d5

Co-authored-by: Sean Lilley <lilleyse@gmail.com>

remove edge visibility extra v_positionView

38a6680

danielzhong added 6 commits September 19, 2025 14:40

Optimize using Cartesian3 and leas heap allocations

6b43c56

handel case when positions are quantized

335d7bc

Revert "handel case when positions are quantized"

bad1aa1

This reverts commit 335d7bc.

Reapply "handel case when positions are quantized"

688a5a4

This reverts commit bad1aa1.

fix

2a356aa

Merge branch 'main' into edge_line_unique_VAO

f3e807f

danielzhong requested a review from lilleyse September 19, 2025 20:28

Merge branch 'main' into edge_line_unique_VAO

5036f73

danielzhong mentioned this pull request Sep 24, 2025

Refactor model pipeline in cesium #12914

Open

danielzhong added 3 commits September 24, 2025 14:10

Adding FeatureID check

92ef75f

Fix

3916a99

Fix

dd67f96

fix bug

c69f8a0

		const renderState = clone(command.renderState, true);
		edgeCommand.renderState = RenderState.fromCache(renderState);

Add support for GLTF extension: EXT_mesh_primitive_edge_visibility #12859

Are you sure you want to change the base?

Add support for GLTF extension: EXT_mesh_primitive_edge_visibility #12859

Uh oh!

Conversation

danielzhong commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue number and link

Testing plan

🔍Review Notes

Bug Fix Summary

Author checklist

Uh oh!

danielzhong commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danielzhong commented Sep 18, 2025

Uh oh!

lilleyse 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!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

danielzhong commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lilleyse commented Sep 19, 2025

Uh oh!

danielzhong commented Sep 19, 2025

Uh oh!

javagl commented Sep 24, 2025

Uh oh!

danielzhong commented Sep 25, 2025

Uh oh!

Uh oh!

danielzhong commented Aug 30, 2025 •

edited

Loading

danielzhong commented Sep 18, 2025 •

edited

Loading

danielzhong commented Sep 19, 2025 •

edited

Loading