Renaming and changing the behavior of parse_glb_zup.

Author: AnisB

genesis/engine/mesh.py

@@ -58,6 +58,9 @@ def __init__(
         self._metadata = metadata or {}
         self._color = np.array([1.0, 1.0, 1.0, 1.0], dtype=gs.np_float)
 
+        # By default, all meshes are considered zup, unless the "FileMorph.file_meshes_are_zup" option was set to False.
+        self._metadata["imported_as_zup"] = True
+
         if self._surface.requires_uv():  # check uvs here
             if self._uvs is None:
                 if "mesh_path" in metadata:
@@ -340,20 +343,19 @@ def from_morph_surface(cls, morph, surface=None):
         if isinstance(morph, gs.options.morphs.Mesh):
             if morph.is_format(gs.options.morphs.MESH_FORMATS):
                 meshes = mu.parse_mesh_trimesh(morph.file, morph.group_by_material, morph.scale, surface)
+                if not morph.file_meshes_are_zup:
+                    for mesh in meshes:
+                        mesh.convert_to_zup()
+                    gs.logger.debug(f"Converting the geometry of the '{morph.file}' file to zup.")
             elif morph.is_format(gs.options.morphs.GLTF_FORMATS):
                 if morph.parse_glb_with_trimesh:
                     meshes = mu.parse_mesh_trimesh(morph.file, morph.group_by_material, morph.scale, surface)
                 else:
                     meshes = gltf_utils.parse_mesh_glb(morph.file, morph.group_by_material, morph.scale, surface)
-                if morph.parse_glb_with_zup:
-                    for mesh in meshes:
-                        mesh.convert_to_zup()
-                else:
-                    gs.logger.warning(
-                        "GLTF is using y-up while Genesis uses z-up. Please set parse_glb_with_zup=True"
-                        " in morph options if you find the mesh is 90-degree rotated. We will set parse_glb_with_zup=True"
-                        " and rotate glb mesh by default later and gradually enforce this option."
-                    )
+                # The GLF spec defines that all meshes are Yup, ignoring the FileMorph.file_meshes_are_zup option.
+                for mesh in meshes:
+                    mesh.convert_to_zup()
+                gs.logger.debug(f"Converting the GLTF geometry to zup '{morph.file}'")
             elif morph.is_format(gs.options.morphs.USD_FORMATS):
                 import genesis.utils.usda as usda_utils
 
@@ -403,6 +405,7 @@ def convert_to_zup(self):
         Convert the mesh to z-up.
         """
         self._mesh.apply_transform(mu.Y_UP_TRANSFORM.T)
+        self._metadata["imported_as_zup"] = False
 
     def apply_transform(self, T):
         """

genesis/options/morphs.py

@@ -522,7 +522,12 @@ class FileMorph(Morph):
     coacd_options : CoacdOptions, optional
         Options for configuring coacd convex decomposition. Needs to be a `gs.options.CoacdOptions` object.
     parse_glb_with_zup : bool, optional
-        Whether to use zup to load glb files. Defaults to False.
+        This parameter is deprecated, see file_meshes_are_zup.
+    file_meshes_are_zup : bool, optional
+        Defines if the mesh files are expressed in a Z-up or Y-up coordinate system. If set to true, meshes are loaded
+        as Z-up and no transforms are applied to the input data. If set to false, all meshes undergo a conversion step
+        where the original coordinates are transformed as follows: (X, Y, Z) → (X, -Z, Y).
+        This conversion always applies to GLTF/GLB files, as they are defined as Y-up by the standard. Defaults to true.
     visualization : bool, optional
         Whether the entity needs to be visualized. Set it to False if you need a invisible object only for collision
         purposes. Defaults to True. `visualization` and `collision` cannot both be False.
@@ -549,7 +554,8 @@ class FileMorph(Morph):
     decompose_robot_error_threshold: float = float("inf")
     coacd_options: Optional[CoacdOptions] = None
     recompute_inertia: bool = False
-    parse_glb_with_zup: bool = False
+    parse_glb_with_zup: Optional[bool] = None
+    file_meshes_are_zup: bool = True
     batch_fixed_verts: bool = False
 
     def __init__(self, **data):
@@ -569,6 +575,13 @@ def __init__(self, **data):
                 "'convexify' and 'decompose_(robot|object)_error_threshold' instead."
             )
 
+        if self.parse_glb_with_zup is not None:
+            self.file_meshes_are_zup = not self.parse_glb_with_zup
+            gs.logger.warning(
+                "FileMorph option 'parse_glb_with_zup' is deprecated and will be removed in future release. Please use "
+                "'file_meshes_are_zup'instead."
+            )
+
         # Make sure that this threshold is positive to avoid decomposition of convex and primitive shapes
         self.decompose_object_error_threshold = max(self.decompose_object_error_threshold, gs.EPS)
         self.decompose_robot_error_threshold = max(self.decompose_robot_error_threshold, gs.EPS)
@@ -668,7 +681,12 @@ class Mesh(FileMorph, TetGenMixin):
     parse_glb_with_trimesh : bool, optional
         Whether to use trimesh to load glb files. Defaults to False, in which case pygltflib will be used.
     parse_glb_with_zup : bool, optional
-        Whether to use zup to load glb files. Defaults to False.
+        This parameter is deprecated, see file_meshes_are_zup.
+    file_meshes_are_zup : bool, optional
+        Defines if the mesh files are expressed in a Z-up or Y-up coordinate system. If set to true, meshes are loaded
+        as Z-up and no transforms are applied to the input data. If set to false, all meshes undergo a conversion step
+        where the original coordinates are transformed as follows: (X, Y, Z) → (X, -Z, Y).
+        This conversion always applies to GLTF/GLB files, as they are defined as Y-up by the standard. Defaults to true.
     fixed : bool, optional
         Whether the object should be fixed. Defaults to False. **This is only used for RigidEntity.**
     batch_fixed_verts : bool, optional
@@ -799,7 +817,12 @@ class MJCF(FileMorph):
     coacd_options : CoacdOptions, optional
         Options for configuring coacd convex decomposition. Needs to be a `gs.options.CoacdOptions` object.
     parse_glb_with_zup : bool, optional
-        Whether to use zup to load glb files. Defaults to False.
+        This parameter is deprecated, see file_meshes_are_zup.
+    file_meshes_are_zup : bool, optional
+        Defines if the mesh files are expressed in a Z-up or Y-up coordinate system. If set to true, meshes are loaded
+        as Z-up and no transforms are applied to the input data. If set to false, all meshes undergo a conversion step
+        where the original coordinates are transformed as follows: (X, Y, Z) → (X, -Z, Y).
+        This conversion always applies to GLTF/GLB files, as they are defined as Y-up by the standard. Defaults to true.
     visualization : bool, optional
         Whether the entity needs to be visualized. Set it to False if you need a invisible object only for collision
         purposes. Defaults to True. `visualization` and `collision` cannot both be False.
@@ -905,7 +928,12 @@ class URDF(FileMorph):
     coacd_options : CoacdOptions, optional
         Options for configuring coacd convex decomposition. Needs to be a `gs.options.CoacdOptions` object.
     parse_glb_with_zup : bool, optional
-        Whether to use zup to load glb files. Defaults to False.
+        This parameter is deprecated, see file_meshes_are_zup.
+    file_meshes_are_zup : bool, optional
+        Defines if the mesh files are expressed in a Z-up or Y-up coordinate system. If set to true, meshes are loaded
+        as Z-up and no transforms are applied to the input data. If set to false, all meshes undergo a conversion step
+        where the original coordinates are transformed as follows: (X, Y, Z) → (X, -Z, Y).
+        This conversion always applies to GLTF/GLB files, as they are defined as Y-up by the standard. Defaults to true.
     visualization : bool, optional
         Whether the entity needs to be visualized. Set it to False if you need a invisible object only for collision
         purposes. Defaults to True. `visualization` and `collision` cannot both be False.
@@ -1003,7 +1031,12 @@ class Drone(FileMorph):
     coacd_options : CoacdOptions, optional
         Options for configuring coacd convex decomposition. Needs to be a `gs.options.CoacdOptions` object.
     parse_glb_with_zup : bool, optional
-        Whether to use zup to load glb files. Defaults to False.
+        This parameter is deprecated, see file_meshes_are_zup.
+    file_meshes_are_zup : bool, optional
+        Defines if the mesh files are expressed in a Z-up or Y-up coordinate system. If set to true, meshes are loaded
+        as Z-up and no transforms are applied to the input data. If set to false, all meshes undergo a conversion step
+        where the original coordinates are transformed as follows: (X, Y, Z) → (X, -Z, Y).
+        This conversion always applies to GLTF/GLB files, as they are defined as Y-up by the standard. Defaults to true.
     visualization : bool, optional
         Whether the entity needs to be visualized. Set it to False if you need a invisible object only for collision
         purposes. Defaults to True. `visualization` and `collision` cannot both be False.

genesis/utils/urdf.py

@@ -131,14 +131,14 @@ def parse_urdf(morph, surface):
                         metadata={"mesh_path": mesh_path},
                     )
 
+                    # If the file is a gltf, we have to convert it to zup
                     if mesh_path.lower().endswith(gs.morphs.GLTF_FORMATS):
-                        if morph.parse_glb_with_zup:
-                            mesh.convert_to_zup()
-                        else:
-                            gs.logger.warning(
-                                "This file contains GLTF mesh, which is using y-up while Genesis uses z-up. Please set "
-                                "'parse_glb_with_zup=True' in morph options if you find the mesh is 90-degree rotated. "
-                            )
+                        mesh.convert_to_zup()
+                        gs.logger.debug(f"Converting the GLTF geometry to zup '{morph.file}'")
+                    # If the file is a not a gltf, we convert to zup if the FileMorph.file_meshes_are_zup is true
+                    elif not morph.file_meshes_are_zup:
+                        mesh.convert_to_zup()
+                        gs.logger.debug(f"Converting the geometry of the '{morph.file}' file to zup.")
 
                     g_info = {"mesh" if geom_is_col else "vmesh": mesh}
                     link_g_infos_.append(g_info)

tests/test_mesh.py

@@ -1,6 +1,7 @@
 import os
 import platform
 import sys
+from contextlib import nullcontext
 
 import numpy as np
 import pytest
@@ -350,55 +351,111 @@ def test_usd_bake(usd_file, show_viewer):
         show_viewer=show_viewer,
         show_FPS=False,
     )
-    robot = scene.add_entity(
+    scene.add_entity(
         gs.morphs.Mesh(
             file=usd_file,
         ),
     )
 
 
 @pytest.mark.required
-def test_urdf_with_existing_glb(tmp_path, show_viewer):
-    glb_file = "usd/sneaker_airforce.glb"
-    asset_path = get_hf_dataset(pattern=glb_file)
-    glb_path = os.path.join(asset_path, glb_file)
-
+@pytest.mark.parametrize("mesh_file", ["yup_zup_coverage/cannon_z.glb", "yup_zup_coverage/cannon_y_-z.stl"])
+def test_urdf_yup(mesh_file, tmp_path):
+    asset_path = get_hf_dataset(pattern=mesh_file)
     urdf_path = tmp_path / "model.urdf"
     urdf_path.write_text(
         f"""<robot name="shoe">
               <link name="base">
                 <visual>
-                  <geometry><mesh filename="{glb_path}"/></geometry>
+                  <geometry><mesh filename="{os.path.join(asset_path, mesh_file)}"/></geometry>
                 </visual>
               </link>
             </robot>
          """
     )
 
-    scene = gs.Scene(
-        show_viewer=show_viewer,
-        show_FPS=False,
-    )
-    robot_urdf_yup = scene.add_entity(
+    scene = gs.Scene()
+    robot = scene.add_entity(
         gs.morphs.URDF(
             file=urdf_path,
+            file_meshes_are_zup=False,
         ),
     )
-    robot_urdf_zup = scene.add_entity(
-        gs.morphs.URDF(
-            file=urdf_path,
-            parse_glb_with_zup=True,
+    mesh = robot.vgeoms[0].vmesh
+
+    with pytest.raises(AssertionError) if mesh_file == "yup_zup_coverage/cannon_z.glb" else nullcontext():
+        assert_allclose(mesh.trimesh.center_mass, (-0.012, -0.142, 0.397), tol=0.002)
+
+
+@pytest.mark.required
+def test_obj_morphes_yup():
+    scene = gs.Scene()
+
+    asset_path = get_hf_dataset(pattern="yup_zup_coverage/*")
+
+    glb_y = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_y.glb",
+            convexify=False,
+            fixed=True,
+            file_meshes_are_zup=True,
         ),
     )
-    robot_mesh = scene.add_entity(
-        gs.morphs.Mesh(
-            file=glb_path,
-            parse_glb_with_zup=True,
+    glb_mesh_y = glb_y.vgeoms[0].vmesh
+    glb_z = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_z.glb",
+            convexify=False,
+            fixed=True,
+            file_meshes_are_zup=True,
+        ),
+    )
+    glb_mesh_z = glb_z.vgeoms[0].vmesh
+    stl_y = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_y_-z.stl",
+            convexify=False,
+            fixed=True,
+            file_meshes_are_zup=False,
+        ),
+    )
+    stl_mesh_y = stl_y.vgeoms[0].vmesh
+    stl_z = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_z_y.stl",
+            convexify=False,
+            fixed=True,
         ),
     )
-    check_gs_meshes(robot_urdf_zup.vgeoms[0].vmesh, robot_mesh.vgeoms[0].vmesh, "robot")
-    robot_urdf_yup.vgeoms[0].vmesh.convert_to_zup()
-    check_gs_meshes(robot_urdf_yup.vgeoms[0].vmesh, robot_mesh.vgeoms[0].vmesh, "robot")
+    stl_mesh_z = stl_z.vgeoms[0].vmesh
+    obj_y = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_y_-z.obj",
+            convexify=False,
+            fixed=True,
+            file_meshes_are_zup=False,
+        ),
+    )
+    obj_mesh_y = obj_y.vgeoms[0].vmesh
+    obj_z = scene.add_entity(
+        morph=gs.morphs.Mesh(
+            file=f"{asset_path}/yup_zup_coverage/cannon_z_y.obj",
+            convexify=False,
+            fixed=True,
+        ),
+    )
+    obj_mesh_z = obj_z.vgeoms[0].vmesh
+
+    assert not glb_mesh_y.metadata["imported_as_zup"]
+    assert not glb_mesh_z.metadata["imported_as_zup"]
+    assert not stl_mesh_y.metadata["imported_as_zup"]
+    assert stl_mesh_z.metadata["imported_as_zup"]
+    assert not obj_mesh_y.metadata["imported_as_zup"]
+    assert obj_mesh_z.metadata["imported_as_zup"]
+
+    for mesh in (glb_mesh_y, glb_mesh_z, stl_mesh_y, stl_mesh_z, obj_mesh_y, obj_mesh_z):
+        with pytest.raises(AssertionError) if mesh is glb_mesh_z else nullcontext():
+            assert_allclose(mesh.trimesh.center_mass, (-0.012, -0.142, 0.397), tol=0.002)
 
 
 @pytest.mark.required

tests/utils.py

@@ -35,7 +35,7 @@
 REPOSITY_URL = "Genesis-Embodied-AI/Genesis"
 DEFAULT_BRANCH_NAME = "main"
 
-HUGGINGFACE_ASSETS_REVISION = "701f78c1465f0a98f6540bae6c9daacaa551b7bf"
+HUGGINGFACE_ASSETS_REVISION = "c50bfe3e354e105b221ef4eb9a79504650709dd2"
 HUGGINGFACE_SNAPSHOT_REVISION = "17d79e7627479ef836524d14449e2fdc4282973d"
 
 MESH_EXTENSIONS = (".mtl", *MESH_FORMATS, *GLTF_FORMATS, *USD_FORMATS)