MacResearch

Author: Drew McCormack
Website: http://www.maccoremac.com

This is the third and final tutorial on integrating the VTK 3D visualization libraries into a Cocoa application. In part 1, we setup the Xcode project; in part 2, we added source code for our model and controller; and this time round we are going to work in Interface Builder to finish off the UI, and hopefully end up with a simple, but functional, Cocoa-VTK application.

Importing Classes

If you have been following along in your own project, open it up now. Otherwise, you can download the source code from last time, and use that as a starting point.

The first step is to import the various classes that were written last time into Interface Builder (IB), so that IB knows about the actions and outlets available. Begin by double clicking on the MoleculeDocument.nib file in the Resources group in the Groups & Files tree on the left of the Xcode project window. You should see Interface Builder start up, and a single document window appear with the text ‘Your document contents here’. We need to remove that text, so click on it to select, and press backspace to remove it.

To import the vtkCocoaGLView class, click on the Classes tab in the MoleculeDocument.nib window, and choose the Classes > Read Files… menu item. Navigate to the include files directory of your VTK installation, choose the vtkCocoaGLView.h file, and press the Parse button.

For the classes in the Xcode project, it is easier just to drag them into IB. Locate the MoleculeDocument.h file in the Groups & Files tree of Xcode, and drag it to the MoleculeDocument.nib window in IB. Repeat for the BasicVTKView.h file.

Laying Out the Window

Now we need to start adding the elements of the UI. We are aiming for something like what is shown in the screenshot below.

First, change the nib files owner to an instance of the MoleculeDocument class. The file owner is the object that loads the nib file; in this case, it is our MoleculeDocument.

1. Click on the Instances tab of the MoleculeDocument.nib window.
2. Select the File’s Owner icon.
3. Bring up the inspector using the key combination Command-Shift-I.
4. Select Custom Class from the popup button in the Inspector.
5. Choose MoleculeDocument from the list of classes.

We will now move to the document window itself. For simplicity, we will prevent the user from resizing the window. To do this:

1. Click on Window in the Instances tab of the MoleculeDocument.nib window.
2. Select Attributes from the popup button in the Inspector.
3. Uncheck the Zoom checkbox to prevent resizing.

We need a custom view now, which will be used for the 3D visualization. This will be an instance of the BasicVTKView class.

1. Open the IB palettes window by choosing Tools > Palettes > Show Palettes.
2. Find the Cocoa Container Views tab. This is usually sixth from the left.
3. Drag the CustomView onto the document window.
4. Click on the CustomView to select it, and resize it to fit in the window, leaving space at the bottom for other controls (see screenshot above).
5. With the custom view selected, bring up the inspector using Command-Shift-I.
6. From the Inspector’s popup button, choose Custom Class.
7. Choose BasicVTKView from the list of classes.

Now we need a slider, to control spring stiffness between the atoms, and a button to stop and start the animation.

1. Go to the Cocoa Controls palette (usually second from the left).
2. Drag the standard glass button in the top left corner to the bottom of the window.
3. Bring up the Inspector, and choose Attributes from the popup button.
4. Enter ‘Play’ for the Title, and ‘Pause’ for Alt. Title.
5. Choose ‘Rounded Bevel Button’ from the Type popup, and then ‘Toggle’ from the Behavior popup.

For the slider, follow this procedure:

1. Drag a slider from the same palette used for the button, and center it above the button (see screenshot above).
2. Select the slider, and choose the Attributes pane in the Inspector.
3. Setup the attributes of the slider as shown in the screen shot below. The most important settings are the Minimum (0.5), the Maximum (2.0), and Current (1.0).

Connecting it up

All that is left to do is connect up the various actions and outlets defined in our controller class. We’ll begin by connecting the vtkView outlet of the MoleculeDocument instance to the custom view in the document window:

1. Hold down the Control key and drag from File’s Owner in the MoleculeDocument.nib document to the BasicVTKView in the document window (see screenshot below).
2. Choose Connections in the Inspector popup button, and then select the Outlets tab.
3. Select the vtkView outlet, and click the Connect button.

Now we need to connect up the Play button, so that when it is pressed, the animation is stopped or started appropriately.

1. Control-drag from the File’s Owner icon to the Play button, and choose playStateButton outlet in the Inspector, and press Connect.
2. Control drag from the slider to the File’s Owner. Select the Target/Action tab in the Connections pane of the inspector, select updateStiffness:, and press Connect.
3. Control drag from the Play button to the File’s Owner, select the togglePlayState: action, and press Connect.

Now save your changes, return to Xcode, and press the Build and Go button. Hopefully you will see the complete Animoltion app.

If you just want the complete source code, download it here.

Animolting

Animoltion is not exactly rocket science. Just press Play to start the animation and Stop to pause. Pressing Play again will cause the animation to continue from where it was paused.

The stiffness slider has until now been somewhat mysterious. If you move the slider to the right, you should see the molecule become stiffer, with the atoms vibrating more rapidly but not moving as far. Moving the slider to the left makes the molecule more floppy, with the atoms vibrating less rapidly, and traveling farther.

Apart from the controls we have built into Animoltion, VTK brings several of its own to the table. Clicking and dragging on the 3D view rotates the molecule, for example. Control-Shift-click and drag up or down zooms in and out. Shift-click and drag translates the view sideways. Control-click and drag causes the view to rotate around the line of sight.

Sometimes you will notice that the atoms move outside the view, or come too close to the camera and are chopped off. In such instances you can press “r”, to reset the camera location. You might also try pressing “w”, which shows the atoms in wireframe; pressing “s” makes them solid again.

Scratching VTK’s Surface

In the comments of the last tutorial, Justin Mitchell posed the question: ‘What can you do with VTK that you can’t just do with OpenGL directly?’ Good question. Here is my response:

Of course, I have chosen a very simple example, one that is quite simple to do in OpenGL, since it only works with spheres. But VTK has much more, and it is nearly all about visualizing data. OpenGL just gives you the primitives to draw with; VTK tells you what to draw. It’s like the difference between a 2D graphics engine like Quartz 2D, and a plotting framework. The plotting framework sits on top of the drawing engine.

Just to get you a bit of an idea of some of the things you can do with VTK, take the example of a scalar field or density. With maybe 20 lines of VTK code, you can generate an isosurface or volume rendering of the data, complete with user interaction (rotating, translating etc). With another 20 lines or so, you could add a cut plane to it. The point is not that you can’t do this with OpenGL yourself, but it will take you thousands of lines. Effectively you will be implementing the same sorts of algorithms (eg marching cubes) that are already built into VTK.

That’s it for this little foray into 3D visualization in Cocoa. I have concentrated on the technical aspects of just getting VTK integrated into a Cocoa app, and haven’t spent much time on VTK itself. We are working on getting a few tutorials on VTK itself, so stay tuned if this is something that interests you.