Release: Extensions (#2497)

- capture STDERR to fix #2495
- release #2492 
- release #2493
- moves `trimesh/exchange/gltf.py` to
`trimesh/exchange/gltf/__init__.py` which is identical for import users,
but lets us add the additional `extensions.py` next to it.

Author: mikedh

pyproject.toml

@@ -5,7 +5,7 @@ requires = ["setuptools >= 61.0", "wheel"]
 [project]
 name = "trimesh"
 requires-python = ">=3.8"
-version = "4.10.1"
+version = "4.11.0"
 authors = [{name = "Michael Dawson-Haggerty", email = "[email protected]"}]
 license = {file = "LICENSE.md"}
 description = "Import, export, process, analyze and view triangular meshes."
@@ -48,6 +48,7 @@ packages = [
     "trimesh.visual",
     "trimesh.viewer",
     "trimesh.exchange",
+    "trimesh.exchange.gltf",
     "trimesh.resources",
     "trimesh.interfaces",
 ]

trimesh/exchange/binvox.py

@@ -553,7 +553,7 @@ def __call__(self, path, overwrite=False):
 
         # generalizes to python2 and python3
         # will capture terminal output into variable rather than printing
-        verbosity = subprocess.check_output(self._args)
+        verbosity = subprocess.check_output(self._args, stderr=subprocess.STDOUT)
 
         # if requested print ourselves
         if self.verbose:
@@ -598,6 +598,7 @@ def voxelize_mesh(mesh, binvoxer=None, export_type="off", **binvoxer_kwargs):
         out_path = binvoxer(model_path)
         with open(out_path, "rb") as fp:
             out_model = load_binvox(fp)
+
     return out_model
 
 

trimesh/exchange/gltf.py trimesh/exchange/gltf/__init__.pytrimesh/exchange/gltf.py renamed to trimesh/exchange/gltf/__init__.py

@@ -1,5 +1,5 @@
 """
-gltf.py
+gltf/__init__.py
 ------------
 
 Provides GLTF 2.0 exports of trimesh.Trimesh objects
@@ -13,14 +13,14 @@
 
 import numpy as np
 
-from .. import rendering, resources, transformations, util, visual
-from ..caching import hash_fast
-from ..constants import log, tol
-from ..resolvers import ResolverLike, ZipResolver
-from ..scene.cameras import Camera
-from ..typed import Dict, List, NDArray, Optional, Stream
-from ..util import triangle_strips_to_faces, unique_name
-from ..visual.gloss import specular_to_pbr
+from ... import rendering, resources, transformations, util, visual
+from ...caching import hash_fast
+from ...constants import log, tol
+from ...resolvers import ResolverLike, ZipResolver
+from ...scene.cameras import Camera
+from ...typed import Dict, List, NDArray, Optional, Stream
+from ...util import triangle_strips_to_faces, unique_name
+from .extensions import handle_extensions
 
 # magic numbers which have meaning in GLTF
 # most are uint32's of UTF-8 text
@@ -75,6 +75,7 @@ def export_gltf(
     tree_postprocessor=None,
     embed_buffers=False,
     extension_webp=False,
+    extension_draco=False,
 ):
     """
     Export a scene object as a GLTF directory.
@@ -101,6 +102,9 @@ def export_gltf(
       Embed the buffer into JSON file as a base64 string in the URI
     extension_webp : bool
       Export textures as webP (using glTF's EXT_texture_webp extension).
+    extension_draco : bool
+      Compress mesh data using Draco (KHR_draco_mesh_compression).
+      Requires the `dracox` package to be installed.
 
     Returns
     ----------
@@ -117,6 +121,7 @@ def export_gltf(
         unitize_normals=unitize_normals,
         include_normals=include_normals,
         extension_webp=extension_webp,
+        extension_draco=extension_draco,
     )
 
     # allow custom postprocessing
@@ -172,6 +177,7 @@ def export_glb(
     tree_postprocessor=None,
     buffer_postprocessor=None,
     extension_webp=False,
+    extension_draco=False,
 ):
     """
     Export a scene as a binary GLTF (GLB) file.
@@ -189,6 +195,9 @@ def export_glb(
       before exporting.
     extension_webp : bool
       Export textures as webP using EXT_texture_webp extension.
+    extension_draco : bool
+      Compress mesh data using Draco (KHR_draco_mesh_compression).
+      Requires the `dracox` package to be installed.
 
     Returns
     ----------
@@ -206,6 +215,7 @@ def export_glb(
         include_normals=include_normals,
         buffer_postprocessor=buffer_postprocessor,
         extension_webp=extension_webp,
+        extension_draco=extension_draco,
     )
 
     # A bufferView is a slice of a file
@@ -610,6 +620,7 @@ def _create_gltf_structure(
     unitize_normals=None,
     buffer_postprocessor=None,
     extension_webp=False,
+    extension_draco=False,
 ):
     """
     Generate a GLTF header.
@@ -626,6 +637,8 @@ def _create_gltf_structure(
       Unitize all exported normals so as to pass GLTF validation
     extension_webp : bool
       Export textures as webP using EXT_texture_webp extension.
+    extension_draco : bool
+      Compress mesh data using Draco (KHR_draco_mesh_compression).
 
     Returns
     ---------------
@@ -683,6 +696,7 @@ def _create_gltf_structure(
                 unitize_normals=unitize_normals,
                 mat_hashes=mat_hashes,
                 extension_webp=extension_webp,
+                extension_draco=extension_draco,
             )
         elif util.is_instance_named(geometry, "Path"):
             # add Path2D and Path3D objects
@@ -703,26 +717,33 @@ def _create_gltf_structure(
     tree.update(nodes)
 
     extensions_used = set()
+    extensions_required = set()
     # Add any scene extensions used
     if "extensions" in tree:
         extensions_used = extensions_used.union(set(tree["extensions"].keys()))
     # Add any mesh extensions used
     for mesh in tree["meshes"]:
         if "extensions" in mesh:
             extensions_used = extensions_used.union(set(mesh["extensions"].keys()))
+        # Check primitives for extensions too
+        for prim in mesh.get("primitives", []):
+            if "extensions" in prim:
+                extensions_used = extensions_used.union(set(prim["extensions"].keys()))
     # Add any extensions already in the tree (e.g. node extensions)
     if "extensionsUsed" in tree:
         extensions_used = extensions_used.union(set(tree["extensionsUsed"]))
     # Add WebP if used
     if extension_webp:
         extensions_used.add("EXT_texture_webp")
+        extensions_required.add("EXT_texture_webp")
+    # Add Draco if used (no fallback, so required)
+    if extension_draco:
+        extensions_used.add("KHR_draco_mesh_compression")
+        extensions_required.add("KHR_draco_mesh_compression")
     if len(extensions_used) > 0:
         tree["extensionsUsed"] = list(extensions_used)
-
-    # Also add WebP to required (no fallback currently implemented)
-    # 'extensionsRequired' aren't currently used so this doesn't overwrite
-    if extension_webp:
-        tree["extensionsRequired"] = ["EXT_texture_webp"]
+    if len(extensions_required) > 0:
+        tree["extensionsRequired"] = list(extensions_required)
 
     if buffer_postprocessor is not None:
         buffer_postprocessor(buffer_items, tree)
@@ -748,6 +769,7 @@ def _append_mesh(
     unitize_normals: bool,
     mat_hashes: dict,
     extension_webp: bool,
+    extension_draco: bool = False,
 ):
     """
     Append a mesh to the scene structure and put the
@@ -773,6 +795,8 @@ def _append_mesh(
       Which materials have already been added
     extension_webp : bool
       Export textures as webP (using glTF's EXT_texture_webp extension).
+    extension_draco : bool
+      Compress mesh data using Draco (KHR_draco_mesh_compression).
     """
     # return early from empty meshes to avoid crashing later
     if len(mesh.faces) == 0 or len(mesh.vertices) == 0:
@@ -963,6 +987,24 @@ def _append_mesh(
             data=data,
         )
 
+    # Handle Draco compression via extension handler
+    if extension_draco:
+        # Determine if normals should be included
+        should_include_normals = include_normals or (
+            include_normals is None and "vertex_normals" in mesh._cache.cache
+        )
+        # Call primitive_export handlers
+        handle_extensions(
+            extensions={"KHR_draco_mesh_compression": {}},
+            scope="primitive_export",
+            mesh=mesh,
+            name=name,
+            tree=tree,
+            buffer_items=buffer_items,
+            primitive=current["primitives"][0],
+            include_normals=should_include_normals,
+        )
+
     tree["meshes"].append(current)
 
 
@@ -1318,35 +1360,29 @@ def _parse_materials(header, views, resolver=None):
       List of trimesh.visual.texture.Material objects
     """
 
-    def parse_values_and_textures(input_dict):
+    def parse_textures(*, data):
         result = {}
-        for k, v in input_dict.items():
+        for k, v in data.items():
             if isinstance(v, (list, tuple)):
                 # colors are always float 0.0 - 1.0 in GLTF
                 result[k] = np.array(v, dtype=np.float64)
             elif not isinstance(v, dict):
                 result[k] = v
             elif images is not None and "index" in v:
                 try:
-                    # get the index of image for texture
+                    index = None
                     texture = header["textures"][v["index"]]
-                    # check to see if this is using a webp extension texture
-                    # should this be case sensitive?
-                    webp = (
-                        texture.get("extensions", {})
-                        .get("EXT_texture_webp", {})
-                        .get("source")
-                    )
-                    if webp is not None:
-                        idx = webp
-                    elif "source" in texture:
-                        # fallback (or primary, if extensions are not present)
-                        idx = texture["source"]
-                    else:
-                        # no source available
-                        continue
-                    # store the actual image as the value
-                    result[k] = images[idx]
+                    # Handle texture extensions through registry
+                    if tex_ext := texture.get("extensions"):
+                        index = handle_extensions(
+                            extensions=tex_ext, scope="texture_source"
+                        )
+
+                    if index is None:
+                        # fall back to standard source key
+                        index = texture.get("source")
+                    if index is not None:
+                        result[k] = images[index]
                 except BaseException:
                     log.debug("unable to store texture", exc_info=True)
         return result
@@ -1364,15 +1400,21 @@ def parse_values_and_textures(input_dict):
                 # add keys of keys to top level dict
                 loopable.update(loopable.pop("pbrMetallicRoughness"))
 
-            ext = mat.get("extensions", {}).get(
-                "KHR_materials_pbrSpecularGlossiness", None
-            )
-            if isinstance(ext, dict):
-                ext_params = parse_values_and_textures(ext)
-                loopable.update(specular_to_pbr(**ext_params))
+            # Handle material extensions through registry
+            if mat_extensions := mat.get("extensions"):
+                ext_results = handle_extensions(
+                    extensions=mat_extensions,
+                    scope="material",
+                    parse_textures=parse_textures,
+                    images=images,
+                )
+                # Flatten extension results into the material parameters
+                for ext_result in ext_results.values():
+                    if isinstance(ext_result, dict):
+                        loopable.update(ext_result)
 
             # save flattened keys we can use for kwargs
-            pbr = parse_values_and_textures(loopable)
+            pbr = parse_textures(data=loopable)
             # create a PBR material object for the GLTF material
             materials.append(visual.material.PBRMaterial(**pbr))
 
@@ -1523,6 +1565,17 @@ def _read_buffers(
                 metadata["gltf_extensions"] = m["extensions"]
 
             for p in m["primitives"]:
+                # Handle primitive preprocessing extensions (e.g. Draco decompression)
+                # These run before reading accessors since they may modify them
+                if prim_extensions := p.get("extensions"):
+                    handle_extensions(
+                        extensions=prim_extensions,
+                        scope="primitive_preprocess",
+                        primitive=p,
+                        accessors=access,
+                        views=views,
+                    )
+
                 # if we don't have a triangular mesh continue
                 # if not specified assume it is a mesh
                 kwargs = deepcopy(mesh_kwargs)
@@ -1543,7 +1596,7 @@ def _read_buffers(
 
                 if mode == _GL_LINES:
                     # load GL_LINES into a Path object
-                    from ..path.entities import Line
+                    from ...path.entities import Line
 
                     kwargs["vertices"] = access[attr["POSITION"]]
                     kwargs["entities"] = [Line(points=np.arange(len(kwargs["vertices"])))]
@@ -1642,6 +1695,16 @@ def _read_buffers(
                     }
                     if len(custom) > 0:
                         kwargs["vertex_attributes"] = custom
+
+                    # Process primitive-level extensions through registry
+                    if prim_extensions := p.get("extensions"):
+                        handle_extensions(
+                            extensions=prim_extensions,
+                            scope="primitive",
+                            primitive=p,
+                            mesh_kwargs=kwargs,
+                            accessors=access,
+                        )
                 else:
                     log.debug("skipping primitive with mode %s!", mode)
                     continue
@@ -2098,7 +2161,7 @@ def _append_material(mat, tree, buffer_items, mat_hashes, extension_webp):
             # add a reference to the base color texture
             result[key] = {"index": len(tree["textures"])}
 
-            # add an object for the texture according to the WebP extension
+            # add texture object, optionally using EXT_texture_webp
             if extension_webp:
                 tree["textures"].append(
                     {"extensions": {"EXT_texture_webp": {"source": index}}}
@@ -2174,7 +2237,7 @@ def get_schema():
     """
     # replace references
     # get zip resolver to access referenced assets
-    from ..schemas import resolve
+    from ...schemas import resolve
 
     # get a blob of a zip file including the GLTF 2.0 schema
     stream = resources.get_stream("schema/gltf2.schema.zip")