SWAG >> LSEdit

LSEdit: The Graphical Landscape Editor

LSEdit is a tool that permits viewing, manipulating, querying, layout and clustering of higraphs. An overview of LSEdit's capabilities can be found here.

The supporting paper can be found here.

Download LSEdit

LSEdit is a graph visualization tool that is particularly suited to exploration and editing of software "landscapes" produced by tools such as CPPX, QLDX, JAVEX and ASX. LSEdit is easy to install and use; it is Java-based and works well on many platforms, including Windows, Linux and Macintosh.

The latest builds of LSEdit are available for download here.

The DMS extension permits LSEdit to display of XML/RDF shared-canvas.

Setup and usage

Extraction from archive: To set up LSEdit, you will need to extract the files given contained in the selected archive. On Unix/Linux to extract from .tar.gz files use:

$ tar -zxvf lsedit.tar.gz

On Windows, use WinZip or other compression utility to decompress the .tar.gz and .zip files.

You need to have Sun's Java installed for LSEdit to work since LSEdit using the Swing foundational classes. It is recommended that you install the SDK since this provides you with the java compiler, in addition to the java runtime software. If you encounter problems running LSEdit as an applet, make sure you are using Sun's JVM. This can be downloaded and installed from http://java.sun.com. You can ensure that you are using the right version of java by typing javac -version. If you are using the wrong version you may need to invoke the right version explicitly or change your search path.

Compiling: It is strongly recommended that you recompile lsedit before using, even if class files needed to run lsedit are provided in the release. This will ensure that the resulting class files are compatible with your installed version of sun's Java. To compile or recompile the source code for LSEdit, change into the directory above the source code, and check that you can now see a directory called lsedit containing the java source code (the *.java files).

Set your CLASSPATH environment variable to '.', and then issue the command

javac.exe -g lsedit/*.java.

The program javac.exe may need to be specified by its full path name (where ever you installed it as part of installing sun's java), if the appropriate java bin directory is not listed in your PATH environment variable. Please be careful to ensure that you compile using sun's (now Oracle's) Java compiler, and not the Microsoft J++ compiler. If you distrust the pre-existing class files in the lsedit directory, remove them before initiating the compile.

Launching on Linux: Assuming you extracted LSEdit files to the directory /home/username/bin/lsedit/, you will be able to run LSEdit with the following command (all on one line):

java -classpath /home/username/bin/ lsedit.LandscapeEditorFrame

Launching on Windows: The command used to launch LSEdit on a Windows computer is very similar to the one used on Linux. Assuming that LSEdit files reside in the directory C:\lsedit you will use the command:

java.exe -classpath c:\ lsedit.LandscapeEditorFrame

Notice that in either case the classpath is set one directory level above the location of LSEdit files.

If you know what landscape you wish to open, you can specify the landscape file name at the end of the command line specified above. For example, if you want to open a file named landscape.ls.ta, you would do it as follows (again, enter the entire command all on one line):

java -classpath /home/username/bin/ lsedit.LandscapeEditorFrame landscape.ls.ta

Since the command to invoke LSEdit is rather long, and typing it out by hand each time is rather cumbersome, it is advisable to create a shell script that would invoke the command for you.

Using lsedit.jar: An alternative method of invoking LSEdit, if you have no need to potentially view or recompile source code, is to use the provided jar file. This is significantly smaller to download, and more convenient to use than unpacking all of the source and class files explicitly associated with LSEdit. To invoke LSEdit using the lsedit.jar file, this file is added to the list of java classpaths as shown below:

java.exe" -classpath .;./lsedit.jar lsedit.LandscapeEditorFrame landscape.ls.ta

Using xming: If you are willingness to accept very slow painting, lsedit can also be run remotely using ssh and xming. You will need to follow the ssh instructions which involve ensuring that
edit -> settings -> tunnelling > x11 is set and that
edit -> settings -> authentication > ssh2 is set
potentially before connecting to the remote machine, and within your ssh session (on the remote machine) setting:

It is recommended that you proof the X-11 connection/communication by getting xclock & to produce a local display, before attempting to use this connection with lsedit. Mileage may vary. Getting X-11 communication to work between a remote and local machine can be rather trying.

Java Performance flags

The actual performance and behaviour of LSEdit may be critically dependent on various additional java optimization flags, and may vary from system to system.

Direct draw. If repainting is very slow, try playing with the following two options, which selectively enable or disable use of external direct draw capabilities within java.

-Dsun.java2d.noddraw=true -Dsun.java2d.ddscale=true

Memory. When operating on very large graphs, the memory allocated by java may become exhausted. It is recommended that to avoid this possibility, memory be explicitly requested when running lsedit. This can be done by setting the minimum and maximum amounts of memory that the java engine is to reserve as shown below:

-Xms128M -Xmx1024M

Using the above options LSEdit might then be invoked using:

java -Xms128M -Xmx1024M -Dsun.java2d.noddraw=true -Dsun.java2d.ddscale=true -classpath . lsedit.LandscapeEditorFrame

Perm Memory. If you are advised that perm memory has become exhaused you will need to increase the size of perm memory. Note that this is distinct in java from the size allocated to the heap, and to the stack. While it is impossible to predict lsedit usage, suitable java arguments that may address this problem are:

-Xms1024M -Xmx1024M -XX:PermSize=512M -XX:MaxPermSize=512M

LSEdit options

-? Report LSEdit version and run time options
-b<pointsize> Set all fonts to the specified pointsize to aid accessibility
-d Generate additional debugging output
-f<steps> Form an automatic forward path trace the indicated number of steps on the node specified by the -N option at startup.
-g<w>x<h> Geometry width and height in pixels for the landscape
-G<w>x<h> Geometry width and height in pixels for the diagram within landscape
-h Report LSEdit version and run time options. Also show any parameters associated with an applet, to test that they are being recognised.
-i<init file> Use the specified init file on startup to establish initial run time options.
-L Use a preset geometry for the landscape on startup.
-l <layout> Default layout algorithm to use initially.
This may be matrix, simplex, sugiyama, spring, old spring, or lisp.
-N <id> The entity with the specified entity id is to be shown on startup.
-P <path> Path to save landscape to.
-S <suffix> Suffix to append to saved landscapes.
-s Perform strict checking of input TA
Errors in the TA will be reported on standard output.
-T<title> Set the frame title to the specified title. This can be useful if one is generating multiple landscapes automatically and wishes to distinguish each from the others
-v Generate verbose parsing output
-X <cmd> Application to filter saved output through.

Applet parameters

test string Test that applet can display the string
lsfile URL Landscape TA file to open
init URL Landscape initialisation parameter file
layout name Set the graph layouter to the named layout algorithm
toolabout URL URL linked to on pressing F11
toolhelp URL URL linked to on pressing F12
startEntity string Entity to navigate to
forward steps Perform a forward trace the indicated number of steps on the start entity.
lsfile_bg0 URL Additional landscape to list in the File menu
lsfile_bg<n> URL Further landscape(s) to list in the File menu

Applet memory issues

When attempting to load very large TA files for viewing in an applet, the browser may hang, if the java runtime engine runs out of memory. In theory one can manually adjust the space available to the java runtime engine by setting parameters on the JRE through the Control Panel Java tool, exactly as is done when java is running in standalone mode. However the user is cautioned that current bugs in java make this impossible to accomplish: See here and here.

Creating your own landscapes

If you are interested in creating LSEdit landscapes yourself, you should read the landscape construction guide, which is available here.

Sample landscapes

Several ready-made landscapes are available for download below.

The EG program
A very small landscape that can be used to test your LSEdit installation.
[download eg.ls.ta]
C488 compiler
A medium-sized landscape representing an extraction of a toy compiler.
[download c488.ta] [download c488.zip]
A larger landscape showing extraction of C++.
[download asx.ta]
Linux kernel
A file-level extraction of the Linux kernel.
[download linux.ls.ta]

Contact information

For more information on LSEdit please contact us at .