Bullet

# World
World configs the solver for this simulation scene. There are two kinds of world listed as the fowllowing.

## BulletMakeWorld
This node is for rigid body object simulation.
### Output: 
`world`: Bullet world
## BulletMultiBodyWorld
This node is for simulating articulated object with multiple parts. Rigidbody objects can also be loaded into this scene.
### Output: 
`world`: Multibody world

## BulletSetWorldGravity
By default, there is no gravitational force enabled. setGravity lets you set the default gravity force for all objects.
### Input:
`world`: Connected with the node for setting the world.
`gravity`: (`NumericVec3`) Set gravity force along XYZ world axis
### Output:
`world`: The world with gravity.

## BulletSetMultiBodyWorldGravity
### Input:
`world`: Connected with the node for setting the world.
`gravity`: (`NumericVec3`) Set gravity force along XYZ world axis
### Output:
`world`: The world with gravity.

# Transform
## BulletMakeTransform
### Input:
`translate`: (`vec3`)
`rotation`: (`vec3`, `vec4`) There are two kinds of rotation. If input is `vec3`, the rotation format is euler angle in ypr. If input is `vec4`, it is quaternion.
### Output:
`trans`: A struct for transform in Bullet simulation. It contains rotation and trans lation information. In this struct, translation is a vec3, and rotation is a 3* 3 matrix.

## BulletMakeFrameFromPivotAxis
Convert a transform described with pivot and axis to matrix representation.
### Input:
`pivot`(vec3): The position of a pivot
`axis`(vec3): The direction of the axis
### Output:
`trans`(BulletTransform):  A struct for transform in Bullet simulation. It contains rotation and trans lation information. In this struct, translation is a vec3, and rotation is a 3* 3 matrix.

## BulletTransformSetBasisEuler
Use a zyx format euler angle to set rotation
### Input:
`trans`: bullet transform
`eulerZYX`: zyx euler

## BulletQuatRotate
TODO: fix code

## BulletComposeTransform
Have two transform matrixs and multiply them to transform for two times.
### Input:
`transFirst`: Transform matrix
`transSecond`: Transform matrix
### Output
`trans`: Output transform

## BulletObjectGetTransform
### Input:
`object`
### Output:
`transform`: world transform

## BulletInverseTransform
### Input:
`transform`
### Output:
`trans_inv`

## BulletExtractTransform
Extract translation and rotation from a bullet transform struct.
### Input:
`trans`: bullet transform
### Output:
`origin`: translation
`rotation`: vec4f rotation

# Geometry
## PrimitiveToBulletMesh
Convert a triangulated mesh from zeno primitive object.
### Input:
`prim`: primitive
### Output:
`mesh`: triangulated mesh

## PrimitiveConvexDecomposition
Perform HACD comvex decomposition algo on a prmitive object.
### Input:
`prim`: primitive to perfrom HACD
### Output:
`listPrim`: The list with convex mesh elements

## PrimitiveConvexDecompositionV
Perform VHACD comvex decomposition algo on a prmitive object.
### Input:
`prim`: primitive to perfrom HACD
### Output:
`listPrim`: The list with convex mesh elements

# Collision
## BulletMakeBoxShape
### Input:
`semiSize`: Half of the length, width, and height
### Output:
`shape`(BulletCollisionShape): The box shape

## BulletMakeSphereShape
### Input:
`radius`: radius
### Output:
`shape`(BulletCollisionShape): The Sphere shape

## BulletMakeStaticPlaneShape
### Input:
`planeNormal`: normal of the plane
`planeConstant`: the position of the plane. The plane normal lets you decide the derection of the plane, while the constant decides the position of the plane.
### Output:
`shape`(BulletCollisionShape): The plane shape

## BulletMakeCapsuleShape
### Input:
`radius`: radius
`height`:height
### Output:
`shape`(BulletCollisionShape): The capsule shape

## BulletMakeCylinderShape
### Input:
`halfExtents`: (width of section, width of section, half height)
### Output:
`shape`(BulletCollisionShape): The capsule shape

## BulletMakeCompoundShape
Initialize a compuond shape
### Output:
`compound`: compound

## BulletCompoundAddChild
add child to compound
### Input:
`compund`: The compound to add child
`childShape`(BulletCollisionShape): child
`trans`: local transform
### Output: 
`compund`: compound with child shapes

##  BulletColShapeCalcLocalInertia
Calculate the inertia of a given collision object in the local frame
### Input:
`colobject`: collision object
`mass`(float): the mass of the object
`isCompuond`(bool): if the object is a compund shape
### Output:
`localInertia`: the inertia of a given collision object in the local frame

## BulletMakeConvexMeshShape
Convert mesh to a collision shape with convex hull
### Input:
`triMesh`: BulletTriangelMesh
### Output:
`shape`: Bullet collision shape

## BulletMakeConvexHullShape (recommend to use this)
Convert mesh to a collision shape with convex hull
### Input:
`triMesh`: BulletTriangelMesh
### Output:
`shape`: Bullet collision shape

![](/media/202304/2022-05-27_005845_303674_1681091509.png)

## BulletMakeObject
Initialize an object with physics properties in Bullet
### Input:
`shape`: BulletCollisionSahpe
`trans`: transform
`mass`: mass, float
### Output:
`object`: BulletObject

## BulletObjectSetDamping
Linear damping affects how the body moves through the world in any given direction. Having linear damping at zero (the default) means objects will keep moving until friction slows them down. At higher values, they would slow down even if they don't touch anything. Angular damping is similar, but applies to angular motion (ie. rotation).
### Input:
`object`: BulletObject
`dampLin`: linear damping
`dampAug`: angular damping
### Output:
`object`: BulletObject

## BulletObjectSetFriction
Friction coefficient, from 0-1.
### Input:
`object`: BulletObject
`friction`: set surface friction
### Output:
`object`: BulletObject

## BulletObjectSetRestitution
Restitution is like 'bounciness'. Higher restitution makes a body bounce more, no restitution gives no added bouncing.
### Input:
`object`: BulletObject
`restitution`: restitution
### Output:
`object`:BulletObject

## BulletObjectGetVel
Get velocity of a rigid body object
### Input
`object`: bullet object
### Output
`linearVel`: vec3f
`angularVel`: vec3f

# Constraint
## BulletMakeConstraint
setup a constraint
### Input
`obj1`: Bullet Object
`obj2`: Bullet Object (optional)
`constraintType`:
- ConeTwist 
- Fixed 
- Gear 
- Generic6Dof 
- Generic6DofSpring 
- Generic6DofSpring2 
- Hinge 
- Hinge2 
- Point2Point 
- Slider 
- Universal
### Output
`constraint`: BulletConstraint

## BulletConstraintSetFrames
Set the position of the constraint
### Input
`constraint`: BulletConstraint
`frame1`: BulletTransform
`frame2`: BulletTransform
### Output:
`constraint`: BulletConstraint

## BulletConstraintGetFrames
### Input
`constraint`: BulletConstraint
### Output:
`frame1`: BulletTransform
`frame2`: BulletTransform

## BulletConstraintSetLimitByAxis
### Input:
`constraint`: BulletConstraint
`axisId`: string
- linearX
- linearY
- linearZ
- angularX
- angularY
- angularZ
`lowLimit`: float
`highLimit`: float
### Output:
`constraint`: BulletConstraint

# Load URDF
The loadURDF will send a command to the physics server to load a physics model from a Universal Robot Description File (URDF). The URDF file is used by the ROS project (Robot Operating System) to describe robots and other objects, it was created by the WillowGarage and the Open Source Robotics Foundation (OSRF). Many robots have public URDF files, you can find a description and tutorial here: http://wiki.ros.org/urdf/Tutorials

Important note: most joints (slider, revolute, continuous) have motors enabled by default that prevent free motion. This is similar to a robot joint with a very high-friction harmonic drive. You should set the joint motor control mode and target settings using `SetMotorControl` node.
##

# Inverse Kinematics and Dynamics
You can compute the joint angles that makes the end-effector reach a given target position in Cartesian world space. Internally, Bullet uses an improved version of Samuel Buss Inverse Kinematics library. At the moment only the Damped Least Squares method with or without Null Space control is exposed, with a single end-effector target. Optionally you can also specify the target orientation of the end effector. In addition, there is an option to use the null-space to specify joint limits and rest poses. This optional null-space support requires all 4 lists (lowerLimits, upperLimits, jointRanges, restPoses), otherwise regular IK will be used. See also inverse_kinematics.py example in Bullet/examples/pybullet/examples folder for details.

![](/media/202304/2022-05-25_230148_482281_1681091547.png)

## BulletCalcInverseKinematics

![](/media/202304/2022-05-25_230514_803830_1681091573.png)
### Input:
`object`: The multibody object
`gravity`: Gravity in the world
`endEffectorLinkIndices`: The link index for the end effector
`targetPositions`: Target position of the end effector (its link coordinate, not center of mass coordinate!). By default this is in Cartesian world space, unless you provide currentPosition joint angles.
`targetOrientations`: Target orientation in Cartesian world space, quaternion [x,y,z,w]. If not specified, pure position IK will be used.
`numIterations`: Max iterations for optimization
`residualThreshold`:  Error threshold for the solver to stop.
`IKMethod`: solver
- VEL_DLS_ORI_NULL 
- VEL_SDLS_ORI 
- VEL_DLS_ORI 
- VEL_DLS_NULL 
- VEL_SDLS
- VEL_DLS 
- JACOB_TRANS
### Output:
`poses`: Pose sequence of the joints in degrees

## BulletMultiBodyCalculateJacobian
BulletMultiBodyCalculateJacobian will compute the translational and rotational jacobians for a point on a link, e.g. x_dot = J * q_dot. The returned jacobians are slightly different depending on whether the root link is fixed or floating. If floating, the jacobians will include columns corresponding to the root link degrees of freedom; if fixed, the jacobians will only have columns associated with the joints. 
### Input:
`object`: Multibody object
`linkIndex`: link index
`localPos`: Position of the point to calculate in the local frame(link frame)
`jointPositionsQ`: Joint positions in degree.
`jointVelocitiesQd`: Joint velocities, namely, the derivitives of joint positions, so it is called Qd, which means 'Q dot'.
`jointAccelerations`: Joint accelerations
`gravity`: Gravity in the world
### Output:
`object`: The multibody object which contains the link
`jacobian_linear`: linear jacobian
`jacobian_angular`: angular jacobian

## BulletMultiBodyCalculateMassMatrix
BulletMultiBodyCalculateMassMatrix will compute the system inertia for an articulated body given its joint positions. The composite rigid body algorithm (CBRA) is used to compute the mass matrix. 
### Input:
`object`: Multibody object
`jointPositionsQ`: Joint positions in degree.
### Output:
`object`: Multibody object
`mass_matrix`: The calculated mass matrix