WIP: Fix glTF model forward direction

Author: superdump

Cargo.toml

@@ -3278,6 +3278,17 @@ description = "A demonstration of Transform's axis-alignment feature"
 category = "Transforms"
 wasm = true
 
+[[example]]
+name = "model_forward"
+path = "examples/transforms/model_forward.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.model_forward]
+name = "model_forward"
+description = "Illustrates when to use camera_forward vs model_forward, and different cases for model_forward"
+category = "Transforms"
+wasm = true
+
 [[example]]
 name = "scale"
 path = "examples/transforms/scale.rs"

crates/bevy_animation/src/animatable.rs

@@ -136,15 +136,20 @@ impl Animatable for Transform {
             translation: Vec3::interpolate(&a.translation, &b.translation, t),
             rotation: Quat::interpolate(&a.rotation, &b.rotation, t),
             scale: Vec3::interpolate(&a.scale, &b.scale, t),
+            flip_model_forward: a.flip_model_forward,
         }
     }
 
     fn blend(inputs: impl Iterator<Item = BlendInput<Self>>) -> Self {
         let mut translation = Vec3A::ZERO;
         let mut scale = Vec3A::ZERO;
         let mut rotation = Quat::IDENTITY;
+        let mut flip_model_forward = None;
 
         for input in inputs {
+            if flip_model_forward.is_none() {
+                flip_model_forward = Some(input.value.flip_model_forward);
+            }
             if input.additive {
                 translation += input.weight * Vec3A::from(input.value.translation);
                 scale += input.weight * Vec3A::from(input.value.scale);
@@ -165,6 +170,7 @@ impl Animatable for Transform {
             translation: Vec3::from(translation),
             rotation,
             scale: Vec3::from(scale),
+            flip_model_forward: flip_model_forward.unwrap_or_default(),
         }
     }
 }

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

@@ -42,6 +42,7 @@ pub(crate) fn node_transform(node: &Node, convert_coordinates: bool) -> Transfor
             translation: Vec3::from(translation),
             rotation: bevy_math::Quat::from_array(rotation),
             scale: Vec3::from(scale),
+            flip_model_forward: true,
         },
     };
     if convert_coordinates {

crates/bevy_transform/src/components/global_transform.rs

@@ -136,6 +136,7 @@ impl GlobalTransform {
             translation,
             rotation,
             scale,
+            ..Default::default()
         }
     }
 
@@ -193,6 +194,7 @@ impl GlobalTransform {
             translation,
             rotation,
             scale,
+            ..Default::default()
         }
     }
 
@@ -367,11 +369,13 @@ mod test {
             translation: Vec3::new(1034.0, 34.0, -1324.34),
             rotation: Quat::from_euler(XYZ, 1.0, 0.9, 2.1),
             scale: Vec3::new(1.0, 1.0, 1.0),
+            ..Default::default()
         });
         let t2 = GlobalTransform::from(Transform {
             translation: Vec3::new(0.0, -54.493, 324.34),
             rotation: Quat::from_euler(XYZ, 1.9, 0.3, 3.0),
             scale: Vec3::new(1.345, 1.345, 1.345),
+            ..Default::default()
         });
         let retransformed = reparent_to_same(t1, t2);
         assert!(
@@ -387,11 +391,13 @@ mod test {
             translation: Vec3::new(1034.0, 34.0, -1324.34),
             rotation: Quat::from_euler(XYZ, 0.8, 1.9, 2.1),
             scale: Vec3::new(10.9, 10.9, 10.9),
+            ..Default::default()
         });
         let t2 = GlobalTransform::from(Transform {
             translation: Vec3::new(28.0, -54.493, 324.34),
             rotation: Quat::from_euler(XYZ, 0.0, 3.1, 0.1),
             scale: Vec3::new(0.9, 0.9, 0.9),
+            ..Default::default()
         });
         // goal: find `X` such as `t2 * X = t1`
         let reparented = t1.reparented_to(&t2);

crates/bevy_transform/src/components/transform.rs

@@ -98,6 +98,11 @@ pub struct Transform {
     ///
     /// [`scale`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/scale.rs
     pub scale: Vec3,
+    /// Whether the model forward direction is flipped from -z to +z.
+    ///
+    /// glTF specifies that models have a forward direction of +z whereas cameras and lights have -z.
+    /// This option allows the glTF importer and other usages to make appropriate adjustments.
+    pub flip_model_forward: bool,
 }
 
 impl Transform {
@@ -106,6 +111,7 @@ impl Transform {
         translation: Vec3::ZERO,
         rotation: Quat::IDENTITY,
         scale: Vec3::ONE,
+        flip_model_forward: false,
     };
 
     /// Creates a new [`Transform`] at the position `(x, y, z)`. In 2d, the `z` component
@@ -126,6 +132,7 @@ impl Transform {
             translation,
             rotation,
             scale,
+            flip_model_forward: false,
         }
     }
 
@@ -317,16 +324,44 @@ impl Transform {
 
     /// Equivalent to [`-local_z()`][Transform::local_z]
     #[inline]
-    pub fn forward(&self) -> Dir3 {
+    pub fn camera_forward(&self) -> Dir3 {
         -self.local_z()
     }
 
     /// Equivalent to [`local_z()`][Transform::local_z]
     #[inline]
-    pub fn back(&self) -> Dir3 {
+    pub fn camera_back(&self) -> Dir3 {
         self.local_z()
     }
 
+    /// Equivalent to [`-local_z()`][Transform::local_z] if `flip_model_forward` is false,
+    /// else [`local_z()`][Transform::local_z]
+    ///
+    /// glTF has opposing forward directions for cameras and lights, and for models. Model
+    /// forward is +z, whereas camera and light forward is -z.
+    #[inline]
+    pub fn model_forward(&self) -> Dir3 {
+        if self.flip_model_forward {
+            self.local_z()
+        } else {
+            -self.local_z()
+        }
+    }
+
+    /// Equivalent to [`local_z()`][Transform::local_z] if `flip_model_forward` is false,
+    /// else [`-local_z()`][Transform::local_z]
+    ///
+    /// glTF has opposing forward directions for cameras and lights, and for models. Model
+    /// forward is +z, whereas camera and light forward is -z. Back is the opposite of this.
+    #[inline]
+    pub fn model_back(&self) -> Dir3 {
+        if self.flip_model_forward {
+            -self.local_z()
+        } else {
+            self.local_z()
+        }
+    }
+
     /// Rotates this [`Transform`] by the given rotation.
     ///
     /// If this [`Transform`] has a parent, the `rotation` is relative to the rotation of the parent.
@@ -469,7 +504,11 @@ impl Transform {
     /// * if `direction` is parallel with `up`, an orthogonal vector is used as the "right" direction
     #[inline]
     pub fn look_to(&mut self, direction: impl TryInto<Dir3>, up: impl TryInto<Dir3>) {
-        let back = -direction.try_into().unwrap_or(Dir3::NEG_Z);
+        let back = if self.flip_model_forward {
+            direction.try_into().unwrap_or(Dir3::NEG_Z)
+        } else {
+            -direction.try_into().unwrap_or(Dir3::NEG_Z)
+        };
         let up = up.try_into().unwrap_or(Dir3::Y);
         let right = up
             .cross(back.into())
@@ -572,6 +611,7 @@ impl Transform {
             translation,
             rotation,
             scale,
+            flip_model_forward: self.flip_model_forward,
         }
     }
 

examples/3d/motion_blur.rs

@@ -343,8 +343,8 @@ fn move_camera(
         }
         CameraMode::Chase => {
             transform.translation =
-                tracked.translation + Vec3::new(0.0, 0.15, 0.0) + tracked.back() * 0.6;
-            transform.look_to(tracked.forward(), Vec3::Y);
+                tracked.translation + Vec3::new(0.0, 0.15, 0.0) + tracked.camera_back() * 0.6;
+            transform.look_to(tracked.camera_forward(), Vec3::Y);
             if let Projection::Perspective(perspective) = &mut *projection {
                 perspective.fov = 1.0;
             }

examples/3d/parallax_mapping.rs

@@ -166,21 +166,25 @@ const CAMERA_POSITIONS: &[Transform] = &[
         translation: Vec3::new(1.5, 1.5, 1.5),
         rotation: Quat::from_xyzw(-0.279, 0.364, 0.115, 0.880),
         scale: Vec3::ONE,
+        flip_model_forward: false,
     },
     Transform {
         translation: Vec3::new(2.4, 0.0, 0.2),
         rotation: Quat::from_xyzw(0.094, 0.676, 0.116, 0.721),
         scale: Vec3::ONE,
+        flip_model_forward: false,
     },
     Transform {
         translation: Vec3::new(2.4, 2.6, -4.3),
         rotation: Quat::from_xyzw(0.170, 0.908, 0.308, 0.225),
         scale: Vec3::ONE,
+        flip_model_forward: false,
     },
     Transform {
         translation: Vec3::new(-1.0, 0.8, -1.2),
         rotation: Quat::from_xyzw(-0.004, 0.909, 0.247, -0.335),
         scale: Vec3::ONE,
+        flip_model_forward: false,
     },
 ];
 

examples/3d/tonemapping.rs

@@ -139,7 +139,7 @@ fn setup_color_gradient_scene(
     camera_transform: Res<CameraTransform>,
 ) {
     let mut transform = camera_transform.0;
-    transform.translation += *transform.forward();
+    transform.translation += *transform.camera_forward();
 
     commands.spawn((
         Mesh3d(meshes.add(Rectangle::new(0.7, 0.7))),
@@ -157,7 +157,7 @@ fn setup_image_viewer_scene(
     camera_transform: Res<CameraTransform>,
 ) {
     let mut transform = camera_transform.0;
-    transform.translation += *transform.forward();
+    transform.translation += *transform.camera_forward();
 
     // exr/hdr viewer (exr requires enabling bevy feature)
     commands.spawn((

examples/camera/camera_orbit.rs

@@ -137,5 +137,5 @@ fn orbit(
     // Adjust the translation to maintain the correct orientation toward the orbit target.
     // In our example it's a static target, but this could easily be customized.
     let target = Vec3::ZERO;
-    camera.translation = target - camera.forward() * camera_settings.orbit_distance;
+    camera.translation = target - camera.camera_forward() * camera_settings.orbit_distance;
 }

examples/gizmos/axes.rs

@@ -143,6 +143,7 @@ fn random_transform(rng: &mut impl Rng) -> Transform {
         translation: random_translation(rng),
         rotation: random_rotation(rng),
         scale: random_scale(rng),
+        ..default()
     }
 }
 
@@ -216,5 +217,6 @@ fn interpolate_transforms(t1: Transform, t2: Transform, t: f32) -> Transform {
         translation,
         rotation,
         scale,
+        flip_model_forward: t1.flip_model_forward,
     }
 }