Shovel.h

Go to the documentation of this file.

/*
Copyright 2007-2025. Algoryx Simulation AB.
 
All AGX source code, intellectual property, documentation, sample code,
tutorials, scene files and technical white papers, are copyrighted, proprietary
and confidential material of Algoryx Simulation AB. You may not download, read,
store, distribute, publish, copy or otherwise disseminate, use or expose this
material unless having a written signed agreement with Algoryx Simulation AB, or having been
advised so by Algoryx Simulation AB for a time limited evaluation, or having purchased a
valid commercial license from Algoryx Simulation AB.
 
Algoryx Simulation AB disclaims all responsibilities for loss or damage caused
from using this software, unless otherwise stated in written agreements with
Algoryx Simulation AB.
*/
 
#pragma once
 
#include <agx/BitState.h>
#include <agxTerrain/PrimaryActiveZone.h>
#include <agxTerrain/SoilParticleAggregate.h>
#include <agxTerrain/SoilPenetrationResistance.h>
#include <agxTerrain/AggregateContactGenerator.h>
#include <agxTerrain/DeformController.h>
#include <agxTerrain/ShovelSettings.h>
#include <agxStream/Serializable.h>
#include <agx/Plane.h>
 
namespace agxCollide
{
  class Geometry;
  class Shape;
}
 
namespace agxTerrain
{
  //--- Forward declarations ---//
  class ShovelAggregateContactMaterialContainer;
  AGX_DECLARE_POINTER_TYPES(ShovelAggregateContactMaterialContainer);
  AGX_DECLARE_VECTOR_TYPES(ShovelAggregateContactMaterialContainer);
  class Terrain;
  class TerrainMaterial;
 
  using TerrainPtrVec = agx::VectorPOD<Terrain*>;
 
  AGX_DECLARE_POINTER_TYPES(Shovel);
  AGX_DECLARE_VECTOR_TYPES(Shovel);
 
  class AGXTERRAIN_EXPORT Shovel : public agxSDK::TerrainToolInstance
  {
  public:
    class ExcavationSettings;
    class Settings;
 
    static Shovel* find(const agxSDK::Simulation* simulation, const agx::Name& name);
 
    static Shovel* find(const agxSDK::Simulation* simulation, const agx::Uuid& uuid);
 
    static ShovelPtrVector findAll(const agxSDK::Simulation* simulation);
 
    Shovel( agx::RigidBody* shovelBody,
            const agx::Line& topEdge,
            const agx::Line& cuttingEdge,
            const agx::Vec3& toothDirection=agx::Vec3(0,0,0),
            agx::Real toothLength=0.15,
            ShovelDebugRenderSettings* settings = nullptr);
 
    Shovel( agx::RigidBody* shovelBody,
            const agx::Line& topEdge,
            const agx::Line& cuttingEdge,
            const agx::Line& teethEdge,
            ShovelDebugRenderSettings* settings = nullptr );
 
    enum class ExcavationMode : agx::UInt32
    {
      PRIMARY = 0,
      DEFORM_BACK = 1,
      DEFORM_RIGHT = 2,
      DEFORM_LEFT = 3
    };
 
    /*
    \return if the shovel is valid after construction. If it is not valid, it will not be possible to add the shovel to
    a simulation.
    */
    virtual bool isValid() const override;
 
    agx::RigidBody* getRigidBody() const;
 
    ExcavationSettings& getExcavationSettings(ExcavationMode mode);
 
    ShovelSettings* getSettings();
    const ShovelSettings* getSettings() const;
 
    AdvancedShovelSettings* getAdvancedSettings();
    AdvancedShovelSettings* getAdvancedSettings() const;
 
    const agx::Line& getTopEdge() const;
 
    agx::Line getTopEdgeWorld() const;
 
    const agx::Line& getCuttingEdge() const;
 
    agx::Line getCuttingEdgeWorld() const;
 
    agx::Vec3 getCuttingDirection() const;
 
    agx::Line getTeethEdgeWorld() const;
 
    agx::Line getTeethEdge() const;
 
    agx::Line getExcavationEdgeWorld() const;
 
    agx::Vec3 getToothOrCuttingDirection() const;
 
    agx::Vec3 getToothOrCuttingDirectionWorld() const;
 
    agx::Vec3 getCuttingDirectionWorld() const;
 
    agx::Vec3 getToothDirectionWorld() const;
 
    agx::Plane getSeparationPlatePlane() const;
 
    agx::Plane getTeethSeparationPlane() const;
 
    agx::Vec3 getBottomPlateDirection() const;
 
    agx::Vec3 getBottomPlateDirectionWorld() const;
 
    struct AGXTERRAIN_EXPORT TeethSettings
    {
      agx::Real   toothLength;
      agx::Real   toothMinRadius;
      agx::Real   toothMaxRadius;
      agx::UInt   numberOfTeeth;
    };
 
    agx::Real computeCuttingEdgeLength() const;
 
    void setExcavationSettings( ExcavationMode mode, ExcavationSettings excavationSettings );
 
    void setTopEdge(agx::Line topEdge);
 
    void setCuttingEdge(agx::Line cuttingEdge);
 
    void setTeethEdge( agx::Line teethEdge );
 
    void setCutTopPlane(agx::Plane cutTopPlane);
 
    const agx::Plane& getCutTopPlane() const;
 
    const agx::Plane& getTeethTopPlane() const;
 
    agx::Plane getCutTopPlaneWorld() const;
 
    agx::Plane getTeethTopPlaneWorld() const;
 
    agx::Plane getExcavationTopPlaneWorld() const;
 
    agx::Plane getExcavationTopPlane() const;
 
    agx::Plane getCurrentSeparationPlane( ExcavationMode mode ) const;
 
    bool getSoilPenetrationModel(agxTerrain::SoilPenetrationResistance::PenetrationModel& model) const;
 
    bool setSoilPenetrationModel(agxTerrain::SoilPenetrationResistance::PenetrationModel model);
 
    agx::Real getSecondarySeparationAngle() const;
 
    agx::Vec3 getSecondaryForwardVector() const;
 
    agx::Vec3 getSecondaryForwardVectorWorld() const;
 
    agx::Real getDeadLoadFraction() const;
 
    agx::Real getInnerSoilBulkVolume() const;
 
    agx::Real getTotalSoilBulkVolume( agx::Real packingFraction = 0.67 ) const;
 
    agx::Real getInnerSoilMass() const;
 
    agx::Real getTotalSoilMass() const;
 
    agx::Real getInnerParticleVolume() const;
 
    agx::Real getInnerVolume() const;
 
    SoilParticleVector getInnerSoilParticles() const;
 
    SoilParticleVector getTotalSoilParticles() const;
 
    agx::Real getInnerContactArea() const;
 
    void setEnable(bool enable);
 
    bool getEnable() const;
 
    ShovelAggregateContactMaterialContainer* getShovelTerrainContactMaterialContainer() const;
 
    const agxCollide::GeometryRefVector& getVoxelCollisionGeometries() const;
 
    void setConnectedShovel( Shovel* shovel );
 
    Shovel* getConnectedShovel();
 
  public:
 
    agx::Frame* getParentFrame() const;
 
    bool collisionGeometriesAreInsideTerrain(Terrain* terrain) const;
 
    const agxCollide::BoundingAABB& getCollisionBound() const;
 
    agx::Bool canDeformTerrain(Terrain* terrain) const;
 
    SoilParticleAggregate* getSoilParticleAggregate() const;
 
    SoilPenetrationResistance* getPenetrationResistance() const;
 
    PrimaryActiveZone* getActiveZone() const;
 
    AggregateContactGenerator* getAggregateContactGenerator() const;
 
    DeformController* getDeformController() const;
 
    agx::Material* getAggregateMaterial() const;
 
    void setEnableShovelTerrainGeometryContacts(Terrain* terrain, bool enable);
 
    void setEnableForTerrain(Terrain* terrain, bool enable);
 
    bool getEnableForTerrain(Terrain* terrain) const;
 
    bool setShovelAggregateContactMaterial( agx::ContactMaterial* contactMaterial,
                                            Shovel::ExcavationMode mode = Shovel::ExcavationMode::PRIMARY );
 
 
    agx::ContactMaterial* getShovelAggregateContactMaterial( Shovel::ExcavationMode mode = Shovel::ExcavationMode::PRIMARY ) const;
 
    const agx::RigidBody* getWedgeAggregate(Shovel::ExcavationMode excavationMode) const;
 
    agx::Real getAggregateTerrainContactDepth(Shovel::ExcavationMode excavationMode) const;
 
    const agx::Vector<agxCollide::BoundingAABB>& getForbiddenBounds();
 
    agxCollide::GeometryContactPtrVector getShovelAggregateContacts(Shovel::ExcavationMode excavationMode) const;
 
    agx::Real getAggregateTerrainContactArea(Shovel::ExcavationMode excavationMode) const;
 
    agx::Vec3 getSeparationContactForce() const;
 
    agx::Vec3 getSeparationNormalForce() const;
 
    agx::Vec3 getSeparationFrictionForce() const;
 
    agx::Vec3 getDeformationContactForce() const;
 
    agx::Vec3 getContactForce() const;
 
    agx::Vec3 getExcavationModeContactForce(Shovel::ExcavationMode excavationMode) const;
 
    bool getPenetrationForce(agx::Vec3& force, agx::Vec3& torque) const;
 
    agx::Vec3 getAggregateTerrainContactForce(Shovel::ExcavationMode excavationMode) const;
 
    agx::Vec3 getAggregateTerrainNormalForce(Shovel::ExcavationMode excavationMode) const;
 
    agx::Vec3 getAggregateTerrainTangentialForce(Shovel::ExcavationMode excavationMode) const;
 
 
    agxCollide::GeometryContactPtrVector getAggregateTerrainContacts(Shovel::ExcavationMode excavationMode) const;
 
    bool isDigging() const;
 
    agx::Real getDynamicMass() const;
 
    agx::Real getSoilAggregateMass(Shovel::ExcavationMode excavationMode) const;
 
    /*
    \return the active terrain that the shovel is acting on. If the shovel is currently not excavating, return nullptr.
    */
    Terrain* getActiveTerrain() const;
 
    /*
    \return if the shovel is currently active. The shovel is active either while interacting with a terrain, or if
    there are particels in the inner shape.
    */
    bool isActive() const;
 
    /*
    \return the current number of maximum soil aggregate contact points
    */
    size_t getMaximumNumberOfContactPoints();
 
    /*
    \return the current number of active soil aggregate
            contact points in the shovel.
    */
    size_t getNumberOfActiveContactPoints();
 
    class AGXTERRAIN_EXPORT ExcavationSettings
    {
    public:
      ExcavationSettings();
 
      ExcavationSettings(agx::UInt32 state);
 
      void setEnable(bool enable);
 
      void setEnableCreateDynamicMass(bool enable);
 
      void setEnableForceFeedback(bool enable);
 
      bool getEnable() const;
 
      bool getEnableForceFeedback() const;
 
      bool getEnableCreateDynamicMass() const;
 
      agx::UInt32 getState() const;
 
      void store( agxStream::OutputArchive& out ) const { m_excavationFlags.store( out ); }
      void restore( agxStream::InputArchive& in ) { m_excavationFlags.restore( in ); }
 
    private:
      enum StateFlags : agx::UInt32
      {
        ENABLED = 1 << 0,
        ENABLE_CREATE_DYNAMIC_MASS = 1 << 1,
        ENABLE_FORCE_FEEDBACK = 1 << 2
      };
      using Flags = agx::BitState<StateFlags, agx::UInt32>;
      Flags m_excavationFlags;
    };
 
    DOXYGEN_START_INTERNAL_BLOCK()
    agx::Plane calculateCutTopPlane();
 
    agx::Plane calculateTeethTopPlane();
 
    void setEdgesCodirectional();
 
    bool getShovelPlanes(agx::Plane& bottomPlane,
                         agx::Plane& backPlane,
                         agx::Plane& leftPlane,
                         agx::Plane& rightPlane) const;
 
    void removeTerrainShovelContacts(Terrain* terrain);
 
    /* Contact filtering for deformers */
    void removeTerrainShovelContactsDeformer(Terrain* terrain);
 
    agx::Real getSubmergedEdgeLength(const agx::Line& edge, const Terrain* terrain) const;
 
    agx::Vec3 getSurfaceTangentFromDeadLoad(agx::Real deadload) const;
 
    agx::Vec3 getCuttingEdgeVelocity();
 
    void setInnerContactArea( agx::Real contactArea );
 
    /* Set whether the settings are dirty. Prompts the shovel to update internal classes due to changed settings. */
    void setSettingsAreDirty(bool enable);
 
    bool getSettingsAreDirty() const;
 
    bool hasValidTeethVolume() const;
 
    bool hasValidToothSettings() const;
 
    void updateVoxelCollisionGeometries();
 
    agx::Physics::GranularBodySystem* getGranularBodySystem() const;
 
    virtual void onAssemblyAdd( agxSDK::Assembly* assembly ) override;
 
    agx::Vec3 getUpDirection() const;
 
    const agx::Vec3iVector& getVoxelsInActiveZoneLastTimeStep();
 
    void init();
 
    void updateTeethGeometry();
 
    ShovelDebugRenderSettings* getDebugRenderSettings() const { return m_debugRenderSettings; }
 
    void aggregatePreCollide();
 
    void updateAggregateCacheData();
 
    void debugRenderAggregatePositions();
 
    agx::Vec3 getGeneratedForwardVector() const { return m_forwardDirection; }
 
    agx::Vec3 getGeneratedBottomVector() const { return m_bottomPlateDirection; }
 
    TangentPatchData& getTangentPatchData() { return m_tangentData; }
 
    AGXSTREAM_DECLARE_SERIALIZABLE( agxTerrain::Shovel );
    DOXYGEN_END_INTERNAL_BLOCK()
 
  protected:
    Shovel();
 
    virtual ~Shovel();
 
    /* Default value for contact region threshold */
    agx::Real computeDefaultContactRegionThreshold() const;
 
    /*
    Creates a frame which uses the shovel body's frame as parent. Other shovel internals
    attaches to this frame to make sure they follow along the shovel rigid body.
    Requires that the shovel body isn't nullptr.
    */
    agx::Frame* createParentFrame();
 
    void initSoilAggregate();
 
    agxSDK::TerrainManager* getTerrainManager();
 
    TerrainPtrVec getTerrainsInSimulation();
 
    virtual void addNotification()  override;
 
    virtual void removeNotification() override;
 
    void setAggregateMaterial(agx::Material* material);
 
    void initalizeContactMaterialsForExistingTerrains(agxSDK::Simulation* simulation);
 
    /*
    Checks if all internal contact materials are correct.
    If there is an active terrain (ie, we are excavating or bulldozing)
    the contact material will be customized for that terrain.
    */
    void checkContactMaterials();
 
    virtual void preCollide() override;
 
    virtual void pre() override;
 
    virtual void post() override;
 
    virtual void last() override;
 
    void calculateDeadLoadFraction();
 
    /*
    Checks if there are particles inside the shovels collision geometries.
    */
    bool shovelHasParticles() const;
 
    void clearActiveZoneWedges() const;
 
    void calculateForbiddenBounds();
 
    static agx::UInt excavationModeToDeformerCollectionIndex(Shovel::ExcavationMode excavationMode);
 
  private:
      enum DeformSide
      {
          BACK = 0,
          LEFT = 1,
          RIGHT = 2
      };
 
  private:
    void createDeformers( const agx::Line& cuttingEdge,
                          const agx::Line& topEdge,
                          const agx::Vec3& forwardVector,
                          const agxCollide::GeometryRefVector& voxelCollisionGeometries );
 
    agx::Vec3Vector extractVertices(const agxCollide::GeometryRefVector& voxelCollisionGeometries);
 
    agx::Vec3 findEdgePoint( agx::Vec3Vector& vertices,
                             agx::Vec3 point,
                             agx::Plane& frontPlane,
                             agx::Plane& bottomPlane,
                             agx::Plane& sidePlane,
                             agx::Real tol );
 
    void addDeformers(const std::array<DeformerCollectionRef, 3>& deformers);
 
    bool shouldDeformMass(Terrain* terrain);
 
    agx::Vec3 computeBottomPlateDirection();
 
    agx::Vec3 computeForwardDirection();
 
    void constructAndAddDeformers();
 
  protected:
 
    ShovelDebugRenderSettingsRef                m_debugRenderSettings;
 
    ShovelSettingsRef                           m_shovelSettings;
 
    struct SoilPenetrationParameters
    {
      agx::Real depthThreshold;
      agx::Real forceScaling;
      agx::Real maxForce;
    };
 
    // Shovel bodies
    agx::RigidBodyRef         m_shovelBody;
    agx::FrameRef             m_parentFrame; /* Parent frame for shovel geometries synchronized with model center of shovel body. */
    TangentPatchData          m_tangentData;
 
    // Geometries used to find shovel-voxel collisions
    agxCollide::GeometryRefVector m_voxelCollisionGeometries;
 
    // Configuration:
    agx::Line                 m_cuttingEdge;
    agx::Line                 m_topEdge;
    agx::Plane                m_cutTopPlane;
    agx::Plane                m_teethTopPlane;
    agx::Vec3                 m_bottomPlateDirection;
    agx::Vec3                 m_forwardDirection;
 
    // Settings
    bool                                m_enabled;
    std::array< ExcavationSettings, 4 > m_excavationSettings;
 
    // Caching of dead load
    agx::Real                     m_deadLoadFraction;
    // Caching of inner contact area
    agx::Real                     m_innerContactArea;
 
    agx::Real                     m_deadLoadAngle=0;
 
    bool                          m_settingsAreDirty;
 
    Shovel*                       m_connectedShovel;
 
    ShovelAggregateContactMaterialContainerRef  m_shovelAggregateCMContainer;
    SoilParticleAggregateRef                    m_soilParticleAggregate;
    SoilPenetrationResistanceRef                m_penetrationResistance;
    // Voxel collision geometries HAVE to be calculated before creating the active zone otherwise it is not possible to create an inner shape.
    PrimaryActiveZoneRef                        m_activeZone;
    AggregateContactGeneratorRef                m_aggregateContactGenerator;
    std::array<DeformerCollectionRef, 3>        m_deformers;
    DeformControllerRef                         m_deformController;
 
    agx::MaterialRef                            m_aggregateMaterial;
    bool                                        m_isActive;
    Terrain*                                    m_activeTerrain;
    agx::Vector<agxCollide::BoundingAABB>       m_forbiddenBounds;
    agx::Vec3iVector                            m_voxelsInPrimaryActiveZoneLastTimeStep;
    agxCollide::BoundingAABB                    m_collisionBound;
  };
 
  class AGXTERRAIN_EXPORT ShovelAggregateContactMaterialContainer : public agx::Referenced, public virtual agxStream::Serializable
  {
  public:
    ShovelAggregateContactMaterialContainer();
 
    ~ShovelAggregateContactMaterialContainer();
 
    bool setContactMaterial(Shovel::ExcavationMode excavationMode, agx::ContactMaterial* contactMaterial);
 
    agx::ContactMaterial* getContactMaterial(Shovel::ExcavationMode excavationMode) const;
 
    DOXYGEN_START_INTERNAL_BLOCK()
    AGXSTREAM_DECLARE_SERIALIZABLE(agxTerrain::ShovelAggregateContactMaterialContainer);
    DOXYGEN_END_INTERNAL_BLOCK()
 
  private:
    agx::Vector< agx::ContactMaterialRef > m_contactMaterials;
  };
 
  class AGXTERRAIN_EXPORT ShovelUtils
  {
    friend class Shovel;
  public:
    /*
    \return true if the given rigidBody is part of a shovel.
    */
    static bool isRigidBodyShovel(const agx::RigidBody* rigidBody);
 
    /*
    \return true if the given geometry is part of shovels rigidBody.
    */
    static bool isGeometryShovel(const agxCollide::Geometry* geometry);
 
  protected:
    /*
    Set some properties on the rigid body to mark it as part of a shovel.
    Used in the shovel constructor.
    */
    static void setIsRigidBodyShovel(agx::RigidBody* rigidBody, bool enable);
  };
 
}