Added basic EXT_mesh_features samples

[javagl]

This is an initial DRAFT of some examples for EXT_mesh_features.

It is not yet decided whether these samples should be here, because they are not strictly speaking "3D tiles samples". Also, there are some kinds of possible samples for EXT_mesh_features that cannot sensibly be part of a tileset (for example, an empty asset that only defines an example schema). But they may serve the purpose of getting an idea of which samples could make sense, and in how far certain functionalities are already supported in CesiumJS.

The current state of this PR is "bare", without any READMEs, screenshots or documentation. These will be added at a later point, as appropriate.

There currently are 5 assets (each wrapped into a trivial tileset) in https://github.com/javagl/3d-tiles-samples/tree/add-ext-mesh-features-samples/EXT_mesh_features . Each asset has the same structure: It consists of a single scene with a single mesh with a single primitive that just consists of 4 quads:

The flavors of this asset, reflected in the test cases, are:

1. "ExplicitFeatureIds": Defines explicit feature IDs (without property tables)
2. "ExplicitFeatureIdsAndSimpleProperty": Defines explicit feature IDs and a simple VEC3/FLOAT32 property
3. "ImplicitFeatureIds": Defines implicit feature IDs (without property tables)
4. "ImplicitFeatureIdsAndSimpleProperty": Defines implicit feature IDs and a simple VEC3/FLOAT32 property
5. "MultipleFeatureIdsAndProperties": Defines multiple feature IDs and different properties

• Cases 1 and 3 do not work yet, because of Model EXT_mesh_features: handle feature IDs without a property table cesium#9884

• Case 2 seems to work, but the displayed values for the vectors is not correct. The vectors should have the values

           float exampleData[] = new float[] {
                0.0f, 0.1f, 0.2f,
                1.0f, 1.1f, 1.2f,
                2.0f, 2.2f, 2.2f,
                3.0f, 3.1f, 3.2f,
            };
  

  The values that are actually shown look like there might be an issue related to endianness, but I haven't investigated it in detail yet. (I can only say that when adding an accessor for these values, the right values are displayed when inspecting the accessor in the VS Code glTF plugin - so they should probably be correct there)

• Case 4 does not seem to work - it does not seem to find the feature IDs when they are defined implicitly.

• Case 5 causes everything to collapse and splill out obscure error messages...

NOTE: Each and every error might be an issue with the sample data itself ... or with CesiumJS. This has to be figured out as we move on. But particularly the last example is "relatively complex", and it's not unlikely that it is invalid in one way or another...

---

In order to quickly tests this, a first draft of the Sandcastle code (that would eventually go into the READMEs) is in https://github.com/javagl/3d-tiles-samples/blob/add-ext-mesh-features-samples/EXT_mesh_features/CommonSandcastleCode.txt

It contains a code block

var testCase = "";
//testCase = "ExplicitFeatureIds";
//testCase = "ExplicitFeatureIdsAndSimpleProperty";
//testCase = "ImplicitFeatureIds";
//testCase = "ImplicitFeatureIdsAndSimpleProperty";
testCase = "MultipleFeatureIdsAndProperties";

that allows to quickly select the example that should be loaded, for debugging and testing.

[ptrgags]

@javagl tried out your examples. I can reproduce the problems for the first 4.

For the 5th one, it loads fine, though it looks like the string property is misalligned, see here how the property value is "Rai" when I click the bottom left square, and if I click the bottom right one I get the "n" for "Rain"

[lilleyse]

One more sample idea that could be considered for a follow up PR - two primitives with features that point to the same property table.

[javagl]

@ptrgags

I can reproduce the problems for the first 4.

There was a wrong index for the property tables that caused the error that I originally considered to be some endianness issue. Sorry about that, it should be fixed with the last commit.

[javagl]

Just noticed a typo in the example data...

2.0f, 2.2f, 2.2f,

That should have been 2.1. It's the details... (will update that at some point...)

[javagl]

In response to #40 (comment) , I just added an example that contains two primitives that refer to the same property table. I'm still in the process of trying to find "the best way" to create these samples, but I'll consider and try out other possible (more "complex") examples, and add them here when ready.

[javagl]

The MultipleFeatureIdsAndProperties example has been updated. Now it properly displays the strings:

The reason for the wrong alignment was that I had created the buffer views as GL_ARRAY_BUFFER buffer views. These require a byteStride of at least 4, and that caused the layout of the data to be changed accordingly. That's wrong when this is about a buffer view that does not have an accessor, is only used for metadata. In the latest state, they use an undefined target (indicating that the data is tightly packed).

[javagl]

I have added a first, basic example for Feature ID Textures. It might look familiar to some of you.

I'll have to look into the details on how the sandcastle has to be updated for this (i.e. to actually look up the feature ID properly - right now, the tooltip always shows the info for Feature ID 0 (Wall)).

@ptrgags Even though texture filtering is set to 9728 (NEAREST), there seems to be some "blurring". The textures right now have a size of 10x10 - could it be that they are resized to a power-of-2 (for some WebGL 1 compatibility or so)?

(For comparison, the screenshot shows the three.js viewer result).

And I'll attach the textures here, just for the giggles:

(Yes, I'll probably replace the color texture with a nicer (higher-resolution) one, this is just a first test...)

[javagl]

... right now, the tooltip always shows the info for Feature ID 0 (Wall)).

That was actually caused by the feature ID being stored in the wrong channel. This is fixed with the last commit.

Also, changed the size of the texture to 16x16 to avoid upsampling. The actual color texture is now a larger, "artificially pixelated" image, like this:

I think this makes sense, but I can also replace that texture with something that more resembles "a real house", if that is preferred.

[javagl]

I have added some basic documentation for the first examples:

• Documentation for ExplicitFeatureIds (showing the structure of the mesh primitive and the IDs)

• Documentation for ExplicitFeatureIdsAndSimpleProperty, which just refers to the first one for the "common" part, and adds information about the actual property, as well as a sandcastle example

• TODO Add the sandcastle for the first example, when feature IDs without property tables work

[javagl]

I have added a (preliminary) "complex" example that can (to some extent) be used for testing some of the changes from CesiumGS/cesium#10018

The example contains two classes, where the second one contains some of the "less trivial" types, namely

• a variable-length ARRAY normalized INT8 property
• a fixed-length ARRAY ENUM property

It also contains two feature IDs (an implicit and an explicit one). The https://github.com/javagl/3d-tiles-samples/blob/add-ext-mesh-features-samples/EXT_mesh_features/CommonSandcastleCode.txt has been updated with a basic toolbar box for selecting the FEATURE_ID_0/1, respectively.

From a first test, it basically ~"seems to work". Some changes have to be done for the finalization:

• add a variable-length string array property (the most complex type, structurually)
• Improve the selection of the feature ID in the sandcastle (and maybe clean up the obtain... functions based on the latest state from the PR)
• give it a more sensible name, maybe...
  _{And not only for this example, but for all of them:}
• add documentation

[javagl]

The last commit adds a "Complex Types" example, showing...

• variable-length (normalized) UINT8 arrays
• fixed-length BOOLEAN arrays
• variable-length STRING arrays
• fixed-length ENUM arrays

I'll probably trim down the "Complex Example" that I added earlier, to omit the array types that had been used there, so that it solely serves as a dedicated sample for multiple classes.

[javagl]

The last commit brings this into a state that could be (close to) ready for a first review.

The main change is that I added documentation, as a README.md in each example. Since the examples are, to some extent, "incremental" or show different "dimensions" independently, there is some potential for overlap and redundancies...:

• ExplicitFeatureIds shows only explicit feature IDs (without property tables). ImplicitFeatureIds shows the same feature IDs (without property tables), but this time, implicit. They link to each other, and contain a description of the basic mesh primitive structure.

• ExplicitFeatureIdsAndSimpleProperty and ImplicitFeatureIdsAndSimpleProperty are the counterparts of those above. They both define the same metadata schema and property table (only accessed with different types of IDs). So they link to each other, and each of them links to its "no-property" counterpart (to have a pointer to the mesh primitive structure)

• TwoPrimitivesOnePropertyTable uses the same structure (schema and table) as the ones above, but assigns them to two primitives. It links to ExplicitFeatureIdsAndSimpleProperty for the structure- and metadata definitions.

• MultipleFeatureIdsAndProperties defines one implicit and one explicit feature ID, so there's a pointer to the corresponding samples (in addition to the description of the "multiple properties", of course)

• ComplexTypes refers to ExplicitFeatureIds for the mesh primitive and feature ID definition, and explains the schema and tables for the "complex" types

• MultipleClasses defines the same feature IDs as MultipleFeatureIdsAndProperties (and therefore, links to that), but shows how they can be used to access multiple classes

• SimpleFeatureIdTexture is pretty much standalone...

• SimplePropertyTexture is also standalone, but not tested extensively.

The "Example Sandcastles" are still missing for most of them (except the Explicit... ones). While the "template" for them is in the CommonSandcastleCode.txt, this still has to be cleaned up and tailored for each specific example.

[javagl]

The more I tried to "clean up" the CommonSandcastleCode.txt, the more I noticed that it was similar at least for the EXT_mesh_features samples. (There was some other code in it, for the other (tileset/tile/group) metadata).

I now changed it to focus on the EXT_mesh_features samples, and allow selecting them at runtime:

Roughly speaking, there are two options:

• Having a minimal sandcastle code in each sample README
• Having that "common" code in its own README.md and then just link to this README from the individual models

I'm a bit on the fence here:

• The first one causes some reduncancy (the code would largely be the same in each example, except for the model name)
• The second one adds some complexity (for setting up the selection mechanism in the sandcastle UI)

Any preferences?

[lilleyse]

A dropdown list is more convenient for browsing the samples. And if the code is mostly the same it wouldn't be worth duplicating for each sample. So my preference is the second option.

[javagl]

The common sandcastle code is now part of a "top-level" README - where "top-level" refers to the EXT_mesh_features subdirectory. (Again: These are, strictly speaking, not 3D Tiles samples...)

The "entry point" for these samples would therefore be https://github.com/javagl/3d-tiles-samples/tree/add-ext-mesh-features-samples/EXT_mesh_features

[javagl]

I could add a first, basic "Feature ID by GPU instance" example here...

... but I think it's better to do this later (in a separate PR). The code that I'm using to create this has become increasingly messy, and I'd like to clean it up a bit first...

[lilleyse]

A couple cosmetic suggestions:

• The default camera view is too zoomed in, making it hard to see what's going on
• The city landscape is a bit gritty. I usually like choosing a nice grassy area as the default location for samples

The swath of examples is great, especially as debug/test data. Over time we should create more samples somewhere between debug data and real world data, but that's out of scope for this PR.

I did a high level pass over the documentation and samples and they generally looked good. Just a few minor comments from me.

[lilleyse]

Suggested change

	This example can be viewn with the [common `EXT_mesh_features` sandcastle](../#common-sandcastle-code)
	This example can be viewed with the [common `EXT_mesh_features` sandcastle](../#common-sandcastle-code)

[lilleyse]

Remove whitespace just to tidy up the document

[lilleyse]

While not strictly necessary, it would be good practice to list out the glTF extensions like in https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_content_gltf#extension-json

[lilleyse]

Usually leaf tiles have geometricError of 0.0

[lilleyse]

I believe we are calling these "entities", though I sometimes find myself gravitating towards "instances"

[javagl]

The inlined comments should be addressed with the last commits (each referring to one comment, applied to all README/tileset files - I hope that I didn't overlook anything).

The default camera view is too zoomed in, making it hard to see what's going on

That also bugged me, but I thought that "whatever magic zoomTo does, it should be right". (As in "fit this into the viewport"). However, I saw that it's possible to add an offset there, and now, this is the initial configuration for the samples:

The city landscape is a bit gritty. I usually like choosing a nice grassy area as the default location for samples

The problem (for me) with choosing a location is: There are so many of them :D So I picked the location of (what I think is) the Cesium Office. How about the fountain at the center of the Washington Square, Cesium.Cartesian3.fromDegrees(-75.152325, 39.94704, 0)?

If it should be some completely neutral place outside of the city, just drop the long/lat, and I'll update it accordingly...

[lilleyse]

I like the Washington Square location 😄

[javagl]

Depending on whether there will be a "new" set of samples (i.e. a new PR), or this one will be updated, I'd use that location then accordingly.

[lilleyse]

@javagl can this be closed now that #47 was merged?

[javagl]

Yes, #47 should contain everything that was contained here (the 'Feature ID by GPU instance' mentioned in #40 (comment) was not yet integrated here, but is still on an implicit TODO list)