# AMVis - Documentation

## Table of Contents

1. What is it?
2. AMVis License
3. Program Documentation
4. Interface Documentation
   1. Sphere
   2. Cube
   3. Cuboid
   4. Cylinder
   5. Torus
   6. InvisibleBody
   7. ObjObject
   8. CompoundPrimitiveBody
   9. Extrusion
   10. Rotation
   11. TestElasticBody
   12. Arrow
   13. CoilSpring
   14. Path
   15. KETSIM_*
   16. KETSIM_ObjObject

## What is it?

AMVis is a 3D multibody visualization program. The main use of this program is to visualize the simulation-output of multibody simulation programs. The bodies consist for example of rigid bodies, which move/rotate in six degrees of freedom in space or of elastic bodies, which have additionally degrees of freedom for their geometry.

The input of AMVis consists mainly of *.body and *.pos files, which describe the type and parameters (geometry) of each body (*.body-files) and a list of values for all degrees of freedom dependent in time (*.pos-files).

## AMVis License

Copyright (c) 2006-2008 Institute of Applied Mechanics, Technische Universität München. (http://www.amm.mw.tum.de)

Licensed under the GPL (see file COPYING or here).

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## Program Documentation

Unfortunately, there is currently no program documentation available for AMVis. But this program is licensed under the GPL, so you are free to have a look at the source code (http://www.amm.mw.tum.de/static/software) for getting all the information you need.

## Interface Documentation

The following section describes the content of the *.body and *.pos files for different types of bodies. Each body file requires exactly n pos-files, where n is the number of instances defined in the body-file (see later). The base name of the pos-filenames must be the same as the base name of the associated body-filename. The extension of the pos-filename has to be '.i.pos', where i is current instance with 4 digits filled with '0' (e.g. .0001.pos, .0002.pos).

Each empty line and each line beginning with a '#' in a *.body file is treated at a comment and is simply ignored.

The first column of each pos-file has to be the time of the current dataset. The time-offset of the datasets has to be equidistant.

Body files can also have the extension '.bodyenv' instead of '.body'. In this case no pos file is needed and the object described by this body file is drawn as an environment object with no movement.

Moreover AMVis searches for a file named '.amvis'. For the search order see the output of 'amvis -h'. This file has the following format:

    eps

eps is the maximum value the drawn bodies will differ from the geometrically correct bodies. For example, a circle is approximised by a regular polygon, which will not differ more then eps from the circle by adjusting a proper number of edges. This value defaults to 0.000001. This value is applied before the scaling of CRigidBody's by the scale factor. So you can, for example, make some bodies less accurate by dividing all their parameters by 10 and using a scale factor of 10.

### Sphere

This type of body draws a sphere with radius 'R'. The center point of the sphere is at 0 0 0. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw a sphere
    Sphere
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # radius R of the sphere
    0.32

#### pos-file

Each dataset has the following syntax:

    t WxP WyP WzP αP βP γP color

Where t represents the current time, WxP, WyP and WzP the current translation and αP, βP and γP (kardan angles) the current rotation. color is a float value between 0 and 1 representing the current draw color of the body. The color runs from blue=0 over cyan=0.25 over green=0.5 over yellow=0.75 to red=1.

##### Movement of the body

Each body has a body fixed local coordinate system L and a reference coordinate system R which has a fixed relative position and rotation with respect to L (see above). And there is a inertial fixed world coordinate system W.
The fixed translation from system R to system L is given in the body-file by the vector

    [RxB  RyB  RzB]T=RrB

which coordinates are given in system R.
The fixed rotation between the systems R and L is given in the body-file by the vector

    [αB  βB  γB]T

which are the kardan angles of the transformation matrix

    ARL=kardan(αB,βB,γB)

from system L to system R.
The time dependend translation between the systems W and R is given in the pos-file by the vector

    [WxP  WyP  WzP]T=WrP

which coordinates are given in system W.
The time dependend rotation between the systems W and R is given in the pos-file by the vector

    [αP  βP  γP]T

which are the kardan angles of the transformation matrix

    AWR=kardan(αP,βP,γP)

from system R to system W.

### Cube

This type of body draws a cube with length 'L'. The center point of the cube is at 0 0 0. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw a cube
    Cube
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # length L of the cube
    0.32

#### pos-file

See pos-file of body 'Sphere'.

### Cuboid

This type of body draws a cuboid with length 'Lx', 'Ly' and 'Lz'. The center point of the cuboid is at 0 0 -Lz/2. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw a cuboid
    Cuboid
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # length Lx of the cuboid
    0.32
    # length Ly of the cuboid
    0.22
    # length Lz of the cuboid
    0.63

#### pos-file

See pos-file of body 'Sphere'.

### Cylinder

This type of body draws a frustum with base radius 'R', top radius 'r' and height 'h'. Optional this item can be displayed with a hole (inner base and top radius). To display a full cylinder or frustum the inner radii can be set to zero or the last two entries of the body file can be omitted. The rotation axis is the z-axis. The top radius is in plane z=0 and the base radius is in plane z=-h. This body can also be used to draw a cylinder (R=r) or a cone (r=0). The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw a frustum, cylinder or cone
    Cylinder
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # base radius
    1.6
    # top radius
    0.7
    # height
    0.63
    # inner base radius
    0.8
    # inner top radius
    0.0

#### pos-file

See pos-file of body 'Sphere'.

### Torus

This type of body draws a torus with outer-radius 'R' and inner-radius 'r'. The center of the body is at 0 0 0 and the rotation axis is the z-axis. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw a torus
    Torus
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # radius of the tube (inner-radius)
    1.2
    # radius of axis of the tube (outer-radius)
    0.63

#### pos-file

See pos-file of body 'Sphere'.

### InvisibleBody

This type of body draws nothing. It can be used to move the camera with that body. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draw nothing
    InvisibleBody
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0

#### pos-file

See pos-file of body 'Sphere'.

### ObjObject

This type of body draws a body defined by a Wavefront (*.obj) file. The body is first transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draws a body defined by a wavefront file
    ObjObject
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the body
    1.0
    # filename of the wavefront file
    objfile.obj
    # use textures from material library (1=use textures, 0=do not use textures)
    1
    # use materials from material library (1=use materials, 0=do not use materials)
    1
    # calculation of face normals:
    # 0=use normals from obj-file
    # 1=calculate per face normals (flat shading)
    # 2=calculate per vertex normals (smooth shading; average of all adjacent normals)
    # 3=calculate real normals (smooth, if angle is small; flat, if angle is great)
    0
    # eps-value when vertices are to be treated as equal
    # netative value = no vertices combination
    # (Is only used for outline calculation and calculation of face normals=2,3)
    1e-4
    # eps-value when normals are to be treated as equal
    # netative value = no normals combination
    # (Is only used for outline calculation)
    1e-4
    # eps-value when faces are to be treated as smooth
    # (Is only used for real nomral calculation and outline calculation)
    0.5
    # calculation of outlines:
    # 0=no outline calculation is done
    # 1=calculate outline
    # 2=read outline from file objfile.outline.obj
    1

#### pos-file

See pos-file of body 'Sphere'.

### CompoundPrimitiveBody

This type of body draws several primitiv bodies. Each primitiv body is initially moved, rotated and scaled relative to the compound primitiv body. The compound primitiv body is also transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draws a compound primitiv body
    CompoundPrimitiveBody
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the compound primitive body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the compound primitive body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor of the compound primitiv body
    1.0

    # definition of the first primitiv body

    # type of first primitiv body one of
    # 'Cube', 'Cuboid', 'Cylinder', 'Sphere', 'Torus', 'ObjObject'
    # 'Extrusion', 'Rotation'
    Cube
    # relativ translation
    0.1 0.23 0.2
    # relativ rotation
    0.2 0.12 1.45
    # relativ scale factor
    2.0
    # specific paramters of the primitiv body (here 'Cube')
    # radius
    0.23

    # definition of the second primitiv body

    # type of second primitiv body one of
    # 'Cube', 'Cuboid', 'Cylinder', 'Sphere', 'Torus', 'ObjObject'
    Cuboid
    # relativ translation (x y z)
    0.1 0.23 0.2
    # relativ rotation (alpha beta gamma; kardan angle; radian)
    0.2 0.12 1.45
    # relativ scale factor
    2.0
    # specific paramters of the primitiv body (here 'Cuboid')
    # length Lx of the cuboid
    0.32
    # length Ly of the cuboid
    0.22
    # length Lz of the cuboid
    0.63

    # definition of move primitiv bodies can follow

#### pos-file

See pos-file of body 'Sphere'.

### Extrusion

This type of body draws a extruded body. The base plane lies in the x-y-plane (z=0) and is extruded in positive z-direction. The base plane is defined by multiple polygon contours. The contours are combined by a OpenGL winding rule. The body is transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draws a extrusion body
    Extrusion
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor
    2.0
    # OpenGL winding rule (ODD, NONZERO, POSITIVE, NEGATIVE, ABS_GEQ_TWO)
    ODD
    # extursion height
    0.5
    # polygon contour definition (x y border)
    # border=0: this polygon edge should be rendered smooth
    # border=1: this polygon edge should be rendered none smooth
    # border=-2: a new polygon contour will follow (x, y: irrelevant)
    # border=-1: all polygon definitions are finished (x, y: irrelevant)
    0 0 1
    1 0 1
    1 1 1
    0 1 1
    0 0 -2
    0.5 0.5 1
    0.7 0.5 1
    0.6 0.7 1
    0 0 -1

#### pos-file

See pos-file of body 'Sphere'.

### Rotation

This type of body draws a rotational body. The rotation profile lies in the x-y-plane (z=0) and is rotated around the y-axis. The rotation profile is defined by a polygon contour. The body is transformed by 'initial translation' and 'initial rotation' and then by the values given by the pos-file.

#### body-file

    # draws a rotational body
    Rotation
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # initial translation of the body [RxB  RyB  RzB]T
    0.5 1.2 0.01
    # initial rotation of the body [αB  βB  γB]T
    0.2 0.0 3.14
    # scale factor
    2.0
    # polygon contour definition (x y border)
    # border=0: this polygon edge should be rendered smooth
    # border=1: this polygon edge should be rendered none smooth
    # border=-1: polygon definition is finished (x, y: irrelevant)
    0.10000  0.10000 1
    0.13894  0.10789 0
    0.17174  0.13033 0
    0.19320  0.16376 0
    0.2 0.2 1
    0.1 0.3 1
    0 0 -1

#### pos-file

See pos-file of body 'Sphere'.

### TestElasticBody

This type of body draws an elastic cuboid with constant length 'Lx', constant width 'Ly' and variable height 'Lz'. The front-left-bottom edge of the cuboid is at 0 0 0. The body is transformed by the values given by the pos-file.

#### body-file

    # draw a elastic cuboid
    TestElasticBody
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # length Lx
    0.32
    # width Ly
    0.2

#### pos-file

Each dataset has the following syntax:

    t x height

Where t represents the current time, x the current translation along the x-axis and height represents the current height 'Lz'.

### Arrow

This type of body draws an arrow TO the point [x,y,z] with the direction [dx,dy,dz].

#### body-file

    # draw an arrow
    Arrow
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # diameter of arrow
    0.01
    # diameter of arrowhead
    0.02
    # length of arrowhead
    0.04
    # type: 0=no head; 1=only to-head; 2=only from-head; 3=from- and to-head
    1
    # scale factor arrow length
    1

#### pos-file

Each dataset has the following syntax:

    t x y z dx dy dz color

Where t represents the current time, x, y, z the TO-point and dx, dy, dz the direction. For color see here

### CoilSpring

This type of body draws a coil spring from the point [x0,y0,z0] to the point [x1,y1,z1].

#### body-file

    # draw a coil spring
    CoilSpring
    # number of instances
    1
    # pos-file is binary=1 (datatype float) or ascii=0
    0
    # number of coils
    4.5
    # radius of coil
    0.02
    # radius of cross section
    0.002
    # scale factor
    1

#### pos-file

Each dataset has the following syntax:

    t x0 y0 z0 x1 y1 z1 color

Where t represents the current time, x0, y0, z0 the FROM-point and x1, y1, z1 the TO-point. For color see here

### Path

This type of body draws a polyline in space from time t0 to tcurrentdataset.

#### body-file

    # draw a path
    Path
    # number of instances n
    2
    # pos-file is binary=1 (datatype float) of ascii=0
    0
    # color: red green blue (values runs from 0 to 1)
    0.5 1 0.2

#### pos-file

Each dataset has the following syntax:

    t x y z

Where t represents the current time, x, y, z the polyline point.

### KETSIM_*

This type of bodies draws special bodies for use with the timing chain simulation program KETSIM developed by the Institute of Applied Mechanics, Technische Universität München (http://www.amm.mw.tum.de).

For bush and roller chains the KETSIM chain link "Glied <xxx>/<yy>" is equivalent to the pos-file "Gl_BB_<yyy>.<(xxx+1)/2>" if <xxx> is odd and "Gl_NN_<yyy>.<xxx/2>.pos" if <xxx> is even.

The files 'KETSIM_FE.minmax', 'KETSIM_Gl_RK.minmax', 'KETSIM_Gl_ZKFL.minmax', 'KETSIM_Gl_ZKZL.minmax' and 'KETSIM_VZ.minmax' are provided for manually editing. Each of these files stores two floating-point values of the the minimum (color=blue) and maximum (color=red) load of bodies, respectively.

By using the optional file 'KETSIM_CoSys.dat' it is possible to change the coordinate system and scaling of all KETSIM bodies. This file has the following syntax:

    x y z
    alpha beta gamma
    scale

If this file is not given, then the KETSIM coordinate system K is equal with the world coordinate system W. If given, then [x y z]T=WrK is the translation vector from system W to system K, which coordinates are given in system W. `alpha`, `beta` and `gamma` are the kardan angles of the transformation matrix AWK=`kardan(alpha, beta, gamma)` from system K to system W. `scale` is simply a scale factor.

### KETSIM_ObjObject

This type of body is eval to 'ObjObject', but the original KETSIM object name has to be added to the end of the body-file to work correctly (e.g. correct coloring). The pos-File of this body must have the format of KETSIM-pos-files:

    t WxP WyP WzP γP force|torque|power