Modelica.Mechanics.MultiBody.Visualizers.Advanced

Information

Package Visualizers.Advanced contains components to visualize 3-dimensional shapes with dynamical sizes. None of the components has a frame connector. The position and orientation is set via modifiers. Basic knowledge of Modelica is needed in order to utilize the components of this package. These components have also to be used for models, where the forces and torques in the frame connector are set via equations (in this case, the models of the Visualizers package cannot be used, since they all have frame connectors).

Content

Arrow	Visualizing an arrow where all parts of the arrow can vary dynamically:
DoubleArrow	Visualizing a double arrow where all parts of the arrow can vary dynamically:
Shape	Visualizing an elementary object with variable size. The following shape types are supported:
Surface	Visualizing a moveable parameterized surface:
PipeWithScalarField	Visualizing a pipe with a scalar field represented by a color coding:

Extends from Modelica.Icons.Package (Icon for standard packages).

Package Content

Name	Description
Arrow	Visualizing an arrow with variable size; all data have to be set as modifiers (see info layer)
DoubleArrow	Visualizing a double arrow with variable size; all data have to be set as modifiers (see info layer)
Shape	Visualizing an elementary object with variable size; all data have to be set as modifiers (see info layer)
Surface	Visualizing a moveable, parameterized surface; the surface characteristic is provided by a function
PipeWithScalarField	Visualizing a pipe with a scalar field
SurfaceCharacteristics	Functions returning surface descriptions

Modelica.Mechanics.MultiBody.Visualizers.Advanced.Arrow

Information

Model Arrow defines an arrow that is dynamically visualized at the defined location (see variables below).

The variables under heading Parameters below are declared as (time varying) input variables. If the default equation is not appropriate, a corresponding modifier equation has to be provided in the model where an Arrow instance is used, e.g., in the form

    Visualizers.Advanced.Arrow arrow(diameter = sin(time));

Variable color is an Integer 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 in the range 0 .. 255. The predefined type MultiBody.Types.Color contains a menu definition of the colors used in the MultiBody library (will be replaced by a color editor).

Parameters

Type	Name	Default	Description
Orientation	R	Frames.nullRotation()	Orientation object to rotate the world frame into the arrow frame.
Position	r[3]	{0,0,0}	Position vector from origin of world frame to origin of arrow frame, resolved in world frame [m]
Position	r_tail[3]	{0,0,0}	Position vector from origin of arrow frame to arrow tail, resolved in arrow frame [m]
Position	r_head[3]	{0,0,0}	Position vector from arrow tail to the head of the arrow, resolved in arrow frame [m]
Diameter	diameter	world.defaultArrowDiameter	Diameter of arrow line [m]
Color	color	Modelica.Mechanics.MultiBody...	Color of arrow
SpecularCoefficient	specularCoefficient	world.defaultSpecularCoeffic...	Material property describing the reflecting of ambient light (= 0 means, that light is completely absorbed)

Modelica definition

model Arrow 
  "Visualizing an arrow with variable size; all data have to be set as modifiers (see info layer)"

  import SI = Modelica.SIunits;
  import Modelica.Mechanics.MultiBody.Types;
  import Modelica.Mechanics.MultiBody.Frames;
  import T = Modelica.Mechanics.MultiBody.Frames.TransformationMatrices;

  input Frames.Orientation R=Frames.nullRotation() 
    "Orientation object to rotate the world frame into the arrow frame.";
  input SI.Position r[3]={0,0,0} 
    "Position vector from origin of world frame to origin of arrow frame, resolved in world frame";
  input SI.Position r_tail[3]={0,0,0} 
    "Position vector from origin of arrow frame to arrow tail, resolved in arrow frame";
  input SI.Position r_head[3]={0,0,0} 
    "Position vector from arrow tail to the head of the arrow, resolved in arrow frame";
  input SI.Diameter diameter=world.defaultArrowDiameter 
    "Diameter of arrow line";
  input Modelica.Mechanics.MultiBody.Types.Color color=Modelica.Mechanics.MultiBody.Types.Defaults.ArrowColor 
    "Color of arrow";
  input Types.SpecularCoefficient specularCoefficient = world.defaultSpecularCoefficient 
    "Material property describing the reflecting of ambient light (= 0 means, that light is completely absorbed)";

protected 
  outer Modelica.Mechanics.MultiBody.World world;
  SI.Length length=Modelica.Math.Vectors.length(r_head) "Length of arrow";
  Real e_x[3](each final unit="1", start={1,0,0}) = noEvent(if length < 1.e-10 then {1,0,0} else r_head/length);
  Real rxvisobj[3](each final unit="1") = transpose(R.T)*e_x 
    "X-axis unit vector of shape, resolved in world frame";
  SI.Position rvisobj[3] = r + T.resolve1(R.T, r_tail) 
    "Position vector from world frame to shape frame, resolved in world frame";

  Visualizers.Advanced.Shape arrowLine(
    length=noEvent(max(0, length - diameter*Types.Defaults.
        ArrowHeadLengthFraction)),
    width=diameter,
    height=diameter,
    lengthDirection=r_head,
    widthDirection={0,1,0},
    shapeType="cylinder",
    color=color,
    specularCoefficient=specularCoefficient,
    r_shape=r_tail,
    r=r,
    R=R) if world.enableAnimation;
  Visualizers.Advanced.Shape arrowHead(
    length=noEvent(max(0, min(length, diameter*Types.Defaults.
        ArrowHeadLengthFraction))),
    width=noEvent(max(0, diameter*MultiBody.Types.Defaults.
        ArrowHeadWidthFraction)),
    height=noEvent(max(0, diameter*MultiBody.Types.Defaults.
        ArrowHeadWidthFraction)),
    lengthDirection=r_head,
    widthDirection={0,1,0},
    shapeType="cone",
    color=color,
    specularCoefficient=specularCoefficient,
    r=rvisobj + rxvisobj*arrowLine.length,
    R=R) if world.enableAnimation;

end Arrow;

Modelica.Mechanics.MultiBody.Visualizers.Advanced.DoubleArrow

Information

Model DoubleArrow defines a double arrow that is dynamically visualized at the defined location (see variables below).

The variables under heading Parameters below are declared as (time varying) input variables. If the default equation is not appropriate, a corresponding modifier equation has to be provided in the model where an Arrow instance is used, e.g., in the form

    Visualizers.Advanced.DoubleArrow doubleArrow(diameter = sin(time));

Variable color is an Integer 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 in the range 0 .. 255. The predefined type MultiBody.Types.Color contains a menu definition of the colors used in the MultiBody library (will be replaced by a color editor).

Parameters

Type	Name	Default	Description
Orientation	R	Frames.nullRotation()	Orientation object to rotate the world frame into the arrow frame.
Position	r[3]	{0,0,0}	Position vector from origin of world frame to origin of arrow frame, resolved in world frame [m]
Position	r_tail[3]	{0,0,0}	Position vector from origin of arrow frame to double arrow tail, resolved in arrow frame [m]
Position	r_head[3]	{0,0,0}	Position vector from double arrow tail to the head of the double arrow, resolved in arrow frame [m]
Diameter	diameter	world.defaultArrowDiameter	Diameter of arrow line [m]
Color	color	Modelica.Mechanics.MultiBody...	Color of double arrow
SpecularCoefficient	specularCoefficient	world.defaultSpecularCoeffic...	Material property describing the reflecting of ambient light (= 0 means, that light is completely absorbed)

Modelica definition

model DoubleArrow 
  "Visualizing a double arrow with variable size; all data have to be set as modifiers (see info layer)"

  import SI = Modelica.SIunits;
  import Modelica.Mechanics.MultiBody.Types;
  import Modelica.Mechanics.MultiBody.Frames;
  import T = Modelica.Mechanics.MultiBody.Frames.TransformationMatrices;

  input Frames.Orientation R=Frames.nullRotation() 
    "Orientation object to rotate the world frame into the arrow frame.";
  input SI.Position r[3]={0,0,0} 
    "Position vector from origin of world frame to origin of arrow frame, resolved in world frame";
  input SI.Position r_tail[3]={0,0,0} 
    "Position vector from origin of arrow frame to double arrow tail, resolved in arrow frame";
  input SI.Position r_head[3]={0,0,0} 
    "Position vector from double arrow tail to the head of the double arrow, resolved in arrow frame";
  input SI.Diameter diameter=world.defaultArrowDiameter 
    "Diameter of arrow line";
  input Modelica.Mechanics.MultiBody.Types.Color color=Modelica.Mechanics.MultiBody.Types.Defaults.ArrowColor 
    "Color of double arrow";
  input Types.SpecularCoefficient specularCoefficient = world.defaultSpecularCoefficient 
    "Material property describing the reflecting of ambient light (= 0 means, that light is completely absorbed)";

protected 
  outer Modelica.Mechanics.MultiBody.World world;
  SI.Length length=Modelica.Math.Vectors.length(r_head) "Length of arrow";
  Real e_x[3](each final unit="1", start={1,0,0}) = noEvent(if length < 1.e-10 then {1,0,0} else r_head/length);
  Real rxvisobj[3](each final unit="1") = transpose(R.T)*e_x 
    "X-axis unit vector of shape, resolved in world frame";
  SI.Position rvisobj[3] = r + T.resolve1(R.T, r_tail) 
    "Position vector from world frame to shape frame, resolved in world frame";

  SI.Length headLength=noEvent(max(0, min(length, diameter*MultiBody.Types.
      Defaults.ArrowHeadLengthFraction)));
  SI.Length headWidth=noEvent(max(0, diameter*MultiBody.Types.Defaults.
      ArrowHeadWidthFraction));
  Visualizers.Advanced.Shape arrowLine(
    length=noEvent(max(0, length - 1.5*diameter*MultiBody.Types.Defaults.
        ArrowHeadLengthFraction)),
    width=diameter,
    height=diameter,
    lengthDirection=r_head,
    widthDirection={0,1,0},
    shapeType="cylinder",
    color=color,
    specularCoefficient=specularCoefficient,
    r_shape=r_tail,
    r=r,
    R=R) if world.enableAnimation;
  Visualizers.Advanced.Shape arrowHead1(
    length=headLength,
    width=headWidth,
    height=headWidth,
    lengthDirection=r_head,
    widthDirection={0,1,0},
    shapeType="cone",
    color=color,
    specularCoefficient=specularCoefficient,
    r=rvisobj + rxvisobj*arrowLine.length,
    R=R) if world.enableAnimation;
  Visualizers.Advanced.Shape arrowHead2(
    length=headLength,
    width=headWidth,
    height=headWidth,
    lengthDirection=r_head,
    widthDirection={0,1,0},
    shapeType="cone",
    color=color,
    specularCoefficient=specularCoefficient,
    r=rvisobj + rxvisobj*(arrowLine.length + 0.5*arrowHead1.length),
    R=R) if world.enableAnimation;

end DoubleArrow;

Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape

Information

Model Shape defines a visual shape that is shown at the location of its reference coordinate system, called 'object frame' below. All describing variables such as size and color can vary dynamically (with the only exception of parameter shapeType). The default equations in the declarations should be modified by providing appropriate modifier quations. Model Shape is usually used as a basic building block to implement simpler to use graphical components.

The following shapes are 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 Shape component.

Additionally, external shapes are specified as DXF-files (only 3-dim. Face is supported). External shapes must be named "1", "2", ... "N". The corresponding definitions should be in files "1.dxf", "2.dxf" etc. Since the DXF-files contain color and dimensions for the individual faces, the corresponding information in the model is currently ignored. 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.

Via input variable extra additional sizing data is defined according to:

Parameter color is a Real 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 in the range 0 .. 255. The predefined type MultiBody.Types.Color contains a menu definition of the colors used in the MultiBody library.

The variables under heading Parameters below are declared as (time varying) input variables. If the default equation is not appropriate, a corresponding modifier equation has to be provided in the model where a Shape instance is used, e.g., in the form

    Visualizers.Advanced.Shape shape(length = sin(time));

Extends from ModelicaServices.Animation.Shape (Different visual shapes with variable size; all data have to be set as modifiers (see info layer)), Modelica.Utilities.Internal.PartialModelicaServices.Animation.PartialShape (Interface for 3D animation of elementary shapes).

Parameters

Type	Name	Default	Description
ShapeType	shapeType	"box"	Type of shape (box, sphere, cylinder, pipecylinder, cone, pipe, beam, gearwheel, spring)
Orientation	R	Frames.nullRotation()	Orientation object to rotate the world frame into the object frame
Position	r[3]	{0,0,0}	Position vector from origin of world frame to origin of object frame, resolved in world frame [m]
Position	r_shape[3]	{0,0,0}	Position vector from origin of object frame to shape origin, resolved in object frame [m]
Real	lengthDirection[3]	{1,0,0}	Vector in length direction, resolved in object frame [1]
Real	widthDirection[3]	{0,1,0}	Vector in width direction, resolved in object frame [1]
Length	length	0	Length of visual object [m]
Length	width	0	Width of visual object [m]
Length	height	0	Height of visual object [m]
ShapeExtra	extra	0.0	Additional size data for some of the shape types
Real	color[3]	{255,0,0}	Color of shape
SpecularCoefficient	specularCoefficient	0.7	Reflection of ambient light (= 0: light is completely absorbed)

Modelica definition

model Shape 
  "Visualizing an elementary object with variable size; all data have to be set as modifiers (see info layer)"

   extends ModelicaServices.Animation.Shape;
   extends Modelica.Utilities.Internal.PartialModelicaServices.Animation.PartialShape;

end Shape;

Modelica.Mechanics.MultiBody.Visualizers.Advanced.Surface

Information

Model Surface defines a moveable, parametrized surface in 3-dim. space that is used for animation. This object is specified by:

• The surface frame (orientation object "R" and origin "r_0") in which the data is specified.
• A set of two parameters, one in u- and one in v-direction, that defines the control points.
• A time-varying position of each control point with respect to the surface frame.

The parameter values (u,v) are given by the ordinal numbers of the corresponding control point in u- or in v-direction, respectively. The surface is then defined by the replaceable function "surfaceCharacteristic" with the interface partialSurfaceCharacteristic that returns the x-, y-, z- coordinate of every control point in form of 3 arrays X, Y, Z, and an optional color array C, if every control point shall have a different color:

  Real X[nu,nv], Y[nu,nv], Z[nu,nv], C[nu,nv,3];

An example of a parameterized surface with color coding is shown in the next figure:

Models Torus, VoluminousWheel, PipeWithScalarField, demonstrate how new visualizer objects can be constructed with the Surface model.
The direct usage of the Surface model, as well as of the Torus and the VoluminousWheel models, are demonstrated with example Examples.Elementary.Surfaces.

Extends from Modelica.Mechanics.MultiBody.Icons.Surface (Surface icon), Modelica.Utilities.Internal.PartialModelicaServices.Animation.PartialSurface (Interface for 3D animation of surfaces), ModelicaServices.Animation.Surface (Animation of a moveable, parameterized surface; the surface characteristic is provided by a function).

Parameters

Type	Name	Default	Description
Surface frame
Orientation	R	Frames.nullRotation()	Orientation object to rotate the world frame into the surface frame
Position	r_0[3]	{0,0,0}	Position vector from origin of world frame to origin of surface frame, resolved in world frame [m]
Surface properties
Integer	nu	2	Number of points in u-Dimension
Integer	nv	2	Number of points in v-Dimension
replaceable function surfaceCharacteristic		partialSurfaceCharacteristic	Function defining the surface characteristic
Material properties
Boolean	wireframe	false	= true: 3D model will be displayed without faces
Boolean	multiColoredSurface	false	= true: Color is defined for each surface point
Real	color[3]	{255,0,0}	Color of surface
SpecularCoefficient	specularCoefficient	0.7	Reflection of ambient light (= 0: light is completely absorbed)
Real	transparency	0	Transparency of shape: 0 (= opaque) ... 1 (= fully transparent)

Modelica definition

model Surface 
  "Visualizing a moveable, parameterized surface; the surface characteristic is provided by a function"
  extends Modelica.Mechanics.MultiBody.Icons.Surface;
  extends Modelica.Utilities.Internal.PartialModelicaServices.Animation.PartialSurface;
  extends ModelicaServices.Animation.Surface;
equation 

end Surface;

Modelica.Mechanics.MultiBody.Visualizers.Advanced.PipeWithScalarField

Information

Model PipeWithScalarField visualizes a pipe and a scalar field along the pipe axis. The latter is shown by mapping 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. The position and orientation of the center of the circle at the left end of the pipe is defined via parameters "r_0" and "R", respectively. The pipe axis is oriented along the x-axis of the local coordinate system described by "R", see figure below:

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

Type	Name	Default	Description
Surface frame
Orientation	R	Frames.nullRotation()	Orientation object to rotate the world frame into the surface frame
Position	r_0[3]	{0,0,0}	Position vector from origin of world frame to origin of surface frame, resolved in world frame [m]
Surface properties
Radius	rOuter		Outer radius of pipe [m]
Length	length		Length of pipe [m]
Integer	n_rOuter	30	Number of points along outer radius
Integer	n_length	10	Number of points along length
SpecularCoefficient	specularCoefficient	0.7	Reflection of ambient light (= 0: light is completely absorbed)
Real	transparency	0	Transparency of shape: 0 (= opaque) ... 1 (= fully transparent)
Color coding
Real	xsi[:]	Modelica.Math.Vectors.relNod...	[:] Relative position along the pipe with x[1] = 0, x[end] = 1
Real	T[size(xsi, 1)]		[:] Scalar values at position xsi*length (will be visualized by color)
Real	T_min		Minimum value of T that corresponds to colorMap[1,:]
Real	T_max		Maximum value of T that corresponds to colorMap[end,:]
Integer	n_colors	64	Number of colors in the colorMap

Modelica definition

model PipeWithScalarField "Visualizing a pipe with a scalar field"
  input Frames.Orientation R=Frames.nullRotation() 
    "Orientation object to rotate the world frame into the surface frame";
  input Modelica.SIunits.Position r_0[3]={0,0,0} 
    "Position vector from origin of world frame to origin of surface frame, resolved in world frame";

  parameter Modelica.SIunits.Radius rOuter "Outer radius of pipe";
  parameter Modelica.SIunits.Length length "Length of pipe";
  parameter Integer n_rOuter=30 "Number of points along outer radius";
  parameter Integer n_length=10 "Number of points along length";
  parameter Types.SpecularCoefficient specularCoefficient = 0.7 
    "Reflection of ambient light (= 0: light is completely absorbed)";
  parameter Real transparency=0 
    "Transparency of shape: 0 (= opaque) ... 1 (= fully transparent)";

  parameter Real xsi[:](min=0,max=1)= Modelica.Math.Vectors.relNodePositions(12) 
    "[:] Relative position along the pipe with x[1] = 0, x[end] = 1";
  input Real T[size(xsi,1)] 
    "[:] Scalar values at position xsi*length (will be visualized by color)";
  parameter Real T_min "Minimum value of T that corresponds to colorMap[1,:]";
  parameter Real T_max "Maximum value of T that corresponds to colorMap[end,:]";
  parameter Integer n_colors=64 "Number of colors in the colorMap";
  replaceable function colorMap =
      Modelica.Mechanics.MultiBody.Visualizers.Colors.ColorMaps.jet
        constrainedby Modelica.Mechanics.MultiBody.Interfaces.partialColorMap 
    "Function defining the color map";
protected 
  parameter Real colorMapData[n_colors,3] = colorMap(n_colors);
  Surface surface(
    R=R,
    r_0=r_0,
    nu=n_length,
    nv=n_rOuter,
    wireframe=false,
    multiColoredSurface=true,
    specularCoefficient=specularCoefficient,
    transparency=transparency,
    redeclare function surfaceCharacteristic =
        Modelica.Mechanics.MultiBody.Visualizers.Advanced.SurfaceCharacteristics.pipeWithScalarField
        (rOuter=rOuter,
         length=length,
         xsi=xsi,
         T=T,
         T_min=T_min,
         T_max=T_max,
         colorMap=colorMapData));
end PipeWithScalarField;