Program Listing for File SubhingeBase.h

↰ Return to documentation for file (include/Karana/SOADyn/SubhingeBase.h)

/*
 * Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
 *
 * NOTICE TO USER:
 *
 * This source code and/or documentation (the "Licensed Materials") is
 * the confidential and proprietary information of Karana Dynamics Inc.
 * Use of these Licensed Materials is governed by the terms and conditions
 * of a separate software license agreement between Karana Dynamics and the
 * Licensee ("License Agreement"). Unless expressly permitted under that
 * agreement, any reproduction, modification, distribution, or disclosure
 * of the Licensed Materials, in whole or in part, to any third party
 * without the prior written consent of Karana Dynamics is strictly prohibited.
 *
 * THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
 * KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
 * FITNESS FOR A PARTICULAR PURPOSE.
 *
 * IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
 * INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
 * OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
 *
 * U.S. Government End Users: The Licensed Materials are a "commercial item"
 * as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
 * only as a commercial end item under the terms of this license.
 *
 * Any use of the Licensed Materials in individual or commercial software must
 * include, in the user documentation and internal source code comments,
 * this Notice, Disclaimer, and U.S. Government Use Provision.
 */

/**
 * @file
 * @brief Contains the declarations for the SubhingeBase class.
 */

#pragma once

#include "Karana/SOADyn/CoordBase.h"
#include "Karana/SOADyn/Defs.h"

namespace Karana::Dynamics {

    namespace kc = Karana::Core;
    namespace km = Karana::Math;

    class HingeBase;
    class CoordData;

    /**
     * @class SubhingeBase
     * @brief Represents the abstract base class for articulation subhinges
     *
     * This class is the base class for subhinges from which physical
     * and compound subhinge classes are derived. See \sref{subhinges_sec}
     * for more discussion about subhinges.
     */
    class SubhingeBase : public CoordBase {

        /* for access to _parent_hinge member */
        friend class HingeOnode;
        friend class PhysicalHinge;

        // For access to isOriented.
        friend class CompoundSubhinge;

      public:
        /**
         * @brief SubhingeBase destructor.
         */
        virtual ~SubhingeBase();

        /**
         * @brief Returns the type string of the object.
         *
         * @param brief if true, return the short form of the class type name, else the full type
         *        name
         * @return The type string.
         */
        std::string_view typeString(bool brief = true) const noexcept override = 0;

        /**
         * @brief Helper method to return the subhinge type
         *
         * @return the subhinge type
         */
        virtual SubhingeType subhingeType() const = 0;

        /**
         * @brief Helper method to return the string name for a SubhingeType subhinge type
         *
         * @param shtype the subhinge type
         * @return the subhinge type as a string
         */
        static std::string subhingeTypeString(SubhingeType shtype);

        /**
         * @brief Set the prescribed flag for the subhinge
         * @param flag the enable/disable flag
         */
        virtual void setPrescribed(bool flag) { _prescribed = flag; }

        /**
         * @brief Return the prescribed flag for the subhinge
         * @return the prescribed mode status
         */
        bool getPrescribed() const { return _prescribed; }

        /**
         * @brief Return the parent hinge for the subhinge
         * @return the PhysicalHinge parent hinge
         */
        const kc::ks_ptr<HingeBase> &parentHinge() const { return _parent_hinge; }

        /**
         * @brief Return the range limits matrix for this subhinge
         *
         * A NaN value indicates an undetermined limit, while infinite
         * value implies that the limit is unbounded.
         *
         * @return the range limits matrix
         */
        const km::Mat &getRangeLimits() const;

        /**
         * @brief Set the range limits matrix for a subhinge Q component
         *
         * A NaN value indicates an undetermined limit, while infinite
         * value implies that the limit is unbounded.
         *
         * @param limits the lower/upper range limits
         * @param offset the offset of the Q coordinate that this applies to
         *               e.g., 0 means these limits are for the first coordinate
         *               of the subhinge
         */
        void setRangeLimits(km::Vec limits, unsigned int offset);

      protected:
        /**
         * @brief Constructs a SubhingeBase.
         * @param nm the name for the subhinge
         * @param hge the parent hinge
         */
        SubhingeBase(std::string_view nm, kc::ks_ptr<HingeBase> hge);

      protected:
        /**
         * the parent hinge
         */
        kc::ks_ptr<HingeBase> _parent_hinge = nullptr;

        /**
         * flag indicating whether the subhinge is prescribed
         */
        bool _prescribed = false;

        /**
         * Matrix of nQx2 size with each row containing the range limits
           for each Q coordinate value for the subhinge. While joint
           limit values (for 1 dof physical subhinges) represent limits
           from the physical system. range limit values are used to
           track the range of coordinates values that can legally
           satisfy the loop constraints that the subhinge is involved
           in. These values are typically computed using the CK solver
           and stored here for subsequent use.

           The limits can vary when constraints come and go, and it is the
           responsibility of the application to update them if needed.

           A NaN value indicates an undetermined limit, while infinite
           value implies that the limit is unbounded.
         */
        km::Mat _range_limits;
    };

} // namespace Karana::Dynamics