Visualize an ontology with one command

A five-minute tutorial for ttl3d, using the Pizza ontology.

What ttl3d does

ttl3d is a command-line tool that turns one or more RDF files (Turtle, N-Triples, RDF/XML, JSON-LD, TriG, N-Quads) into a single HTML page showing the graph in 3D or 2D. Every IRI that is a subject or the object of a relation becomes a node; every IRI-to-IRI triple becomes a link labelled with its predicate. The page embeds all of its JavaScript, so it opens from a file, works offline, and sends nothing anywhere. It runs on Python 3.10 or newer on Linux, macOS and Windows.

Install

pip install ttl3d

or, from conda-forge (Python 3.11 or newer there):

conda install -c conda-forge ttl3d

Render the Pizza ontology

The Pizza ontology is the classic OWL tutorial ontology from Stanford and Manchester. Download it, then run:

ttl3d pizza.owl --color-by type -o pizza.html

ttl3d prints one line, 121 nodes, 103 links -> pizza.html (view: 3d, layout: stress, labels: node+edge), and the page is ready. This is the result. --color-by type colours each node by its rdf:type, so classes, object properties and individuals get their own legend rows; the default colours by input file instead, which is what you want when several files make up one ontology.

What you can do in the page

Drag to rotate, scroll to zoom. The 3D | 2D switch at the top rebuilds the same graph as a flat canvas; filters, search and the open card carry over.
Click a legend row to keep that group, its neighbours and the edges it asserts, and dim the rest. Type in the search box to dim everything whose label does not match.
Click a node for its card: types, definition, synonyms, properties, incoming and outgoing relations (each clickable) and sources.
Nodes are pinned to a stress-minimised layout computed at build time, so the picture is the same every time you open the file. "Free-float physics" releases them into a live simulation.

Options you will reach for

Option	When
`--view 2d`	Start in the 2D view; the switch is there either way.
`--lang de`	Prefer German labels and definitions; untagged literals rank next.
`--type-links`	Draw `rdf:type` as edges instead of listing types on the card.
`--attribute-preds foaf:homepage,rdfs:seeAlso`	Keep predicates off the picture and show them on the card.
`--layout force`	Skip the precomputed layout for very large graphs; above 1000 nodes ttl3d does this on its own.
`--format xml`	Force a parser when the extension misleads, for example Turtle in a `.owl` file.

Several files, one graph

Pass every file of a modular ontology at once: ttl3d core.ttl extensions.ttl -o all.html. The nodes and links merge into one graph, the legend shows which file declared each node, and every relation row on a card names the files asserting it. That is the case ttl3d was written for, and the Solar System demo shows it with two files.

Too big to draw

A knowledge graph of a million triples needs a question first. ttl3d solar-system.ttl solar-system-missions.ttl --focus :Earth --hops 2 keeps Earth and everything within two links of it, 12 of the demo's 41 nodes; --schema on the same files keeps the classes and properties and drops the instances, 11 nodes. Both run before the layout, and ttl3d prints what it kept on stderr.

From a SPARQL endpoint

A store is drawn without an export: ttl3d --endpoint https://query.wikidata.org/sparql --query @wikidata-moons.rq -o moons.html runs the CONSTRUCT in the file, treats the answer as a source with its own legend row, and prints what it fetched. Queries repeat and mix with files; credentials come from TTL3D_SPARQL_USER/TTL3D_SPARQL_PASSWORD or TTL3D_SPARQL_TOKEN, never from the command line. Answers over 100 MB (--max-mb) are refused with a hint to narrow the query. The example query is in the repository under examples/.

From a table

A property graph in CSV needs no conversion: ttl3d missions.csv mission-links.csv --color-by type -o missions.html reads a node table (an id column, with name, type and any other columns) and an edge table (source, target, relation); the other cells of an edge row, a year and a kind of visit in the Space missions demo, show on the card under the relation. Neo4j and Gephi exports work as they are, --columns source=from_id maps any other header, and in Python a pandas DataFrame is a table too. The two example files are in the repository under examples/.

From Python

The same pipeline is a function call, and the options are the command line's:

import rdflib, ttl3d

g = rdflib.Graph().parse("pizza.owl")
ttl3d.write(("pizza", g), "pizza.html", color_by="type")   # a file
ttl3d.show(("pizza", g))                                    # inline, as the last line of a notebook cell

Sources are file paths, rdflib.Graph objects, DataFrames, (name, source) pairs or a {name: source} mapping, in any mix. Open the example notebook in Colab.

Limits

Blank nodes are skipped, so OWL restrictions and RDF lists do not appear as nodes.
No reasoning: only asserted triples are drawn.
The stress layout is quadratic; on graphs far beyond 1000 nodes --layout stress takes minutes.

More demos on the demo index. Source, issues and the full option table: github.com/soheilabadifard/TTL_to_3D.