Merge pull request #12544 from CesiumGS/ellipsoid-voxel-order

Fix glTF voxel ordering for ellipsoid shapes

Author: ggetz

Apps/SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/schema.json

@@ -1,14 +1,11 @@
 {
   "tileAvailability": {
-    "availableCount": 1,
     "constant": 1
   },
-  "contentAvailability": {
-    "availableCount": 1,
+  "contentAvailability": [{
     "constant": 1
-  },
+  }],
   "childSubtreeAvailability": {
-    "availableCount": 0,
     "constant": 0
   }
 }

Apps/SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/subtrees/0/0/0/0.json

@@ -2,6 +2,40 @@
   "asset": {
     "version": "2.0"
   },
+  "extensionsUsed": [
+    "EXT_primitive_voxels",
+    "EXT_structural_metadata"
+  ],
+  "extensionsRequired": [
+    "EXT_primitive_voxels",
+    "EXT_structural_metadata"
+  ],
+  "extensions": {
+    "EXT_structural_metadata": {
+      "schema": {
+        "classes": {
+          "voxel": {
+            "properties": {
+              "a": {
+                "type": "VEC4",
+                "componentType": "FLOAT32"
+              }
+            }
+          }
+        }
+      },
+      "propertyAttributes": [
+        {
+          "class": "voxel",
+          "properties": {
+            "a": {
+              "attribute": "_DATA"
+            }
+          }
+        }
+      ]
+    }
+  },
   "scene": 0,
   "scenes": [
     {
@@ -19,82 +53,53 @@
     {
       "primitives": [
         {
-          "mode": 2147483649,
           "attributes": {
-            "_a": 0
+            "_DATA": 0
           },
+          "mode": 2147483647,
           "extensions": {
             "EXT_primitive_voxels": {
+              "shape": 0,
               "dimensions": [
                 2,
                 2,
                 2
-              ],
-              "bounds": {
-                "min": [
-                  0.0,
-                  0.0,
-                  -1.0
-                ],
-                "max": [
-                  1.0,
-                  1.0,
-                  0.0
-                ]
-              }
+              ]
+            },
+            "EXT_structural_metadata": {
+              "propertyAttributes": [0]
             }
           }
         }
       ]
     }
   ],
-  "extensionsUsed": [
-    "EXT_primitive_voxels",
-    "EXT_structural_metadata"
-  ],
-  "extensionsRequired": [
-    "EXT_primitive_voxels",
-    "EXT_structural_metadata"
-  ],
-  "extensions": {
-    "EXT_structural_metadata": {
-      "schemaUri": "../../../../schema.json",
-      "propertyAttributes": [
-        {
-          "class": "voxel",
-          "properties": {
-            "a": {
-              "attribute": "_a"
-            }
-          }
-        }
-      ]
-    }
-  },
   "accessors": [
     {
       "bufferView": 0,
-      "type": "SCALAR",
+      "byteOffset": 0,
       "componentType": 5126,
-      "min": [
-        0.0
-      ],
+      "count": 8,
       "max": [
-        1.0
+        1.0, 1.0, 1.0, 1.0
+      ],
+      "min": [
+        0.0, 0.0, 0.0, 0.0
       ],
-      "count": 8
+      "type": "VEC4"
     }
   ],
   "bufferViews": [
     {
       "buffer": 0,
-      "byteLength": 32
+      "byteOffset": 0,
+      "byteLength": 128
     }
   ],
   "buffers": [
     {
       "uri": "a.bin",
-      "byteLength": 32
+      "byteLength": 128
     }
   ]
-}
+}

Apps/SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/tiles/0/0/0/0.gltf

@@ -2,7 +2,19 @@
   "asset": {
     "version": "1.1"
   },
-  "schemaUri": "schema.json",
+  "schema": {
+    "id": "voxel",
+    "classes": {
+      "voxel": {
+        "properties": {
+          "a": {
+            "type": "VEC4",
+            "componentType": "FLOAT32"
+          }
+        }
+      }
+    }
+  },
   "statistics": {
     "classes": {
       "voxel": {
@@ -28,7 +40,7 @@
         500000.0
       ]
     },
-    "geometricError": 0.0,
+    "geometricError": 16.0,
     "refine": "REPLACE",
     "content": {
       "uri": "tiles/{level}/{x}/{y}/{z}.gltf",
@@ -45,7 +57,7 @@
     },
     "implicitTiling": {
       "subdivisionScheme": "OCTREE",
-      "subtreeLevels": 3,
+      "subtreeLevels": 1,
       "availableLevels": 1,
       "subtrees": {
         "uri": "subtrees/{level}/{x}/{y}/{z}.json"

Apps/SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/tiles/0/0/0/a.bin

@@ -44,14 +44,6 @@
         viewer.extend(Cesium.viewerVoxelInspectorMixin);
         viewer.scene.debugShowFramesPerSecond = true;
 
-        const customShaderWhite = new Cesium.CustomShader({
-          fragmentShaderText: `void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material)
-  {
-      material.diffuse = vec3(1.0);
-      material.alpha = 1.0;
-  }`,
-        });
-
         const customShaderColor = new Cesium.CustomShader({
           fragmentShaderText: `void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material)
   {
@@ -60,13 +52,13 @@
   }`,
         });
 
-        function createPrimitive(provider, customShader) {
+        function createPrimitive(provider) {
           viewer.scene.primitives.removeAll();
 
           const voxelPrimitive = viewer.scene.primitives.add(
             new Cesium.VoxelPrimitive({
               provider: provider,
-              customShader: customShader,
+              customShader: customShaderColor,
             }),
           );
 
@@ -87,7 +79,7 @@
               const provider = await Cesium.Cesium3DTilesVoxelProvider.fromUrl(
                 "../../SampleData/Cesium3DTiles/Voxel/VoxelBox3DTiles/tileset.json",
               );
-              const primitive = createPrimitive(provider, customShaderColor);
+              const primitive = createPrimitive(provider);
             },
           },
           {
@@ -96,7 +88,7 @@
               const provider = await Cesium.Cesium3DTilesVoxelProvider.fromUrl(
                 "../../SampleData/Cesium3DTiles/Voxel/VoxelCylinder3DTiles/tileset.json",
               );
-              const primitive = createPrimitive(provider, customShaderColor);
+              const primitive = createPrimitive(provider);
             },
           },
           {
@@ -105,7 +97,7 @@
               const provider = await Cesium.Cesium3DTilesVoxelProvider.fromUrl(
                 "../../SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/tileset.json",
               );
-              const primitive = createPrimitive(provider, customShaderWhite);
+              const primitive = createPrimitive(provider);
             },
           },
         ]);

Apps/SampleData/Cesium3DTiles/Voxel/VoxelEllipsoid3DTiles/tileset.json

@@ -7,6 +7,7 @@
 #### Breaking Changes :mega:
 
 - `Camera.getPickRay` was erroneously returning a result in camera coordinates. It is now returned in world coordinates as stated in the documentation. The result can be transformed using `Camera.inverseViewMatrix` to achieve the previous behavior.
+- `VoxelMetadataOrder` has been made private, and the `metadataOrder` property has been removed from the `VoxelProvider` interface.
 
 #### Additions :tada:
 
@@ -23,6 +24,7 @@
 - Fixed camera zooming in 3D orthographic mode when pixelRatio is not 1. [#12487](https://github.com/CesiumGS/cesium/pull/12487)
 - Fixed VaryingType.MAT3: "mat2" significant typo. [#12524](https://github.com/CesiumGS/cesium/issues/12524)
 - Fixed shape bounds and transforms for cylinder-shaped voxels. [#12522](https://github.com/CesiumGS/cesium/pull/12522)
+- Fixed metadata ordering for ellipsoid voxel tilesets. [#12544](https://github.com/CesiumGS/cesium/pull/12544)
 - Fixed an issue where clamped entities' height updates could stall when using high-resolution terrain due to a growing queue of tiles in `updateHeights` in `QuadtreePrimitive`. [#12476](https://github.com/CesiumGS/cesium/issues/12476)
 
 ## 1.127 - 2025-03-03

Apps/Sandcastle/gallery/Voxels in 3D Tiles.html

@@ -110,7 +110,10 @@ function Cesium3DTilesVoxelProvider(options) {
   this._names = names;
   this._types = types;
   this._componentTypes = componentTypes;
-  this._metadataOrder = VoxelMetadataOrder.GLTF;
+  this._metadataOrder =
+    shape === VoxelShapeType.ELLIPSOID
+      ? VoxelMetadataOrder.Z_UP
+      : VoxelMetadataOrder.Y_UP;
   this._minimumValues = minimumValues;
   this._maximumValues = maximumValues;
   this._maximumTileCount = maximumTileCount;
@@ -288,6 +291,7 @@ Object.defineProperties(Cesium3DTilesVoxelProvider.prototype, {
    * @memberof Cesium3DTilesVoxelProvider.prototype
    * @type {VoxelMetadataOrder}
    * @readonly
+   * @private
    */
   metadataOrder: {
     get: function () {

Apps/Sandcastle/gallery/Voxels in 3D Tiles.jpg

@@ -3,10 +3,22 @@
  * In all cases, x data is contiguous in strides along the y axis,
  * and each group of y strides represents a z slice.
  * However, the orientation of the axes follows different conventions.
+ *
  * @enum {number}
+ * @private
  */
 const VoxelMetadataOrder = {
-  XYZ: 0, // Default ordering following the 3D Tiles convention. Z-axis points upward.
-  GLTF: 1, // Ordering following the glTF convention. Y-axis points upward.
+  /**
+   * The default ordering following the 3D Tiles convention. Z-axis points upward.
+   * @type {number}
+   * @constant
+   */
+  Z_UP: 0,
+  /**
+   * The ordering following the glTF convention. Y-axis points upward.
+   * @type {number}
+   * @constant
+   */
+  Y_UP: 1,
 };
 export default Object.freeze(VoxelMetadataOrder);

CHANGES.md

@@ -1502,7 +1502,7 @@ function initFromProvider(primitive, provider, context) {
     primitive._paddingAfter,
     primitive._inputDimensions,
   );
-  if (provider.metadataOrder === VoxelMetadataOrder.GLTF) {
+  if (provider.metadataOrder === VoxelMetadataOrder.Y_UP) {
     const inputDimensionsY = primitive._inputDimensions.y;
     primitive._inputDimensions.y = primitive._inputDimensions.z;
     primitive._inputDimensions.z = inputDimensionsY;

packages/engine/Source/Scene/Cesium3DTilesVoxelProvider.js

@@ -145,18 +145,6 @@ Object.defineProperties(VoxelProvider.prototype, {
     get: DeveloperError.throwInstantiationError,
   },
 
-  /**
-   * Gets the ordering of the metadata in the buffers.
-   *
-   * @memberof VoxelProvider.prototype
-   * @type {VoxelMetadataOrder}
-   * @default VoxelMetadataOrder.XYZ
-   * @readonly
-   */
-  metadataOrder: {
-    get: DeveloperError.throwInstantiationError,
-  },
-
   /**
    * Gets the metadata minimum values.
    *