Skip to content

Commit b007a68

Browse files
committed
[doc] Geometry "supported file formats" explains ktx2 textures
We also refresh some glTF-related details (e.g., VTK support).
1 parent ac9dc3f commit b007a68

File tree

1 file changed

+27
-7
lines changed

1 file changed

+27
-7
lines changed

geometry/geometry_file_formats_doxygen.h

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -185,26 +185,31 @@ namespace geometry {
185185
notable exceptions:
186186
187187
- .glb "container" files are not supported.
188-
- Support for glTF extensions depends on the ultimate consumer of the glTF
189-
file (see below).
188+
- Support for glTF
189+
<a href="https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#specifying-extensions">extensions</a>
190+
depends on the ultimate consumer of the glTF file (see below).
190191
- Animation and skinning. If such data is present, it is ignored.
191192
192193
A Mesh file can reference a .gltf file but only for visual roles.
193194
194195
- Illustration roles
195196
- .gltf features are well supported in meshcat-based visualizers (using
196197
either MeshcatVisualizer or DrakeVisualizer in conjunction with meldis).
197-
- There is generally broad support for glTF extensions.
198+
- There is generally
199+
<a href="https://threejs.org/docs/?q=loader#examples/en/loaders/GLTFLoader">broad support</a>
200+
for glTF extensions.
198201
- To get optimal visual appearance, Meshcat should be configured to use an
199202
environment map (see Meshcat::SetEnvironmentMap()).
200203
201204
- Perception roles
202205
- RenderEngineGl does not support .gltf files. A Mesh or Convex which
203206
references such a file will be silently ignored.
204207
- RenderEngineVtk does support .gltf files.
205-
- As VTK does not support extensions, RenderEngineVtk does not either.
206-
- RenderEngineVtk does not yet support specifying an environment map.
207-
This will lead to PBR materials being under illuminated.
208+
- The glTF extensions supported are whatever VTK's glTF loader
209+
implements, which at the time of this writing are KHR_lights_punctual
210+
and KHR_materials_unlit.
211+
- To get optimal visual appearance, RenderEngineVtk should be configured
212+
to use an environment map (see RenderEngineVtkParams::environment_map).
208213
- RenderEngineGltfClient does support .gltf files (as the name suggests).
209214
- Geometries defined by a .gltf file are passed almost verbatim to the
210215
render server (animation and morphing data is excluded).
@@ -220,7 +225,22 @@ namespace geometry {
220225
221226
As a rule of thumb, for Drake's purposes .gltf files with external assets
222227
(i.e., separate .bin and .png files) will load faster than .gltf files
223-
with assets embedded as base64-encoded `data:` URIs.
228+
with assets embedded as base64-encoded data URIs.
229+
230+
For best performance, we recommend that meshes destined for the Illustration
231+
role use the
232+
<a href="https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_texture_basisu/README.md">KHR_texture_basisu</a>
233+
extension, where textures are stored using the .ktx2 file format. Loading .ktx2
234+
textures in a web browser is substantially faster than .png textures. In the
235+
common case where the same mesh will also be used by the Perception role, be
236+
aware that many render engines do not support the KHR_texture_basisu extension
237+
so it should be listed in "extensionsUsed" but not "extensionsRequired" in the
238+
.gltf file for widest compatibility. (The mesh will have both .png and .ktx2
239+
textures available.) Refer to the
240+
<a href="https://github.com/RobotLocomotion/models">Drake models repository</a>
241+
for examples. To convert .png files to .ktx2 files, refer to the
242+
<a href="https://github.com/KhronosGroup/KTX-Software">KTX-Software</a>
243+
repository.
224244
225245
<!-- TODO(SeanCurtis-TRI): Flesh this out. Technically, Meshcat will consume
226246
the .dae file. But it will probably cause chaos if passed anywhere else.

0 commit comments

Comments
 (0)