Alternative glTF coordinate conversion

crates/bevy_gltf/src/convert_coordinates.rs

@@ -1,34 +1,16 @@
-use core::f32::consts::PI;
+//! Utilities for converting from glTF's [standard coordinate system](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units)
+//! to Bevy's.
+use serde::{Deserialize, Serialize};
 
 use bevy_math::{Mat4, Quat, Vec3};
 use bevy_transform::components::Transform;
 
 pub(crate) trait ConvertCoordinates {
-    /// Converts the glTF coordinates to Bevy's coordinate system.
-    /// - glTF:
-    ///   - forward: Z
-    ///   - up: Y
-    ///   - right: -X
-    /// - Bevy:
-    ///   - forward: -Z
-    ///   - up: Y
-    ///   - right: X
-    ///
-    /// See <https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units>
+    /// Converts from glTF coordinates to Bevy's coordinate system. See
+    /// [`GltfConvertCoordinates`] for an explanation of the conversion.
     fn convert_coordinates(self) -> Self;
 }
 
-pub(crate) trait ConvertCameraCoordinates {
-    /// Like `convert_coordinates`, but uses the following for the lens rotation:
-    /// - forward: -Z
-    /// - up: Y
-    /// - right: X
-    ///
-    /// The same convention is used for lights.
-    /// See <https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#view-matrix>
-    fn convert_camera_coordinates(self) -> Self;
-}
-
 impl ConvertCoordinates for Vec3 {
     fn convert_coordinates(self) -> Self {
         Vec3::new(-self.x, self.y, -self.z)
@@ -48,34 +30,87 @@ impl ConvertCoordinates for [f32; 4] {
     }
 }
 
-impl ConvertCoordinates for Quat {
-    fn convert_coordinates(self) -> Self {
-        // Solution of q' = r q r*
-        Quat::from_array([-self.x, self.y, -self.z, self.w])
-    }
+/// Options for converting scenes and assets from glTF's [standard coordinate system](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units)
+/// (+Z forward) to Bevy's coordinate system (-Z forward).
+///
+/// The exact coordinate system conversion is as follows:
+/// - glTF:
+///   - forward: +Z
+///   - up: +Y
+///   - right: -X
+/// - Bevy:
+///   - forward: -Z
+///   - up: +Y
+///   - right: +X
+///
+/// Note that some glTF files may not follow the glTF standard.
+///
+/// If your glTF scene is +Z forward and you want it converted to match Bevy's
+/// `Transform::forward`, enable the `rotate_scene_entity` option. If you also want `Mesh`
+/// assets to be converted, enable the `rotate_meshes` option.
+///
+/// Cameras and lights in glTF files are an exception - they already use Bevy's
+/// coordinate system. This means cameras and lights will match
+/// `Transform::forward` even if conversion is disabled.
+#[derive(Copy, Clone, Default, Debug, Serialize, Deserialize)]
+pub struct GltfConvertCoordinates {
+    /// If true, convert scenes by rotating the top-level transform of the scene entity.
+    ///
+    /// This will ensure that [`Transform::forward`] of the "root" entity (the one with [`SceneInstance`](bevy_scene::SceneInstance))
+    /// aligns with the "forward" of the glTF scene.
+    ///
+    /// The glTF loader creates an entity for each glTF scene. Entities are
+    /// then created for each node within the glTF scene. Nodes without a
+    /// parent in the glTF scene become children of the scene entity.
+    ///
+    /// This option only changes the transform of the scene entity. It does not
+    /// directly change the transforms of node entities - it only changes them
+    /// indirectly through transform inheritance.
+    pub rotate_scene_entity: bool,
+
+    /// If true, convert mesh assets. This includes skinned mesh bind poses.
+    ///
+    /// This option only changes mesh assets and the transforms of entities that
+    /// instance meshes. It does not change the transforms of entities that
+    /// correspond to glTF nodes.
+    pub rotate_meshes: bool,
 }
 
-impl ConvertCoordinates for Mat4 {
-    fn convert_coordinates(self) -> Self {
-        let m: Mat4 = Mat4::from_scale(Vec3::new(-1.0, 1.0, -1.0));
-        // Same as the original matrix
-        let m_inv = m;
-        m_inv * self * m
+impl GltfConvertCoordinates {
+    const CONVERSION_TRANSFORM: Transform =
+        Transform::from_rotation(Quat::from_xyzw(0.0, 1.0, 0.0, 0.0));
+
+    fn conversion_mat4() -> Mat4 {
+        Mat4::from_scale(Vec3::new(-1.0, 1.0, -1.0))
     }
-}
 
-impl ConvertCoordinates for Transform {
-    fn convert_coordinates(mut self) -> Self {
-        self.translation = self.translation.convert_coordinates();
-        self.rotation = self.rotation.convert_coordinates();
-        self
+    pub(crate) fn scene_conversion_transform(&self) -> Transform {
+        if self.rotate_scene_entity {
+            Self::CONVERSION_TRANSFORM
+        } else {
+            Transform::IDENTITY
+        }
+    }
+
+    pub(crate) fn mesh_conversion_transform(&self) -> Transform {
+        if self.rotate_meshes {
+            Self::CONVERSION_TRANSFORM
+        } else {
+            Transform::IDENTITY
+        }
+    }
+
+    pub(crate) fn mesh_conversion_transform_inverse(&self) -> Transform {
+        // We magically know that the transform is its own inverse. We still
+        // make a distinction at the interface level in case that changes.
+        self.mesh_conversion_transform()
     }
-}
 
-impl ConvertCameraCoordinates for Transform {
-    fn convert_camera_coordinates(mut self) -> Self {
-        self.translation = self.translation.convert_coordinates();
-        self.rotate_y(PI);
-        self
+    pub(crate) fn mesh_conversion_mat4(&self) -> Mat4 {
+        if self.rotate_meshes {
+            Self::conversion_mat4()
+        } else {
+            Mat4::IDENTITY
+        }
     }
 }

crates/bevy_gltf/src/lib.rs

@@ -128,7 +128,7 @@
 //! See the [glTF Extension Registry](https://github.com/KhronosGroup/glTF/blob/main/extensions/README.md) for more information on extensions.
 
 mod assets;
-mod convert_coordinates;
+pub mod convert_coordinates;
 mod label;
 mod loader;
 mod vertex_attributes;
@@ -155,7 +155,7 @@ pub mod prelude {
     pub use crate::{assets::Gltf, assets::GltfExtras, label::GltfAssetLabel};
 }
 
-use crate::extensions::GltfExtensionHandlers;
+use crate::{convert_coordinates::GltfConvertCoordinates, extensions::GltfExtensionHandlers};
 
 pub use {assets::*, label::GltfAssetLabel, loader::*};
 
@@ -198,19 +198,9 @@ pub struct GltfPlugin {
     /// Can be modified with the [`DefaultGltfImageSampler`] resource.
     pub default_sampler: ImageSamplerDescriptor,
 
-    /// _CAUTION: This is an experimental feature with [known issues](https://github.com/bevyengine/bevy/issues/20621). Behavior may change in future versions._
-    ///
-    /// How to convert glTF coordinates on import. Assuming glTF cameras, glTF lights, and glTF meshes had global identity transforms,
-    /// their Bevy [`Transform::forward`](bevy_transform::components::Transform::forward) will be pointing in the following global directions:
-    /// - When set to `false`
-    ///   - glTF cameras and glTF lights: global -Z,
-    ///   - glTF models: global +Z.
-    /// - When set to `true`
-    ///   - glTF cameras and glTF lights: global +Z,
-    ///   - glTF models: global -Z.
-    ///
-    /// The default is `false`.
-    pub use_model_forward_direction: bool,
+    /// The default glTF coordinate conversion setting. This can be overridden
+    /// per-load by [`GltfLoaderSettings::convert_coordinates`].
+    pub convert_coordinates: GltfConvertCoordinates,
 
     /// Registry for custom vertex attributes.
     ///
@@ -223,7 +213,7 @@ impl Default for GltfPlugin {
         GltfPlugin {
             default_sampler: ImageSamplerDescriptor::linear(),
             custom_vertex_attributes: HashMap::default(),
-            use_model_forward_direction: false,
+            convert_coordinates: GltfConvertCoordinates::default(),
         }
     }
 }
@@ -276,7 +266,7 @@ impl Plugin for GltfPlugin {
             supported_compressed_formats,
             custom_vertex_attributes: self.custom_vertex_attributes.clone(),
             default_sampler,
-            default_use_model_forward_direction: self.use_model_forward_direction,
+            default_convert_coordinates: self.convert_coordinates,
             extensions: extensions.0.clone(),
         });
     }

crates/bevy_gltf/src/loader/gltf_ext/scene.rs

@@ -10,10 +10,7 @@ use itertools::Itertools;
 #[cfg(feature = "bevy_animation")]
 use bevy_platform::collections::{HashMap, HashSet};
 
-use crate::{
-    convert_coordinates::{ConvertCameraCoordinates as _, ConvertCoordinates as _},
-    GltfError,
-};
+use crate::GltfError;
 
 pub(crate) fn node_name(node: &Node) -> Name {
     let name = node
@@ -29,8 +26,8 @@ pub(crate) fn node_name(node: &Node) -> Name {
 /// on [`Node::transform()`](gltf::Node::transform) directly because it uses optimized glam types and
 /// if `libm` feature of `bevy_math` crate is enabled also handles cross
 /// platform determinism properly.
-pub(crate) fn node_transform(node: &Node, convert_coordinates: bool) -> Transform {
-    let transform = match node.transform() {
+pub(crate) fn node_transform(node: &Node) -> Transform {
+    match node.transform() {
         gltf::scene::Transform::Matrix { matrix } => {
             Transform::from_matrix(Mat4::from_cols_array_2d(&matrix))
         }
@@ -43,15 +40,6 @@ pub(crate) fn node_transform(node: &Node, convert_coordinates: bool) -> Transfor
             rotation: bevy_math::Quat::from_array(rotation),
             scale: Vec3::from(scale),
         },
-    };
-    if convert_coordinates {
-        if node.camera().is_some() || node.light().is_some() {
-            transform.convert_camera_coordinates()
-        } else {
-            transform.convert_coordinates()
-        }
-    } else {
-        transform
     }
 }