Did you know ... Search Documentation:
Pack prolog_graphviz -- README.md

Prolog-based graph visualization

A Prolog-based library for visualizing graphs that uses the GraphViz library.


  1. Install SWI-Prolog.
  2. Install the GraphViz library:
apt install graphviz # Debian, Ubuntu
dnf install graphviz # Fedora, Red Hat


Install this library:

swipl -g 'pack_install(prolog_graphviz)' -t halt


Once installed, modules from this library are loaded as follows:

?- [library(gv)].

Exporting a single node

The basic feature of this library is that it allows you to write to a GraphViz output file or to a GraphViz viewer by simply writing to a Prolog output stream. The following example (see example/hello.pl) shows how to write a graph consisting of one node, and open the result in a GraphViz viewer:

?- gv_view([Out]>>format(Out, "x [label=<Hello,<BR/>world!>,shape=diamond];\n", [])).

This opens the following image inside a GraphViz-compatible viewer:


Exporting a single edge

In this example (see example/loves.pl) we write a graph that consists of a single edge:

?- gv_export('loves.svg', [Out]>>format(Out, "John -- Mary [label=loves];\n", [])).

This writes the following image to an SVG file. See the table in Section Output formats for a full list of supported output formats.


Advanced use

While you can use this library by directly writing DOT strings to an output stream, more advanced export tasks often benefit from using the library's support predicates. The most important ones are:

  • dot_node/[2,3] for exporting nodes.
  • dot_arc/[3,4] for exporitng (directed) arcs.
  • dot_edge/[3,4] for exporting (undirected) edges.

dot_arc/4 and dot_edge/4 take a list of options that are emitted as GraphViz attributes. Option label(+or([string,list(string)])) allows (multi-line) Unicode labels to be emitted using HTML-like labels (see Section HTML-like labels).

Exporting a proof tree

Suppose your program returns proof trees that consist of an entailment rule label, a conclusion, and an arbitrary number of premises:

?- Proof = t(rdfs(3),∈(class,class),[t(axiom(rdfs),range(range,class),[]),

The following program (see example/proof_tree.pl) exports such proof trees. Notice that this program uses the support predicates. This allows the nodes to be characterized by Prolog terms instead of DOT IDs. For most programs this results in simplified code because. Since these support predicates are idempotent, emitting the same node/edge multiple times does not accidentally change the exported graph.

:- use_module(library(apply)).
:- use_module(library(graph/gv)).
:- use_module(library(yall)).

view_proof(Proof) :-
  gv_view({Proof}/[Out]>>export_proof(Out, Proof), [directed(true)]).

export_proof(Out, Tree) :-
  Tree = t(Rule,Concl,Prems),
  dot_node(Out, Concl),
  dot_node(Out, Tree, [color(green),label(Rule)]),
  dot_arc(Out, Concl, Tree),
  maplist(export_subproof(Out, Tree), Prems).

export_subproof(Out, Node, Tree) :-
  Tree = t(_Rule,Concl,_Prems),
  dot_node(Out, Concl),
  dot_arc(Out, Node, Concl),
  export_proof(Out, Tree).

Since we use the predicate dot_arc/3, we must specify option directed(true) (graphs are undirected by default).

In order to open a specific proof tree, like $Proof, in a GraphViz-compatible viewer, we make the following call:

?- view_proof($Proof).

This produces the following visualization:


Exporting a parse trees

Suppose your program returns syntactic parse trees like the following:

?- Tree = s(np(det(the),n(cat)),vp(v(loves),np(det(the),n(dog))))

The following code exports such parse trees to SVG (see example/parse_tree.pl):

:- use_module(library(apply)).
:- use_module(library(graph/gv)).
:- use_module(library(yall)).

export_tree(Tree) :-
  gv_export('parse_tree.svg', {Tree}/[Out]>>export_tree(Out, Tree, _)).

export_tree(Out, Tree, Id) :-
  Tree =.. [Op|Trees],
  dot_node_id(Out, Id, [label(Op)]),
  maplist(export_tree(Out), Trees, Ids),
  maplist(dot_edge_id(Out, Id), Ids).

Notice that in the above program we use dot_node_id/3 instead of dot_node/3 and dot_edge_id/3 instead of dot_edge/3. The `*_id` versions require us to supply the DOT IDs ourselves. Arbitrary DOT IDs are generated with dot_id/1.

We can generate the visualization for the above syntax tree ($Tree), by making the following call:

?- export_tree($Tree).

This prodices the following result:


Notice that we create a new DOT ID (dot_id/1) for each node in the tree. Because of this, the two occurrences of ‘the’ can be distinguished.

Directed arcs or undirected edges?

Both directed and undirected graphs can be exported. By default, gv_export/[2,3] and gv_view/[1,2] export undirected graphs. Directed graphs are exported by setting the directed(true) option in gv_export/3 or gv_view/2. For undirected graphs, undirected edges are emitted with dot_edge/[3,4] and dot_edge_id/[3,4]. For directed graph, directed edges or arcs are emitted with dot_arc/[3,4] and dot_arc_id/[3,4].

Debugging graph exports

Sometimes when you use this library, or any other graph export library, a graph export may come out incorrectly: it either does not compile, or it does compile but looks weird. In such cases, it is convenient to be able to print the content that is exported to the top-level for inspection by the programmer. Printing the export to the top-level can be enabled with debug(dot), and disabled by nodebug(dot) (see library debug for more information).


This section gives a full enumeration of the values that are supported by this library's options.

Layout methods (option method/1)

The followig GraphViz layout methods are supported. They can be specified with the method(+atom) option in gv_export/[2,3] and gv_view/[1,2].

MethodUse case
circoCircular graph layouts.
dotDirected graphs.
fdpUndirected graphs.
neatoUndirected graphs.
osageArray-based layouts.
patchworkSquarified tree maps.
sfdpLarge undirected graphs.
twopiRadial graph layouts.

Output formats (option format/1)

The following GraphViz output formats are supported. They can be specified with the format(+atom) option in gv_export/[2,3] and gv_view/[1,2].

ExtensionTypeMedia TypeDescription
bmpbinaryimage/bmpWindows Bitmap (BMP)
canontextA prettyprinted version of the DOT input, with no layout performed.
cgimagebinaryCGImage, a drawable image object in Core Graphics (the low-level procedural drawing API for iOS and Mac OS X).
cmaptextClient-side image map files. Not well-formed XML.
cmapxtextServer-side and client-side image map files. Well-formed XML.
cmapx_nptextLike cmapx, but only using rectangles as active areas.
dottexttext/vnd.graphvizReproduces the DOT input, along with layout information.
dot_jsontextapplication/jsonJSON representation of the content (i.e., non-layout) information of the dot format.
epsbinaryimage/epsEncapsulated PostScript (EPS)
exrbinaryOpenEXR: a high dynamic-range (HDR) image file format developed by Industrial Light & Magic for use in computer imaging applications.
figtextFIG graphics format used by Xfig.
gdtextGD format (libgd).
gd2binaryGD2 format (libgd, compressed)
gifbinaryimage/gifGraphics Interchange Format (GIF)
gtkviewerGTK-based viewer
gvtextSame as dot.
icobinaryimage/vnd.microsoft.iconWindows icon format
imaptextSame as cmapx.
imap_nptextSame as cmapx_np.
ismaptextHTML image map
jp2binaryimage/jp2JPEG 2000
jpebinaryimage/jpegSame as jpeg.
jpegbinaryimage/jpegJoint Photographic Experts Group (JPEG)
jpgbinaryimage/jpegSame as jpeg.
jsontextapplication/jsonJSON representation of the content an layout information of the xdot format.
json0textapplication/jsonJSON representation of the content an layout information of the dot format.
pctbinaryimage/x-pictPICT: A graphics file format introduced on the original Apple Macintosh computer as its standard metafile format.
pdfbinaryapplication/pdfPortable Document Format (PDF)
pictextPIC language developed for troff.
picttextSame as pic.
plaintextA simple, line-based language.
plain-exttextLike plain, but providing port names on head and tail nodes when applicable.
pngtextimage/pngPortable Network Graphics (PNG)
povbinaryScene-description language for 3D modelling for the Persistence of Vision Raytracer.
ps2binaryPostScript output with PDF notations
psdbinaryimage/vnd.adobe.photoshopAdobe Photoshop PSD
sgibinaryimage/sgiSilicon Graphis Image (SGI)
svgtextimage/svg+xmlScalable Vector Graphics (SVG)
svgzbinaryapplication/gzipGNU zipped SVG
tgabinaryimage/x-targaTruevision Advanced Raster Graphics Adapter (TARGA)
tifbinaryimage/tiffSame as tiff.
tiffbinaryimage/tiffTagged Image File Format (TIFF)
tktextTK graphics primitives
vdxtextMicrosoft Visio XML drawing
vmltextapplication/vnd.openxmlformats-officedocument.vmlDrawingVector Markup Lanuage (VML)
vmlzbinaryGNU zipped VML
vrmltextmodel/vrmlVirtual Reality Modeling Language (VRML)
wbmpbinaryimage/vnd.wap.wbmpWireless Application Protocol Bitmap Format (WBMP)
webpbinaryimage/webpGoogle image format for the web (WebP)
x11viewerX11-based viewer
xdottexttext/vnd.graphvizLike dot, but adding more detailed information about how graph components are drawn.
xdot_jsontextapplication/jsonJSON representation of the content (i.e., non-layout) information of the xdot format.
xdot1.2texttext/vnd.graphvizSame as setting xdotversion=1.2 with the xdot format.
xdot1.4texttext/vnd.graphvizSame as setting xdotversion=1.4 with the xdot format.
xlibviewerSame as x11.

HTML-like labels

The DOT language supports several HTML-like facilities that allow rich labels to be printed for arcs, edges, and nodes. These can be specified by option label(+or([string,list(string)])), which takes either a string or a list of strings. In a list of strings, each string represents one line in a multi-line label.

Strings must adhere to the following BNF grammar for DOT HTML-like labels:

label : text
      | table
text : textitem
     | text textitem
textitem : string
         | <BR/>
         | <FONT> text </FONT>
         | <I> text </I>
         | <B> text </B>
         | <U> text </U>
         | <O> text </O>
         | <SUB> text </SUB>
         | <SUP> text </SUP>
         | <S> text </S>
table : [ <FONT> ] <TABLE> rows </TABLE> [ </FONT> ]
rows : row
     | rows row
     | rows <HR/> row
row: <TR> cells </TR>
cells : cell
      | cells cell
      | cells <VR/> cell
cell: <TD> label </TD>
    | <TD> <IMG/> </TD>

In addition to the above BNF grammar, tags are allowed to have attributes that are formatted similar to HTML attributes. Different tags support different sets of attributes:

Supported attributes for TABLE

  • BGCOLOR="color"
  • BORDER="value"
  • CELLBORDER="value"
  • CELLPADDING="value"
  • CELLSPACING="value"
  • COLOR="color"
  • COLUMNS="value"
  • HEIGHT="value"
  • HREF="value"
  • ID="value"
  • PORT="portName"
  • ROWS="value"
  • SIDES="value"
  • STYLE="value"
  • TARGET="value"
  • TITLE="value"
  • TOOLTIP="value"
  • WIDTH="value"

Supported attributes for BR


Supported attributes for FONT

[67, 79, 76, 79, 82, 61, 34, 99, 111, 108, 111, 114, 34]
Sets the color of the font of text that appears within `<FONT>…</FONT>`, or the border color of the table or cell within the scope of `<TABLE>…</TABLE>`, or `<TD>…</TD>`. This color can be overridden by COLOR attributes in descendents. By default, the font color is determined by the GraphViz fontcolor attribute of the corresponding node, edge or graph, and the border color is determined by the GraphViz color attribute of the corresponding node, edge or graph.
[70, 65, 67, 69, 61, 34, 102, 111, 110, 116, 110, 97, 109, 101, 34]
[80, 79, 73, 78, 84, 45, 83, 73, 90, 69, 61, 34, 118, 97, 108, 117, 101, 34]

Supported attributes for IMG

  • SRC="value"

Supported attributes for TD

  • BGCOLOR="color"
  • BORDER="value"
  • CELLPADDING="value"
  • CELLSPACING="value"
  • COLOR="color"
  • COLSPAN="value"
  • HEIGHT="value"
  • HREF="value"
  • ID="value"
  • PORT="portName"
  • ROWSPAN="value"
  • SIDES="value"
  • STYLE="value"
  • TARGET="value"
  • TITLE="value"
  • TOOLTIP="value"
  • WIDTH="value"