Bodies and geometry¶

Bodies¶

A body is a rigid body with its mass, its principal moments of inertia about the center of mass, and its position and orientation at t = 0:

bodies:
  arm:
    mass: 2.0
    inertia: [0.002, 0.17, 0.17]        # about the principal axes
    position: [0.5, 0, 0]                # center of mass, global
    orientation: [1, 0, 0, 0]            # principal axes = global axes
    velocity: [0, 0, 0]                  # initial velocity of the center of mass
    angular_velocity: [0, 0, 5]          # initial angular velocity, global components

key	value
`id`	id
`mass` (required)	number
`inertia` (required)	list of 3	Principal moments of inertia about the center of mass, body frame.
`position`	[x, y, z] or a point name	Global position of the center of mass. Default [0,0,0].
`orientation`	list of 4 or a frame name	Principal axes as Euler parameters [theta0, theta1, theta2, theta3], theta0 scalar part. Normalized by the generator. Default [1,0,0,0].
`velocity`	[x, y, z]	Global velocity of the center of mass. Default [0,0,0].
`angular_velocity`	[x, y, z]	Angular velocity in GLOBAL components. Default [0,0,0].
`shapes`	shapes
`element`	`rigid_body` \| `rigid_body_euler`	Body formulation: rigid_body (Lie group) or rigid_body_euler (Euler parameters with a normalization constraint, as legacy FreeDyn; models converted with freedyn2 convert --profile legacy). All bodies of a model use the same one. Default `rigid_body`.
`jacobian`	`full` \| `no_qvv`	Iteration matrix: full, or without the velocity derivatives of the inertia forces (legacy RegardVelocityInertiaForcesInsideJacobian = no; rigid_body_euler). Default `full`.
`newmark`	`standard` \| `modified`	rigid_body_euler: the legacy ModifyNewmark option (modified). Default `standard`.

inertia are the principal moments in the body frame; orientation gives the principal axes. A body with a full inertia tensor: rotate its frame to the principal axes (the eigenvectors of the tensor) and give the eigenvalues.
A real body satisfies I1 + I2 ≥ I3 for every ordering of its moments; the checks report an error otherwise.
Bodies move on the Lie group R³ × SO(3): no singular angles, any rotation.

Shapes¶

Geometry is for the viewer only; it does not change the simulation. Without shapes a body is drawn as the box of its mass and inertia, a wheel with a tire as a cylinder.

bodies:
  arm:
    ...
    shapes:
      - {type: box, size: [1.0, 0.05, 0.05]}                          # at the body frame
      - {type: cylinder, radius: 0.04, length: 0.1, position: [1, 0, 0],
         orientation: [0.7071068, -0.7071068, 0, 0], color: "#e15759"} # axis along global y
      - {type: mesh, file: arm.stl, scale: 0.001, position: [0, 0, 0]} # CAD export of the assembly, mm
ground:
  shapes:
    - {type: box, size: [2, 2, 0.02], position: [0, 0, -0.5], opacity: 0.5}

key	value
`id`	id
`type` (required)	`box` \| `cylinder` \| `sphere` \| `mesh`	box: edge lengths size along the shape axes. cylinder: radius and length, axis along the shape z axis. sphere: radius. mesh: an STL or OBJ file (relative to the model file), vertices in shape coordinates, times scale.
`size`	[x, y, z]	box: edge lengths [m].
`radius`	number	cylinder, sphere [m].
`length`	number	cylinder [m].
`file`	string	mesh: .stl (binary or ASCII) or .obj file.
`scale`	number or list	mesh: factor of the file coordinates, e.g. 0.001 for mm. Default 1.
`frame`	`global` \| `body`	position and orientation global at t = 0 (as all model input, default; e.g. a mesh exported from a CAD assembly: position [0,0,0]) or in the body frame.
`position`	[x, y, z]	Origin of the shape frame. Default the body frame origin (center of mass).
`orientation`	list of 4	Shape frame as Euler parameters. Default the body frame.
`color`	string	#rrggbb. Default a color per body.
`opacity`	number	Default 1.

Like all model input, shapes are placed globally at t = 0 (with frame: body in the body frame instead). A mesh exported from a CAD assembly has its vertices in assembly coordinates: give it position: [0, 0, 0] and it sits where it was in the assembly. Meshes: binary or ASCII STL, OBJ.