convex_body command

Purpose

Command for defining convex non-spherical objects.

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

convex_body id command-ID file filename keyword values

Keywords	Description
id	obligatory; user-assigned name for the command call (used as reference in particle_template)
file	obligatory; filename of stl file containing the particle template
move	vector; move the mesh by this extent in x-, y-, and z-direction default: (0, 0, 0); range: (-∞,∞); units: [length]
moment_of_inertia *	`principal` vector1 `off_diagonal` vector2 vector1: (Ixx, Iyy, Izz); vector with the principal values of the inertia tensor vector2: (Iyx, Ixz, Iyz); vector with the off-diagonal values
mass *	mass assigned to this convex body units: [mass]
center_of_mass *	vector with center of mass units: [length]
scale	factor to scale the template
scale_axes	3D vector with factors to scale the template along the cartesian axes
rotate	`axis` vector `angle` value; axis: rotation axis vector, rotation goes through origin; angle: rotation angle in degrees

* Either all or non of the quantities moment_of_inertia, mass and center_of_mass have to be defined.

Examples

convex_body id c1 move (0, 0, 0) file data/cube.stl &
              center_of_mass (0, 0, 0) mass 0.1 &
              moment_of_inertia principal (1.5e-4, 1.5e-4, 1.5e-4) off_diagonal (0, 0, 0)
convex_body id c2 move (0, 0, 0) file data/cube.stl &
              center_of_mass (0, 0, 0) mass 0.1 &
              moment_of_inertia principal (1.5e-4, 1.5e-4, 1.5e-4) off_diagonal (0, 0, 0) &
              rotate axis (1.,1.,1.) scale_axes (1.2,0.7,1.01)

Description

Define a a convex non-spherical objects that is used as input for a particle_template command that defines a concave object. The convex non-spherical object is defined by an stl file, whose file name is specified via the file keyword. The stl can be translated using the keyword move.

After a convex hull mesh is read, an analytical formula is used to compute mass, center of mass and the inertia tensor including its eigensystem. As an alternative, the body’s mass and inertia tensor can be specified directly via keywords mass, center_of_mass and inertia_tensor. Note that you can either specify both mass and center_of_mass or none of them. Furthermore, if the moment_of_inertia keyword is present, both principal and off_diagonal keywords must follow with the relatives vectors.

The scale, scale_axes and rotate keywords can be used to change the particle shape after reading the STL file. scale scales the whole particle by a constant factor. scale_axes scales the particle by different factors along the cartesian axes, eg. scale_axes (0.5,1,2) will scale all x coordinates by 0.5, leave y coordinates untouched, and scale z coordinates by a factor of 2. rotate, along with its sub-keywords axis and angle, rotates the particle around an axis through the coordinate origin by a defined angle. An arbitrary number of operations is allowed, and the operations are executed in order of appearance in the command.

Note

If mass, center of mass and inertia tensor are not specified, scale, scale_axes and rotate operations are applied before these quantities are computed, so the shape transformations will affect the outcome. If, however, the mass, center_of_mass and moment_of_inertia keywords are given by the user, then those values remain unchanged.

Default

move = (0 ,0 ,0)