ModelExperimental -> Model Roadmap

[j9liu]

One of the major items on the 3D Tiles Next Roadmap (#9520) is bringing ModelExperimental up to feature parity with Model, so that it can entirely replace it. In other words, we aim to remove the current Model class and any related files, and rename ModelExperimental to Model without any hiccups.

This issue goes into more detail than the overall roadmap and will be updated as necessary.

Remaining ModelExperimental Features

• Basic 2D / CV rendering: ModelExperimental - Support rendering in 2D and Columbus View modes #9934
• Clamp to ground Add height reference (clamp-to-ground) to ModelExperimental #10448
• Support AGI_articulations Add support for AGI_articulations to ModelExperimental #10479
• Support silhouettes Add silhouettes to ModelExperimental #10457
• Support distanceDisplayCondition Add distanceDisplayCondition to ModelExperimental #10481
• Add options.id for picking Add options.id to ModelExperimental #10491
• Add options.credit Add credit option to ModelExperimental #10489
• Add options.asynchronous Add asynchronous option to ModelExperimental.fromGltf #10490
• Rendering statistics Add statistics to ModelExperimental, ModelExperimental3DTileContent #9886
• Support outline extension for OSM buildings: Rendering issues when rendering OSM buildings with ModelExperimental #10338
• Integration with entities and CZML systems: Ensure entities and CZML work with ModelExperimental #10285
• Use GltfLoader in ClassificationModel

Important bugfixes

• Normal mapping rendering bug: Normal mapping incorrect for Model #10296
• Custom shaders and instancing bug: Custom shaders don't work on instanced models #10113
• 3D Tiles BIM model crashes: comment in ModelExperimental Sandcastle Testing #10379
• OSM buildings render differently Rendering issues when rendering OSM buildings with ModelExperimental #10338

Lower-priority bugfixes

• Quantized animation bug: Dequantization doesn't work for AnimatedMorphCube #10321
• Morph targets unit test failure: ModelSpec - "renders glTF with morph targets" fails #10354
• Artifacts in 2D / CV when rendering over IDL: Artifacts in 2D / CV mode when rendering over the IDL #10401 (fix in the distant future)
• Some tilesets not showing up with projectTo2D in 2D / CV Some OSM buildings not appearing in 2D / CV mode #10402 (more related to bounding volumes in 2D than ModelExperimental itself)

Testing

• Ensure all models from glTF-Sample-Models load correctly with ModelExperimental
• Ensure that tilesets load correctly with ExperimentalFeatures.enableModelExperimental set to true
• Ensure that entities and CZML work with ModelExperimental
• Go through the "category - gltf" label for any important lingering issues
• Go through Sandcastles and make sure they work with ModelExperimental. See ModelExperimental Sandcastle Testing #10379

Files to remove

• Model
• ModelInstanceCollection
• ModelAnimationCache
• ModelAnimation
• ModelAnimationCollection
• ModelNode
• ModelMesh
• ModelUtility -- make sure it no longer needs to be used by ClassificationModel
• ModelOutlineLoader
• all related specs

Files to rename

• ModelExperimental and related architecture
  • ModelExperimentalSceneGraph
  • ModelExperimentalNode
  • ModelExperimentalPrimitive
  • ModelExperimentalSkin
  • ModelExperimentalAnimationChannel
  • ModelExperimentalAnimation
  • ModelExperimentalAnimationCollection
  • ModelExperimental3DTileContent
  • ModelExperimentalType
  • ModelExperimentalUtility
• Shaders
  • ModelExperimentalVS
  • ModelExperimentalFS
• loadAndZoomToModelExperimental
• all related specs

[lilleyse]

This is very exciting! Just a few more things to add from me:

• glTF 1.0: Is the custom shader architecture flexible enough that it could allow glTF 1.0 models to still work? The main model we're concerned about is https://sandcastle.cesium.com/?src=3D%20Tiles%20BIM.html. It may not be easy to find a replacement. We need to put in a day or two to come up with a plan here.
• If we decide to deprecate anything, it should be mentioned in the June release
• Documentation sweep to make sure that everything marked @private should remain @private
• We should consider setting tileset.enableModelExperimental = true by default so that we can start catching regressions early. We should test as many 3D Tiles datasets as we can find and allow for a couple weeks for bug fixes.
• Re ModelUtility - it would be annoying to maintain two utility files. It might be worth updating ClassificationModel to use GltfLoader even though it's lower on the priority list.

[j9liu]

Should we consider adding a url option to the ModelExperimental.fromGltf constructor? Model.fromGltf takes a url whereas ModelExperimental.fromGltf takes gltf, so this will break things when we make the switch from Model to ModelExperimental.

EDIT: this was done in #10371

[lilleyse]

@j9liu yeah definitely. I got tripped up by this earlier today. Could you open a PR for that?

[j9liu]

Going through the glTF 2.0 sample models, leaving notes where I see differences (excluding models with extensions we don't support):

Cube

Pretty subtle rendering difference, but it seems like the top of the cube rendered by Model (right) is more shiny than the cube rendered by ModelExperimental (left).

This doesn't have to do with the placement of the models in the scene; swapping their positions yields the same result (Model now on left):

Flight Helmet

The gold part of the model renders darker in ModelExperimental than it does for Model.

Model	ModelExperimental

Fox

The fox model renders brighter for ModelExperimental (left) than Model (right). This is even with image-based-lighting turned off.

EDIT: The below difference is because CesiumJS does not automatically generate normals for glTFs without them. #6506

It also seems like the model isn't shaded properly; it looks unlit, despite having normals. Here's an example of the model being shaded with normals in glTF-Sample-Viewer, without IBL:

Lantern

The emissive part of the model (the lantern) is less bright in CesiumJS than it is for glTF-Sample-Viewer.

glTF-Sample-Viewer	ModelExperimental

Morph Stress Test

Both Model and ModelExperimental crash trying to load this model with similar errors:

We're not required to support this many morph targets according to the spec, so it's not necessary to fix this.

Multi UV Test

Again, ModelExperimental (left) looks darker than Model (right):

Normal Tangent Mirror Test

EDIT: Fixed by #10507

When the normal maps are viewed from the back, the domes should appear concave, like they are pushed into the plane. But the front and back of the model look the same on ModelExperimental.

Model	ModelExperimental

Normal Tangent Test

EDIT: Fixed by #10507

Same issue as above.

Model	ModelExperimental

Simple Meshes

Another instance where ModelExperimental (left) is darker than Model (right):

Simple Morph

And then an instance where ModelExperimental (left) is brighter than Model (right):

This also applies for "Simple Skin" and "Triangle"

Simple Sparse Accessor

Sparse accessors are not yet supported in CesiumJS.

glTF-Sample-Viewer	ModelExperimental

Spec Gloss vs. Metal Rough

The water bottles rendered with both material types are darker for ModelExperimental (left) than they are for Model (right)

Texture Linear Interpolation Test

EDIT: This is meant to be broken for WebGL 1 according to the README of this sample model.

The spheres are about the same color for glTF-Sample-Viewer, but they are distinctly different for Model / ModelExperimental

glTF-Sample-Viewer	ModelExperimental

Texture Settings Test

EDIT: Fixed by #10507

The double-sided texture renders dark for ModelExperimental but fine for Model.

Model	ModelExperimental

Two-Sided Plane

EDIT: Fixed by #10507

The under-side of the plane isn't dark for ModelExperimental even though it is for Model.