Snap to view (#23674)

# Objective

- Adds ``SnapToView`` camera controller as solution to #23499 

## Solution

- Adds ``snap_to_view`` module behind ``free_camera`` feature flag 
## Testing

- Manually tested with ``cargo run --example free_camera_controller
--features="free_camera bevy_dev_tools"`` and ``cargo run --example
scene_viewer --features="free_camera bevy_dev_tools"``:
  - All six hotkeys works.
    - [LCtrl +] Numpad1  - Snap to front/back
    - [LCtrl +] Numpad3  - Snap to right/left
    - [LCtrl +] Numpad7  - Snap to top/bottom
- Tested on Linux (Wayland)
---

## Showcase


https://github.com/user-attachments/assets/cca71180-c273-473f-a168-9793438d861f

Add ``SnapToViewCamera`` component to any ``Camera3d`` entity. 
Change parameters inside ``SnapToViewCamera`` to change snap speed and
hotkeys.

```rust
app.add_plugins(SnapToViewPlugin);

commands.spawn((
    Camera3d::default(),
    SnapToViewCamera::default(),
));
```

---------

Co-authored-by: taishi-sama <alexandra.2002.mikh@gmail.com>

Author: taishi-sama

_release-content/release-notes/snap_to_axes.md

@@ -0,0 +1,18 @@
+---
+title: Snap to axes
+authors: ["@taishi-sama"]
+pull_requests: [23674]
+---
+
+``FreeCamera`` now able to align itself to axes on hotkey presses.
+
+| Default Key Binding | Action                 |
+|:--------------------|:-----------------------|
+| `Numpad1`           | Snap to front(-Z)      |
+| `LCtrl` + `Numpad1` | Snap to back(+Z)       |
+| `Numpad3`           | Snap to right(+X)      |
+| `LCtrl` + `Numpad3` | Snap to left(-X)       |
+| `Numpad7`           | Snap to top(+Y)        |
+| `LCtrl` + `Numpad7` | Snap to bottom(-Y)     |
+
+These hotkeys can be changed by modifying ``FreeCamera`` component.

crates/bevy_camera_controller/src/free_camera.rs

@@ -13,6 +13,7 @@
 //! The required [`FreeCameraState`] component will be added automatically.
 //!
 //! To configure the settings of this controller, modify the fields of the [`FreeCamera`] component.
+// TODO: Discuss switching camera to orthographic mode.
 
 use bevy_app::{App, Plugin, RunFixedMainLoop, RunFixedMainLoopSystems};
 use bevy_camera::Camera;
@@ -24,7 +25,9 @@ use bevy_input::mouse::{
 use bevy_input::touch::Touches;
 use bevy_input::ButtonInput;
 use bevy_log::info;
-use bevy_math::{ops::exp, EulerRot, Quat, StableInterpolate, Vec2, Vec3};
+use bevy_math::curve::{Interval, SampleAutoCurve};
+use bevy_math::Curve;
+use bevy_math::{ops::exp, Dir3, EulerRot, Quat, StableInterpolate, Vec2, Vec3};
 use bevy_time::{Real, Time};
 use bevy_transform::prelude::Transform;
 use bevy_window::{CursorGrabMode, CursorOptions, Window};
@@ -42,7 +45,9 @@ impl Plugin for FreeCameraPlugin {
         // This ordering is required so that both fixed update and update systems can see the results correctly
         app.add_systems(
             RunFixedMainLoop,
-            run_freecamera_controller.in_set(RunFixedMainLoopSystems::BeforeFixedMainLoop),
+            (run_freecamera_controller, rotate_freecam_to)
+                .chain()
+                .in_set(RunFixedMainLoopSystems::BeforeFixedMainLoop),
         );
     }
 }
@@ -91,6 +96,14 @@ pub struct FreeCamera {
     pub mouse_key_cursor_grab: MouseButton,
     /// [`KeyCode`] for grabbing the keyboard focus.
     pub keyboard_key_toggle_cursor_grab: KeyCode,
+    /// Modifier [`KeyCode`] for making pressed axis alignment buttons go in opposite direction
+    pub key_snap_reverse: KeyCode,
+    /// [`KeyCode`] for snapping camera to top/bottom (+Y/-Y).
+    pub axis_top: KeyCode,
+    /// [`KeyCode`] for snapping camera to right/left (+X/-X).
+    pub axis_right: KeyCode,
+    /// [`KeyCode`] for snapping camera to front/back (-Z/+Z).
+    pub axis_front: KeyCode,
     /// Base multiplier for unmodified translation speed.
     pub walk_speed: f32,
     /// Base multiplier for running translation speed.
@@ -117,6 +130,8 @@ pub struct FreeCamera {
     pub scroll_factor: f32,
     /// Friction factor used to exponentially decay [`velocity`](FreeCameraState::velocity) over time.
     pub friction: f32,
+    /// Speed of camera rotation to snapped axis in radians/second
+    pub rotation_speed: f32,
 }
 
 impl Default for FreeCamera {
@@ -132,11 +147,16 @@ impl Default for FreeCamera {
             key_run: KeyCode::ShiftLeft,
             mouse_key_cursor_grab: MouseButton::Right,
             keyboard_key_toggle_cursor_grab: KeyCode::KeyM,
+            key_snap_reverse: KeyCode::ControlLeft,
+            axis_top: KeyCode::Numpad7,
+            axis_right: KeyCode::Numpad3,
+            axis_front: KeyCode::Numpad1,
             walk_speed: 5.0,
             run_speed: 15.0,
             // Approximation of ln(1.05)
             scroll_factor: 0.04879016,
             friction: 40.0,
+            rotation_speed: PI / 16.0 * 60.0,
         }
     }
 }
@@ -154,7 +174,10 @@ Freecamera Controls:
     {:?} & {:?}\t- Fly forward & backwards
     {:?} & {:?}\t- Fly sideways left & right
     {:?} & {:?}\t- Fly up & down
-    {:?}\t- Fly faster while held",
+    {:?}\t- Fly faster while held
+    [{:?} + ]{:?}\t- Snap to Up (+Y)/Down (-Y)
+    [{:?} + ]{:?}\t- Snap to Right (+X)/Left (-X)
+    [{:?} + ]{:?}\t- Snap to Front (-Z)/Back (+Z)",
             self.mouse_key_cursor_grab,
             self.keyboard_key_toggle_cursor_grab,
             self.key_forward,
@@ -164,6 +187,12 @@ Freecamera Controls:
             self.key_up,
             self.key_down,
             self.key_run,
+            self.key_snap_reverse,
+            self.axis_top,
+            self.key_snap_reverse,
+            self.axis_right,
+            self.key_snap_reverse,
+            self.axis_front,
         )
     }
 }
@@ -189,6 +218,9 @@ pub struct FreeCameraState {
     pub speed_multiplier: f32,
     /// This [`FreeCamera`]'s translation velocity.
     pub velocity: Vec3,
+    /// Dictates camera movement during camera snap at speed, specified in [`FreeCamera`] by [`FreeCamera::rotation_speed`] field.
+    /// Consist of counter of seconds from pressing curve snap hotkeys and curve that used to interpolate between old and new rotation
+    pub rotation_curve: Option<(f32, SampleAutoCurve<Quat>)>,
 }
 
 impl Default for FreeCameraState {
@@ -200,6 +232,7 @@ impl Default for FreeCameraState {
             yaw: 0.0,
             speed_multiplier: 1.0,
             velocity: Vec3::ZERO,
+            rotation_curve: None,
         }
     }
 }
@@ -210,6 +243,8 @@ impl Default for FreeCameraState {
 /// - [`FreeCameraState`] stores the dynamic runtime state, including pitch, yaw, velocity, and enable flags.
 ///
 /// This system is typically added via the [`FreeCameraPlugin`].
+///
+/// Axis snapping takes priority over mouse movement.
 pub fn run_freecamera_controller(
     time: Res<Time<Real>>,
     mut windows: Query<(&Window, &mut CursorOptions)>,
@@ -361,4 +396,69 @@ pub fn run_freecamera_controller(
             transform.rotation = Quat::from_euler(EulerRot::ZYX, 0.0, state.yaw, state.pitch);
         }
     }
+    // Axis snapping
+    let mod_key_pressed = key_input.pressed(config.key_snap_reverse);
+    let mut rotate_to = None;
+    if key_input.just_pressed(config.axis_front) {
+        if mod_key_pressed {
+            rotate_to = Some((Dir3::Z, Dir3::Y));
+        } else {
+            rotate_to = Some((Dir3::NEG_Z, Dir3::Y));
+        }
+    }
+    if key_input.just_pressed(config.axis_right) {
+        if mod_key_pressed {
+            rotate_to = Some((Dir3::NEG_X, Dir3::Y));
+        } else {
+            rotate_to = Some((Dir3::X, Dir3::Y));
+        }
+    }
+    if key_input.just_pressed(config.axis_top) {
+        if mod_key_pressed {
+            rotate_to = Some((Dir3::NEG_Y, Dir3::NEG_Z));
+        } else {
+            rotate_to = Some((Dir3::Y, Dir3::Z));
+        }
+    }
+    if let Some((dir, up)) = rotate_to {
+        let start = transform.rotation;
+        let target = Transform::default().looking_to(dir, up).rotation; // I don't understand why Quat::look_to_rh produce different result.
+        let angle = target.angle_between(start);
+        let rotation_time = angle / config.rotation_speed;
+
+        if let Ok(interval) = Interval::new(0.0, rotation_time) {
+            let curve = SampleAutoCurve::new(interval, [start, target])
+                .expect("Interval should be in bounds as start and end are finite numbers");
+            state.rotation_curve = Some((0.0, curve));
+        }
+    }
+}
+
+/// Smoothly changes orientation([`Transform`]) of [`FreeCamera`] camera according to target orientation in [`FreeCameraState`].
+///
+/// - [`FreeCamera`] contains static configuration such as key bindings and rotation speed.
+/// - [`FreeCameraState`] stores the dynamic runtime state, including direction for camera rotation and enable flags.
+///
+/// This system is typically added via the [`FreeCameraPlugin`].
+pub fn rotate_freecam_to(
+    mut query: Query<(&mut Transform, &mut FreeCameraState), With<Camera>>,
+    time: Res<Time<Real>>,
+) {
+    let Ok((mut transform, mut state)) = query.single_mut() else {
+        return;
+    };
+    if !state.enabled {
+        return;
+    }
+    let Some((progress, curve)) = state.rotation_curve.as_mut() else {
+        return;
+    };
+    *progress += time.delta_secs();
+    transform.rotation = curve.sample_clamped(*progress);
+    if !curve.domain().contains(*progress) {
+        state.rotation_curve = None;
+    }
+    let (yaw, pitch, _roll) = transform.rotation.to_euler(EulerRot::YXZ);
+    state.pitch = pitch;
+    state.yaw = yaw;
 }

examples/camera/free_camera_controller.rs

@@ -20,6 +20,12 @@
 //! | QE                  | Vertical movement      |
 //! | Left shift          | Run                    |
 //! | Scroll wheel        | Change movement speed  |
+//! | Numpad1             | Snap to front          |
+//! | `LCtrl` + Numpad1   | Snap to back           |
+//! | Numpad3             | Snap to right          |
+//! | `LCtrl` + Numpad3   | Snap to left           |
+//! | Numpad7             | Snap to top            |
+//! | `LCtrl` + Numpad7   | Snap to bottom         |
 //!
 //! The movement speed, sensitivity and friction can also be changed by the [`FreeCamera`] component.
 //!
@@ -103,7 +109,7 @@ fn spawn_text(mut commands: Commands, free_camera_query: Query<&FreeCamera>) {
         },
         children![Text::new(format!(
             "{}",
-            free_camera_query.single().unwrap()
+            free_camera_query.single().unwrap(),
         ))],
     ));
     commands.spawn((

examples/tools/scene_viewer/main.rs

@@ -195,7 +195,6 @@ fn setup_scene_after_load(
             run_speed: 3.0 * walk_speed,
             ..default()
         };
-
         // Display the controls of the scene viewer
         info!("{}", camera_controller);
         info!("{}", *scene_handle);