Class PhysicsSoftBody

All Implemented Interfaces:
Comparable<NativePhysicsObject>
Direct Known Subclasses:
ReducedDeformableBody

public class PhysicsSoftBody extends PhysicsBody
A collision object to simulate a soft body, based on Bullet's btSoftBody. It is modeled as a mesh of nodes. Unlike other collision objects, the CollisionShape is ignored and is typically null.
  • Field Details

    • logger2

      public static final Logger logger2
      message logger for this class
  • Constructor Details

    • PhysicsSoftBody

      public PhysicsSoftBody()
      Instantiate an empty soft body. The new body is not added to any physics space.
    • PhysicsSoftBody

      protected PhysicsSoftBody(boolean unused)
      Instantiate an uninitialized soft body, for internal use.
      Parameters:
      unused - to distinguish from the no-arg constructor
  • Method Details

    • addVelocity

      public void addVelocity(Vector3f velocity)
      Add velocity to this entire body.
      Parameters:
      velocity - the velocity to add (in physics-space coordinates, not null, unaffected)
    • addVelocity

      public void addVelocity(Vector3f velocity, int nodeIndex)
      Add velocity to the indexed node of this body.
      Parameters:
      velocity - the velocity to add (in physics-space coordinates, not null, unaffected)
      nodeIndex - which node to add it to (≥0, <numNodes)
    • appendFaces

      public void appendFaces(IndexBuffer nodeIndices)
      Append faces to this body. A Face is a triangle connecting 3 nodes.
      Parameters:
      nodeIndices - a face is created for every 3 indices in this buffer (not null, direct, size a multiple of 3)
    • appendLinks

      public void appendLinks(IndexBuffer nodeIndices)
      Append links to this body. A link is an interaction (or force) between 2 nodes.
      Parameters:
      nodeIndices - a link is created for each pair of indices in this buffer (not null, direct, size a multiple of 2)
    • appendNodes

      public void appendNodes(FloatBuffer nodeLocations)
      Append nodes to this body, each with mass=1. Nodes provide the shape of a soft body. Each node has its own location, velocity, mass, etcetera.
      Parameters:
      nodeLocations - a node is created for every 3 floats in this buffer (not null, direct, limit a multiple of 3)
    • appendTetras

      public void appendTetras(IndexBuffer tetrahedra)
      Append tetrahedra to this body. A tetrahedron defines a volume between 4 nodes.
      Parameters:
      tetrahedra - a tetrahedron is created for every 4 indices in this buffer (not null, direct, size a multiple of 4)
    • applyForce

      public void applyForce(Vector3f force)
      Apply a force that acts uniformly across the entire body.
      Parameters:
      force - the force to add (in physics-space coordinates, not null, unaffected)
    • applyForce

      public void applyForce(Vector3f force, int nodeIndex)
      Apply a force to the indexed node of this body.
      Parameters:
      force - the force to add (in physics-space coordinates, not null, unaffected)
      nodeIndex - which node to add it to (≥0, <numNodes)
    • applyRotation

      public void applyRotation(Quaternion rotation)
      Rotate this body.
      Parameters:
      rotation - the rotation to apply (not null, unaffected)
    • applyScale

      public void applyScale(Vector3f factors)
      Scale this body.
      Parameters:
      factors - the scale factor to apply to each axis (not null, unaffected)
    • applyTransform

      public void applyTransform(Transform transform)
      Transform this body.
      Parameters:
      transform - the transform to apply (not null, unaffected)
    • applyTranslation

      public void applyTranslation(Vector3f offset)
      Translate this body.
      Parameters:
      offset - the translation to apply to each axis (not null, unaffected)
    • clusterCenter

      public Vector3f clusterCenter(int clusterIndex, Vector3f storeResult)
      Copy the center location of the indexed cluster.
      Parameters:
      clusterIndex - which cluster (≥0, <numClusters)
      storeResult - storage for the result (modified if not null)
      Returns:
      a location vector (in physics-space coordinates, either storeResult or a new vector)
    • copyClusterCenters

      public FloatBuffer copyClusterCenters(FloatBuffer storeResult)
      Copy the center-of-mass locations of all clusters in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 floats per cluster (in physics-space coordinates, either storeResult or a new buffer)
    • copyClusterMasses

      public FloatBuffer copyClusterMasses(FloatBuffer storeResult)
      Copy the masses of all clusters in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing a float value per cluster (either storeResult or a new buffer)
    • copyClusterVelocities

      public FloatBuffer copyClusterVelocities(FloatBuffer storeResult)
      Copy the (linear) velocities of all clusters in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 floats per cluster (in physics-space coordinates, either storeResult or a new buffer)
    • copyFaces

      public IntBuffer copyFaces(IntBuffer storeResult)
      Copy the node indices of all faces in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 indices per face (either storeResult or a new buffer)
    • copyLinks

      public IntBuffer copyLinks(IntBuffer storeResult)
      Copy the node indices of all links in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 2 indices per link (either storeResult or a new buffer)
    • copyLocations

      public FloatBuffer copyLocations(FloatBuffer storeResult)
      Copy the locations of all nodes in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 floats per node (in physics-space coordinates, either storeResult or a new buffer)
    • copyMasses

      public FloatBuffer copyMasses(FloatBuffer storeResult)
      Copy the masses of all nodes in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing a float value per node (either storeResult or a new buffer)
    • copyNormals

      public FloatBuffer copyNormals(FloatBuffer storeResult)
      Copy the normal vectors of all nodes in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 floats per node (in physics-space coordinates, either storeResult or a new buffer)
    • copyTetras

      public IntBuffer copyTetras(IntBuffer storeResult)
      Copy the node indices of all tetrahedra in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 4 indices per tetrahedron (either storeResult or a new buffer)
    • copyVelocities

      public FloatBuffer copyVelocities(FloatBuffer storeResult)
      Copy the (linear) velocities of all nodes in this body.
      Parameters:
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing 3 floats per node (in physics-space coordinates, either storeResult or a new buffer)
    • countClusters

      public final int countClusters()
      Count the clusters in this body.
      Returns:
      the number of clusters (≥0)
    • countFaces

      public final int countFaces()
      Count the faces in this body.
      Returns:
      the number of faces (≥0)
    • countLinks

      public final int countLinks()
      Count the links in this body.
      Returns:
      the number of links (≥0)
    • countNodes

      public final int countNodes()
      Count the nodes in this body.
      Returns:
      the number of nodes (≥0)
    • countNodesInCluster

      public int countNodesInCluster(int clusterIndex)
      Count the nodes in the indexed cluster.
      Parameters:
      clusterIndex - which cluster (≥0, <numClusters)
      Returns:
      the number of nodes (≥0)
    • countPinnedNodes

      public final int countPinnedNodes()
      Count the pinned nodes in this body.
      Returns:
      the number of pinned nodes (≥0)
    • countTetras

      public final int countTetras()
      Count the tetrahedra in this body.
      Returns:
      the number of tetrahedra (≥0)
    • cutLink

      public boolean cutLink(int nodeIndex0, int nodeIndex1, float cutLocation)
      Cut a pre-existing link in this body. TODO clarify the semantics
      Parameters:
      nodeIndex0 - the index of a node in the link (≥0,<numNodes)
      nodeIndex1 - the index of the other node in the link (≥0,<numNodes)
      cutLocation - where to cut the link
      Returns:
      true if successful, otherwise false
    • generateBendingConstraints

      public void generateBendingConstraints(int numHops, SoftBodyMaterial material)
      Generate bending constraints based on hops in the adjacency graph. This may increase the number of links.
      Parameters:
      numHops - (in links, ≥2)
      material - the material for appending links (not null)
    • generateClusters

      public void generateClusters()
      Generate one cluster per tetrahedron (or one per face if there are no tetrahedra). Any pre-existing clusters are released.
    • generateClusters

      public void generateClusters(int k, int maxIterations)
      Generate clusters (K-mean). Any pre-existing clusters are released.
      Parameters:
      k - (≥1, <numNodes)
      maxIterations - the maximum number of iterations (>0, default=8192)
    • get

      public float get(Cluster parameter, int clusterIndex)
      Read the specified parameter of the indexed cluster.
      Parameters:
      parameter - which parameter to read (not null)
      clusterIndex - which cluster (≥0, <numClusters)
      Returns:
      the coefficient value
    • getSoftConfig

      public SoftBodyConfig getSoftConfig()
      Access the SoftBodyConfig of this body.
      Returns:
      the pre-existing instance (not null)
    • getSoftMaterial

      public SoftBodyMaterial getSoftMaterial()
      Access the Material of this body.
      Returns:
      the instance associated with this body (not null)
    • getWorldInfo

      public SoftBodyWorldInfo getWorldInfo()
      Access the world info.
      Returns:
      the pre-existing instance (not null)
    • isCollisionAllowed

      public boolean isCollisionAllowed(long pcoId)
      Test whether collisions are allowed between this body and the identified collision object. Disallowed collisions may result from anchors.
      Parameters:
      pcoId - the native ID of the other collision object (not zero)
      Returns:
      true if allowed, otherwise false
    • isEmpty

      public final boolean isEmpty()
      Test whether this body is empty.
      Returns:
      true if empty, otherwise false
    • isWorldInfoProtected

      public boolean isWorldInfoProtected()
      Test whether this body's world info should be replaced when added to a space.
      Returns:
      false if the info should be replaced, true if it should be preserved
    • listNodesInCluster

      public IntBuffer listNodesInCluster(int clusterIndex, IntBuffer storeResult)
      List all nodes in the indexed cluster.
      Parameters:
      clusterIndex - which cluster (≥0, <numClusters)
      storeResult - storage for the result (direct, modified) or null
      Returns:
      a direct buffer containing node indices (either storeResult or a new buffer)
    • margin

      public float margin()
      Read the collision margin of this body.
      Returns:
      the margin distance (in physics-space units, >0)
    • nodeLocation

      public Vector3f nodeLocation(int nodeIndex, Vector3f storeResult)
      Copy the location of the indexed node.
      Parameters:
      nodeIndex - which node (≥0, <numNodes)
      storeResult - storage for the result (modified if not null)
      Returns:
      a location vector (in physics-space coordinates, either storeResult or a new vector)
    • nodeMass

      public float nodeMass(int nodeIndex)
      Read the mass of the indexed node.
      Parameters:
      nodeIndex - which node to read (≥0, <numNodes)
      Returns:
      the mass of the node (≥0)
    • nodeNormal

      public Vector3f nodeNormal(int nodeIndex, Vector3f storeResult)
      Copy the normal vector of the indexed node.
      Parameters:
      nodeIndex - which node (≥0, <numNodes)
      storeResult - storage for the result (modified if not null)
      Returns:
      a normal vector (in physics-space coordinates, either storeResult or a new vector)
    • nodeVelocity

      public Vector3f nodeVelocity(int nodeIndex, Vector3f storeResult)
      Copy the velocity of the indexed node.
      Parameters:
      nodeIndex - which node (≥0, <numNodes)
      storeResult - storage for the result (modified if not null)
      Returns:
      a velocity vector (in physics-space coordinates, either storeResult or a new vector)
    • randomizeConstraints

      public void randomizeConstraints()
      Randomize constraints to reduce solver bias.
    • releaseAllClusters

      public void releaseAllClusters()
      Release all clusters.
    • releaseCluster

      public void releaseCluster(int clusterIndex)
      Release the indexed cluster.
      Parameters:
      clusterIndex - which cluster to release (≥0, <numClusters)
    • resetRestingLengths

      public void resetRestingLengths()
      Set the resting lengths of all links to their current lengths.
    • restingLengthsScale

      public float restingLengthsScale()
      Read the scale factor for resting lengths.
      Returns:
      the scale factor
    • set

      public void set(Cluster parameter, int clusterIndex, float value)
      Alter the specified parameter of the indexed cluster.
      Parameters:
      parameter - which parameter to alter (not null)
      clusterIndex - which cluster (≥0, <numClusters)
      value - the desired value
    • setMargin

      public final void setMargin(float margin)
      Alter the collision margin of this body.
      Parameters:
      margin - the desired margin distance (in physics-space units, >0)
    • setMassByArea

      public void setMassByArea(float totalMass)
      Alter the total mass for this body, distributing it based on the area of each face.
      Parameters:
      totalMass - the desired total mass (>0)
    • setMassByCurrent

      public void setMassByCurrent(float totalMass)
      Alter the total mass for this body, distributing it to nodes in proportion to their current masses.
      Parameters:
      totalMass - the desired total mass (>0, default=numNodes)
    • setMasses

      public void setMasses(FloatBuffer masses)
      Alter the masses of all nodes.
      Parameters:
      masses - a direct buffer containing the desired masses (not null, all elements ≥0)
    • setMassFromDensity

      public void setMassFromDensity(float density)
      Alter the total mass of this body, weighted by volume.
      Parameters:
      density - the desired density (>0)
    • setNodeMass

      public void setNodeMass(int nodeIndex, float mass)
      Alter the mass of the indexed node.
      Parameters:
      nodeIndex - which node to modify (≥0, <numNodes)
      mass - the desired mass (≥0, default=1)
    • setNodeVelocity

      public void setNodeVelocity(int nodeIndex, Vector3f velocity)
      Alter the velocity of the indexed node.
      Parameters:
      nodeIndex - which node to modify (≥0, <numNodes)
      velocity - the desired velocity vector (not null, unaffected)
    • setNormals

      public void setNormals(FloatBuffer normals)
      Alter the normal vectors of all nodes.
      Parameters:
      normals - a direct buffer containing the desired normals (in physics-space coordinates, not null, unaffected)
    • setPhysicsLocationDp

      public void setPhysicsLocationDp(Vec3d location)
      Directly relocate the center of this body's bounding box.
      Parameters:
      location - the desired location (in physics-space coordinates, not null, finite, unaffected)
    • setPose

      public void setPose(boolean setVolumePose, boolean setFramePose)
      Set the "default pose" (lowest energy state) of this body based on its current pose.
      Parameters:
      setVolumePose - true→alter the volume pose, false→ don't alter it
      setFramePose - true→alter the frame pose, false→ don't alter it
    • setProtectWorldInfo

      public void setProtectWorldInfo(boolean newState)
      Alter whether this body's world info should be replaced when the body gets added to a space.
      Parameters:
      newState - true to preserve the world info, false to allow it to be replaced (default=false)
    • setRestingLengthScale

      public void setRestingLengthScale(float scale)
      Alter the scale factor for resting lengths.
      Parameters:
      scale - the desired scale factor
    • setVelocities

      public void setVelocities(FloatBuffer velocities)
      Alter the velocities of all nodes.
      Parameters:
      velocities - a direct buffer containing the desired velocities (in physics-space coordinates, not null, unaffected)
    • setVelocity

      public void setVelocity(Vector3f velocity)
      Alter the velocities of all nodes to make them identical.
      Parameters:
      velocity - the desired velocity vector (in physics-space coordinates, not null, unaffected)
    • setVolumeDensity

      public void setVolumeDensity(float density)
      Set volume density (using tetrahedra) TODO clarify semantics
      Parameters:
      density - the desired density
    • setVolumeMass

      public void setVolumeMass(float mass)
      Set volume mass (using tetrahedra) TODO clarify semantics
      Parameters:
      mass - the desired mass
    • setWindVelocity

      public void setWindVelocity(Vector3f velocity)
      Alter the wind velocity.
      Parameters:
      velocity - the desired velocity vector (in physics-space coordinates, not null, unaffected)
    • setWorldInfo

      public void setWorldInfo(SoftBodyWorldInfo worldInfo)
      Replace the world info of this body.

      Invoke this method after adding the body to a space. Adding a body to a space may replace its world info.

      Parameters:
      worldInfo - the desired SoftBodyWorldInfo (not null, alias created)
    • volume

      public float volume()
      Calculate the volume of this body.
      Returns:
      the total volume (in cubic physics-space units, ≥0)
    • windVelocity

      public Vector3f windVelocity(Vector3f storeResult)
      Copy the wind velocity.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a velocity vector (in physics-space coordinates, either storeResult or a new vector)
    • destroySoftBody

      protected void destroySoftBody()
      Destroy the pre-existing btSoftBody (if any) except for its worldInfo.
    • initDefault

      protected void initDefault()
      Reinitialize the btSoftBody to the default values.
    • newEmptySoftBody

      protected void newEmptySoftBody()
      Create an empty btSoftBody for this PhysicsSoftBody, using the pre-existing worldInfo. The pre-existing btSoftBody (if any) will be destroyed.
    • setConfig

      protected void setConfig(SoftBodyConfig newConfig)
      Replace the configuration properties.
      Parameters:
      newConfig - the desired configuration
    • setWorldInfoInternal

      protected void setWorldInfoInternal(SoftBodyWorldInfo newInfo)
      Replace the world-dependent info.
      Parameters:
      newInfo - the desired info
    • boundingBox

      public BoundingBox boundingBox(BoundingBox storeResult)
      Calculate the axis-aligned bounding box for this body.
      Overrides:
      boundingBox in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a bounding box (in physics-space coordinates, either storeResult or a new instance)
    • getGravity

      public Vector3f getGravity(Vector3f storeResult)
      Copy this body's gravitational acceleration.
      Specified by:
      getGravity in class PhysicsBody
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an acceleration vector (in physics-space coordinates, either storeResult or a new vector, not null)
    • getMass

      public float getMass()
      Determine the total mass of this body.
      Specified by:
      getMass in class PhysicsBody
      Returns:
      the total mass (≥0)
    • getPhysicsLocation

      public Vector3f getPhysicsLocation(Vector3f storeResult)
      Locate the center of this body's axis-aligned bounding box.
      Overrides:
      getPhysicsLocation in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a location vector (in physics-space coordinates, either storeResult or a new instance, not null)
    • getPhysicsLocationDp

      public Vec3d getPhysicsLocationDp(Vec3d storeResult)
      Locate the center of this body's axis-aligned bounding box.
      Overrides:
      getPhysicsLocationDp in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a location vector (in physics-space coordinates, either storeResult or a new instance, not null, finite)
    • getPhysicsRotation

      public Quaternion getPhysicsRotation(Quaternion storeResult)
      Copy the orientation (rotation) of this body to a Quaternion.
      Overrides:
      getPhysicsRotation in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an identity quaternion (either storeResult or a new instance, not null)
    • getPhysicsRotationDp

      public Quatd getPhysicsRotationDp(Quatd storeResult)
      Copy the orientation (rotation) of this body to a Quatd.
      Overrides:
      getPhysicsRotationDp in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an identity quaternion (either storeResult or a new instance, not null)
    • getPhysicsRotationMatrix

      public Matrix3f getPhysicsRotationMatrix(Matrix3f storeResult)
      Copy the orientation of this body (the basis of its local coordinate system) to a Matrix3f.
      Overrides:
      getPhysicsRotationMatrix in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an identity matrix (either storeResult or a new instance, not null)
    • getPhysicsRotationMatrixDp

      public Matrix3d getPhysicsRotationMatrixDp(Matrix3d storeResult)
      Copy the orientation of this body (the basis of its local coordinate system) to a Matrix3d.
      Overrides:
      getPhysicsRotationMatrixDp in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      an identity matrix (either storeResult or a new instance, not null)
    • getScale

      public Vector3f getScale(Vector3f storeResult)
      Copy the scale factors of this object.
      Overrides:
      getScale in class PhysicsCollisionObject
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      the value (1,1,1) (either storeResult or a new vector)
    • setGravity

      public void setGravity(Vector3f acceleration)
      Alter this body's gravitational acceleration.

      Invoke this method after adding the body to a space. Adding a body to a space may override its gravity.

      Specified by:
      setGravity in class PhysicsBody
      Parameters:
      acceleration - the desired acceleration vector (in physics-space coordinates, not null, unaffected)
    • setMass

      public void setMass(float totalMass)
      Alter the total mass for this body, distributing it in proportion to the current mass of each node.
      Specified by:
      setMass in class PhysicsBody
      Parameters:
      totalMass - the desired total mass (>0, default=numNodes)
    • setPhysicsLocation

      public void setPhysicsLocation(Vector3f location)
      Directly relocate the center of this body's bounding box.
      Specified by:
      setPhysicsLocation in class PhysicsBody
      Parameters:
      location - the desired location (in physics-space coordinates, not null, finite, unaffected)