Folder and File Structure standards?

[echadwick-artist]

I think we could use some standardization for folders and files.

There are a few of the unwritten rules I learned from other contributors a few years ago, when I started submitting assets to these repos.

I think these rules should be codified into the SubmittingModels.md documentation, but I would like feedback from other contributors before we add this additional section. There are also a few typos in the md, but those shouldn't require discussion.

I propose to add this section to SubmittingModels.md :

Folder and File Structure

Folder and file names must be consistent as this helps with tooling and automation.

• Asset top folder should use the same name as the .gltf file in the /glTF subfolder.
  • For example Models/ABeautifulGame matches Models/ABeautifulGame/glTF/ABeautifulGame.gltf
• metadata.json file containing the asset metadata (see below).
• README.body.md file containing the asset description (see below).
• /glTF subfolder is mandatory, it should contain the asset with JSON .gltf, .bin, and all individual resources (such as textures).
  • PNG textures are preferred to avoid compression artifacts; if a variant is desired with .jpeg resources it can be provided in a /glTF-JPG subfolder (see below).
• /screenshot subfolder is mandatory, it should contain the screenshot plus any other resources used in the README.md.
• /glTF-Binary subfolder is optional, if a variant is included for a binary .glb.
• /glTF-Draco subfolder is optional, if a variant is included with compressed geometry using the extension KHR_draco_mesh_compression.
• /glTF-Embedded subfolder is optional, if a variant is included for an embedded .gltf.
• /glTF-IBL subfolder is optional, if a variant is included using custom image-based lighting; for example with the extension EXT_lights_image_based.
• /glTF-JPG subfolder is optional, if a variant is included using resources in compressed .jpeg format.
• /glTF-KTX-BasisU subfolder is optional, if a variant is included with compressed textures using the extension KHR_texture_basisu.
• /glTF-Quantized subfolder is optional, if a variant is included with compressed geometry using the extension KHR_mesh_quantization.

[echadwick-artist]

Rethinking this sentence:

PNG textures are preferred to avoid compression artifacts; if a variant is desired with .jpeg resources it can be provided in a /glTF-JPG subfolder (see below).

I think reducing file size for the repo is an important consideration, and JPEG compression should be recommended for asset in the main \glTF folder.

Should we include a \Source-Assets folder, including the DCC-native model source format, and uncompressed textures in PNG format?

[lexaknyazev]

JPEG compression should be recommended for asset in the main \glTF folder.

Only for color textures and only if compression artifacts are not visible.

[echadwick-artist]

Thanks Alexey. Updated:

Folder and File Structure

Folder and file names must be consistent as this helps with tooling and automation.

• Asset top folder should use the same name as the .gltf file in the /glTF subfolder.
  • For example Models/ABeautifulGame matches Models/ABeautifulGame/glTF/ABeautifulGame.gltf
• metadata.json file containing the asset metadata (see below).
• README.body.md file containing the asset description (see below).
• /glTF subfolder is mandatory, it should contain the asset with JSON .gltf, .bin, and all individual resources (such as textures).
  • JPEG compression is recommended for assets in the main \glTF folder, only for color textures and only if compression artifacts are not noticeable.
• /screenshot subfolder is mandatory, it should contain the screenshot plus any other resources used in the README.md.
  • The /screenshot/screenshot.jpg file should use JPG format with the largest dimension at 150 pixels. The small size allows preview pages to be loaded quickly, and the uniform width improves page formatting.
  • Optionally, a higher resolution version may also be included. A larger screenshot is useful for showing nice rendering features, and should be embedded into the asset readme. It should be named /screenshot/screenshot_Large.jpg. The resolution should be 1280 pixels for the longest dimension, for example 1280x720 which is 720p HD.
• /glTF-Binary subfolder is optional, if a variant is included for a binary .glb.
• /glTF-Draco subfolder is optional, if a variant is included with compressed geometry using the extension KHR_draco_mesh_compression.
• /glTF-Embedded subfolder is optional, if a variant is included for an embedded .gltf.
• /glTF-IBL subfolder is optional, if a variant is included using custom image-based lighting; for example with the extension EXT_lights_image_based.
• /glTF-PNG subfolder is optional, if a variant is included using all texture resources in uncompressed .png format.
• /glTF-KTX-BasisU subfolder is optional, if a variant is included with compressed textures using the extension KHR_texture_basisu.
• /glTF-Quantized subfolder is optional, if a variant is included with compressed geometry using the extension KHR_mesh_quantization.

[lexaknyazev]

screenshot_Large

Inconsistent spelling here. Should be either screenshotLarge or screenshot_large. The latter would be my preference.

---

/glTF-PNG

Consider suggesting hi-res images in this case.

---

Should there be a standard name for meshopt-compressed assets?

[spnda]

Should there be a standard name for meshopt-compressed assets?

Also, is there any particular reason why all sample models for EXT_meshopt_compression were removed for this repository? I use them in my testing CI, and these removals are currently keeping me from switching.

[emackey]

@spnda The missing models have returned in #124.

[javagl]

It's good that this issue was "bumped", because ... it's still open, and there are some open questions.

The information from the updated "Folder and File Structure" list above could be inserted somewhere near https://github.com/KhronosGroup/glTF-Sample-Assets/blob/main/SubmittingModels.md#requirement-details

(Beyond that: IIRC, when I submitted the last model, it wasn't perfectly clear for me which parts of the metadata JSON have to be provided in which form, but maybe that can be clarified in a PR that addresses this issue as well)