If you feel
inclined to take a deeper look into the CaGe, or possibly extend it, this
page is for you.
The production process:
Generators and Embedders
CaGe is a
"control center" for a collection of programs that do the actual
work. These external programs are our generators and embedders.
communicates with these programs using pipes -- the input/output mechanism
best known from the UNIX world. The external programs aren't actually
"aware" that they are working in the CaGe, they only read and
write data using the three standard i/o streams known as standard input,
standard output and standard error. CaGe sets these streams up and reads
from or writes into them.
can be any program that produces graphs on standard output, in any of
the formats understood by CaGe. From a technical point of view, a generator
is nothing more than such a graphs-producing program controlled via its
command line, possibly supported by a Java class to define its own options
window within CaGe. If you would like to use a generator program without
writing Java code for the options window, you can do so via the external
generator button in CaGe's first window,
providing a command line with all option parameters there.
Embedder takes one graph and computes (2D or 3D) coordinates for
its vertices. Like the generators, it must use the graph formats known
to CaGe, and it must output the graph's vertices in the same order as
they were supplied in the input. CaGe needs some additional information
about an embedder: it must have methods to manipulate the embedder command
line to make the embedder spend more time trying to achieve a good embedding,
and to start a 2D re-embedding with a new exterior face.
After a generator
has been selected and output options chosen, CaGe starts the generation
program and reads graphs from it. Graphs selected for output are passed
on to the appropriate embedder. (If both 2D and 3D output was chosen,
embedder processes are run separately for the two dimensions.)
Adding a Generator
If you want
to use a new generator with its own options window, you need to provide
CaGe with a Java class extending cage.GeneratorPanel,
a subclass of javax.swing.JPanel.
CaGe will instantiate an object of this class, add it to a window, call
the method showing
to allow some extra preparation and then show the window. After the user
has clicked "Next" on another panel in the same window, getGeneratorInfo
is called which must return an object of type cage.GeneratorInfo,
containing several items of information such as the command line that
you would otherwise enter in the "external generator" options
You need to add entries to the configuration file CaGe.ini
to make CaGe offer the new generator to the user. The existing entries
will provide you with a template. To access other entries from the configuration
file, you can use the static getConfigProperty
method of the cage.CaGe class.
little flexibility as yet with respect to the format a generator is expected
to produce, even if a GeneratorPanel is provided. All generators are currently
required to output one of CaGe's two input formats described below.
Adding an Embedder
Adding your own embedder to CaGe is a fairly uncommon use-case in our eyes.
If however you do feel the need to use a specific embedder that is not part of
CaGe, then this guide might provide you with the necessary
information and tips.
currently two graph formats that CaGe can read, so generators and embedders
must use one of these for their output. CaGe will try to recognize which
of these formats it is reading.
formats have an optional header identifying the format in an unambiguous
way. If there is no header in an input that CaGe is reading, the program
will guess from the first byte, but false guesses are possible. A header
consists of the format name enclosed in double angle brackets >>...<<.
These brackets can also contain a comment, separated from the format name
by white space. The header can be on its own line (i.e. followed by a
line separator) if the format is line-oriented (which currently applies
to the writegraph format, described next).
The Writegraph format (input/output)
Format names used in headers: writegraph, writegraph2d, writegraph3d
originated from Combinatorica, a Mathematica package. It is a plain-text
format and easily readable for humans. There is one line for each vertex,
and this line contains, separated by white space, the vertex
number (sequentially numbered, starting with one) vertex coordinates,
the numbers of all vertices adjacent to the current one. Since
we deal with lists of graphs, we define a line containing just the number
zero as the separator between two graphs (as zero is not a valid vertex
an embedded graph (with coordinates for the vertices), writegraph is the
format of choice. It then contains either the 2D or 3D embedding, and
the format name in the header is expected to communicate this fact. For
a non-embedded graph, it is possible to include no coordinates (and use
"writegraph" without a dimension in the header), but there is
also the convention of including zero coordinates (and the format name
should then specify the number of zero coordinates used for each vertex
as "2d" or "3d"). One comment sometimes given in the
header after the format name is "planar", signifying that the
order in which vertices are listed can be used to construct a planar embedding
of the graph. See "Planar Code" for details.
The Planar Code format (input/output)
Format names used in headers: planar_code, embed_code
This is a
binary format not including coordinate information. Planar code does however
contain a hint for a 2D embedding as a convention. This information lies
in the order that a vertex's adjacencies are listed.
A Planar Code representation of a graph starts with a number giving the total number
of vertices. Then, for each vertex, follows a sequence of numbers specifiying
that vertex's neighbours. This sequence must enumerate the neighbours
as they appear when you go clockwise in one circle around the vertex.
Going anti-clockwise is allowed as well, but the direction must be the
same for all vertices of the graph. This information is actually a partial
encoding of a 2D embedding of the graph, and it is used by our 2D embedder.
Other formats (output only): PDB and CML
CaGe can save graphs in two other popular formats, PDB and CML. Both
of these are popular in the chemistry world and "rich" formats,
providing ways of expressing large amounts of different chemical information.
By the nature of its production process, CaGe doesn't know much about
the chemistry of its results, and thus only uses a small part of the CML
and PDB languages. The >>...<< format headers defined above
are not used with CML and PDB in order to produce compatible output.
In PDB, CaGe uses "ATOM" and "CONECT" records to encode
vertices and edges of its graphs. The CML features used by CaGe have been
chosen to produce CML output that is both compact and readable by one
of its viewers, Jmol, which CaGe "feeds"
with graphs to display via this CML format. CML's <molecule>
tag is amended by CaGe with a convention="MathGraph"
attribute. This instructs our "tailored" version of the Jmol
applet to strictly adhere to the atom coordinates and bonds given in the
input, rather than try to embed any atoms itself or second-guess the existence
or absence of bonds. (By contrast, there is no way to get the Rasmol viewer
out of its bond-guessing habit.)