Modelica.Mechanics.MultiBody.Visualizers

Information

Package Visualizers contains components to visualize 3-dimensional shapes. These components are the basis for the animation features of the MultiBody library.

Content

FixedShape FixedShape2	Visualizing an elementary shape with dynamically varying shape attributes. FixedShape has one connector frame_a, whereas FixedShape2 has additionally a frame_b for easier connection to further visual objects. The following shape types are supported:
FixedFrame	Visualizing a coordinate system including axes labels with fixed sizes:
FixedArrow, SignalArrow	Visualizing an arrow. Model "FixedArrow" provides a fixed sized arrow, model "SignalArrow" provides an arrow with dynamically varying length that is defined by an input signal vector:
Ground	Visualizing the x-y plane by a box:
Torus	Visualizing a torus:
VoluminousWheel	Visualizing a wheel:
PipeWithScalarField	Visualizing a pipe with a scalar field represented by a color coding:
Advanced	Package that contains components to visualize 3-dimensional shapes where all parts of the shape can vary dynamically. Basic knowledge of Modelica is needed in order to utilize the components of this package.

The colors of the visualization components are declared with the predefined type MultiBody.Types.Color. This is a vector with 3 elements, {r, g, b}, and specifies the color of the shape. {r,g,b} are the "red", "green" and "blue" color parts. Note, r g, b are given as Integer[3] in the ranges 0 .. 255, respectively.

Package Content

Name	Description
FixedShape	Visualizing an elementary shape with dynamically varying shape attributes (has one frame connector)
FixedShape2	Visualizing an elementary shape with dynamically varying shape attributes (has two frame connectors)
FixedFrame	Visualizing a coordinate system including axes labels (visualization data may vary dynamically)
FixedArrow	Visualizing an arrow with dynamically varying size in frame_a
SignalArrow	Visualizing an arrow with dynamically varying size in frame_a based on input signal
Ground	Visualizing the ground (box in z=0)
Torus	Visualizing a torus
VoluminousWheel	Visualizing a voluminous wheel
PipeWithScalarField	Visualizing a pipe with scalar field quantities along the pipe axis
Colors	Library of functions operating on color
Advanced	Visualizers that require basic knowledge about Modelica in order to use them

Modelica.Mechanics.MultiBody.Visualizers.FixedShape

Information

Model FixedShape defines a visual shape that is shown at the location of its frame_a. All describing data such as size and color can vary dynamically by providing appropriate expressions in the input fields of the parameter menu. The only exception is parameter shapeType that cannot be changed during simulation. The following shapes are currently supported via parameter shapeType (e.g., shapeType="box"):
 

The dark blue arrows in the figure above are directed along variable lengthDirection. The light blue arrows are directed along variable widthDirection. The coordinate systems in the figure represent frame_a of the FixedShape component.

Additionally, external shapes can be specified as (not all options might be supported by all tools):

• "1", "2", ...
  define external shapes specified in DXF format in files "1.dxf", "2.dxf", ... The DXF-files must be found either in the current directory or in the directory where the Shape instance is stored that references the DXF file. This (very limited) option should not be used for new models. Example:
  shapeType="1".
  
• "modelica://<Modelica-name>/<relative-path-file-name>"
  characterizes the file that is stored under the location of the <Modelica-name> library path with the given relative file name. Example:
  shapeType = "modelica://Modelica/Resources/Data/Shapes/Engine/piston.dxf".
  
• "file://<absolute-file-name>"
  characterizes an absolute file name in the file system. Example:
  shapeType="file://C:/users/myname/shapes/piston.dxf".

The supported file formats are tool dependent. Most tools support at least DXF-files (a tool might support 3-dim. Face of the DXF format only), but may support other format as well (such as stl, obj, 3ds). Since visualization files contain color and other data, the corresponding information in the model is usually ignored.

The sizes of any of the above components are specified by the length, width and height variables. Via variable extra additional data can be defined:

Parameter color is a vector with 3 elements, {r, g, b}, and specifies the color of the shape. {r,g,b} are the "red", "green" and "blue" color parts. Note, r g, b are given as Integer[3] in the ranges 0 .. 255, respectively. The predefined type MultiBody.Types.Color contains a menu definition of the colors used in the MultiBody library together with a color editor.

Parameters

Name	Description
animation	= true, if animation shall be enabled
if animation = true
shapeType	Type of shape
r_shape[3]	Vector from frame_a to shape origin, resolved in frame_a [m]
lengthDirection	Vector in length direction of shape, resolved in frame_a [1]
widthDirection	Vector in width direction of shape, resolved in frame_a [1]
length	Length of shape [m]
width	Width of shape [m]
height	Height of shape [m]
color	Color of shape
extra	Additional data for cylinder, cone, pipe, gearwheel and spring
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved

Modelica.Mechanics.MultiBody.Visualizers.FixedShape2

Information

Model FixedShape2 defines a visual shape that is shown at the location of its frame_a. This model is identical to FixedShape with the only difference that an additional frame_b is present which is parallel to frame_a. This makes it more convenient to connect several visual shapes together when building up more complex visual objects. All describing data such as size and color can vary dynamically by providing appropriate expressions in the input fields of the parameter menu. The only exception is parameter shapeType that cannot be changed during simulation. The following shapes are currently supported via parameter shapeType (e.g., shapeType="box"):
 

 
The dark blue arrows in the figure above are directed along variable lengthDirection. The light blue arrows are directed along variable widthDirection. The coordinate systems in the figure represent frame_a of the FixedShape component.

Additionally, external shapes can be specified as (not all options might be supported by all tools):

• "1", "2", ...
  define external shapes specified in DXF format in files "1.dxf", "2.dxf", ... The DXF-files must be found either in the current directory or in the directory where the Shape instance is stored that references the DXF file. This (very limited) option should not be used for new models. Example:
  shapeType="1".
  
• "modelica://<Modelica-name>/<relative-path-file-name>"
  characterizes the file that is stored under the location of the <Modelica-name> library path with the given relative file name. Example:
  shapeType = "modelica://Modelica/Resources/Data/Shapes/Engine/piston.dxf".
  
• "file://<absolute-file-name>"
  characterizes an absolute file name in the file system. Example:
  shapeType="file://C:/users/myname/shapes/piston.dxf".

The supported file formats are tool dependent. Most tools support at least DXF-files (a tool might support 3-dim. Face of the DXF format only), but may support other format as well (such as stl, obj, 3ds). Since visualization files contain color and other data, the corresponding information in the model is usually ignored.

The sizes of any of the above components are specified by the length, width and height variables. Via variable extra additional data can be defined:

Parameter color is a vector with 3 elements, {r, g, b}, and specifies the color of the shape. {r,g,b} are the "red", "green" and "blue" color parts. Note, r g, b are given as Integer[3] in the ranges 0 .. 255, respectively. The predefined type MultiBody.Types.Color contains a menu definition of the colors used in the MultiBody library together with a color editor.

In the following figure the relationships between frame_a and frame_b are shown. The origin of frame_b with respect to frame_a is specified via parameter vector r.

Parameters

Name	Description
animation	= true, if animation shall be enabled
if animation = true
shapeType	Type of shape
r_shape[3]	Vector from frame_a to shape origin, resolved in frame_a [m]
lengthDirection	Vector in length direction of shape, resolved in frame_a [1]
widthDirection	Vector in width direction of shape, resolved in frame_a [1]
length	Length of shape [m]
width	Width of shape [m]
height	Height of shape [m]
extra	Additional data for cylinder, cone, pipe, gearwheel and spring
color	Color of shape
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)

Connectors

Name	Description
frame_a	Coordinate system a (all shape definition vectors are resolved in this frame)
frame_b	Coordinate system b

Modelica.Mechanics.MultiBody.Visualizers.FixedFrame

Information

Model FixedFrame visualizes the three axes of its coordinate system frame_a together with appropriate axes labels. A typical example is shown in the following figure:
 

The sizes of the axes, the axes colors and the specular coefficient (= reflection factor for ambient light) can vary dynamically by providing appropriate expressions in the input fields of the parameter menu.

Parameters

Name	Description
animation	= true, if animation shall be enabled
if animation = true
showLabels	= true, if labels shall be shown
length	Length of axes arrows [m]
diameter	Diameter of axes arrows [m]
color_x	Color of x-arrow
color_y	Color of y-arrow
color_z	Color of z-arrow
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved

Modelica.Mechanics.MultiBody.Visualizers.FixedArrow

Information

Model FixedArrow defines an arrow that is shown at the location of its frame_a.
 

The direction of the arrow specified with vector n is with respect to frame_a, i.e., the local frame to which the arrow component is attached. The direction and length of the arrow, its diameter and color can vary dynamically by providing appropriate expressions in the input fields of the parameter menu.

Parameters

Name	Description
animation	= true, if animation shall be enabled
if animation = true
r_tail[3]	Vector from frame_a to arrow tail, resolved in frame_a [m]
n	Vector in arrow direction, resolved in frame_a [1]
length	Length of complete arrow [m]
diameter	Diameter of arrow line [m]
color	Color of arrow
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved

Modelica.Mechanics.MultiBody.Visualizers.SignalArrow

Information

Model SignalArrow defines an arrow that is dynamically visualized at the location where its frame_a is attached. The position vector from the tail to the head of the arrow, resolved in frame_a, is defined via the signal vector of the connector r_head (Real r_head[3]):
 

The tail of the arrow is defined with parameter r_tail with respect to frame_a (vector from the origin of frame_a to the arrow tail).

Parameters

Name	Description
animation	= true, if animation shall be enabled
if animation = true
r_tail[3]	Vector from frame_a to arrow tail, resolved in frame_a [m]
diameter	Diameter of arrow line [m]
color	Color of arrow
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved
r_head[3]	Position vector from origin of frame_a to head of arrow, resolved in frame_a [m]

Modelica.Mechanics.MultiBody.Visualizers.Ground

Information

This shape visualizes the x-y plane by a box

Parameters

Name	Description
animation	= true, if animation of ground shall be enabled
length	Length and width of box (center is at x=y=0) [m]
height	Height of box (upper surface is at z=0, lower surface is at z=-height) [m]
groundColor	Color of box

Modelica.Mechanics.MultiBody.Visualizers.Torus

Information

Model Torus visualizes a torus. The center of the torus is located at connector frame_a (visualized by the red coordinate system in the figure below). The left image below shows a torus with ri=0.5 m and ro = 0.2 m. The right images below shows the torus with the additional parameter settings:

  opening    =   45 degree
  startAngle = -135 degree
  stopAngle  =  135 degree

In the advanced menu the discretization of the surface visualization can be defined by the number of points of the inner radius of the torus (n_ri) and by the number of points of the outer radius of the torus (n_ro). In case the torus is closed (that is, opening = 0 degree), the actual number of points is one less (that is n_ri-1, n_ro-1), because the first and the last point of the parametrization coincide in this case.

Parameters

Name	Description
animation	= true, if animation shall be enabled
ri	Inner radius of torus [m]
ro	Outer radius of torus (=width/2) [m]
opening	Opening angle of torus [rad]
startAngle	Start angle of torus slice [rad]
stopAngle	End angle of torus slice [rad]
Material properties
wireframe	= true: 3D model will be displayed without faces
color	Color of surface
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)
transparency	Transparency of shape: 0 (= opaque) ... 1 (= fully transparent)
Discretization
n_ri	Number of points along ri
n_ro	Number of points along ro

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved

Modelica.Mechanics.MultiBody.Visualizers.VoluminousWheel

Information

Model VoluminousWheel provides a simple visualization of a tire using a torus and a pipe shape object. The center of the wheel is located at connector frame_a (visualized by the red coordinate system in the figure below).

Parameters

Name	Description
animation	= true, if animation shall be enabled
rTire	Radius of the tire [m]
rRim	Radius of the rim [m]
width	Width of the tire [m]
rCurvature	Radius of the curvature of the tire [m]
Material properties
color	Color of tire
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)
Discretization
n_rTire	Number of points along rTire
n_rCurvature	Number of points along rCurvature

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved

Modelica.Mechanics.MultiBody.Visualizers.PipeWithScalarField

Information

Model PipeWithScalarField visualizes a pipe and a scalar field along the pipe axis. The latter is shown by mapping the scalar field to color values with a color map and utilizing this color at the perimeter associated with the corresponding axis location. Typically the scalar field value is a temperature, but might be also another quantity. Predefined color maps are available from MultiBody.Visualizers.Colors.ColorMaps and can be selected via parameter "colorMap". A color map with the corresponding scalar field values can be exported as vector-graphics in svg-format with function MultiBody.Visualizers.Colors.colorMapToSvg. Connector frame_a of this component is located in the center of the circle at the left side of the pipe and the pipe axis is oriented along the x-axis of frame_a, see figure below in which frame_a is visualized with a coordinate system:

The color coding is shown in the next figure. It was generated with MultiBody.Visualizers.Colors.colorMapToSvg using the following call:

colorMapToSvg(Modelica.Mechanics.MultiBody.Visualizers.Colors.ColorMap.jet(),
              height=50, nScalars=6, T_max=100, caption="Temperature in C");

Parameters

Name	Description
animation	= true, if animation shall be enabled
rOuter	Outer radius of pipe [m]
length	Length of pipe [m]
xsi[:]	[:] Relative position along the pipe with x[1] = 0, x[end] = 1
T[size(xsi, 1)]	[:] Scalar values at position xsi*length (will be visualized by color)
T_min	Minimum value of T that corresponds to colorMap[1,:]
T_max	Maximum value of T that corresponds to colorMap[end,:]
Color coding
replaceable function colorMap	Function defining the color map
n_colors	Number of colors in the colorMap
specularCoefficient	Reflection of ambient light (= 0: light is completely absorbed)
transparency	Transparency of shape: 0 (= opaque) ... 1 (= fully transparent)
Discretization
n_rOuter	Number of points along outer radius
n_length	Number of points along length

Connectors

Name	Description
frame_a	Coordinate system in which visualization data is resolved
Color coding
replaceable function colorMap	Function defining the color map