Terrain.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 <agxTerrain/AvalancheController.h>
#include <agxTerrain/PrimaryActiveZone.h>
#include <agxTerrain/TerrainMaterial.h>
#include <agxTerrain/Grid.h>
#include <agxTerrain/ColumnHeightGrid.h>
#include <agxTerrain/SoilPenetrationResistance.h>
#include <agxTerrain/TerrainGridControl.h>
#include <agxTerrain/deprecated/TerrainToolCollection.h>
#include <agxTerrain/TerrainPhysics.h>
#include <agxTerrain/TerrainMassOccupancyController.h>
#include <agxTerrain/TerrainMaterialController.h>
#include <agxTerrain/CompactionController.h>
#include <agxTerrain/TerrainContactGenerator.h>
#include <agxTerrain/SoilSimulationInterface.h>
#include <agxTerrain/SoilParticleStatistics.h>
#include <agxTerrain/TerrainMaterialLibrary.h>
#include <agxTerrain/TerrainDataAtlas.h>
#include <agxTerrain/TerrainProperties.h>
#include <agxTerrain/GroundCollapseController.h>
#include <agxTerrain/ForbiddenBound.h>
 
#include <agxSDK/TerrainInstance.h>
 
#include <agx/HashSet.h>
#include <agx/HighAccuracyTimer.h>
#include <agx/BitState.h>
#include <agx/IndexLambdaKernel.h>
 
#include <agxCollide/Plane.h>
#include <agxCollide/Geometry.h>
#include <agxCollide/HeightField.h>
#include <agxTerrain/VoxelGridUtils.h>
 
#include <agxTerrain/ExternalDeformer.h>
 
namespace agxTerrain
{
  class TerrainPager;
 
  typedef agx::Physics::GranularBodyPtr SoilParticlePtr;
  typedef agx::Physics::GranularBodyPtrVector SoilParticlePtrVector;
  typedef agx::HashSet<agx::Vec3i> VoxelIndexSet;
  typedef std::pair<SoilParticlePtr, agx::Real> ParticleWeightPair;
  typedef agx::Vector<ParticleWeightPair> ParticleWeightPairVector;
  typedef agx::HashTable<agx::Vec3i, ParticleWeightPairVector> IndexToParticleWeightPairVector;
  typedef agx::SetVector<agx::Vec2i> ModifiedVerticesSetVector;
  typedef agx::Vector<agx::Vec2i> ModifiedVerticesVector;
  typedef agx::Vector<std::pair<SoilParticlePtr, float>> ParticleDeltaVector;
  using TerrainIndexSet = agx::HashSet<agx::Vec2i>;
 
  AGX_DECLARE_POINTER_TYPES(Terrain);
  AGX_DECLARE_VECTOR_TYPES(Terrain);
 
  class AGXTERRAIN_EXPORT Terrain : public agxSDK::TerrainInstance
  {
  public:
    enum class MaterialType
    {
      TERRAIN,
      PARTICLE,
      AGGREGATE
    };
 
    enum class MassType
    {
      SOLID,
      PARTICLE,
      FLUID
    };
 
  public:
    static agx::Bool isTerrainGeometry( const agxCollide::Geometry* geometry );
 
    static agx::Bool getEnableKinematicForParticles( const agx::RigidBody* rb );
 
    static void setEnableKinematicForParticles( agx::RigidBody* rb, agx::Bool enable );
 
    static Terrain* find( const agxSDK::Simulation* simulation, const agx::Name& name );
 
    static Terrain* find( const agxSDK::Simulation* simulation, const agx::Uuid& uuid );
 
    static TerrainPtrVector findAll( const agxSDK::Simulation* simulation, const agx::Name& name );
 
    static TerrainPtrVector findAll( const agxSDK::Simulation* simulation );
 
  public:
    static Terrain* createFromHeightField(const agxCollide::HeightField* heightField, agx::Real maximumDepth);
 
    Terrain(size_t resolutionX, size_t resolutionY, agx::Real elementSize, agx::Real maximumDepth);
 
    Terrain(size_t resolutionX, size_t resolutionY, agx::Real elementSize,
            const agx::RealVector& heights, bool flipY, agx::Real maximumDepth);
 
    Terrain(size_t resolutionX, size_t resolutionY, agx::Real elementSize,
      const agx::RealVector& heights, const agx::RealVector& minimumHeights);
 
    void setCompaction( agx::Real compaction, bool replaceCompactedSoil = true ) const;
 
    void setTransform(const agx::AffineMatrix4x4& transform);
 
    agx::AffineMatrix4x4 getTransform() const;
 
    agx::AffineMatrix4x4 getInverseTransform() const;
 
    void setEnable( bool enable );
 
    bool getEnable() const;
 
    void setPosition(const agx::Vec3& position);
 
    agx::Vec3 getPosition() const;
 
    void setRotation(const agx::Quat& rotation);
 
    agx::Quat getRotation() const;
 
    agx::Vec3 transformPointToTerrain(const agx::Vec3 point) const;
 
    agx::Vec3 transformPointToVoxelSpace( const agx::Vec3 point ) const;
 
    agx::Vec3 transformPointToWorld(const agx::Vec3 point) const;
 
    agx::Vec3 transformVectorToTerrain(const agx::Vec3 vector) const;
 
    agx::Vec3 transformVectorToWorld(const agx::Vec3 vector) const;
 
    const agxCollide::HeightField* getHeightField() const;
 
 
    virtual agxCollide::Geometry* getGeometry() const override;
 
    const agxCollide::HeightField* getSoilParticleBoundedHeightField() const;
 
    void setDeformable( bool deformable );
 
    inline bool getDeformable() const;
 
    void setNoMergeEdgeMargin(size_t noMergeEdgeMargin);
 
    void setNoMerge(bool noMerge);
 
    bool getNoMerge();
 
    ForbiddenBound* addNoMergeZoneToGeometry( agxCollide::Geometry* geometry,
                                              const agxCollide::BoundingAABB& bound,
                                              const agx::AffineMatrix4x4& localTransform );
 
 
    agx::Real getTanReposeAngle(agx::Vec2i xy) const;
 
    const ModifiedVerticesVector& getModifiedVertices() const;
 
    const ModifiedVerticesVector& getModifiedParticleVertices() const;
 
    void removeModifiedParticleVertice(agx::Vec2i terrainIndex);
 
    const ModifiedVerticesVector& getParticleVertices() const;
 
    agx::Vec2 getSize() const;
 
    size_t getResolutionX() const;
 
    size_t getResolutionY() const;
 
    agx::Real getElementSize() const;
 
    size_t getMemoryUsage();
 
    agx::Real getMinimumAllowedHeight() const;
 
    bool getEnableMinimumHeights() const;
 
    void setEnableMinimumHeights(bool enable);
 
 
    agx::Vec3 getSurfacePosition(const agx::Vec2i& terrainIndex, bool includeSurfaceParticles = false) const;
 
    agx::Vec3 getSurfacePositionWorld(const agx::Vec2i& terrainIndex, bool includeSurfaceParticles = false) const;
 
    agx::Vec2i getClosestGridPoint(const agx::Vec3& worldPosition, bool clampToBound=false) const;
 
    agx::Bool projectPointToSurface(const agx::Vec3& worldPosition, agx::Vec3& result) const;
 
    agx::Bool projectPointToSurfaceInDirection( const agx::Vec3& worldPosition, const agx::Vec3& worldDirection, agx::Vec3& result ) const;
 
    bool isBorderIndex(const agx::Vec2i& terrainIndex) const;
 
    bool isIndexWithinBounds(const agx::Vec2i& terrainIndex) const;
 
    bool isWorldPositionWithinBounds(const agx::Vec3& position) const;
 
    bool isLocalPositionWithinBounds(const agx::Vec3& position) const;
 
    void setHeight(const agx::Vec2i& terrainIndex, agx::Real height);
 
    agx::Real getHeight(const agx::Vec2i& terrainIndex, bool includeSurfaceParticles = false) const;
 
    void setMinimumHeight(const agx::Vec2i& terrainIndex, agx::Real minimumHeight);
 
 
    agx::Real getMinimumHeight(const agx::Vec2i& terrainIndex) const;
 
    agx::Real calculateVolume() const;
 
    agx::Real calculateTotalSolidMass() const;
 
    agx::Real calculateTotalFluidMass() const;
 
    agx::Real calculateTotalDynamicMass() const;
 
    agx::Real calculateTotalMass() const;
 
 
    ShovelPtrVector getShovels() const;
 
    ExternalDeformerPtrVector getExternalDeformers() const;
 
 
    agx::Real getLastExcavatedVolume() const;
 
    bool hasOverlap(const agxCollide::Geometry* geometry) const;
 
    agx::Material* getMaterial( Terrain::MaterialType type = Terrain::MaterialType::TERRAIN ) const;
 
 
    void setMaterial(agx::Material* material, Terrain::MaterialType type = Terrain::MaterialType::TERRAIN);
 
 
    agx::Material* getAssociatedMaterial(TerrainMaterial* terrainMaterial) const;
 
 
    bool setAssociatedMaterial(TerrainMaterial* terrainMaterial, agx::Material* material);
 
 
    bool exchangeTerrainMaterial(TerrainMaterial* oldTerrainMaterial, TerrainMaterial* newTerrainMaterial);
 
    bool removeTerrainMaterial(TerrainMaterial* terrainMaterialToRemove);
 
    void clearTerrainMaterials(bool clearAddedMaterials = true);
 
 
    agx::ContactMaterial* getContactMaterial( Terrain::MaterialType type1, Terrain::MaterialType type2 );
 
    TerrainMaterial* getDefaultTerrainMaterial() const;
 
    TerrainMaterial* getTerrainMaterial() const;
 
 
    TerrainMaterial* getTerrainMaterial(agx::Vec3 position) const;
 
    void setTerrainMaterial( TerrainMaterial* terrainMaterial, agx::Material* material = nullptr );
 
    bool addTerrainMaterial(TerrainMaterial* terrainMaterial);
 
 
    int addTerrainMaterial(TerrainMaterial* terrainMaterial, agxCollide::Geometry* geometry);
 
    bool loadLibraryMaterial( const agx::String& materialName );
 
    static TerrainMaterial* getLibraryMaterial(const agx::String& materialName);
 
 
    static agx::StringVector getAvailableLibraryMaterials();
 
    bool loadMaterialFile( const agx::String& filename );
 
    static TerrainMaterial* getMaterialFromFile(const agx::String& filename);
 
    bool setHeights( const agx::RealVector& heights, bool flipY = false, bool resetCompaction = true );
 
    bool setMinimumHeights(const agx::RealVector& minimumHeights);
 
    agx::RealVector getMinimumHeights() const;
 
    bool addForbiddenBound( IForbiddenBound* bound );
 
    bool removeForbiddenBound( IForbiddenBound* bound );
 
    IForbiddenBoundPtrVector getForbiddenBounds();
 
    bool pointIsInsideForbiddenBounds(const agx::Vec3& positionWorld, bool onlyUserDefined = false );
 
    bool indexIsInsideForbiddenBounds( const agx::Vec3i& terrainIndex, bool onlyUserDefined = false );
 
    void convertToDynamicMassInShape(agxCollide::Shape* shape);
 
    bool removeVolumeInShape( agxCollide::Shape* shape );
 
    void triggerForceAvalancheAll();
 
    agx::RealVector getResizedHeightField(size_t factorX, size_t factorY) const;
 
    SoilSimulationInterface* getSoilSimulationInterface() const;
 
    TerrainGridControl* getTerrainGridControl() const;
 
    agx::Real getTotalSoilParticleMass() const;
 
    SoilParticleStatistics getSoilParticleStatistics() const;
 
    const TerrainContactRefVector& getTerrainContacts() const;
 
    TerrainContactRefVector* getTerrainContactsVector() const;
 
    TerrainContactPtrVector getTerrainContactsPtrVector() const;
 
    agx::Real getAverageSoilParticleRadius() const;
 
    void setProperties( TerrainProperties* properties );
 
    TerrainProperties* getProperties();
 
    TerrainProperties* getProperties() const;
 
    agx::RealVector getMaterialWeightsInLine( const agx::Line& line ) const;
 
    agx::RealVector getMaterialWeightsInGridPoints( const agx::Vec3iVector& gridPoints ) const;
 
    bool getIntersectingGridElements( agxCollide::Geometry* geometry,
                                      agx::Vec3iVector& gridPoints ) const;
 
    bool getIntersectingActiveGridElements( agxCollide::Geometry* geometry,
                                            agx::Vec3iVector& gridPoints,
                                            MassType massType,
                                            bool onlyMidpoint=false) const;
 
    float removeFluidMassInGeometry(agxCollide::Geometry* geometry, float fluidMass);
 
    float getParticleNominalRadius() const;
 
    size_t getNumSoilParticles() const;
 
    size_t getNumCreatedParticles() const;
 
    agx::Vec3 getUpDirection() const;
 
    agx::Real getVoxelArea() const;
 
    agx::Real getVoxelVolume() const;
 
    static agx::Real getTerrainParticlePackingRatio();
 
    bool hasMultipleTerrainMaterials() const;
 
 
    // --- DEPRECATED --- //
 
    AGX_DEPRECATED_FOR(2.40.0.0, agxSDK::Simulation::add)
    bool add(Shovel* shovel);
 
    AGX_DEPRECATED_FOR(2.40.0.0, agxSDK::Simulation::remove)
    bool remove(Shovel* shovel);
 
    AGX_DEPRECATED(2.40.0.0)
    deprecated::TerrainToolCollectionRefVector getToolCollections() const;
 
    AGX_DEPRECATED(2.40.0.0)
    deprecated::TerrainToolCollection* getToolCollection(const Shovel* shovel) const;
 
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getPenetrationForce)
    bool getPenetrationForce(const Shovel* shovel, agx::Vec3& force, agx::Vec3& torque) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getSeparationContactForce)
    agx::Vec3 getSeparationContactForce(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getSeparationNormalForce)
    agx::Vec3 getSeparationNormalForce(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getSeparationFrictionForce)
    agx::Vec3 getSeparationFrictionForce(const Shovel * shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getDeformationContactForce)
    agx::Vec3 getDeformationContactForce(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getExcavationModeContactForce)
    agx::Vec3 getExcavationModeContactForce(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getContactForce)
    agx::Vec3 getContactForce(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getShovelAggregateContacts)
    agxCollide::GeometryContactPtrVector getShovelAggregateContacts(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getDeadLoadFraction)
    agx::Real getLastDeadLoadFraction(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getInnerVolume)
    agx::Real getInnerVolume(const Shovel* shovel) const;
 
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::isDigging)
    bool isDigging(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getDynamicMass)
    agx::Real getDynamicMass(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getSoilAggregateMass)
    agx::Real getSoilAggregateMass(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, agxSDK::Simulation::contains)
    bool contains(const Shovel* shovel) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, ShovelUtils::isRigidBodyShovel)
    bool isRigidBodyShovel(const agx::RigidBody* body) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, ShovelUtils::isGeometryShovel)
    bool isGeometryShovel(const agxCollide::Geometry* geometry) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::setShovelAggregateContactMaterial)
    bool setShovelAggregateContactMaterial(Shovel* shovel,
      agx::ContactMaterial* contactMaterial,
      Shovel::ExcavationMode mode = Shovel::ExcavationMode::PRIMARY);
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getShovelAggregateContactMaterial)
    agx::ContactMaterial* getShovelAggregateContactMaterial(const Shovel* shovel,
      Shovel::ExcavationMode mode = Shovel::ExcavationMode::PRIMARY) const;
 
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getAggregateTerrainContactForce)
    agx::Vec3 getAggregateTerrainContactForce(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getAggregateTerrainNormalForce)
    agx::Vec3 getAggregateTerrainNormalForce(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getAggregateTerrainTangentialForce)
    agx::Vec3 getAggregateTerrainTangentialForce(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getAggregateTerrainContactArea)
    agx::Real getAggregateTerrainContactArea(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
    AGX_DEPRECATED_FOR(2.40.0.0, Shovel::getAggregateTerrainContacts)
    agxCollide::GeometryContactPtrVector getAggregateTerrainContacts(const Shovel* shovel, Shovel::ExcavationMode excavationMode) const;
 
 
    DOXYGEN_START_INTERNAL_BLOCK()
 
    AGXSTREAM_DECLARE_SERIALIZABLE( agxTerrain::Terrain );
 
    size_t getNumActiveVoxels() const;
 
    size_t getNumModifiedVoxels() const;
 
    bool verifyMassColumnIntegrity(const agx::Vec2i& terrainIndex) const;
 
    bool isVoxelIndexBelowMaximumDepth(const agx::Vec3i& index) const;
 
    bool isBoundaryDepthVoxel(const agx::Vec3i& index) const;
 
    agx::Line transformLineToTerrain(const agx::Line& line) const;
 
    agx::Line transformLineToVoxelSpace( const agx::Line& line ) const;
 
    agx::Line transformLineToWorld(const agx::Line& line) const;
 
    bool isVoxelIndexInsideGeometryBound(const agx::Vec3i& index) const;
 
    agx::AffineMatrix4x4 getVoxelSpaceTransform() const;
 
    bool isBorderIndexAndBordersLocked(const agx::Vec2i& terrainIndex) const;
 
    CompactionController* getCompactionController() const;
 
    TerrainDataAtlas* getTerrainDataAtlas() const;
 
    virtual void runBuildIslandsTask() override;
 
    void clearAllSoilParticles();
 
    agx::Real calculateTotalVoxelVolume() const;
 
    agx::Vec3 getNormalFromTerrainIndex( const agx::Vec2i& terrainIndex ) const;
 
    float addFluidMassToColumn(const agx::Vec2i& terrainIndex, float fluidMass) const;
 
    float removeFluidMassFromColumn(const agx::Vec2i& terrainIndex, float fluidMass);
 
    float addFluidMass(const agx::Vec3i& voxelIndex, float fluidMass) const;
 
    float removeFluidMass(const agx::Vec3i& voxelIndex, float fluidMass);
 
    agx::Real calculateFluidOccupancy() const;
 
    agx::Real getTotalSoilParticleOccupancy() const;
 
    agx::Vec3 getLocalPositionFromVoxelIndex(const agx::Vec3i& voxelIndex) const;
 
    agx::Vec3 getWorldPositionFromVoxelIndex(const agx::Vec3i& voxelIndex) const;
 
    agx::Vec3i getVoxelIndexFromLocalPosition(const agx::Vec3& position) const;
 
    inline agx::Vec3i getVoxelIndexFromGridPosition(agx::Vec3 position) const
    {
      return VoxelGridUtils::getVoxelIndexFromGridPosition(position, m_voxelSize);
    }
 
    inline agx::Vec2i getTerrainIndexFromGridPosition(agx::Vec3 position) const
    {
      agx::Vec3i vi = getVoxelIndexFromGridPosition(position);
      return agx::Vec2i(vi.x(), vi.y());
    }
 
    agx::Vec3i getVoxelIndexFromWorldPosition(const agx::Vec3& position) const;
 
    agx::Vec3i getSurfaceVoxelIndexFromTerrainIndex(const agx::Vec2i& terrainIndex) const;
 
    void setForbiddenVoxelsForDynamicMass(const agx::Vec3iVector& voxelIndices);
 
    bool getForbiddenVoxelsForDynamicMass(agx::Vec3iVector& voxelIndices) const;
 
    bool isForbiddenVoxelsForDynamicMass(const agx::Vec3i& voxelIndex) const;
 
    bool voxelContainsShovel(const agx::Vec3i& voxelIndex) const;
 
    bool hasCreatedParticle( agx::Physics::ParticlePtr particle ) const;
 
    bool hasSameParticleMaterial(agx::Physics::ParticlePtr particle) const;
 
    TerrainMassOccupancyController* getMassOccupancyController() const;
 
    TerrainMaterialController* getMaterialController() const;
 
 
    GroundCollapse::GroundCollapseController* getGroundCollapseController() const;
 
 
    void adjustFluidMassInGrid(agx::Vec3i binIndex, int binVoxels, float availableFluidMass, float remainingFluidMass);
 
    agx::Vec3iVector getVoxelsOccupiedByShovel(Shovel* shovel) const;
 
    agx::Vec3iVector getVoxelsOccupiedByDeformer(ExternalDeformer* deformer) const;
 
    bool isPointSubmerged( const agx::Vec3& point ) const;
 
    bool voxelHasParticles(const agx::Vec3i& voxelIndex) const;
 
    bool isForbiddenIndex(const agx::Vec3i& index);
 
    void addTerrainIndexToAvalanche(const agx::Vec2i& index);
 
    /*Get the lowest z-index allowed in the height field*/
    int getLowestAllowableVoxelIndexZ() const;
 
    /*Get the lowest z-index allowed at the specific index*/
    int getMinimumHeightVoxelIndexZ(const agx::Vec2i& index) const;
 
 
    agx::Vec3 constructVoxelFieldOffset() const;
 
    void setTerrainPager(agxTerrain::TerrainPager* pager);
 
    void setIsTerrainPagerTile(bool isPagerTile);
 
    bool getIsTerrainPagerTile() const;
 
    bool shouldUpdateTerrain() const;
 
    bool hasEnabledShovels() const;
 
    bool hasParticlesInTerrain() const;
 
    void debugRenderFluidMass();
 
    bool isSolidVoxel( const agx::Vec3i& index ) const;
 
    bool isActiveSolidVoxel( const agx::Vec3i& index ) const;
 
    void markIndexAsModified( const agx::Vec2i& terrainIndex );
 
    bool isSurfaceVoxel(const agx::Vec3i& index) const;
 
    const agx::AffineMatrix4x4& _getVoxelSpaceTransform() const;
 
    const agx::AffineMatrix4x4& _getInvVoxelSpaceTransform() const;
 
    const agx::AffineMatrix4x4& _getTransform() const;
 
    const agx::AffineMatrix4x4& _getInverseTransform() const;
 
    void debugRenderParticleHeightField( agx::Real sizeFactor = 0.8,
                                         const agxRender::Color& color = agxRender::Color::White() );
 
    bool isEdgeSubmerged(const agx::Line& edge) const;
 
    bool isEdgeSubmergedInSolid(const agx::Line& edge) const; //Is this method ever used?
 
    bool isEdgeSubmergedInHeightfield(const agx::Line& edge, const agxCollide::HeightField* heightfield) const;
 
    /*
    Updates the surface heightfield in the given indices.
 
    HeightField heights are calculated from the underlying occupancy grid.
    \param indices - the column indices to update heights in.
    */
    void updateSurfaceHeightFieldFromTerrainIndices(const agx::Vec2iVector& indices);
 
    DOXYGEN_END_INTERNAL_BLOCK()
 
  protected:
    Terrain();
 
    virtual void addNotification() override;
 
    virtual void removeNotification() override;
 
    virtual void preEveryStep() override;
 
    virtual void preCollide() override;
 
    virtual void pre() override;
 
    virtual void post() override;
 
    virtual void last() override;
 
 
    virtual void syncIfPager() override;
 
    void resetIndices();
 
  protected:
    typedef struct offsetIndexInfo
    {
      agx::UInt size;
      agx::UInt groundParticleIndex;
      agx::UInt stopMergeIndex;
      agx::UInt offset;
      agx::UInt currentIndex;
    } offsetIndexInfo;
 
    using GoToStopCondition = std::function<bool(const agx::Vec3i& index)>;
    using ParticleIslandVector = agx::Vector<agx::Vector<std::pair<agx::Vec3i, offsetIndexInfo>>>;
 
    bool isSolidBoundaryVoxel(const agx::Vec3i& index) const;
    bool isSubmergedVoxel(const agx::Vec3i& index) const;
    bool isFilledSolidVoxel(const agx::Vec3i& index) const;
    bool hasVoxelCompaction(const agx::Vec3i& index) const;
    bool isVoxelWithinTerrainIndexBounds(const agx::Vec3i& index) const;
    bool getSurfaceVoxel(const agx::Vec3i& voxelIndex, agx::Vec3i& result) const;
    bool findPathToSurfaceVoxel(const agx::Vec3i& startVoxel, std::deque<agx::Vec3i>& result);
    bool findSurfaceVoxel(const agx::Vec3i& index, agx::Vec3i& result) const;
    agx::Vec3i goToVoxelKernel(const agx::Vec3i& start, const GoToStopCondition& stopCondition) const;
    agx::Vec3i goToSurfaceVoxel(const agx::Vec3i& start) const;
    agx::Vec3i goToBoundaryVoxel(const agx::Vec3i& start) const;
    void updateSurfaceHeightFieldFromDirtyVoxels();
    void updateSurfaceHeightFieldFromVoxelIndices(const agx::Vec3iVector& updateIndices, bool updateParticleHeightField=true);
    void updateSurfaceHeightFieldFromVoxelIndices(const agxData::LocalVector<agx::Vec3i>& updateIndices);
    void updateSurfaceHeightFieldFromVoxelIndex(const agx::Vec3i& voxelIndex);
    void updateSurfaceHeightFieldFromHeightsTable( agx::HashTable<agx::Vec2i, std::pair<agx::Vec3i, agx::Real> >& table );
    void updateSurfaceHeightFieldFromIndicesAndHeights(agx::Vec2uVector& hfIndices, agx::RealVector& hfHeights);
 
    void traceGridSurfaceVoxel(const agx::Vec2i& terrainIndex, agx::Vec3i& surfaceVoxel) const;
    agx::Real traceGridSurfaceHeightFromVoxelIndex(const agx::Vec3i& index);
    /*
    Calculates height in the specified voxel from compaction data and voxel level.
    */
    agx::Real calculateSurfaceHeightFromVoxelIndex(const agx::Vec3i& voxelIndex);
    void initializeSurfaceHeightFieldFromVoxelGrid();
    void initVoxelStructureFromHeightField( bool adjustForCompaction = false );
    void convertVoxelsInActiveZonesToDynamicMass();
    bool shouldPrimaryActiveZoneRemoveMass(Shovel* shovel);
    bool shouldDeformerActiveZoneRemoveMass(Shovel* shovel, DeformerCollection* deformerCollection);
    bool shouldExternalDeformerActiveZoneRemoveMass(agx::RigidBody* deformerBody, DeformerCollection* deformerCollection);
    void convertRemovedOccupancyToDynamicMass();
    void createSoilParticles();
    agx::Vec3 getValidParticlePosition(const agx::Real radius, const agx::Vec3i& index, const agx::Vec3& pos);
    void addDirtyVoxelsToAvalanche();
    void removeSoilParticlesOutsideTerrainBounds();
    void updateTransformationFromParentBody();
    void storeModifiedTerrainIndex( const agx::Vec2i& terrainVertex );
    void addModifiedParticleTerrainIndex(const agx::Vec2i& terrainIndex);
    void updateIndicesForAvalanche(TerrainIndexSet& forbiddenVertices);
    agx::Real findNewHeightFromVoxelIndex(const agx::Vec3i& index);
 
    SoilParticlePtrVector calculateParticlesInContactWithSurfaceGraph(agxCollide::GeometryPtrVector& contactGeometries);
 
    bool _getIntersectingGridElements(
      BasicGrid* grid,
      agxCollide::Geometry* geometry,
      agx::Vec3iVector& gridPoints,
      bool isOccupied = true,
      bool onlyMidpoint = false) const;
 
    void sortParticlesIntoVoxels();
    void sortParticlesIntoColumns();
 
    TerrainIndexSet findTerrainIndices(agxTerrain::SoilParticlePtrVector& particles);
 
    /*
    For every column we have particles in, shoot a ray into space and find possible collisions with the geometries that are connected in the particle-surface graph.
    If there is a collision, save the position for filtering later.
    */
    void raytraceColumns( agxCollide::GeometryPtrVector geometries,
                          agx::HashTable <agx::Vec2i, agx::Vec4>& contactPositionTable,
                          const TerrainIndexSet& columnTerrainIndices,
                          bool parallelExecute);
 
    /*
    Filter away particles so the remaining particles all are below that columns contact position voxel.
    This prevents merging through geometries.
    */
    void filterParticlesAboveContactGeometryVoxels( agx::HashTable <agx::Vec2i, agx::Vec4>& contactPositionTable,
                                                    agxTerrain::SoilParticlePtrVector& particles);
 
    void debugRenderContactGeometryVoxels();
 
    agx::HashTable<agx::Vec3i, agx::UInt64Vector> sortParticlesIntoBins(int binVoxels);
 
    void preSortSynchronizeParticleHeightField();
    void postSortSynchronizeParticleHeightField();
 
    // Sampling method
    void sampleParticleMassVelocity();
 
    void preUpdateTerrainContacts();
    void postUpdateCompaction();
    void postUpdateGroundCollapse();
    bool isDirty();
    void markVoxelToAvalanche(const agx::Vec3i& changedVoxel);
    void updateOccupancyFromHeightChange(const agx::Vec2i& heightFieldIndex);
    void initializeTanReposeAngles();
    void updateTanReposeAngles();
    void avalanche();
    void computeForbiddenBounds();
    void initializeFromHeightField();
    void sanitizeMaxDepthData();
 
    // Resize soil particles
    void resizeSoilParticles();
    void computeParticleGrowthTables(const agx::UInt64Vector& particleIndices, ParticleDeltaVector& particles);
    void growParticlesFromFluidMass(agx::Vec3i binIndex, int binVoxels, float availableFluidMass, ParticleDeltaVector& particles);
    void growSmallParticlesFromParticleMass(ParticleDeltaVector& particles, float particleRadiusUpperLimit);
    void growLargeParticlesFromParticleMass(ParticleDeltaVector& particles, float particleRadiusUpperLimit);
 
    // Merge soil particles functions
    void mergeSoilParticlesAndFluidMass();
    void addNeighbours(agxData::LocalVector<agx::Vec3i>& indexQueue, agx::Vec3i index);
    bool mergeFluidMass();
    void createParticleIslands( ParticleIslandVector& particleIslands );
    void mergeParticleIslands( const ParticleIslandVector& particleIslands, agxData::LocalVector<agx::Vec3i>& mergedParticleIndices );
    void resizeOrRemoveParticles( const agx::HashTable<SoilParticlePtr, std::array<agx::Real, 2>>& particlesToUpdate );
    agx::Real getMergeSpeedSquared() const;
 
    // Merge to excavation edge functions
    void mergeSoilToExcavationEdge();
    agx::Vec3iVector mergeSoilInColumnToVoxel(agx::Vec3i topVoxel, size_t numVoxelsToSurfaceThreshold, agx::Plane cuttingPlane);
    float convertParticlesToSolidMass(agx::Vec3i voxel, ParticleWeightPairVector particles, float occupancyToRemove,  agx::Vec3iVector& changedIndices);
    void moveParticlesToSurface(agx::Vec3iVector changedVoxelIndices);
 
    // Step fluid mass
    void stepFluidMass();
    void calculateFluidMassTransport(agx::HashTable<agx::Vec3i, float>& fluidMassTable);
    void applyFluidMassChanges(agx::HashTable<agx::Vec3i, float>& fluidMassTable);
    void enforceIncompressibilityColumnwise();
    // \todo?
    //agx::Vec3f getVoxelVelocity(const agx::Vec3i& voxelIndex, agx::HashTable<agx::Vec3i, size_t>& shovelVoxels);
    void createFluidMassInVoxel(const agx::Vec3i& voxelIndex, agx::Real32 amount);
    void createFluidMassOnTerrainSurface(const agx::Vec2i& terrainIndex, int surfaceVoxelOffset, agx::Real32 amount);
 
    // Conversion functions for particle radius and general occupancy
    float convertParticleRadiusToOccupancy(float radius) const;
    float convertOccupancyToParticleRadius(float occupancy) const;
    float getDynamicMassCompaction(const agx::Vec3i& voxelIndex) const;
    bool particleIslandShouldMerge(const agx::Vector<std::pair<agx::Vec3i, offsetIndexInfo>>& island);
    bool voxelColumnHasParticles(const agx::Vec2i& vertex) const;
 
    template <class F>
    void iterateOverSolidVoxels( F&& func ) const;
 
    // TerrainMaterial bookkeeping functions
    void removeEmptyTerrainMaterialVoxels();
 
    void calculateShovelVoxelIntersection();
 
    agx::HashVector<agx::Vec2i, agx::Int> getShovelHeightPerColumn();
 
    agx::Real convertFluidOccupancyToMass(agx::Real occupancy) const;
    agx::Real convertFluidMassToOccupancy(agx::Real mass) const;
 
    agx::Real generateRandomNumber();
    agx::Vec3 generateRandomSoilParticlePositionPerturbation(agx::Real maxDelta);
    agx::Quat generateRandomSoilParticleRotation();
 
    void debugRenderForbiddenBounds();
 
    AvalancheController* getAvalancheController() const;
 
    agx::Bool isIndexWithinBoundsIssueWarning( const agx::Vec2i& terrainIndex ) const;
 
    void renderVoxelAABB(agx::Vec3i index, agx::Vec4f color);
 
    agx::TaskGroupRef createTask_preCollide();
    void initBuildIslandTask();
    void updateInternalTransforms();
 
    void updateCachedMassProperties();
 
    void moveEntityDataToCurrentThread();
 
    void sanityCheckHeightFieldAgainstMaxDepth();
 
    friend class AvalancheController;
    friend class SoilSimulationInterface;
    friend class TerrainMaterial;
    friend class SoilParticleAggregate;
    friend class TerrainGridControl;
    friend class TerrainMassOccupancyController;
    friend class TerrainMaterialController;
    friend class CompactionController;
    friend class TerrainPhysics;
    friend class TerrainCache;
    friend class TerrainWheelDeformer;
 
  protected:
    virtual ~Terrain();
 
    Terrain(agxCollide::HeightField* heightField, agx::Real maximumDepth);
 
  private:
    using BoundingAABBVector             = agx::Vector<agxCollide::BoundingAABB>;
    using VoxelIndexOffsetIndexInfoTable = agx::HashTable<agx::Vec3i, offsetIndexInfo>;
 
  private:
    DOXYGEN_START_INTERNAL_BLOCK()
    friend class agx::InternalData;
    agx::Referenced* getInternalData() const;
 
    void setInternalData( agx::Referenced* data );
    DOXYGEN_END_INTERNAL_BLOCK()
 
  private:
    agxCollide::HeightFieldRef                m_surfaceHeightField;
    agxCollide::HeightFieldRef                m_particleHeightField;
    agx::Real                                 m_voxelSize;
    TerrainPropertiesRef                      m_properties;
    agx::UniformRealGenerator                 m_generator;
    float                                     m_nominalSoilParticleRadius;
 
    agxCollide::GeometryRef                   m_surfaceGeometry;
    agx::AffineMatrix4x4                      m_transform;
    agx::AffineMatrix4x4                      m_invTransform;
    agx::AffineMatrix4x4                      m_voxelSpaceTransform;
    agx::AffineMatrix4x4                      m_invVoxelSpaceTransform;
    agx::Vec3                                 m_voxelFieldOffset;
 
    TerrainDataAtlasRef                         m_terrainDataAtlas;
    TerrainMassOccupancyControllerRef           m_massOccupancyController;
    TerrainMaterialControllerRef                m_materialController;
    CompactionControllerRef                     m_compactionController;
    TerrainContactGeneratorRef                  m_terrainContactGenerator;
    AvalancheControllerRef                      m_avalancheController;
    SoilSimulationInterfaceRef                  m_soilSimulationInterface;
    TerrainGridControlRef                       m_terrainGridInterface;
    GroundCollapse::GroundCollapseControllerRef m_collapseController;
 
    agx::MaterialRef                          m_particleMaterial;
    agx::MaterialRef                          m_aggregateMaterial;
 
    agx::ContactMaterialRef                   m_terrainParticleContactMaterial;
    agx::ContactMaterialRef                   m_terrainAggregateContactMaterial;
    agx::ContactMaterialRef                   m_particleParticleContactMaterial;
 
    AvalancheController::TerrainIndexSet      m_terrainIndicesToAvalanche;
 
    size_t                                    m_noMergeEdgeMargin;
    bool                                      m_noMerge;
    BoundingAABBVector                        m_forbiddenBounds;
    agx::HashTable<agx::Vec3i, Shovel*>       m_voxelIndexToShovelPtr;
    agx::HashTable<agx::Vec3i, ExternalDeformer*>  m_voxelIndexToExternalDeformerPtr;
    agx::HashTable<Shovel*, agx::Vec3iVector> m_voxelsInPrimaryActiveZoneLastTimeStep;
    agx::Vec3iVector                          m_dirtyVoxelIndices;
    agx::Real32Vector                         m_removedOccupancy;
    agx::Real                                 m_lastRemovedVolume;
    VoxelIndexSet                             m_voxelHasCreatedParticle;
    VoxelIndexSet                             m_forbiddenVoxelsForDynamicMass;
    TerrainIndexSet                           m_mergedTerrainVertices;
    ModifiedVerticesSetVector                 m_modifiedVoxelColumns;
    ModifiedVerticesSetVector                 m_modifiedTerrainVertices;
    ModifiedVerticesSetVector                 m_modifiedParticleVertices;
    ModifiedVerticesSetVector                 m_particleTerrainVertices;
 
    size_t                                    m_numCreatedParticles;
    float                                     m_averageSoilParticleRadius;
 
    // Sort particles into voxels
    VoxelIndexOffsetIndexInfoTable            m_voxelParticleOffsetTable;
    ParticleWeightPairVector                  m_voxelParticleWeightPairVector;
 
    // Sort particles into columns
    agx::IndexVector                          m_particlesInContactWithSurface;
    agx::HashTable <agx::Vec2i, agx::Vec4>    m_contactPositionTable;
 
    VoxelIndexOffsetIndexInfoTable            m_columnParticleOffsetTable;
    ParticleWeightPairVector                  m_columnParticleWeightPairVector;
 
    agx::HashTable<agx::Vec2i, agx::Real>     m_columnParticleHeight;
    agx::HighAccuracyTimer                    m_timer;
 
    agx::IndexLambdaKernelRef                 m_indexKernel;
 
    bool                                      m_isTerrainPagerTile;
    agxTerrain::TerrainPager*                 m_terrainPager;
    bool                                      m_enable;
 
    agx::RealVector                           m_tanReposeAngles;
 
    // !HACK! !BEWARE! Islands partitioning
    // The build islands task is not executed when using PPGS.
    // No island partitioning means no parallelization of solving the rigid body system.
    // However, we still need islands in Terrain to determine which particles are in contact with the ground.
    // Thus, we manually load and execute the task in Terrain.
    // The task is loaded and bound for each Terrain that is added but is only executed once by agxSDK::Simulation.
    // The task is executed using the runBuildIslandsTask() method.
    agx::TaskRef m_buildIslandsTask;
    agx::TaskGroupRef m_preCollideUpdateTask;
    agx::TaskRef m_sortParticlesToVoxelsTask;
    agx::TaskRef m_sortParticlesToColumnsTask;
    agx::TaskRef m_calculateShovelVoxelIntersection;
    agx::TaskRef m_convertSolidToDynamicMassTask;
 
    agx::ParallelTaskRef m_updateHeightfieldsTask;
    agx::Job             m_updateHeightfieldsJobs[2];
    agx::ParallelTaskRef m_voxelCollisionTask;
    agx::ParallelTaskRef m_geometryFilterTask;
 
    agxTerrain::IForbiddenBoundRefVector      m_userForbiddenBounds;
    agxTerrain::IForbiddenBoundRefVector      m_tempForbiddenBounds;
 
    bool                                      m_enableFluidMerge; // Only used for testing. Should not be serialized.
 
    agx::Vector<agxCollide::ShapeRef> m_userInputFailureShapes;
 
    agx::ref_ptr<agx::Referenced> m_internalData;
 
    ShovelRefVector m_restoredShovelsFromToolCollection; // Used for restoring old terrains. Should not be serialized.
    ShovelPtrVector m_restoredDisableFlagFromToolCollection; // Used for restoring old terrains. Should not be serialized.
  };
 
 
  inline TerrainDataAtlas* Terrain::getTerrainDataAtlas() const
  {
    return m_terrainDataAtlas;
  }
 
  inline TerrainMaterial* Terrain::getDefaultTerrainMaterial() const
  {
    return m_materialController->getDefaultTerrainMaterial();
  }
 
 
  inline TerrainMaterial* Terrain::getTerrainMaterial() const
  {
    return m_materialController->getDefaultTerrainMaterial();
  }
 
 
  inline TerrainMaterial* Terrain::getTerrainMaterial(agx::Vec3 position) const
  {
    auto voxelIndex = getVoxelIndexFromWorldPosition(position);
    return m_materialController->getTerrainMaterial(voxelIndex);
  }
 
 
  inline size_t Terrain::getResolutionX() const
  {
    return m_surfaceHeightField->getResolutionX();
  }
 
 
  inline size_t Terrain::getResolutionY() const
  {
    return m_surfaceHeightField->getResolutionY();
  }
 
 
  inline agx::Real Terrain::getElementSize() const
  {
    return m_voxelSize;
  }
 
 
 
  inline const agx::AffineMatrix4x4& Terrain::_getVoxelSpaceTransform() const
  {
    return m_voxelSpaceTransform;
  }
 
 
 
  inline const agx::AffineMatrix4x4& Terrain::_getInvVoxelSpaceTransform() const
  {
    return m_invVoxelSpaceTransform;
  }
 
 
 
  inline const agx::AffineMatrix4x4& Terrain::_getTransform() const
  {
    return m_transform;
  }
 
 
 
  inline const agx::AffineMatrix4x4& Terrain::_getInverseTransform() const
  {
    return m_invTransform;
  }
 
 
  inline agx::Vec3i Terrain::getSurfaceVoxelIndexFromTerrainIndex(const agx::Vec2i& terrainIndex) const
  {
    auto solidGrid = static_cast<ColumnHeightGrid*>(m_terrainDataAtlas->getGridMassOccupancyData(TerrainDataAtlas::MassType::SOLID));
    int voxelHeight = solidGrid->getSurfaceHeightIndex(terrainIndex);
 
    return agx::Vec3i( terrainIndex.x(), terrainIndex.y(), voxelHeight);
  }
 
  inline bool Terrain::getIsTerrainPagerTile() const
  {
    return m_isTerrainPagerTile;
  }
 
  inline bool Terrain::getDeformable() const
  {
    return m_properties->getEnableDeformation();
  }
 
 
 
  inline bool Terrain::getEnableMinimumHeights() const
  {
    return m_terrainDataAtlas->getEnableMinimumHeights();
  }
 
 
  inline void Terrain::setEnableMinimumHeights(bool enable)
  {
    m_terrainDataAtlas->setEnableMinimumHeights(enable);
  }
}