File format for Digital Anatomist Browser frame files
last modified: 3/8/95
Kraig Eno

This document describes the contents of what will be called here
"frame files". These are plain text files containing a sequence of
lines of ASCII characters which specify the image file and other
information to be used by an anatomical browser program for
displaying an image and a number of polygonal "active areas".


<newline> := \015			(octal)

<image-specification> := PICTGRAPHIC <file-name><newline>
	- This directive always occurs on line one, and is required. If this
directive is not present or if the image file cannot be accessed, the
frame will not be opened. The file name follows the word
"PICTGRAPHIC" with a single space in between. The location of the
file is relative to the Browser's "current directory", which is the same
as the location of the program itself unless it has been reset by
opening a script file interactively. An example of an image file name
is "Scans:image.pict", which indicates that a file named "image.pict"
is stored in the "Scans" folder. Directory paths should virtually always
be relative to the current location.


<number> := -16384 | -16383 | ... | -2 | -1 | 0 | 1 | 2 | 3 | ... | 16383
<coordinate> := <number>,<number>
	a <coordinate> is an X,Y pair defining a coordinate on a plane where
the numbers refer to screen pixels; 0,0 is the top left but points may be
anywhere in the plane including negative values.

<region-specification> :=
	STRUCTURE <name><newline><coordinate>,...,<coordinate><newline>
	- The bulk of most frame files is made up of a series of region
specification directives. Each takes up two lines: the word STRUCTURE
indicates that the rest of the line (after a space) should be taken as
the name of an active area, and the following line should be used as
coordinate data, which should define a closed polygon by a series of
at least three ordered line segments. (If the last coordinate does not
match the first, then a closing segment is assumed). The coordinate data
may be quite long, as many as 200-300 points, with each point being 6-8
characters long (counting the comma separators). This means that a
single line may contain 2000 characters or more, which puts a constraint
on the kinds of programs which can be used to manipulate the frame files.
In particular, TeachText and Word on the Mac seem to do quite well, while
vi on Unix rarely works.

 
<color> := BLACK | WHITE | RED | GREEN | BLUE | YELLOW | CYAN | MAGENTA
	- Colors may be specified in either upper or lower case.

<outline-color-specification> := OUTLINE-COLOR <color><newline>
	- The outline color is used when drawing the line around an active
area, as when it is clicked by the user. It is the same for every outline
on the frame. If this directive is not present, then the Browser's
current global default is used (it's usually set to CYAN, but can be
changed with a script command).


<highlight-color-specification> := HIGHLIGHT-COLOR <color><newline>
	- The highlight color is used to make an active area's outline stand
out for some reason. Currently, this feature is used to highlight the
outlines of a button which refers to frames which are currently open,
as a visual cue to help indicate which frames the user has seen and
what he's seeing now. It is the same for every outline on the frame.
If this directive is not present, then the Browser's current global
default is used (usually RED).


<outline-thickness-specification> := OUTLINE-THICKNESS <number><newline>
	- The number of pixels used in drawing outlines on a frame is
controlled by this frame-wide value. If used, it should be between
1 and 8, inclusive. If this directive is missing, the current program
default is used, usually 1.

<window-type-specification> := WINDOW-TYPE STATIC<newline>
	- Normal frames are "dynamic", that is, they are disposed
when the user moves to a different frame. STATIC frames, however,
stay on the screen and retain a place in memory so that their
contents can be used in later operations or for visual comparison
with other images. STATIC frames must be manually closed by the user.

<frame-information> := FRAME-INFO <arbitrary text><newline>
	- This is a string of ASCII text that can be inserted into a
scrolling text box (if present in the browser software) to give the user
details or instructions about the content of a particular image. It has
been used to tell what direction a series of cross-sections runs (i.e.
rostral to caudal), and to describe the content of individual stained
histology slides.

<script-command> := (<arbitrary text>)<newline>
	- These Lisp-like commands, enclosed in parentheses all on one line,
enable the Macintosh browser to be re-configured on the fly when a particular
frame is loaded. This is used right now for setting up directory path defaults
when entering a dataset which is in a different place from the startup path.


Example frame file:
------------------
PICTGRAPHIC Scans:Topography:lat right.pict
OUTLINE-COLOR WHITE
STRUCTURE cerebellum
159,324,138,305,70,302,74,329,78,348,114,382,192,371,191,353,199,346,217,339,201,330,177,323,159,324
STRUCTURE flocculus
214,350,203,356,197,356,198,363,229,356,229,349,223,342,218,343,214,350
STRUCTURE SQUARE
1,1,1,100,100,100,100,1,1,1


NOTE!
I am informed that some of our actual data files are not quite correct, so
if you're writing a parser that is intended to open the ones we've produced,
there are some robustness issues you should be aware of.
1. Not all contours always have at least three points; there are even some
"STRUCTURES" defined having only a single X,Y coordinate.
2. The final end-of-line character is missing on a few files.