Purdue University
Purdue e-Pubs Computer Science Technical Reports
Department of Computer Science
1996
Tonitza A Graphics Package for Structural Biology User's Guide Ioana Maria Martin Dan C. Marinescu Report Number: 96-022
Martin, Ioana Maria and Marinescu, Dan C., "Tonitza A Graphics Package for Structural Biology User's Guide" (1996). Computer Science Technical Reports. Paper 1278. http://docs.lib.purdue.edu/cstech/1278
This document has been made available through Purdue e-Pubs, a service of the Purdue University Libraries. Please contact
[email protected] for additional information.
TONITZA
A GRAPIDCS PACKAGE FOR STRUCTURAL BIOLOGY USER'S GUIDE
Ioana M. Boier Martin Dan C. Marinescu Department of Computer Sciences Purdue Unlverslly West Lafayette, IN 47907-1398
CSO TR-96-022 AprU 1996
TONITZA A GRAPHICS PACKAGE FOR STRUCTURAL BIOLOGY
User's Guide
by
Ioana M. Boier Martin and Dan C. Marinescu Department of Computer Sciences Purdue University West Lafayette, IN 47907-1398
March 1996
II
TABLE OF CONTENTS
Page LIST OF FIGURES
· IV
ABSTRACT . . .
· vi
I. INTRODUCTION
1
2. THE GRAPHICAL USER INTERFACE.
1
3. THE INPUT/OUTPUT MODULE
1
3.1 File Formats . . . . . . .
3
3.1.1 The BRICK Format. . 3.1.2 ThePLANE-BY-PLANEFormat 3.1.3 The MAP INTEGER*2 Format 3.1.4 The SOl Format . . 3.1.5 The TIFF Format. . 3.2 ReadingfWriting Data Files
3
3.3 Defining Grid Properties . 3.4 Saving the Current Session and Exiting Tonitza
5 5 6 6 6 9 .10
4. THE COMPUTATION MODULE .
.11
4.1 Data Rotation. . . . . . 4.2 Correlation of Data Sets . .
.11
4.4 Graphs and Histograms. . . .
· 11 · 12 .13 · 15 · 16 · 17 · 18 .18
5. THE VISUALIZATION MODULE.
.20
4.2.1 Plot Average Density 4.2.2 Compute Optimal Magnification. 4.2.3 Refining the Correlation Regions 4.2.4 Compute the Scaling Function. . 4.2.5 ShowlModify Correlation Parameters. 4.3 Composite Map Calculation
III
Page 5.1 2D/3D Representations. . . . 5.1.1 Sections . . . . . . . 5.1.1.1 Types of Sections 5.1.1.2 The Colormap Editor. 5.1.2 Volumes . 5.1.2.1 Isosurfaces . 5.1.2.2 The Material Editor . 5.1.3 Manipulating Sections and Volumes 5.2 Animating Objects. . . . . . . . . . 5.2.1 Animating Objects Using the MouselDials. 5.2.2 Recording Images and Producing Movies 5.3 Image Processing . . . . . . . . . . . . .
.20 .20 .20 .25 .27 .27 .29 .31 .31 .32 .33 .33
6. IMPLEMENTATION NOTES.
.35
6.1 The OpenGL Library. . .
.35 .35
6.2 The EX Interface Builder .
6.3 The Organization of the Program Modules in Tonitza . 6.3. I The Main Program 6.3.2 Creation Routines . . 6.3.3 Callbacks. . . . . . 6.3.4 Input/Output Routines. 6.3.5 Drawing Routines . . 6.3.6 Routines for Generating Object Representations
6.3.7 Routines for Object ManipulationlCustomization 6.3.8 Computation Routines. . . . 6.3.9 Routines for Defining the Fonts 6.3.10 Error Handling Routines 6.3.11 Utility Routines.
APPENDIX
.36 .36 .36 .36 .37 .38 .39 .39 .41 .42 .42 .43
.
.44
ACKNOWLEDGMENTS
.47
BIBLIOGRAPHY . . .
.48
IV
LIST OF FIGURES
1. A snapshot of the screen during a Tonitza session.. . . . . . . . . . . . . . 2 2. Header information window. 3. File selection box.
. . . . . . . . . . . . . . . . . . . . . .7
.
8
4. Data rotation window.
.
5. Dialog window for defining grid properties.
. . . . . . . . . . . . . . . .9
6. The correlation steps.
8
. . . . . . . . .
. . . . . 13
7. Average electron density as a function of the particle radius (2D plot)
14
8. Average electron density as a function of the particle radius (3D plot)
14
9. Correlation coefficient as a function of the particle radius.. . . . .
15
10. A plot of the correlation coefficient as a function of the particle radius.
I!. The "Show Parameters" window.
.
16
. . . . . . . . . . . . . . . . . . . 17 . . . . . . . . . 19
12. The histogram window.
13. Electron density histogram for a Ross River virus structure. . . . . . . . . . 19 14. Dialog window for defining contouring parameters.
. . . . . . . . . . . . 21
15. Dialog window for defining continuous scale parameters
21
16. Dialog window for defining spherical sections. . . . .
22
17. A snapshot of the contents of the command area for sections. 18. Dialog window for defining contour stacks.
. . . . . . . . 23
. . . . . . . . . . . . . . . 24
v
19. Stack of mask contour maps for a Coxackievirus B3 asymmetric unit. . . _ . . 24 20. Spherical sections viewed along the two-, three-, and five-fold axes.. _ . . . . 25 21. The colormap editor.
.
26
22. Dialog window for defining the isosurface parameters. . . . . . _ . . . . . 28 23. A snapshot of the command area for volumes.
. . . . . . . . . . . . . . 29
24. The material editor. . . . . . . . . . . . . . . . . . _ . . . . . . . 30 25. Dialog window for printing images.
. . . . . . . . . . . . . . . . . . 32
vi
ABSTRACT
Tonitza is a graphics package for Structural Biology which provides capabilities for visu-
alizing scinetific data sets in various two- and three-dimensional representations and for combining visualization with specific computations to allow the biologist to interpret and
debug hislher data. This guide contains examples and step-by-step instructions for using the package.
I. INTRODUCTION
Tonitza is an interactive graphics package which is relatively easy-la-use and easily extensible to include new features. It has been specifically designed to deal with large data
sets, such as those produced in X-ray crystallography and electron microscopy experiments. Although it is aimed at the field of Structural Biology, Tonitza can be used to visualize any vector field data. Tonitza consists of a graphical user interface (GUI), input/olltput, visualization, and
computation modules. This document provides step-by-step instructions for using the package. All examples are based on data sets representing Ross River or Coxackie B3
virus structures [CHEN95j, [MUCK95].
2. THE GRAPHICAL USER INTERFACE
Tonitza incorporates a variety of interface styles. The main style is that of a directmanipulation user interface [FOLE90], in which the objects and attributes that can be
operated on are represented visually and operations are_ invoked by actions performed on the visual representations, typically using the mouse. However, this interaction style is not sufficient by itself and other interface styles such as menus are also included. Figure 1 shows a snapshot of the screen during a Tonitza session.
3. THE INPUT/OUTPUT MODULE
The Input/Output (I/O) module is responsible for reading/writing data files from/to the disc, for automatic file format recognition, for conversion between fonnats, and for handling I/O errors.
2
Figure 1. A snapshot of the screen during a Tonitza session.
3 3.1. File Formats Conceptually, each file consists of a header followed by data. The header usually contains a magic number (for format identification), some comment about the contents of the file, the dimensions of the file and other statistical information (e.g. minimum and maximum data values, background value, etc.). You can display the header information by choosing the Show Header Info option from the File or Options menus. Figure 3
shows the contents of the header window for a file in the MAP INTEGER*2 format. The dialog box at the top of the window al10ws you to specify the name of a file for which you
wish to display the header information. You can type the full path of the file in the dialog box or you may press the " ..." button and select a file name from a list of files already opened. The data follows the header and it may be compressed or not (if it is compressed, some compression information may be stored between the header and the actual data). The data values correspond to a two- or three-dimensional vector field. The rest of the section describes in detail the formats accepted in Tonitza version 2.0 . Note that the program can be easily modified to include other formats.
3.1.1. The BRICK Format A file in the BRICK format [ROSS94] consists of a header (64K) and a set of sequentially stored bricks of data. A brick is a 3D volume consisting of a number of consecutive grid points. For each grid point, the information is packed into two bytes: 10 bits electron density and 6 bits mask. Note that for h-cell data in this format only electron density information is be available. Given a 3-D mesh of na x nb x nc grid points, from iix to ifx in the x-direction, from iiy to ify in the y-direction and from iiz to ifz in the z-direction, we have: na = ifx iix + 1, nb = ify - iiy + 1, and nc = ifz - iiz + 1. A brick is a 3-D volume consisting of bx x by x bz consecutive grid points. Currently bx = by
= bz = 16. There are 4096 grid
points within a brick and the storage space occupied by a brick is 8K bytes. The grid points within a brick are stored in the x --+ y --+ z order. We can look at the bricks as a 3-D structure consisting of layers of bricks stored in
4 the x
--7
y
--7 Z
order. Call "ibrick", '1brick", "kbrick" the number of bricks in the x, y and
z direction respectively. The values "ibrick", "jbrick", "kbrick" are computed as follows:
ibrick
= (na -
l)/bx + l,
jbrick
= (nb -I)/by + l,
kbrick
= (nc -I )/bz + 1 ,
ijbrick = ibrickxjbrick The brick reference point is the brick point closest to the origin of the 3-D brick space. Given the brick with 3-D coordinates (ibid, jbid, kbid) its reference point has the 3-D coordinates (istart,jstart, kstart) given by:
istaet = bx x (ibid - 1) + iix. jstart = by x (jbid -I) + iiy, kstart = bzx(kbid-l)+iiz.
The relation between local and global coordinates of a grid point is as follows. Assume that you are given (ij,k) the local coordinates of a point in brick "bid" with the reference point (istart, jstart, kstart). Then its global coordinates (iglobal, jglobal, kglobal) are given by: iglobal = i + istart - I, jglobal = j + jstart - I, kglobal = k + kstart - I. The bricks are stored sequentially in the x ~ y
I
~
z order.
Brickl I Brick 2 1
1 BriCknb1
The brick with 3-D brick coordinates "ibid", "jbid", "kbid" is stored sequentially as brick "bid" with: bid = (k - 1) X ibrick x kbrick + (j - 1) X ibrick + i. The first layer of bricks (z=l) contains ibrick x jbrick bricks: (I,
2, ......
(ibrick + I, .....
(ibrick x (jbrick - I) + 1 ..........
ibrick),
2 x ibrick),
ibrick x jbrick)
The total number of bricks is: nbr = ibrick x jbrick x kbrick. Note: The brick format is used to store both the p-cell (which contains either the mask or the electron density and the mask) and the h-ceU which contains only the electron density.
S For the h-cell the computation of the mesh geometry is similar to the one described above for the p-cell: mx :::: ifhx - iihx + I, my :::: ifhy - iihy + 1, rnz :::: ithz - iihz
+ 1, ibrickh::::
(rnx-l) I bxh + 1, jbrickh = (my - 1) I byh + 1, kbrickh = (mz - I) I bzh + 1, ijbrickh =
ibrickh x jbrickh, nbrh:::: ibrickh x jbrickh x kbrickh.
3.1.2. The PLANE-BY-PLANE Format A file in this format [ROSS94] consists of a header (64 KB) and a set of sequentially stored y-planes of data. This data format is used to export results produced by envelope to fftinv or to import from fftsynth new electron density data.
3.1.3. The MAP INTEGER*2 Format
In this case, the data file consists of a header and a set of sequentially stored "sections" of data [BAKE95]. Each data record contains a row of density values. This structure is summarized in the table below:
REC#
DESCRIPTION
1
1*4
magic number:::: -3
2
18A4
map title
3
31*4, SF
mow, ncol, nsec, mapmin, mapmax, aoverb, abang, scalef
4
6F
a, b, c, alpha, beta, gamma
S
3F, 61*4
deja, delb, dele, tmatrix
6
ncol1*2
a row of data
...
...
...
nrow*ncol+6
...
...
6 3.1.4. The SGI Format This is a generic bitmap fannat used for storing black_and-white, graYRscale, and color images [IMAG94]. SGI files may contain compressed or uncompressed data. In the
former case, the file consists of a 512 bytes header, a scanline offset table and compressed image data. In the latter
Ca
