User Tutorial - Working with Videos

Updated for version mgui-1.0.20-alpha

This tutorial takes you through the steps of setting up a video sequence, running it, and writing it to a series of image files. The final section describes how to convert these image files into a video file, using VirtualDub or avconv software.


Videos in ModelGUI are a means of adding a temporal dimension to your shape models; i.e., by changing camera angles, shape morphology, attributes, vertex data, and so on. This is a powerful way to visualize both static and dynamic data, and also allows shape models to be represented persistently as video files. The following tutorial explains the basic concepts underlying the way videos are specified and run in the ModelGUI session. A description of how to convert these videos to files is also provided.

For this tutorial, if you are using Windows, you will need to download VirtualDub software, a freely available video production tool which will allow you to produce and fine-tune your video output. If you are using other OS platforms, see "Other platforms" at the end of this tutorial.

You will also need to download this Shape Model file, so we have something to visualize:


Setting up a session

First we need some shapes and a 3D window to render. To do this, open the File Panel expand the "Input" section, select "ModelGUI Shape Models (*.smod, *.smod.gz)" as the file type, click "Browse", and navigate to the "user-tutorial-videos.smod.gz" file you downloaded above. Now click "Read Data", and your shape model will load. To view it, right click anywhere in the window space (under "Tab1") and select "New window > Graphic 3D Window". Next, to set the current model as this window's source, right-click again and select "Set source > Default Model". You screen should now look like:


* Note: this file includes the geometry for the Civet template surface (see here), and its corresponding Laplacian field (see here).

Setting up a video

Now we're ready to play with the video GUI. Go to the Windows Panel and expand the "Video (3D)" section. The UI looks like this:


To get started, we'll want to create a new video, so click "New" and call the video "spin_360". The new video will be current, with a default duration of 1 min:


Video tasks

Videos are specified as a set of scheduled tasks, which manipulate shapes, cameras, attributes, etc., at specific time points during the video playback. Tasks are displayed in the Task List. To add a new task to the list, click "New task". Three types of task are currently available (more types are planned):

  • SetView3D: Sets the camera of the 3D window to a specific view
  • RotateView3D: Rotates the camera of the 3D window about its X and Y axes
  • AttributeUpdate: Allows object attributes to be altered
  • ChangeSections: Iterates the current section of a 2D window between two sections

For our simple video, we want to do two things:

1. Set the initial view to left, sagittal
2. Rotate the camera 360 degrees ($2\pi$ radians) about its Y axis

This involves two tasks. First, add a SetView3D task, set the start and stop times both to "00:00:000", and choose "sections_sagittal" as the target view. Unselect "Set zoom" and "Set target point", and the dialog should look like this:


Second, add a RotateView3D task, setting the start time to 00:01:000 and the stop time to 00:30:000 (30 s of rotation). For the Y angle, which must be specified in radians, type "2pi" ("pi" will be recognized and converted to its actual value):


Video playback

The tasks we have created now appear in the TASK LIST. You can edit a particular task by selecting it and clicking "Edit". Notice that the Set View 3D task is coloured pink. This indicates that the task is currently active (since it begins at 00:00:000). As playback continues, tasks will appear pink in this list while they are active.


Video playback is controlled by the buttons under the CONTROLS heading. These buttons allow you to start, stop, and reset the video playback:


Playback will continue for the duration specified at the top of the section. In our case, this value is currently set to the default of 1 min. Since our rotation is only 30 s, we want to change this value to "00:30:000". After doing this, click "Update" to effect the change.

Now we're ready to go. Click the Forward button (>) and the brain should first align itself sagittally and then start to spin clockwise. The timer will display the elapsed time. Try the Stop (||) and Reset (|<) buttons to get a feel for how the video controls the 3D display.

One hint here: depending on your graphics card, the 3D axis displayed at top right may cause the playback to be choppy. You can turn this axis off by right-clicking on the window, selected "Edit attributes" under "Graphic3D Window", and unchecking the "ShowAxes" attribute.

Writing to an image stack

Videos can also be written to disk, as sets of sequential screen capture images, and then made into video files using your third-party program of choice — for Windows platforms, we prefer VirtualDub, as explained in the next section. To write a video to disk, click "Browse" under the OUTPUT heading and select the folder where you want the images to be written. Next click Options, and the following dialog box will appear:


This allows you define the number of images (or frames) per second, and the start and stop time of the video. The "wait for" value forces the video to wait the specified interval between screen captures. Longer values of this are useful if you expect the renderer to lag after changes — due to complex shape models, for instance. The "use offscreen buffer" currently does nothing*. Here, we only want to set the stop time to "00:30:000" and click OK.

Now we're ready to record our video. Reset the video to "00:00:000", if you haven't already done so, and then click "Write". The video will play at a much slower rate, and the png images will be written to the folder you specified.

Working with VirtualDub (Windows)

Now we can make a video file. Assuming you downloaded and installed VirtualDub, as above, you can run the program now. Select File > Open video file… and navigate to the directory containing your images. Select the first image and click "Open". The screen will now show a sequence of all the files in the directory:


Next we want to set the frame rate to match the one we specified in ModelGUI. Select Video > Frame Rate, and the following dialog box appears. Select "Change frame rate to (fps):" and change it to 30. Click OK.


Choosing a codec

Video codecs specify how a video file should be compressed and decompressed. Your decision of codec will depend on how you want to use the video. Some codecs are optimized for high definition, others for online video streaming, and others for mobile devices. You may also simply want to make the video widely available, and so choose a standard codec which will work on all platforms without the need for downloading anything.

First, we will use the "Cinepak Codec by Radius" codec. It's not the world's best codec, but it is pretty standard, so it should be good for dissemination across different platforms.


Now select File > Save as AVI.. and specify a video file for your output. The video will be constructed.

A better (but non-standard) codec is x264, which can be downloaded here. You may have to restart VirtualDub to see this codec. When we select the codec "x264vfw…", the dialog informs us that this codec has a few format restrictions: the images must be of even size, and the colour depth must be either 24 or 32-bit. As a little trick suggested by the x264 developers, click "Configure", and check the "VirtualDub Hack" box, then OK.

Click OK, and then select Video > Filters… This dialog will allow you to ensure the image size meets the codec restrictions. This step is only necessary if your image dimensions are not factors of 2. If such is the case, select Add.. and "resize", and the following dialog box appears:


Under "Codec-friendly sizing", select "Multiples of 2", and then OK. The resize filter will be added and everything should be good to go. As before, select File > Save as AVI… and select a file name for your video. We can now compare the two videos. Note that you can play with the configuration to fine-tune the output. There is a slider in the x264 configuration dialog which allows you to improve quality (at the expense of compression). Find a codec and configuration that works for you.

Other platforms

Software also exists for Linux and Mac to create videos from image stacks.


For Linux, the standard option is avconv. You can generate a video file from the terminal window with the following command:

avconv -i spin_360_%03d.png -r 30 -b:v 5000k video.mp4 -c:v libx264

Here, the option -i specifies the input files; where "%03d" is a wildcard specifying sequential three-digit numbers, as are output from mgui. -r specifies the frame rate (30 frames per second). -b specifies the bitrate (in this case 5000 kB/s); increasing this increases quality but also file size. -c:v specifies the video codec for the output (use avconv -codecs to see a list of available codecs). Again, you'll want to select a codec based on your intended audience, bearing in mind that some codecs are not standard on some operating systems…

Note that avconv has many options. You can play around with them, using Google to help you figure things out and fine-tune your output.

Mac OS

For Mac OSX, you can also use avconv, although you will need to install it first. If you have Homebrew installed, you can simply run:

brew install libav

A word about video screen capture

Another method of constructing a video from ModelGUI is via a video screen capture program, such as Camtasia Studio for Windows (not free), or QuickTime for Mac OS. You can experiment with this approach; however, we've found that the continuity of the resulting video is less than optimal… Still, this approach may be ideal for demonstrations, tutorials, etc.


See the ModelGUI Vimeo channel for some examples of videos produced with mgui.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License