support 2.5D/2D projection by default when the option projectTo2D is not set #12825

mickae1 · 2025-08-20T11:29:05Z

to test :
test.zip

you can find here the sandcastle

github-actions · 2025-08-20T11:29:27Z

Thank you for the pull request, @mickae1!

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

mickae1 · 2025-08-21T07:38:26Z

@lukemckinstry @ggetz do you think this pull request can be accepted for the next cesium release ? My teams need it.

Thank you,

mzschwartz5 · 2025-08-25T21:44:28Z

Hi @mickae1! Thanks for opening a PR and contributing this feature. I have a couple questions to kick off my review:

Is there a GH issue or forum post that discusses this feature? If so, can you link it so we maintain the context of this feature for posterity? If not, it might be a good idea to open an issue or write a forum post to get feedback / direction.
One thing I'd want to discuss in such an issue is the best way to implement this feature that fits in with the Cesium's design. Right now, you're using a compiler macro to ignore Cesium's built-in geometry stage function when a flag is set. I think a more natural way to do this would be to pass in and override with your new geometry stage here. That way, the engine is never potentially in a situation where there's no geometry stage function (if, say, you forget to supply one). It's guaranteed to have at least the default.

But beyond the actual implementation, I'm curious what it is you're trying to achieve with this new feature - maybe we already support what you want to do some other way! (Again, why it's often helpful to start with or link a forum post).

I'll assign myself as a reviewer so I can get notified when you reply!

mzschwartz5 · 2025-08-25T21:45:31Z

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

@@ -166,6 +166,7 @@ import ModelImagery from "./ModelImagery.js";
 * @privateParam {boolean} [options.showCreditsOnScreen=false] Whether to display the credits of this model on screen.
 * @privateParam {SplitDirection} [options.splitDirection=SplitDirection.NONE] The {@link SplitDirection} split to apply to this model.
 * @privateParam {boolean} [options.projectTo2D=false] Whether to accurately project the model's positions in 2D. If this is true, the model will be projected accurately to 2D, but it will use more memory to do so. If this is false, the model will use less memory and will still render in 2D / CV mode, but its positions may be inaccurate. This disables minimumPixelSize and prevents future modification to the model matrix. This also cannot be set after the model has loaded.
+ * @privateParam {boolean} [options.customGeometryStage=false] Whether to override the default geometry stage, to let the user define it's own geometry stage.


Small nit- it's -> its.

But, per my overall comment, I think it might make more sense to do something like pass in the geometry stage function snippet itself rather than a flag.

mzschwartz5 · 2025-08-25T21:47:48Z

Oh, also - if you haven't already, can you add yourself to CONTRIBUTING.md and add your feature to CHANGES.md?

mickae1 · 2025-08-25T22:44:20Z

Hi @mickae1! Thanks for opening a PR and contributing this feature. I have a couple questions to kick off my review:

Is there a GH issue or forum post that discusses this feature? If so, can you link it so we maintain the context of this feature for posterity? If not, it might be a good idea to open an issue or write a forum post to get feedback / direction.

One thing I'd want to discuss in such an issue is the best way to implement this feature that fits in with the Cesium's design. Right now, you're using a compiler macro to ignore Cesium's built-in geometry stage function when a flag is set. I think a more natural way to do this would be to pass in and override with your new geometry stage here. That way, the engine is never potentially in a situation where there's no geometry stage function (if, say, you forget to supply one). It's guaranteed to have at least the default.

But beyond the actual implementation, I'm curious what it is you're trying to achieve with this new feature - maybe we already support what you want to do some other way! (Again, why it's often helpful to start with or link a forum post).

I'll assign myself as a reviewer so I can get notified when you reply!

you can find here the issue :

#12815

mickae1 · 2025-08-26T00:17:21Z

for my model loaded from glb, i want to do the projection change in vertex shader when I'm in 2D/2.5D . ( i don't want any cpu computing the 2D projection )

the code works, the projection works.

you can find here the sandcastle

please tell me what I need to do to validate this pull request

mickae1 · 2025-08-27T07:28:41Z

I've made modifications, to start a new approach, more generic to every one, please give advice .

the updated sandcastle

…not set add the options.customGeometryStageVS Whether to override the default VS geometry stage, to let the user define its own VS geometry stage.

mzschwartz5 · 2025-08-29T13:56:50Z

packages/engine/Source/Shaders/Model/GeometryStageVS.glsl

+	return vec3(altitude, plate_x, plate_y);
+}
+
+vec3 cartesianToCartographic(vec3 cartesian) {


I'm still processing the math here, but wondering if something here might be helpful (or if we can even just use these functions directly). It looks conceptually similar.

If we can use the above, I wonder if isSphere is actually a fast path, given the expense of trig functions on the GPU. Might be worth doing some performance measurements there to see. Maybe it's faster to just treat everything as an ellipsoid and use that non-trig iterative method.

mzschwartz5 · 2025-08-29T14:01:17Z

packages/engine/Source/Shaders/Model/GeometryStageVS.glsl


    #if defined(USE_2D_POSITIONS) || defined(USE_2D_INSTANCING)
    vec3 position2D = attributes.position2D;
    vec3 positionEC = (u_modelView2D * vec4(position2D, 1.0)).xyz;
    computedPosition = czm_projection * vec4(positionEC, 1.0);
    #else
-    computedPosition = czm_projection * vec4(v_positionEC, 1.0);
+	if(czm_morphTime != 1.){


Small nit- given that, the vast majority of the time, we operate in 3D mode, it would be slightly faster to invert this check so that it short-circuits more often.

(Looking back at this, I see that this is within the USE_2D_POSITIONS macro, so is it already always 2D mode? If we remove the CPU-side projection implementation, per my overall-review comment, then we would remove this macro too, I think, and we'd need the czm_morphTime check you added.)

mzschwartz5 · 2025-08-29T14:20:56Z

packages/engine/Source/Shaders/Model/GeometryStageVS.glsl

+		vec3 cartographic = cartesianToCartographic(positionMC);
+		vec3 position = projectToGeographic(cartographic);
+
+		vec3 positionEC = (czm_view * vec4(position, 1.0)).xyz;


Do we still need to write out to v_positionEC in this branch of the if-statement?

i don't know, If it is used in other pipeline, or used in fragment shader.

The prefix v_ typically means it's a vertex output attribute - so it would get used in the fragment shader. In this case, you can see that here.

mzschwartz5 · 2025-08-29T15:56:49Z

packages/engine/Source/Shaders/Model/GeometryStageVS.glsl


    #if defined(USE_2D_POSITIONS) || defined(USE_2D_INSTANCING)
    vec3 position2D = attributes.position2D;
    vec3 positionEC = (u_modelView2D * vec4(position2D, 1.0)).xyz;
    computedPosition = czm_projection * vec4(positionEC, 1.0);
    #else
-    computedPosition = czm_projection * vec4(v_positionEC, 1.0);
+	if(czm_morphTime != 1.){
+		vec3 cartographic = cartesianToCartographic(positionMC);


(This probably reveals some misunderstanding I have but) - why does this operate on the model space position instead of world or eye space?

mzschwartz5 · 2025-08-29T15:59:19Z

Overall comment - I have yet to test the changes, will do soon. Just did an overview for the moment. I think this could be a really nice contribution - if it works as promised without any regressions, we should go a step further and remove the CPU implementation of the projection. This would be the default, and we could skip the added options to the geometry pipeline stage to override the implementation.

mickae1 · 2025-09-02T08:08:22Z

@mzschwartz5 what i'm doing in the vertex shader, is exactly what is done in the cpu :

cesium/packages/engine/Source/Core/GeometryPipeline.js

Line 616 in 4da5e56

GeometryPipeline.projectTo2D = function (

with :

 const lonLat = ellipsoid.cartesianToCartographic(
      value,
      scratchProjectTo2DCartographic,
    );
    //>>includeStart('debug', pragmas.debug);
    if (!defined(lonLat)) {
      throw new DeveloperError(
        `Could not project point (${value.x}, ${value.y}, ${value.z}) to 2D.`,
      );
    }
    //>>includeEnd('debug');

    const projectedLonLat = projection.project(
      lonLat,
      scratchProjectTo2DCartesian3,
    );

I found out why, it need to be vec3(z,x,y ) to be working : ( and not vec3(x,y,z) ) :

because it's what you are doing in other shader :

cesium/packages/engine/Source/Shaders/PolylineVS.glsl

Line 47 in 4da5e56

p = czm_translateRelativeToEye(position2DHigh.zxy, position2DLow.zxy);

but not here, why ?

cesium/packages/engine/Source/Shaders/Model/GeometryStageVS.glsl

Line 12 in 4da5e56

vec3 positionEC = (u_modelView2D * vec4(position2D, 1.0)).xyz;

mickae1 mentioned this pull request Aug 20, 2025

Cesium.Model & modelMatrix: Cesium.Matrix4.IDENTITY & 2D Mode #12815

Open

mickae1 force-pushed the main branch from 7d49f0f to 864602c Compare August 21, 2025 07:31

mzschwartz5 self-assigned this Aug 25, 2025

mzschwartz5 reviewed Aug 25, 2025

View reviewed changes

mickae1 force-pushed the main branch from 864602c to b833fb6 Compare August 26, 2025 00:04

mickae1 changed the title ~~add the option customGeometryStage to let the user customize the geometry stage function in the vertex shader~~ add the option customGeometryStageVS to let the user customize the geometry stage function in the vertex shader Aug 26, 2025

mickae1 force-pushed the main branch from b833fb6 to a48b72e Compare August 27, 2025 07:25

mickae1 changed the title ~~add the option customGeometryStageVS to let the user customize the geometry stage function in the vertex shader~~ support 2.5D/2D projection by default when the option projectTo2D is not set Aug 27, 2025

mickae1 force-pushed the main branch from a48b72e to 6cb804e Compare August 27, 2025 08:21

support 2.5D/2D projection by default when the option projectTo2D is …

09d7454

…not set add the options.customGeometryStageVS Whether to override the default VS geometry stage, to let the user define its own VS geometry stage.

mickae1 force-pushed the main branch from 5b9a129 to 09d7454 Compare August 29, 2025 07:41

mzschwartz5 reviewed Aug 29, 2025

View reviewed changes

support 2.5D/2D projection by default when the option projectTo2D is not set #12825

Are you sure you want to change the base?

support 2.5D/2D projection by default when the option projectTo2D is not set #12825

Conversation

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

Uh oh!

Uh oh!

github-actions bot commented Aug 20, 2025

Uh oh!

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

Uh oh!

Uh oh!

mzschwartz5 commented Aug 25, 2025

Uh oh!

mzschwartz5 Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 commented Aug 25, 2025

Uh oh!

mickae1 commented Aug 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

mickae1 commented Aug 27, 2025

Uh oh!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mickae1 Aug 29, 2025 • 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!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 commented Aug 29, 2025

Uh oh!

mickae1 commented Sep 2, 2025

Uh oh!

Uh oh!

mickae1 commented Aug 20, 2025 •

edited

Loading

mickae1 commented Aug 21, 2025 •

edited

Loading

mickae1 commented Aug 26, 2025 •

edited

Loading

mickae1 Aug 29, 2025 •

edited

Loading