MacInPlot II

October 22, 1992

by
Thomas J. Smith
Department of Biology
Purdue University
West Lafayette, IN 47907


INTRODUCTION:
	
	MacInPlot II is a new version of the previous program MacInPlot.  The old version was written in QuickBasic whereas the new version was written in 'C' using Simantec's 'Think Cª'.  I have kept all of the old options while adding several new ones.  By switching to 'C', the program now is fully compatible with System 7.0, runs much faster, and proper event handling affords proper window updating when windowing between applications.  In addition, I have tried to use pop-up menus and default settings so that the user can run the program more efficiently.

Some of the new options:
1) Reads PDB files

2) Reads FRODO plot files directly and converts them on the Mac to MacInPlot files.

3) Creates and deletes MOL objects such as Ca backbones, zones, and selection according to residue types.

4) Interactive 3-D rotations and two 'Movie' options.  One just displays constant motion on the screen, and the other writes out PICT files for every rotation.

5) Using MOL objects, creates a wire model where the lines are colored by atom type.

6) Writes out updated MacInPlot files and files that can be read into a MacIntosh space-filling program called MacMolecule.

7) Zoom-in and Zoom-out functions.

8) Full 32 bit color.

9)  The background color can be changed and toggled on/off.

10)  Can now read the surface dots created by the 'Surf' option of FRODO's 'MOL' menu.

GETTING STARTED

1) Install the MacInPlot program onto your hard drive.

2) Get the FRODO plot or PDB files from the network.
	**All letters must be UPPER CASE**

3) !!Place the files in the same directory as MacInPlot!!!
	-sorry I have not yet fixed this bug yet.

4) Start MacInPlot.

5) Convert PDB or FRODO files to a MacInPlot file.

6) Open the new MacInPlot file and have fun.

Note:
	When I create a MacInPlot file, I calculate a series of offsets and scale factors that will fit all of the objects into the left hand 1/2 of the screen.  In this way, the objects will stay on the screen during rotations, and there will be room for the stereo pair.  When you perform rotations, I reset the scale factors and offsets back to these original settings.  This may be annoying at times, but will keep you from having to chase your objects around the screen every time you perform a rotation.

OPTIONS:

**Note:  I do not clear and redraw the screen after every menu selection.  Therefore, you may need to 'Clear (ð-D)' then 'Draw (ð-V)' to view the new diagram properly.**

MENU:  FILE

Convert FRODO File:
	User is asked to open a FRODO plot file.  This file must be in the same directory as the MacInPlot application.  If the file contains electron density, then the user can strip away electron density that is not within the cutoff distance to the atomic model.  Note that only the atomic model is used and not Mol objects.  The user is then directed to name the output file - again, in the same directory as the MacInPlot application.  The resulting file is a MacInPlot format input file.  Be aware that if you have a large electron density and decide to use the clip option to remove the unwanted density, it will take some time (curl up to a good book or get some coffee).  For normal files, the files are read and converted in much less than a minute.

Convert PDB File:
	User can open a PDB format file (again, remember that the input and output files must be in the same directory) and create a MacInPlot file.  The user can make bond connections according to the order in which they appear in the list (Link) or according to the distance between the atoms (NoLink).  In the case of NoLink, each atom is checked with the next 10 atoms for whether or not a possible bond exists.

Open MacInPlot File:
	User can open a MacInPlot File.  File must be in the same directory as the MacInPlot application.

Close MacInPlot File:
	User can close this MacInPlot File and open another.  Colors and pen thicknesses are kept.

Write New MacInPlot File:
	The current coordinates are written out to a new MacInPlot file.  The coordinates saved correspond to those displayed on the screen.  For example, say a PDB file was used to make a MacInPlot with the previous option.  The user might then read in the new MacInPlot file and perform rotations and maybe create Mol objects.  The new orientation and Mol objects are saved to the MacInPlot file.

Write MM File:
	An interesting shareware program called MacMolecule can pretty nice space filling and ball+stick models.  However, software does not come with the program to convert normal atomic files to the input necessary for the program.  This option takes the atomic model displayed and writes out the required file.

Write PICT File:
	This option writes out the chosen objects to a file of universal PICT format.  Any Mac program can open and print this file (including TeachText).  Note that all colors (including background) are transferred.  This file is far superior to a bit image since it is really just the binary file of the QuickDraw commands that make up the displayed image.

Quit MacInPlot:
		Kind of obvious.

MENU:  Drawing

Copy:
	Draws all of the objects that you have turned on to the Clipboard.  E.g.  Get the diagram that you like, select copy, then go to another drawing application and hit 'Paste'.  Note that unlike the previous version, you need not quit the MacInPlot program to paste to another application.  The program is completely System 7.0 compatable.  Be aware that you may have objects on the screen that are no longer selected for drawing and therefore will not appear on the clipboard.  It is a good idea to hit 'Clear' and then copy.

Clear:
	Erases the screen.

Draw:
		Draws the objects that have turned on using the options under the 'Select' menu item.  This just displays to the screen and not to the Clipboard.

Line Thickness:
	This is a pop-up menu that allows the user to change the pen thickness of the various objects:  Atomic Model, Mol Objects, E.D. Maps, and Distance Lines.  If the user selects Mol Objects or E.D. Maps, then a second pop-up menu appears to allow the selection of an individual mol object or E.D. Map.  After the object is touched by the mouse yet another pop-up menu appears displaying pen thicknesses of 1-9 pixels.  The initial pen thicknesses are 1 for all objects.  The previous selection of thickness is marked with a check mark.

Line Color:
	This is a pop-up menu similar to the Line Thickness menu item.  If Mol Objects or E.D. Maps are selected, then a pop-up menu appears to allow the user to select which Mol Object or E.D. Map color is to be changed.  After the object is selected, a standard MacIntosh color wheel appears.  The user is shown the previous color selection and allowed to select the desired color.  The intensity slide bar on the right must be moved up from the bottom, otherwise the color will always be black.  Merely click on the desired color at the desired intensity then click on 'O.K.' 

Stereo:
	The user can toggle on/off the stereo image.  Remember to hit the 'Draw' menu item to see the change.

Label Color:
	Using the standard MacIntosh color wheel, the user can change the color of the atomic labels.

Distance Label Color:
	The user can draw lines between selected atoms and place a label on the mid point of this line.  This option changes the color of these labels.

Background Color:
	The user can select the background color.  Be aware that the option 'Background' under the 'Select' menu must be turned on first.  The default color for the background is black -- therefore watch your model colors as you turn this off and on.

Walleyed Stereo:
	When a stereo pair is drawn, it will be with a +6¡ rotation about the screen's Y axis.  This is the 'standard' stereo pair that can be viewed with stereo glasses, or with Marty Feldman's eyes.

Cross-eye Stereo:
	The stereo pair will be drawn with a -6¡ rotation about the Y axis.  This is not the 'standard' stereo image, cannot be properly viewed with stereo glasses, but I can see easily.

MENU: Labels:

Font:
	The program goes to the System file and finds all available Fonts.  These fonts are displayed as a pop-menu.  The selected font will be used for all subsequent labelling.

Style:
	The user is allowed to change the style of all labelling with this pop-up menu.  Each menu item is drawn with that particular style.

Size:
	The user can change the label font size to one of the standard sizes shown in the pop-up menu or some other size by selecting 'other...'.

MENU:  Labelling:

**Note:  you need to create a label before any labels will be properly shown.  See 'Create a Label' of this Menu before proceeding to the other options.**
Hand Pick Atoms:
After creating a label for the atoms, this option allows the user to use the mouse to hand pick the atoms to be labelled.  After this menu is selected, the cursor changes to a




'bulls-eye'.  The 'hot' pixel of this cursor is the center.  Therefore, center the bulls-eye over the desired atom before clicking the mouse button.  This cursor will hopefully help one to remember which interactive subroutine is currently active.  I have tried to automatically turn this option off when I thought it would be necessary.

Move A Label:
After creating a label for the atoms, this option allows the user to move individual labels to increase diagram clarity.  After this menu is selected, the cursor changes to a 




The 'hot' area of this cursor is the upper left corner.  In other words, get the box in the upper left corner of the cursor over an atom before cliking the mouse.  Again, I have tried to prevent unusual behavior by shutting this option off at the appropriate times.  To activate a particular label, just click on the corresponding atom.  If that atom was not previously labelled, it will be now.  Move the mouse to where you want it to be, and click again.  Do not 'click and drag', just click.  You can keep moving the label around with mouse clicks.  After you have selected an atom, the next two items on the menu( 'Keep Label Change' and 'Discard Label Change' ) go from grey to black and can now be selected.  If you like the new position of the label, just select 'Keep Label Change', if you do not, hit 'Discard Label Change'.  You will stay in this interactive mode until you select the 'Move a Label' menu item again, or another of the interactive menu items such as 'Hand Pick Atoms', 'Zoom In', or "Zoom Out'.  These adjustments to the label positions are discarded once you go to any of the rotation functions since I felt that such adjustments would be useless in another orientation.  Be aware that the label movement 'erases' bits of the model as it passes over it.  This is because I did not refresh the screen after each label movement - I found that it slowed the Mac down too much.  The adjustments to the label position are multiplied by a scale factor such that the distance you offset the label at one scale factor is proportionally the same at a different scale factor.

Keep Label Change:
Discard Label Change:
	These two items are used in conjunction with the 'Move a Label' option and are ONLY active once a label has been selected and the user has started the moving process.  These functions are discussed above.

Global Offset:
	Simple routine.  Allows the user to offset all of the labels in the X and Y directions.  Just input the offset (in pixels) in the dialog box and hit O.K.  As with other label offsets, these adjustments are cleared after any rotations are performed.

Reset Label Offsets:
	Erases all label offsets.  After selection the labels are moved to right of the atoms.

Pick From List:
	Allows the user to pick which atoms are to be labelled from a scrolling list of the atoms.  A radio button appears to the left of the various atoms.  Click on this button to select it, again to deselect it.  Scroll to the next 10 atoms with 'Next Page' or back to the previous 10 atoms with'Previous Page'.  A selected atom button is black and an unselected atom is white.  This is an improvement over FRODO in that invidual atoms can be deselected without starting all over again.

Create Labels:
	Allows the user to create the exact type of label to be applied to the atoms.  Each atom has a residue type, residue number, and atom type identifier.  To create a type of label, just select them in the order you wish them to appear.  You do not have to use all three atom identifyers for the labels.  To help you, I have changed the buttons over the various labels upon selection.  For example, say that you decided that the residue type is the first thing to appear in the label.  You click on the button above the label saying 'Residue Type' and the button will change to read 'Item #1'.  Neat, huh?  If you make a mistake, just hit the "Start over" button and do it again.  Every time you enter this routine, I have to purge the memory that these labels reside in.  Therefore, each time you enter this subroutine, you loose the label that you chose before.  However, the atoms that you selected are still flagged for being labelled with the new label.

MENU:  Select:

This menu merely turns the various objects off and on.  Selected objects have a check mark next to them.  When the program is started up, atomic labels are automatically turned on.

Atomic Model:
	Turns the Atomic Model off and on.

Mol Obects:
	A pop-up menu appears to allow the user to turn individual Mol objects off and on.  The program figures out how many mol objects you have and only turns on those Mol Objects (shown in black rather than gray) which exist in the file or have been created by the user.

E.D. Maps:
	A pop-up menu appears to allow the user to turn individual Maps off and on.  If the map exists in the input file, then it appears as a 'selectable' item in black.

Atom Labels:
	Turns the atom labels off and on.  This does not 'deselect' the atoms to be labelled, just hides the labels until you toggle them back on.

Distance Lines:
	As to be discussed, the user can measure distances and put lines between atoms.  This option hides these lines temporarily.

Background:
	This allows the user to toggle the background off and on.  What I am actually doing is filling a rectangle (the same size as the clip area--which is much larger than the diagram itself) and drawing that in the first 'layer'.  Therefore, if you port the diagram over to another application, be aware that the models are on top of a large, colored rectangle.

MENU:  Misc.:

This menu is called Misc. since I could not come up with a clever name for it.

Rotate:
	Allows the user to rotate all objects by inputting rotation angles about the x,y, and z axes.  If you have a color Mac, a multi colored diagram appears in the dialog box to show you the directions of the various rotations.  When you are happy with your input, hit 'O.K.'.  Wait a minute and the screen will clear and the new diagram will appear.  My new option 'Interactive Rotation' will probably be more popular.

Stereo Separation:
	The user can change the separation (in pixels) between the stereo pairs.  Adjustments to the scale factor also adjust this stereo separation.  Say the user is at a scale factor of 100.  If he chooses a scale factor of 200, then the stereo separation will double as well.  I did this to try to fit the most of the objects into the screen and prevent the stereo pairs from overlapping.

Interactive Rotation:
	When this item is selected, a thin bar appears just below the menu bar in the upper left corner of the screen.  It contains a series of  <,  <<,  >,  >>, buttons next to X, Y, and Z labels.  The double marks are for large rotation increments and the single marks are for small increments.  As should be obvious, > means rotate about that particular axis in the + direction, and the < means rotate about that particular axis in the - direction.  The default setting is a 3¡ rotation for a small step and a 10¡ rotation for a large step.  These step sizes can be changed by the next menu item.  **Note, when in this mode, you cannot do any thing but hit one of the buttons in this bar.  When you are done, hit the button labelled 'Done'.

Change Rot. Step Size:
	The user can change the step sizes for the above menu item.  A dialog box appears, and the user inputs the new value(s).  Hit O.K. when you are done.

Create Mol Object:
	If you are familiar with FRODO, the terms used here are the same.  To explain the process in the program may help you to understand how to use the option better.  I have not yet programmed the removal of Mol objects, you can only add to them, and you can only have 10 mol objects (while it is easy to increase this number, 10 is a good place to stop for now).  The input should be self explainatory and is a series of dialog boxes.
To summarize what happens:

-Do you want the Mol object you are about to create appended to the last or to create a new Mol object?

-What type of Mol object will this be?
	-> C-a  (Creates a C-a  Backbone from your atomic coordinates)
	-> Zone (Displayes all atoms within a desired Zone)
	-> Residue Type (Displays desired amino acid types found within 
				a chosen zone).
	-> Mol Balls (Draws a ball of desired diameter at each C-a  position 
			within the chosen zone).

-What zone of the atomic model will be used for this Mol object?

-If the Mol object is to be the 'Residue Type' kind, what amino acid types are to be selected for?
	In this case, you may choose up to 3 different amino acid types to 
	look for.  You can input less than three if you wish.
	**Note:  The program is case sensitive.  Atomic file and your input 
	here should all be upper case.

A new Mol object should now appear in black in the 'Select' menu under the Mol Object menu item.  To view the new Mol object, turn it on with the select menu and then draw the figure (ð-V).

Draw Distance Lines:
	This option measures the distance between two atoms (not Mol objects), draws a line between them, and places a desired label in the middle of the line.  When this menu item is chosen, the cursor changes to the following shape:




The 'hot' pixel of the cursor is in the center of the box in the upper right hand corner of the cursor.  You can turn off this interactive menu item by selecting it again from the menu.  To run this option, simply click on the first atom to label and you should see a box appear about the atom.  Move the cursor to the second atom and click on it.  A dialog box will then appear telling you the distance and asking you for a label.  If you do not want a label, simply delete all of the default text found in the dialog box.  **Note, you are limited to 30 characters.  I felt that more than 30 was a bit verbose.  The color and thickness of these lines can be changed as described under the 'Draw' menu.

Make Atom Color Model:
	This is my most colorful option.  It creates a wire model, based on the atomic model, where the different atom types have different colors.  This is similar to the 'Atom type' option in the 'Bones' version of FRODO and similar also to 'O'.  I thought a lot about how I wanted to do this, and decided that the following was one of the better ways.  I create 4 new Mol objects: 1 for the C atoms, 1 for the N atoms, 1 for the O atoms, and finally 1 for all of the rest of the atoms (in this order).  In this way, the user can select and deselect the items, change the colors and line thicknesses, and when the file is written out with the 'Write New MIP File' option, these Mol objects are saved for future use.  To summarize the input an output:

	-A dialog box appears to ask you for the zone you wish to display
	in this way.
	-4 new Mol objects appear in the 'Select' menu, the order of these 
	new Mol objects is -> C, N, O, others.
	-The program automatically selects the 4 new objects, sets the colors
	to yellow, blue, red, and green respectively.
	-The screen is cleared and all of the selected objects are drawn 
	(including the 4 new Mol objects);

Delete Mol Object:
	When the cursor is dragged over this item, a pop-up menu appears and the user is able to choose which MOL object is to be deleted.  The MOL objects that appear after the deleted object are shuffled up one.  i.e. if you have 3 objects and delete the second one, the third object now becomes the second object and there is no longer a third object.  All of the menus are updated to show the change.  To conserve as much memory as possible, I create a scratch area of RAM, write the objects to that area, and reallocate exactly as much memory is needed after the deletion.  Therefore, the memory usage is maximized ( I also use Handles instead of fixed pointers during the moves).  ***Note:  If, for whatever reason, a Mol object is created that has 0 vectors or objects, it will not be deleted.  This comes from a strict C regulation that says one can not unallocate a block of memory that is empty.
Dot Color:
	FRODO can simulate the surface of a molecule by placing 'dots' at a given radius about the atoms.  This is done by creating a 'MOL' object and using the 'SURF' option within the MOL menu.  I have tried to duplicate these colors when I read the dots in from the FRODO plot file.  The carbon atoms have yellow dots about them, the oxygens have red and the nitrogens have blue.  The default for this pop-up menu is the above 'original color scheme'.  However, I thought that the user might not like this color scheme, and since these dots are in a MOL object, I allow the user to change the color scheme with this menu by selecting the 'New color' choice of this pop-up menu.  If this latter menu item is selected, then all of the dot colors will be changed to the color of that particular MOL object.
Dot Size:
	The size of the dots can be changed with this pop-up menu.  The default size is 2 pixels in diameter.  The previous selection is marked with a check mark.

MENU:  Size & Pos.

Change Scale:
	Allows the user to change the scale factor applied to the models.  A dialog box appears, displays the old value, and asks the user for a new value.

Zoom In:
	You can now 'Zoom In' on a particular atom in the atomic structure.  This is handy for the 'Hand Pick' and 'Draw Distance Line' options.  Note that you MUST select an atom to zoom in on.  I need an atom for a reference point to calculate the offset and scale factors.  Therefore, if your MacInPlot file only contains Mol objects, this option will not work (nor will the 'Zoom Out' option work).  This interactive menu item can be toggled off by choosing again from the menu.  When this option is activated, the cursor changes to:




Simply click on an atom.  The chosen atom will be placed in the center of the screen and the size of the objects will be increase by 1 1/2.  Unlike FRODO, you do not have to have the atomic structure displayed at the time of selection, but you must have the atoms in the file.

Zoom Out:
	Pretty much the same as Zoom In except the size of the objects are decrease by 1/2.  When this option is active, the cursor changes to:




Again, you need to select an atom, and the selected atom is centered in the middle of the screen.

Reposition:
	This option allows you to move the objects around the screen.  You do not have to select an atom.  When you select this option, a dialog box opens to remind you of how to use it.  All you need to do is to click on a part of the object where it currently is and then click on the position that you want it to be.  This is the same as a 'Click and Drag' option found in many graphics programs except you do not 'Drag' the mouse.  I did not want to use the 'Drag' method (where the screen needs to be refreshed when the mouse is moved) because with a lot of vectors, or with the old Mac SE and Plus, this is excruciatingly slow.

Do Movie:
	This is a fairly useless option, but was only a couple of lines of code--so what the heck.  When you select this option, you are given the same dialog box found in the 'Rotate' option.  You can input the rotation you wish each step of the movie to be.  After this, the objects that are currently selected begin to rotate.  To stop the movie, just click the mouse within the window.

Make Movie PICTS:
	This is the same as the last option except that for each rotation, a PICT file is written out.  The process continues until the mouse is clicked on the image.  The files are created in the local directory and start with the name 'Frame0' and numbered sequentally after that.  We have used this option to readily create a movie using MacroMind Director.

Slab...:
	This menu option allows the user to 'slab' or to trim the image on the front, back, top, bottom, left, and right sides.  A window appears with + and - buttons next to the words front, back, top, bottom, left and right.  For example, if the user selects the  
 button next to the word top, then the image gets trimmed down on the top.  If he had selected the 
, then the image would have gotten larger at the top.  Some notes as to this procedure.  1)  The image gets trimmed down by 5% of the maximum width of the image for each press of the button, and 2)  the slab is with respect to the screen coordinate system.  Therefore, as a slabbed image is rotated, you will see different vectors appear and disappear.  This is the same idea as used in FRODO, except FRODO only uses a uniform slab in the front and back of the image.  3)  When you copy this image to the Clipboard or to a PICT file, the vectors which have been slabbed away, will not appear in these files.  4)  I cheated.  FRODO will trim each vector where MacInPlot either keeps or deletes entire vectors.  This was done for the sake of speed and memory.  Sorry, this may make smaller images look a little ragged around the edges.  Smaller Macs could not handle what I would have to do if I were to do it properly.

Reset Slab:
	This option resets all of the slabs to get back to the original image.

********************************************************************************************
	This is the first release of this new version, and I certainly do not claim to have found all of the bugs.  If you run into problems, please let me know as soon as possible.


Input Files:

	The MacInPlot file is a normal ASCII file that is read as free format.  The input values are read in the following order.

MacInPlot File:

xmin, xmax, ymin, ymax, zmin, zmax [all floating points]
(the min and max values for the x, y, and z coordinates)

number of atoms, number of vectors in atomic model, number of Mol objects [all integers]

number of vectors in each Mol Object [integers]
(one value per line, one value per Mol object)

X, Y, Z, residue number, residue type, atom type [3 floating point, 1 integer]
(for i=0 to i<number of atoms)

X, Y, Z, action [3 floating point, 1 integer]
(for i=0 to i< number of vectors in atomic model
action =0 for MOVE, and action=1 for DRAW)

X, Y, Z, action [3 floating point, 1 integer]
(for i=0 to i< number of vectors in each Mol Object--
Mol Objects are one right after another)

Number of electron density maps [integer]

Number of electron density vectors [integer]
(for i=0 to i< number of electron density maps
one value per line)

X, Y, Z, action [3 floating point, 1 integer]
(for i=0 to i< number of vectors in each electron density map--
electron density maps are one right after another)