Skip to content

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

fix: apply 3DxWare SpaceMouse axis settings

kenos25ea43e89f59
diff --git a/Cargo.lock b/Cargo.lock
index fb54fc4d18..1d12d8fb56 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3297,6 +3297,7 @@ dependencies = [
"embed-resource",
"hidapi",
"log",
+ "quick-xml 0.38.4",
"rfd",
"serde_json",
"solvecraft-engine",
diff --git a/apps/solvecraft/Cargo.toml b/apps/solvecraft/Cargo.toml
index 0f79184834..f7c1d4a385 100644
--- a/apps/solvecraft/Cargo.toml
+++ b/apps/solvecraft/Cargo.toml
@@ -21,6 +21,7 @@ rfd = { workspace = true }
[target.'cfg(target_os = "windows")'.dependencies]
hidapi = { version = "2.6.7", default-features = false, features = ["windows-native"] }
+quick-xml = { workspace = true }
[target.'cfg(all(unix, not(target_os = "macos")))'.dependencies]
winit = { version = "0.30", default-features = false, features = ["x11"] }
diff --git a/apps/solvecraft/src/space_mouse.rs b/apps/solvecraft/src/space_mouse.rs
index b3effda35e..53c350185e 100644
--- a/apps/solvecraft/src/space_mouse.rs
+++ b/apps/solvecraft/src/space_mouse.rs
@@ -6,11 +6,14 @@ use std::time::{Duration, Instant};
use egui::Context;
use hidapi::{DeviceInfo, HidApi};
+use quick_xml::Reader;
+use quick_xml::events::Event;
use solvecraft_engine::render::Camera;
use solvecraft_ui_egui::SolveApp;
const STALE_AFTER: Duration = Duration::from_millis(150);
const RETRY_AFTER: Duration = Duration::from_secs(2);
+const MAX_PROFILE_BYTES: u64 = 1024 * 1024;
#[derive(Clone, Copy, Debug, Default, PartialEq)]
struct Axes {
@@ -18,6 +21,172 @@ struct Axes {
rotation: [i16; 3],
}
+#[derive(Clone, Copy, Debug, PartialEq)]
+struct AxisRule {
+ output: usize,
+ enabled: bool,
+ reversed: bool,
+ scale: f64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+struct DriverMapping {
+ axes: [AxisRule; 6],
+ overall_scale: f64,
+}
+
+impl Default for DriverMapping {
+ fn default() -> Self {
+ Self { axes: std::array::from_fn(|output| AxisRule { output, enabled: true, reversed: false, scale: 1.0 }), overall_scale: 1.0 }
+ }
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+struct Motion {
+ translation: [f64; 3],
+ rotation: [f64; 3],
+}
+
+impl DriverMapping {
+ fn apply(self, axes: Axes) -> Motion {
+ let raw = [
+ normalized(axes.translation[0]),
+ normalized(axes.translation[1]),
+ normalized(axes.translation[2]),
+ normalized(axes.rotation[0]),
+ normalized(axes.rotation[1]),
+ normalized(axes.rotation[2]),
+ ];
+ let mut logical = [0.0; 6];
+ for (input, rule) in self.axes.iter().enumerate() {
+ if rule.enabled {
+ let sign = if rule.reversed { -1.0 } else { 1.0 };
+ logical[rule.output] = raw[input] * sign * rule.scale * self.overall_scale;
+ }
+ }
+ Motion { translation: [logical[0], logical[1], logical[2]], rotation: [logical[3], logical[4], logical[5]] }
+ }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct ProfileAxis {
+ input: Option<usize>,
+ output: Option<usize>,
+ enabled: bool,
+ reversed: bool,
+ scale: f64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum ProfilePart {
+ Input,
+ Output,
+}
+
+fn axis_index(name: &str) -> Option<usize> {
+ match name.trim() {
+ "HIDMultiAxis_X" => Some(0),
+ "HIDMultiAxis_Y" => Some(1),
+ "HIDMultiAxis_Z" => Some(2),
+ "HIDMultiAxis_Rx" => Some(3),
+ "HIDMultiAxis_Ry" => Some(4),
+ "HIDMultiAxis_Rz" => Some(5),
+ _ => None,
+ }
+}
+
+/// 3DxWare stores the active KMJ application's axis selection, swapping, inversion and speed in
+/// `%APPDATA%/3Dconnexion/3DxWare/Cfg/<app>-KMJ.xml`. Direct HID reads bypass the driver, so apply
+/// that profile explicitly when it exists. Unknown or incomplete fields retain the raw HID axis.
+fn parse_driver_mapping(xml: &[u8]) -> Option<DriverMapping> {
+ let mut reader = Reader::from_reader(xml);
+ reader.config_mut().trim_text(true);
+ let mut buf = Vec::new();
+ let mut mapping = DriverMapping::default();
+ let mut axis: Option<ProfileAxis> = None;
+ let mut part = None;
+ let mut field = Vec::new();
+ let mut found = false;
+ loop {
+ match reader.read_event_into(&mut buf).ok()? {
+ Event::Start(start) => match start.local_name().as_ref() {
+ b"Axis" => axis = Some(ProfileAxis { enabled: true, scale: 1.0, ..Default::default() }),
+ b"Input" => part = Some(ProfilePart::Input),
+ b"Output" => part = Some(ProfilePart::Output),
+ name @ (b"ActionID" | b"Enabled" | b"Reversed" | b"Scale" | b"OverallScale") => field = name.to_vec(),
+ _ => {}
+ },
+ Event::Text(text) => {
+ let value = String::from_utf8_lossy(text.as_ref());
+ match field.as_slice() {
+ b"ActionID" => {
+ if let Some(current) = axis.as_mut() {
+ match part {
+ Some(ProfilePart::Input) => current.input = axis_index(&value),
+ Some(ProfilePart::Output) => current.output = axis_index(&value),
+ None => {}
+ }
+ }
+ }
+ b"Enabled" => {
+ if let Some(current) = axis.as_mut() {
+ current.enabled = value.trim().eq_ignore_ascii_case("true");
+ }
+ }
+ b"Reversed" => {
+ if part == Some(ProfilePart::Output)
+ && let Some(current) = axis.as_mut()
+ {
+ current.reversed = value.trim().eq_ignore_ascii_case("true");
+ }
+ }
+ b"Scale" => {
+ if part == Some(ProfilePart::Output)
+ && let Some(scale) = value.trim().parse::<f64>().ok().filter(|scale| scale.is_finite())
+ && let Some(current) = axis.as_mut()
+ {
+ current.scale = scale.clamp(0.0, 10.0);
+ }
+ }
+ b"OverallScale" => {
+ if let Some(scale) = value.trim().parse::<f64>().ok().filter(|scale| scale.is_finite()) {
+ mapping.overall_scale = scale.clamp(0.0, 10.0);
+ }
+ }
+ _ => {}
+ }
+ }
+ Event::End(end) => match end.local_name().as_ref() {
+ b"Axis" => {
+ if let Some(current) = axis.take()
+ && let (Some(input), Some(output)) = (current.input, current.output)
+ {
+ mapping.axes[input] = AxisRule { output, enabled: current.enabled, reversed: current.reversed, scale: current.scale };
+ found = true;
+ }
+ }
+ b"Input" | b"Output" => part = None,
+ b"ActionID" | b"Enabled" | b"Reversed" | b"Scale" | b"OverallScale" => field.clear(),
+ _ => {}
+ },
+ Event::Eof => break,
+ _ => {}
+ }
+ buf.clear();
+ }
+ found.then_some(mapping)
+}
+
+fn load_driver_mapping() -> Option<DriverMapping> {
+ let profile = std::path::PathBuf::from(std::env::var_os("APPDATA")?).join("3Dconnexion").join("3DxWare").join("Cfg").join("solvecraft-KMJ.xml");
+ if std::fs::metadata(&profile).ok()?.len() > MAX_PROFILE_BYTES {
+ log::warn!("3D mouse: ignoring oversized 3DxWare profile {}", profile.display());
+ return None;
+ }
+ let xml = std::fs::read(&profile).ok()?;
+ parse_driver_mapping(&xml)
+}
+
#[derive(Clone, Copy)]
struct Reading {
axes: Axes,
@@ -107,6 +276,8 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
pub struct SpaceMouse {
shared: Arc<Mutex<Reading>>,
last_frame: Instant,
+ driver_mapping: DriverMapping,
+ mapping_checked_at: Instant,
}
impl SpaceMouse {
@@ -118,13 +289,21 @@ impl SpaceMouse {
if let Err(error) = std::thread::Builder::new().name("solvecraft-3d-mouse".into()).spawn(move || reader(worker_ctx, worker_state)) {
log::warn!("3D mouse: reader could not start: {error}");
}
- Self { shared, last_frame: now }
+ Self { shared, last_frame: now, driver_mapping: load_driver_mapping().unwrap_or_default(), mapping_checked_at: now }
}
pub fn tick(&mut self, app: &mut SolveApp, ctx: &Context) {
let now = Instant::now();
let seconds = now.duration_since(self.last_frame).as_secs_f64().min(0.05);
self.last_frame = now;
+ if now.duration_since(self.mapping_checked_at) >= RETRY_AFTER {
+ let updated = load_driver_mapping().unwrap_or_default();
+ if updated != self.driver_mapping {
+ log::info!("3D mouse: applying updated 3DxWare axis profile");
+ self.driver_mapping = updated;
+ }
+ self.mapping_checked_at = now;
+ }
if !app.preferences.space_mouse_enabled || app.home.open {
return;
}
@@ -141,7 +320,14 @@ impl SpaceMouse {
}
app.begin_external_navigation();
let height = app.viewport.rect.map_or(600.0, |rect| f64::from(rect.height().max(1.0)));
- navigate(&mut app.cam, axes, seconds * speed.clamp(0.1, 5.0), height, app.session.active_sketch.is_some());
+ navigate(
+ &mut app.cam,
+ self.driver_mapping.apply(axes),
+ seconds * speed.clamp(0.1, 5.0),
+ height,
+ app.session.active_sketch.is_some(),
+ app.preferences.zoom_reverse,
+ );
ctx.request_repaint_after(Duration::from_millis(16));
}
}
@@ -153,15 +339,21 @@ fn normalized(value: i16) -> f64 {
if v.abs() <= 20.0 { 0.0 } else { v.signum() * ((v.abs() - 20.0) / 330.0).min(1.0) }
}
-fn navigate(cam: &mut Camera, axes: Axes, seconds: f64, height: f64, sketch: bool) {
+fn navigate(cam: &mut Camera, motion: Motion, seconds: f64, height: f64, sketch: bool, reverse_zoom: bool) {
if !(seconds > 0.0) || !seconds.is_finite() {
return;
}
- let [x, y, z] = axes.translation.map(normalized);
- let [rx, ry, rz] = axes.rotation.map(normalized);
- cam.pan(x * height * 0.6 * seconds, -y * height * 0.6 * seconds, height);
- cam.zoom_at((-z * 1.5 * seconds).exp(), None);
+ let [x, y, z] = motion.translation;
+ let [rx, ry, rz] = motion.rotation;
+ // Logical 3DxWare coordinates are X = left/right, Y = zoom and Z = up/down. The user's
+ // profile above can swap the physical forward/back and up/down axes before they reach here.
+ cam.pan(x * height * 0.6 * seconds, z * height * 0.6 * seconds, height);
+ let zoom_sign = if reverse_zoom { -1.0 } else { 1.0 };
+ cam.zoom_at((-y * zoom_sign * 1.5 * seconds).exp(), None);
if !sketch {
+ // These are logical 3DxWare coordinates after the profile mapping above: Rx is Tilt,
+ // Ry is Roll and Rz is Spin. The KMJ profile swaps physical Ry/Rz for the selected
+ // navigation mode, so swapping them again here would make Roll behave like Spin.
cam.orbit(ry * 250.0 * seconds, rx * 250.0 * seconds);
cam.roll_by(rz * 2.0 * seconds);
}
@@ -171,6 +363,10 @@ fn navigate(cam: &mut Camera, axes: Axes, seconds: f64, height: f64, sketch: boo
mod tests {
use super::*;
+ fn raw(axes: Axes) -> Motion {
+ DriverMapping::default().apply(axes)
+ }
+
#[test]
fn decodes_separate_reports_without_stale_motion_or_padding_interference() {
let now = Instant::now();
@@ -192,15 +388,102 @@ mod tests {
fn six_axes_move_the_camera_and_sketches_keep_their_orientation() {
let mut cam = Camera::default();
let before = cam;
- navigate(&mut cam, Axes { translation: [350, 350, 350], rotation: [350, 350, 350] }, 0.02, 600.0, false);
+ navigate(&mut cam, raw(Axes { translation: [350, 350, 350], rotation: [350, 350, 350] }), 0.02, 600.0, false, false);
assert_ne!(cam.target, before.target);
assert!(cam.distance < before.distance);
assert_ne!(cam.yaw, before.yaw);
assert_ne!(cam.pitch, before.pitch);
assert_ne!(cam.roll, before.roll);
let orientation = (cam.yaw, cam.pitch, cam.roll);
- navigate(&mut cam, Axes { translation: [350, 0, 0], rotation: [350, 350, 350] }, 0.02, 600.0, true);
+ navigate(&mut cam, raw(Axes { translation: [350, 0, 0], rotation: [350, 350, 350] }), 0.02, 600.0, true, false);
assert_eq!((cam.yaw, cam.pitch, cam.roll), orientation);
assert!(cam.is_valid());
}
+
+ #[test]
+ fn individual_axes_have_physical_spacemouse_meaning() {
+ let before = Camera::default();
+
+ let mut slide = before;
+ navigate(&mut slide, raw(Axes { translation: [350, 0, 0], rotation: [0; 3] }), 0.02, 600.0, false, false);
+ assert_ne!(slide.target, before.target);
+ assert_eq!(slide.distance, before.distance);
+
+ let mut push = before;
+ navigate(&mut push, raw(Axes { translation: [0, 350, 0], rotation: [0; 3] }), 0.02, 600.0, false, false);
+ assert_eq!(push.target, before.target);
+ assert!(push.distance < before.distance);
+
+ let mut lift = before;
+ navigate(&mut lift, raw(Axes { translation: [0, 0, 350], rotation: [0; 3] }), 0.02, 600.0, false, false);
+ assert_ne!(lift.target, before.target);
+ assert_eq!(lift.distance, before.distance);
+
+ let mut tilt = before;
+ navigate(&mut tilt, raw(Axes { translation: [0; 3], rotation: [350, 0, 0] }), 0.02, 600.0, false, false);
+ assert_eq!((tilt.yaw, tilt.roll), (before.yaw, before.roll));
+ assert_ne!(tilt.pitch, before.pitch);
+
+ let mut roll = before;
+ navigate(&mut roll, raw(Axes { translation: [0; 3], rotation: [0, 350, 0] }), 0.02, 600.0, false, false);
+ assert_eq!((roll.pitch, roll.roll), (before.pitch, before.roll));
+ assert_ne!(roll.yaw, before.yaw);
+
+ let mut twist = before;
+ navigate(&mut twist, raw(Axes { translation: [0; 3], rotation: [0, 0, 350] }), 0.02, 600.0, false, false);
+ assert_eq!((twist.yaw, twist.pitch), (before.yaw, before.pitch));
+ assert_ne!(twist.roll, before.roll);
+ }
+
+ #[test]
+ fn reverse_zoom_setting_applies_to_spacemouse() {
+ let before = Camera::default();
+ let motion = raw(Axes { translation: [0, 350, 0], rotation: [0; 3] });
+ let mut normal = before;
+ navigate(&mut normal, motion, 0.02, 600.0, false, false);
+ let mut reversed = before;
+ navigate(&mut reversed, motion, 0.02, 600.0, false, true);
+ assert!(normal.distance < before.distance);
+ assert!(reversed.distance > before.distance);
+ }
+
+ #[test]
+ fn applies_3dxware_axis_swaps_and_reversals() {
+ let profile = br#"
+ <AppCfg><Devices><Device><AxisBank>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_X</ActionID></Input><Output><ActionID>HIDMultiAxis_X</ActionID><Reversed>false</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Y</ActionID></Input><Output><ActionID>HIDMultiAxis_Z</ActionID><Reversed>false</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Z</ActionID></Input><Output><ActionID>HIDMultiAxis_Y</ActionID><Reversed>true</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Rx</ActionID></Input><Output><ActionID>HIDMultiAxis_Rx</ActionID><Reversed>false</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Ry</ActionID></Input><Output><ActionID>HIDMultiAxis_Rz</ActionID><Reversed>false</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Rz</ActionID></Input><Output><ActionID>HIDMultiAxis_Ry</ActionID><Reversed>true</Reversed></Output></Axis>
+ </AxisBank></Device></Devices></AppCfg>
+ "#;
+ let mapping = parse_driver_mapping(profile).expect("valid 3DxWare profile");
+ let motion = mapping.apply(Axes { translation: [350, 0, 350], rotation: [350, 0, 350] });
+ assert_eq!(motion.translation, [1.0, -1.0, 0.0]);
+ assert_eq!(motion.rotation, [1.0, -1.0, 0.0]);
+ }
+
+ #[test]
+ fn mapped_roll_and_spin_reach_distinct_camera_rotations() {
+ let profile = br#"
+ <AppCfg><Devices><Device><AxisBank>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Ry</ActionID></Input><Output><ActionID>HIDMultiAxis_Rz</ActionID><Reversed>false</Reversed></Output></Axis>
+ <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Rz</ActionID></Input><Output><ActionID>HIDMultiAxis_Ry</ActionID><Reversed>true</Reversed></Output></Axis>
+ </AxisBank></Device></Devices></AppCfg>
+ "#;
+ let mapping = parse_driver_mapping(profile).expect("valid 3DxWare profile");
+ let before = Camera::default();
+
+ let mut physical_roll = before;
+ navigate(&mut physical_roll, mapping.apply(Axes { translation: [0; 3], rotation: [0, 350, 0] }), 0.02, 600.0, false, false);
+ assert_eq!((physical_roll.yaw, physical_roll.pitch), (before.yaw, before.pitch));
+ assert_ne!(physical_roll.roll, before.roll);
+
+ let mut physical_spin = before;
+ navigate(&mut physical_spin, mapping.apply(Axes { translation: [0; 3], rotation: [0, 0, 350] }), 0.02, 600.0, false, false);
+ assert_ne!(physical_spin.yaw, before.yaw);
+ assert_eq!((physical_spin.pitch, physical_spin.roll), (before.pitch, before.roll));
+ }
}