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& cuttingDirection,
            Shovel* connectedShovel=nullptr,
            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();
 
    AdvancedShovelSettings* getAdvancedSettings();
 
    const agx::Line& getTopEdge() const;
 
    agx::Line getTopEdgeWorld() const;
 
    const agx::Line& getCuttingEdge() const;
 
    agx::Line getCuttingEdgeWorld() const;
 
    const agx::Vec3& getCuttingDirection() const;
 
    agx::Vec3 getCuttingDirectionWorld() 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 setCuttingDirection(agx::Vec3 cuttingDirection);
 
    void setCutTopPlane(agx::Plane cutTopPlane);
 
    const agx::Plane& getCutTopPlane() const;
 
    agx::Plane getCutTopPlaneWorld() const;
 
    agx::Plane getCurrentSeparationPlane( ExcavationMode mode ) const;
 
    bool getSoilPenetrationModel(agxTerrain::SoilPenetrationResistance::PenetrationModel& model) const;
 
    bool setSoilPenetrationModel(agxTerrain::SoilPenetrationResistance::PenetrationModel model);
 
    agx::Vec3 getSecondaryCuttingDirection() const;
 
    agx::Real getSecondarySeparationAngle() 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;
 
  public:
 
    agx::Frame* getParentFrame() const;
 
    bool collisionGeometriesAreInsideTerrain(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;
 
    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();
 
    void setEdgesCodirectional();
 
    agx::Bool canDeformTerrain(Terrain* terrain) const;
 
    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 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;
 
    Shovel* getConnectedShovel();
 
    agx::Physics::GranularBodySystem* getGranularBodySystem() const;
 
    virtual void onAssemblyAdd( agxSDK::Assembly* assembly ) override;
 
    agx::Vec3 getUpDirection() const;
 
    const agx::Vec3iVector& getVoxelsInActiveZoneLastTimeStep();
 
    ShovelDebugRenderSettings* getDebugRenderSettings() const { return m_debugRenderSettings; }
 
    AGXSTREAM_DECLARE_SERIALIZABLE( agxTerrain::Shovel );
    DOXYGEN_END_INTERNAL_BLOCK()
 
  protected:
    Shovel();
 
    virtual ~Shovel();
 
    /* Make sure cutting direction is normalized */
    agx::Vec3 ensureCuttingDirectionIsNormalized(agx::Vec3 cuttingDirection);
 
    /* 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();
 
    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);
 
  protected:
    ShovelDebugRenderSettingsRef                m_debugRenderSettings;
 
    struct SoilPenetrationParameters
    {
      agx::Real depthThreshold;
      agx::Real forceScaling;
      agx::Real maxForce;
    };
 
    // Configuration:
    agx::RigidBodyRef         m_shovelBody;
    agx::Line                 m_cuttingEdge;
    agx::Line                 m_topEdge;
    agx::Vec3                 m_cuttingDirection;
    agx::Plane                m_cutTopPlane;
 
    // Settings
    bool                      m_enabled;
    ShovelSettingsRef         m_shovelSettings;
    std::array< ExcavationSettings, 4 > m_excavationSettings;
 
    // Caching of dead load
    agx::Real                 m_deadLoadFraction;
    // Caching of inner contact area
    agx::Real                 m_innerContactArea;
 
    agx::FrameRef m_parentFrame; /* Parent frame for shovel geometries synchronized with model center of shovel body. */
 
    // Geometries used to find shovel-voxel collisions
    agxCollide::GeometryRefVector m_voxelCollisionGeometries;
    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);
  };
}