2.5 Using the 3D environment

The VIBES Toolbox has extensive functionality to plot structures, visualize mode shapes, and export videos. In this tutorial, the basics of the 3D environment will be explained and several workflows will be demonstrated.

The following classes will be explored in this tutorial:

• vibes.figure3d
• vibes.ui.Mesh
• vibes.ui.Element
• vibes.ui.Face

Plotting the nodes of a numerical model

We begin by loading an object of superclass vibes.abstract.NumericalModel into the workspace, in this case, a vibes.ModalModel. The demonstrated methods can be applied to any numerical model object.

mModel = vibes.load('VIBES,Examples,Datasets','mat','Crane','Crane.ModalModel.mat');

% The simplest way to show the geometry of the model is to plot its nodes.
% Open the 3D viewer and plot the nodes.
V = vibes.figure3d();
mModel.plotNodes();

% Set some axes bounds, set the camera view to #4
V.ZBounds(1) = 0; V.resetAxesLimits();
V.view(4); pause(1);

% You can also add plot styles to the plotNodes method. For example, plot
% the model with red circles instead.
mModel.plotNodes('ro')

Familiarising with the 3D viewer

Use the right mouse button on an object to open a context menu with self-explaining functions.

The following keyboard shortcuts for camera and axes control exist:

• (SHIFT)-1,2,3,4 – Transition camera to default positions
• 0 – Reset camera
• p – Change to perspective view
• o – Change to orthogonal view
• x – Toggle axes
• g – Toggle grid (if axes are present)

Using mesh objects

For more extensive plotting capabilities, it is helpful to create a mesh object. Objects of class vibes.ui.Mesh can be created from any numerical model. Numerical models which have mode shapes associated with them, such as the current modal model and some vibes.CMSModel objects, will automatically pass on this information to the mesh object.

% Clear the nodes and plot a mesh
V.removeAllNodes();
mesh = mModel.plotMesh();
V.lookAt();

% Take a look at the properties of the mesh object.
disp(mesh)

% You can set properties of the mesh directly, such as its color.
mesh.Color = 'r';

% All objects plotted in the 3D viewer can be accessed via its object.
disp(V)

Defining elements

Notice that the mesh object allows specifying elements. The elements for the crane model can be found in the Crane.mat file. This file contains the properties of the original Finite Element Model of the crane.

crane = vibes.load('VIBES,Examples,Datasets','mat','Crane','Crane.mat');

The Elements field in the crane structure has three columns. The first one defines the element type, as described in the ElementTypes field. The second and third columns contain the node numbers of connected nodes. As a demonstration, we will give every element type its own color.

% First, extract the connectivity list.
connectivity = crane.Elements(:,2:3);

% Define a set of colors.
clrSet = {'r','g','b','k','c','y'};

% Pick a color for each element
types = crane.Elements(:,1);
clrs = clrSet(types);

You can add the elements directly to the mesh object, specify them as a parameter in the numerical model or create Element objects using the vibes.ui.Element class. The latter will be shown below.

Element objects can be created from a set of nodes and a connectivity list. Additionally, the color and line style can be defined.

elems = vibes.ui.Element(mModel.Nodes,connectivity,'Color',clrs);

% Show the created element objects.
disp(elems)

% Assign the elements to the mesh.
mesh.Elements = elems;

V.clf();
mesh.plot();

V.ZBounds(1) = 0; V.lookAt(); V.resetAxesLimits();
V.view(4); pause(1);

Defining faces

It is also possible to define faces for the mesh. We will demonstrate this by adding faces between the four ground nodes of the model (nodes 1, 2, 3, and 4). Faces can be defined in a similar way to elements, using the vibes.ui.Face class. You can let the mesh create face objects for you by assigning them to the connectivity list.

% Define the faces' connectivity.
faces = [1 2 3; 1 3 4];

% Assign it to the mesh.
mesh.Faces = faces;

% Show the created faces.
disp(mesh.Faces);

You can change the plot style of faces and elements after creating them using the setStyle method. For faces, you can define a color and an opacity value. As a demonstration, we will set the color to green and the opacity to 75%.

mesh.Faces.setStyle('g0.75');

Visualizing mode shapes

The mesh object that we have created contains the mode shape data of the modal model. You can use this to visualize the vibration modes of the model. The following keyboard shortcuts can be used to view mode shapes in the 3D viewer:

• Spacebar – play/pause the current mode shape
• CTRL + up arrow – switch to next mode shape
• CTRL + down arrow – switch to previous mode shape
• CTRL + SHIFT + up/down arrows – skip 10 mode shapes up or down

mesh.animateMode(7);

pause(2.5);

mesh.pause();

Visualizing operational deflection shapes

Mesh objects can also be created from vibes.FRFMatrix and vibes.FreqBlocks objects. In this case, the columns of the matrix are taken as mode shapes for the mesh object.

% Load an FRF matrix
Y = vibes.load('VIBES,Examples,Datasets','mat','Benchmark','YA.FRFMatrix.mat');

Create a mesh from it using the vibes.FRFMatrx/ods method. Define some faces for increased visibility.

V.clf(); V.hideAxes();

mesh = Y.ods('Faces',[1 2 3; 1 3 4]);
V.lookAt();

You can use keyboard shortcuts to cycle through different columns of the FRF matrix:

• CTRL + up arrow – switch to next column
• CTRL + down arrow – switch to previous column
• CTRL + SHIFT + up/down arrows – skip 10 columns up or down
• CTRL + right arrow – go up one frequency point
• CTRL + left arrow – go down one frequency point
• CTRL + SHIFT + left/right arrows – skip 10 frequencies up or down

Advanced 3D plotting: color functions

Using mesh and face objects, it is possible to make the color of the face depend on the displacement of its nodes. This is achieved by setting the face color to the value fcn, indicating that it should adopt its color from a color function defined by the mesh’s animation object. The animation object controls the movement and the graphics of the mesh. The animation object should be assigned a colormap, from which the color function can draw its colors. By default, the mesh assigns a color to a face based on the displacement of its nodes compared to the maximum displacement at that frequency.

% Set the faces' color value to 'fcn'
mesh.Faces.setStyle('fcn');

% Set the mesh animation's colormap to 'parula', MATLAB's default colormap
mesh.Animation.ColorMap = parula();

Additionally, it is also possible to define your own color functions. A color function is called once for every set of faces that has the color fcn and the same opacity value. A color function should take three input parameters: the mesh’s animation object, a structure that contains the indices in the node list per face, and a structure that contains the properties of the patch object that are to be set. An example of a color function that colors faces based only on the displacement in X-direction is found in the example folder.

% Set the mesh animation's color function to the new function
mesh.Animation.ColorFcn = @customColorFcn;

% View different columns at different frequencies to see how the color
% function behaves!
mesh.Animation.Index = [6 590];