Another project
feat(render): arcball orbit, pan, roll drag navigator
Lewis: May this revision serve well! <lu5a@proton.me>
author
Lewis
date
(Jun 7, 2026, 11:30 AM +0300)
commit
4aa6001e
4aa6001ea2ef8c48ab3ea6b275bb0b46dff0ef96
parent
d7aef0be
d7aef0be70cc56928091928cd28c303408312327
change-id
mrsptoqx
mrsptoqxuxwxsltzzzvyolmyspmtwwqu
+446
-5
+144
-2
crates/bone-render/src/camera3.rs
+144
-2
crates/bone-render/src/camera3.rs
···
4
4
use uom::si::length::millimeter;
5
5
6
6
use bone_types::{
7
-
Aabb3, AxisAngle, Camera3, Plane3, Point3, Projection, ProjectionKind, Result, StandardView,
8
-
Tolerance, TypesError, UnitVec3, Vec3, ZoomFactor,
7
+
Aabb3, Angle, AxisAngle, Camera3, Plane3, Point3, Projection, ProjectionKind, Result,
8
+
StandardView, Tolerance, TypesError, UnitVec3, Vec3, ZoomFactor,
9
9
};
10
10
11
11
use crate::camera::ViewportExtent;
···
13
13
const ORTHO_DEPTH_FACTOR: f64 = 8.0;
14
14
const RAY_TOLERANCE: Tolerance = Tolerance::new(1.0e-12);
15
15
const FOCAL_DENOM_FLOOR: f64 = 1.0e-9;
16
+
const ARCBALL_MIN_AXIS: f64 = 1.0e-9;
16
17
const FRAME_MARGIN: f64 = 1.2;
17
18
const SILHOUETTE_COLLAPSE_FRACTION: f64 = 1.0e-6;
18
19
···
125
126
)
126
127
}
127
128
129
+
pub fn arcball_rotation(
130
+
camera: Camera3,
131
+
extent: ViewportExtent,
132
+
from: ViewportPoint,
133
+
to: ViewportPoint,
134
+
) -> Result<AxisAngle> {
135
+
let grabbed = arcball_vector(camera, extent, from)?;
136
+
let dragged = arcball_vector(camera, extent, to)?;
137
+
let axis = grabbed.cross(&dragged);
138
+
let axis_norm = axis.norm();
139
+
if axis_norm < ARCBALL_MIN_AXIS {
140
+
return Ok(AxisAngle::new(
141
+
UnitVec3::z_axis(),
142
+
Angle::new::<radian>(0.0),
143
+
));
144
+
}
145
+
let angle = grabbed.dot(&dragged).clamp(-1.0, 1.0).acos();
146
+
let unit = axis / axis_norm;
147
+
Ok(AxisAngle::new(
148
+
UnitVec3::new_unchecked(unit.x, unit.y, unit.z),
149
+
Angle::new::<radian>(angle),
150
+
))
151
+
}
152
+
153
+
pub fn roll_about_view(
154
+
camera: Camera3,
155
+
extent: ViewportExtent,
156
+
from: ViewportPoint,
157
+
to: ViewportPoint,
158
+
) -> Result<Camera3> {
159
+
let forward = view_direction(camera)?;
160
+
let cx = f64::from(extent.width().value()) * 0.5;
161
+
let cy = f64::from(extent.height().value()) * 0.5;
162
+
let (ax, ay) = (from.x() - cx, from.y() - cy);
163
+
let (bx, by) = (to.x() - cx, to.y() - cy);
164
+
let angle = (ax * by - ay * bx).atan2(ax * bx + ay * by);
165
+
Camera3::new(
166
+
camera.eye(),
167
+
camera.target(),
168
+
camera
169
+
.up()
170
+
.rotated(AxisAngle::new(forward, Angle::new::<radian>(angle))),
171
+
camera.projection(),
172
+
)
173
+
}
174
+
128
175
pub fn frame_isometric(aabb: Aabb3, extent: ViewportExtent) -> Result<Camera3> {
129
176
let direction = UnitVec3::try_from_components(1.0, 1.0, 1.0, RAY_TOLERANCE)?;
130
177
frame_along(aabb, extent, direction, UnitVec3::z_axis())
···
285
332
(camera.target() - camera.eye()).try_normalize(RAY_TOLERANCE)
286
333
}
287
334
335
+
fn arcball_vector(
336
+
camera: Camera3,
337
+
extent: ViewportExtent,
338
+
pixel: ViewportPoint,
339
+
) -> Result<NVec3<f64>> {
340
+
let forward = view_direction(camera)?;
341
+
let (fx, fy, fz) = forward.components();
342
+
let f = NVec3::new(fx, fy, fz);
343
+
let (ux, uy, uz) = camera.up().components();
344
+
let right = f.cross(&NVec3::new(ux, uy, uz)).normalize();
345
+
let up = right.cross(&f);
346
+
let (ndc_x, ndc_y) = ndc_of(pixel, extent);
347
+
let sphere_x = ndc_x * aspect_ratio(extent);
348
+
let radius_sq = sphere_x * sphere_x + ndc_y * ndc_y;
349
+
let depth = if radius_sq <= 1.0 {
350
+
(1.0 - radius_sq).sqrt()
351
+
} else {
352
+
0.0
353
+
};
354
+
let local = NVec3::new(sphere_x, ndc_y, depth).normalize();
355
+
Ok(right * local.x + up * local.y - f * local.z)
356
+
}
357
+
288
358
fn translate(camera: Camera3, delta: Vec3) -> Result<Camera3> {
289
359
Camera3::new(
290
360
camera.eye() + delta,
···
572
642
"world point under the cursor should survive an orbit"
573
643
);
574
644
});
645
+
}
646
+
647
+
#[test]
648
+
fn arcball_rotation_is_identity_when_the_cursor_holds_still() {
649
+
let pixel = vp(70.0, 90.0);
650
+
let Ok(rotation) = arcball_rotation(ortho_camera(), extent(), pixel, pixel) else {
651
+
panic!("a zero-length drag still yields a rotation");
652
+
};
653
+
assert!(
654
+
rotation.angle().get::<radian>().abs() < 1e-12,
655
+
"holding the cursor still produces no rotation"
656
+
);
657
+
}
658
+
659
+
#[test]
660
+
fn arcball_speed_is_isotropic_across_aspect() {
661
+
let wide = ViewportExtent::new(
662
+
crate::camera::ViewportPx::new(512),
663
+
crate::camera::ViewportPx::new(256),
664
+
);
665
+
let (cx, cy) = (256.0, 128.0);
666
+
let span = 60.0;
667
+
let Ok(horizontal) = arcball_rotation(ortho_camera(), wide, vp(cx, cy), vp(cx + span, cy))
668
+
else {
669
+
panic!("a horizontal drag rotates");
670
+
};
671
+
let Ok(vertical) = arcball_rotation(ortho_camera(), wide, vp(cx, cy), vp(cx, cy + span))
672
+
else {
673
+
panic!("a vertical drag rotates");
674
+
};
675
+
let h = horizontal.angle().get::<radian>();
676
+
let v = vertical.angle().get::<radian>();
677
+
assert!(
678
+
(h - v).abs() < 1e-9,
679
+
"equal pixel drags must rotate equally on a non-square viewport: h={h} v={v}"
680
+
);
681
+
}
682
+
683
+
#[test]
684
+
fn antipodal_single_step_drag_collapses_to_no_rotation() {
685
+
let Ok(rotation) =
686
+
arcball_rotation(ortho_camera(), extent(), vp(256.0, 128.0), vp(0.0, 128.0))
687
+
else {
688
+
panic!("the arcball still yields a rotation at the sphere edge");
689
+
};
690
+
assert!(
691
+
rotation.angle().get::<radian>().abs() < 1e-9,
692
+
"a single step between antipodal sphere points is intentionally a no-op, not a pi flip"
693
+
);
694
+
}
695
+
696
+
#[test]
697
+
fn roll_sweep_from_right_to_below_rolls_up_toward_positive_x() {
698
+
let Ok(projection) = Projection::orthographic(Length::new::<millimeter>(2.0)) else {
699
+
panic!("half height is positive");
700
+
};
701
+
let Ok(front) = Camera3::new(
702
+
Point3::from_mm(0.0, -10.0, 0.0),
703
+
Point3::origin(),
704
+
UnitVec3::z_axis(),
705
+
projection,
706
+
) else {
707
+
panic!("camera is non-degenerate");
708
+
};
709
+
let Ok(rolled) = roll_about_view(front, extent(), vp(200.0, 128.0), vp(128.0, 200.0)) else {
710
+
panic!("a roll drag transforms the camera");
711
+
};
712
+
let (ux, uy, uz) = rolled.up().components();
713
+
assert!(
714
+
(ux - 1.0).abs() < 1e-9 && uy.abs() < 1e-9 && uz.abs() < 1e-9,
715
+
"a right-then-below screen sweep rolls up from +z to +x: ({ux}, {uy}, {uz})"
716
+
);
575
717
}
576
718
577
719
#[test]
+5
-3
crates/bone-render/src/lib.rs
+5
-3
crates/bone-render/src/lib.rs
···
2
2
pub mod camera3;
3
3
pub mod diff;
4
4
pub mod gpu;
5
+
pub mod navigate;
5
6
pub mod pick;
6
7
pub mod pipelines;
7
8
pub mod preview;
···
12
13
13
14
pub use camera::{Camera2, GridSpacing, PixelsPerMm, ViewportExtent, ViewportPx};
14
15
pub use camera3::{
15
-
ViewportPoint, clip_from_world, frame_isometric, frame_standard_view, orbit_about_pixel,
16
-
orbit_about_point, pan_pixels, world_from_clip, world_on_focal_plane, world_ray,
17
-
zoom_about_pixel,
16
+
ViewportPoint, arcball_rotation, clip_from_world, frame_isometric, frame_standard_view,
17
+
orbit_about_pixel, orbit_about_point, pan_pixels, roll_about_view, world_from_clip,
18
+
world_on_focal_plane, world_ray, zoom_about_pixel,
18
19
};
19
20
pub use diff::{PixelDiff, PixelDiffError, PixelDiffReport, PixelDiffThreshold, PixelMismatch};
20
21
pub use gpu::{BackendTag, Capabilities, Gpu, OffscreenContext};
22
+
pub use navigate::{DragModifiers, NavGesture, ViewportNavigator};
21
23
pub use pick::{
22
24
EntityKindTag, PickAperture, PickId, PickIdError, PickIndex, PickQuery, PickedItem, Picker,
23
25
};