4/07 IEEE Article
4/03 IEEE Article
6/02 GSRC Presentations
Metropolis Model Structure Viewer User's Guide
model structure viewer is an
It presents a graphical display of the objects in a Metropolis model
and the connections between their ports.
- Creating a Metropolis project
Below is an example of the display of the top-level netlist of
the Picture-in-Picture modeling example.
Double-clicking on an object representing a netlist (displayed as
a gray box by default) opens another view showing the structure of
Double-clicking on another object opens a text editor on the source
code for that object.
To date, the Structure Viewer has been tested on Windows XP and Redhat
Enterprise Linux Release 4.
The Structure Viewer requires
Eclipse 3.1 or later,
using Java version 1.5 or later,
Graphical Editor Framework (GEF)
Eclipse plugin, release 3.1.1 or later.
It also requires a local installation of
Also, in order to do automatic layout, the open-source
layout programs from AT&T must be accessible.
Before you can use the Metropolis plugin, some initial setup is necessary
- Download Eclipse 3.1 (or later) from
install it on your system.
- Download the Graphical Editor Framework (GEF) plugin from
(The runtime version is sufficient, as opposed to the development-kit
Unzip the downloaded
file in the folder containing your Eclipse
installation (i.e., containing the folder called "eclipse"), and its
contents should be extracted into their proper places (the plugins,
features, and readme folders).
- Download the metro_ui plugin from
and unzip it
into your Eclipse installation in the same way.
- Download Metropolis from
and install it according to the included documentation.
- Download and install the GraphViz layout programs from
In order to create a graphical view of a Metropolis model,
the model must be in a Metropolis project under Eclipse.
Create a project from the
- Open the Java perspective:
Window -> Open Perspective -> Java
- Specify the location of your Metropolis installation and your Java
Window -> Preferences -> Metropolis
Fill in the paths by typing, or by using the
- Disable automatic building:
Build Automatically (if it shows a checkmark)
File -> New -> Project... -> Other -> Metropolis Project
You are first prompted to give the project a name.
The name must be the name of the root package of your model.
The top-level folder of the project is where you will put any metamodel (.mmm)
source files belonging to the top-level package, and any subfolders
After entering the name, you can hit
Your Metropolis metamodel (.mmm) source code can be created in place
using Eclipse's text editor, or it can be imported into your project.
To import files that are accessable from your file system,
select the project title in the Package Explorer view,
right-click to bring up the context menu, and select the
Import..." menu item.
On the first page of the resulting wizard,
File system" as the source
and navigate to your files in the subsequent wizard pages.
If your files are in CVS, you can instead use the
Team -> Share Project..."
context menu item to check out your files
The details of using CVS with Eclipse are outside the scope
of this document, but are fairly straight-forward.
The specifications for compiling your model
(i.e., the information you would include on the
command line of a
metacomp command that would build it)
are entered as properties of the Eclipse project containing
To enter that information, right-click on the project resource
in the Package Explorer view:
The Properties dialog for a Metropolis project will contain two
pages, called "
Properties in project context menu:
Metro Source Files".
Here are illustrations of example settings for the
To further illustrate, here are settings for the
Metro Specs page,
for entering Java classpath and Metropolis
classpath (each initially set to default values), and the
fully-qualified name of the top-level model package,
and the name of the top-level netlist.
Metro Source Files page,
with tools for browsing to files
in the project, in the Metropolis library, and elsewhere in the
local file system, respectively.
Add... button to add entries.
Select entries and click the
button to delete them.
Once your source files are in place
and the properties are set correctly for compiling,
you can build your model by selecting
the project name,
or any resource listed under it,
view and then the main-menu item
Metro Specs page
for the PiP example.
Metro Source Files page
for the PiP example.
This will invoke the Metropolis elaborator backend to compile the
model through the elaboration stage. The
Project -> Build Project
Window -> Show View -> Console)
displays the output of that process.
A successful build will create a folder inside the project called
(Subsequent builds will create
To avoid this accumulation, delete unwanted
metroX.tmp folders before building.)
metro0.tmp is a binary representation of
the model structure called
Below is a screendump of an Eclipse window showing the output of
a successful build of the
and the file
NET which it creates.
Output of a build.
Double-clicking on the file
will bring up a display of the elaborated netlist described by
The initial appearance of the graphical display
depends on the layout preference settings.
Before describing the preferences, a note about auto-layout is in order:
Automatic layout is provided as a helpful starting point for laying out
It may not provide a suitable finished layout, but can help
provide an initial layout that is understandable and
easily modifiable by hand.
The preferences can be helpful in getting the most out of auto-layout.
The layout preferences are accessed from the main Eclipse menus:
Window -> Preferences -> Metropolis -> Layout
Do automatic layout...
- All objects will initially appear stacked on top of each other
in the upper-left corner, and must be positioned by hand to create
and understandable display.
When no layout has yet been done
- Automatic layout will be done, as long as no layout has yet been
saved for this netlist.
Auto layout style
spring tension (GraphViz neato)
- Use GraphiViz neato to do layout, which uses a
This is probably the most generally useful choice, although the others
may be worth experimenting with.
hierarchical, in rank and file (GraphViz dot)
- Use GraphViz dot to do layout.
dot is most applicable to hierarchical directed graphs.
radial (GraphViz twopi)
- twopi tries to arrange things in circular arcs.
circular (GraphViz circo)
- circo tries to arrange the graph in concentric circles.
More information about these layout schemes is available on the
Stretch the distance between components...
This slider allows adjusting the distance between objects provided
by the auto-layout program.
Location of GraphViz programs
This file-specification tool must be filled in to tell the
plugin where to find the layout programs, if auto-layout is desired.
Fit MObjects around their names / Use default MObject size:
The initial size of netlist components is set here to either fit snugly around
their name labels, or else to be a set width and height in pixels.
- Color Editors
Color editors are provided to change the colors used to identify
the types of objects displayed.
The display shows the structure of a netlist.
The name of the netlist whose structure is being displayed appears
in the tab at the top of the Structure Viewer.
The components of the netlist appear as colored rectangles.
A rectangle's color corresponds to the type of component it represents.
The color key is on the layout preferences page (see above),
where the colors are customizable.
The name of the component in the netlist is displayed in the middle
of its rectangle.
Hovering over a component displays its name,
the fully-qualified name of its class,
and its type in a tooltip.
Connections between the netlist components are displayed as lines
connecting them, attached at their ports.
A gray circle on a component rectangle represents an input port
The name of the interface is displayed in a tooltip when the mouse
hovers over it.
A white circle on a component rectangle represents an output port.
The name of the port is displayed in a tooltip when the mouse
hovers over it.
A gray or white circle that is not on a component rectangle
is a "shadow port".
Its connection ends at a port that is not in the currently displayed
Shadow ports are so called because they can be thought of as the point
where a connection casts a shadow on the netlist boundary
on its way to an endpoint in some other netlist.
A shadow port can appear either as a free-floating symbol,
when it represents a connection endpoint outside of the current
or as a port symbol on a netlist object,
when it represents a connection endpoint inside that netlist.
The following figure illustrates:
If the preferences have been set to do automatic layout,
and the GraphViz programs are correctly installed,
the netlist components will be automatically layed out
in some manner the first time a netlist is displayed.
Automatic layout will also happen on subsequent displays
of the same netlist, as long as the layout has not been saved.
The rectangular component symbols and the free-floating
shadow port symbols can be dragged into any position.
They can also be resized by selecting them and dragging their
Multiple symbols can be selected at once by dragging a selection
box around them, or by doing
to add them to the current selection.
Saving (and a caveat)
Currently, saving means saving the layout,
and it is done in any of three ways described below.
An important caveat:
If multiple views of the model are open when one is saved
-- i.e., views of multiple netlists in a hierarchical structure --
it is important to realize that the layout for all
views will be saved.
That is, the layout for the entire model is saved in one place
and saving any view saves the layout for all views.
- Open a sub-netlist
Double-clicking on a netlist symbol will open another viewer displaying
the structure of that netlist.
Edit source code
Double-clicking on a non-netlist component figure will open a
text editor on the source code for that component,
if that source code file resides in the local Metropolis project
Reposition and resize objects
Objects can be repositioned by dragging them, and resized by
selecting them and dragging their handles.
Undo and redo
Layout changes can be undone and re-done in three ways:
Edit menu contains
- The Eclipse workspace toolbar contains icons for
- Right-clicking on the diagram background brings up
a pop-up menu containing
- The graph layout can be saved in three ways:
File menu contains a
- The workspace toolbar contains a
- If layout changes have been made when a graph page is closed,
the user is prompted whether to save the layout or to close without
The view image can be saved to a file by right-clicking on the background
and selecting "Export Image..." from the popup menu.
This will bring up a dialog to use to specify the file type, file name,
and location of the exported image file.
JPEG and BMP formats have been tested to work on Windows and Redhat Linux
platforms. The underlying Java API theoretically also supports PNG and GIF,
but success with those is yet to be seen.