Marine Visualization Toolbox

Tutorial#1

This tutorial is a step-by-step instruction to create an animation with the Marine Visualization Toolbox. Before starting make sure the MVT toolbox is correctly installed: While in your work folder, type help mvt. This should display the contents of the MVT, if not see the installation instructions.


Step 1 - Setting up the 6 DOF data

It is assumed that yuo are already familiar with 6 DOF data, if not see 6 DOF data in Marine Visualization basics. Operating on structures and arrays are described here.

In MVT the 6 DOF data is represented by a two dimensional matrix, with N row and 6 columns (Nx6), where N is the total number of data samples. Each row holds the values of the 6 vessel states in the following order: [x y z phi theta psi] (Equal to: [x y z roll pitch yaw]). All angles are given in radians.

Step 1:

Load the saved data from tut1-01.mat (Hint: Highlight the text below, right click and select Evaluate Selection):

     filename = fullfile(matlabroot, 'toolbox', 'mvt', 'tutorials', 'tut1-01.mat');
     load(filename);

This command loads the 6 DOF data saved in tut1-01.mat into your MATLAB workspace as a variable named sixDOF. To see the contents of the array, type:

     sixDOF

To plot the 6 DOF data, for instance the xy-positions, type something like:

     plot(sixDOF(:,1), sixDOF(:,2), 'r-')

This will plot a red line in the xy-plane, recall that x and y is found in the first and second column.

 


Step 2 - Setting up the time vector

Since animations describe movement over time, the relative time of each sample (each row in the 6 DOF data) must be identified. This is done in a column vector, with dimensions Nx1. Each entry, n = 1...N, contain the time value for it's respective samples (rows in sixDOF). The time vector may have varying time steps (the time between subsequent time values), but must be strictly increasing.

Step 2:

     filename = fullfile(matlabroot, 'toolbox', 'mvt', 'tutorials', 'tut1-02.mat');
     load(filename);

This loads the time vector time_vec to your MATLAB workspace, to see it's contents, type:

     time_vec

The column vector time_vec now contains the time values (in seconds) for the samples in sixDOF. Note that the length of time_vec equals the length of sixDOF.

To see how any of the variables in the 6 DOF data vary over time, for instance the x-position (yaw or psi), type:

     plot(time_vec, sixDOF(:,1), 'r-');

This will plot the x-position versus time. This line is drawn from one sample point to another, if you want to see the sample points, type:

     hold on;
     plot(time_vec, sixDOF(:,1), 'bo');

These commands first tell MATLAB not to erase the old plot, then to plot the sample points as blue circles.

 


Step 3 - Setting up the vessel structure

Most function arguments in MVT are based on structures, a structure can hold several values of different classes (e.g. double and char). Structures are created using the .-operator (the dot-operator), structure arrays are created simply by indexing the structure name, see example below. Variables contained in a structure is called a field, see struct for more information on structures.

Structures may be named anything for use with MVT, but the fields must apply to the following convention:

Step 3:

The 6 DOF data and time vector representing one particular vessel must be organized in a structure. In this example we name this structure vesselData. To insert the 6 DOF data sixDOF and the time vector time_vec into vesselData, type:

     vesselData.x = sixDOF;
     vesselData.t = time_vec;

To view the contents of vesselData, type:

     vesselData

This command will describe the contents of vesselData.
To retrieve, or edit, a specific field in the structure, use the dot-operator, for instance:

     vesselData.x

These commands will print the contents of vesselData.x.

 


Step 4 - Starting mvtguide

The function mvtguide calls other functions of MVT in the following order:

If you are an experienced MATLAB user these functions may be called manually (see their help pages for input-output arguments), as mvtguide is only a help function to keep track of input and output arguments.

Step 4:

Call mvtguide with the newly created structure as input argument:

     mvtguide(vesselData)

This command calls the mvtguide function, which in turn prompts the user for input of varios kinds, see following steps.

 


Step 5 - Define type of vessel

By executing the steps above you should now see a dialog box named Settings, this is where you define the type of vessels in youre animation, and what scene the vessels will be animated in. In this tutorial you should select the Cybership vessel model and basin scene model, but any selections are valid (the input 6 DOF data will probably not match any other vessel model).

Step 5:

Select the vessel model named Cybership in the list: Selected vessel is linked to...

Select the scene model named basin in the popupmenu: Select scene:

Confirm your choiches by pressing the OK button. The vessel is now linked to a 3D model, and a 3D scene is selected as the surroundings for the animation. These are passed to the createvrml function.

 


Step 6 - Saving the VRML file

You are now prompted for a filename by createvrml, the requested filename is where the vessel model and scene model are assembled into one single file. You should specify a filename that make it easy to identify later, in this tutorial you should name it my_tutorial.wrl, otherwise the tutorial might not complete.

Step 6:

Enter the filename my_tutorial.wrl and press OK.

 


Step 7 - Setting up a sequence

Two new windows should now appear on your screen, and look like the two figures below. If not, check the error message in your MATLAB workspace. See help on director for detailed information on fields and settings.


Figure of the virtual reality figure window.

 


Figure of the director graphical user interface

The huge donut diplayed in the virtual world is the path of the vessel, to decrease it's size enter a smaller value in the Path Size field. The pool is the selected scene model basin.

Step 7:

To decrease the size of the vessel path, enter a smaller value in the Path Size field, for instance 0.01. You should now be able to see the vessel Cybership, which is positioned according to the first sample in the 6 DOF data.

Select the desired viewpoint from the viewpiont list, viewpoints with prefix vessel move with the specified vessel, while all other viewpionts stay fixed to the scene model.

The selected viewpoint, start sample, end sample, Vessel settings and World settings define a sequence, press the Add sequence button to add the sequence to the total animation. All sequences are listed in the animation listbox, which now should look something like the above figure.

Press Play sequence to preview the sequence.

Press Record to save the animation to file, you are prompted for video settings. The default values should produce a satisfactory result in most cases, but remeber to change the filename to avoid overwriting old video-files. Select or enter the filename my_tutorial.avi. Recording will start, and a bar shows the recording progress. Make sure that the figure window is not minimized or completely covered by other windows while recording, this will ruin the video-file!

 


Step 8 - View the saved animation

When recording is finished, locate your newly created video-file (which was specified just before the recording started) in the file browser, and play the animation!

 


To get to know the functionality of director, experiment by changing the settings, change the viewpoint, record different sample intervals, change the appearance of your vessel, record several sequences into one animation etc.

 

ExamplesTutorial#2