Folder and File Structure standards?
echadwick-artist opened this issue · comments
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
.gltffile in the/glTFsubfolder.- For example
Models/ABeautifulGamematchesModels/ABeautifulGame/glTF/ABeautifulGame.gltf
- For example
metadata.jsonfile containing the asset metadata (see below).README.body.mdfile containing the asset description (see below)./glTFsubfolder 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-JPGsubfolder (see below).
- PNG textures are preferred to avoid compression artifacts; if a variant is desired with .jpeg resources it can be provided in a
/screenshotsubfolder is mandatory, it should contain the screenshot plus any other resources used in the README.md./glTF-Binarysubfolder is optional, if a variant is included for a binary .glb./glTF-Dracosubfolder is optional, if a variant is included with compressed geometry using the extension KHR_draco_mesh_compression./glTF-Embeddedsubfolder is optional, if a variant is included for an embedded .gltf./glTF-IBLsubfolder is optional, if a variant is included using custom image-based lighting; for example with the extension EXT_lights_image_based./glTF-JPGsubfolder is optional, if a variant is included using resources in compressed .jpeg format./glTF-KTX-BasisUsubfolder is optional, if a variant is included with compressed textures using the extension KHR_texture_basisu./glTF-Quantizedsubfolder is optional, if a variant is included with compressed geometry using the extension KHR_mesh_quantization.
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?
JPEG compression should be recommended for asset in the main \glTF folder.
Only for color textures and only if compression artifacts are not visible.
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
.gltffile in the/glTFsubfolder.- For example
Models/ABeautifulGamematchesModels/ABeautifulGame/glTF/ABeautifulGame.gltf
- For example
metadata.jsonfile containing the asset metadata (see below).README.body.mdfile containing the asset description (see below)./glTFsubfolder 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.
/screenshotsubfolder is mandatory, it should contain the screenshot plus any other resources used in the README.md.- The
/screenshot/screenshot.jpgfile 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.
- The
/glTF-Binarysubfolder is optional, if a variant is included for a binary .glb./glTF-Dracosubfolder is optional, if a variant is included with compressed geometry using the extension KHR_draco_mesh_compression./glTF-Embeddedsubfolder is optional, if a variant is included for an embedded .gltf./glTF-IBLsubfolder is optional, if a variant is included using custom image-based lighting; for example with the extension EXT_lights_image_based./glTF-PNGsubfolder is optional, if a variant is included using all texture resources in uncompressed .png format./glTF-KTX-BasisUsubfolder is optional, if a variant is included with compressed textures using the extension KHR_texture_basisu./glTF-Quantizedsubfolder is optional, if a variant is included with compressed geometry using the extension KHR_mesh_quantization.
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?
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.
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)