Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Navigation: snap free orbit direction and roll with Shift (#6943) (#6949)

Victor Santos Oliveira6e12f5954fd3
diff --git a/assets/locales/pending/free-orbit-shift-snap.json b/assets/locales/pending/free-orbit-shift-snap.json
new file mode 100644
index 0000000000..8390ea149c
--- /dev/null
+++ b/assets/locales/pending/free-orbit-shift-snap.json
@@ -0,0 +1,20 @@
+{
+ "en": {
+ "nav.free_orbit.snap_help": "Mouse and 3D mouse rotate through both poles and preserve roll. Hold Shift during an orbit drag to snap the view direction and roll."
+ },
+ "de": {
+ "nav.free_orbit.snap_help": "Maus und 3D-Maus drehen über beide Pole hinweg und behalten die Rollausrichtung bei. Halten Sie beim Ziehen zum Drehen die Umschalttaste gedrückt, um Blickrichtung und Rollausrichtung einrasten zu lassen."
+ },
+ "pt-BR": {
+ "nav.free_orbit.snap_help": "Mouse e mouse 3D giram através dos dois polos e preservam a rotação da imagem. Mantenha Shift pressionado durante uma órbita por arraste para alinhar a direção da vista e a rotação da imagem."
+ },
+ "ja": {
+ "nav.free_orbit.snap_help": "マウスと3Dマウスで両極を越えて回転でき、ロールも保持されます。オービットのドラッグ中にShiftを押すと、視線方向とロールがスナップします。"
+ },
+ "ko": {
+ "nav.free_orbit.snap_help": "마우스와 3D 마우스로 양쪽 극점을 지나 회전할 수 있으며 롤 각도가 유지됩니다. 궤도 회전 드래그 중 Shift를 누르면 보기 방향과 롤 각도가 스냅됩니다."
+ },
+ "zh": {
+ "nav.free_orbit.snap_help": "鼠标和3D鼠标可越过两极旋转,并保留画面旋转角度。在拖动环绕时按住Shift,可吸附视图方向和画面旋转角度。"
+ }
+}
diff --git a/crates/ui-egui/src/navigation.rs b/crates/ui-egui/src/navigation.rs
index 9551b1b17a..c2064b64bf 100644
--- a/crates/ui-egui/src/navigation.rs
+++ b/crates/ui-egui/src/navigation.rs
@@ -756,20 +756,28 @@ pub(crate) fn snapped_axis_camera(cam: Camera) -> Camera {
to
}
+/// Choose the closest quarter-turn picture orientation without losing roll at a pole.
+fn snapped_quarter_roll(mut target: Camera, reference: Camera) -> Camera {
+ let (right, up, back) = reference.basis();
+ let mut best = target;
+ let mut best_score = f64::NEG_INFINITY;
+ for quarter in 0..4 {
+ target.roll = f64::from(quarter) * std::f64::consts::FRAC_PI_2;
+ let (r, u, b) = target.basis();
+ // Maximizing the rotation trace minimizes the angular distance between orientations.
+ let score = r.dot(right) + u.dot(up) + b.dot(back);
+ if score > best_score {
+ best = target;
+ best_score = score;
+ }
+ }
+ best
+}
+
/// Orbit by a pointer drag. With `snap` the displayed view is the nearest standard or diagonal
/// direction at once; the unsnapped orbit is kept in `orbit_free` so many small deltas still
/// cross snap boundaries. A small angular margin avoids flicker at a boundary.
pub(crate) fn orbit_drag(app: &mut SolveApp, rect: Rect, dx: f64, dy: f64, press: Option<Pos2>, snap: bool, around_cursor: bool) {
- // Free rotation must not enter the yaw/pitch snap: it discards roll at the poles.
- if app.preferences.free_orbit {
- app.viewport.orbit_free = None;
- if around_cursor {
- orbit(app, rect, dx, dy, press);
- } else {
- orbit_camera(app, dx, dy);
- }
- return;
- }
let displayed = app.cam;
let previous_free = app.viewport.orbit_free.take();
if let Some(free) = previous_free {
@@ -778,11 +786,14 @@ pub(crate) fn orbit_drag(app: &mut SolveApp, rect: Rect, dx: f64, dy: f64, press
if around_cursor {
orbit(app, rect, dx, dy, press);
} else {
- app.cam.orbit(dx, dy);
+ orbit_camera(app, dx, dy);
}
let free = app.cam;
app.viewport.orbit_free = Some(free);
if !snap {
+ if app.preferences.free_orbit {
+ app.viewport.orbit_free = None;
+ }
return;
}
let mut target = snapped_axis_camera(free);
@@ -794,6 +805,9 @@ pub(crate) fn orbit_drag(app: &mut SolveApp, rect: Rect, dx: f64, dy: f64, press
target.pitch = displayed.pitch;
}
}
+ if app.preferences.free_orbit {
+ target = snapped_quarter_roll(target, free);
+ }
// The cursor and origin pivots stay still; the axis gizmo has no pivot (it orbits about the
// view centre, see `axis_view`).
let pivot = if around_cursor {
@@ -1161,6 +1175,111 @@ mod tests {
assert!(app.session.undo.is_empty() && app.session.selection.is_empty());
}
+ #[test]
+ fn every_standard_direction_preserves_its_nearby_quarter_orientation() {
+ use super::*;
+ use solidcraft_engine::render::UpAxis;
+ for up in [UpAxis::Z, UpAxis::Y] {
+ for fov in [0.0, 0.6] {
+ for direction in snap_directions() {
+ for quarter in 0..4 {
+ let base = Camera { up, fov, ..Default::default() };
+ let mut expected = snapped_axis_camera(base.looking_from(base.from_frame(direction)));
+ expected.roll = f64::from(quarter) * std::f64::consts::FRAC_PI_2;
+ let mut free = expected;
+ free.rotate_in_view(Vec3::new(0.008, -0.01, 0.0));
+ let result = snapped_quarter_roll(snapped_axis_camera(free), free);
+ let (r, u, b) = result.basis();
+ let (er, eu, eb) = expected.basis();
+ assert!(
+ r.dist(er) < 4e-6 && u.dist(eu) < 4e-6 && b.dist(eb) < 4e-6,
+ "up={up:?} direction={direction:?} quarter={quarter}: {result:?}"
+ );
+ assert_eq!(result.target, free.target);
+ assert_eq!(result.distance, free.distance);
+ assert_eq!(result.fov, free.fov);
+ }
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn free_orbit_shift_snaps_direction_and_quarter_turn_roll() {
+ use super::*;
+ use solidcraft_engine::render::UpAxis;
+ let rect = Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0));
+ for up in [UpAxis::Z, UpAxis::Y] {
+ for fov in [0.0, 0.6] {
+ for quarter in 0..4 {
+ let roll = f64::from(quarter) * std::f64::consts::FRAC_PI_2;
+ let mut app = crate::SolveApp::new(Default::default(), crate::Services::default());
+ app.preferences.free_orbit = true;
+ app.cam = Camera { target: Vec3::new(2.0, 3.0, 4.0), yaw: 0.08, pitch: 0.1, roll: roll + 0.08, distance: 47.0, fov, up };
+ let expected = Camera { yaw: 0.0, pitch: 0.0, roll, ..app.cam };
+ orbit_drag(&mut app, rect, 0.0, 0.0, None, true, false);
+ let (right, vertical, back) = app.cam.basis();
+ let (r, u, b) = expected.basis();
+ assert!(
+ right.dist(r) < 1e-9 && vertical.dist(u) < 1e-9 && back.dist(b) < 1e-9,
+ "up={up:?}, fov={fov}, quarter={quarter}: {:?}",
+ app.cam
+ );
+ assert_eq!(app.cam.target, expected.target);
+ assert_eq!(app.cam.distance, expected.distance);
+ assert_eq!(app.cam.fov, expected.fov);
+ assert!(app.viewport.orbit_free.is_some());
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn free_orbit_shift_keeps_the_pivot_and_resumes_the_unsnapped_drag() {
+ use super::*;
+ use solidcraft_engine::render::UpAxis;
+ let rect = Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0));
+ for up in [UpAxis::Z, UpAxis::Y] {
+ for fov in [0.0, 0.6] {
+ for around in [OrbitAround::ViewCentre, OrbitAround::Origin, OrbitAround::Cursor] {
+ let mut app = crate::SolveApp::new(Default::default(), crate::Services::default());
+ let mut reference = crate::SolveApp::new(Default::default(), crate::Services::default());
+ let initial = Camera { target: Vec3::new(2.0, 3.0, 4.0), yaw: 0.2, pitch: 0.3, roll: 2.8, fov, up, ..Default::default() };
+ let pivot = match around {
+ OrbitAround::ViewCentre => None,
+ OrbitAround::Origin => Some(Vec3::ZERO),
+ OrbitAround::Cursor => Some(Vec3::new(7.0, -2.0, 3.0)),
+ };
+ for a in [&mut app, &mut reference] {
+ a.preferences.free_orbit = true;
+ a.preferences.orbit_around = around;
+ a.cam = initial;
+ a.viewport.orbit_pivot = pivot;
+ }
+ let design = app.session.doc.to_json();
+ let log = app.session.log.len();
+ for (dx, dy) in [(12.0, 5.0), (-6.0, 8.0), (3.0, -4.0)] {
+ orbit_drag(&mut reference, rect, dx, dy, None, false, true);
+ orbit_drag(&mut app, rect, dx, dy, None, true, true);
+ assert!(app.viewport.orbit_free.is_some());
+ if let Some(p) = pivot {
+ assert!(app.cam.frame_coords(p).dist(initial.frame_coords(p)) < 1e-8);
+ }
+ }
+ orbit_drag(&mut app, rect, 0.0, 0.0, None, false, true);
+ let (right, vertical, back) = app.cam.basis();
+ let (r, u, b) = reference.cam.basis();
+ assert!(right.dist(r) < 1e-9 && vertical.dist(u) < 1e-9 && back.dist(b) < 1e-9);
+ assert!(app.cam.target.dist(reference.cam.target) < 1e-8);
+ assert!(app.viewport.orbit_free.is_none());
+ assert_eq!(app.session.doc.to_json(), design);
+ assert_eq!(app.session.log.len(), log);
+ assert!(app.session.undo.is_empty());
+ }
+ }
+ }
+ }
+
#[test]
fn free_orbit_is_opt_in_for_every_preset_and_shared_by_mouse_and_device() {
use super::*;
@@ -1173,7 +1292,7 @@ mod tests {
h.app.preferences.nav = preset.id.into();
h.app.preferences.free_orbit = enabled;
h.app.cam = initial;
- orbit_drag(&mut h.app, rect, 0.0, 80.0, None, true, false);
+ orbit_drag(&mut h.app, rect, 0.0, 80.0, None, !enabled, false);
if enabled {
assert!((h.app.cam.back().dot(initial.back()) - 0.64_f64.cos()).abs() < 1e-9);
assert!(h.app.viewport.orbit_free.is_none());
@@ -1195,7 +1314,7 @@ mod tests {
}
#[test]
- fn solidworks_mouse_orbit_passes_the_pole_without_snapping() {
+ fn solidworks_mouse_orbit_passes_the_pole_and_shift_snaps() {
use serde_json::json;
for up in [solidcraft_engine::render::UpAxis::Z, solidcraft_engine::render::UpAxis::Y] {
for button in ["middle", "right"] {
@@ -1209,9 +1328,10 @@ mod tests {
h.call("ui.drag", json!({"x0":800,"y0":400,"x1":800,"y1":480,"button":button,"steps":40}));
assert!((h.app.cam.back().dot(before.back()) - 0.64_f64.cos()).abs() < 1e-6, "{up:?} {button}: {:?}", h.app.cam);
assert!(h.app.viewport.orbit_free.is_none());
- let before = h.app.cam;
h.call("ui.drag", json!({"x0":800,"y0":400,"x1":850,"y1":400,"button":"right","shift":true,"steps":20}));
- assert!((h.app.cam.back().dot(before.back()) - 0.4_f64.cos()).abs() < 1e-6);
+ let snapped = super::snapped_axis_camera(h.app.cam);
+ assert!(h.app.cam.back().dist(snapped.back()) < 4e-6);
+ assert!((h.app.cam.roll / std::f64::consts::FRAC_PI_2 - (h.app.cam.roll / std::f64::consts::FRAC_PI_2).round()).abs() < 1e-9);
assert!(h.app.viewport.orbit_free.is_none());
}
}
@@ -1238,7 +1358,8 @@ mod tests {
assert!((before.back().dot(h.app.cam.back()) - (seconds * 2.0).cos()).abs() < 1e-9);
let device_cam = h.app.cam;
h.app.cam = mouse;
- orbit_drag(&mut h.app, rect, rotation[1] * seconds * 250.0, rotation[0] * seconds * 250.0, None, true, false);
+ // Compare continuous rotation; Shift snapping is exercised separately.
+ orbit_drag(&mut h.app, rect, rotation[1] * seconds * 250.0, rotation[0] * seconds * 250.0, None, false, false);
mouse = h.app.cam;
assert!(mouse.back().dist(device_cam.back()) < 1e-9 && mouse.basis().0.dist(device_cam.basis().0) < 1e-9);
h.app.cam = device_cam;
diff --git a/crates/ui-egui/src/prefs/navigation.rs b/crates/ui-egui/src/prefs/navigation.rs
index 540414d484..5bef4f5e00 100644
--- a/crates/ui-egui/src/prefs/navigation.rs
+++ b/crates/ui-egui/src/prefs/navigation.rs
@@ -70,7 +70,7 @@ pub(super) fn show(app: &mut SolveApp, ui: &mut egui::Ui, t: &Tokens) {
let free_orbit = setting::free_orbit(app, ui);
crate::scenario::publish_target("prefs:free_orbit", free_orbit.rect);
if app.preferences.free_orbit {
- ui_kit::text(ui, crate::i18n::tr("nav.free_orbit.help"), ui_kit::Text::Hint("free_orbit"));
+ ui_kit::text(ui, crate::i18n::tr("nav.free_orbit.snap_help"), ui_kit::Text::Hint("free_orbit"));
}
let help = if app.preferences.nav == TOUCHPAD_NAV {
app.tr("nav.touchpad.help").to_owned()
diff --git a/docs/book/src/guide/ui-tour.md b/docs/book/src/guide/ui-tour.md
index f2d8daf771..a0a4664cd4 100644
--- a/docs/book/src/guide/ui-tour.md
+++ b/docs/book/src/guide/ui-tour.md
@@ -42,7 +42,9 @@
diagonal view; Shift does not request snapping when the preset already requires it to orbit.
Enable **Preferences → Navigation → Free orbit** to rotate the mouse and 3D mouse continuously
- through both poles, preserving roll without axis snapping. It defaults to off for every mouse
+ through both poles, preserving roll. During an orbit drag, Shift snaps the view direction and
+ the picture rotation to the nearest quarter turn; releasing Shift resumes the unsnapped rotation.
+ Free orbit defaults to off for every mouse
preset. With SolidWorks navigation, right-click a planar face and choose **Normal to Selection**
to use Look At (also Ctrl+8); repeat to flip the side, preserving scale and projection.