Digital Anatomist Server Installation Guide

This installation has been test on CentOS 7.5 and Apache httpd 2.46, last installed 2018 June 12 by jfb.

Directory Naming

The Digital Anatomist utilizes two main source directories and several links to subdirectories within these source directories. Each of the source directories should be located at the root level of your Web document directory on your Web server.

The first source directory is DA-5.2.x (where x is the current minor release number), which was created when you untarred the distribution file. This directory contains all the source code, documentation, and java classes that are needed to create the necessary cgi programs. When the source is compiled the executables are placed in the bin subdirectory of this directory.

The second source directory is DA-ATLASES. This directory contains the atlas contents that are created by the Framebuilder tool and are accessed by the cgi programs. Each subdirectory within DA-ATLASES constitutes an atlas. DA-ATLASES is separated from DA-5.2.x in order to separate the atlas content from the atlas software. This way, when updates are made to the software the DA-ATLASES directory does not need to change.

Links are used to further simplify the update process. The link DA points to the most recent version of the software. Once this release is installed it will point to DA-5.2.x. Similary, the link, /cgi-bin/DA will point to DA/bin, where cgi-bin is the location of your server's cgi-bin directory.

When a new software update arrives, the installation procedure involves changing a few variables in files in the source code directory, typing `make' to compile the source code, then typing `make install' to install the compiled code. The links are created by this latter command.

Within the DA-5.2.x (DA) directory are the following files and directories

/bin/DA
Binary exectuable CGI programs once they have been compiled.The DA subdirectory is kept for backward compatabiliy with earlier versions.
/classes
Java class files for running the FrameBuilder program to annotate your images.
copyright.html
Software copyright that is linked to from every atlas. Each individual atlas can also have its own content copyright.
/docs
Documentation.
framebuilder.html
Home page for FrameBuilder. This page loads the FrameBuilder Applet.
/gifs
A few small GIF files that are used in the atlas software.
index.html
Index containing links to the list of atlases on this server, FrameBuilder, and documentation. This is the default page to which the atlas "Top" button links.
/local
Local configuration. Files in this directory must be edited during the installation, in addition to framebuilder.html.
/logs
Contains files the help resolve error messages, called ETABs, and will also contain the log files of the CGI programs, once they start being used.
/src
C and java source code.
Test
A test atlas that will be installed as a link from your DA-ATLASES directory so you can test the programs.

Other directories that may be referenced:

cgi-bin
This refers to DA/bin, which should be designated in your httpd virtual machine configuration (see below) to be referred by the URL: http://your.machine.addr.here/cgi-bin/.
"web server document root"
This refers to the directory that is the top level directory visble from the web. The URL that points just to your machine, with no path after it, points to this directory.
"atlas directory"
When referring to an atlas's directory, this means the directory for a specific atlas, inside DA-ATLASES. For example, if your server has a 'Thorax' atlas, the Thorax atlas's directory would be DA-ATLASES/Thorax.

Configuring the Software

Before you can compile the Digital Anatomist CGI Package, you must configure the software for your specific system by editing the following files, that reside inside the DA/local directory:

You must also edit DA-5.2/framebuilder.html if you want to run the Framebuilder authoring program.

The above instructions place the DA files within the top level of your web server. It is also possible to place the files in an individual user's home directory, using the public_html mechanism. This will allow more than one running copy of the DA code to placed on the same server. Click here for instructions.

Compiling the Programs

If you have made the proper adjustments above, you must cd into the DA/src/c directory. (the one with all the CGI source code files). Then issue the following commands:



% make DA_CGI
% make install

You should now have all the necessary binaries in the necessary directories, with all the correct links. You can test the programs by clicking on "Test Atlas" on the index.html page for this package.

Creating a New Atlas

Now that you have installed and tested the atlas software, and have configured framebuilder.html, you are ready to create a new atlas. To create a new atlas, you must cd into the DA-5.2/bin directory, and issue the following command:

% createAtlas

You will be asked for the name of the atlas, the name of the author, and what his password will be. Then the atlas directory, inside the DA-ATLASES directory, wil be set up for you.

The Test atlas that comes with this package is already setup with name, author and password all set to be "Test".

Uploading GIF Images

Once you have installed a new atlas, you can begin creating content. To do this, you must first upload the images you wish to annotate to the atlas server. All GIFs that an atlas uses must be located in that atlases directory in a sub-directory called gifs. Example: an atlas named 'Thorax' would keep all of it's GIF files in the directory: DA-ATLASES/Thorax/gifs. You may make as many levels of sub-directories in this gifs as you like.

An (relatively) easy way to allow content authors to upload their images is through the "Upload Script". A link to this can be found on the framebuilder.html page, which is available by clicking "FrameBuilder authoring tool" from the index.html page of this distribution. From this page, you will see a link to upload images. Clicking on this will give you instructions on how to upload images.

Annotating Images With FrameBuilder

FrameBuilder is what you will use to create your own framefiles for annotated images. To use FrameBuilder, open framebuilder.html by clicking on "FrameBuilder authoring tool" as above.

Once you are on the FrameBuilder Page, you can begin using FrameBuilder, or you can read the instructions linked from that page. Also from this page are links to the 'update script' and 'upload script'. NOTE that after an editing session, you should run the update script that is linked from this page.

Creating a Link to the First Frame

To create a link to the first frame you need to make an HTML document with a link to the program PageMaster with a parameter designating which frame file is the one to be used, and a parameter denoting which atlas to use. The link from the index page, "Local Test Atlas", is an example:

<A HREF="/cgi-bin/DA/PageMaster?atlas:Test+ffpathIndex/Splash^Page+2">

The Text between the ':' in 'atlas:' and the first '+' is the name of the atlas you wish to use (same name as the corresponding atlas directory). The text between the 'h' in 'ffpath' and the '+2' is the path to the desired frame, relative to the specified atlas's root directory. Spaces should be escaped with carets (^). Note that you can link to any frame in the atlas, but it is usual to link initially to the top level frame. The "Retrieve URL for this Page" button on each generated atlas page will show the appropriate URL for that page, which can then be pasted into some other html document, a useful feature when creating tutorials that access only specific atlas pages.

Constraints on File Naming

Due to certain quirks in the system, there are a few simple restrictions on how you can name your gifs, framefiles, and QuickTime movies.

Naming your Quicktime Movies

One peculiarity of the Quicktime movie handling is that the files names are not supposed to be the same in the movies directory as they are referenced in the frame files. For example, if a frame file linked to a movie called brain.mov the actualy name of the file would have to be: brain.mov.mov . The movie must have .mov appended to the name it is called by the frame file. I know this is wierd but it is a necessary hack that I will *hopefully* fix someday.

Naming Conventions for All Files

All files (frame files, GIF files, Quicktime movies, etc.) need to free from any *bad* characters in their filenames. Files must NOT have the following characters: plus sign (+), slash (/), ampersand (&), caret (^), equal sign (=), percent sign (%), exclamation point (!), semicolon (;), double quote ("), single quote ('), and asterik (*). These are special characters to the Digital Anatomist CGI programs, and thus should not be used in filenames. All GIF files (the only kind of images currently handled) must end in ".gif".

Maintaining the Atlases

Everytime a new GIF had been added to the atlas, or an existing GIF has been modified, the atlas needs to be updated. The atlas also needs to be updated everytime a new framefile is created or an existing frame has been modified. These updates can be done from the web browser, by accessing the framebuilder.html, which points to the CGI program atlasUpdater. There are two kinds of updates. The GIF update option only needs to be run when a GIF file has been added or modified, or when a framefile has been added or modified. The navigation table update option only needs to be run when a new framefile has been added to the network of frames, or one of the existing frames' control links has been changed.

Occasionally, you will find that error messages arise from atlas use. A program called look_err has been designed to help you decipher the error codes. When an error code arises, all you must do is go to the URL that points to the CGI program look_err, which should be in your cgi-bin directory. For example:

http://your.server.here/cgi-bin/DA/look_err

You will be given a form into which you are to enter the error code you received. Then, depending upon the situation, a certain amount of information will be given to you about the problem that occurred. Some of them may be simple things like a misspelled frame file name inside a frame file. Some of them may turn out to be program bugs that will need to be fixed in a future release of the software.

Last Modified -23 May 1997