M o n t a g e

Three - Dimensional Reconstruction from Serial Sections

User's Manual Version 4.4

25 February 1988

Rob Smith

Copyright (C) 1988
Robert G. Smith
Room 123, Anat-Chem Bldg.
Univ. of PA Medical School
Phila., PA  19104-6058  
All Rights Reserved

Montage and Mpict Reconstruction Manual

Table of Contents

Copyright (C) 1988 Robert G. Smith

Montage Tracing Manual

method of aligning traces for Montage


The process of serial 3D reconstruction works by aligning successive sections and making a stack of sections which can then be portrayed (either optically or by computer display) in three dimensions. This process depends critically on the alignment of data between sections. This manual explains the process of alignment and gives several different methods for achieving good alignment.

In order to understand the problem of alignment, it is useful to consider a typical example. If you wanted to reconstruct a helical "spring" that had been sectioned perpendicularly to the axis of the helix, you would see only an ellipse on each section. If you simply traced each ellipse and aligned the ellipse with the ellipse on the next section, you would reconstruct an elliptical cylinder, not the original helix. This problem occurs with any obliquely cut object such as a fiber or elongated cell in a serial reconstruction.

fiducial marks

In order to prevent this type of "reconstruction distortion", you must use "fiducial marks" which are used to align the data drawn from each section. Fiducial marks are normally objects on the same section as your data which aren't being reconstructed themselves and serve only to preserve the alignment between two sections. Alternately, fiducials can be absolute artificial landmarks which have been imposed on the material begin reconstructed, for example, the holes left by pins pushed through biological tissue.

You should have at least 3, preferably 5 fiducial marks which you draw along with your data on each section. They may be small objects which are only useable for several sections, so you may need more fiducials than 3 if some of them can't be used to align the next section. If you had only one fiducial besides your data on each section, you would accumulate a small rotational error from each section, because it's inevitably easy to misalign the angle of rotation when aligning only one small trace from section to section. Remember, you can't use your data traces to align with. So you need at least 2, and you should have at least 3 to 5 fiducials per section.

If your fiducials are related to each other in some way, for instance they're two fibers which both travel in the same oblique direction, or 3 fibers twisted around each other in a helix, their average "motion" will "bias" the reconstruction, and you will still have a problem with translational or rotational errors. So the whole 3D reconstruction process depends on using a random assortment of fiducials (or else absolute reference marks). This is the reason that you must use 3 or more fiducials; you have a better chance of using unrelated objects if you use many.

CLICK HERE to return to Table of Contents

aligning with transparent sheets

There are several ways to enter data into Montage. The standard way is to trace from your raw data (photograph, drawing, or image of slide) onto transparent (acetate or mylar) sheets. The transparent sheet allows you to keep traces from successive photographs in your series aligned, and also serves as a permanent record of how the alignments were made. See below "Tracing from photographs".

aligning with a mirror

The Montage program can be used to reconstruct without using transparent sheets, if desired. If you want to digitize your data from photographs or microscope sections directly, you need to align each section with the image of the previous section. One method for doing this is to mount the rear of the digitizing tablet and the bottom of the video screen together at a right angle, with a sheet of stiff acrylic plastic (or glass) mounted on a hinge between them. The plastic sheet acts as a mirror to allow the screen image to be seen while aligning the present section's photograph with the video graphics image from the previous section. The screen display is turned upside down using the Montage "k" command. This technique sometimes saves time because the separate tracing step is not needed. The disadvantage is that the fiducial marks must be digitized and alignments must be performed each time data from a section is entered or reviewed for checking.

aligning with a drawing tube

Montage can also be used to draw thick sections viewed on a microscope equipped with a drawing tube pointed at the video screen or bitpad. This way, you can digitize using the image of the cursor on the screen or digitizing tablet. If you point the drawing tube at the digitizing tablet, you should draw the fiducials onto a sheet laid on the tablet, and align with their image in the microscope. Montage allows you to adjust the mag on the x or y axes separately (using the "z" command), so you can get good correspondence between the screen and your material.

aligning with a projector

Another way to align with montage is to focus the image of a slide projector or projection microscope on the bitpad, using one transparent sheet to draw fiducial marks. Then put the next section in the projector and align the section with the fiducials on the transparent sheet, then draw that section's fiducials and trace that new section using the bitpad cursor. You can move either the section or the transparent sheet for alignment; if the slide can move, it may be easier to move it rather than the sheet, which can be left taped to the tablet. This procedure is similar to the standard transparent sheet alignment method, except that the transparent sheet is needed only to align the successive images, not to transfer the traces being digitized. Use tape to hold the transparent sheets in place after you've aligned them with the fiducial marks.

You can make an alignment dot on the bitpad surface (or on a transparent sheet taped to the surface) which will help aligning the projector image with your traces. You make a "base link" (see the "Montage" manual, Sect. 5) on each section which corresponds with the location of the alignment dot.

CLICK HERE to return to Table of Contents

Tracing from photographs onto transparent sheets


You will need a stack of transparent (acetate or mylar) sheets punched to fit a three-ring binder, several colored pens that write on the sheets, and a roll of masking tape. You need a method to align the sheets with each other; an artist's jig is best. The artist's jig is a piece of plastic about the dimensions of a ruler that has two pegs which fit into the outermost two holes in the sheets. The transparent sheets can be laid one on top of another onto the two jig pegs and this aligns them. The jig can be made from acrylic plastic, and the fingers made from nylon or a similar material.

If you don't have an artist's jig, you can make an alignment jig by using tape to mark the location of two corners of your first transparent sheet. Place two pieces of tape at a right angle to make a "corner" which fits the corner of the plastic sheet; then make a second corner mark. Then you can place all the other transparent sheets on the tape marks so that their corners are aligned with the corners of the first sheet.

drawing traces onto transparent sheets

To reconstruct from a series of photographs, tape the the first photograph to a table, and tape the artist's jig just to the rear (the side away from you) of the photograph. Place a transparent sheet on the artist's jig so it lies over the photograph and draw the features you want to reconstruct onto the sheet. You should also draw in several (three to five) extra features that you're not reconstructing to use as "fiducial marks" which help in aligning successive sections.

After you've drawn the features from the first photograph onto the transparent sheet, replace the first photograph below the sheet with the second section's photograph. Align the second photo with the first transparent sheet by carefully moving the photo around while observing how the fiducial marks drawn from the first photo align with the corresponding features from the second photo. Use all the fiducial marks (at least 3) to get a "best fit". Then tape the second photo in place to save the alignment. Replace the first transparent sheet on the artist's jig with the second transparent sheet, and draw the reconstructed features and fiducials as you did from the first photograph. Continue this process until you are finished the series.

CLICK HERE to return to Table of Contents

making montages with transparent sheets

When you trace pictures on the bitpad, there is a problem because the bitpad active area can only fit one 20 x 25 cm print. You make montages whenever you want to trace objects which lie on more than one photograph. A montage is a large picture composed of smaller pictures. The drawings from each photograph in the section must therefore be traced on a different transparent sheet. To allow the drawings from each separate "montage area" (photograph on same section) to be merged into one picture properly, you use a special method of aligning the transparent sheets when you trace from the photographs.

When you need to trace over the edge of one photograph's area, align the sheet for the next photograph area with the first by overlapping them with their holes from opposite corners placed onto one peg of the artist's jig, keeping the edges parallel, so that the second sheet is only on one peg. (Or you can just keep the sheets edge-to-edge, with the corners touching.) This keeps all of the sheets in the same relative rotation. The pictures from which you're tracing must have at least 10% overlap, and should represent neat rows of material from the sections you're photographing.

Trace some fiducial marks which overlap onto the first sheet, and then place the second, overlapping photograph so it aligns with the overlapping fiducials. When you've traced the overlapping fiducials onto both transparent sheets, you are free to move the second transparent sheet back onto both pegs on the alignment jig and move the overlapping photograph back. You can now continue tracing data onto the second sheet.

Some final words from experience

There are several ways to use Montage without going through the transparent sheet step, so 3-D reconstruction is available for many kinds of material. The standard transparent sheet tracing technique is often preferable because it gives a permanent record of how a cell was aligned and traced which can be checked by a second person. When studies must be occasionally re-checked after several months or a year, this factor is sometimes more important than the extra amount of time it takes to separately align and trace from photographs onto transparent sheets.

CLICK HERE to return to Table of Contents

Montage User's Manual

Method of aligning traces for Montage

aligning with transparent sheets

There are several ways to enter data into Montage. If you have made traces onto transparent sheets as described in the Montage "Tracing" manual (Sect. 4), the digitizing step is relatively easy because the traces on the sheets are already aligned.

aligning with a mirror

The Montage program can be used to reconstruct without using transparent sheets, if desired. If you want to digitize your data from photographs or microscope sections directly, you need to align every section when you digitize it. One way to do this is to mount the rear of the bitpad and the bottom of the video screen together at a right angle, with a sheet of stiff acrylic plastic (or glass) mounted on a hinge between them. The plastic sheet acts as a mirror to allow the screen image to be seen while aligning the present section's photograph with the video graphics image from the previous section. The screen is turned upside down for this using the "k" command. This technique sometimes saves time because the separate tracing step is not needed. The disadvantage is that the fiducial marks must be digitized and alignments must be performed each time data from a section is entered or checked. See the "Tracing" manual (Sect. 4) for the standard tracing method.

aligning with a drawing tube

Montage can also be used to draw thick sections using a microscope equipped with a drawing tube pointed at the video screen or bitpad. This way, you can digitize using the image of the cursor on the screen or bitpad. Montage allows you to adjust the mag on the x or y axes separately (using the "z" command), so you can get good correspondence between the screen and your material.

aligning with a projector

Another way to align with montage is to focus the image of a slide projector or projection microscope on the bitpad, using one transparent sheet to draw fiducial marks. Then put the next section in the projector and align the section with the fiducials on the transparent sheet, then trace that new section using the bitpad cursor. You can move either the section or the transparent sheet for alignment; if the slide can move, it may be easier to move it rather than the sheet, which can be left taped to the tablet. This procedure is similar to the standard transparent sheet alignment method, except that the transparent sheet is needed only to align the successive images, not to transfer the traces being digitized. Use tape to hold the transparent sheets in place after you've aligned them with the fiducial marks.

You can make an alignment dot on the bitpad surface (or on a transparent sheet taped to the surface) which will help aligning the projector image with your traces. You make a "base link" (see below) on each section which corresponds with the location of the alignment dot.

CLICK HERE to return to Table of Contents

tracing from transparent sheets

Let's say you're tracing a cell from a series of transparent sheets which you have traced from 20 x 25 cm prints. In order to keep the traces on successive sections of your transparent sheets correctly aligned, you need a method of keeping the sheets exactly superimposed. There are two easy ways to do this.

The first (and best) way is to use an artist's jig which is a piece of plastic about the dimensions of a ruler which has two prongs positioned to fit into the outer two holes of the transparent sheets. You tape the artist's jig to the digitizing tablet on the side away from you. Then you can lay one or more sheets onto the jig to keep them exactly aligned. The artist's jig can be made from pieces of acrylic plastic, nylon, or a similar material. Make sure that you tape the corners of the sheet opposite the holes to the tablet to prevent the sheet from moving when you are digitizing. Masking tape works nicely for this purpose. The artist's jig saves time by allowing you to position the sheets quickly.

The second way to align is to make alignment marks on the digitizing tablet which correspond to the corners of the transparent sheets. You simply lay a transparent sheet with its corners on the marks and tape it in place.

The active area of the bitpad ends at the indented line about 5 cm from the edge of the bitpad. You must keep any traces you digitize inside this area. If your traces are too large to fit inside the bitpad active area, don't worry, because there's a way of positioning your work that'll enable you to enter traces as large as you want.

CLICK HERE to return to Table of Contents

Montage beginning commands

Starting Montage

First, start Linux going with the boot procedure (see section 3). Make sure the disk has enough space for the data file you will create: type the command "df" to see the number of free blocks left (see section 3). Each section of data in the file normally requires 2K (2048 bytes or 4 blocks) of space on the disk, although you can change this if you like. Type "montage" ( means the "enter" or "return" key) to run the montage program. Montage prompts you for the name of your file. Enter your file name; if it's a new file, mont`ge will tell you so, and will put it in your directory for you.

You can also give the name of an already existing file to Montage. Montage attempts to find it in the directory. If montage can't find your file, it makes a new file. If you don't remember exactly what your existing file name is, type "^C" (control-c) at this point to exit montage, and use "ls -lt" to find your file. To understand more about files and file names, see "Components" (Section 2) and the Linux Guide (section 3 of the manual).

If you have specified a new file, then montage creates it for you, zeroing it one section at a time. Montage first says:

      Section size = 1024
      Do you wish to change ? (Y/N)
Simply type at this prompt to leave the section size at 1024 words (2048 bytes) per section. Next, Montage says:

     Zeroing Data file
     Start at which section? ( for 1)
Type to start your file at section 1. Next, Montage says:

     Stop at which section? ( for 100 sections)
You should type in the number of sections that you think you will use. Don't enter a large number of sections unless you're sure: 1) there's room for the resulting file and 2) you really need them now. For now, you should keep the file small; you can easily add extra sections to an existing data file later. As each section is zeroed, montage prints dots "...." on the screen, 50 dots to a line. To change the size of the file later, you first compress it and then uncompress it using the "fstor" command (Sect. 7).

help menu

The commands explained to you below are all listed on the montage help menu at the end of this section. To enter a command, you type the command code given on the menu into the keyboard. The menu is also available to you when you're running the program. You type "h" (help) to display the help menu.

CLICK HERE to return to Table of Contents

write mode and sections

You normally store all the points from one transparent sheet together in your data file in a "section". Each section corresponds to the tissue section from which the photographs you're tracing were taken. The data file is organized as a sequential series of these sections; each has the space for about one thousand points. If you have a "montage" of several overlapping areas on one section, then the points from all these areas are stored in one section. You can see the amount of space left in the section on the bottom of the screen.

In order to save the points you enter on each section, you must give the "write mode" ("w") command before you make any links or points. You get the message "write" in red at the top of the screen when "write mode" is on. If "write mode" is not turned on, then your data will be lost when you go to the next section, or when you exit from the montage program.

CLICK HERE to return to Table of Contents

tracing with digitizing tablet

There are three ways to use the bitpad, "Absolute mode" ("A"), and "cursor mode" ("B"), and "Position mode" ("@"). Absolute mode moves the cursor on the screen whenever you move the bitpad mouse. Cursor mode moves the cursor on the screen only when you keep the yellow "1" button on the mouse pressed while you move the mouse. Position mode keeps the cursor in the middle of the screen, but moves the data in the background.

Absolute mode is the easiest to learn to use. You simply move the mouse and see the cursor move on the screen. If you press the yellow button ("1"), the cursor on the screen stops moving, allowing you to align the mouse with a different coordinate on the bitpad.

Cursor mode is useful for montages where your trace data is larger than the bitpad active area. You simply press the yellow button ("1") on the mouse whenever you want the cursor on the screen to follow your hand movements of the mouse. Whenever you let up on the 1 button, the cursor on the screen doesn't move. This allows you to move the mouse without affecting the location of the cursor on the screen. This is necessary for making montages because there has to be a way to change the relative correspondence between the screen and the bitpad coordinate systems.

Think of the graphics screen as a single window in your car on a distant planet. You can control where you point your window, and thereby what objects and stars you see in the outside world. The outside world is very large, much too large to see with one window, so you need a way to move the window. If you move the cursor off to the side of the window, the window gets "pulled" by the cursor to a new position. In absolute mode, the bitpad is like a joystick which directs the cursor (and thereby the window). In cursor mode, the bitpad is like a wheel connected to the ground outside: you can steer your car on the ground by alternately pushing the wheel (pressing the button) and lifting up your hand to get a new grip on the wheel (lifting your finger off the button). In position mode, you have more direct control of your window view.

CLICK HERE to return to Table of Contents

explanation of links

The video screen displays your data as dots or lines on the screen. These correspond to the drawings you have digitized on the bitpad. You can think of the cursor as your pen for transferring the drawing from the bitpad onto the video screen and into the computer's memory. You move the cursor by moving the mouse. This correspondence between the cursor and mouse movements is defined by points called "links", which are the basic unit of data in your file. You create an "alignment link" to define a reference point where you can move your "pen", the cursor. Once at the link, the cursor's location on the video screen corresponds to a location on the bitpad, which you can refer back to later.

use of links

Links are used for alignment, for trace points, and for flag locations. You use alignment links to move the cursor around quickly, and to set the cursor location to be equivalent to a bitpad location. However, you can set the position on the bitpad to correspond to other locations in the picture by making different alignment links and using one them as your starting point. This feature allows you to display your trace data on the screen in different positions, and is very useful when you're making montages.

the current link

The "current link" is always the link you have either just created or moved the cursor to using a command such as "nearest link". Thus, the current link defines the alignment of the picture that you see. The current link is displayed on the screen as "CL". Most of the link commands such as "erase link", "next link", "last link", "move link" or "make point" (these are explained below) work on the current link only. New links are always made immediately following the current link in the current section buffer.

cursor alignment (the "x" command and base links)

One way to keep your cursor aligned with your sections is to use the "x" command. In this method, you draw a dot on the bitpad which serves as a reference point to align the bitpad mouse with. You move the mouse to the dot on the bitpad and then press "x". Whenever you press "x", the screen cursor moves to location (0,0) on the screen and the location of the bitpad mouse is aligned with (remembered as) this same location. This method is particularly helpful in absolute mode ("A") because you don't need any alignment links.

Another way to keep the alignment between the mouse location and the cursor on the screen is to make "alignment links", normally one per section. These serve as reference points for your traces. The alignment links are made at the same location in each section, and serve to align the cursor from one section to the next. A dot in the center of the bitpad serves as the reference point to align the mouse with the links. To make an alignment link, make the screen cursor go to (0,0) or some other location and without moving the mouse, use the "make base link" command ("0") to make a link which can be aligned with the bitpad center dot. The base link gets displayed as a "B" in the picture. You may use the keypad to enter numbers if you want. Normally the first base link on a section is entered at the location (0,0) using the "x" command.

trace links (contain points for tracing cell outlines)

To digitize a tracing of a cell, get the mouse aligned with the cursor on the screen using the following procedure. Move the cursor on the screen near the alignment link and enter the "nearest link" ("^r") command. This causes the cursor to be exactly centered on the alignment link. If you're in absolute mode, the alignment between bitpad and screen is preserved automatically as long as you don't press the yellow button or use any of the "link move" commands (described below). If you're in cursor mode, you need to re-align for every new link you make: Keeping the cursor on the screen at the alignment link, move the mouse to the dot on the bitpad with your finger off the mouse button; then move the cursor on the screen to the proper place by pressing the yellow 1 button and moving the mouse crosshairs over your transparent sheet to the trace you want to enter.

Make a "trace link" ("2") at this point; it becomes the "current link" or "CL" on the picture. You can then make points ("1") at appropriate intervals around the outline you're entering. Don't make the last point at the position of the first point, because trace points are made in "close" mode; the first point is duplicated automatically to make the last point. This means that the first and last points of the trace link are always connected. The points in a new link aren't displayed right after you make them but you can see them when you make the next link or press "8". You can see the connections between the points using the "set line display mode" ("u"). This displays your points as connected lines, not points. Normally, you make points in a clockwise direction only. Later on, if you want to analyze your trace links for area, counter-clockwise links give negative area.

If you need to trace lines on a section which aren't closed contours, turn the "close" mode off by pressing 'c'. This mode can be used to digitize tree structures by creating new links at each branch point.

You normally make a new trace link for each profile (or "slice") you want to trace. Set the branch or cell number ("s"; see below) to a different value for each trace link. This allows your trace links to be displayed separately using the filter if needed (see Section 5: Mpict).

CLICK HERE to return to Table of Contents

Colors on the screen

You can set the color of any data links on your screen using the "s" command to change the color of the current status. For example, type "s", followed by "color=red". This will cause any new links to be displayed in red on the screen and in red when they are plotted on paper later. The color of points can also be changed later. The following colors are available:

Number     Low inten        Number       High intensity

0          black            8            gray
1          blue             9            ltblue
2          green            10           ltgreen
3          cyan             11           ltcyan
4          red              12           ltred
5          magenta          13           ltmag
6          brown            14           yellow
7          white            15           brtwht
The color numbers are used by the graphics card to display the correct color. They can be referred to later during 3D picture display by their name if you want to display only links with a certain color, or if you want to change the color of certain links only.

CLICK HERE to return to Table of Contents

making new sections

For each new section, you simply follow the steps outlined above. First, move the cursor to the alignment link with the "nearest link" command. This positions the cursor so that the alignment link you make on the new section will be at the same location as on the current section. Next, advance to the new section using the "next section" ("ctrl-@") command. Make an alignment link on the new section, and you're ready to make your trace links.

exit from montage

When you're finished entering your trace data, exit "montage" with the "quit program" command ("q"). This saves your last section data in the disk file. Before it exits, the program prompts you,"Sure you want to exit?" You then have a chance to re-enter the program. Answer "y" if you really want to exit. This is a safety feature to prevent accidental exits.

CLICK HERE to return to Table of Contents

More Link Commands

move to link

You can move the cursor's position from one link to the next by entering the "next link" ("^a"), "last link" ("^q"), or "nearest link" ("^r") commands. The "next link" means simply the link which was created immediately after the "current link", and the "last link" means the one before. The "nearest link" command makes the cursor go to the position of the nearest link, and also moves the entire picture so that the link and cursor are centered on the screen. These three commands use the "general filter" to select which links to go to (see below).

The "nearest link" is very useful when you want to move the screen to display a different area which wasn't visible before. You simply move the cursor by alternately pressing the button and when you get near enough to a link you can press "^r" which gets the link centered in a hurry. This works in all three bitpad modes: absolute ("A"), cursor ("B"), and position ("@"). If you're in absolute mode ("A"), the screen cursor will stay in alignment as long as you don't press the yellow button and don't use any of the link move commands.

change a link

You can easily erase or move a link. Simply move the cursor near the link on the screen, enter the "nearest link" ("^r") command, and the link of interest becomes labeled "CL", which means it is the current link. To erase the current link, enter the "erase link" ("P") command. After the link is erased, the current link "CL" moves to the previous link. To move the current link, you enter "move link mode" ("l" = small L) and then move the cursor on the screen. The link follows the cursor. Enter "l" (move link) again to stop the link movement. You may also change a link's internal values; see "set status" ("t") below.

add trace points

You can erase and add points to a trace link easily. Move the cursor near the link of interest, and enter the "nearest link" ("^r") command; the link becomes the current link. Then enter the "next point" ("^d") command successively until the current point marker "CP" reaches the right point. You can then enter the "erase point" ("Q") command, or you can add new points which will be inserted after the current point. Remember that trace links are "closed"; the beginning and end points of the trace are coincident.

CLICK HERE to return to Table of Contents

current status

Besides a picture of your data points, the video screen displays the current status. This is the information which defines the position of the cursor, and will be used to make the next link that you create. Each link contains a set of numbers, called "link fields", which were copied from the current status at the time the link was created. The fields are:

xbio,ybio      x,y coordinates of the link.
section        section number.
area           area number for montages.
branch         branch number.
cell           cell number.
color          color of link on screen.
flag           flag spec number (only in flag links).
type           link type (base,cell,flag,trace,grain,line)
                              (see "types of links" below).

You can change the values in the current status with the "set current status" ("s") command. This causes any new links created to have the new status incorporated into them. See "setting current status" below.

d menu: extra commands

The "display" ("d") command gives you a second help menu with more commands. After you see the "display menu", you type another character shown in the menu to enter a command. The status of the current link may be displayed on the right side of the screen using the command "display current link" ("d"). Press "dd" again, and you get a display of more link fields on the screen. Press "dd" a third time; you get a still more complete display of link fields. A fourth time gives you the original display.

     dd   displays the current link on the right.
     de   displays more information in the current link.
     df   checks for bad data in a section and erases it.
     dk   erases an entire section quickly.

jump to section

You can display the picture for any section with the "jump to section" ("j") command. Type in a section number, and this section will be immediately displayed. You can also use the "next section" ("ctrl-@" or "ctrl-2") or "last section" ("ctrl-p") commands to move one section at a time. All these commands use the relative filter for alignment.


You can change the size of the picture displayed on the video screen by entering the "change mag" ("m") command. The mag selected can be anywhere from .001 to 1000. Mag 1 gives the picture closest to real-size compared to the size of the bitpad tracing.

CLICK HERE to return to Table of Contents

Advanced Commands

button macros

You can make a sequence of commonly used commands into a "macro" which will be run every time you press a function key on the keyboard or a button on the bitpad mouse. To do this, you enter the "button macro" ("b") command, and the computer displays the current state of the macro function keys. It asks you whether you want to change them and you enter "y". You then follow by pressing the function key or mouse button you will use, followed by the sequence of montage commands which will be in the macro. You stop the macro with a double press on the escape key (). You may enter up to 80 characters into a single macro.

Montage has a limited symbolic reference capability. Inside the "s" and "t" commands (which allow you to change the current status and the current link, respectively) you can create and set variables, and use their values instead of keyboard input. For instance you could modify a series of links by defining two variables inside the ("s" or "t" commands):

          xincr = 10; yincr = 20
Then you could define a macro which changes the location of a link automatically:

          b                        (button macro, displays current macros)
          y                        (yes, I want to change.)
          F1                       (the program the F1 function key)
          t                        (change current link command )         
          xbio = xbio + xincr;     (increment xbio) 
          ybio = ybio + yincr; 
                              (The Enter key to stop "t" )
          ^p  (go to next section)
          ^r  (find nearest link)
This makes it possible to run the "t" command automatically to change the coordinates of an object on all sections. Remember, you enter the macro exactly as you would type it when you're running the command yourself without a macro.

Note that in the examples shown here the commands are on separate lines for clarity; you must not type or "Enter" except to end the "t" or "s" command. Remember that anything inside the "< >" angle brackets means the name of a key such as or or , and the "< >" should not taken literally.

Another example of a useful macro is when you're making new links with different colors and branch numbers. It is a lot of typing to run the "s" command and change the current status every time you want to change a branch number.

To make it easier, try this:

          b              (button macro command) 
          y              (yes, I want to change)
                     (macro program Function key F2)
          s              (set current status command)
          br=br+1        (new branch num = old branch num + 1)
                    (the Return or Enter key to end the s command)
               (stop the macro)      

          bysco=red  (set current status color to be red)
          bysco=blue (set color to be blue)
You can use macros for any sequence of keys that you could type yourself at normal speed. You will notice that when you exit Montage and run it again, the macros get erased and your must re-enter them. One way to eliminate this problem is to avoid exiting Montage by using the "!" command (see below) to run UNIX commands from within Montage. You can then return back to Montage with your macros intact. Another way:

reading commands from a file

If you have made some long macros, you will find that you lose the macro definitions when you exit from Montage. You can put your macros into a text file and read them automatically into Montage using the "r" command. For instance you can make a file "macros" using "vi" or "ice" which contains:

          bysbr = br+1 
          bysco = red    
          bysco = blue  
This "macros" file could be read in from the disk drive whenever you run the "r" command:

     Please enter the file to be read: macros
Then your three macros for F2, F3 and F4 would be read in automatically. You can also read in one file from within another file's "r" command (recursively), so you can read several files at once, and accomplish quite complicated actions.

CLICK HERE to return to Table of Contents

Types of links

There are commands to make five types of links:

Type    Enter       Use

0) Base   0         for alignment
2) Trace  2         for tracing cells.
3) Flag   3         to mark synapses, etc.
4) Grain  4         for marking grains.
5) line   5         for marking fibers which pass through sections.
Any one of these types of links may be used for alignment of transparent sheets. The base, trace, and grain links all simply display their single characters in the screen display. The flag link displays "F" followed by the flag name. The line link gives a "L 4 5" display on the screen where the "4 5" are typical cell and branch numbers.

Line links

Line links are used for defining lines which go through many sections. The line can go from one section both forward and backward. It is useful for defining the path which a fiber moves through tissue. Line links are difficult to enter correctly, because each line link has a pointer to both the line link immediately before and after it. This gives an order to the links in a line vector, and allows the line to go through tissue any direction, forward or backward.

In order to create a new line, you must have the "current link" (CL on the screen) at a link that isn't another line link. Then each time you add another link to the line, you must be sure the "current link" is set to the line link that you wish to connect the new link to. Also, you must have "write" mode ("w") set on when you enter the link, otherwise the pointers won't be correct.

You can travel forwards and backwards on the line link vector with the use of the "last link" and "next link" commands. If the pointers aren't set right, you can figure out what the problem is with the "display current link" ("dd" and "de") commands to enable you to see the pointer fields. The "Lp" and "Np" link fields tell give the link and section number for the last and next links in the line.

Grain links

Grain links are exactly like trace links, except that their points are not displayed as a connected polygon. You can use them for displaying point information, such as individual grains on an autoradiogram.

CLICK HERE to return to Table of Contents

Flag links

Flag links are used to make a point stand out by displaying it as one or several words. You use the "g" command to define the current flag specification, and you can enter a list of numbers or words. This list is displayed on the bottom left of the screen, and this definition will appear in any flag links made. In order for the flag words to appear correctly, you must create a file called "flag.def" which contains all the definitions you are using. Montage reads the "flag.def" file each time you run it as a command, and translates each word into a number, to be used as an "index" in the symbol table. Later, you can use the same flag word definitions when you run the picture program "mict" and the definition file "flag.def" will allow the picture program to respond correctly.

The really powerful feature about flag links is that you can use a flag word to define the features of the flag for one category only, and use several categories for each flag, as you would in a relational data-base program. Later, you can select flags for display or analysis which match a logical relationship between the several flag word fields. Since flags can contain an unlimited number of flag word fields (each represented by one integer), this is a very powerful system.

You can access the separate flag word fields through the use of the "f0, f1, f2, etc." and "anyflag" fields when you use the filter. "f0, f1" refer to the contents of the first, second, etc. flag fields. "anyflag" refers to the contents of any flag field that matches the logical expression it's in. See the filter example below (page 6-24) for a typical use.

Flag link definitions

Flag links display their name or number on the screen. You can make a definition table for all your flag types which associates each flag type with a name. The definition table is put in a separate "flag.def" file which gets read each time you run the montage program. You make the definition file using an editor such as "vi" or "ice" just as you would any other text file. The syntax for the flag definition file is:

  1. One flag definition per line.
  2. Each line begins with a character string of up to 15 characters. There should be no spaces in the character string, but if you want two words separated by a space you may place the words (and the space) inside double quotes.
  3. After the character string, there must be an equals "=" sign, followed by a definition number for the flag.
  4. A sharp "#" anywhere on the line makes everything after it ignored until the next line, allowing you to place comments to yourself in the file. (see next paragraph for explanation.)
For example, a typical file might be:

#    Flag definition file
flat = 20
round = 21
"large square" = 22
# end of file
Once you have set the flag definition table, you can then enter any flag into the "current flag specification" at the bottom of the screen with the "make flag spec" ("g") command. You can enter as many names or numbers, separated by spaces, as you like; these will all appear in the current flag spec. When you create a flag link, the flag spec. names and numbers will appear in the screen display along with the marking "F". Thus, you can see the name of all your flags right on the screen where you place them.


     F input amacrine 7
You can include your flag definition file in your corfiles when you use "picture" to make 3D pictures of your data. This allows you to use the same flag definitions to describe to the filter which flags to display in your picture. To create or change the "flag.def" file when you're running Montage, you can make use of the "!" system command (see below) to run the editor ("vi" or "ice"; see Sect 7) from inside Montage. This allows you to run any Linux command line while you're running Montage; you can even run Montage inside itself to look at a different data file!

setting current status

The current status is the information which you incorporate into a link when you first create it. To change the current status, you simply enter the "set current status" ("s") command. Then you may enter as many changes as you like, separated with semicolons ";". Each status change has: 1) the link field you're changing; this can be abbreviated. 2) The new value for the field. 3) If another field change is on the same line, you must have a semicolon ";". You end your entry with a blank line.

The "change link status" ("t") also has the same synt`x. It is used for changing a field of the current link after it has already been created.

For example, to change the branch to 25 and the cell number to 7:

          br 25; ce 7
would do the trick!

size of sections

Montage allows you to make data files of different sizes. You can change the section size whenever you make a new data file. Normally, you use the largest size possible, but you can use a smaller size if you're running out of room on the working disk. The data files normally have a section size of 1024.

Whenever you make a new file, Montage displays the current section size, then asks you whether you want to make a different size file. If you want to change to a different size, you answer with a "y", then enter the new number, which should be an even multiple of 512 (either 512, 1024, 1536, 2048, etc). When you run "montage" with existing files, it automatically finds the proper section size to use with that file.

The "fstor" storage program (section 6 of manual) allows you to compress your datafile. When this is done, each section is reduced to the exact size which holds the points in each section; this is a variable number. When you "uncompress" the file, each section gets expanded to the current section size (which you can set to less than 1024 but is normally 1024). Fstor always asks you if you want to change the section size before it uncompresses the file. You can also change the section size in "fstor" with the "change section size" command.

Another way to compress your data files for archival storage by the use of the pack(1) and unpack(1) commands. These use a special bit-compression scheme.

CLICK HERE to return to Table of Contents

zero x,y position

Normally, montage starts out with the cursor set at location 0,0 and you can make your first base link there to keep an absolute reference point from which to make all your other base links (if you don't have multiple areas). However, in absolute mode ("A"), your first link will be at the absolute coordinate of the bitpad cursor, which will not usually be 0,0. If you want your base links to start out at 0,0 (this is nice but not necessary), then use the "x" command which causes the current bitpad position to be 0,0 and shows that location on the screen (as if you went to a link there).

The absolute mode allows you to enter absolute locations of points without any need for drawing marks on the bitpad. Once you go to a link, however, the absolute coordinates are moved so they don't refer to an absolute bitpad location any more. To set the correct alignment again, you can move the bitpad mouse to your alignment dot on the bitpad surface and press "x" or go to the correct base link.

If you want to make a lot of base links at (0,0) the easiest way is to make a blank file called zero.dat which contains, say 20 sections with base links at (0,0). Then use the "fstor" program (Sect 6) to compress this file and save it. When you need a file of say, 80 sections, take the zero.sto file and run

     cat z20.sto z20.sto >x40.sto
     cat x40.sto x40.sto >file.sto
     fstor -n file.sto xxx.sto -r xxx.sto file.dat
to make the file. It will have 80 blank sections, each with a copy of the original link. "fstor -n file1 file2" means renumber the sections in the file.

The Linux system command "!"

You can run any Linux command when you're running Montage by entering a "!" in front of the line. Montage responds to your "!" by resetting the screen back to text mode so you can see your command operating normally. After your one-line command stops running, Montage says: Type to continue ... After you type a , your previous Montage display reappears.

CLICK HERE to return to Table of Contents


The montage program has a very powerful filter system which allows you to select links with any combination of field values (branch, area, color, cell number, etc). The purpose of the filter is to give you a way to describe different parts of your drawings so you can separate them later. If you'll ever need to display parts of your drawings separately, or in a different color on the plotter, you need the filter. Think of the filter as a seive through which to pass your datafile.

There are two filters you can use. The first, the general filter, controls which links the cursor will move to with the commands "nearest link", "next link" or "last link". This allows you to select which links you use for alignment when making montages (see "making montages with transparent sheets below").

The second filter is the display filter. This filter controls which links are displayed each time a new screen display is generated. Thus, you can greatly simplify a large screen display by filtering out unwanted links during display. In addition, you can select which sections to display on the screen with the display filter. The programs "mpict", "fstor" and "glink" all use the same filter.

You use the filter by creating "filter specs" which describe the form of link that you want to find. Each filter spec describes the exact form of link by specifying for each field (number) in the link what range of values is acceptable. You assign an appropriate filter spec to each filter; then the filter automatically finds the links you want whenever you enter a command which uses the filter.

link fields

The filter can look for any combination of the following fields:

type           the link type (base,cell,ftype,trace,grain)
xbio,ybio      the x,y coordinates of the link.
section        the section number.
area           the area number for montages.
branch         the branch number.
cell           the cell number.
color          link color.
flag           the first flag spec number (only in flag links).
f1,f2,f3, etc. other flag spec numbers in flag links.
anyflag        any flag spec in a flag link.
To make it easier for you to create and use the filter specs, there is a table with space for eight filter specs to be defined for use in the filters. A simple numbering scheme, in which each filter spec line is given a number, allows you to refer to this spec by its number when you use it for either filter. Thus, any filter spec may be used for either filter. In practice, you define new filter specs as you need them, and add them to the filter spec table.

The filter language syntax for one line is:

          1) Link field, which can be abbreviated.
          2) Equals "=" sign.
          3) Lower bound for field.
          4) Comma "," (optional, use with upper bound.)
          5) Upper bound for field (optional).
          6) If more filter specs. are on the same line, you 
               separate them with a space or semicolon ";".
Example of filter syntax:
          typ = flag;  flag = 4,7;  branch = 5
This example would filter for a flag type link whose flag value was either 4, 5, 6 or 7, and whose branch was 5.

You may put as many filter specs on a single line as will fit; normally this maximum is ten. To pass through the filter, a link must statisfy all the filter specs on one line (normally separated by semicolons); this is a "logical and" function. The lower and upper bounds (inclusive) allow you to specify a range of values for any field. If you need more ambiguity in a filter spec, you may use the "logical or" function by using "or" between specs. You may also use left and right parentheses to define more complicated logical functions than exclusively "and" or "or" (see example below).

To make it easier for you to write filter specs, the filter accepts multiple filter specs on a line separated by either semicolons, commas, or spaces (you can leave out the semicolons).

You may also use the notation current - 1 (or + 1) to describe any field in a link referred to the current status. This can be abbreviated to "cur - 1".

Example of filter spec table:

     filter spec table:

     1)   typ = base;                   (link type must be 0)
     2)   typ = trace,grain;            (link type 2,3,4)
     5)   typ = 2; (cel = 1) or (cel = 3);  (trace link on cell 1 or 3)
     6)   f1=dark; anyflag=bipolar;       (any dark bipolar) 
     7)   typ = ftype,grain;               (link type 3 and 4)
     8)   sec = cur - 1; typ = trace;     (any trace link on previous section)

     reference numbers:

     g 2       (link type 2,3,4)
     r 1       (link type 0)
     d 7       (Flag,grain links on current section, and
                    any trace links on previous section)

To change the filter, use the "filter" ("f") command, then type "g", "r", "d" to change any of the filters to a different filter spec; or to change filter specs, type "f". Then enter the number of the filter spec. you want to change, and enter the filter spec.

use of filter by other programs

The "fstor", "glink" and "mpict" programs all use the same filter language, with the same syntax as described above. Corfiles for "mpict" can have up to 100 filter spec lines, each with its own pen number and hide status.

CLICK HERE to return to Table of Contents

Surgery with filter

Another feature of the filter is the ability to do surgery by selecting only links above or below a plane located in three-space. Planes are defined by the syntax:

     above xloc yloc zloc a b c
     below xloc yloc zloc a b c
The (xloc,yloc,zloc) define a point in original x,y bio coordinates which the plane passes through. The (a b c) define the solid angle at which the plane passes through the point for the equation:
   a(x-xloc) + b(y-yloc) + c(z-zloc) = 0
It is sometimes difficult to find the proper locations for the planes because they can't be seen, only their effect on the display can be seen. For starters, define the (xloc,yloc,zloc) point to be the center of the cell, so that no matter which angle you choose for the plane, you will be able to see where it cuts through the material. The values for a,b, and c be determined empirically or intuitively by noting that a,b,c affect the x,y or z slope of the plane, respectively. The values for a,b,c should not all be zero at once, since this selects for all points. Setting one of a,b or c to zero makes the plane have no slope in that direction. Increasing one of a,b or c makes that coordinate affect the slope more. Once you get the slope right, you can move the intersection point very easily.

One hint to make this easier. If you set the value for c to -1, then the a value is equal to the x slope (the tangent of the y rotation), and the b value is equal to the y slope (an x rotation). In this case,

     z-z0 =  tan(yrot)(x-x0) + tan(xrot)(y-y0)
for example
     above 0 0 0 2 3 -1
selects for points above a plane with a slope of 2 in the x direction (a y rotation), and 3 in the y direction (an x rotation). A similar equation holds for setting either a or b to equal -1.

display filter: additional sections use to align sections

Normally, the display filter can accept links for display from the current section only. However, it has a special feature not found in the other filter functions which allows display of other sections in addition to the current section. The Display filter function will use additional filter spec lines each of which may display links from one other section. The display filter continues to use all succeeding filter spec lines until a blank line or the end of the filter table. Only the first section displayed will have trace links displayed as lines. The other sections are displayed as dots only. For instance, if filter specs 6, 7 and 8 are set, you can use all three specs for display by setting the display filter to 6. Filter specs 7 and 8 will then also display on the screen, but will have only dots, no lines.

This feature allows you to align previous sections with your current section. To do this, set the second filter line to "sect=cur-1". This allows you to see the links from the previous section as dots; you can align links on your current section with them using the "l" (move link) command.

CLICK HERE to return to Table of Contents

First page of the main menu:

^2 = Next section  (rfilt)     ^p = Last section  (rfilt)    Nov 87
^a = Next link     (gfilt)     ^w = Last link     (gfilt)
^b = Current link              ^r = Nearest link  (gfilt)
^c = Go to cursor              ^s = Nearest link, don't move (gfilt)
^d = Next point                ^t = Last point
^h = Next frame                ^x = Last frame

0 = Make base link            P = Erase link
1 = Make point                Q = Erase point
2 = Make trace link
3 = Make flag link
4 = Make grain link           @ = position mode
5 = Make line link            A = absolute mode (default)
7 = Close slice               B = cursor mode
8 = Redisplay for abs mode

Second page of the main menu:

b  = make Button macro
c  = Close trace link (off/on)
d  = link display menu: link params (on/off)
f  = change Filter
g  = make flag spec
h  = Help table
i  = display symbol defs.
j  = Jump to section
k  = make screen upside down
l  = move Link mode

m  = change Magnification
n  = short screen display
q  = exit program
r  = read commands from file
s  = Set current status
t  = Change link status
u  = Set line display mode
w  = write mode (on/off)
x  = stage to zero pos
y  = link display (on/off)
X,q = exit program
z  = change screen size
!  = run Linux system command!

The display menu:

        Display Menu

d = display current link on screen
e = display more information about current link
f = fix section
k = kill section, clear to all zeroes
any other key = return to display

CLICK HERE to return to Table of Contents

Making montages with transparent sheets

When you trace pictures on the bitpad, there is a problem because the bitpad active area can only fit one 8" x 10" print. You make montages whenever you want to trace features which lie on more than one photograph. A montage is a large picture composed of smaller pictures. The drawings from each photograph must therefore be traced separately on the bitpad. To allow the drawings from each separate "montage area" (photograph on same section) to be merged into one picture properly, you use a special method of aligning the transparent sheets when you trace from the photographs.

When you need to trace over the edge of one area, align the sheet for the next area with the first by overlapping them with their holes from opposite corners placed onto one peg of the artist's jig, keeping the edges parallel. (Or you can just keep the sheets edge- to-edge, with the corners touching.) This keeps all of the sheets in the same relative rotation. The pictures from which you're tracing must have at least 10% overlap, and should represent neat rows of material from the sections you're photographing.

using alignment links to create the montage

When you're tracing from montages of transparent sheets, you first make the alignments for different "montage areas" by making extra alignment links (normally base links) which are created with the screen cursor moved from the first alignment link by an amount equivalent to the offset between your transparent sheets. Thus, each montage area should have its own alignment link which corresponds to the location of the same bitpad dot, but which represents a different area of the picture. Each area alignment link has a unique number in its "area" link field. When you're tracing from transparent sheets, you can select for that area by using the "general filter" for any of the "move to link commands" ("^a","^q","^r","^t"). Whenever you move to a link, the current status (defines the data to be entered into the fields of a new link) area field is set from the current link, so any new links are put inside the new area.

reference points

To create the extra alignment links, you need two reference points defined by the transparent sheet you're working from. The distance between the reference points represents the distance between adjacent montage areas. The reference points may be the artist jig peg holes, or you may use a corner of the sheet to define them.

Place the transparent sheet so that the first montage area is within the active area of the bitpad. Make a dot underneath the corner on a piece of tape on the bitpad, move the sheet by the amount required to place the next montage area in the active area of the bitpad, and make a second dot on the bitpad. Make two additional dots for another corner in the same manner, to keep the sheet in correct rotation alignment. Use these reference points to position the transparent sheets for the different montage areas. Of course, if you're using the peg holes for the reference points, you don't need to make any dots on the bitpad.

making montage areas

Montage areas are defined by alignment links; the "area" number in each link defines which area. To make a new area alignment link, you first set the "area" number in the current status ("s"). Go to the first alignment link with the "nearest link" ("^r") command, move the mouse (with the button down in absolute mode; in cursor mode) to the first reference point, move the mouse (with the button up in absolute mode; down in cursor mode) the proper distance to the second reference point, and make the new alignment (base "0") link. This alignment link defines a new montage area by changing the alignment between the bitpad coordinate system and the picture on the screen.

If you're setting up a series of sections for montages, you can save time by correctly making all the alignment links in the first section. Then copy them to all successive sections using the "next section" ("^p") command followed by the "base link" ("0") command. If you copy area links in this manner, you should set the "relative filter" ("fg 2") to a null filter spec (see next paragraph) so the area number in the current status doesn't get changed. Alternately, you can copy all the links in a section using the "cat" UNIX command to copy the section multiple times.

tracing transparent sheets using areas

Once all the alignment links are in place, you can easily switch from one area to another by going to the alignment link which defines that area. Whenever you go to a link, the current status gets set from the nearest link defined by the relative filter. This automatically sets the correct area number in the current status, so that you make all trace links which use that alignment link have the same area number. You can easily change the relative filter to define which links are used to set the current status. This is necessary when you're first making the alignment links: you don't want any previous alignment links on a new section to change your area number when you're copying area alignment links from an old section (see above).

tracing montage overlaps

Sometimes, you find that trace points overlap between two montage areas. In this case, you need to add new trace points to an already existing trace link from a different montage area. To do this, first position the new transparent sheet on the bitpad reference point (see "reference points" above). Next, go to the alignment link for the new sheet and move the mouse to the center bitpad dot, as you normally would to align the mouse with the cursor; then move the cursor near to the old trace link in the other montage area. Use the "nearest link, don't move" ("^s") command to establish the old trace link as the current link; this doesn't change the cursor position. With the "next point" ("^d") command, move the "CP" marker to the point just before (clockwise) the new ones you're going to add. Then add points to the trace link with the "make point" ("1") command.

coping with slow displays

When you're tracing cells with many points, you will find that the picture display is very slow. This is due to the small but real time it takes the computer to calculate and display the position of each point. You can alleviate this somewhat by keeping the bitpad button pressed (in cursor mode); then no new picture display occurs. You can also use the "short screen display" ("n") command to eliminate most of the numbers on the current status display. You can use the display filter to select only nearby links for display; set the display filter to
   xbio = cur -200, cur+200; ybio = cur -200, cur+200".

CLICK HERE to return to Table of Contents

Montage switches

To run montage with different graphics boards, you enter a command switch on the command line right after the "montage". The switches are:
          -b    Linux standard driver, as in plot(1G): "setenv GTERM epc"  
          -e    Enhanced Graphics Adapter (EGA)
          -g    Video Graphics Adapter (VGA)  default
          -h    Hercules board
          -c    change calibration for bitpad with 200 points/inch 
          -x    X Windows driver

CLICK HERE to return to Table of Contents

Some final words from experience

There are several ways to use Montage without going through the transparent sheet step, so 3-D reconstruction is available for many kinds of material. The standard transparent sheet tracing technique is often preferable because it gives a permanent record of how a cell was aligned and traced which can be checked by a second person. When studies must be occasionally re-checked after several months or a year, this factor is sometimes more important than the extra amount of time it takes to separately align and trace from photographs onto transparent sheets.

Montage is an evolving system, and is very easy to modify. We have tried to keep Montage as simple as possible so it's easy for those of us who don't have much experience with computers. At the same time, we have added advanced features that make Montage useful for many different types of 3-D reconstruction. If there is a problem with the manual, or Montage program or any of the other programs in the Montage system, please let us know so we can fix it.

If you think of a new feature you feel would be really useful to others, let us know. We may be able to change Montage to suit your needs. If you've purchased the source code, we encourage you to make the change yourself or get a programmer to do it for you. We would appreciate a copy of your changes so we can evaluate and add them for use by others.

CLICK HERE to return to Table of Contents

Mpict User's Manual

Mpict is a three-dimensional display program. It displays all the sections of a data file on the video screen. You can give commands to rotate and translate the picture, to create the picture you want. There are also commands to load and store corfiles. These files contain copies of all the display parameters that mpict uses.

mpict interactive

To run mpict on the video terminal, type "picture". This runs mpict interactively so you can change any of the the starting values of the display parameters. You first define the data file by typing "datfil = filename". The section increment is initially set to 1, which means that every section is displayed. You may change this or any other value by typing the parameter name, followed optionally by an equals sign, then the parameter value. You can abbreviate parameter names as long as they aren't ambiguous; for instance, "datfile" can be abbreviated to "da". You can also include multiple parameter definitions on a line by separating them with semicolons (";"). You can edit the line you've typed by using the "^h" (backspace) or "^u" (delete line) commands. You enter the line with a carriage return ( or "Enter" key).

picture display

The picture displays when you give the "run" command. You can stop the picture during the display by typing one "^C" (control-C). To stop the program, type two "^C's" or type the command "quit" or "q", followed by a blank line.

You may not actually see anything on the screen the first time you display a picture with the "run" command because the "xcent, ycent, zcent" center location can't be set until after the picture is drawn. Just run it a second time and the picture should be centered on the screen so it just fits in. The x,y,zcent and mag parameters are set automatically (when auto=1) so you don't have to worry about getting it centered.

CLICK HERE to return to Table of Contents

save and load corfiles

When you've got your picture to look exactly right, set the "corfile" with the line "corfile = myfile.cor". Then give the command "save". This saves the parameter values for your picture into "myfile.cor". If this file already exists, the new picture parameters overwrite the old file. The picture parameter file is called a "corfile" because it contains the coordinates for display of the picture. The corfile is a copy of the parameter display which you see on the screen.

If you want to make several pictures display at once, you can use the command "save !" which appends additional parameter values for another picture onto the end of the corfile, and doesn't erase the existing ones.

You can also use the commands "save filename" or "save ! filename" to create corfiles. If the corfile is not explicitly given or has not been defined by the "corfile = name" command, then the default file name "data.cor" is used for both the "save" and "save !" commands.

To load the parameters from a corfile you have already made, give the command "load filename". This erases all previously set display parameters and sets them to the values from the loaded corfile. The corfile can be used to run mpict without your attendance; see below. A corfile always has the parameter "auto" set off (0) so you can override the automatic mag feature by changing mag after you load an existing corfile (or turn off auto).

After you save a corfile, you can edit it with "vi" or "joe" and add extra "run", "include" and "erase" lines. To make your corfile easier to understand, you can put comments in wherever you want by putting a "#" at the beginning of the line. This causes "mpict" to ignore that line.

CLICK HERE to return to Table of Contents


Flag links in your picture can be displayed in a variety of sizes, shapes, and in eight colors. To define a flag for display, give the command:
     filter [num] [pen num] shape [size num] flag num
       "filter num"      is the filter number, from 0 to 99; 
       "pen num"         is the pen number for the plotter;
       "shape [char]"    is the symbol type printed at the flag;
       "size num"        is the symbol size;
       "flag num"        is the link flag number.
There are 100 filters available for displaying links. Each category of flag described in a filter line will be displayed with the pen color and symbol shape defined in the filter line. The pen color and symbol size do not need to be put on the line; if they're left out, the default pen color defined by the pen parameter in the corfile controls the color and the size is set to 4. If the symbol is "char", a following single character defines the shape to be a standard alphabetical character. To erase a flag display, type "flag number" and leave the rest of the line blank.

Flag sizes range from a tiny dot (1) to one-half the size of the full picture (15). Pen colors 1 to 4 are the pen numbers on the HP plotter, and colors 5 to 8 are a second round of colors used after pens 1 to 4. Shapes are:

   char    single char following symbol name: "char x"
   cross (plus symbol)
For example, the filter line:
     filter 1 pen 2 circle size 8 flag 24 
defines flag 24 to be displayed as a circle of size 8 (fairly large) drawn with pen 2.

The filter line:

     filter char R size 4 flag=10 f2=12
defines flag (10,12) to be drawn as an "R" of size 4 (small) drawn with the default pen. This filter line defines filter 0 by default because no filter number appears.

The filter line:

   filter tri anyflag=23
draws a triangle for a flag having a 23 in any of its flag fields.

You can include your "flag.def" file that you defined for the "montage" program into your corfile to allow you to make use of the flag definitions. For example, if your flag.def file had:

     bipolar = 25
     amacrine = 26
You could make use of these definitions by including the flag.def file into your corfile and defining a flag filter like:
   blue = 4
   include flag.def
   filter pen blue square size 3 anyflag=bipolar f2=7
This draws a small square using the blue (4th) pen for any flag with a 25 in any of its flag fields and a 7 in field 2.

CLICK HERE to return to Table of Contents

Display parameters (set = 1 to turn on; set = 0 to turn off)

xrot,yrot,zrot      Sets rotation of picture: xrot first, zrot last. 

xcent,ycent,zcent   Sets the center of rotation for the cell (set by auto)
                    Three-dimensional point in bitpad coordinates.

mag        Sets the overall magnification of the picture (set by auto)

auto       Normally set to 1.  This makes mag, xcent, ycent, and zcent 
           be changed the next time you run the picture.  This
           automatically keeps your picture the largest size possible
           and centers it for you.  If you turn "auto" off (0), you
           can change the mag to match the mag of other pictures.
           Always turned off in corfiles (automatically).

xtran,ytran    Sets location of picture on screen (normally 0.5,0.5).

incr      section increment (initially set to 1)

finc      flag section increment; 0 means finc = "incr" above (set to 1)

pen       Default plotter pen number (default 1).

zdist     Distance between sections (default 5)

line      Sets number of microns for calibration line.

calib     Sets proportion of (x,y) to z values for points, and length of 
           calibration line (number of microns per cm on bitpad).

xline,yline   Sets location of calibration line (default .95 .1);

fill       If set=1 produces slices filled with color.  Can be
           overridden by the value of fill in a filter spec.

hide       Sets default hidden line status.  Draws a picture on the 
           plotter with hidden line removal; set "hide 1".
           This causes the flags to be displayed           
           before the cell data, so the flags will not be hidden.
           The hidden-line memory is reinitialized after 
           each "run" command.  

clear      Clears the screen of text before the picture gets displayed.
           If you are running the program from a graphics terminal with 
           the same screen for both graphics and text, set "clear=1".  
           If not set, the previous picture stays.

notext     Causes screen to wait after picture is drawn before 
           returning to text mode for paramater display.

silent     The "silent = 1" command prevents printout of the parameters
           when running mpict from a corfile.  You can set this in
           the corfile, or you can run mpict with the extra switch "-s"
           which accomplishes the same thing (e.g. "mpict -s ....")

CLICK HERE to return to Table of Contents


Use this command to display only selected links.

The syntax is:

filter [n] [pen[=]n][;] [hide[=]n][;] [fill=n][;] [symbol] [size[=]n] filterspec 
Everything inside square brackets "[]" above is optional; that is, the equals signs "=" and ";" semicolons may be left out. The pen and hide commands are also optional; if they are left out, the default pen and hide settings take over.

For printouts of flags, "Symbol" means any one of: triangle, square, circle, cross, asterisk, or char (see the flags description above). "size" ranges from 1 to 9, giving symbols the size of a small dot to one half the whole picture. "fill" can be set on (=1) or off (=0) and will produce trace links or flags filled with color.

The filterspec is everything on the line after the options. It has syntax exactly like the filter in "montage" and "fstor" (see "filter" in section 4: Montage manual.)

You may run the filter very simply like: filter cell 5

Or you may make up to one hundred filters each with a unique number (0-99). These will appear in the corfile just as they do on the screen.

To turn off a filter, type "filter (num)" with the rest of the line blank.

You may include your flag definition file in a corfile so flags can be described by character strings instead of numbers.


Use this command to draw lines and write of text in your picture. The syntax is:
              label [num] label commands (rest of line)
The "label commands" are:
            charwidth x         set character width to "x".

            erase               erase screen

            move  x y           move pen to (x,y)

            draw  x y           draw to (x,y)

            line  x1 y1 x2 y2   draw line segment from (x1,y1) to (x2,y2)

            text x y "text"     write "text" starting at (x,y). '"' is the
                                delimiter char, which can be any character;
                                there must be matching char at end.

            pen num             change pen to "num".

            size x              change picture size to a square "x" on a side

            include "name"      include command file "name" at this point.

            flag shape size     draw flag like the filter  
The picture labels are drawn on a square picture which extends from 0 to 1.0 in both X and Y. This, however, may be changed with the "size" command.

You can abbreviate the above label commands to single chars; only the first character in each command is used. Multiple commands per line are allowed, separated by spaces. For example:

          c .02 p 3 t .2 .8 /Cell 8: bipolar/
          p 1 t .2 .75 "  Corfile zzz"
says character width = .02, pen number 3, text starting at .2 .8., followed by more text drawn with pen 1.
          flag tri 9          says make a flag which is a triangle of size 9
The above label commands are exactly the same as those for the "labels" command. The only difference is that you can enter the label commands into a corfile and the label will be drawn on your picture immediately after the picture is done. See page 6-15 for more details on drawing labels.


Causes the sections in a data file to be displayed in reverse; this has the effect that the cell is drawn as its mirror image.


This command resets all corfile values, including the flags, filters, and labels. The "erase" command is automatically inserted into the beginning of a saved corfile. You may, however, delete this line with the editor or add further "erases" if you wish. You can also give the commands:
erase flags    Erases only the flag defs in corfile 
erase filter   Erases only the filter lines in corfile
erase label    Erases only the label lines in corfile

derase         This command turns on/off the "erase" which 
               is normally put at the start of a
               saved corfile. Default is on (derase = 1).

include name   This command causes corfile "name" to be           
               loaded immediately into the display paramater 
               tables.  Previous values not set in the corfile are 
               not changed in the tables, unless the "erase" command 
               is in the included file.
Several of the above picture commands make use of the "standard graphics screen". This is defined to be a square with its lower left corner at the point (0,0) and its upper right corner at (1.0, 1.0). The (xtran,ytran) and (xline,yline) params as well as all of the (x,y) label commands use this standard screen, so their values should normally range from 0 to 1.

system commands from within mpict

You can run any UNIX system command by typing a "!" at the beginning of the line followed by any one line UNIX command. This is useful for looking at your directory while running "mpict" or "picture".

CLICK HERE to return to Table of Contents

mpict non-interactive

You may also run mpict in a non-interactive mode directly from a corfile you've already made. All the parameters in the corfile get read in, just as if you typed them in from the keyboard. You can type "mpict mpict -s < cell.cor | hide11 | hpflt -c | hplot; echo "pict done^G^G"& This would run "mpict" in the background from the corfile "cell.cor", and send the picture generated through the hide11 filter to remove hidden lines, then to "hpflt" and "hplot" to plot the picture. After this is done, the words "pict done" get printed, and the two ^G's ring the bell. The "-s" means don't print anything on the screen; this is equivalent to setting the "silent" parameter. Whenever you're hiding pictures, remember that hide9 runs 16 times faster than hide11, and hide10 runs four times faster. Use hide9 for rough layouts and for the video screen, then use hide10 pen trials. Only use hide11 for final copies because it is much slower.

After you get familiar with the corfile commands, you may use "vi" to edit corfiles, adding "run", "erase" and "include" commands to draw large pictures composed of many individual corfiles. You can make your corfiles easier to understand by using comment lines. You enter comments by placing a "#" at the beginning of a line; this causes mpict to ignore that line.

You can run mpict with several different switch options on the command line:

mpict -f   make ".m" output files from multiple ".cor" input files

mpict -m   use the secondary monochrome screen to display text 

mpict -s   don't write any text onto the screen; useful for batch processing 

CLICK HERE to return to Table of Contents

some useful picture commands

There are several commands you can use to run mpict automatically from corfiles. They are executable text files ("command files"), so you can print them out or copy them for your own use if you like. The "$argv" in some of the files means that the command will work on one or many files equally well. See next section for details on the "vid", "hide" and "hpflt" programs. These commands are in the "/usr/bin" directory:
   picture          This is the normal way to interactively
                    draw pictures, but can also be run
                    from a corfile or the standard input.
                    Pictures on screen are not drawn with
                    hidden lines removed. 

                    "mpict | vid -i"

   picthide         This is like "picture" except that it
                    will remove hidden lines if the "hide"
                    parameter is set. Not normally used.

                    "mpict | hide9 -i | vid -i"

   drawpic          This draws from a list of files to the plotter,
                    or it can draw from the standard input.
                    For the IBM Color Plotter, drawpic contains the
                    "ibmflt" line.  The "-c" option for hpflt (ibmflt)
                    sorts pens by color.  You may use any switch options
                    for hpflt (ibmflt) on the command line;
                    the third example below and pages 6-6, 6-7.

                      "hpflt -c $argv | hplot"    for HP 7221A plotter
                      "ibmflt -c $argv | iplot"   for IBM Color plotter
Examples of drawpic usage:
          drawpic < file1.plt
          drawpic file1.m file2.m file3.h file4.plt
          drawpic -w -m 2.5 -x 4500 -y 4500 file1.h -m 1.5 -x 7500 file2.h
   dopic9, dopic11: These draw pictures from one or many 
                    corfiles at once, using hide9 or hide11.
                    Remember, hide9 runs 16 times faster than
                    hide11, and hide10 4 times faster.

                      "mpict -s $argv | hide9 -i"

   makehid9, makehid11:  These take one or many corfiles and
                    produce corresponding ".h" files
                    for later display or plotting.

                         foreach i ($argv)
                           mpict -s <$i | hide11 -i >$i:r.h

CLICK HERE to return to Table of Contents

Linux Advanced Commands

Shell commands

You can combine any valid command lines in Linux to make more elaborate commands which can be put into command files using the vi editor, and then make them executable using the command "chmod +x file". These commands can then be run at low priority by the "nice" prefix command.

For instance, the command "draw9" (in "/usr/bin/draw9") contains:

     nice +20 dopic9 $argv | drawpic
The "#" in the first line of the file makes this command run under the "C-shell" program (see the CSH chapter in the Linux Introductory manual). This command line is be equivalent to:
     nice +20 mpict -s (command args) | hide9 -i | hpflt -c | hplot
When the command runs, the "$argv" in the "draw9" command gets replaced by any switches or file names you type on the line after "draw" (see the Linux csh manual for more details). The "nice" command only runs the first command in the line at low priority. The "draw9" command runs:
      "mpict -s file | hide9 -i"
at low priority because these commands are inside "dopic9". This command is also found in the directory "/usr/bin" for your use. You can use it like:
          draw9 file1           or          draw9 < file1
Or more elaborately:
          draw9 file1 file2 ... filen
Still more elaborately:
          draw `cat filelist`
Where "file1 ... filen" are corfiles to be plotted, or "filelist" is a file which contains a list of corfiles to be plotted. The "`"s (reverse quotes) around "cat filelist" in the last example cause the C-shell to run the command "cat filelist" first; the result of this (its standard output) is given as a list to "draw". You can draw pictures on the screen or with:
          dopic9 corfiles | vid

CLICK HERE to return to Table of Contents

Composing illustrations: posit

Once you've drawn several pictures to your satisfaction, with rotations and details like flags and pen colors set correctly, you can compose illustrations by combining several pictures into one on the plotter. This is useful where you need to take existing pictures and adjust their relative positions on a page. You can position the individual pictures from corfiles and then hide them all at once to create distance perspective where one picture overlaps another.

The posit program allows you to merge several pictures and send the resulting picture to be hidden, displayed or drawn on the plotter. This process simplifies complicated illustrations because all the individual pictures can be generated and hidden separately, and this need only be done once. Composing the illustration is thereby easier because only the locations of the individual pictures has to be defined.

Example 1:

          posit -f -x 1000 -y 7000 file1.h -x 4000 -5000 file2
This creates file1.p and file2.p with (x,y) offsets from existing ".h" files which had already been hidden.

Example 2:

          posit  -f -x 1000 -y 2500 file1.m -x 1500 -y 2000 file2.m
          hide11 -f -h file1.p file2.p  
This creates file1.h and file2.h with (x,y) offsets from corresponding ".m" (mpict) files and then hides the second picture behind the first using the "-h" option for hide on the ".p" output files. Pen colors are preserved.

If you have several picture files to make, hide and position, you can run them most easily by using the -f options with mpict, hide and posit. For example, by running

     mpict -f ab*.cor 
you can make lots of pictures from many cor files all at once. Each corfile must have a different name, but if the names have some of their characters in common, you can use the "?" and "*" wildcards to refer to them selectively. The "datfiles" referred to inside the corfiles may be any valid data file, and in particular may be the same data file. This is a good way of generating several views of one cell from one command line, without needing to type lots of file names.

An alternate way is to use the command "makehid11 file1... filen" and then to use posit afterwards (see page 6-20).


You can create quite subtle overlay and transparency effects with judicious use of the hide11 and posit commands. You can merge two pictures, each with its hidden lines removed, by drawing one on top of the other with a different pen, to give the impression of transparency. By running the output of posit through hide11, you can cause the first pictures in an illustration to be in front of those added later. Normally, however you get better results if you run hide on pictures not previously hidden, so you should posit all you pictures before you run them though hide11. For example:
   posit -f -x 1000 -y 3000 file1.m -x 2000 -y 4500 file2.m
   hide -f file*.p
   drawpic file*.h
Another way to achieve the same transparency effect is to make a ".cor" file which draws several pictures using filters from one file, separated by "runs". For example you could use the ice or vi editor to make the following corfile "file1.cor":
     xrot 0
     yrot 10
     zrot 0 
     hide 1
     datfile file1.dat
     corfile file1.cor
     filter 1 pen 5 cell=4
     filter 1 pen 3 cell=8
     filter 1 pen 6 cell=12
This "file1.cor" corfile draws three cells with different pens, all on the same picture. When the picture is run through the hide filter, the cells all have their internal hidden lines removed but will be "transparent" to each other. You can position them with "xtran" and "ytran" in the corfile. To create this picture, use the following commands:
   mpict -s file1.cor | hide11 >file1.h
   makehid11 file1.cor             makes same ".h" file

   drawpic file1.h                 draws the picture on plotter
   vid     file1.h                 draws the picture on the screen

CLICK HERE to return to Table of Contents

Summary of file types

In the UNIX system, file names can be anything you want, but the "C-Shell" has an easy way to deal with names that have ".something" at the end of the file name ($var:r cuts off ".something"; see the csh manual for details). This makes it useful to have the ".something" stand for a file type, and in this manual we have standardized the following file types:
which creates
file       Picture       vi          mpict -s    hide        posit

file type   .cor         .cor        .m          .h          .p

purpose     To store     To modify     to make    to remove   to position
            parameters   labels,       picture    hid lines   a picture


CLICK HERE to return to Table of Contents

Making higher level commands

If want to compose an illustration which requires a set of pictures individually placed, with labels to go with them, you might run commands like:
          makehid ab*.cor
          posit -f -x 2000 -y 3300 ab1.cor  
          posit -f -x 4500 -y 3800 ab2.cor  
          posit -f -x 6700 -y 2000 ab3.cor  
          drawpic ab*.p
          labels << eof | drawpic -x 6000
          t .2 .3 "Washington"
          t .4 .35 "Lincoln"
          t .65 .2 "Trudeau"
In this example, the "<< eof" after labels is a csh command which says take all the text up to the word "eof" in the shell file as the standard input to "labels". See the csh manual for more details. You can achieve the same result with the command:
          labels < labelfile | drawpic
where labelfile contains the same sequence of labels as above. Which is easier for you?

You might want to repeat this sequence of commands several times to get the positions of the pictures and labels right. Instead of retyping the whole command sequence, you can simply put it into a text file using "vi" or "ice" and have the shell run this file for you. This allows you to copy the file and easily make changes without removing your original copy if you want to go back to it.

          vi presidents                make the file
          chmod +x presidents          make it executable 
          presidents                   run it
          cp presidents pres2          copy it
          vi pres2                     make new version
          pres2                        run new version
You can replace the drawpic in the above example with a variable like plot so that you can first run the command with "vid" to plot on the screen and then run it on the plotter with "drawpic". Vid and drawpic are designed to use the same switch arguments, to make this possible. You can set numeric variables with the "@" command (see the csh manual). You set string (char) variables in the csh language with the "set" command:
     set plot = "abc"
     $plot ab*.p                   use "$" to invoke variable
     labels < labelfile | $plot -x 6000
You can set a variable from the command line which invokes the command using the standard csh notation:
     set plot = $argv[1]
     $plot ab*.p                   var is first arg after command
     labels < labelfile | $plot -x 6000
Then run the command with different values for the variable:
     president vid
     president drawpic
There are numerous possibilities for this type of command-making. The csh has many of the control statements which exist in the "C" language, including the "for" and "if" statements. Use your imagination, and read the "csh" manual.

CLICK HERE to return to Table of Contents

Utility Programs


"fstor" allows you to store data files into compressed form and retrieve them from compressed form into data files, optionally using the filter to select which data to copy. You can compress files to make them fit on a floppy disk by using the "store" command. You can get them back into the original data file with the "retrieve" command. You can also copy files with the filter. Normally, you use fstor for making backup copies of your data files. You can also break a large file into smaller files using fstor to copy only selected ranges of sections.

When you run fstor, get the help table with "h":

     c    copy file using filter

     f    change filter (see section 4: montage manual)

     h    help table

     l    change section length (see section 4: montage manual)

     n    renumber sections in file; useful after merging files

     r    retrieve file from storage using filter

     s    store file in compressed form using filter

     v    verify file (take out garbage, make all trace 
          links clockwise, fix section numbers)        

     z    change from format (old UNIX system) to 
          current .dat file format

     X    exit from program
The "fstor" filter command uses the same filter as described in the montage manual (section 5 of this manual). However, a special feature of the fstor filter table is that the filter continues from one filter spec to the next as long as the next filter spec has been defined. A link will be selected if it fits any of the filter specs on different lines. This gives you more space to define filters.

You can also run fstor with command line switches. When you are familiar with Linux, this is the faster way. The Linux version of fstor has the following switches (see Section 3 for a description of command line switches):

     -C    copy from stdin to stdout
     -D    reverse copy from stdin to stdout
     -N    renumber from stdin to stdout
     -R    retrieve from storage from stdin to stdout
     -S    store from stdin to stdout

     -a num    calib for "above", "below" in filter (um per cm)
     -b    use following number as start section
     -q    use following number as stop section
     -l num   change section length to num 
     -c    copy from immediately following filename to next
     -d    reverse copy file from following filename to next
     -n    renumber from immediately following filename to next
     -r    retrieve from immediately following filename to next
     -s    store from immediately following filename to next
     -t num    section thickness in um for "above","below" in filter
     -v    verify from immediately following filename to next
   fstor -l 512 -r file1.sto file1.dat       Retrieve a data file

   fstor -s file2.dat file2.sto              make a .sto file 

   fstor -b 10 -q 120 -R file1x.dat   look at part of a file
For archival storage, you may want to further compress your files using the gzip(1) and gunzip(1) commands supplied with Linux. These commands use a data-compression technique which makes use of the fact that some 8-bit bytes are more common in a file than others. This works well for text files and some binary data files (".dat" or ".sto" files) because they don't contain an equal distribution of all bit patterns.
   gzip alpha.dat                        gzip is Linux's compression prog.
   gunzip alpha.dat.gz 

CLICK HERE to return to Table of Contents


Glink prints out links in a data file. It can display the number and type of links and the number of points, or it can print the area, grain density and perimeter of links. You can select which links to display using the filter. See next page for more "glink" examples.

The glink help table:

     a    find area, perim (print section totals and grand total)
     c    change Calibration (microns per centimeter)
     d    display links (print section totals of number 
           of links and points, and grand total)
     f    change Filter (see section 4: montage manual)
     l    change section length (see section 5: montage manual)
     s    section thickness (microns)
     t    display indiv trace and areas and perims when 
               used with "a" mode above
     q    exit program
The Linux version of glink can be run from the standard input to the standard output with the use of the following switches (see the Section 3 for a description of command line switches):
     -A    area and perimeter
     -D    display number and type of links
     -F    flag links only
     -Z    display all link fields (for debugging)
     -a    area of following filename, output to following filename
     -d    number and type of links from following filename
     -b    use following number as start section 
     -c num    calib for "above","below" in filter
     -f    make ".g" files from data files
     -g    read flag defs from "flag.def"
     -q    use following number as stop section
     -s    section thickness (microns)
     -t    display indiv trace areas and perims with totals 
For example:
               glink -D file.dat
This command causes glink to display the number of links in "file.dat" on the screen. If you want to put the output into a file, you could use:
               glink -D file.dat >file.g 
You can run glink on several data files at once, using the "-f" command-line switch. For instance:
               glink -f -A file1.dat file2.dat file3.sto
This analyzes the data files for area and perimeter and makes "file1.g", "file2.g", "file3.g" from the data files.

Using glink intelligently

Glink analyzes your data and prints large reports. However glink's reports may not be formatted exactly as you would like them. UNIX makes it easy to get the report you want by filtering (selectively printing) and sorting, using standard tools. You can filter and sort the output from Glink with grep(1) and sort(1) to organize your data for printouts. For more powerful list processing you can use awk(1) to reformat, move columns around, and make totals of columns. See the Linux User's Guide for more on awk(1).

For instance, you could enter the following command line:

   glink -F file.dat | grep amacrine | sort +3 >file.srt
to get a total of all "amacrine" flags in a data file, sorted by their flag numbers (column 3 of glink output).

You can use column and var (supplied with Montage) to get the standard deviation of selected data. column prints out a selected column from the standard input or a text file, and var prints the mean, variance, and standard deviation of a list of numbers. For instance:

   glink -t -A -b 4 -q 9 datafile | grep ' a ' | column 3 | var 
gives the standard deviation of all trace links on sections 4 through 9 of "datafile". The "grep ' a '" filters out only the individual trace areas printed by the glink "-t" switch. You could make it easier to use this sequence of commands by inventing your own command called gvar:
   glink -t -A -b $1 -q $2 $3 | grep ' a ' | column 3 | var
Then you could invent another command to automatically graph this data in a histogram, which you could name histo:
   gvar $1 $1 $2 | bins -w 20 | graph -M 40 | drawpic
This command "histo" allows you to gather data from any selected set of sections, make a histogram with "bins" (see below), and plot the data using "graph" (see below) and "drawpic".

The column command (used above) is merely a shell file (executable text file: chmod(1)) invoking awk(1):

   awk "{print \$$1}" $2
Everything inside the "{ }" brackets is the awk command. The \$$1 passes the column number to awk from the shell command, in this case "column". The $2 means pass the second argument from column to awk as a file name. This means you can use the column command on a file name without a pipe to its standard input:
    column 4 file5.g
To find the approximate radius of traced polygons, you might use the formula:
   radius =   (perim / (2*pi) + sqrt( area / pi)) / 2  
It's easy to do this kind of processing with the following commands. First make the glink file which contains the areas and perims of individual polygons.

Use the editor to make the command "garea":

   glink -t -A -b $1 -q $2 $3 > $3.g
Next process the separate "a" and "p" lines together and compute the formula:

The command "grad":

    awk ' $1 == "p" { printf ("%g ", $3) }
          $1 == "a" { printf ("%g\n",$3) }' |\
    awk ' { print ($1/(2*3.1416) + sqrt($2/3.1416)) / 2; }
You could then run the commands:
      garea 1 2 file.sto
      grad < file.sto.g
and you get a list of radii of individual traces.

As you can see, "awk" is very powerful and easy to use. See "The awk Programming Language" chapter in the Linux Support Tools Guide, or The AWK Programming Language by Aho, Kernighan and Weinberger (available in paperback) for information and examples on how to use awk(1).

CLICK HERE to return to Table of Contents


The hide program erases lines in a three-dimensional drawing which should not be seen because they're hidden. You can pipe the picture data from the picture program through one of the hide programs. There are three hide programs, called "hide9", "hide10", and "hide11". They are exactly the same except that the resolution of the picture is different. "hide9" gives a resolution of 512 x 512; "hide10" gives 1024 x 1024, and "hide11" gives 2048 x 2048. "hide9" runs 16 times faster than "hide11", and "hide10" runs four times faster. Use "hide9" for rough copies and the video screen, and use "hide10" for testing pens on the plotter. Use "hide11" for final illustrations only because it runs much slower.

Command line switches for hide are:

          -i        run hide in non-interruptable mode

          -f        make all input files into corresponding
                    ".h" output files

          -h        make picture hidden even when hide not set

          -j        make picture non-hidden even when hide set
For instance, to make a picture on the video screen with hidden line removal, enter "mpict | hide9 -i | vid -i". This is the same as the command "picthid9".

The usual way to run the "hide" programs is to run a shell command file (See Sect 3) which contains a command line invoking the "hide" program. A typical hide command is:

   makehid11 *.cor            makes ".h" files from ".cor" files
You can use the "-f" option in the mpict and hide programs to automatically create files for you. Mpict makes ".m" files and hide makes ".h" files. This is especially helpful when you are making composite illustrations out of picture files you have already made.
   mpict -f -s *.cor          makes ".m" files from ".cor"
   hide11 -f *.m              makes ".h" files from ".m" files

CLICK HERE to return to Table of Contents

hpflt and hplot, ibmflt and iplot

You use "hpflt" (or "ibmflt") to convert the picture data coming from mpict or hide into plotting data suitable for the HP 7221A (or IBM color) plotter. "hplot" ("iplot") does the actual data transmission to the plotter. Switches for hpflt (ibmflt) are:
          -c        sort output by pen color (waits until end to draw)

          -i        non-interrupt mode

          -m        Use following number as mag, default 1.0

          -p        Use following number as plotter pen number.
                     This overrides any pens defined in the picture file. 

          -r        Rotate picture sideways 90o

          -s        Use following number as speed for plotter,
                    up to 30. Default is 4 cm/sec.

          -x        Use following number as x offset (default 7500)
                    This is the center of the picture, calibrated in
                    thousandths of an inch. One cm = 400 units.

          -y        Use following number as y offset (default 5000)
                    Calibrated as "-x" above.

          -w        Wait after using each pen, to allow paper to be changed 

          -z        Save individual pen files after exit; use with "-c" above
To use the plotter, first read "running the plotter" below. Pipe the your picture data into "hpflt" ("ibmflt"), and then into "hplot" ("iplot"). The "drawpic" command combines these two into one command that is easier to use. For instance, to make a picture defined by the corfile "cell.cor" you could type:
     mpict cell.cor | hide10 | hpflt | hplot
or   mpict cell.cor | hide10 | drawpic
When you run the plotting programs this way, you may find that they run too slow, causing the plotter pen to leak on the paper. You can save the results of the hidden line routine in a temporary file by typing:
                    mpict -s  cell.cor | hide10 > cell.h
               or   makehid10 cell.cor

   then later:      drawpic cell.h
This will draw the picture faster, because the slow hide10 program does not run when the picture is being plotted. Use the makehid or dopic commands described in section 5 to create plot files (".m",".p", or ".h").

The drawpic command is a convenient way to run the "hpflt -c | hplot" ("ibmflt -c | iplot") combination because these individual commands are all put into a command file for you, set up to use either standard input or a list of files. The command 8by11 draws pictures on standard 8 1/2 x 11 inch paper in the same way as drawpic but at a smaller mag. See section 5 for a description of picture command files.

If you want to include more command line switches, you can add them before the file name:

   drawpic -w -p 2 -m 1.5 -x 5600 -y 4600 file.plt
The drawpic ("hpflt -c" switch) command sorts all the pen draw commands according to the color of the current pen used. This is a more efficient use of plotter time, because each pen is only used once. This makes the plotting process go faster, although the plotting is delayed by up to a minute because of the need to sort all the plotter commands.

When you have defined more than 4 pens in a picture, you can use the "drawpic -w" switch to stop the plotter after each pen is used. This allows you to change the paper or the pen for each separately defined pen. Another way to insert more pens is to wait until the first four pens have been used, you stop the plotter by pressing the plotter "Enter" button, and then change the first four pens (1 - 4) to their corresponding colors the second set (5 - 8). After the pens are changed, press the plotter "Enter" button again to resume plotting.

The "drawpic", "vid" and "posit" commands are designed to use many of the same command line switches so they can be used nearly identically in command files.

CLICK HERE to return to Table of Contents


You use "vid" to display graphics data that comes from "nc" or "plotmod".

Vid command line switches are:

   -a       make "postscript" file on stdout: "vid -a > file"
   -c       make color "postscript" file on stdout: "vid -c > file"
   -l       make "postscript" raster file on stdout.
   -e       use Enhanced Graphics Adapter
   -h       use monochrome Hercules board
   -t       use Tektronix 4014 type display terminal
   -X       use X-windows for graphics display
   -d name      define name of X-windows screen to display on  
   -k       invert screen (upside down)
   -m n     use "n" as mag, default 1.0
   -p n     use "n" as color (16 colors)
   -r       rotate picture sideways 90 deg
   -w n     use "n" as size of X-window. 
   -x n      use "n" as x offset (default 8192)
                      This defines center of picture.
   -y n      use "n" as y offset (default 8192)
                      This defines center of picture.
   -v       don't erase screen when first starting video graphics mode.

Example:       nc -t file1 | vid        (="neurc file1") 
               nc -t file2 | vid -v     (don't erase screen)
Vid normally erases the screen when you first run it, but you can tell it not to with the "-v" switch listed above. Vid normally doesn't erase its picture when it is finished displaying. To get back to text mode you use the "t" (or "textmod") command. This doesn't erase the graphics screen, so you can run vid several times with as many text commands in between as you want. For instance:
   vid file1                          (make first picture on screen)
   ls -l
   cd otherdir
   vid -v file2                       (superimpose 2nd picture on first)


This command changes the video screen back to text mode. Command line switches are:
   -e     EGA driver.
   -h     Hercules driver. 
   -v     Change from text mode back to video
           (restore a previous picture)
"textmod" is normally run (aliased) to run as the command "t".


Posit allows you to set the position of subpictures in an illustration consisting of several picture files. Posit has the same command switches as "vid" and "hpflt", but it doesn't display the files; it merely puts them on the standard output or into output files of extension ".p".

Posit command line switches:

          -i        non-interrupt mode

          -f        make ".p" output files from input

          -m        Use following number as mag, default 1.0

          -p        Use following number as plotter pen number.
                     This overrides any pens defined in the picture file. 

          -x        Use following number as x offset (default 5000)
                    This is the center of the picture, calibrated in
                    thousandths of an inch. One cm = 400 units

          -y        Use following number as y offset (default 5000)
                    Calibrated as "-x" above.

Example 1:
          posit -f -x 1000 -y 7000 file1.h -x 4000 y -6000 file2.h
This creates file1.p and file2.p with (x,y) offsets from existing ".h" files which had already been hidden.
Example 2:
          posit  -f -x 100 -y 250 file1.m -x 150 -y 200 file2.m
          hide11 -f -h file1.p file2.p  
This creates file1.h and file2.h with (x,y) offsets from corresponding ".m" (mpict) files and then hides the second picture behind the first using the "-h" option for hide on the ".p" output files. Pen colors are preserved.

Batch proccessing using mpict, hide, hpflt, posit, fstor, glink

These programs may all be run with their standard inputs redirected to files. You can also run them like "hpflt file" without the "<" symbol for the standard input redirection. Multiple input files are also allowed on the command line, as in "hpflt file1 file2". This allows batch processing of your files into one output file. Mpict and hide can be run with the "-f" switch to automatically create output files corresponding to input files with the ".m" and ".h" extensions added onto the input file names.

CLICK HERE to return to Table of Contents


Graph is described in the Ampex Plotting Package Manual. It is similar to the standard "graph" command that comes with most UNIX systems. It takes pairs of numbers separated by spaces from the standard input as the X and Y values of a graph. Successive points are connected by straight lines. You can display the graph by piping to either "vid" for the video screen or "hpflt" for the plotter. The maximum and minimum dimensions for the graph axes are normally determined automatically from the data on the input stream. There are many useful switch options for this program, described in the manual. Graph switch options:
   -c char             char is point label
   -C char             char is point label; no connecting lines 
   -f filename      "filename" is a file containing a list
                         of points; filename "-" means standard input;
                         maximum of 8 filenames allowed.
   -g num           num is grid style; 0-> solid grid; 1-> dotted grid;
                         2-> no grid but solid maxima; 3-> no grid(default)
   -l "label"       label for x axis
   -L "label"       label for y axis
   -m val           min for y axis
   -M val           max for y axis
   -p num           num is pen/dash style when doing multiple graphs 
                      with the -f switch:
                         0-> dashes only (default);
                         1-> pen changes and dashes;
                         2-> pen changes only
   -t num           num is the tic style of x-axis:
                         0 -> many tics, few numbers (default);
                         1 -> few tics,  few numbers;
                         2 -> many tics, many numbers;
                         3 -> few tics,  many numbers
   -T num           num is the tic style of y-axis:
                         0 -> many tics, few numbers (default);
                         1 -> few tics,  few numbers;
                         2 -> many tics, many numbers;
                         3 -> few tics,  many numbers;
   -o               make x axis logarighmic (bug in axis labeling)
   -O               make y axis logarighmic (bug in axis labeling)
   -v num           point label char size, 1=small, 7=large;
   -w num           x axis char size for label, 1=small, 7=large;
   -W num           y axis char size for label, 1=small, 7=large;
You can run graph interactively by typing "graph | vid" and then entering a set of points, one x,y point pair per line (x and y separated by spaces not commas), and a CTRL-D to stop entering data and display the graph. You can also make a text file with an editor and run "graph < file | vid" which causes graph to get its input from the file instead of the keyboard.

using graph intelligently

If you want to draw several (up to 8) lines on a graph, you can use the "-f" switch to include several files as input data. Put a "-f" before each file like this:
          graph -f file1 -f file2 -f file3
and the first one will be a solid line, the second will be a dotted line, and the third will be a dashed line. If you want colors, use the "-p" switch.

If you want to have control over the scale of the plot (so that it isn't always drawn as a square which fills the page) you can use the "-m" and "-M" switches for the y-axis, and you can include some dummy extra points to extend the x-axis, one for each end.

   For instance:

     0 0                 extends left side to 0
     data points
     10 0                extends right side to 10
You can use the "grp" comand to run graph automatically on several file names:
     grp file1 file2 file3 | vid
"grp" is a C-shell command file which contains something like:
set pen = 1

#set axis = 
set axis = "-T 3 -t 0"
set min =
#set min = "-m -.1"
set max =
#set max = "-M 1.2"

if ($#argv == 1) then
  graph -p $pen $axis $min $max -f $1

else if ($#argv == 2) then
  graph -p $pen $axis $min $max -f $1 -f $2

 ( and so on up to 8:  "-f 1  ...  -f $8" )

CLICK HERE to return to Table of Contents


Bins generates a histogram from a sequence of numbers at the standard input. The histogram is output as a sequence of X,Y number pairs, suitable for input to "graph" above. Bins switch options:
     -h             make two points per bin for histogram graph
     -n             cause bins to be not centered on binwidths
     -o num         num = offset value for array             
     -w num         num = bin width
The switch option "-w" uses the following number in the command line as the bin width. For example, given a file of numbers "sample" you could type:
     bins -w 5 -h < sample | graph | vid

     to see the histogram of "sample" displayed on the 
screen, with a bin width of 5.


Spline is a nice addition to the graph command. It takes a sequence of X,Y number pairs and generates a smooth curve from them, suitable for input to graph. For example, you could type:
     spline < list | graph | vid
to see "list" displayed as a smooth curve instead of with straight lines.


Var takes a sequence of numbers, one number per line, from the standard input and prints the variance and standard deviation to the standard output.

CLICK HERE to return to Table of Contents


Labels takes input from the standard input and draws lines and text on the standard output for use as a pipe to either "vid" or "hpflt". It uses commands identical to the "label" command in "mpict". The commands are:
     ch x                     change char size to x.
     ci x                     make circle with radius x.
     erase                    erase screen.
     flag shape size          draw flag as in "filter" in mpict(5).  
     fo x                     change text font to x.
     fr name                  move to frame "name".
     include name             include file "name".
     move x [,] y             move pen to (x,y).
     draw x [,] y             draw to (x,y).
     line x1[,]y1[,]x2[,]y2   draw line segment from (x1,y1) to (x2,y2).
     o x                      make dashed line of type x.
     or x                     set origin of frame to (x,y).
     pen num                  change pen to "num".
     rd x [,] y               relative draw to (x,y).
     rm x [,] y               relative move to (x,y).
     rl x [,] y               relative line.
     ro x                     rotate x degrees.
     size x                   set size of picture to "x".
     text x [,] y "text"      write "text" starting at (x,y).
     u "text"                 write "text" at current position.
     q                        quit to shell                   
All "labels" commands can be abbreviated to their first letter; for example, "m x y" means "move x,y". Commands having the same first letter need two letters.


   c .05 p 3 t .7 .9 /Right Side/
   move .7 .8 flag char E 12 move .4 .7 flag tri 4
   i elephant
This command sequence writes "Right Side" starting at location (0.7,0.9) with a character size of .05 using pen 3, then writes two flags, and then runs the file "elephant" which could have other label commands in it (e.g. it could draw an elephant).

The labels program normally draws lines inside the standard video screen, which is defined to have its lower left corner at the point (0,0) and its upper right corner at (1.0, 1.0). Anything outside this square viewing window is not displayed. You may redefine the size of the window using the "size" command by giving a factor with which to scale the standard screen. You may also create sub-pictures within the standard picture which can be rotated, translated and scaled with respect to the standard picture. Each sub-picture (frame) can have its own sub-pictures, much like the UNIX file system. You move from one frame to another by using the "frame" command (.. means parent).

CLICK HERE to return to Table of Contents


Density allows the user to find the area inside any closed curve, the perimeter around the edge of the curve, and the density of grains inside the curve. The "density" program runs on any IBM-XT or AT which has a "Sketchpad" digitizer (bitpad) connected. You enter tracing commands for "density" from the four buttons on the mouse, but you use the keyboard to change display modes and enter new calibrations. Note that most of the functions of "density" can be accomplished automatically from trace data files using the "glink" program.

You trace around the circumference of the curve with the bitpad's cursor, keeping the "Z" button pressed while moving the cursor. The computer receives a continuous stream of X,Y values from the bitpad; these define the path that the cursor takes in time. The computer does an approximate integration on the point stream; it defines small rectangles underneath the curve; these are added to a continuing sum to produce the total area when the curve has been completely traced.

The program uses the following algorithm:

Differential X and Y values (deltas) are calculated by subtracting the previous X and Y values from the present ones. The area of a small rectangle which defines the area under the curve between the present point and the previous point is calculated, and added into the area sum. This rectangle has a width of delta X, and a height of the present Y value minus one half delta Y. The X and Y values are determined as differences themselves from a "zero" point. You set the location of the zero point whenever you press the bitpad "1" or "2" buttons.

Assuming that you start on the leftmost point on the curve, and trace along the top of the curve clockwise, the area sum would contain the area of the curve plus all the area beneath the curve as well; this is not what you want. But if you keep tracing clockwise along the bottom of the curve back towards the starting point, the area underneath the curve gets subtracted, leaving only the area inside the curve as the final sum. This result is obtained with the algorithm described above because if the point stream has negative delta X's, the areas of all the rectangles defined will also be negative, and therefore will subtract from the sum. The algorithm will work for any closed curve no matter what its shape, and no matter where you start tracing on the curve.

It's important that you don't move too fast, so that the points aren't too far apart; this would lower the accuracy of the area summation because the differential rectangles would not be close to the true shape of the curve. It is also important that you trace the exact entire curve; there should be no overlap or underlap. The algorithm does not check for start and finish points, so that as long as the trace button is pressed, the point stream is analyzed and area computed. In fact, you may stop tracing, let the trace button up, and take a rest; then you may start again, tracing with the button pressed again. The algorithm ignores the point stream when the trace button isn't pressed.

CLICK HERE to return to Table of Contents

accuracy and repeatibility

The density program doesn't always give correct answers. There is "noise" in the readings from the bitpad, and this makes the "density" program sometimes give slightly different numbers when you make traces around areas. Occasionally, there can be huge errors in the digitized numbers.

When using "density", it's important to make sure you're getting consistent values for your area and perimeter tracings. You should test your results by digitizing one area ten times. Note the answers, and find the largest, smallest, and average value. If the largest or smallest values for the area are different from the average by more than 5%, you have some kind of problem with repeatability. This could be due to tracing the area too fast, or it could be noise in the bitpad digitizer. If you can't get better accuracy, then ask for help (see section 2: "components", for a description of what to do).

You should also verify that your readings are accurate; that is, you should estimate the area of a region by some other means, and then compare this with your readings from the "density" program. You can draw a square which is 2 centimeters on each side and digitize its area. Try it in two different orientations; edge up and corner up. You should get 4 square cm for area, and 8 cm for perimeter. The numbers generated by the bitpad correpond to 400 per cm. You can draw a horizontal line a 2 cm long to check the operation of the bitpad itself; it should give a "dx" value of 800.

Never assume that the computer always gives you the correct answer unless you have tested it yourself!

The absolute limit on the accuracy and repeatibility of the density program depends on the digital representation of point locations by the bitpad. The bitpad always has the chance of being off by plus or minus one, because it is a digital device. Therefore its accuracy is also ultimately limited to the reading you get, plus or minus one. If you are tracing an object which is about 2 mm across, its dimensions will be about 100 in raw bitpad coordinates (absolute x,y on the screen). The linear error would be at least one percent (one in 100), and the area error would be at least two percent (errors add when uncertain numbers are multiplied). So your error will get larger for smaller objects being traced. You should make an estimate of the error for the diameter of object you're tracing, so you'll know what to expect.

CLICK HERE to return to Table of Contents

running density

The bitpad 4-button cursor must be on the tracing pad within the depression, in order for the program to run. When it is running, the program continually prints the absolute X and Y values, the zero X and Y values. You can make the delta X and Y values appear also, but this slows down the display considerably, and makes the points further apart.

If density runs ok, you may use it now to trace area. To see the commands available, type "h" for help. You can set the calibration with the "c" command, change to perimeter ("p") mode, and display dx and dy ("d").

The functions of the four buttons on the cursor:

     1 = Trace button:  Press this to sum area and
             perimeter as you move the cursor.

     2 = Add subtotal to total:  Press this button if
            you want to add the present area subtotal to
            the area total.  This also clears the subtotal,
            and creates a new zero reference point.

     3 = Clear subtotal, don't add to total.  You press
            this button to discard the present subtotal,
            without adding it to the total.  This leaves
            the total unchanged, and also creates a new
            zero reference point.

     4 = Count grains.  Press this button to give an automatic
            density subtotal.  This adds to the density total
            when you press button 1.

        The average is displayed on the screen below the
        total sum.  This average is computed from the 
        total sum divided by the number of times the
        subtotal has been added to the total.

        All of the above commands give the user an audible
        beep when density has accepted the keypress.
        In order to enter a command properly, you must
        hold a button pressed until you hear the beep
        (except on a system where there's no beep).
To see what commands are available with density, press "h" and the following help table will display on the screen.

density commands:

     a    set Area mode
     c    change Calibration
     d    Display dx, dy
     h    Help table
     p    Perimeter mode
     q    quit to Linux
     r    Remove entry; restore previous values
     s    change Section count
     t    change area Total
     u    Update grain total
     x    quit to Linux
     z    zero all totals

To stop the density program, enter the command "x" or "q", and the Linux prompt "%" will appear at the bottom of the console screen.

CLICK HERE to return to Table of Contents

Programmer's Guide

February, 1988

Hardware required for Montage.

Montage needs a computer which has a high-speed fixed disk. Although the Montage system could run on a floppy-based system, the high speed and large capacity of hard disks makes 3-D reconstruction much easier. Many brands of personal computer are suitable; a particularly good combination of high speed and low cost are the AT compatibles with 30 or 40 Megabyte Winchester drives.

The Linux operating system runs on AT compatibles, and has been used to develop the Montage system. Although neither an AT compatible nor Linux are necessary to run Montage, they are highly recommended.

Hardware needed:

          386 (w/387 math coprocessor) or 486 PC-clone 
              200 MB hard disk 
              3.5" and/or 5.25" floppy
              and 4MB RAM (8MB for running X, recommended)     
          digitizing tablet (Summagraphics MM-1201)
          graphics card with hi-res capability (SVGA, pref S3).
          laser printer or pen plotter (IBM Color Plotter or similar).
          2 serial communication lines.
Software needed:
          Linux or other UNIX-compatible operating system.
          Montage system.
          Ampex graphics package (included free).
The Linux system is available by anonymous ftp from:
Documentation on Linux is available at:
Summagraphics Digitizing Tablets (MM-1201) are sold by:
          Tri-Marc Inc.
          11716 Parklawn Dr.
          Rockville, MD  20852
          (301) 213-4991
Contact Summagraphics, Inc., 35 Brentwood Ave, Fairfield, CT, 06430 Phone # (203) 384-1344 for other distributors.

CLICK HERE to return to Table of Contents

Notes on Installing Linux

You should carefully read the Linux installation HOWTO documents manual when you install Linux on your harddisk. Here are some helpful hints for installing Linux on a computer used primarily for 3-D reconstruction.


First, you should make sure that you give the Linux file system (the disk partition) enough room to hold all of the Linux system, the source and binary code for the Montage system, and lots of data files. Linux needs about 20 Mega-bytes to function, minimal. When you select partition sizes (at the beginning of the install) you should give Linux 50 to 100 Mega-bytes of space extra beyond what Linux itself needs. If you need to do a lot of DOS work, you may want to give DOS 50 Mega-bytes (out of a 200 Mb disk) and give Linux also 150 Mb. You will also need to make a Linux swap partition.

booting on a partition

You should make the Linux partition be the active one (the one that boots up automatically when you power up or reset) unless you will be doing a lot of DOS work. You can easily change the active disk with the fdisk command in both DOS and Linux.

setting up logins

Set up user logins with the adduser command in Linux, after logging in as "root". You can also make logins manually by editing the "/etc/passwd" file, and making new directories. See the Linux Installation Guide for more details.

Several commands included with the Montage system use the C-shell (csh) command syntax. The csh is highly desirable for drawing pictures in a 3-D reconstruction environment because it has history substitution. This feature allows you to run long complicated commands you had previously entered without entirely retyping the line, by simply referring to the previous commands and making simple changes. There are a few features in sh that the csh doesn't have but they are not usually used.

To use the C-shell you should put "/bin/csh" at the end of each user's "/etc/passwd" line. Then the csh will run when users login. You should create ".login" files for each user which tell the c-shell (csh) what to do each time you log in. You should set the "path" inside ".login" with the command:

set path=(. /bin /usr/bin /usr/mont/bin ) 
This allows the Montage system to access its binary programs which are normally stored in "/usr/mont/bin".

You can also make a ".cshrc" file for each user which sub-shells of the login csh run when they first start executing. See "An Introduction to the C-Shell" int the Linux User's Guide for more information.

CLICK HERE to return to Table of Contents

Installing Montage under Linux

The Montage system will completely install itself on a Linux operating system. On other operating system systems such as UNIX or Xenix, changes may be needed in order to allow the Montage programs to display graphics information on the video screen.

To install Montage under Linux you login as "root", insert Montage System Disk 1 (high density), and type:

          cd /usr
          mkdir mont
          cd mont
          tar xvf /dev/fd0 makefile
           (Enter a ^C after makefile is read from floppy.)
          make instalmont
The installation program will tell you when to insert each source disk, and will compile and link the entire system for you. This includes all the Montage programs and the linking of graphics drivers to the Linux kernel.

If you need to make changes to the source code, you may want to manually compile the Montage system. To do this, use the "make" command to make the Montage programs after you add changes with the editor. The source code resides in a directory called /usr/mont which has separate subdirectories for different parts of the Montage system. Each of the inp, sys, and pl subdirectories has a "makefile" which tells the "make" command which source files are needed to create each binary file. See the Linux (1) manual and the Linux User's Guide if you need more information on how to use the "make" command. Make (compile and link) the Montage programs and copy the binaries to the "/usr/bin" directory using the following commands:

su root
make compile
You can also compile any of the programs separately by going to the /usr/mont subdirectory where it resides and using the "make" command for that program only.

CLICK HERE to return to Table of Contents

Installing Montage under other UNIX systems

The first step in transporting Montage to another operating system is to establish that you can read the source code from the floppy disks. The system is normally supplied on 5 1/4" floppy disks in "high-density" format (double-sided, quad density, 15 sectors per track) but can be supplied on double-sided double-density, 9 sectors per track floppies. They can also be supplied in several other formats, if necessary. The source code is copied onto the disks using the standard UNIX utility "tar" (tape archiver). This utility has its own standard directory system (not UNIX or DOS) on the disk which is standard between UNIX systems and there should be no problem with tar reading the Montage disks on other UNIX systems, as long as the floppy disk format is correct.

transporting without UNIX disks

If tar is not available or doesn't work, the source code for Montage can be supplied on standard DOS 5 1/4" floppy disks. Many UNIX systems designed for personal computers have DOS read and write capability, so this provides a second route to transport programs. Although Montage as supplied is not designed to run under DOS, it can be modified fairly easily to do so.

Another method for transporting the Montage source code is to send all the source through a serial port. Use tar(1) to make a file out of all the source directories, then send convert this file to hex-encoded ASCII using the "atoh" program, and send it to the other UNIX system using the cu(1) program. This was the method used to transport the Montage system from a PDP11/34 computer to the IBM-AT compatible.


Once you have recovered the source from the floppy disks, you can try compiling the programs. Normally, before you can run transported programs, you need to do some work on the I/O subroutines for graphics and the digitizing tablet.

If you are using the Summagraphics MM-1201 digitizing tablet on another UNIX system, the change may be as easy as modifying the name of the serial line (normally "/dev/com1" in "mbitp.c") which Montage uses to communicate with the correct tty device. If you are using another digitizing tablet, you will need to make more changes to accomodate it. In this case, you should copy the handler "mbitp.c" to another file name and keep to the original source as much as possible.

On other UNIX systems, it may be necessary to use a different method of graphics output. If a graphics board is used, the best method is to use graphics driver subroutines supplied with the UNIX system (mprint*.c). If the board is so new that no driver subroutines are available, the next best (easiest) approach is to use direct I/O to the graphics board ports or memory space (because nothing else in the system knows about it). If the UNIX system prevents access to the ports (as on Linux sys V rel 2.2 80286 systems) then you must either write a driver and link it with the system (as is done with the Montage system) or use built-in handlers for main memory (e.g. "/dev/mem") and I/O space (e.g "/dev/iomem").

CLICK HERE to return to Table of Contents

Digitizing tablet

The Montage system has been developed with the Summagraphics series of digitizing tablets. These tablets have been sold under the brand name of "bitpad", and this "brand name" is used a lot in this manual; it has become a generic term for us. The driver for the bitpad is fairly simple and it can easily be modified for use with other digitizing tablets. We currently use the Sketchpad MM1201 from Summagraphics which has a resolution of 40 points per mm, more than necessary. We reduce the resolution to 5 points per mm for most work except in the "density" program where the very fine details are digitized.

The minimal requirements for the digitizing tablet and plotter vary depending on how much programming you're willing to do to get the system going. If you prefer, you can use any other digitizing tablet which has a resolution of at least 10 points/mm, can digitize at least 200 points per second, has the ability to digitize a point upon command from the computer, and have a digitizing cursor with a button whose status (up/down) is available to the computer. There are several on the market that fulfill this requirement.

Any comparable digitizing tablet will work with the Montage system, with the appropriate software changes to the driver for the tablet. If you already have another brand of digitizing tablet, or would like to get one, you need to refer to the programming or technical manual for the tablet in order to modify the bitpad handler subroutine for it.

The original bitpads from Summagraphics (c. 1977) were accessed through parallel ports which gave a very high point sample rate. A driver for this type of bitpad is available, although most digitizing tablets (including the Summagraphics Sketchpad) are now accessed through a serial communications line at a speed of 9600 baud, or about 1000 chars per second.

Setting up Summagraphics MM-1201 digitizing tablet

In order to make the bitpad operate with the Montage system, you must have the bitpad jumpers connected properly. Undo the screws underneath the tablet and take the cover off.

The jumpers (in MM-1201) should be set to:

   jumper   status       meaning

     AA   attached       fixed baud rate of 9600 baud
     AB   attached       packed binary format
     AC   removed        parity not enabled
See the manual for the location of these jumpers.

Another change must be made to the connector cable. Pin 8 on the bitpad serial communications cable must be connected to pin 6 and pin 20 (these two are wired together already) or else the the serial adapter in the computer won't communicate. This can be done by taking apart the connector and moving a gold-plated connector from one of the unused pins (there are five of them) to pin 8, and soldering a wire to this pin, then soldering this wire to the wire that connects pins 6 and 20.

Another way to accomplish this is to make or buy a "universal" extension cord for the serial communications line which has a male connector on one end and a female connector on the other. Then you can wire pins 6 to 8 to 20 together and also 4 to 5 together (on each end) so that the bitpad will handshake properly with the computer serial adapter. The pin numbers are different for the 9-pin AT type serial adapter connectors. Good luck!

You should connect the bitpad to com1, the first serial communications line. The pen plotter should be connected to com2. You can change these assignments by modifying the handlers for these devices ("inp/mbitp.c" for the bitpad, and "pl/plotidr.c" for the plotter.

CLICK HERE to return to Table of Contents

Extra serial ports

The Montage system can run very nicely with only 2 serial communication lines. The digitizing tablet connects to one, and the pen plotter connects to the second. To get 2 lines, you can buy a combination board which holds 2 serial lines, or you can buy just one extra line in addition to your standard AT compatible configuration (which normally comes with one). In a pinch, you can make do with one serial line by sharing it between the bitpad and plotter.

If you would like to have more than 2 serial lines, other boards are available which hold 4 or 8 serial lines and will work with standard Linux or XENIX. This makes possible two or three users running simultaneously from remote terminals. The only limitation with this approach is that most terminals don't have hi-resolution graphics capability so you can't run the montage or vid programs. However, this is a good approach for running the plotter. It is very nice to have an extra terminal handy to run the plotter (which takes very little computer time) while someone else is running the montage program or is designing some new pictures.

Serial communication boards which hold 4 or 8 lines are available from several sources, including:

     Digiboard Inc.
     6751 Oxford St.
     St. Louis Park, MN   55426
     (612) 922-8055

     Star Gate Technologies, Inc.
     Suite 109
     33800 Curtis Blvd.
     Eastlake, OH  44094
     (216) 951-5922

C language

The Montage programs are written in the "C" language. This allows easy transportation of the programs to other operating systems, including the various versions of standard UNIX, XENIX, or any system supporting the redirection of standard output and input with a standard "C" compiler and library. For a good introduction to the C language by the people who developed the language, read The C Programming Language, by Kernighan and Ritchie. There are many books on learning C now available in popular bookstores which may appeal to beginners. There is a good C language reference section in the Linux Programmer's manual. A good introduction to using the editors on UNIX is Introducing the UNIX system by McGilton and Morgan.

Most of the Montage programs have been written with liberal use of the "#define" compiler directive to allow macro substitution. Instead of "{" the "begin" statement is used, and "}" has been replaced with "end". These are not standard "C" but serve to make the code easier to read for some beginners or those who have trained in PASCAL. These and several other useful macros are defined in the file "mdef.h" which resides in the "/usr/mont/h" directory. If the usage of these macros is objectionable, it is a simple matter to replace the "begin" with "{" and "end" with "}", using either the "replace" command, the "sed" or "vi" editors, or the "m4" macro processor.

For an excellent list of books and seminars on UNIX and C, you can call or write:

          Uni-Ops Books
          19995 Mt. View Rd.
          Boonville, CA 95415-0650
          (707) 895-2050

CLICK HERE to return to Table of Contents

Program Development under Linux

The montage and picture program modules are located in several directories. The /usr/mont/inp directory has all files needed for montage, and /usr/mont/sys and /usr/mont/pl have all files needed for mpict and vid and hpflt device drivers, respectively. Common header files are in /usr/mont/h.

Makefiles exist in each directory, and these list all dependencies of binary files on object files, and object files on header files. The whole system can be re-compiled in less than an hour on an IBM-PC AT or compatible. You can compile on an AT and copy the binaries for use on an XT under Linux.

Since the programs were originally written in PASCAL under RT-11 on a PDP11/34, and then translated to C and transported to the Z80 CP/M system and UNIX, there is a large assortment of subroutines designed to make I/O independent of the operating system. Most of these subroutines are not needed now that the UNIX C Library is available on many machines and is quite standardized.

To save incremental changes from versions of source code, a simple "Source Code Control System" has been created which keeps the file in its most recent form and saves the differences between it and earlier versions. You say "puts file" and "file" is added to "file.H". To retrieve a file, say "gets -num file" and an earlier version "num" file will be made for you. This greatly simplifies the process of finding bugs which inevitably return long after you first fixed them. In the long run, though, it will be better to use the standard "SCCS" system now widely available on UNIX systems.

CLICK HERE to return to Table of Contents

Montage modules: short descriptions

bitptest.c     tests the bitpad and bitpad handler
dbitp.c        bitpad handler for "density"
dcons.c        keyboard handler for "density"
dens.c         main module for "density"
dstr.c         number to ascii print routines for "density"
dsub.c         misc subroutines for "density"
inout.s        input/output to port subroutines for graphics
iopriv.c       Set priority for I/O to ports for graphics
mbitp.c        bitpad handler 
mcmds.c        misc command subroutines: mag, macros, etc.
mcons.c        keyboard handler
mdebug.c       second (link display, debug) menu commands
mdisp.c        displays the screen: links and current info
mdum.c         dummy handler for movie functions 
mfile.c        file handlers
mfilt.c        filter: eval() and filter()
mfinit.c       symbols for describing link fields for filter 
mgflg.c        get flag defs from file
mgflt.c        get filter spec defs from keyboard
mglob.c        global variable defs
mgsym.c        symbol table handlers: entsym(); getfstr(); etc.
mhelp.c        display help file 
minit.c        misc init funcs
minterp.c      command interpreter
mio.c          text file handlers
mlexan.c       token parser for keybd input (used for filter, etc.)
mlink.c        make different types of links in section buffer
mlnk.c         low level funcs for "mlink"
mnxlnk.c       get next and last link 
mont.c         main module     
movstg.c       set cursor loc on screen (also stage motion for movie)
mpep.c         frame grabber handler (used for movies system only)
mprinte.c      Enhanced Graphics Adapter handler 
mprinth.c      Hercules board handler
mprintm.c      Linux standard display driver (mono,ega)
mprintt.c      Tektronix 4014 (like) handler (our Z80 emulates Tek)
mpsub.c        misc subroutines
msecio.c       section read and write subroutines
msetup.c       setup rotation matrix subroutines
mstg.c         low level stage subroutines
msub.c         misc subroutines
msubo.c        old version of misc subs.
mtransf.c      rotate and translate points using rotation matrix
mupdat.c       write sections to disk (simple virt. memory scheme)
mvid.c         device-independent driver for graphics 
mvido.c        old mvid
mvidsub.c      subroutines for graphics driver
mzero.c        init routines for sections, links.
putsym.c       print text on graphics screen using vector font 
scrtest.c      test driver for graphics screen
vect.c         generates vectors on graphics screen (Bresenham's alg.)

Mpict modules: short descriptions

fbufio.c       section buffer read and write for "fstor"
fsec.c         command subroutines for "fstor"
fstor.c        main module for "fstor"
ftran.c        translate command for "fstor" links from old to new fmt
garea.c        command subroutines for "glink"
glink.c        main module for "glink"
hdot.c         draw dot for hercules board (now inside mprinth.c)
hfile.c        file handler for "hide9-11"
hide.c         main module for "hide9-11"
hidsub.c       hidden line subroutines for "hide9-11"
hvirt.c        virtual memory for "hide9-11"
mcons.c        keyboard handler
mdraw.c        draw flag symbols on picture
mdum2.c        dummy routines
mfile.c        file handler: open, close, read, write
mfilt.c        filter routines: eval() and filter()
mfinit.c       symbols for describing link fields for filter
mflag.c        subroutines to print flags on picture: calls mdraw
mgetu.c        comnd parser for mpict: state mach interpr. graph lang.
mgflg.c        get flag defs from file for "fstor", "glink"
mgflgx.c       get flag defs from file for "mpict"
mgflt.c        get filter spec defs from keyboard
mgfltx.c       get filter spec defs from keyboard for "mpict"
mglob.c        global variables for "fstor" and "glink"
mglobx.c       global variables for "mpict"
mgsym.c        symbol table: entsym(); getfstr(); getfval(); etc.
mhelp.c        display help file
mio.c          text file handlers (designed for old z80 CP/M system)
mlexan.c       token parser for keybd input: strings, constants, punct.
mlexanx.c      token parser for getting strings
mlink.c        make different types of links in section buffer
mlnk.c         low level funcs for "mlink" 
mlnkn.c        low level funcs for "mlink", no stage movement
mnull.c        null handler  
mnxlnk.c       get next and last link
mpict.c        main module
mpinit.c       symbol defs 
mprintms.c     secondary monochrome board handler
mrinit.c       symbol defs
msecio.c       section read and write subroutines
msend.c        write picture params to .cor file 
msetup.c       setup rotation matrix subroutines
msub.c         misc subroutines
mtransf.c      rotate and translate points using rotation matrix
mupdatx.c      dummy "mupdat" 
mvid.c         device-independent driver for graphics 
mzero.c        zero section buffers, links
plsub.c        plotter subs
putsym.c       print text on graphics screen using vector font
scrtest.c      test graphics screen driver

plot modules: short descriptions

Plotdb.c       Ampex plot package debugger
Tek.c          Tektronix handler for Ampex plot package
ega.c          Enhanced Graphics Adapter driver
exp.c          draws test graph: exponential * sine
graph.c        Ampex graph generator
graphl.c       modified graph generator 
graphx.c       modified graph generator
herc.c         Hercules driver
hp.c           Hewlett-Packard plotter driver
hpflt.c        HP-7221A plotter filter for Ampex plot package. 
hplot.c        HP-7221A plotter driver
inout.s        input/output to port subroutines for graphics
iopriv.c       Set priority for I/O to ports for graphics
label.c        label generator subroutines 
labels.c       label generator main module: used by "mpict"
mprinte.c      Enhanced Graphics Adapter driver
mprinth.c      Hercules board driver
mprintm.c      Linux standard display driver (mono,ega)
mprintt.c      Tektronix 4014 driver
mvid.c         device-independent driver for graphics 
pdigit.c       digitize points on plotter (use plotter as digitizer)
plabel.c       subroutines for plotter
plotdr.c       driver subroutines for "hplot"
plotsub.c      subroutines for "hpflt"
plsub.c        driver subroutines
pltest.c       plotter test routine
posit.c        main module for "posit" (position pictures on screen)
putsym.c       print text on graphics screen using vector font
scrtest.c      test graphics screen
symcomp.c      compile vectors symbols into random-access table
term.c         terminal graphics handler (uses char resolution)
vect.c         generates vectors on graphics scrn (Bresenham's Alg.)
vid.c          main module for "vid" (uses Ampex plot package)
wscreen.c      secondary monochrome screen handler

useful commands: short descriptions: C-shell files

8by11          like drawpic but smaller picture
ccstr          C-shell file file to strip multiple files 
ccstrip.c      source for stripper
cradd.c        source for command to add 's for DOS
diskcopy.c     source for floppy copy command
dopic9         make hidden picture
draw9          make hidden picture
drawpic        draw pictures on plotter
drawpix        like drawpic but no pensort
makehid10      make ".h" files from ".cor" files
makepic        shell file to make pictures automatically
overwrite      copy a file onto another; used by "replace"
picthide       like "picture" but draws hidden line onto screen
picture        interactive picture-drawing program
replace        selectively replace one char string with another
sget           incremental source code retriever
sput           simple incremental backup programs for source code 
tblue          change EGA terminal to blue
tbold          change terminal to boldface
tcyan          change terminal to cyan
tgreen         change terminal to green 
tmag           change terminal to magenta
tred           change terminal to red
treset         change terminal back to white-on-black
tty1off        turn off login at com1
tty1on         turn on  login at com1
tty2off        turn off login at com2
tty2on         turn on  login at com2
wsadd.c        source for file to add phantom 's for WS
wx             shell file to make text file into one line per word

CLICK HERE to return to Table of Contents

Montage data structures: sections

The data structures for the montage data files are kept as simple as possible, allowing for possible changes in the future. Each file is a sequence of constant length buffers, called "sections". Each section is defined by the C structure "sectblock". A sectblock is defined as:
typedef int sectdata [DATASIZE]

typedef struct
     int len;       /* length of block */
     int typ;       /* version number */
     int section;   /* section number */
     int tmpw;      /* not currently used */
     int free;      /* the free data pointer */
     int seq;       /* the max sequence number */
     sectdata data; /* the data array for a section */
There are six words at the beginning of each section which define that section, followed by an integer array "sectdata" which contains links. The size of sectdata can vary, according to the size of file wanted, but each section within a file always has the same size sectdata arrays. The "typ" field is currently set to 5000 arbitrarily; the "free" field is the index into "sectdata" for the first free space. The "seq" field gets incremented whenever a link is created in the section, but no change is made when links are erased.

Although a more sophisticated file structure, for instance a b-tree or variable length section indexed file with a header describing the data might seem advantageous, it was found through experience that the simpler structure presently used has several advantages. It is easy to cut files apart if they are too long for backup, etc. It is easy to paste them back together when new data must be added to a file at a later time, or to recover a backed-up cut-apart file. It is much easier to patch a file blown to pieces by a malfunctioning disk if the file consists of constant length sections. The (usually) unique version number which is part of the structure of each section helps with the debugging process because section numbers are adjacent to the version number, which makes it easy to find any section by number with "od(1)" or "adb(1)". Finally, the "fstor" program can easily compress and restore data files because the structure of each section stays the same during the compression process; only the extra space in a section is removed during a compression.


Within each section, there are a variable number of variable length "links". Each link carries information about one point or "slice". The "link" definition is:
typedef struct
          int len,typ;
          int section;
          int area,branch;
          int xbio,ybio;
          int linknum;
          int cellnum;
          int color;
          int pts;
        } link;
The line link (struct { } link2) has four extra fields:
          int nxnum,nxsec;    pointer to next line link
          int lanum,lasec;    pointer to last line link 
          int len2;           the ending length pointer  
The "len" and "typ" and "section" fields are the same as in "sectblock" defined above. The original compiler used the names of structure fields for any structure; thus each use of a field name had to define the same offset. For instance if you defined "sect" once as offset 3, and once defined as offset 4, you'd get an error. The newer compilers don't have this problem.

The "len" field gives the length of the link, as in "sectblock", above. Links can be variable length, depending on what type they are. Their type is defined by the "typ" field. See the file "mlink.c" for definitions of the types. The "frame", "section", "area", "branch" give information about where the link is. The "stage" fields give the absolute stage positions of the link for the movie stage. The "bio" fields give the bio coordinate position of the link.

The "linknum", "lanum", "lasec", "nxnum" and "nxsec" fields contain information for line links. Each link is given a sequence number unique to its section. To find the next link in the process vector, find the section given by "nxsec", and then find the link whose "linknum" field contains the sequence number given by "nxnum". The "lanum" and "lasec" fields similarly define the previous link in the line vector. Originally, this system of defining a line vector was used for all links, but it was too difficult for users of the system to learn how to use, so I left it only for line links.

The "cellnum" and "color" fields contain user- defined information about the data in the picture being traced. The "color" field is only used by color systems such as the EGA and is used by the color plotter by default if no color has otherwise been set for displaying points. The colors used by the EGA driver are the same numbers as those in the IBM documentation; that is, 1=blue, 2=green, 4=red, etc.

The last field in each link is always a duplicate of the "len" field, so that the filter can go from link to link either forwards or backwards. This means that the "pts" field in a base link contains the duplicate of "len", but in flag or trace links, which are variable length, there is always an extra field stuck on the end. For the line link, the "len2" field serves the same purpose.

trace links

In trace links, the "pts" field value describes the number of points in the link. The first point is a delta value from the xbio, ybio fields. The rest of the points are delta values from the previous point. Points are variable length and are compressed into a single word, if the delta values are less than 125 (see routines "makpt()" and "gpval()" in file "mlnk.c"). If the delta values are larger, then either two or three words are used. This data-compression technique obviously works only if much of the data points are closer than 125 to each other. Better data-compression techniques are available, and you may want to add one to Montage if you anticipate severe problems with data file size.

At one point during the development of Montage, the digitizing tablet calibration was 200 points per inch. Newer digitizing tablet had a calibration in terms of 40 points per mm and we felt that metric calibration would be better. All the old data files were translated to a new link format and the data points scaled to a new calibration. This caused a problem when the data was plotted because roundoff errors during the scaling process caused random errors in the x,y delta point values (which are integer values), and this caused trace links not to be closed (the last point and the first point didn't coincide). We decided to leave the data in the old calibration, and re-scale it (using floating point) only during the plotting phase. If you want to re-scale data points, remember this problem.

CLICK HERE to return to Table of Contents

section buffers

There are three section buffers which normally contain the current, next, and last sections. This allows the user to go to the next and last sections quickly so they may be displayed without delay. There is a simple "get buffer" and "release buffer" mechanism implemented in the file "mupdat.c". This algorithm keeps the current section in the third buffer, when the user goes to the next section. This saves time if the user then goes back, because the third buffer contains the previous section, which does not need to get written back to disk unless the user goes forward by two sections. Currently the algorithm is not used for look-ahead because hard disk drives make the system fast enough without look-ahead.

The "getbuf" routine uses four arrays, each describing the three section buffers. The "secbuf" array contains the section numbers, the "secpri" array contains the priority, the "secpnt" array contains the address of the section buffer, and the "secwrt" array contains the write flag, which tells whether each buffer has been written into and therefore must be written back to disk.

section display

The dispvid subroutine is a rather complex routine optimized for displaying the picture on the screen quickly where there is a fast screen erase command in the driver. The montage program erases and then redisplays the entire screen each time the digitizing cursor button is let up. Originally, the screen had to be entirely redisplayed because in the "movie mode" the mouse was used to move the entire screen display in the X and Y directions to follow the video picture from the movie stage.

When the user is only tracing from acetate sheets onto the bitpad using the "cursor" mode, the entire screen doesn't need to move; the cursor moves instead. The algorithm used here should eventually be modified to allow selective object erasure and display, instead of erasing the entire screen. This would minimize screen display times when only a few points are displayed. Try adding an "erase" flag and a "selective-display" flag for the display routine. When the selective flag is on, the display routine would only add (or subtract) the current link. When the "erase" flag is on, the display routine would erase the entire screen instead.

There are two types of screen display. When something in the display has been modified since the last display, the entire screen display is regenerated. However, when no links have been modified, the screen is quickly redisplayed with an offset, saving the time for multiplying all the points by a mag.

When the "newpts" flag is set, the display routine uses the display filter to select which links to display. Each type of link has a different appearance on the screen. As each link is selected for display, its location is calculated by adding an offset, then scaled according to the mag, and an entry is made in the "lits" (literals) array. This array contains X,Y pairs for all points, a flag telling whether they should be displayed as vectors, and all character strings for the link displays. When all the links have been entered into the lits array this way, the lits array is displayed with the current bio coordinates defining the offset for the center of the screen.

When the "newpts" flag is not set, the screen is simply erased and redisplayed from the "lits" array. The purpose of the lits array is to make this type of redisplay fast. This is possible because no multiplications or divisions need to be done to redisplay the lits array; it only needs a X,Y value added to the location of each point to define where the screen has been moved by the digitizing tablet cursor.

CLICK HERE to return to Table of Contents

symbol table

There is a general purpose symbol table, along with a set of subroutines for using it, which makes user parameter entry much easier (see "mgsym.c"). The keyboard parsing routine is very forgiving and allows extra spaces and syntax variations. This compiler is a state machine which accepts user input, and compares tokens (see the file "mgsym.c") to the symbol table to give each token a category. There are a set of tokens put into the symbol table at program initialization which define the filter fields and a few other useful things. A symbol table entry is defined in "mgsym.c" by:
typedef struct
     char slen,styp;
     int sval;
     TEXT *strp;
The "slen" field defines the length of the table entry. "styp" defines the symbol category, either "LSYM", "DSYM" or "USYM". See the state machine in the filter compiler (mgflt.c) for usage of these categories. The "sval" field contains the numerical value associated with the symbol. The "strp" field contains the pointer to the symbol's text string. The text string may be anywhere in memory, or can be placed in the symbol table immediately following the "strp" field. In the latter case, the "slen" field is incremented by the length of the text string.

CLICK HERE to return to Table of Contents


The filter compiler in "mgflt.c" puts a sequence of integer codes into a filter spec. These codes are a simplified translation of the filter spec syntax, described in "mgflt.c". The filter compiler is a rather complex state machine and should be changed to use "yacc" to simplify the syntax specifications. This would allow a more "C"-like syntax for filter definitions. One known bug in the compiler is that although link fields may be offset with positive or negative variables (e.g. sec=cur -2), there must be a space before the "-" sign, and no space after it.

Each filter function calls the filter with a parameter set to the address of a filter spec, and the filter compares links with the parameters defined by the filter spec. The filter subroutine "filter()" calls the routine "eval()" to evaluate one level of a filter spec inside parentheses. The filter is optimized to use register variables as much as possible, but must use stack variables to some extent because "eval()" is a recursive subroutine.

An extra feature was added recently to the filter to allow "surgery" on filtered objects. This feature of the filter selects links which are above or below the plane defined by the equation

     a(x-x0) + b(y-y0) + c(z-z0) = 0
where x0,y0,z0 is a point the plane passes through and a,b,c relate to the slope of the plane in the x,y,z axes, respectively. Although the a,b,c parameters are difficult to set right, this feature is useable, and it runs fairly fast. It would be better to transform three genuine angles of rotation into plane equation coefficients which could be stored instead of the a,b,c parameters. This can be done easily enough (in "mgflt.c") when necessary. For c = -1, the following equation holds:
   z - z0 = tan(yrot)(x-x0) + tan(xrot)(y-y0)
   a = tan(yrot)
   b = tan(xrot)
   c = -1
This sometimes simplifies finding the proper coefficients. By setting either a or b to -1, other variations are possible.

CLICK HERE to return to Table of Contents

Montage program

The montage program is designed to be easy to use for beginners, because beginners usually end up with the job of entering data. It is not well- optimized for screen display speed because typically data entry is done by rote on a digitizing tablet and screen display doesn't affect entry much. Several functions have been asked for by users of the system, such as automatic copying of data from one section to the next in case of a missing section, trace link rotation to allow aligning of data entered with a rotational misalignment, continuous data point entry to save fingers during data entry, etc. These features are all relatively easy to add and have not been because it has been easy to work without them.

We believe that it is better to have the user enter points one at a time rather than to digitize points continuously because this gives control over the sometimes quite subjective process of data entry. Although on other systems "data thinning" algorithms are employed to filter continuous points on the basis of curvature, we like to give this control to the user.

Montage is a very simple program. It waits for either keyboard or digitizer input and does the appropriate action, then redisplays the screen if necessary. Some features, like the filter and display subroutine are very complicated, but these are fairly well debugged and have run well for seven years on Z80's, 11/34's and IBM AT compatibles.

Montage history

Montage originally was much more complicated because it controlled a movie stage and video system and kept track of multiple adjacent areas automatically. Consider the reference frames (x,y coordinates) necessary to keep track of all this:
     digitizer   keeps track of where digitizer cursor is 
     screen      defines where center of screen is 
     cursor      defines where cursor is on screen 
     section     reconstructed world coordinates  
     stage       physical location of film on video camera
     align       how far section has moved when aligning. 
     cur link    where the current link is 
The montage data entry program would keep track of each of these coordinate systems and move the stage to the correct location defined by the user's digitizer input, referenced to the biological coordinates, displayed in screen coordinates, and translated to the stage coordinates. Each frame in the movie film had a different correspondence between the frame coordinates and the section coordinates; furthermore, frame numbers (physical section number) could be different or in fact completely out of sequence from section numbers (logical section numbers).

The montage micro-alignment algorithm allowed alignments within sections, using the nearest base link vvin a section to define a local reference point ("link" between two coordinate systems) for a small region of the section. This was called the "relative" mode because the alignments were relative to a local reference. The alignments anywhere in a section could be continually improved by adding new base links wherever the more distant links gave misalignments because of tissue distortion.

The original montage allowed a system of base links to define an area so that each area in a section could have a different frame number and stage coordinates than its adjacent neighbors. Whenever the user moved the cursor out of an area, the algorithm would find the nearest base link and would use its correspondence between section coordinates and stage coordinates to define where the stage should move (frame number, x and y coordinates) to display the video image of the new area.

Embedded in this algorithm was the method of creating the proper alignment between sections and between adjacent areas in a section. In order to make alignments, the previous section was saved in the frame grabber (PEP device) and the video image of the present section was displayed either flashed transiently or mixed with the current section. The user controlled the location of the stage (translation and rotation) by moving the digitizing tablet cursor and this movement was "remembered" as the new section's stage coordinates (section coords stay the same during alignment).

In order to create montages from several areas, the user had to align areas within each section. This was accomplished in the same manner as alignment between sections except that before the stage was moved to align, the frame was advanced to the new area so that the alignment could be made to the correct frame image. It was found best to align all the sections in one of the areas first and later align all the areas in each section to the previously aligned first area. There were always problems with misalignment between areas because of distortion of the biological material. Whenever part of a frame (photograph) of an area was not good, this algorithm made it very easy to simply make another overlapping photograph, give it a new area number, define it with base links around its edge, and align it with the frame.

Most of this code for the control of the movie system and automatic montaging is still included in the source files, except where its inclusion would cause serious problems. The "xstage", "ystage" and "rstage" fields in the link structure have been omitted to save space in data files.

Montage needs to be able to check the keyboard without waiting so that it can check to see if a point has arrived from the bitpad. This can be difficult in some UNIX systems, but is relatively easy under Linux sys V (see "inp/mcons.c"). However, this means that interrupt processing ("^C" normally stops programs) cannot be in place during the time Montage is running. Unless you really have to, don't change this code because it is difficult to debug (causes the terminal to lock, etc.).

A useful feature not included in the current system is the ability to merge two data files with a translational offset. This is needed whenever data entered as separate data files is to be displayed (usually as an afterthought) with correct alignment between objects. This feature was included in the first set of reconstruction programs written by Neil Friedman but it is not usually needed because data can be entered all into one file (not several) to preserve the accuracy of alignment between objects in the file.

Usually by the time two separate files have been created it is no simple matter to get all of the traces from each correctly aligned the way it was on the original section. This is because if 3-D objects are reconstructed separately, there is no guarantee that their reconstructed coordinate systems will correspond with each other through a long series of sections. There will inevitably be local distortions which add up through a series and cause alignment problems between objects. See Stevens et al., 1980, Brain Res. Rev., 2:265 for another description of the problems involved.

Another feature which might be added to the montage program is the ability to translationally and rotationally align the data from two successive sections after it has been entered. This would be reasonably simple because only two commands would be needed: a translation command to move an entire section's data, and the corresponding rotation command. We haven't needed this because all our alignments are done using acetate sheets (or on the movie stage on the old system).

If the section size is not large enough to hold all objects, the section size can be increased by a re- compiling with a larger maximum section size. Another trick is to cut and paste files with fstor to keep file size small for floppy backup.

We are currently planning to add automatic data entry from acetate sheets to the Montge system, using a video camera and frame grabber board. This will allow traces on an acetate sheet to be entered by laying the sheet down on a light table and taking a snapshot with the video camera and frame grabber board. This should considerably speed the process of data entry, and will leave only the process of object recognition and tracing onto the acetate sheets to be done manually.

Although automatic systems for digitizing and recognizing objects in a gray-scale image are currently available, they are still in early stages of development. They require expensive hardware to hold the data for just a few gray-scale images. Consider the problem of storing the data from a good-quality electron micrograph image which has 8 bits of gray- scale and a resolution on the order of 10,000 x 10,000. Each image would require 100 Mega-bytes of storage! The algorithms necessary to sort through a series of micrographs simply haven't been invented yet! We are believe that the problem of 3D serial reconstruction would be an ideal test case for the first artificial vision system able to cope with the tremendous resolution required.

CLICK HERE to return to Table of Contents

Mpict program

Mpict also uses a very simple algorithm: get parameters, display the picture, and repeat, saving or loading the parameters if necessary. The picture is displayed through the use of an intermediate graphics language, the Ampex package, which allows Mpict to draw a picture on many devices identically. The advantage of this is that the device drivers are kept separate from the picture-drawing process and this keeps the system small and easily modified. There is a slight hesitation as the picture information is "piped" through a buffer from one program to another, but this is not usually objectionable.

Mpict uses a somewhat complicated state machine in ("mgetu.c") to analyze syntax while processing parameter definitions given by the user, but the state machine is reliable and is easy to change. The state machine should be simplified, using "yacc" to create the state machine by defining the syntax for mpict user input. This would have the added advantage that a full "C" language syntax could be included in the parameter input language (see Chap. 8 in The UNIX Programming Environment by Kernighan and Pike for complete source code to a "C" interpreter).

The matrix math was borrowed from the previous FORTRAN version written by Neil Friedman, which was borrowed from elsewhere, which was ... etc. It is probably not as efficient in running or with variables as it could be, but it is robust and does not give trouble.

The algorithm for finding the center of the cell for automatic centering on the screen looks difficult, but is really very simple. The algorithm is needed because there is no way in advance to tell where to place the picture because each new rotation gives a different two-dimensional projection of the 3D data. By finding the min and max of the x,y data on the screen, an inverse matrix rotation to the original coordinates gives the center of the cell in the original data coordinates. If the user gives no x or y axis rotation, the z coordinate for the center will not be accurate, but that is OK because it is not needed for a face-on view.

One version of Mpict was written for a system which had both a monochrome monitor and a color monitor with an EGA card. This allowed display of pictures while giving easy screen access for scrolling text. A driver was written for this "secondary monochrome" display and is included in the mpict source code, but is not currently used. The EGA driver should be improved to allow text and graphics simultaneously. A newer version of Linux may have a better driver.

CLICK HERE to return to Table of Contents

Ampex package

The Ampex graphics library is included free with the Montage source code. It includes a set of "C"-callable subroutines which makes heavy use of the UNIX "pipe" feature. The Ampex package is very powerful because it has a vector-type character generator and has hierarchical subpicture organization. It is fast because sequential rotations are included in one rotation matrix. Data does not get rotated more than once, even if it is within a subpicture which is rotated with respect to another rotated subpicture (only the matrix needs to be rotated several times, not the data).

The Ampex package sends its output to the standard output, where it can be piped to any other filter, graphics driver, or file. The device- independent graphics language is very simple; just a command byte and one or more data bytes. The x,y data is defined in absolute coordinates from the root frame and the resolution is 16384 which is more than enough for most graphics drivers. It is very easy to make a new device driver filter by taking one of the Ampex drivers, vid, tek, hpflt, or ibmflt and modifying it by adding the correct move, draw, pen up, pen down and pen grab commands.

A few commands have been added to the original language such as set pen color for the plotter and turn on and off the hidden line routine. The hide commands allow the hide routine to receive both hidden and unhidden data at its standard input, giving the algorithm a way of differentiating between them so it can send the unhidden data unchanged to its standard output.

The Montage System relies heavily on the Ampex language for communication between the "mpict", "hide", "vid" and "ibmflt" commands through pipes. This feature allows the Montage programs to be modular, and gives great flexibility. A picture may be computed and its Ampex language image saved (e.g. in a ".plt" file) for later use. Although the standard Linux plot language is nearly the same for the purposes of this system, the Ampex package was chosen because its source code was available.

The Ampex manual is included in case you want to write applications which use it.

CLICK HERE to return to Table of Contents

Hidden line routine

The hidden line routines Hide9-11 are very simple to understand, but difficult to decipher. Data comes coded in the Ampex language through the standard input and points are drawn in Ampex language on the standard output. Each point except the first in a polygon defines a line segment. The line segment is drawn if it is in front of the previously hidden area in the picture. To calculate what part of the line segment is hidden, the algorithm converts the line to adjacent pixels in a "staircase" pattern, and draws a partial vector line segment to the standard output whenever the previous point was not hidden and the present point is.

To calculate what part of the picture is hidden, each set of line segments which define a contour are converted to a filled polygon by sorting the points on the x axis and drawing space-filling lines between them. The space-filling lines are one pixel wide and are written to the hidden line table. In a previous version, the points were saved in the form of line- segment quadruplets, thus saving space, but in the present version, the space-filling lines are saved as a one bit-plane graphics memory, accessed by read and write routines in terms of (x,y) coordinates. This allows a 512 resolution hidden-line table to fit inside 32K bytes. The 2048 resolution hidden-line table requires 512K bytes, and is currently implemented using a "virtual-memory" least-recently-used disk algorithm. A few blocks of the file are kept in memory, and when a new part of the hidden-line table is needed, the block which has least recently been used is written to disk if it has been modified, and is then free to be read with the new block from disk. It is hoped that after the price of memory goes down a little further and larger data-space compilers become available that the hidden-line table may be kept completely in memory, and it is conceivable that within a few years the entire hidden-line algorithm will be accomplished automatically on a graphics card.

There are a few bugs in the hidden-line routine as it stands. One has to do with not properly detecting a space-filling line which is on the end of a contour so that it touches the contour with an odd number of points. This case is discarded and causes a one-pixel- wide glitch on the end of some contours. This has never been noticeable to us in several years of hard use of the system. But it does cause one minor problem; the Hide program simply can't deal with vertically oriented lines generated from end-on sections. When a series of sections through a cell is rotated 90 degrees in the y axis, this makes vertical lines which sometimes are not displayed because they are only one pixel wide and may have odd numbers of points in them. The solution to this problem is simple: don't try to run the Hide program on vertical end-on sections; horizontal lines are no problem, so if you have to, rotate around the x axis, or don't hide at all. The bug may not be difficult to fix, but it has not been a serious problem.

The other bug in Hide is that when two lines cross at a very slight angle (1 degree or so) the algorithm sometimes causes the rear line to be broken up into line segments one pixel long for a few successive pixels near the intersection point. This is caused by the algorithm converting both lines into pixels before the hidden table calculation. A partial fix was to add some hysteresis to the hidden-line intersection calculation, but the bug is still there.

The Hide algorithm is only designed for closed contours, and it will try to close (make last be equal to first) any sequence of points given to it. This causes problems in cases like alphanumeric characters where you don't want to have a sequence of points interpreted as a closed polygon. A useful addition to the Ampex graphics language would be to have two types of point lists, one closed and one open. The hidden- line algorithm could easily take care of the open case; it just hasn't been added yet.

CLICK HERE to return to Table of Contents

Device handlers

The device handlers interpret the Ampex graphics language and draw the picture on the appropriate device. They are all based on the tek driver which came with the package, and are intended to look completely interchangeable to any program generating graphics. The Vid program has the complexity that it must generate a staircase pattern for vectors defined as a list of adjacent points, and must send this list of points to the proper graphics board.

There are several graphics devices supported: the monochrome board, the Hercules board, the EGA (Enhanced Graphics Adapter), and the Tektronix 4014. Vid (and also Montage) uses a set of dummy device- independent subroutines to keep the main routines small and simple. The dummy subroutines are loaded at run- time with addresses to the proper subroutines for the device being used, allowing one Vid program to run without recompilation on several devices. The Hercules card is the fastest, because its pixel addressing is much simpler than the EGA.

In Linux Sys V rel 2.3, the EGA card can be accessed in two ways: 1) through the standard Linux driver (Monochrome, Color, Enhanced) using the "-b" switch option in "vid" and "montage", and 2) the Montage driver using the "-e" option. The standard Linux driver "-b" is substantially slower, especially for the screen erase function. Therefore the "montage" program writes text generated in the standard driver by a character matrix when in this mode. You must set the GTERM environment variable using the command "setenv GTERM epc" for the Linux driver to correctly access the EGA display. You should put this line in your ".login" (csh) file so that it will run automatically each time you log in. See plot(1G) in the Linux User Ref. Manual for more details on the Linux standard driver. The Montage "-e" driver generates text in a vector- driven font algorithm. To use the Montage EGA driver, the EGA card must have 256KB memory installed, although the Linux "-b" driver works with 128KB.

The Montage graphics drivers are written to be flexible and easy to change for future graphics cards. There are two basic modes: "OVERLAY" and "GRAPHICS" (see "mvid.c"). The OVERLAY mode writes text from the standard char matrix font onto the graphics screen. The GRAPHICS mode writes text onto the graphics screen using a vector-type font, and therefore does not require both text and graphics on the display at the same time. The Hercules card requires the use of the GRAPHICS mode, but the EGA card can be used with either mode.

The Hpflt and Ibmflt programs use a "trick" to sort their output by pen color. Hpflt initializes eight files, one for each pen, and whenever a pen change command is received, hpflt switches its output to go into a file corresponding to that pen. After all the input is read, the eight files are closed and reopened and read from sequentially. Otherwise, hpflt is very much like Vid.

CLICK HERE to return to Table of Contents



The original point editor program called "FIX" (written by Neil Friedman for John Stevens in FORTRAN) was elegant because it took a compressed data file as input and created a compressed data file as output, but used an expanded constant section-length file for its inner workings. During each picture editing session, it would take several minutes to expand the file at the beginning and compress it at the end of the session. The user would often grow tired of waiting. The fstor program grew out of the perception that it would be more time-efficient to give to the user the discretion of when to compress data files. Often several data files are kept in expanded form which wouldn't have been possible with the old system.


The fstor program has been changed recently to allow various kinds of operations having to do with data file management and storage. One of the early problems was that trace links were sometimes entered counter-clockwise which gives negative area when automatically analyzed later using the glink program. So one subroutine ("verify") was added to fstor to make all links clockwise. This subroutine checks the area subtended by a list of points in a link; if the area is positive, then the points define a "clockwise" profile. The verify mode sometimes changes the amount of space used to store a list of points, so only a ".dat" file (which normally has extra space in it) may be verified.

Later, it became useful to add a filter to allow part of a file to be copied selectively using the filter, so this was added to all the fstor subroutines. The copy, store and retrieve functions can work on either ".sto" or ".dat" files. In order to change the section size of a ".dat" file, you should store it first.

In order to use the fstor program more intelligently, shell command files called "pak" and "unpak" to various nice things to save typing when doing a lot of data file manipulation.

The "pack(1)" and "unpack(1)" commands are useful for archival storage because they use a special bit- encoding technique to encode bytes, the most common bytes getting the smallest bit code. See the Linux manual for their use.

CLICK HERE to return to Table of Contents

Debugging Policy

In any sofware system of at least moderate complexity, there are usually small errors or corrections to be made to the system before it can be adapted to a new environment. This is especially true of the Montage system because by its very nature, serial reconstruction is an individualized endeavour. Each laboratory which uses Montage will probably need a slightly different set of software features. We assume that if you purchase the source code for the Montage system, you will be able to make changes and correct most minor problems in the code yourself.

If you have found a program error or would like us to make a change which would expand Montage's capabilities, please let us know and we will do our best to help. We are always interested in correcting programming errors in the Montage system and we will do our best to fix bugs that are brought to our attention. But as with any other complex system we do not guarantee the Montage system to be free of errors and we cannot guarantee that we will be able (or willing) to fix every error that occurs during the use of the programs. If you have the source code for the system, we will do our best to give you updates with new modifications. If you make changes to your system to improve it, we would appreciate a copy of your source along with a short explanation, so we can distribute the improvement to others. We make no guarantee that the Montage system will be useful for any purpose other than that for which it was developed in this laboratory.

When you buy a copy of the Montage source code from us, you agree not to let other persons or laboratories use your copy without their paying us for a license. It will obviously be difficult to enforce this arrangement strictly; however, we will only give assistance to those who have paid for the system.