SBML Layout Extension

A first draft specification of the SBML Render package is available. (last updated April 14,2015).

As of August 13, 2013 the Layout package has been officially accepted by the SBML Community. The official specification is hosted on co.mbine.org.

Official specification for the SBML Layout Package (RC2) (last updated 07/24/2013)

specification for the SBML layout extension (last updated 04/25/2005)

specification for the SBML render extension (last updated 05/25/2011)

If you have specific questions, issues or suggestions, those are always welcome and should be directed to the Layout or Render Package Working groups:

• sbml-layout or
• sbml-render

04/14/2015

Release of Draft1 of the completed Level 3 Specification for Render.

08/13/2013

Release of V1 of the completed Level 3 Specification for Layout.

07/24/2013

Release of RC2 of the completed Level 3 Specification for Layout.

05/25/2011

Small change to the SBML render extension with respect to the interpretation of the text-anchor attributes.

The examples and the software packages will be updates to reflect this change soon.

The patch against libsbml for reading and writing render information with libsbml if not affected by this change.

10/03/2010

I have just updated most of the software and examples for the SBML layout and render extension.

The software section now contains an updated version of the XSLT stylesheet that has a number of bugfixes and that is able to handle layout and render information in SBML Level 3 documents.

Also new is a patch against the sources for libsbml 4.1.0. This patch enables reading and writing the SBML render extension in libsbml 4.1.0 for SBML Level 2 as well as SBML Level 3 documents. The patch includes updated documentation for all classes as well as a number of new unittests as well as language bindings for python and java complete with unittests.

The library for the rendering of layout and render information has also been updated and contains some bugfixes as well as updates to work with the latest version of the patched libsbml 4.1.0.

There are also some changes to the examples section, e.g. the render extension testcases now come with source files, SVG images and PNG images for the individual testcases. All testcases are now available in an SBML Level 2 version as well as an SBML Level 3 version.

Last but not least, there are some more complex render extension examples which I used to test the implementations. One of the new examples is a reproduction of a figure from the SBGN specification:

10/29/2009

I finally had the time to finish some things that have been sitting on my harddisk for a while.

First, there is a new updated version of the render extension specification. It contains a lot of clearifications and updates as well as some minor changes that are supposed to make implementations easier.

You can download the new version of the render extension specification here.

In addition to an updated specification, I have updated the XSLT stylesheet that can be used to create SVG drawings from SBML layout and render information.

The new version of the stylesheet has lots of cleanups in the code, much more documentation in the code as well as some bugfixes. The sylesheet can create SVG drawing based on the older version of the render extension as well as the new version that I mentined above. Per default the stylesheet no longer uses SVG marker to display arrow heads. Markers are a nice feature, but they don't seem to be very well supported by current SVG implementations. The new stylesheet now draws the arrow heads explicitely. However, there is a parameter that can be passed to the XSLT processor that reenables markers.

The new stylesheet can be downloaded here.

Last but not least, there now is a C++ implementation of the render extension. The C++ implementation consists of two parts. The first of which is a patch against libsbml that implements the data structures as well as reading and writing the render extension elements. The implementation is similar to the already existing implementation for the layout extension. Just like the XSLT stylesheet, the C++ implementation can read render information according to the old specification as well as the new. Writing render information however is always done in the new format.

Currently this extension to libsbml is C++ only, there are no other language bindings right now.

You can download the implementation as a patch against the sources of libsbml-3.4.1. Actually the patch contains a lot more than it needs to and it basically brings the libsbml 3.4.1 sources up to date with the current subversion repository as well as adding the render extension datatypes.

If you are interested in this patch, you can download it here.

Besides this patch against libsbml, I have written a small C++ library that uses the datastructures from libsbml to render layouts with and without render information using OpenGL. So far the implementation is using mostly constructs available in OpenGL 1.5 and should therefore run on most systems.

I did not have time to clean up the code so far, so the API might be a bit inconsistent in places and the renderer might not be as fast as would be posible. But for the small examples I have tested it with so far, it was fast enough. My primary goal was to have a correct implementation first and optimize later.

The sources for the render library can be downloaded here.

In order to be able to test the render library, I have written a small application with a graphical user interface. The application can read SBML files with layout and render information and display them. The user can switch layouts and render information as well as zoom. There is also limited support for changing layouts by selecting and moving elements in the layout.

To make the application a bit more useful I also added the possibility to export bitmaps of the displayed layouts of (almost) arbitrary size. On systems with newer OpenGL implementations the display as well as the exported bitmaps are antialiased.

The application uses the Qt toolkit which is freely available for Microsoft Windows, Mac OS X and all kinds of Linux/Unix systems. This way, the application can also be compiled on all those platforms.

The sources for the application can be downloaded from here. Additionally I have compiled binaries for everal platforms:
LayoutViewer (Windows 32Bit) (6 MB)
LayoutViewer (Mac OS X Intel, 32Bit) (13 MB)
LayoutViewer (Linux 32Bit) (3 MB)

The windows and the Mac OS X versions should include all the necessary libraries, the linux version is dynamically linked and you need to install expat, libpng, libjpeg as well as Qt4.

(I meant to provide a universal binary for Mac OS X to allow people to run it on PPC based computers, but right now my maschine will not compile universal binaries for Qt4 on Mac OS X 10.6.)

There is one important thing missing right now, which is an updated XML Schema for the new render specification and I hope to find some time to finish that soon.

Another item that is missing is documentation for the different downloads I have provided here. I also hope that I will be able to fix this soon.

For the time being I hope that the application for displaying layouts as well as the XSLT stylesheet might be useful for some of you.

Another thing that developers that actually try to implement the render extension might find useful is a set of testcases for the the render extension. They are just small samples that test certain aspects of the render extension.

The complete set of systematic testcases is available here.

As always, feedback is more than welcome.

01/30/2008

During the SuperHackathon on Okinawa I found some time to update the render specification a bit and to fix some warnings and errors from he layout and render examples with libsbml 3.

A list of changes can be found at the end of the document. They are all based on feedback from Frank Bergmann from the University of Washington.

• New render extension specification draft
• layout example 1
• layout example 2
• layout example 3
• layout example 4
• layout example 5
• layout example 6
• render example

03/12/2007

During the last few days, I finally found the time to go over the render specification to correct some mistakes and rewrite some parts.

I also updated the stylesheets and corrected some errors in the example files.

The new stylesheet can now transform SBML files with layout and render information into SVG drawings just like before but I corrected some bugs that prevented it to run with Xalan.

I also integrated the functionality of the old stylesheet into the new one so layout information only can now be rendered. If you only specify the id of a layout and no render information id, the layout will be rendered as it would have been with the old stylesheet. If you do not specify a layout id at all, the first layout will be rendered. With respect the rendering layout information only, the old stylesheet and the new stylesheet should behave exactly the same.

The old stylesheet has also been updated. So far it always rendered the first layout. The new version has a new parameter called LAYOUT_ID which can be used to specify the id of the layout to be rendered. If the parameter is not specified, the first layout is rendered just as before.

• New render extension specification draft
• XSLT stylesheet to transform and SBML file with layout & render information into SVG
• simple sample file
• more complex sample file
• XSLT stylesheet to transform and SBML file with layout information only into SVG.

As always, feedback and bug reports, especially on the render specification are very welcome.

Here are a few examples that were created from the sample files above:

10/12/2006

I thought it would be a good idea to upload some of the files for the new render extension I have been working on for people to play with. Comments and suggestions are always welcome and I would be glad to get as much feedback as possible. You can get the following files:

• New render extension specification draft
• XSLT stylesheet to transform and SBML file with layout & render information into SVG
• simple sample file
• more complex sample file

To use the stylesheet you need an XSLT processor which supports XSLT 1.0. xsltproc works just fine. To convert an SBML file with layout & render information into an SVG drawing, you have to specify to input files and some parameters that tell the processor which layout and which render information to process. The render information either has to be a global render information or a set of render information within the layout that is to be processed. To render the Kohn Map in the second sample file you would for example say:

xsltproc --stringparam "LAYOUT_ID" "KohnMapLayout" --stringparam "RENDER_INFORMATION_ID" "KohnMapStyle" --param "ZOOM_FACTOR" "2.0" --param "VIEWPORT_PADDING" "2.0" sbml_extended_layout-svg.xsl CaMK-Activation.xml > CaMK-Activation-KohnMap.svg

You can find a short documentation of the parameters used in the example and some others not used at the top of the stylesheet.

05/17/2006

I finally found the time to update the xslt stylesheet for converting SBML Layout into SVG and I would like to thank Frank Bergman for his help in the debugging process and Bill Denney for pointing me at the SVG markers. There are many small improvements and so I will only list the ones that I think are important:

• XSLT stylesheet validates agains Relax NG schema
• SVG output is now SVG 1.0 which might help some older SVG implementations.
• SVG output validates against Schema from W3C
• Arrow heads are now drawn using SVG markers
• Most parameters, e.g. colors can be overridden when calling the XSLT processor
• The arrows for modifier species references no longer use color coding only for the type of modification but use different arrow heads. The style of the arrow heads was taken from Frank Bergmans online layout renderer.
• Parts of lines that should not be visible are now clipped away.

Due to some discussion we had at the SBML Hackathon lately, I changed the license to the less restrictive LGPL.

You can download it here.

Small note to windows users: the xslt stylesheet uses some math extensions. The XSLT Processors under Mac OS X and Linux seem to include those, but some Windows XSLT processors don't. In oder to enable them under those prozesors, you have to remove the comment tags around the import statement just after the license text. And naturally you have to make sure that math.xsl is there.

03/10/2006

Since there has been a request concerning the license of the XSLT stylesheet, I uploaded a new version of the stylesheet which is now under the GPL2. You can still get it at the same place.

04/25/2005

As promised here is another example that demonstrates the representation of modifier species references with the layout extension.

While working on this example, I found two bugs in the current layout implementation, so I also uploaded a new patched version of libsbml-2.2.0. This patch fixes an issue with ModifierSpecies being written incorrectly as well as roles for SpeciesReferenceGlyphs being written as integer values rather then strings as stated in the document.

I also found two minor mistakes in the document. the role of a species reference glyphs was "UNDEFINED", this has been changed to "undefined" since all the other keywords are lowercase. We also forgot to mention the "undefined" keyword later on in the text.

We not only forgot the undefined keyword in the document, we also forgot to add it to the XML Schema, so I also uploaded a new version of the schema.

An update to the XSLT stylesheet was also necessary in order to draw the species reference glyphs differently depending on their role attribute. This is surely not the final version, but it is enough to demonstrate the representation of modifier species references by species reference glyphs.

Files:
SBML Layout specification document version 2.2
C++ sample that generates sample3
sample3 PNG rendering done with rsvg
sample3 SVG rendering
sample3 SBML file with layout
XSLT stylesheet
XML Schema file

04/13/2005

These is a preliminary version of an example layout for glycolysis. Since they came up in a discussion on the libsbml mailing list, I released them so that other people can participate in the discussion. Be aware that they probably do contain some errors that I haven't found and much less fixed.

File:
SBML file with layout
PNG image created from SVG

04/12/2005

As promised, here is a new version of the layout specification. The only real change from the last version is the included sample file. The specification new includes the file that can be generated from any of the three programming samples below. It therefore conformes to the implementation.

04/11/2005

With the Hackathon 2005 coming up, it is time for a new release of the implementation of the layout extension. This release adds a few bugfixes to the implementation itself as well as some programming examples in C++, Java and Python. Since the CVS of libsbml is being redone right now, I have not had the time yet to bring the implementation up to the latest CVS version of libsbml. The current implementation is done on a libsbml version that was checked out from CVS on 12/20/2004. It essentially is version 2.2.0 with some bugfixes and minor enhancements.

To enable the layout extension when you configure libsbml, you add the command line switch --enable-layout when you run configure. Also remember to add the -DMAKE_LAYOUT switch if you compile C or C++ programs that use classes or functions from the layout extension.

To make it easier for people who want to try this release, I uploaded an already patched version of libsbml which has been tested under Mac OS X and linux (Debian/unstable).

An updated documentation where this new sample file replaces the existing on will be released soon. I also wrote an xslt stylesheet that tries to render a SBML file with layout information as an SVG image. The stylesheet is to some extend customizable via variables and it should be easy to adept it to generate the output you like.

This image has been generated from the SBML file that is generated by one of the programming examples (they all generate the same SBML file), processing it with xsltproc and rendering it with rsvg. If anybody is interested in a documentation how to do this, feel free to contact me and I will provide one.

click here for a larger version


Files:
patch against libsbml CVS from 12/20/2004 (~50k)
libsbml CVS 12/20/2004 with layout extension (~3.5MB)
C++ sample program
Java sample program
Python sample program
Simple SBML sample file with layout information
SBML layout to SVG XSLT stylesheet

01/14/2005

I just removed a few bugs from the layout extension implementation and made the parser behave more like the parser for the rest of the SBML file. This also fixed some small memory leaks. The new patch against libsbml-2.2.0 is available from here. I also noticed a small typo in the sample file. The corrected version can be downloaded here. The typo still exists in the document, but I don't think that an update will be necessary because of a missing "s". Applying the patch works the same as before: To apply the patch, you have to unzip the libsbml-2.2.0.zip file and the patch_libsbml_2.2.0_layout-2005-01-14.zip file. Now change into the libsbml-2.2.0 directory and call "patch -p1 < ../patch_libsbml_2.2.0_layout-2005-01-14". Now you can call configure. In the libsbml-2.2.0 directory you will also find a README.layout that explains what you have to do in order to enable the layout extension for libsbml.

11/19/2004

A new version of the layout extension patch patch is available for download. This patch can be applied to libsbml 2.2.0 and adds the layout extension as described by version 2.1.1 of the document. To apply the patch, you have to unzip the libsbml-2.2.0.zip file and the layout_patch_libsbml_2.2.0.zip file. Now change into the libsbml-2.2.0 directory and call "patch -p1 < ../layout_patch_libsbml_2.2.0". Now you can call configure. In the libsbml-2.2.0 directory you will also find a README.layout that explains what you have to do in order to enable the layout extension for libsbml.

10/08/2004	Updated version of the SBML layout specification	Document as PDF	Simple example file.	XML Schema
06/30/2004	Updated version of the SBML layout specification	Document as PDF	Simple example file.	XML Schema
04/29/2004	A first implementation of the layout extension. (patch against libsbml 2.0.3)	patchfile for libsbml-2.0.3	Simple example file.
02/03/2004	Just some small fixes in the documentation for the simplified layout.		layout draft pdf	xml schema file
01/20/2004	This is the simplified proposal that was discussed in St. Louis.		layout draft pdf	xml schema file
10/28/2003	New version of the render document with many changes. The schema file is the same for layout and render part. There are some small schema bugs in the document that have been corrected in the schema.	render draft html	render draft pdf	xml schema file
10/28/2003	New layout document with mostly facelifting and some changes to make it more consistent with the render document.	layout document html	layout document pdf	xml schema file
09/18/2003	This is a first draft of the render part of the layout extension.	render draft pdf
09/11/2003	This version has some minor changes. The document now specifies the default size unit to be pt and the layout object has a bounding box.	html	pdf	xml schema
09/05/2003	Grouping of layout objects and edge representation have been added. This is Version 1.1a. Version 1.1 as sent to the mailing list has a small error that was corrected in this version.	html	pdf	xml schema
07/05/2003	Layout information has been taken out of the model definition.	documentation in html format	documentation in pdf format	xml schema	sample file
05/26/2003	Compartment was missing a "z" and "depth" attribute for 3D layout.	documentation in html format	documentation in pdf format	xml schema	sample file
05/22/2003	New version of the document that adds some points concerning SBML Level 2, 3 dimensional layout information and some points discussed in the SBML discussion mailing list.
05/20/2003	First version of the document uploaded.

These are some simple examples on how to store layout information in SBML files:
example 1 (last updated 30/01/2008)
example 2 (last updated 30/01/2008)
example 3 (last updated 30/01/2008)
example 4 (last updated 30/01/2008)
example 5 (last updated 30/01/2008)
example 6 (last updated 30/01/2008)

render extension "testsuite" (last updated 10/03/2010):
Here are a few example files for the SBML render extension. Each file tries to cover a certain element or aspect of the render extension. This set of files was used to test the implementation of the XSLT stylesheet and the render library as well as the render extension patch against libsbml. The different examples are available as SBML Level 2 and SBML Level 3 files. For each layout and render information of each file, there is an SVG image that was created with the XSLT stylesheet from the software section and a PNG image created with the Batik toolkit from the corresponding SVG file. The new version of the testcases also includes the sources that can be used to create the SBML documents. The sources depend on a patched version of libsbml 4. The patch for libsbml 4.1. can be downloaded from the software section.

render extension examples (last updated 10/03/2010):
These are some render extension examples that combine different features from the render extension. The file includes the SBML documents (most for SBML Level 2 as well as SBML Level 3), SVG figures created from the layout and render information in the SBML documents and PNG images created from the SVG figures with the help of the Batik toolkit.

large render extension example (last updated 30/01/2008):
This is a rather complex example on how to use layout and render extension in SBML files. It contains several layouts and each layout has one or more assocatiated pieces of render information.

simple render extension example (last updated 09/03/2007):
This is a rather simple example on how to use the layout and the render extension in SBML files. The file contains a single layout and it associated different styles with the layout so that is can be rendered in different ways.

Unless specified otherwise, all software is licensed under the LGPL.

XSLT stylesheet (last updated 10/03/2010)
This stylesheet can be used to convert layout and render information in SBML files to SVG vector drawings. For this, an xsltprocessor, e.g. xslt has to be used.

render extension patch for libsbml 4.1.0 (Last updated 10/01/2010):
This patch can be applied against the source code for libsbml version 4.1.0. it enables reading and writing of render information in libsbml 4.1.0. Support for layout information is already included in libsbml.

render extension patch for libsbml 4.2.0 (Last updated 01/15/2011):
This patch can be applied against the source code for libsbml version 4.2.0. it enables reading and writing of render information in libsbml 4.1.0. Support for layout information is already included in libsbml.

This patch is used to compile current versions of COPASI (e.g. 4.6.33 and 4.6.34).

Please note that these patches contain an experimental implementation for reading and writing layout and render information in SBML Level 3 files using the proposed package mechanism of SBML Level 3. Since the SBML layout and render extension are not official SBML Level 3 extensions yet, SBML Level 3 files with layout or render information should not be distributed. It is always possible that the format will differ from the format currently used. This only applies to SBML Level 3 files being written with a version of libsbml that has one of these patches applies, SBML Level 2 files are not affected.

render extension patch for libsbml 3.4.1 (Last updated 10/29/2009):
This patch can be applied against the source code for libsbml version 3.4.1. it enables reading and writing of render information in libsbml 3.4.1. Support for layout information is already included in libsbml.

render library (last updated 10/01/2010):
An OpenGL based C++ library to render layout and render information from SBML files. It requires the data structures that the render extension patch adds to libsbml.

Layout Viewer:
This is a small example program that uses the above render extension patch and the render library to display layout and render information in SBML files. The program reads SBML files and displays the layout information in the file. The user is able to choose which layout is displayed if there are several and if there is render information connected to the layout information the user can choose how to render the layout. If there is no render information in the file, the user can choose a style from a set of predefined styles. The displayed layouts can be modified and exported as bitmap images.

The program is either available as source code or as a binary for different platforms:
Layout viewer source code (last updated 10/29/2009)
Layout viewer for Mac OS X (32 Bit) (last updated 10/29/2009)
Layout viewer for Microsoft Windows (32 Bit) (last updated 10/29/2009)
Layout viewer for Linux (32 Bit) (last updated 10/29/2009)