First minor wording pass for content_gltf

[javagl]

• Renamed "glTF model" to "glTF asset", roughly inspired by EXT_feature_metadata deep dive glTF#4 (comment)

• I tried to explain the "Why" before the "How" for using the 3DTILES_content_gltf structure to declare the extensions that are used by the glTF asset. I found the naming a bit confusing at the first glance, and wonder why the name was changed from gltfExtensionsUsed to extensionsUsed in bc21c2c#diff-ca64f943dc5ef8ec5baabf371a7dffd2270adb6a64b4456fd98b8d87b43c0790 ...

The "Comparison with Existing Tile Formats" section may need some polishing:

• The links will have to be updated at some point

• Some technical terms have to be reviewed to be consistent with other specs (e.g. "information" vs. "metadata" vs. "properties").

• I actually started changing "to instance" to "to instantiate" (c.f. https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#374-instantiation ), but for the sake of consistency with the Instanced3DModel spec, did not do this, eventually.

• Do we go all the way of using "may" as in https://www.rfc-editor.org/rfc/rfc2119.txt ? (Then, we could omit the word "can"...)

• Not being a native English speaker, I can only say that I'd write "Batched 3D Model content can be converted into glTF content" instead of "Batched 3D Model content can converted to a glTF content", but that may also be wrong (or it may not matter at all). At least, I'm reasonably sure about the missing "be"...

• I was tempted to rephrase the common statement

  • RTC_CENTER can instead be stored in a glTF node translation.
    to
  • The RTC_CENTER can be added to the translation component of the root node of the glTF asset
    but that may sound too convoluted...

[ptrgags]

@donmccurdy could you do the first review pass?

[donmccurdy]

Good wording changes! Replies to the bullet points inline:

I found the naming a bit confusing at the first glance, and wonder why the name was changed from gltfExtensionsUsed to extensionsUsed...

I'm undecided on this one. In glTF we try to use terms that wouldn't need to change if the extension were merged into the core specification, i.e. if the extension wrapper did not exist. So e.g. for KHR_materials_clearcoat, every property begins with the term "clearcoat". But I don't know if that same philosophy is useful for 3D Tiles.

Some technical terms have to be reviewed to be consistent with other specs (e.g. "information" vs. "metadata" vs. "properties").

We leaned pretty heavily on the term "properties" in EXT_mesh_features, because the term "metadata" is overloaded in the glTF space. I think either term is OK for 3D Tiles — we may still have time to claim the term "metadata" here if we want, without overloading it? — as long as we're consistent. I'm not sure which I prefer.

Do we go all the way of using "may" as in https://www.rfc-editor.org/rfc/rfc2119.txt ? (Then, we could omit the word "can"...)

I slightly prefer the word "may" as well, but either is OK with me.

I'd write "Batched 3D Model content can be converted into glTF content" instead of "Batched 3D Model content can converted to a glTF content",

Agreed, both changes improve the sentence. (reference) 👍

The RTC_CENTER can be added to the translation component of the root node of the glTF asset...

I can't quite tell how RTC_CENTER relates to the sections it is used in, so some clarification might be helpful. Maybe "Root node of glTF asset may be translated, rather than using RTC_CENTER." Does RTC_CENTER always affect the whole model, so only translation of the root is relevant?

[donmccurdy]

Suggested change

	With this extension, the tile content may be a glTF asset. In order to allow runtime engines to determine compatibility before loading the content, any extensions that are required by the glTF asset must be declared in the `3DTILES_content_gltf` object. This is a property of the top-level tileset `extensions` object and contains two optional properties:
	With this extension, the tile content may be a glTF asset. In order to allow runtime engines to determine compatibility before loading the content, any extensions that are required by the glTF asset must be declared in the `3DTILES_content_gltf` object. This is a property of the top-level tileset `extensions` object and contains two properties:

Found the combination of "must be declared" and "two optional properties" confusing at first – if needed we could add another sentence saying that when no extensions are required or used, the respective properties should be omitted?

[donmccurdy]

Suggested change

	* [`EXT_mesh_gpu_instancing`](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/EXT_mesh_gpu_instancing) may be used to instance glTF assets. The extension supports per-instance translations, rotations, and scales.
	* glTF 2.0 supports reuse of the same mesh at multiple translations, rotations, and scales. To optimize reused meshes for more efficient GPU instancing, [`EXT_mesh_gpu_instancing`](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/EXT_mesh_gpu_instancing) may be used.

In reviewing EXT_mesh_gpu_instancing there was some ambiguity around the term "instancing": some other software uses the term "instancing" to mean any kind of data reuse. In this appendix we disambiguate between "data instancing" and "GPU instancing".

I think "glTF asset" is the right term for the paragraph above, but in this case it might be more correct to say "mesh" since the extension does not instance the entire asset.

[lilleyse]

I found the naming a bit confusing at the first glance, and wonder why the name was changed from gltfExtensionsUsed to extensionsUsed in bc21c2c#diff-ca64f943dc5ef8ec5baabf371a7dffd2270adb6a64b4456fd98b8d87b43c0790 ...

I wouldn't be opposed to changing it back as I've been confused too when looking at tilesets that use this extension. If everyone else is good with that we should make the change.

Originally we thought gltfExtensionsUsed was superfluous but it's probably fine.

[lilleyse]

Meta comments:

1. Do we need the appendix? Is it useful? Or can it just be removed?
2. Do we need the JSON Schema Reference? I think we decided to remove that from EXT_mesh_features since many glTF and 3D Tiles extensions don't actually have a JSON Schema Reference section like the core spec does.

[donmccurdy]

Maybe contentExtensionsUsed? Pros: "gltf" looks odd in camelCase, Cons: less specific. Related: KhronosGroup/glTF#2060

Do we need the appendix? Is it useful? Or can it just be removed?

I think it's a bit unusual for the spec to include what looks (to me at least) like a migration guide. But if you think the question will come up a lot, that does seem like a useful thing to have in writing for sure. Could also make for a good technical blog post at some point.

Do we need the JSON Schema Reference?

I'd be in favor of omitting the markdown generated from the property reference, at least until there's a good way to +/- instantly rebuild that without manual work. I think the inline links to schema files are reasonably clear in CesiumGS/glTF#21, would be curious if that reads way the same to others.

[javagl]

The minor wording comments have been integrated. I hesitated a bit regarding the extensionsUsed/extensionsRequired properties. It may be "spec-level-nitpicking", but one question that came to my mind was whether there should be statements like

• When a glTF asset declares extensionsRequired, then they MUST be declared in the 3DTILES_content_gltf.extensionsRequired array
• When a glTF asset declares extensionsUsed, then they MUST/MAY/SHOULD (?) be declared in the 3DTILES_content_gltf.extensionsUsed array

The first one is clear. The second one is debatable...

---

We leaned pretty heavily on the term "properties" in EXT_mesh_features

To achieve some consistency here, I aligned the wording of "per-point metadata and multi-point metadata" to "per-point properties and multi-point features", as it seems to be called in https://github.com/donmccurdy/glTF/blob/ext-feature-metadata-v2.9/extensions/2.0/Vendor/EXT_mesh_features/README.md#examples

---

Does RTC_CENTER always affect the whole model, so only translation of the root is relevant?

To my understanding, this is the case - but with the disclaimer that I'd have to think carefully (and re-read) about the roles of skeleton hierarchies. I slightly elaborated that statement, hoping that it adds clarification.

---

Maybe contentExtensionsUsed? Pros: "gltf" looks odd in camelCase, Cons: less specific.

Maybe, one day, we'll have a 3DTILES_content_collada extension and then re-use the contentExtensionsUsed arrays? :D I don't have a strong preference, but think that contentExtensionsUsed could avoid confusion.

---

Do we need the JSON Schema Reference?

This seems to be a general question. I think that at least the extension specs should be "consistent", in that they either all contain that reference, or none of them. And I think that they currently all contain that reference, so I think it's OK to leave it there. (It's far easier to remove that in all of them, than to add it back later...).

Do we need the appendix?

Instead of plainly removing it, one option could be to move that into some MIGRATION_GUIDE.md (or whatever it is called), and link to that, maybe even in the "Overview" section, with something like

In many cases, existing tile formats can be converted into the corresponding glTF content, as described in the [MIGRATION_GUIDE.md].

?

[javagl]

@ptrgags The schema reference has been removed, and the appendix is moved to a dedicated document (I hope the name MIGRATION_GUIDE.md is OK...)

[donmccurdy]

I hesitated a bit regarding the extensionsUsed/extensionsRequired properties. It may be "spec-level-nitpicking"...

I'm not sure I understand the intended use of the extensionsUsed/Required properties in 3DTILES_content_gltf well enough to make a suggestion here, it might be easier to address this item in Slack or a call. I don't think it needs to hold up this PR.

To achieve some consistency here, I aligned the wording of "per-point metadata and multi-point metadata" to "per-point properties and multi-point features"

👍

Maybe, one day, we'll have a 3DTILES_content_collada extension...

See earlier comment – I don't think we need to spend too much time worrying about hypotheticals like COLLADA or merging the extension into the core spec, but I would like to understand the current use of extensionsUsed/Required a bit better than I do now.

Do we need the JSON Schema Reference?

In many cases, existing tile formats can be converted into the corresponding glTF content, as described in the [MIGRATION_GUIDE.md].

We addressed both of these during today's call, right? Or let me know if not!

[ptrgags]

@javagl read through your edits, I only see a few places that need some tweaks.

I still need to look through the comments above to make sure I didn't overlook anything that others have brought up.

[ptrgags]

Maybe link to the section where RTC_CENTER is defined? https://github.com/CesiumGS/3d-tiles/tree/main/specification/TileFormats/Batched3DModel#coordinate-system

[javagl]

There are some places where I thought that a link to the corresponding documentation could be helpful - and that literally (and figuratively) starts at the highest level, meaning that the first sentence could be "Written against the [3D Tiles 1.0 specification](link)."

If there is a geenral guideline like "Add links when a reference is mentioned for the first time", then I can take that into account in future review passes.

[ptrgags]

@javagl hm yeah to some extent mentioning the 3D Tiles 1.0 specification is enough for most details

Though here with RTC_CENTER, this is a less obvious detail that a reader might miss in the main specification if they're not reading it carefully, so this link is for added clarity.

[lilleyse]

We addressed both of these during today's call, right? Or let me know if not!

What were the decisions from the call? I wasn't able to make it today.

[ptrgags]

Ah, let me summarize:

• regarding the schema reference, we opted to remove it in favor of a link to the schema since we don't have a sure-fire way of running wetzel on extensions.
• regarding the appendix, we decided to move it to its own document (at least for now)
• in terms of the contentExtensionsUsed vs gltfExtensionsUsed we decided to hold off on this until we can all be there to discuss it. Could even be a separate PR if we later decide to change it.

[javagl]

The links to the schema still have to be added. More generally, there may be other links that could be useful, as of the comment at #488 (comment) , but I'll start with the schema links and RTC_CENTER (a bit later today)

[ptrgags]

@javagl sorry for the delay. The changes look good, thanks!