Interactive Anatomy Atlas

A technical explanation

This document describes some of the less obvious behaviors and techniques present in the Interactive Atlas version 2.1b for the Macintosh.

There is user documentation included with the Atlas distribution, and of course like any good GUI program its use is self-evident...and if you believe that, I'm sure you'll believe that the C source code is self-documenting too. But since we aren't going to post the code to the Web just yet, we'd like to describe the internal workings of the application in English for those who are interested.
----- This document is divided into the following sections:

User Interface

There are several well-defined windows in the Atlas program (here's a screen shot to show what we'll be talking about, in case you've never seen the application running before.)

Image Windows
The "Image" window is usually the central focus in any Atlas session. All other windows are designed to float on top of the image, either displaying information about what the user sees in the image or giving control over the session. Unlike most other Macintosh applications, clicking inside an image window does not always bring it to the front; that can be done by clicking in the title bar, which makes it the front-most window and lets the user move it around.

There can be more than one image window depending on how the program is configured and on what the user does. Even if the program is set to show only one image at a time (the default), there is usually at least one "hidden" image window sitting around in memory because of the way navigation works. It is important to realize early on in this explanation that all of the subject lists, the opening splash frames, the help windows, and interactive evaluation screens operate in exactly the same way; only the artwork is different. All these windows consist simply of a bitmapped graphic with various regions outlined as named polygonal buttons. The Atlas program's basic operation is to display one of these images, load the associated list of hot areas, and wait for the user to click on one of them.

Navigation Bar
Glossary Window
Movies Window
Videodisc Controls

QuickTime Animations

[IMAGE]

The original Anatomy Browser had facilities for controlling a videodisc player for the purpose of displaying moving computer-generated 3D models of gross anatomy; this worked well but it's hard to distribute disc platters over the network and besides, not everyone has a videodisc player around. Therefore, we shifted to using QuickTime movies for primary delivery of these materials.

At this time, we do not do any application-defined interaction with the animations. The Atlas has access to a list which associates anatomical structures with appropriate movie file names, and can launch an appropriate movie when the user clicks a button or in response to a script command. Movies are then played by an entirely separate application. The Macintosh operating system (7.0 and later) supports a mechanism called "Apple Events"; in the case of the Atlas, an 'ODOC' event is sent to the Finder to tell it the name of a movie file to open. The Macintosh Finder then runs the movie just as if the user had double-clicked on it. (This can lead to problems on systems which are still running older versions of the operating system, or which do not use the Finder; in the long term we plan to eliminate both problems by supporting movies directly in a window within the application, which will also allow for better control and interaction with the animations.)

Script Execution

Most of the operations that the Atlas program can do, can be triggered by means of script commands. As noted above under "User Interface", any hot area on an image can be defined as a command which will produce some action -- loading a different frame, or starting a movie, perhaps. A sequence of these same commands can be placed into a text file and used to make the program execute a series of actions, or to alter a group of program settings. In fact, the "settings" file which is always loaded by the program immediately at startup is simply a series of script commands; the icons used to start a session are script files as well.

While the script files are contain only ASCII text, it helps on a Macintosh to set things up so that they can be opened conveniently. There is provision for setting a "creator type" on a document which tells what to do when you double-click on it; in the present case, the script files are given a type of 'ANAt' so that they will be opened by the Atlas program. Alternatively, they may be opened manually from within the application by using the "Open" command out of the file menu. This has the side effect of altering a global setting in the running program so that later file accesses will occur within the folder containing the script -- so a script file is often used to set things up for a particular data set, and the program doesn't have to magically keep track of the locations of its data files. (The recommended tool for editing scripts is the TeachText utility, which will open a script file easily as long as it's under 32K).

Now I suppose you'd like to see a list of all the commands and what they do.

Networking

Protocols
When we speak of the Atlas retrieving data objects such as PICT files over a network, we are specifically referring to the capability of establishing a link to a remote server computer through a TCP/IP network using the MacTCP driver. We are NOT talking about AppleShare, where data files (and even the program itself) can be located on a mounted volume -- as far as the client software is concerned, in the latter case the files seem to be located on the desktop and any underlying network transfers are handled transparently by the operating system. That can be a useful method of deploying the software on a local area network but is useless for connecting a client program to a Unix server through the worldwide Internet, which is a primary design goal for this software. Thus, the "network protocols" described here are strictly TCP/IP-based and have nothing to do with AppleTalk.

In early prototypes of our client software, only one server connection was possible at a time and different data types were transferred using different protocols, depending mostly on the knowledge, expertise, and mood of the programmer at the time that each was implemented. Most notably, when transferring image data the client and server used a variant of the 2-channel command/data communication style used by "ftp". This worked but required the creation of a new stream for every image, and never gave satisfactory performance. Since the major complaint against these early versions was its lack of speed, a different approach was taken when implementing the production version.

First, the program can be configured to be standalone, finding its data on locally-mounted disks only; in this case, the network drivers and associated buffers are never opened, saving RAM for other purposes. If the network is enabled and active, then and only then will the program attempt to create a link to a server. These streams are usually set up at the beginning of a session through the use of script commands which specify the IP address and port number of the remote machine. There are actually 4 types of server connections possible:

Images, frame files, and movies come from an IMAGE server through a very simple protocol: when a file is requested, the server sends a short message indicating the number of bytes to follow, then sends the contents of the file. Before initiating most transfers, the client makes a simpler request to find out the size of the file in order to confirm its existence.

Glossary entries and terminology-related queries are made to an experimental STRUCTURAL INFORMATION server which is based on XLisp. Messages are sent and received in a Lisp-like syntax, bracketed with parentheses and using quotes to delimit text strings; each request and corresponding reply are detected by their structure as valid S-expressions.

At the beginning of most sessions, a brief connection to a DISPATCH server provides the client with the addresses that it will use for its other connections; this eliminates most of the need for the client to maintain knowledge of what servers are available. Finally, the LOG server can accept a transcript of the activities recorded by a client during a session, providing an easy way to obtain usage and performance data without manual intervention on the part of the user.

The Image and Structural Information server connections are designed to persist throughout an entire session, both to maximize performance and response times for network transfers and to reduce the load on the server machines.

Techniques

QuickTime movie files produced on the Macintosh are normally saved with both a data and resource fork, and a file type of 'MooV'. Since none of the data servers we use have any provision for storing special files of this type, the files were transferred and stored in the "MacBinary II" format and are separated and stored in the proper format when downloading to the Macintosh client. In the long term we could probably "flatten" the movies prior to storing on the server and just transfer and save the data- fork-only format -- this should help compatibility with non-Macintosh platforms as well.

Performance & Reliability Issues

Some Timing Benchmarks We've observed very good performance in network transfers on local ethernet networks, even using relatively slow client and server hardware. To take two real-world examples, we'll get the numbers for a IIx talking to a NeXT and for a Q950 talking to an Indigo.

ZapTCP Apple's MacTCP drivers have turned out to be reasonably solid after some puzzling situations were ironed out. The biggest problem we encountered was the fact that an improperly closed network stream will eventually cause the client machine to lock up, presumably when the operating system attempts to store incoming data into a buffer which is no longer valid. This happens if the Atlas program stops for some reason or is force-exited prematurely. One solution is to install the "ZapTCP" extension, a small fix issued by an Apple programmer specifically to combat this behavior. With this extension running, a stream that is still open when an application stops will just result in a message to the user, rather than a complete system failure.

Network timeouts can be specified by a script command to keep the Atlas from waiting indefinitely for incoming data. This is most useful for clients using slow or unreliable network connections, for example when accessing a server located in a distant country. There was another mystifying issue, though, having to do with timing: when an image file is retrieved immediately following the corresponding frame file, certain connections exhibit a strange symptom of timing out and reporting the image as "unavailable" even when the server has already sent the data. To fix this, we tried inserting a two-second pause between asking for a frame and an image file, which took care of the problem. A kludge, certainly, but it works and it's not too noticeable.

Data Structures

Most "data structures" used in the program are simple Macintosh memory handles (indirect pointers) to RAM buffers used to hold the contents of files. This maximizes performance in disk and network transfers while yielding acceptable response even when the contents have to be parsed on the fly. (The only noticeable bottlenecks in the program have to do with loading and display of PICT images and QuickTime files; efficiency in other areas of the program has not been a major issue to date).

Handles are allocated and filled for the following kinds of information:

The only data structures worthy of the name are those used for global program settings and per-frame data such as the lists of button names and shapes. Program settings and preferences are stored in fields of a global static C struct; the frame data, which is the symbolic information specific to an image, is loaded into a buffer and then parsed into the following structure: 
typedef struct frame_info {
	int		imgtype;
	PicHandle	imghand; // a Handle to the PICT image data
	long		outline_color;
	int		outline_width, outline_height;
	long		highlight_color;
	Handle		contourlist;	// linked list of contour records
	char		frame_name[FILENAME_SIZE+1];
} frame_info;
The button list is a linked list whose C definition looks like the following: 
typedef struct contour {
	Handle		next;	// indirect pointer to next contour
	RgnHandle	rgn;	// indirect pointer to a QuickDraw region
	int		visible;
	char		name[];	// a variable-length string
} contour;
In memory, it ends up looking like: 
frame_info:
   frame name: "This frame"
   image ---> [PICT image data in separate block]
   outline color: YELLOW
   outline width: 1 pixel
   outline height: 1 pixel
   highlight color: RED
   contourlist --
                |
             contour "ABCDEFG":
               visible: 1
               rgn --> [coordinate data]
               next --
                     |
                  contour "HIJKLMN":
                    visible: 1
                    rgn --> [coordinate data]
                    next -- ...
                              |
                           contour "XYZ":
                             visible: 0
                             rgn --> [coordinate data]
                             next --0

The button records are added to the front of the list in the order that they are read from the frame definition file; this ensures that when hit-testing is performed, matching structures are found in a well-defined way. Specifically, if a small structure outline is traced and inserted in the file LATER than a larger one whose perimeter surrounds it, then it will appear to the user to be "on top" of the earlier one.

Videodisc Drivers

As mentioned above in the section on QuickTime movies, the ability of the program to drive a videodisc player has been largely ignored lately because most animations are delivered in the form of QuickTime files. However, there IS continued support for Sony and Pioneer videodisc players. Sony models LDP-1500 and LDP-2000 will work, and any Pioneer model which responds to the LDV-4200 command set.

The ability to access frames from a videodisc continues to be a viable option for anyone wishing to integrate the software with large collections of images that are available on disc. The Atlas program must be configured to use the correct port, baud rate, and command set, as outlined in the guide which accompanies the program; then an index for each videodisc must be built according to the proper format. The latter step may be time-consuming if done by hand, but once done the result may be useful to many people. Any text editor may be used to do the work. If you have entered the data for a widely-avalable videodisc such as the Slice of Life, we would appreciate receiving a copy of your map file so that it can be distributed and used by others.

The Atlas contains some interface and program gadgets to allow the user to select among multiple possible videodiscs; unfortunately no one has ever actually used anything except Dr. Sundsten's Human Brain Animations disc, and the tools for juggling discs were never brought to completion. In practice, you use a script command (in the "settings" file, most likely) to indicate which videodisc is the default, and the appropriate map is used.