Implement AbstractPath and related API changes to support multiple path types

CHANGELOG.md

@@ -6,6 +6,10 @@ request related to the change, then we may provide the commit.
 
 This is not a comprehensive list of changes but rather a hand-curated collection of the more notable ones. For a comprehensive history, see the [OpenSim Core GitHub repo](https://github.com/opensim-org/opensim-core).
 
+v4.5
+====
+- Added `AbstractPath` which is a base class for `GeometryPath` and other path types (#3388).
+
 v4.4.1
 ======
 - IMU::calcGyroscopeSignal() now reports angular velocities in the IMU frame.

OpenSim/Actuators/DeGrooteFregly2016Muscle.cpp

@@ -27,6 +27,7 @@
 #include <OpenSim/Actuators/Thelen2003Muscle.h>
 #include <OpenSim/Common/CommonUtilities.h>
 #include <OpenSim/Simulation/Model/Model.h>
+#include "OpenSim/Simulation/Model/GeometryPath.h"
 #include "OpenSim/Common/STOFileAdapter.h"
 
 using namespace OpenSim;
@@ -1021,31 +1022,40 @@ void DeGrooteFregly2016Muscle::replaceMuscles(
         actu->set_ignore_activation_dynamics(
                 muscBase.get_ignore_activation_dynamics());
 
-        const auto& pathPointSet = muscBase.getGeometryPath().getPathPointSet();
-        auto& geomPath = actu->updGeometryPath();
-        for (int ipp = 0; ipp < pathPointSet.getSize(); ++ipp) {
-            auto* pathPoint = pathPointSet.get(ipp).clone();
-            const auto& socketNames = pathPoint->getSocketNames();
-            for (const auto& socketName : socketNames) {
-                pathPoint->updSocket(socketName)
-                        .connect(pathPointSet.get(ipp)
-                                         .getSocket(socketName)
-                                         .getConnecteeAsObject());
+        // Copy the muscle's path.
+        if (auto* pGeometryPath = muscBase.tryUpdPath<GeometryPath>()) {
+            const auto& pathPointSet = pGeometryPath->getPathPointSet();
+            for (int ipp = 0; ipp < pathPointSet.getSize(); ++ipp) {
+                auto* pathPoint = pathPointSet.get(ipp).clone();
+                const auto& socketNames = pathPoint->getSocketNames();
+                for (const auto& socketName : socketNames) {
+                    pathPoint->updSocket(socketName)
+                            .connect(pathPointSet.get(ipp)
+                                             .getSocket(socketName)
+                                             .getConnecteeAsObject());
+                }
+                actu->updGeometryPath().updPathPointSet()
+                        .adoptAndAppend(pathPoint);
             }
-            geomPath.updPathPointSet().adoptAndAppend(pathPoint);
-        }
 
-        const auto& pathWrapSet = muscBase.getGeometryPath().getWrapSet();
-        for (int ipw = 0; ipw < pathWrapSet.getSize(); ++ipw) {
-            auto* pathWrap = pathWrapSet.get(ipw).clone();
-            const auto& socketNames = pathWrap->getSocketNames();
-            for (const auto& socketName : socketNames) {
-                pathWrap->updSocket(socketName)
-                        .connect(pathWrapSet.get(ipw)
-                                .getSocket(socketName)
-                                .getConnecteeAsObject());
+            const auto& pathWrapSet = pGeometryPath->getWrapSet();
+            for (int ipw = 0; ipw < pathWrapSet.getSize(); ++ipw) {
+                auto* pathWrap = pathWrapSet.get(ipw).clone();
+                const auto& socketNames = pathWrap->getSocketNames();
+                for (const auto& socketName : socketNames) {
+                    pathWrap->updSocket(socketName)
+                            .connect(pathWrapSet.get(ipw)
+                                             .getSocket(socketName)
+                                             .getConnecteeAsObject());
+                }
+                actu->updGeometryPath().updWrapSet()
+                        .adoptAndAppend(pathWrap);
             }
-            geomPath.updWrapSet().adoptAndAppend(pathWrap);
+        } else {
+            OPENSIM_THROW(Exception,
+                    "Muscle '{}' contains supported path type {}.",
+                    muscBase.getName(), 
+                    muscBase.getPath().getConcreteClassName())
         }
 
         std::string actname = actu->getName();
@@ -1074,14 +1084,14 @@ void DeGrooteFregly2016Muscle::extendPostScale(
         const SimTK::State& s, const ScaleSet& scaleSet) {
     Super::extendPostScale(s, scaleSet);
 
-    GeometryPath& path = upd_GeometryPath();
+    AbstractPath& path = updPath();
     if (path.getPreScaleLength(s) > 0.0)
     {
         double scaleFactor = path.getLength(s) / path.getPreScaleLength(s);
         upd_optimal_fiber_length() *= scaleFactor;
         upd_tendon_slack_length() *= scaleFactor;
 
-        // Clear the pre-scale length that was stored in the GeometryPath.
+        // Clear the pre-scale length that was stored in the path.
         path.setPreScaleLength(s, 0.0);
     }
 }

OpenSim/Actuators/McKibbenActuator.cpp

@@ -107,7 +107,7 @@ void McKibbenActuator::computeForce(const SimTK::State& s,
 
     double actuation = computeActuation(s);
 
-    getGeometryPath().addInEquivalentForces(s, actuation, bodyForces, generalizedForces);
+    getPath().addInEquivalentForces(s, actuation, bodyForces, generalizedForces);
 }
 //_____________________________________________________________________________
 /**

OpenSim/Actuators/Millard2012AccelerationMuscle.cpp

@@ -557,14 +557,14 @@ extendPostScale(const SimTK::State& s, const ScaleSet& scaleSet)
 
     Super::extendPostScale(s, scaleSet);
 
-    GeometryPath& path = upd_GeometryPath();
+    AbstractPath& path = updPath();
     if (path.getPreScaleLength(s) > 0.0)
     {
         double scaleFactor = path.getLength(s) / path.getPreScaleLength(s);
         upd_optimal_fiber_length() *= scaleFactor;
         upd_tendon_slack_length() *= scaleFactor;
 
-        // Clear the pre-scale length that was stored in the GeometryPath.
+        // Clear the pre-scale length that was stored in the path.
         path.setPreScaleLength(s, 0.0);
     }
 }

OpenSim/Actuators/Millard2012EquilibriumMuscle.cpp

@@ -598,14 +598,14 @@ extendPostScale(const SimTK::State& s, const ScaleSet& scaleSet)
 {
     Super::extendPostScale(s, scaleSet);
 
-    GeometryPath& path = upd_GeometryPath();
+    AbstractPath& path = updPath();
     if (path.getPreScaleLength(s) > 0.0)
     {
         double scaleFactor = path.getLength(s) / path.getPreScaleLength(s);
         upd_optimal_fiber_length() *= scaleFactor;
         upd_tendon_slack_length() *= scaleFactor;
 
-        // Clear the pre-scale length that was stored in the GeometryPath.
+        // Clear the pre-scale length that was stored in the path.
         path.setPreScaleLength(s, 0.0);
     }
 }

OpenSim/Actuators/ModelFactory.cpp

@@ -22,6 +22,7 @@
 #include <OpenSim/Simulation/SimbodyEngine/PinJoint.h>
 #include <OpenSim/Simulation/SimbodyEngine/SliderJoint.h>
 #include <OpenSim/Simulation/SimbodyEngine/WeldJoint.h>
+#include <OpenSim/Simulation/Model/GeometryPath.h>
 #include <OpenSim/Common/CommonUtilities.h>
 
 using namespace OpenSim;
@@ -171,35 +172,44 @@ void ModelFactory::replaceMusclesWithPathActuators(OpenSim::Model &model) {
 
         model.addForce(actu);
 
-        // For the connectee names in the PathPoints to be correct, we must add
-        // the path points after adding the PathActuator to the model.
-        const auto& pathPointSet = musc.getGeometryPath().getPathPointSet();
-        auto& geomPath = actu->updGeometryPath();
-        for (int ip = 0; ip < pathPointSet.getSize(); ++ip) {
-            auto* pathPoint = pathPointSet.get(ip).clone();
-            const auto& socketNames = pathPoint->getSocketNames();
-            for (const auto& socketName : socketNames) {
-                pathPoint->updSocket(socketName)
-                        .connect(pathPointSet.get(ip)
-                                .getSocket(socketName)
-                                .getConnecteeAsObject());
+        // Copy the muscle's path.
+        if (auto* pGeometryPath = musc.tryUpdPath<GeometryPath>()) {
+            // For the connectee names in the PathPoints to be correct, we must
+            // add the path points after adding the PathActuator to the model.
+            const auto& pathPointSet = pGeometryPath->getPathPointSet();
+            for (int ip = 0; ip < pathPointSet.getSize(); ++ip) {
+                auto* pathPoint = pathPointSet.get(ip).clone();
+                const auto& socketNames = pathPoint->getSocketNames();
+                for (const auto& socketName : socketNames) {
+                    pathPoint->updSocket(socketName)
+                            .connect(pathPointSet.get(ip)
+                                             .getSocket(socketName)
+                                             .getConnecteeAsObject());
+                }
+                actu->updGeometryPath().updPathPointSet()
+                        .adoptAndAppend(pathPoint);
             }
-            geomPath.updPathPointSet().adoptAndAppend(pathPoint);
-        }
 
-        // For the connectee names in the PathWraps to be correct, we must add
-        // the path wraps after adding the PathActuator to the model.
-        const auto& pathWrapSet = musc.getGeometryPath().getWrapSet();
-        for (int ipw = 0; ipw < pathWrapSet.getSize(); ++ipw) {
-            auto* pathWrap = pathWrapSet.get(ipw).clone();
-            const auto& socketNames = pathWrap->getSocketNames();
-            for (const auto& socketName : socketNames) {
-                pathWrap->updSocket(socketName)
-                        .connect(pathWrapSet.get(ipw)
-                                .getSocket(socketName)
-                                .getConnecteeAsObject());
+            // For the connectee names in the PathWraps to be correct, we must
+            // add the path wraps after adding the PathActuator to the model.
+            const auto& pathWrapSet = pGeometryPath->getWrapSet();
+            for (int ipw = 0; ipw < pathWrapSet.getSize(); ++ipw) {
+                auto* pathWrap = pathWrapSet.get(ipw).clone();
+                const auto& socketNames = pathWrap->getSocketNames();
+                for (const auto& socketName : socketNames) {
+                    pathWrap->updSocket(socketName)
+                            .connect(pathWrapSet.get(ipw)
+                                             .getSocket(socketName)
+                                             .getConnecteeAsObject());
+                }
+                actu->updGeometryPath().updWrapSet()
+                        .adoptAndAppend(pathWrap);
             }
-            geomPath.updWrapSet().adoptAndAppend(pathWrap);
+        } else {
+            OPENSIM_THROW(Exception,
+                    "Muscle '{}' contains supported path type {}.",
+                    musc.getName(), 
+                    musc.getPath().getConcreteClassName())
         }
 
         musclesToDelete.push_back(&musc);

OpenSim/Actuators/ModelFactory.h

@@ -60,7 +60,7 @@ class OSIMACTUATORS_API ModelFactory {
     /// @name Modify a Model
     /// @{
 
-    /// Replace muscles in a model with a PathActuator of the same GeometryPath,
+    /// Replace muscles in a model with a PathActuator of the same path,
     /// optimal force, and min/max control defaults.
     /// @note This only replaces muscles within the model's ForceSet.
     static void replaceMusclesWithPathActuators(Model& model);

OpenSim/Actuators/RigidTendonMuscle.cpp

@@ -161,7 +161,7 @@ void RigidTendonMuscle::calcMusclePotentialEnergyInfo(const SimTK::State& s,
 void RigidTendonMuscle::calcFiberVelocityInfo(const State& s, FiberVelocityInfo& fvi) const
 {
     /*const MuscleLengthInfo &mli = */getMuscleLengthInfo(s);
-    fvi.fiberVelocity = getGeometryPath().getLengtheningSpeed(s);
+    fvi.fiberVelocity = getPath().getLengtheningSpeed(s);
     fvi.normFiberVelocity = fvi.fiberVelocity / 
                             (getOptimalFiberLength()*getMaxContractionVelocity());
     fvi.fiberForceVelocityMultiplier = 

OpenSim/Analyses/MuscleAnalysis.h

@@ -28,6 +28,7 @@
 //=============================================================================
 // INCLUDES
 //=============================================================================
+#include <OpenSim/Common/PropertyStrArray.h>
 #include <OpenSim/Simulation/Model/Analysis.h>
 #include <OpenSim/Simulation/Model/Muscle.h>
 #include "osimAnalysesDLL.h"

OpenSim/Common/XMLDocument.cpp

@@ -66,8 +66,10 @@ using namespace std;
 // 30516 for GeometryPath default_color -> Appearance
 // 30517 for removal of _connectee_name suffix to shorten XML for socket, input
 // 40000 for OpenSim 4.0 release 40000
+// 40500 for OpenSim 4.5 release, moving 'GeometryPath' nodes under the 'path' 
+//       node for supporting generic path types.
 
-const int XMLDocument::LatestVersion = 40000;
+const int XMLDocument::LatestVersion = 40500;
 //=============================================================================
 // DESTRUCTOR AND CONSTRUCTOR(S)
 //=============================================================================

OpenSim/ExampleComponents/HopperDevice.h

@@ -101,7 +101,7 @@ class OSIMEXAMPLECOMPONENTS_API HopperDevice : public ModelComponent {
     void extendRealizeDynamics(const SimTK::State& s) const override {
         const auto& actuator = getComponent<PathActuator>(get_actuator_name());
         double level = fmin(1., getTension(s) / actuator.get_optimal_force());
-        actuator.getGeometryPath().setColor(s, SimTK::Vec3(level, 0.5, 0));
+        actuator.getPath().setColor(s, SimTK::Vec3(level, 0.5, 0));
     }
 
 }; // end of HopperDevice

OpenSim/Examples/ExampleHopperDevice/defineDeviceAndController.h

@@ -105,7 +105,7 @@ class Device : public ModelComponent {
     void extendRealizeDynamics(const SimTK::State& s) const override {
         const auto& actuator = getComponent<PathActuator>("cableAtoB");
         double level = fmin(1., getTension(s) / actuator.get_optimal_force());
-        actuator.getGeometryPath().setColor(s, SimTK::Vec3(0.1, level, 0.1));
+        actuator.getPath().setColor(s, SimTK::Vec3(0.1, level, 0.1));
     }
 
 }; // end of Device

OpenSim/Examples/ExampleHopperDevice/defineDeviceAndController_answers.h

@@ -154,7 +154,7 @@ class Device : public ModelComponent {
     void extendRealizeDynamics(const SimTK::State& s) const override {
         const auto& actuator = getComponent<PathActuator>("cableAtoB");
         double level = fmin(1., getTension(s) / actuator.get_optimal_force());
-        actuator.getGeometryPath().setColor(s, SimTK::Vec3(0.1, level, 0.1));
+        actuator.getPath().setColor(s, SimTK::Vec3(0.1, level, 0.1));
     }
 
 }; // end of Device

OpenSim/Examples/ExampleLuxoMuscle/LuxoMuscle_create_and_simulate.cpp

@@ -747,7 +747,6 @@ void createLuxoJr(OpenSim::Model& model){
                                             "back_extensor_right",
                                             back_extensor_F0, back_extensor_lm0,
                                             back_extensor_lts, pennationAngle);
-
     backExtensorRight->addNewPathPoint("back_extensor_right_origin", *chest,
                                       back_extensor_origin);
     backExtensorRight->addNewPathPoint("back_extensor_right_insertion", *back,

OpenSim/Simulation/Model/AbstractPath.cpp

@@ -0,0 +1,68 @@
+/* -------------------------------------------------------------------------- *
+ *                          OpenSim:  AbstractPath.cpp                        *
+ * -------------------------------------------------------------------------- *
+ * The OpenSim API is a toolkit for musculoskeletal modeling and simulation.  *
+ * See http://opensim.stanford.edu and the NOTICE file for more information.  *
+ * OpenSim is developed at Stanford University and supported by the US        *
+ * National Institutes of Health (U54 GM072970, R24 HD065690) and by DARPA    *
+ * through the Warrior Web program.                                           *
+ *                                                                            *
+ * Copyright (c) 2005-2023 Stanford University and the Authors                *
+ * Author(s): Nicholas Bianco, Joris Verhagen, Adam Kewley                    *
+ *                                                                            *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
+ * not use this file except in compliance with the License. You may obtain a  *
+ * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
+ *                                                                            *
+ * Unless required by applicable law or agreed to in writing, software        *
+ * distributed under the License is distributed on an "AS IS" BASIS,          *
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
+ * See the License for the specific language governing permissions and        *
+ * limitations under the License.                                             *
+ * -------------------------------------------------------------------------- */
+
+#include "AbstractPath.h"
+#include "Appearance.h"
+
+using namespace OpenSim;
+
+AbstractPath::AbstractPath() : ModelComponent() {
+    setAuthors("Nicholas Bianco, Joris Verhagen, Adam Kewley");
+
+    Appearance appearance;
+    appearance.set_color(SimTK::Gray);
+    constructProperty_Appearance(appearance);
+}
+
+AbstractPath::AbstractPath(AbstractPath const&) = default;
+
+AbstractPath::~AbstractPath() noexcept = default;
+
+AbstractPath& AbstractPath::operator=(const AbstractPath&) = default;
+
+AbstractPath::AbstractPath(AbstractPath&& other) noexcept = default;
+
+AbstractPath& AbstractPath::operator=(AbstractPath&& other) noexcept = default;
+
+// DEFAULTED METHODS
+const SimTK::Vec3& AbstractPath::getDefaultColor() const
+{
+    return get_Appearance().get_color();
+}
+
+void AbstractPath::setDefaultColor(const SimTK::Vec3& color)
+{
+    updProperty_Appearance().setValueIsDefault(false);
+    upd_Appearance().set_color(color);
+}
+
+double AbstractPath::getPreScaleLength(const SimTK::State&) const
+{
+    return _preScaleLength;
+}
+
+void AbstractPath::setPreScaleLength(const SimTK::State&,
+        double preScaleLength)
+{
+    _preScaleLength = preScaleLength;
+}