TerrainMaterial.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/config/AGX_USE_AGXTERRAIN.h>
#include <agxTerrain/export.h>
#include <agx/Material.h>
#include <array>
 
namespace agxTerrain
{
  class Terrain;
  AGX_DECLARE_POINTER_TYPES(TerrainMaterial);
 
  class AGXTERRAIN_EXPORT TerrainMaterial : public agx::Referenced
  {
  public:
    AGX_DECLARE_POINTER_TYPES(BulkProperties);
    AGX_DECLARE_POINTER_TYPES(ParticleProperties);
    AGX_DECLARE_POINTER_TYPES(CompactionProperties);
    AGX_DECLARE_POINTER_TYPES(ExcavationContactProperties);
    AGX_DECLARE_POINTER_TYPES(TerramechanicsProperties);
 
  public:
    TerrainMaterial(const agx::String& name="");
 
    const agx::String& getName() const;
 
    void setName(const agx::String& name);
 
    const agx::String& getDescription() const;
 
    BulkProperties* getBulkProperties() const;
 
    CompactionProperties* getCompactionProperties() const;
 
    ParticleProperties* getParticleProperties() const;
 
    ExcavationContactProperties* getExcavationContactProperties() const;
 
    /*
    \return the soil properties for terramechanics.
    */
    TerramechanicsProperties* getTerramechanicsProperties() const;
 
 
    agx::Real getSoilPackingFraction() const;
 
    void setDescription(const agx::String& description );
 
    agx::String getLastError() const;
 
    void printParameters() const;
 
  public:
 
    class AGXTERRAIN_EXPORT BulkProperties : public agx::Referenced
    {
    public:
      BulkProperties(TerrainMaterial* terrainMaterial);
 
      agx::Real getDensity() const;
 
      agx::Real getMaximumDensity() const;
 
      agx::Real getYoungsModulus() const;
 
      agx::Real getPoissonsRatio() const;
 
      agx::Real getFrictionAngle() const;
 
      agx::Real getDilatancyAngle() const;
 
      agx::Real getCohesion() const;
 
 
      /*
      \return the tangential cohesion used between soil aggregate <-> terrain.
      */
      agx::Real getTangentialCohesion() const;
 
 
      agx::Real getSwellFactor() const;
 
      agx::Real getDeltaReposeAngle() const;
 
      void setDensity(agx::Real density);
 
      void setMaximumDensity(agx::Real maxDensity);
 
      void setYoungsModulus(agx::Real youngsModulus);
 
      void setPoissonsRatio(agx::Real poissonsRatio);
 
      void setFrictionAngle(agx::Real frictionAngle);
 
      void setDilatancyAngle( agx::Real dilatancyAngle );
 
      void setCohesion(agx::Real cohesion);
 
      /*
      Set the tangential cohesion (Pa) of the bulk material.
      \param tangentialCohesion - the specified tangential cohesion to set to the bulk material.
      */
      void setTangentialCohesion(agx::Real tangentialCohesion);
 
      void setSwellFactor(agx::Real swellFactor);
 
      void setDeltaReposeAngle(agx::Real deltaReposeAngle);
 
      AGXTERRAIN_STORE_RESTORE_INTERFACE;
 
    protected:
      virtual ~BulkProperties() {}
      void onChanged();
 
    public:
      agx::Real m_density;
      agx::Real m_maxDensity;
      agx::Real m_youngsModulus;
      agx::Real m_poissonsRatio;
      agx::Real m_frictionAngle;
      agx::Real m_cohesion;
      agx::Real m_tangentialCohesion;
      agx::Real m_dilatancyAngle;
      agx::Real m_swellFactor;
      agx::Real m_deltaReposeAngle;
 
      TerrainMaterial* m_terrainMaterial;
    };
 
 
 
    class AGXTERRAIN_EXPORT CompactionProperties : public agx::Referenced
    {
    public:
      CompactionProperties();
 
      agx::Real getHardeningConstantKE() const;
 
      agx::Real getHardeningConstantNE() const;
 
      agx::Real getPreconsolidationStress() const;
 
      agx::Real getBankStatePhi() const;
 
      agx::Real getCompressionIndex() const;
 
      agx::Real getCompactionTimeRelaxationConstant() const;
 
      agx::Real getStressCutOffFraction() const;
 
      agx::Real getAngleOfReposeCompactionRate() const;
 
      void setHardeningConstantKE(agx::Real k_e);
 
      void setHardeningConstantNE(agx::Real n_e);
 
      void setPreconsolidationStress(agx::Real preconsolidationStress);
 
      void setBankStatePhi(agx::Real phi0);
 
      void setCompressionIndex(agx::Real compressionIndex);
 
      void setCompactionTimeRelaxationConstant(agx::Real compactionTimeRelaxationConstant);
 
      void setStressCutOffFraction(agx::Real stressCutOffFraction);
 
      void setAngleOfReposeCompactionRate(agx::Real angleOfReposeCompactionRate);
 
      void setDilatancyAngleScalingFactor( agx::Real scalingFactor );
 
      agx::Real getDilatancyAngleScalingFactor() const;
 
      AGXTERRAIN_STORE_RESTORE_INTERFACE;
 
    protected:
      virtual ~CompactionProperties() {}
 
    private:
      agx::Real m_hardening_ke;
      agx::Real m_hardening_ne;
      agx::Real m_preconsolidationStress;
      agx::Real m_compressionIndex;
      agx::Real m_phi0;
      agx::Real m_compactionTimeRelaxationConstant;
      agx::Real m_stressCutOffFraction;
      agx::Real m_angleOfReposeCompactionRate;
      agx::Real m_dilatancyAngleScalingFactor;
    };
 
 
 
    class AGXTERRAIN_EXPORT ParticleProperties : public agx::Referenced
    {
    public:
      ParticleProperties(TerrainMaterial* terrainMaterial);
 
      agx::Real getParticleDensity() const;
 
      agx::Real getParticleYoungsModulus() const;
 
      agx::Real getParticleRestitution() const;
 
      agx::Real getParticleSurfaceFriction() const;
 
      agx::Real getParticleRollingResistance() const;
 
      agx::Real getParticleCohesion() const;
 
      agx::Real getParticleTerrainYoungsModulus() const;
 
      agx::Real getParticleTerrainRestitution() const;
 
      agx::Real getParticleTerrainSurfaceFriction() const;
 
      agx::Real getParticleTerrainRollingResistance() const;
 
      agx::Real getParticleTerrainCohesion() const;
 
      agx::Real getAdhesionOverlapFactor() const;
 
      void setParticleYoungsModulus(agx::Real youngsModulus);
 
      void setParticleRestitution(agx::Real restitution);
 
      void setParticleSurfaceFriction(agx::Real friction);
 
      void setParticleRollingResistance(agx::Real rollingResistance);
 
      void setParticleCohesion(agx::Real cohesion);
 
      void setParticleTerrainYoungsModulus(agx::Real youngsModulus);
 
      void setParticleTerrainRestitution( agx::Real restitution );
 
      void setParticleTerrainSurfaceFriction(agx::Real friction);
 
      void setParticleTerrainRollingResistance(agx::Real rollingResistance);
 
      void setParticleTerrainCohesion(agx::Real cohesion);
 
      void setAdhesionOverlapFactor( agx::Real adhesionOverlapFactor );
 
      AGXTERRAIN_STORE_RESTORE_INTERFACE;
 
    protected:
      virtual ~ParticleProperties() {}
      void onChanged();
 
    protected:
      struct ParticleParticleParameters
      {
        ParticleParticleParameters();
 
        agx::Real youngsModulus;
        agx::Real restitution;
        agx::Real surfaceFriction;
        agx::Real rollingResistance;
        agx::Real cohesion;
      };
 
      struct ParticleTerrainParameters
      {
        ParticleTerrainParameters();
 
        agx::Real youngsModulus;
        agx::Real restitution;
        agx::Real surfaceFriction;
        agx::Real rollingResistance;
        agx::Real cohesion;
      };
 
    protected:
      ParticleParticleParameters m_particleParticleParameters;
      ParticleTerrainParameters  m_particleTerrainParameters;
      agx::Real                  m_adhesionOverlapFactor;
 
      TerrainMaterial* m_terrainMaterial;
    };
 
  public:
    DOXYGEN_START_INTERNAL_BLOCK()
 
    
    void setLastError( const agx::String& errorString );
 
    void updateIfDirty( Terrain* terrain );
 
    bool isDirty() const;
 
    void setDirty(bool isDirty);
 
    agx::Real calculateAdhesionOverlap( Terrain * terrain, agx::Real adhesion );
 
    void synchronize(Terrain* terrain);
 
    AGXTERRAIN_STORE_RESTORE_INTERFACE;
    DOXYGEN_END_INTERNAL_BLOCK()
 
  protected:
    virtual ~TerrainMaterial();
 
    void updateParticleDensity( Terrain* terrain );
    void synchronizeBulkProperties( Terrain* terrain );
    void synchronizeParticleProperties( Terrain* terrain );
 
  private:
    agx::String                     m_name;
    agx::String                     m_description;
    agx::String                     m_lastError;
    BulkPropertiesRef               m_bulkProperties;
    ParticlePropertiesRef           m_particleProperties;
    CompactionPropertiesRef         m_compactionProperties;
    ExcavationContactPropertiesRef  m_excavationContactProperties;
    TerramechanicsPropertiesRef     m_terramechanicsProperties;
    bool                            m_isDirty;
  };
 
 
 
  class AGXTERRAIN_EXPORT TerrainMaterial::ExcavationContactProperties : public agx::Referenced
  {
  public:
    ExcavationContactProperties(TerrainMaterial* terrainMaterial);
 
    agx::Real getMaximumContactDepth() const;
 
    agx::Real getDepthDecayFactor() const;
 
    agx::Real getDepthIncreaseFactor() const;
 
    agx::Real getMaximumAggregateNormalForce() const;
 
    agx::Real getAggregateStiffnessMultiplier() const;
 
    agx::Real getExcavationStiffnessMultiplier() const;
 
    agx::Real getDepthAngleThreshold() const;
 
    void setAggregateStiffnessMultiplier(agx::Real stiffnessMultiplier);
 
    void setExcavationStiffnessMultiplier(agx::Real excavationStiffnessMultiplier);
 
    void setMaximumContactDepth(agx::Real maximumDepth);
 
    void setDepthDecayFactor(agx::Real depthDecay);
 
    void setDepthIncreaseFactor(agx::Real depthIncreaseFactor);
 
    void setMaximumAggregateNormalForce(agx::Real maximumAggregateForce);
 
    void setDepthAngleThreshold( agx::Real depthAngleThreshold );
 
    AGXTERRAIN_STORE_RESTORE_INTERFACE;
 
  protected:
    virtual ~ExcavationContactProperties();
 
  private:
    agx::Real m_maximumDepth;
    agx::Real m_depthDecayFactor;
    agx::Real m_depthIncreaseFactor;
    agx::Real m_maximumAggregateNormalForce;
    agx::Real m_aggregateStiffnessMultiplier;
    agx::Real m_excavationStiffnessMultiplier;
    agx::Real m_depthAngleThreshold;
    TerrainMaterial* m_terrainMaterial;
  };
 
 
  class AGXTERRAIN_EXPORT TerrainMaterial::TerramechanicsProperties : public agx::Referenced
  {
    public:
      TerramechanicsProperties();
 
      /*
      [-] The 'n_0' in n = n_0 + n_1 * slip_ratio, where 'n' is sinkage exponent
      */
      agx::Real getSinkageExponentParameterA() const;
 
      /*
      [-] The 'n_0' in n = n_0 + n_1 * slip_ratio, where 'n' is sinkage exponent
      */
      void setSinkageExponentParameterA(agx::Real v);
 
      /*
      [-] The 'n_1' in n = n_0 + n_1 * slip_ratio, where 'n' is sinkage exponent
      */
      agx::Real getSinkageExponentParameterB() const;
 
      /*
      [-] The 'n_1' in n = n_0 + n_1 * slip_ratio, where 'n' is sinkage exponent
      */
      void setSinkageExponentParameterB(agx::Real v);
 
      /*
      [m] The 'a_0' in K_x = a_0 + slip_angle * a_1, where tau_x = [c + sigma*tan(phi)][1-exp(-j_x/K_x)]
      */
      agx::Real getShearModulusTangentialParameterA() const;
      /*
      [m] The 'a_0' in K_x = a_0 + slip_angle * a_1, where tau_x = [c + sigma*tan(phi)][1-exp(-j_x/K_x)]
      */
      void setShearModulusTangentialParameterA(agx::Real v);
 
      /*
      [m] The 'a_1' in K_x = a_0 + slip_angle * a_1
      */
      agx::Real getShearModulusTangentialParameterB() const;
 
      /*
      [m] The 'a_1' in K_x = a_0 + slip_angle * a_1
      */
      void setShearModulusTangentialParameterB(agx::Real v);
 
      /*
      [m] The 'a_0' in K_y = a_0 + slip_angle * a_1, where tau_y = [c + sigma*tan(phi)][1-exp(-j_y/K_y)]
      */
      agx::Real getShearModulusLateralParameterA() const;
 
      /*
      [m] The 'a_0' in K_y = a_0 + slip_angle * a_1, where tau_y = [c + sigma*tan(phi)][1-exp(-j_y/K_y)]
      */
      void setShearModulusLateralParameterA(agx::Real v);
 
      /*
      [m] The 'a_1' in K_y = a_0 + slip_angle * a_1
      */
      agx::Real getShearModulusLateralParameterB() const;
 
      /*
      [m] The 'a_1' in K_y = a_0 + slip_angle * a_1
      */
      void setShearModulusLateralParameterB(agx::Real v);
 
      /*
      [N/m^(n+1)] The 'k_c' in p = (k_c/b + k_phi)z^n
      */
      agx::Real getCohesiveModulusBekker() const;
 
      /*
      [N/m^(n+1)] The 'k_c' in p = (k_c/b + k_phi)z^n
      */
      void setCohesiveModulusBekker(agx::Real v);
 
      /*
      [N/m^(n+2)] The 'k_phi' in p = (k_c/b + k_phi)z^n
      */
      agx::Real getFrictionalModulusBekker() const;
 
      /*
      [N/m^(n+2)] The 'k_phi' in p = (k_c/b + k_phi)z^n
      */
      void setFrictionalModulusBekker(agx::Real v);
 
      /*
      [-] The 'k_c_prime' in p = (c*k_c_prime + rho*g*b*k_phi_prime)(z/b)^n
      */
      agx::Real getCohesiveModulusReece() const;
 
      /*
      [-] The 'k_c_prime' in p = (c*k_c_prime + rho*g*b*k_phi_prime)(z/b)^n
      */
      void setCohesiveModulusReece(agx::Real v);
 
      /*
      [-] The 'k_phi_prime' in p = (c*k_c_prime + rho*g*b*k_phi_prime)(z/b)^n
      */
      agx::Real getFrictionalModulusReece() const;
 
      /*
      [-] The 'k_phi_prime' in p = (c*k_c_prime + rho*g*b*k_phi_prime)(z/b)^n
      */
      void setFrictionalModulusReece(agx::Real v);
 
      /*
      [-] The 'a_0' in theta_m = (a_0 + a_1*slip_ratio) * theta_f
      */
      agx::Real getMaximumNormalStressAngleParameterA() const;
 
      /*
      [-] The 'a_0' in theta_m = (a_0 + a_1*slip_ratio) * theta_f
      */
      void setMaximumNormalStressAngleParameterA(agx::Real v);
 
      /*
      [-] The 'a_1' in theta_m = (a_0 + a_1*slip_ratio) * theta_f
      */
      agx::Real getMaximumNormalStressAngleParameterB() const;
 
      /*
      [-] The 'a_1' in theta_m = (a_0 + a_1*slip_ratio) * theta_f
      */
      void setMaximumNormalStressAngleParameterB(agx::Real v);
 
      /*
      [-] The 'a_0' in theta_r = (a_0 + a_1*slip_ratio) * theta_f
      */
      agx::Real getRearAngleParameterA() const;
 
      /*
      [-] The 'a_0' in theta_r = (a_0 + a_1*slip_ratio) * theta_f
      */
      void setRearAngleParameterA(agx::Real v);
 
      /*
      [-] The 'a_1' in theta_r = (a_0 + a_1*slip_ratio) * theta_f
      */
      agx::Real getRearAngleParameterB() const;
 
      /*
      [-] The 'a_1' in theta_r = (a_0 + a_1*slip_ratio) * theta_f
      */
      void setRearAngleParameterB(agx::Real v);
 
    AGXTERRAIN_STORE_RESTORE_INTERFACE;
 
    protected:
      virtual ~TerramechanicsProperties() {}
 
    private:
      agx::Real m_sinkageExponentParameterA;
      agx::Real m_sinkageExponentParameterB;
      agx::Real m_shearModulusTangentialParameterA;
      agx::Real m_shearModulusTangentialParameterB;
      agx::Real m_shearModulusLateralParameterA;
      agx::Real m_shearModulusLateralParameterB;
      agx::Real m_cohesiveModulusBekker;
      agx::Real m_frictionalModulusBekker;
      agx::Real m_cohesiveModulusReece;
      agx::Real m_frictionalModulusReece;
      agx::Real m_maximumNormalStressAngleParameterA;
      agx::Real m_maximumNormalStressAngleParameterB;
      agx::Real m_rearAngleParameterA;
      agx::Real m_rearAngleParameterB;
  };
 
 
 
  inline TerrainMaterial::BulkProperties* TerrainMaterial::getBulkProperties() const
  {
    return m_bulkProperties;
  }
 
 
  inline TerrainMaterial::CompactionProperties* TerrainMaterial::getCompactionProperties() const
  {
    return m_compactionProperties;
  }
 
 
  inline TerrainMaterial::ParticleProperties* TerrainMaterial::getParticleProperties() const
  {
    return m_particleProperties;
  }
 
 
  inline TerrainMaterial::ExcavationContactProperties* TerrainMaterial::getExcavationContactProperties() const
  {
    return m_excavationContactProperties;
  }
 
  inline TerrainMaterial::TerramechanicsProperties* TerrainMaterial::getTerramechanicsProperties() const
  {
    return m_terramechanicsProperties;
  }
 
 
  inline agx::Real TerrainMaterial::BulkProperties::getDensity() const
  {
    return m_density;
  }
 
 
  inline agx::Real TerrainMaterial::BulkProperties::getMaximumDensity() const
  {
    return m_maxDensity;
  }
 
 
  inline agx::Real TerrainMaterial::BulkProperties::getYoungsModulus() const
  {
    return m_youngsModulus;
  }
 
 
  inline agx::Real TerrainMaterial::BulkProperties::getPoissonsRatio() const
  {
    return m_poissonsRatio;
  }
 
 
  inline agx::Real TerrainMaterial::BulkProperties::getFrictionAngle() const
  {
    return m_frictionAngle;
  }
 
  inline agx::Real TerrainMaterial::BulkProperties::getDilatancyAngle() const
  {
    return m_dilatancyAngle;
  }
 
  inline agx::Real TerrainMaterial::BulkProperties::getCohesion() const
  {
    return m_cohesion;
  }
 
  inline agx::Real TerrainMaterial::BulkProperties::getTangentialCohesion() const
  {
    return m_tangentialCohesion;
  }
 
  inline agx::Real TerrainMaterial::BulkProperties::getSwellFactor() const
  {
    return m_swellFactor;
  }
 
  inline agx::Real TerrainMaterial::BulkProperties::getDeltaReposeAngle() const
  {
    return m_deltaReposeAngle;
  }
 
  inline agx::Real TerrainMaterial::ParticleProperties::getAdhesionOverlapFactor() const
  {
    return m_adhesionOverlapFactor;
  }
 
  inline agx::Real TerrainMaterial::CompactionProperties::getDilatancyAngleScalingFactor() const
  {
    return m_dilatancyAngleScalingFactor;
  }
}