configure mouse dragging with a single parameter

Author: vincekurtz

bindings/generated_docstrings/multibody_meshcat.h

@@ -417,7 +417,11 @@ independent of the body's mass.
 
 When no drag is in progress the output is empty. Any body with
 geometry published to Meshcat by a geometry∷MeshcatVisualizer can be
-dragged; the world body cannot.)""";
+dragged; the world body cannot.
+
+This system is ``double``-only, because Meshcat reports drag state as
+plain doubles and mouse interaction is not meaningful for other scalar
+types.)""";
           // Symbol: drake::multibody::meshcat::MeshcatMouseSpring::AddToBuilder
           struct /* AddToBuilder */ {
             // Source: drake/multibody/meshcat/meshcat_mouse_spring.h
@@ -434,7 +438,7 @@ newly-added system.
     `plant`'s applied-spatial-force input port is not already
     connected.)""";
           } AddToBuilder;
-          // Symbol: drake::multibody::meshcat::MeshcatMouseSpring::MeshcatMouseSpring<T>
+          // Symbol: drake::multibody::meshcat::MeshcatMouseSpring::MeshcatMouseSpring
           struct /* ctor */ {
             // Source: drake/multibody/meshcat/meshcat_mouse_spring.h
             const char* doc =
@@ -464,21 +468,21 @@ Parameter ``stiffness``:
             // Source: drake/multibody/meshcat/meshcat_mouse_spring.h
             const char* doc =
 R"""(Returns the input port for the bodies' poses (a
-``std∷vector<math∷RigidTransform<T>>``).)""";
+``std∷vector<math∷RigidTransform<double>>``).)""";
           } get_body_poses_input_port;
           // Symbol: drake::multibody::meshcat::MeshcatMouseSpring::get_body_spatial_velocities_input_port
           struct /* get_body_spatial_velocities_input_port */ {
             // Source: drake/multibody/meshcat/meshcat_mouse_spring.h
             const char* doc =
 R"""(Returns the input port for the bodies' spatial velocities (a
-``std∷vector<SpatialVelocity<T>>``).)""";
+``std∷vector<SpatialVelocity<double>>``).)""";
           } get_body_spatial_velocities_input_port;
           // Symbol: drake::multibody::meshcat::MeshcatMouseSpring::get_spatial_forces_output_port
           struct /* get_spatial_forces_output_port */ {
             // Source: drake/multibody/meshcat/meshcat_mouse_spring.h
             const char* doc =
 R"""(Returns the output port for the applied spatial forces (a
-``std∷vector<ExternallyAppliedSpatialForce<T>>``).)""";
+``std∷vector<ExternallyAppliedSpatialForce<double>>``).)""";
           } get_spatial_forces_output_port;
         } MeshcatMouseSpring;
       } meshcat;

bindings/generated_docstrings/visualization.h

@@ -581,18 +581,6 @@ R"""(Determines whether to enable alpha sliders for geometry display.)""";
           const char* doc =
 R"""(Whether to create a Meshcat object if needed.)""";
         } enable_meshcat_creation;
-        // Symbol: drake::visualization::VisualizationConfig::enable_mouse_interaction
-        struct /* enable_mouse_interaction */ {
-          // Source: drake/visualization/visualization_config.h
-          const char* doc =
-R"""(Whether to enable interactively dragging bodies with the mouse in
-Meshcat. In a connected Meshcat browser, holding Ctrl and dragging a
-body with the left mouse button applies a virtual spring force that
-pulls the body toward the cursor (see
-multibody∷meshcat∷MeshcatMouseSpring). Has no effect for Meldis/LCM,
-and is skipped if the plant's applied-spatial-force input port is
-already connected.)""";
-        } enable_mouse_interaction;
         // Symbol: drake::visualization::VisualizationConfig::initial_proximity_alpha
         struct /* initial_proximity_alpha */ {
           // Source: drake/visualization/visualization_config.h
@@ -617,8 +605,14 @@ See also:
           // Source: drake/visualization/visualization_config.h
           const char* doc =
 R"""(The mass-normalized stiffness (in 1/s²) of the interactive mouse
-spring; see multibody∷meshcat∷MeshcatMouseSpring. Only used when
-enable_mouse_interaction is true.)""";
+spring that lets a user drag bodies with the mouse in Meshcat. In a
+connected Meshcat browser, holding Ctrl and dragging a body with the
+left mouse button applies a virtual spring force that pulls the body
+toward the cursor (see multibody∷meshcat∷MeshcatMouseSpring).
+
+Setting this to std∷nullopt disables mouse interaction. It also has no
+effect for Meldis/LCM, and is skipped if the plant's
+applied-spatial-force input port is already connected.)""";
         } mouse_interaction_stiffness;
         // Symbol: drake::visualization::VisualizationConfig::publish_contacts
         struct /* publish_contacts */ {
@@ -656,7 +650,6 @@ point; see drake#15021 for details.))""";
             std::make_pair("delete_on_initialization_event", delete_on_initialization_event.doc),
             std::make_pair("enable_alpha_sliders", enable_alpha_sliders.doc),
             std::make_pair("enable_meshcat_creation", enable_meshcat_creation.doc),
-            std::make_pair("enable_mouse_interaction", enable_mouse_interaction.doc),
             std::make_pair("initial_proximity_alpha", initial_proximity_alpha.doc),
             std::make_pair("lcm_bus", lcm_bus.doc),
             std::make_pair("mouse_interaction_stiffness", mouse_interaction_stiffness.doc),

visualization/test/visualization_config_functions_test.cc

@@ -1,6 +1,7 @@
 #include "drake/visualization/visualization_config_functions.h"
 
 #include <memory>
+#include <optional>
 #include <set>
 #include <string>
 #include <vector>
@@ -247,7 +248,7 @@ GTEST_TEST(VisualizationConfigFunctionsTest, ApplyNothing) {
   config.publish_inertia = false;
   config.publish_proximity = false;
   config.publish_contacts = false;
-  config.enable_mouse_interaction = false;
+  config.mouse_interaction_stiffness = std::nullopt;
 
   // We'll fail in case any message is transmitted.
   DrakeLcm drake_lcm;
@@ -311,13 +312,13 @@ GTEST_TEST(VisualizationConfigFunctionsTest, MouseInteraction) {
     EXPECT_EQ(count_springs(builder), 1);
   }
 
-  // Disabled via the config flag.
+  // Disabled by clearing the stiffness.
   {
     DiagramBuilder<double> builder;
     auto [plant, scene_graph] = AddMultibodyPlantSceneGraph(&builder, 0.0);
     plant.Finalize();
     VisualizationConfig config;
-    config.enable_mouse_interaction = false;
+    config.mouse_interaction_stiffness = std::nullopt;
     ApplyVisualizationConfig(config, &builder, &lcm_buses, &plant, &scene_graph,
                              meshcat);
     EXPECT_EQ(count_springs(builder), 0);

visualization/visualization_config.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <optional>
 #include <string>
 
 #include <Eigen/Dense>
@@ -29,7 +30,6 @@ struct VisualizationConfig {
     a->Visit(DRAKE_NVP(enable_meshcat_creation));
     a->Visit(DRAKE_NVP(delete_on_initialization_event));
     a->Visit(DRAKE_NVP(enable_alpha_sliders));
-    a->Visit(DRAKE_NVP(enable_mouse_interaction));
     a->Visit(DRAKE_NVP(mouse_interaction_stiffness));
   }
 
@@ -81,18 +81,16 @@ struct VisualizationConfig {
   /** Determines whether to enable alpha sliders for geometry display. */
   bool enable_alpha_sliders{false};
 
-  /** Whether to enable interactively dragging bodies with the mouse in Meshcat.
-   In a connected Meshcat browser, holding Ctrl and dragging a body with the
-   left mouse button applies a virtual spring force that pulls the body toward
-   the cursor (see multibody::meshcat::MeshcatMouseSpring). Has no effect for
-   Meldis/LCM, and is skipped if the plant's applied-spatial-force input port is
-   already connected. */
-  bool enable_mouse_interaction{true};
-
-  /** The mass-normalized stiffness (in 1/s²) of the interactive mouse spring;
-   see multibody::meshcat::MeshcatMouseSpring. Only used when
-   enable_mouse_interaction is true. */
-  double mouse_interaction_stiffness{100.0};
+  /** The mass-normalized stiffness (in 1/s²) of the interactive mouse spring
+   that lets a user drag bodies with the mouse in Meshcat. In a connected
+   Meshcat browser, holding Ctrl and dragging a body with the left mouse button
+   applies a virtual spring force that pulls the body toward the cursor (see
+   multibody::meshcat::MeshcatMouseSpring).
+
+   Setting this to std::nullopt disables mouse interaction. It also has no
+   effect for Meldis/LCM, and is skipped if the plant's applied-spatial-force
+   input port is already connected. */
+  std::optional<double> mouse_interaction_stiffness{100.0};
 };
 
 }  // namespace visualization

visualization/visualization_config_functions.cc

@@ -78,20 +78,23 @@ void ApplyVisualizationConfigImpl(const VisualizationConfig& config,
           builder, plant, meshcat,
           internal::ConvertVisualizationConfigToMeshcatContactParams(config));
     }
-    if (config.enable_mouse_interaction) {
+    if (config.mouse_interaction_stiffness.has_value() &&
+        config.mouse_interaction_stiffness.value() > 0) {
       // MeshcatMouseSpring drives the plant's applied-spatial-force input port.
       // Only add it if that port is still available; otherwise (e.g., the user
       // has already connected their own external forces) skip it with a warning
       // rather than failing the whole visualization setup.
+      // TODO(vincekurtz): use some sort of spatial force combiner system to
+      // allow multiple sources of spatial forces to be applied to the plant.
       if (builder->IsConnectedOrExported(
               plant.get_applied_spatial_force_input_port())) {
         log()->warn(
-            "VisualizationConfig.enable_mouse_interaction is set, but the "
+            "VisualizationConfig.mouse_interaction_stiffness is set, but the "
             "plant's applied-spatial-force input port is already connected, so "
             "interactive mouse dragging will not be enabled.");
       } else {
-        MeshcatMouseSpring::AddToBuilder(
-            builder, &plant, meshcat, config.mouse_interaction_stiffness);
+        MeshcatMouseSpring::AddToBuilder(builder, &plant, meshcat,
+                                         *config.mouse_interaction_stiffness);
       }
     }
     if (config.publish_inertia && config.enable_alpha_sliders) {